Natural Stripe

Overview

Natural Stripe is a repo-embedded Stripe catalog engine delivered as a Node.js module and CLI. It gives engineering teams a deterministic, test-first workflow for defining, reviewing, and deploying product catalogs to Stripe straight from source control.

What The App Does

1. Manifest → Engineers describe products, prices, and media in JSON committed to the repo.
2. Validate → pnpm test runs schema and hygiene checks to catch malformed or duplicate objects early.
3. Status → The CLI compares the manifest against the live or stubbed Stripe account.
4. Diff → A reviewable JSON diff is produced showing adds, updates, and removals.
5. Artifact → The diff can be checked in or surfaced in CI for code-review.
6. Apply → A single command applies the diff to Stripe, creating or updating catalogue objects.
7. Sync/Deploy → On success the module can copy mirrored assets into public/images/products/catalog so the storefront is instantly in sync.

A thin Next.js operator UI (my-store/dev/catalog) can be layered on top, but the core project deliberately stays headless.

Product/UX Review

Strengths: • Treats catalog changes like code, enabling PR review and automated tests rather than dashboard clicks. • CLI surfaces clear, colorised output plus machine-readable JSON for CI pipelines (tests/​project-cli.test.mjs ensures stability). • Opt-in live-Stripe lane keeps local and CI runs deterministic; integration tests run only with an explicit test key.

Limitations: • Purely developer-facing; no built-in web dashboard or non-technical workflow. • Stripe’s eventual consistency and rate limits are not abstracted away; long diffs can require multiple apply attempts. • Media mirroring is opinionated (fixed folder path) and may not suit monorepos without extra plumbing.

Technical Architecture

• Node.js ES modules (.mjs) with zero runtime dependencies beyond stripe@14. • CLI entry: src/project-cli.mjs; exports shared helpers consumed by the operator UI. • Core utilities in src/catalog-core.mjs handle normalisation (strings, currency, booleans, tag lists) to guarantee stable hashing. • Workflow modules: – catalog-seed.mjs creates deterministic fixtures for tests. – catalog-hygiene-lib.mjs and catalog-hygiene.mjs run duplicate/invalid checks. – catalog-sync.mjs executes diff/apply against Stripe. • Extensive node:test coverage: unit, smoke, integration (live Stripe), and coverage reporting through c8. • GitHub Actions (.github/workflows/ci.yml) runs npm run check, enforcing the same gates locally and in CI.

AI Techniques And Patterns

No meaningful AI or LLM features appear in the codebase. The only hint is a “rag” code-signal flag, but no retrieval, prompting, or model calls are implemented.

What Was Learned

• Treating catalog data as code drastically reduces “works in dashboard but not in prod” incidents. • Deterministic fixtures and a stubbed Stripe client keep unit tests fast and offline. • Separating validation, diff, and apply phases makes failures explicit and reviewable, but requires developers to understand Stripe object lifecycles. • Live integration tests must stay opt-in; otherwise CI flakiness appears due to network and Stripe rate limits.

Strengths And Tradeoffs

Strengths • End-to-end test suite with clear lanes (unit, smoke, integration) provides high confidence. • Plain JSON manifests make the tool language-agnostic and easy to review. • Minimal runtime surface area—only one external dependency—simplifies upgrades and security posture.

Tradeoffs • Developer-only interface limits adoption by merchandising or marketing teams. • Tight coupling to Stripe means portability to other PSPs would require major refactor. • Fixed directory conventions for mirrored assets introduce constraints on repo structure.