@volter/twin-stripe 2.0.38 → 3.0.0

package/src/engine/treasury.ts

@@ -0,0 +1,47 @@
+// Treasury semantics: financial accounts and the flows that move their money (outbound payments
+// and transfers, inbound transfers), each posting a double entry to the account's ledger (a
+// transaction and its entry). An outbound flow stays processing (cancelable) until the network
+// settles it; an inbound transfer settles at once, as in test mode. The machines in
+// ../manifest.ts say which flows cancel. Lists and retrieves with no required scope are the
+// derived core's.
+import type { Row } from './common.ts';
+
+export const FA = 'treasury.financial_account';
+export const TX = 'treasury.transaction';
+export const ENTRY = 'treasury.transaction_entry';
+export const ENTRY_TYPES = new Set(['credit_reversal', 'debit_reversal', 'inbound_transfer', 'inbound_transfer_return', 'issuing_authorization_hold', 'issuing_authorization_release', 'outbound_payment', 'outbound_transfer', 'received_credit', 'received_debit']);
+
+/** A financial account's features as the served spec's treasury.financial_account_features gives them: a toggle
+ *  (card_issuing, deposit_insurance, intra_stripe_flows) or a feature per network (financial_addresses.aba,
+ *  inbound_transfers.ach, outbound_payments.ach and .us_domestic_wire, outbound_transfers likewise), each
+ *  { requested, status, status_details }. What a request asks for is laid over what the account had. Where the
+ *  documentation stops and the twin decides: a requested feature is active at once (test mode), and one never requested
+ *  is left out (each is optional in the served spec). Answers the features and the active features' paths. */
+export const NETWORKS: Record<string, string[]> = { financial_addresses: ['aba'], inbound_transfers: ['ach'], outbound_payments: ['ach', 'us_domestic_wire'], outbound_transfers: ['ach', 'us_domestic_wire'] };
+export const TOGGLES = ['card_issuing', 'deposit_insurance', 'intra_stripe_flows'];
+export function featuresOf(requested: Row, had: Row = {}): { features: Row; active: string[] } {
+  const on = (v: unknown): boolean => v === true || v === 'true';
+  const setting = (asked: boolean) => ({ requested: asked, status: asked ? 'active' : 'restricted', status_details: [] });
+  const features: Row = { ...had };
+  for (const t of TOGGLES) {
+    const r = requested[t] as Row | undefined;
+    if (r && typeof r === 'object' && r.requested !== undefined) features[t] = setting(on(r.requested));
+  }
+  for (const [f, nets] of Object.entries(NETWORKS)) {
+    const r = requested[f] as Row | undefined;
+    if (!r || typeof r !== 'object') continue;
+    const current = (features[f] as Row | undefined) ?? {};
+    const next: Row = { ...current };
+    for (const n of nets) {
+      const nr = r[n] as Row | undefined;
+      if (nr && typeof nr === 'object' && nr.requested !== undefined) next[n] = setting(on(nr.requested));
+    }
+    features[f] = next;
+  }
+  const active: string[] = [];
+  for (const t of TOGGLES) if ((features[t] as Row | undefined)?.status === 'active') active.push(t);
+  for (const [f, nets] of Object.entries(NETWORKS)) for (const n of nets) if (((features[f] as Row | undefined)?.[n] as Row | undefined)?.status === 'active') active.push(`${f}.${n}`);
+  return { features, active };
+}
+
+export const noTransitions = { canceled_at: null, failed_at: null, posted_at: null, returned_at: null };

package/src/{stripe-version.ts → engine/version.ts}

@@ -8,7 +8,7 @@
 // Where the evidence stops: the changes below are the ones between the kept shape and the vendored spec that
 // the pack's journeys reach, each from Stripe's changelog for basil (docs.stripe.com/changelog/basil); a version
 // pinned between basil and the spec's is rendered in the spec's shape, not its own.
-import surface from './generated/surface.gen.json' with { type: 'json' };
+import surface from '../generated/surface.gen.json' with { type: 'json' };
 
 type Row = Record<string, unknown>;
 
