@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/stripe-conformance.d.ts

@@ -0,0 +1,41 @@
+import { specConformance } from '@volter/world-tooling';
+type JsonSchema = specConformance.JsonSchema;
+type KnownDeviation = specConformance.KnownDeviation;
+type SpecViolation = specConformance.SpecViolation;
+export type StripeSchemas = Record<string, JsonSchema>;
+export type StripeViolation = SpecViolation & {
+    object: string;
+    id: string;
+};
+export type StripeConformanceReport = {
+    ok: boolean;
+    resourcesChecked: number;
+    fieldsChecked: number;
+    violations: StripeViolation[];
+    knownIgnored: number;
+};
+/** Load the vendored per-object Stripe JSON Schemas (type+required+enum from OpenAPI). */
+export declare function loadStripeSchemas(): Promise<StripeSchemas>;
+/** Load the declared scope (Stripe fields the twin does not model, + reasons). */
+export declare function loadStripeKnownDeviations(): Promise<KnownDeviation[]>;
+/**
+ * Validate every Stripe resource the twin serves (in `root`) against the published
+ * schema. A wrong type, an undeclared missing-required field, an enum violation, or
+ * a fabricated field fails the report.
+ */
+export declare function checkStripeConformance(schemas: StripeSchemas, opts?: {
+    root?: string;
+    known?: KnownDeviation[];
+}): StripeConformanceReport;
+export type StripeCoverageReport = specConformance.SpecCoverageReport & {
+    object: string;
+};
+/**
+ * Per-object coverage: of the fields each Stripe object declares, which does the
+ * twin emit? Computed over one representative resource of each type present in
+ * `root` — the "what we emulate / what we're missing" report, from the spec.
+ */
+export declare function stripeCoverage(schemas: StripeSchemas, opts?: {
+    root?: string;
+}): StripeCoverageReport[];
+export {};

package/dist/src/stripe-conformance.js

@@ -0,0 +1,96 @@
+// Stripe twin conformance (scorecard R2) — spec-conformance against Stripe's
+// PUBLISHED OpenAPI, offline (no API key). Stripe is the twin we CANNOT dual-run
+// against a live sandbox, so the published spec carries the most weight here.
+//
+// For every resource the twin emits, validate its REST body against the vendored
+// per-object schema (test-fixtures/stripe-schemas.json) via the shared
+// specConformance harness: declared TYPES, REQUIRED fields (omission), and ENUMS.
+// Polymorphic Stripe fields (anyOf/$ref — `customer` may be id|object|null) are
+// left untyped in the projection and so are not type-checked, avoiding false
+// positives. Fields the twin deliberately does not model are DECLARED in
+// stripe-known-deviations.json with reasons; an undeclared missing-required field,
+// a wrong type, an enum violation, or a fabricated field all fail CI.
+import { readFile } from 'node:fs/promises';
+import { twinResources } from '@volter/world-core';
+import { specConformance } from '@volter/world-tooling';
+import { OBJECT_NAME } from "./stripe-twin.js";
+// twin resource type -> Stripe OpenAPI object name (the resources the twin serves)
+const TYPE_TO_OBJECT = {
+    charge: 'charge', customer: 'customer', payment_intent: 'payment_intent', refund: 'refund',
+    subscription: 'subscription', setup_intent: 'setup_intent', payment_method: 'payment_method',
+    price: 'price', product: 'product', invoice: 'invoice', invoiceitem: 'invoiceitem',
+    dispute: 'dispute', payout: 'payout', balance_transaction: 'balance_transaction', event: 'event',
+    checkout_session: 'checkout.session', billing_portal_session: 'billing_portal.session',
+    billing_portal_configuration: 'billing_portal.configuration',
+    account: 'account', transfer: 'transfer',
+    tax_rate: 'tax_rate', tax_calculation: 'tax.calculation', tax_registration: 'tax.registration',
+    credit_note: 'credit_note', tax_id: 'tax_id', customer_balance_transaction: 'customer_balance_transaction',
+    issuing_authorization: 'issuing.authorization', issuing_card: 'issuing.card',
+    issuing_cardholder: 'issuing.cardholder', issuing_transaction: 'issuing.transaction',
+};
+const isTwinExtra = (k) => k.startsWith('_');
+const fixturePath = (name) => new URL(`../test-fixtures/${name}`, import.meta.url).pathname;
+// The emitted REST body == the twin's view(): strip internal fields, add object + id.
+// Mirrors stripe-twin.ts view(): a vendor `type` field collides with the kernel
+// discriminator, so it is stored under `_stripe_type` and restored to `type` on emit.
+function emitted(r) {
+    const { type, updatedAt, _stripe_type, ...rest } = r;
+    const out = { object: OBJECT_NAME[type] ?? type, ...rest, id: r.id };
+    if (_stripe_type !== undefined)
+        out.type = _stripe_type;
+    return out;
+}
+/** Load the vendored per-object Stripe JSON Schemas (type+required+enum from OpenAPI). */
+export async function loadStripeSchemas() {
+    return JSON.parse(await readFile(fixturePath('stripe-schemas.json'), 'utf8'));
+}
+/** Load the declared scope (Stripe fields the twin does not model, + reasons). */
+export async function loadStripeKnownDeviations() {
+    const doc = JSON.parse(await readFile(fixturePath('stripe-known-deviations.json'), 'utf8'));
+    return doc.deviations;
+}
+/**
+ * Validate every Stripe resource the twin serves (in `root`) against the published
+ * schema. A wrong type, an undeclared missing-required field, an enum violation, or
+ * a fabricated field fails the report.
+ */
+export function checkStripeConformance(schemas, opts = {}) {
+    const resources = twinResources('stripe', opts.root);
+    const violations = [];
+    let fieldsChecked = 0;
+    let knownIgnored = 0;
+    for (const r of resources) {
+        const objectName = TYPE_TO_OBJECT[r.type];
+        if (!objectName)
+            continue;
+        const schema = schemas[objectName];
+        if (!schema)
+            continue;
+        const rep = specConformance.checkSpecConformance(emitted(r), schema, { exemptKey: isTwinExtra, known: opts.known ?? [] });
+        fieldsChecked += rep.fieldsChecked;
+        knownIgnored += rep.knownIgnored;
+        for (const v of rep.violations)
+            violations.push({ ...v, object: objectName, id: r.id });
+    }
+    return { ok: violations.length === 0, resourcesChecked: resources.length, fieldsChecked, violations, knownIgnored };
+}
+/**
+ * Per-object coverage: of the fields each Stripe object declares, which does the
+ * twin emit? Computed over one representative resource of each type present in
+ * `root` — the "what we emulate / what we're missing" report, from the spec.
+ */
+export function stripeCoverage(schemas, opts = {}) {
+    const byType = new Map();
+    for (const r of twinResources('stripe', opts.root))
+        if (!byType.has(r.type))
+            byType.set(r.type, r);
+    const out = [];
+    for (const [type, r] of byType) {
+        const objectName = TYPE_TO_OBJECT[type];
+        const schema = objectName ? schemas[objectName] : undefined;
+        if (!objectName || !schema)
+            continue;
+        out.push({ object: objectName, ...specConformance.specCoverage(schema, emitted(r), { exemptKey: isTwinExtra }) });
+    }
+    return out;
+}

