@volter/twin-stripe 2.0.38 → 3.0.1

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

@@ -1,43 +0,0 @@
-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;
-    /** fields checked per twin resource type: a type the check skipped (no schema) is absent */
-    fieldsByType: Record<string, 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

@@ -1,105 +0,0 @@
-// 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";
-import { INCLUDABLE_FIELDS, render } from "./stripe-version.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.
-// ...and then rendered in the version a caller that pins none is served (stripe-version.ts render): since 24e757f60
-// the twin KEEPS objects in the 2024-06-20 shape its rules were written against and answers them in the served
-// version's (basil onward moved an invoice's subscription and charge, a charge's source, ...), so the stored row is
-// not what any client receives. The schemas are projected from a post-basil spec, so the answer is what is checked.
-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;
-    // expanded: an includable field (a session's line_items, a charge's refunds) is answered only when a request asks, and
-    // the check reads the answer that carries it so its shape is still checked
-    return render(out, undefined, INCLUDABLE_FIELDS);
-}
-/** 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;
-    const fieldsByType = {};
-    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;
-        fieldsByType[r.type] = (fieldsByType[r.type] ?? 0) + 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, fieldsByType };
-}
-/**
- * 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

@@ -1,161 +0,0 @@
-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;
-}>;