@@ -65,7 +65,7 @@ const BASIL_CHANGES: Record<string, (o: Row, parent?: Row) => Row> = {
     const parent = o.parent !== undefined ? o.parent : subscription ? { type: 'subscription_details', quote_details: null, subscription_details: { metadata: {}, subscription } } : null;
     // "confirmation_secret … Currently, this contains the client_secret of the PaymentIntent that Stripe creates during
     // invoice finalization" (docs.stripe.com/api/invoices/object; includable, answered only when expanded: INCLUDABLE);
-    // the intent's client_secret is the one stripe-twin.ts mintClientSecret gives it
+    // the intent's client_secret is the one ./stripe.ts mintClientSecret gives it
     const intent = typeof o.payment_intent === 'string' && o.payment_intent ? o.payment_intent : null;
     const confirmation_secret = intent ? { type: 'payment_intent', client_secret: `${intent}_secret_twin` } : null;
     return { ...omit(o, ['payment_intent', 'charge', 'paid', 'paid_out_of_band', 'subscription']), parent, confirmation_secret };
@@ -272,7 +272,8 @@ export function render(value: unknown, pinned?: string | null, expand: string[]
     if (!kind || o.deleted === true) return o;
     // metadata holds strings ("key-value pairs", each value up to 500 characters, docs.stripe.com/metadata); the form
     // reader coerces a numeric-looking value to a number, which the answer gives back as the string it was sent as
-    if (o.metadata && typeof o.metadata === 'object' && !Array.isArray(o.metadata)) o.metadata = Object.fromEntries(Object.entries(o.metadata as Row).map(([k, v]) => [k, typeof v === 'number' || typeof v === 'boolean' ? String(v) : v]));
+    // reads the same, and a key posted "" to remove it is not there (../semantics/shared.ts withMetadata)
+    if (o.metadata && typeof o.metadata === 'object' && !Array.isArray(o.metadata)) o.metadata = Object.fromEntries(Object.entries(o.metadata as Row).filter(([, v]) => v !== '').map(([k, v]) => [k, typeof v === 'number' || typeof v === 'boolean' ? String(v) : v]));
     const kept = KEPT[kind] ? omit(o, KEPT[kind]!) : o;
     // an includable field a version's change adds (an invoice's confirmation_secret) is hidden as its stored ones are
     return omit(withNulls(BASIL_CHANGES[kind] ? BASIL_CHANGES[kind]!(kept) : kept, kind), hidden);

package/src/engine/webhook-endpoints.ts

@@ -0,0 +1,14 @@
+// Webhook endpoint semantics: registering a URL and the events it subscribes to. Delivery reads
+// the endpoints from the tree, signing each POST with the endpoint's own secret; a disabled one
+// (the machine in ../manifest.ts) receives nothing. Endpoint list, retrieve and delete are the derived core's.
+//
+// The Events API lists and retrieves the stored events of the account a request acts for: an event of a connected
+// account carries it ("Each event for a connected account contains a top-level `account` property that identifies the
+// connected account. Because the connected account owns the object that triggered the event, you must make API
+// requests for that object as the connected account", docs.stripe.com/connect/webhooks; the event's `account`: "The
+// connected account that originates the event", spec/openapi.json.gz), so a request with the Stripe-Account header
+// sees that account's events and one without it the platform's, those with no `account`. Where the documentation
+// stops and the twin decides: a platform request does not see its connected accounts' events.
+
+export const WE = 'webhook_endpoint';
+

package/src/engine/webhooks.ts

@@ -0,0 +1,72 @@
+// Stripe's events as its handlers and its declared `events` need them (the kernel renders, stores, signs and delivers
+// every event a write sends: ../manifest.ts `events`, ../semantics/shared.ts STRIPE_EVENTS): which write sends which
+// event type, Stripe's own event types (the spec's list, ../generated/events.gen.json), and the one message Stripe decides
+// by its receiver's answer, the real-time authorization request.
+import { hmac } from '@volter/world-core';
+
+import vendorEvents from '../generated/events.gen.json' with { type: 'json' };
+
+/** Every event type Stripe's spec enumerates: a write whose operation is one sends it, and `<resource>.create`,
+ *  `.update` and `.delete` send `<resource>.created`, `.updated` and `.deleted` when Stripe has that type. */
+export const STRIPE_EVENT_TYPES: ReadonlyArray<string> = (vendorEvents as { types: string[] }).types;
+
+/** The writes whose event is named otherwise than by their resource (the rest are STRIPE_EVENT_TYPES'). A refund sends
+ *  `refund.created` for the Refund; the charge's own write is recorded as `charge.refunded`, the charge with its new
+ *  totals. `issuing_authorization.request` is no write's: it is asked of the endpoint (askForAuthorization). */
+export const NAMED_EVENTS: Record<string, string> = {
+  'payment_intent.confirm': 'payment_intent.succeeded',
+  'payment_method.attach': 'payment_method.attached',
+  'payment_method.detach': 'payment_method.detached',
+  'setup_intent.confirm': 'setup_intent.succeeded',
+  'subscription.create': 'customer.subscription.created',
+  'subscription.update': 'customer.subscription.updated',
+  'subscription.cancel': 'customer.subscription.deleted',
+  'invoice.finalize': 'invoice.finalized',
+  'invoice.pay': 'invoice.paid',
+  'invoice.void': 'invoice.voided',
+  'dispute.create': 'charge.dispute.created',
+};
+
+/** Whether an endpoint's `enabled_events` takes a type: `*` takes all, `<family>.*` the family, else the type itself. */
+export function stripeEventMatches(enabledEvents: unknown, type: string): boolean {
+  if (!Array.isArray(enabledEvents)) return false;
+  return enabledEvents.some((p) => {
+    const s = String(p);
+    return s === '*' || (s.endsWith('.*') && type.startsWith(s.slice(0, -1))) || s === type;
+  });
+}
+
+/** A `Stripe-Signature` header: HMAC-SHA256 over `${timestamp}.${payload}` keyed by the endpoint's secret, as
+ *  `t=<unix>,v1=<hex>` (docs.stripe.com/webhooks#verify-manually). */
+export const stripeSignature = (payload: string, secret: string, timestamp: number): string => `t=${timestamp},v1=${hmac(secret, `${timestamp}.${payload}`)}`;
+
+// ── Real-time authorization (issuing_authorization.request) ──────────────────────────────────────
+// Stripe delivers issuing_authorization.request to the one enrolled endpoint while the card network holds the
+// authorization open, and the endpoint must answer within Stripe's 2-second window ("This request should be made within
+// the timeout window of the real-time authorization flow", stripe@22.3.0 Issuing/Authorizations.d.ts; the current method
+// is to "respond directly to the webhook request to approve an authorization"). The answer's body carries the decision:
+// a JSON object with a boolean `approved` (and, for an amount-controllable request, an optional integer `amount`).
+// Outcomes map onto request_history.reason (stripe@22.3.0 RequestHistory.Reason): webhook_approved / webhook_declined,
+// the endpoint answered in time; webhook_timeout, no answer inside the window (an unreachable endpoint too);
+// webhook_error, "the direct webhook response is invalid (for example, parsing errors or missing parameters)": a
+// non-2xx status, a body that is not JSON, or no `approved`.
+export const STRIPE_REALTIME_AUTH_TIMEOUT_MS = 2_000;
+
+export type StripeAuthRequestOutcome =
+  | { kind: 'approved'; amount?: number }
+  | { kind: 'declined' }
+  | { kind: 'timeout'; message: string }
+  | { kind: 'error'; message: string };
+
+/** The endpoint's answer read as the decision: `approved` (and an optional `amount`), or an error for an answer Stripe
+ *  cannot read. */
+export function readDecision(res: { status: number; body: string }): StripeAuthRequestOutcome {
+  if (res.status < 200 || res.status >= 300) return { kind: 'error', message: `Webhook endpoint responded with HTTP status ${res.status}.` };
+  let parsed: unknown;
+  try { parsed = JSON.parse(res.body); } catch { return { kind: 'error', message: 'Webhook response body was not valid JSON.' }; }
+  const approved = (parsed as { approved?: unknown } | null)?.approved;
+  if (typeof approved !== 'boolean') return { kind: 'error', message: 'Webhook response is missing the required `approved` parameter.' };
+  if (!approved) return { kind: 'declined' };
+  const amount = (parsed as { amount?: unknown }).amount;
+  return { kind: 'approved', ...(typeof amount === 'number' && Number.isInteger(amount) && amount > 0 ? { amount } : {}) };
+}

package/src/fetch.ts

@@ -0,0 +1,27 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,
+// the World's doors, the vendor's screens and the API from the pack's parts (architecture, "The pack contract").
+import { createPackFetch, type DerivedFetch, type DerivedSurface, type PackFetchOptions } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { around } from './semantics/around.ts';
+import { clock } from './semantics/clock.ts';
+import * as doors from './semantics/doors.ts';
+import { stripeSemantics } from './semantics/index.ts';
+import { screen as screen_billing_portal } from './screens/billing-portal.tsx';
+import { screen as screen_checkout } from './screens/checkout.tsx';
+import { screen as screen_connect_oauth } from './screens/connect-oauth.tsx';
+import { screen as screen_connect_onboarding } from './screens/connect-onboarding.tsx';
+import { screen as screen_dashboard } from './screens/dashboard.tsx';
+import { screen as screen_stripe_js } from './screens/stripe-js.ts';
+
+export function createStripeFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createPackFetch({
+    manifest,
+    surface: surface as DerivedSurface,
+    handlers: stripeSemantics,
+    doors,
+    around,
+    clock,
+    screens: { "billing-portal": screen_billing_portal, "checkout": screen_checkout, "connect-oauth": screen_connect_oauth, "connect-onboarding": screen_connect_onboarding, "dashboard": screen_dashboard, "stripe-js": screen_stripe_js },
+  }, options);
+}