package/dist/src/stripe-connector.d.ts

@@ -0,0 +1,161 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { StripeBudget, type StripeBudgetOptions } from './stripe-budget.js';
+export declare const INTERNAL_SUBJECT_TYPES: Set<string>;
+/**
+ * The injected real-Stripe boundary. `request` issues ONE Stripe REST call:
+ *   method  — 'GET' | 'POST' | 'DELETE'
+ *   path    — e.g. '/v1/customers' or '/v1/customers/cus_123'
+ *   params  — form params (POST) or query filters (GET); omitted for plain GETs
+ * It returns the parsed JSON body (a Stripe object or `{ object: 'list', data }`) or
+ * a Stripe `{ error }` envelope. A real client (the `stripe` SDK or a raw fetch
+ * wrapper) is structurally assignable; tests pass a fake.
+ */
+export type StripeExecute = (method: 'GET' | 'POST' | 'DELETE', path: string, params?: Record<string, unknown>) => Promise<{
+    object?: string;
+    data?: any;
+    error?: {
+        message?: string;
+        type?: string;
+    };
+    [k: string]: unknown;
+}>;
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveStripeOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: StripeBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: StripeBudgetOptions;
+};
+/**
+ * A live executor against the real Stripe REST API (secret key = the user's own).
+ * Form-encodes POST params; sends GET filters as a query string. Never imported by
+ * the pack's own code path — only constructed by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.stripe.com` request, and therefore the one
+ * place the rate budget has to be enforced — and Stripe is the pack where a runaway loop does not
+ * merely annoy a vendor, it MOVES MONEY. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `StripeBudgetError` instead of returning when the
+ * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `Retry-After` /
+ * 429 signal becomes a persisted cooldown that makes every later call fail fast WITHOUT touching
+ * Stripe. There is deliberately no OPTION to disable the guard, and no
+ * value a caller can pass for `budget` that yields an unguarded client. That is NOT immunity from
+ * a caller who WANTS one: a fresh `budgetOptions.path` per construction, or an injected clock,
+ * restores the allowance, because the seam tests need cannot be denied to a determined caller in
+ * the same process. The kernel header states that limit and this does not upgrade it. See `stripe-budget.ts` for why,
+ * and for the limits of the guarantee.
+ */
+export declare function liveStripeExecute(apiKey: string, base?: string, opts?: LiveStripeOptions): StripeExecute;
+/**
+ * Map a real-Stripe customer (snake_case) → a twin sync resource. Only the stable
+ * scalar fields the twin tracks are carried; absent fields become null so the diff
+ * is faithful (an unset email reads as null, not missing).
+ */
+export declare function mapCustomer(c: Record<string, unknown>): SyncResource;
+/**
+ * Map a real-Stripe subscription (snake_case) → a twin sync resource. The single
+ * subscribed price id is lifted out of items.data[0].price.id (Stripe's nested list
+ * shape) so the twin tracks a flat, diffable `price`.
+ */
+export declare function mapSubscription(s: Record<string, unknown>): SyncResource;
+/**
+ * A GENERIC scalar mapper for the collections that don't need special id-lifting like
+ * subscriptions do. We carry the stable, diffable scalar fields a twin tracks (anything
+ * that is a string/number/boolean), dropping nested objects/arrays (which the twin either
+ * synthesizes or doesn't diff on). This keeps every collection's pull faithful without a
+ * bespoke mapper per type — vendor-SPECIFIC lifting (subscription.price) stays explicit.
+ */
+export declare function mapScalarResource(type: string, r: Record<string, unknown>): SyncResource;
+/** Pull real Stripe customers via the executor and map them to twin sync resources. */
+export declare function pullStripeCustomers(execute: StripeExecute, opts?: {
+    limit?: number;
+}): Promise<SyncResource[]>;
+/** Pull real Stripe subscriptions via the executor and map them to twin sync resources. */
+export declare function pullStripeSubscriptions(execute: StripeExecute, opts?: {
+    limit?: number;
+}): Promise<SyncResource[]>;
+export declare function syncStripeFromReal(execute: StripeExecute, opts: {
+    root?: string;
+    occurredAt: string;
+    limit?: number;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real
+ * Stripe REST surface for EVERY write operation the twin records. The action carries
+ * the twin operation (`<type>.<verb>`) plus its subject:
+ *   - `<type>.create`              → POST   /v1/<collection>
+ *   - `subscription.cancel`        → DELETE /v1/subscriptions/:id
+ *   - `payout.cancel`              → POST   /v1/payouts/:id/cancel  (sub-action)
+ *   - `payment_intent.confirm`     → POST   /v1/payment_intents/:id/confirm
+ *   - `setup_intent.confirm`       → POST   /v1/setup_intents/:id/confirm
+ *   - `payment_method.detach`      → POST   /v1/payment_methods/:id/detach
+ *   - `invoice.finalize|pay|void`  → POST   /v1/invoices/:id/<verb>
+ *   - `dispute.close`              → POST   /v1/disputes/:id/close
+ *   - `<type>.update` (or any other verb) → POST /v1/<collection>/:id
+ *
+ * Unknown/unsupported operations must FAIL LOUDLY at push time (see pushStripeAction),
+ * never be silently dropped — so this resolver always returns a concrete request and
+ * the caller validates the operation is one the twin is allowed to push.
+ */
+export declare function stripeRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>): {
+    method: 'POST' | 'DELETE';
+    path: string;
+};
+/** Throw if `op` is not a write operation this connector can faithfully push. */
+/** Whether this operation is one the connector can faithfully send to Stripe. */
+export declare function isPushable(op: string): boolean;
+/**
+ * Push ONE pending action to REAL Stripe via the injected executor. Returns the real
+ * external id (the Stripe object id from the response — for a create that is a freshly
+ * minted id; for an update it echoes the subject). WRITES TO THE REAL ACCOUNT.
+ */
+export declare function pushStripeAction(execute: StripeExecute, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>): Promise<{
+    externalId: string;
+}>;
+/** The pack's executor over the kernel's: the same Stripe REST call, carried by the head. Stripe's API is
+ *  form-encoded, which is what `stripeExecute` already speaks — this only carries it. */
+export declare function stripeExecuteOver(execute: RemoteExecute): StripeExecute;
+/** The refresh adapter: pull every modeled collection and the webhook endpoints through the executor. */
+export declare function syncStripeFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** The perform adapter: one entry crosses to Stripe, or settles with the reason it never could. The twin's
+ *  own subject types — the recorded `event` envelopes the write path persists for the Events API, and the
+ *  idempotency bookkeeping — are local state and must never be sent. */
+export declare function performStripeAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;
+/**
+ * Pull EVERY tracked collection from real Stripe (not just customers + subscriptions) in
+ * one pass and return the combined sync resources. This is the read half of a full sync.
+ */
+export declare function pullStripeAll(execute: StripeExecute, opts?: {
+    limit?: number;
+}): Promise<SyncResource[]>;
+/** Pull the account's registered webhook endpoints (so the twin mirrors them too). */
+export declare function pullStripeWebhookEndpoints(execute: StripeExecute, opts?: {
+    limit?: number;
+}): Promise<SyncResource[]>;
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to
+ * real Stripe and confirm it, then (2) PULL all collections + webhook endpoints back and
+ * fold them into the event log. Pushing first means the pull observes the twin's own writes
+ * as confirmed external state (no double-count). Returns per-direction counts. Same code
+ * path offline (fake executor) and live (real key) — D4-faithful.
+ */
+export declare function fullSyncStripe(execute: StripeExecute, opts: {
+    root?: string;
+    occurredAt: string;
+    limit?: number;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+    collections: number;
+}>;