@volter/twin-stripe 0.1.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@volter/twin-stripe",
+  "version": "0.1.0",
+  "description": "Local Stripe twin \u2014 a faithful, stateful local Stripe API your real `stripe` SDK talks to unmodified. Mirror, simulate, and fork. Built on @volter/twin.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack",
+    "stripe",
+    "payments"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "client",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!test-fixtures/*.SOURCE.md",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/stripe"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/stripe#readme",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "world-stripe": "src/cli.ts"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/twin": "0.1.0"
+  },
+  "devDependencies": {
+    "@volter/twin": "0.1.0",
+    "@volter/twin-tooling": "0.1.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "stripe": "^22.2.1",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env bun
+// world-stripe CLI: serve the Stripe API twin, the mirror UI, or run conformance.
+import { hasFlag, optionValue } from '@volter/twin/args';
+import { createStripeTwinServer } from './stripe-server.ts';
+import { createStripeMirrorServer } from './stripe-mirror-ui.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve') {
+  const s = createStripeTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`stripe twin (spec-correct API)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await new Promise(() => {});
+} else if (cmd === 'mirror') {
+  const s = createStripeMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`stripe mirror UI (dashboard) at http://127.0.0.1:${s.port}\n`);
+  await new Promise(() => {});
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/twin-tooling
+  const { checkStripeConformance, loadStripeKnownDeviations, loadStripeSchemas, stripeCoverage } = await import('./stripe-conformance.ts');
+  const [schemas, known] = await Promise.all([loadStripeSchemas(), loadStripeKnownDeviations()]);
+  const report = checkStripeConformance(schemas, { ...(root ? { root } : {}), known });
+  process.stdout.write(`${JSON.stringify({ ...report, coverage: stripeCoverage(schemas, { ...(root ? { root } : {}) }) }, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-stripe serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// @volter/twin-stripe — the Stripe twin (one vendor, one package), built on the
+// shared @volter/twin kernel. REST transport, spec-correct shapes, event/webhook
+// emission, and a React dashboard UI mirror. (Conformance tooling lives in
+// @volter/twin-tooling, a dev dependency — not shipped in the runtime API.)
+export { handleStripeTwinRequest } from './stripe-twin.ts';
+export type { StripeRequest, StripeResponse } from './stripe-twin.ts';
+export { createStripeTwinServer } from './stripe-server.ts';
+export { parseStripeForm } from './stripe-form.ts';
+export {
+  clearStripeWebhooks,
+  computeStripeSignature,
+  constructEvent,
+  emitStripeEvent,
+  eventTypeFor,
+  generateTestHeaderString,
+  listStripeWebhooks,
+  registerStripeWebhook,
+  StripeSignatureVerificationError,
+} from './stripe-events.ts';
+export type { StripeEvent, StripeEventDelivery } from './stripe-events.ts';
+export {
+  fullSyncStripe,
+  liveStripeExecute,
+  mapCustomer,
+  mapScalarResource,
+  mapSubscription,
+  pullStripeAll,
+  pullStripeCustomers,
+  pullStripeSubscriptions,
+  pullStripeWebhookEndpoints,
+  pushPendingStripeActions,
+  pushStripeAction,
+  stripeRequestForAction,
+  syncStripeFromReal,
+} from './stripe-connector.ts';
+export type { StripeExecute } from './stripe-connector.ts';
+export { buildStripeMirrorClient, createStripeMirrorServer, stripeMirrorHtml } from './stripe-mirror-ui.ts';
+
+// Registry descriptor (#1): the pack self-describes so tooling can discover it.
+// A consumer does `registerPack(pack)` after importing this package.
+import type { TwinPack } from '@volter/twin';
+export const pack: TwinPack = {
+  vendor: 'stripe',
+  transport: 'rest',
+  bin: 'world-stripe',
+  resources: ['charge', 'customer', 'payment_intent', 'setup_intent', 'payment_method', 'subscription', 'price', 'product', 'invoice', 'invoiceitem', 'refund'],
+  specSource: 'test-fixtures/stripe-schemas.json (per-object JSON Schemas from Stripe OpenAPI)',
+  description: 'Stripe REST twin — spec-correct shapes, events, dashUI mirror.',
+  // Stripe.js calls the same-origin '/v1/…' and loads from api.stripe.com — the dev proxy
+  // forwards '/v1/' to the twin and strips the absolute host so calls come back same-origin.
+  browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://api.stripe.com' },
+};