@volter/twin-stripe 0.1.0

package/src/stripe-conformance.ts

@@ -0,0 +1,110 @@
+// 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 { twinResources } from '@volter/twin';
+import { specConformance } from '@volter/twin-tooling';
+import type { TwinResource } from '@volter/twin';
+import { OBJECT_NAME } from './stripe-twin.ts';
+
+type JsonSchema = specConformance.JsonSchema;
+type KnownDeviation = specConformance.KnownDeviation;
+type SpecViolation = specConformance.SpecViolation;
+
+// twin resource type -> Stripe OpenAPI object name (the resources the twin serves)
+const TYPE_TO_OBJECT: Record<string, string> = {
+  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',
+};
+
+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;
+};
+
+const isTwinExtra = (k: string): boolean => k.startsWith('_');
+const fixturePath = (name: string): string => 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: TwinResource): Record<string, unknown> {
+  const { type, updatedAt, _stripe_type, ...rest } = r as TwinResource & { _stripe_type?: unknown };
+  const out: Record<string, unknown> = { 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(): Promise<StripeSchemas> {
+  return JSON.parse(await Bun.file(fixturePath('stripe-schemas.json')).text()) as StripeSchemas;
+}
+
+/** Load the declared scope (Stripe fields the twin does not model, + reasons). */
+export async function loadStripeKnownDeviations(): Promise<KnownDeviation[]> {
+  const doc = JSON.parse(await Bun.file(fixturePath('stripe-known-deviations.json')).text()) as { deviations: KnownDeviation[] };
+  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: StripeSchemas, opts: { root?: string; known?: KnownDeviation[] } = {}): StripeConformanceReport {
+  const resources = twinResources('stripe', opts.root);
+  const violations: StripeViolation[] = [];
+  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 };
+}
+
+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 function stripeCoverage(schemas: StripeSchemas, opts: { root?: string } = {}): StripeCoverageReport[] {
+  const byType = new Map<string, TwinResource>();
+  for (const r of twinResources('stripe', opts.root)) if (!byType.has(r.type)) byType.set(r.type, r);
+  const out: StripeCoverageReport[] = [];
+  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/src/stripe-connector.ts

@@ -0,0 +1,373 @@
+// Stripe CONNECTOR — the live-vendor pull/push path that gives the Stripe twin the
+// full "git for SaaS" lifecycle (the piece every other connector pack already had,
+// and Stripe was missing entirely).
+//
+// PULL  (real → twin):  fetch real Stripe objects, map snake_case → SyncResource[],
+//                       fold into the event log via syncPull (shadow-diff dedup, so a
+//                       re-pull of identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action, call the real Stripe REST API
+//                       and confirmAction on success — which records the confirmed
+//                       fields as an observed event and suppresses the local
+//                       projection (the change is counted exactly once).
+//
+// The vendor I/O is an INJECTED executor (the auth-boundary, hard-problem #6): the
+// kernel and this pack hold NO Stripe key and import NO network client.
+//   - offline/tests pass a fake executor (deterministic, no network),
+//   - live runs pass `liveStripeExecute(apiKey)` (the user's own secret key).
+// Same code path either way, so the connector is fully exercisable offline AND
+// runnable against a real account.
+import { confirmAction, pendingActions, syncPull } from '@volter/twin';
+import type { SyncResource, TwinAction } from '@volter/twin';
+
+const SERVICE = 'stripe';
+
+// Subject types that are twin-internal and are NEVER pushed to real Stripe: the recorded
+// Stripe `event` envelopes (the local Events-API store) and idempotency bookkeeping.
+const INTERNAL_SUBJECT_TYPES = new Set(['event', '_idempotency']);
+
+/**
+ * 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 }>;
+
+/**
+ * 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.
+ */
+export function liveStripeExecute(apiKey: string, base = 'https://api.stripe.com'): StripeExecute {
+  return async (method, path, params) => {
+    const headers: Record<string, string> = { Authorization: `Bearer ${apiKey}` };
+    let url = `${base}${path}`;
+    const form = encodeForm(params ?? {});
+    const init: { method: string; headers: Record<string, string>; body?: string } = { method, headers };
+    if (method === 'GET') {
+      if (form) url += `?${form}`;
+    } else if (form) {
+      headers['Content-Type'] = 'application/x-www-form-urlencoded';
+      init.body = form;
+    }
+    const res = await fetch(url, init);
+    return (await res.json()) as { object?: string; data?: any; error?: { message?: string } };
+  };
+}
+
+// Stripe's nested form encoding (a[b]=c). Only the shapes the connector pushes
+// (flat scalars + one level of object nesting, e.g. metadata) are handled.
+function encodeForm(params: Record<string, unknown>, prefix = ''): string {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    const name = prefix ? `${prefix}[${key}]` : key;
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      const nested = encodeForm(value as Record<string, unknown>, name);
+      if (nested) parts.push(nested);
+    } else {
+      parts.push(`${encodeURIComponent(name)}=${encodeURIComponent(value === null ? '' : String(value))}`);
+    }
+  }
+  return parts.join('&');
+}
+
+function listOf(res: { data?: unknown }): any[] {
+  return Array.isArray(res.data) ? res.data : [];
+}
+function throwIfError(res: { error?: { message?: string } }, ctx: string): void {
+  if (res.error) throw new Error(`stripe ${ctx} failed: ${res.error.message ?? 'unknown error'}`);
+}
+
+// ── PULL ────────────────────────────────────────────────────────────────────
+
+/**
+ * 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 function mapCustomer(c: Record<string, unknown>): SyncResource {
+  return {
+    type: 'customer',
+    id: String(c.id),
+    fields: {
+      email: (c.email as string) ?? null,
+      name: (c.name as string) ?? null,
+      description: (c.description as string) ?? null,
+      phone: (c.phone as string) ?? null,
+      currency: (c.currency as string) ?? null,
+      delinquent: typeof c.delinquent === 'boolean' ? c.delinquent : null,
+      created: typeof c.created === 'number' ? c.created : null,
+      livemode: typeof c.livemode === 'boolean' ? c.livemode : null,
+    },
+  };
+}
+
+/**
+ * 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 function mapSubscription(s: Record<string, unknown>): SyncResource {
+  const items = s.items as { data?: Array<{ price?: { id?: unknown } }> } | undefined;
+  const firstPrice = items?.data?.[0]?.price?.id;
+  return {
+    type: 'subscription',
+    id: String(s.id),
+    fields: {
+      customer: (s.customer as string) ?? null,
+      status: (s.status as string) ?? null,
+      currency: (s.currency as string) ?? null,
+      cancel_at_period_end: typeof s.cancel_at_period_end === 'boolean' ? s.cancel_at_period_end : null,
+      price: typeof firstPrice === 'string' ? firstPrice : null,
+      created: typeof s.created === 'number' ? s.created : null,
+      livemode: typeof s.livemode === 'boolean' ? s.livemode : null,
+    },
+  };
+}
+
+/**
+ * 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 function mapScalarResource(type: string, r: Record<string, unknown>): SyncResource {
+  const fields: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(r)) {
+    if (k === 'id' || k === 'object') continue;
+    if (v === null || typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') fields[k] = v ?? null;
+  }
+  return { type, id: String(r.id), fields };
+}
+
+// The full set of collections a full sync pulls, mapped to the REST list path + the twin
+// resource type. Customers + subscriptions keep their bespoke mappers (id-lifting); the
+// rest use the generic scalar mapper.
+const PULL_COLLECTIONS: Array<{ path: string; type: string; map?: (r: Record<string, unknown>) => SyncResource; params?: Record<string, unknown> }> = [
+  { path: '/v1/customers', type: 'customer', map: mapCustomer },
+  { path: '/v1/subscriptions', type: 'subscription', map: mapSubscription, params: { status: 'all' } },
+  { path: '/v1/products', type: 'product' },
+  { path: '/v1/prices', type: 'price' },
+  { path: '/v1/charges', type: 'charge' },
+  { path: '/v1/payment_intents', type: 'payment_intent' },
+  { path: '/v1/invoices', type: 'invoice' },
+  { path: '/v1/refunds', type: 'refund' },
+  { path: '/v1/payouts', type: 'payout' },
+  { path: '/v1/disputes', type: 'dispute' },
+  { path: '/v1/coupons', type: 'coupon' },
+];
+
+/** Pull real Stripe customers via the executor and map them to twin sync resources. */
+export async function pullStripeCustomers(execute: StripeExecute, opts: { limit?: number } = {}): Promise<SyncResource[]> {
+  const res = await execute('GET', '/v1/customers', { limit: opts.limit ?? 100 });
+  throwIfError(res, 'pull customers');
+  return listOf(res).map(mapCustomer);
+}
+
+/** Pull real Stripe subscriptions via the executor and map them to twin sync resources. */
+export async function pullStripeSubscriptions(execute: StripeExecute, opts: { limit?: number } = {}): Promise<SyncResource[]> {
+  const res = await execute('GET', '/v1/subscriptions', { status: 'all', limit: opts.limit ?? 100 });
+  throwIfError(res, 'pull subscriptions');
+  return listOf(res).map(mapSubscription);
+}
+
+/**
+ * Pull from real Stripe (customers + subscriptions) and fold into the twin (mirror
+ * seeding). syncPull's shadow-diff makes a re-pull of identical state a no-op.
+ */
+export async function syncStripeFromReal(
+  execute: StripeExecute,
+  opts: { root?: string; occurredAt: string; limit?: number },
+): Promise<{ observed: number; deltasAppended: number }> {
+  const customers = await pullStripeCustomers(execute, { ...(opts.limit ? { limit: opts.limit } : {}) });
+  const subscriptions = await pullStripeSubscriptions(execute, { ...(opts.limit ? { limit: opts.limit } : {}) });
+  const resources = [...customers, ...subscriptions];
+  const result = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.deltasAppended };
+}
+
+// ── PUSH ────────────────────────────────────────────────────────────────────
+
+// Stripe resource type → REST collection segment, for building create paths.
+// (Pluralization isn't uniform — e.g. `dispute`→`disputes` is fine but several types
+// the twin writes need an explicit mapping so the path matches real Stripe exactly.)
+const COLLECTION: Record<string, string> = {
+  customer: 'customers',
+  subscription: 'subscriptions',
+  charge: 'charges',
+  product: 'products',
+  price: 'prices',
+  invoice: 'invoices',
+  payment_intent: 'payment_intents',
+  setup_intent: 'setup_intents',
+  payment_method: 'payment_methods',
+  refund: 'refunds',
+  dispute: 'disputes',
+  payout: 'payouts',
+};
+
+// Verb-style twin operations that map to a real-Stripe SUB-ACTION endpoint
+// (POST /v1/<collection>/:id/<verb>) rather than a plain resource update. The twin
+// records these verbs verbatim as the operation's suffix (see stripe-twin.ts:
+// payment_intent.confirm, setup_intent.confirm, payment_method.detach,
+// invoice.finalize|pay|void, dispute.close, payout.cancel). The verb here IS the
+// real Stripe path segment, so this stays faithful as the twin grows.
+const SUBACTION_VERBS = new Set(['confirm', 'detach', 'finalize', 'pay', 'void', 'close']);
+
+// `cancel` is resource-specific in real Stripe: a subscription is canceled with
+// DELETE /v1/subscriptions/:id, but a payout is canceled with POST
+// /v1/payouts/:id/cancel. Anything else canceled via DELETE on the resource is a safe
+// default (no other type the twin emits a `.cancel` for uses a sub-action path).
+const CANCEL_VIA_SUBACTION = new Set(['payout']);
+
+/**
+ * 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 function stripeRequestForAction(action: Pick<TwinAction, 'operation' | 'subject'>): { method: 'POST' | 'DELETE'; path: string } {
+  const op = action.operation ?? `${action.subject.type}.update`;
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  const collection = COLLECTION[action.subject.type] ?? `${action.subject.type}s`;
+  const base = `/v1/${collection}`;
+  if (verb === 'create') return { method: 'POST', path: base };
+  if (verb === 'cancel') {
+    return CANCEL_VIA_SUBACTION.has(action.subject.type)
+      ? { method: 'POST', path: `${base}/${action.subject.id}/cancel` }
+      : { method: 'DELETE', path: `${base}/${action.subject.id}` };
+  }
+  // confirm / detach / finalize / pay / void / close → /:id/<verb>
+  if (SUBACTION_VERBS.has(verb)) return { method: 'POST', path: `${base}/${action.subject.id}/${verb}` };
+  // update (and any other plain mutation) → POST the resource itself.
+  return { method: 'POST', path: `${base}/${action.subject.id}` };
+}
+
+// The twin operations this connector knows how to push to real Stripe. Anything not
+// here (a new/unmodeled write op) must FAIL LOUDLY rather than be silently dropped —
+// pushing an unrecognized op risks hitting the wrong real endpoint or no-op'ing a
+// real change. New twin write ops must be deliberately added here.
+const PUSHABLE_VERBS = new Set(['create', 'update', 'cancel', ...SUBACTION_VERBS]);
+
+/** Throw if `op` is not a write operation this connector can faithfully push. */
+function assertPushable(op: string): void {
+  const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+  if (!PUSHABLE_VERBS.has(verb)) {
+    throw new Error(`stripe push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  }
+}
+
+/**
+ * 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 async function pushStripeAction(
+  execute: StripeExecute,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+): Promise<{ externalId: string }> {
+  assertPushable(action.operation ?? `${action.subject.type}.update`);
+  const { method, path } = stripeRequestForAction(action);
+  const res = await execute(method, path, method === 'DELETE' ? undefined : (action.fields ?? {}));
+  throwIfError(res, `push ${action.subject.type}`);
+  const id = (res as { id?: unknown }).id;
+  return { externalId: typeof id === 'string' && id ? id : action.subject.id };
+}
+
+/**
+ * Push the twin's PENDING local actions to real Stripe and CONFIRM each (R18): for
+ * every pending `set` action, call the real API; on success, `confirmAction` records
+ * the confirmed fields as an observed event and maps action → event (suppressing the
+ * local projection). Idempotency: a confirmed action is no longer pending, so a
+ * re-push enacts NOTHING — the executor is never called twice for the same change.
+ * `execute` is injected (fake offline / live key).
+ */
+export async function pushPendingStripeActions(
+  execute: StripeExecute,
+  opts: { root?: string; occurredAt: string },
+): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  for (const action of pendingActions(SERVICE, opts.root)) {
+    // Twin-internal subject types (the recorded Stripe `event` envelopes the write path
+    // persists for the Events API, and idempotency bookkeeping) are NOT real-Stripe writes —
+    // they are local-only state and must never be pushed. Skip them (not an error).
+    if (INTERNAL_SUBJECT_TYPES.has(action.subject.type)) continue;
+    const { externalId } = await pushStripeAction(execute, action);
+    confirmAction({ service: SERVICE, actionId: action.id, subject: action.subject, fields: action.fields ?? {}, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+    confirmed.push(action.id);
+    externalIds[action.id] = externalId;
+  }
+  return { pushed: confirmed.length, confirmed, externalIds };
+}
+
+// ── FULL SYNC (all collections + webhooks, bi-directional) ───────────────────
+
+/** Pull a single REST list collection and map each row to a twin sync resource. */
+async function pullCollection(execute: StripeExecute, spec: { path: string; type: string; map?: (r: Record<string, unknown>) => SyncResource; params?: Record<string, unknown> }, limit: number): Promise<SyncResource[]> {
+  const res = await execute('GET', spec.path, { ...(spec.params ?? {}), limit });
+  throwIfError(res, `pull ${spec.type}`);
+  const map = spec.map ?? ((r: Record<string, unknown>) => mapScalarResource(spec.type, r));
+  return listOf(res).map(map);
+}
+
+/**
+ * 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 async function pullStripeAll(execute: StripeExecute, opts: { limit?: number } = {}): Promise<SyncResource[]> {
+  const limit = opts.limit ?? 100;
+  const all: SyncResource[] = [];
+  for (const spec of PULL_COLLECTIONS) all.push(...await pullCollection(execute, spec, limit));
+  return all;
+}
+
+/** Pull the account's registered webhook endpoints (so the twin mirrors them too). */
+export async function pullStripeWebhookEndpoints(execute: StripeExecute, opts: { limit?: number } = {}): Promise<SyncResource[]> {
+  const res = await execute('GET', '/v1/webhook_endpoints', { limit: opts.limit ?? 100 });
+  throwIfError(res, 'pull webhook_endpoints');
+  return listOf(res).map((w: Record<string, unknown>) => mapScalarResource('webhook_endpoint', w));
+}
+
+/**
+ * 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 async function fullSyncStripe(
+  execute: StripeExecute,
+  opts: { root?: string; occurredAt: string; limit?: number },
+): Promise<{ pushed: number; observed: number; deltasAppended: number; collections: number }> {
+  // 1. PUSH pending local changes to real Stripe (and confirm each).
+  const push = await pushPendingStripeActions(execute, { occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  // 2. PULL all collections + webhooks back into the twin.
+  const resources = [
+    ...await pullStripeAll(execute, { ...(opts.limit ? { limit: opts.limit } : {}) }),
+    ...await pullStripeWebhookEndpoints(execute, { ...(opts.limit ? { limit: opts.limit } : {}) }),
+  ];
+  const pull = syncPull({ service: SERVICE, resources, occurredAt: opts.occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { pushed: push.pushed, observed: pull.observed, deltasAppended: pull.deltasAppended, collections: PULL_COLLECTIONS.length + 1 };
+}