@volter/twin-stripe 2.0.37 → 3.0.0

package/src/semantics/payment-methods.ts

@@ -1,145 +0,0 @@
-// PaymentMethod semantics: a PaymentMethod is created detached, attached to a customer, and
-// detached again. The list is the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { declineFor, paymentMethodSubObject, TEST_TOKEN_DECLINES } from '../stripe-twin.ts';
-import { AFTER_SUCCESS_CARDS, afterSuccessOf } from './after-payment.ts';
-import { at, created, fail, type Row } from './shared.ts';
-
-const PM = 'payment_method';
-const noBilling = { address: null, email: null, name: null, phone: null };
-const pmMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such payment_method: '${id}'`, 404, 'resource_missing');
-
-// the raw card number, cvc and bank account number are never echoed: the modeled sub-object is
-// what the PaymentMethod carries, with the decline outcome its card implies, so a later charge
-// naming it only by id declines the same way
-const create: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const pmType = typeof params.type === 'string' ? params.type : 'card';
-  const { card: _card, sepa_debit: _sepa, us_bank_account: _ach, type: _t, ...rest } = params;
-  const sub = paymentMethodSubObject(pmType, params);
-  const declineOutcome = pmType === 'card' ? (declineFor(() => undefined, params) ?? null) : null;
-  // and what Stripe does after its card succeeds (a dispute, a review), which a later charge naming it by id brings
-  const afterSuccess = pmType === 'card' ? afterSuccessOf(ctx, params.card) : undefined;
-  // the billing details the create gives are the method's (docs.stripe.com/api/payment_methods/create#create_payment_method-billing_details)
-  const given = rest.billing_details && typeof rest.billing_details === 'object' ? (rest.billing_details as Row) : {};
-  return ctx.reply(await created(ctx, PM, { ...rest, type: pmType, customer: null, livemode: false, billing_details: { ...noBilling, ...given }, ...sub, _declineOutcome: declineOutcome, ...(afterSuccess ? { _afterSuccess: afterSuccess } : {}) }, {}));
-};
-
-const TEST_PM_CARDS: Record<string, { brand: string; number: string }> = {
-  ...AFTER_SUCCESS_CARDS,
-  pm_card_mastercard: { brand: 'mastercard', number: '5555555555554444' },
-  pm_card_amex: { brand: 'amex', number: '378282246310005' },
-  pm_card_discover: { brand: 'discover', number: '6011111111111117' },
-};
-
-/** The card a charge was paid with, as its payment_method_details reports it
- *  (docs.stripe.com/api/charges/object#charge_object-payment_method_details): a stored PaymentMethod's card, a
- *  documented test name (pm_card_* or tok_*, the same cards), or a raw card; undefined for anything else. */
-export function paymentMethodDetails(ctx: SemanticsContext, ref: unknown): Row | undefined {
-  let card: Row | undefined;
-  // a payment method of another kind (a US bank account) is described by its own block, as the charge reports it
-  const stored = typeof ref === 'string' && ref ? ctx.get(PM, ref) : undefined;
-  // Stripe's US bank account test methods (pm_us_bank_account, pm_usBankAccount_*) are its test bank's account
-  const pm = stored ?? (typeof ref === 'string' && /^pm_us_?bank_?account/i.test(ref) ? { type: 'us_bank_account', ...paymentMethodSubObject('us_bank_account', {}) } : undefined);
-  if (pm && typeof pm.type === 'string' && pm.type !== 'card') {
-    const own = (pm[pm.type] as Row | undefined) ?? {};
-    const pick = ['account_holder_type', 'account_type', 'bank_name', 'fingerprint', 'last4', 'routing_number'];
-    return { type: pm.type, [pm.type]: Object.fromEntries(pick.filter((k) => own[k] !== undefined).map((k) => [k, own[k]])) };
-  }
-  if (typeof ref === 'string' && ref) {
-    const stored = ctx.get(PM, ref)?.card as Row | undefined;
-    if (stored) card = stored;
-    else card = testCardOf(ref);
-  } else if (ref && typeof ref === 'object') card = paymentMethodSubObject('card', { card: ref }).card as Row;
-  if (!card) return undefined;
-  return {
-    type: 'card',
-    card: {
-      brand: card.brand, last4: card.last4, exp_month: card.exp_month, exp_year: card.exp_year, funding: card.funding ?? 'credit',
-      country: card.country ?? 'US', network: card.brand, fingerprint: card.fingerprint ?? null,
-      checks: card.checks ?? { address_line1_check: null, address_postal_code_check: null, cvc_check: 'pass' },
-      three_d_secure: null, wallet: null, installments: null, mandate: null,
-    },
-  };
-}
-
-// attaching needs an existing customer; a well-known test token (pm_card_visa, …) is a template:
-// attaching it mints a new PaymentMethod on the customer carrying that card's outcome
-/** Whether a payment method can be attached: a stored one, or a documented test name that attaching mints. */
-export const attachable = (ctx: SemanticsContext, id: string): boolean => !!ctx.get(PM, id) || (id.startsWith('pm_card_') && (id in TEST_TOKEN_DECLINES || id in AFTER_SUCCESS_CARDS));
-
-/** Attach a payment method to a customer (both known to exist or be attachable): a stored one moves to the
- *  customer; a test name mints a new PaymentMethod on the customer carrying that card's outcome. */
-/** The card a test name (pm_card_*, tok_*) stands for, never stored as a PaymentMethod (docs.stripe.com/testing#cards). */
-function testCardOf(ref: string): Row | undefined {
-  const name = ref.replace(/^tok_/, 'pm_card_');
-  if (!name.startsWith('pm_card_')) return undefined;
-  const test = TEST_PM_CARDS[name] ?? { brand: 'visa', number: '4242424242424242' };
-  return { ...(paymentMethodSubObject('card', { card: { number: test.number } }).card as Row), brand: test.brand };
-}
-
-export async function attachPaymentMethod(ctx: SemanticsContext, id: string, customer: string): Promise<Row> {
-  if (!ctx.get(PM, id)) return materializeTestMethod(ctx, id, customer);
-  return ctx.write(PM, id, { customer }, 'payment_method.attach');
-}
-
-/** A documented test name (pm_card_visa, pm_card_visa_chargeDeclined, …) made a real PaymentMethod, as Stripe
- *  does when one is used: the brand and number it stands for (docs.stripe.com/testing#cards) and its outcome. */
-export async function materializeTestMethod(ctx: SemanticsContext, id: string, customer: string | null): Promise<Row> {
-  const card = TEST_PM_CARDS[id] ?? { brand: 'visa', number: '4242424242424242' };
-  const sub = paymentMethodSubObject('card', { card: { number: card.number } });
-  (sub.card as Record<string, unknown>).brand = card.brand;
-  const afterSuccess = AFTER_SUCCESS_CARDS[id]?.outcome;
-  return created(ctx, PM, { type: 'card', customer, livemode: false, billing_details: noBilling, ...sub, _declineOutcome: TEST_TOKEN_DECLINES[id] ?? null, ...(afterSuccess ? { _afterSuccess: afterSuccess } : {}) }, {});
-}
-
-const attach: Semantics = async (ctx) => {
-  const id = at(ctx, 'payment_method');
-  const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
-  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-  if (!ctx.get('customer', customer)) return fail(ctx, `No such customer: '${customer}'`, 400, 'resource_missing');
-  if (!attachable(ctx, id)) return pmMissing(ctx, id);
-  return ctx.reply(await attachPaymentMethod(ctx, id, customer));
-};
-
-const retrieve: Semantics = async (ctx) => {
-  const m = ctx.get(PM, at(ctx, 'payment_method'));
-  return m ? ctx.reply(m) : pmMissing(ctx, at(ctx, 'payment_method'));
-};
-
-const detach: Semantics = async (ctx) => {
-  const id = at(ctx, 'payment_method');
-  if (!ctx.get(PM, id)) return pmMissing(ctx, id);
-  return ctx.reply(await ctx.write(PM, id, { customer: null }, 'payment_method.detach'));
-};
-
-export const paymentMethods: Record<string, Semantics> = {
-  PostPaymentMethods: create,
-  PostPaymentMethodsPaymentMethodAttach: attach,
-  GetPaymentMethodsPaymentMethod: retrieve,
-  PostPaymentMethodsPaymentMethodDetach: detach,
-};
-
-/** A PaymentMethod made from a confirm's `payment_method_data` ("If provided, this hash will be used to create a
- *  PaymentMethod", docs.stripe.com/api/setup_intents/confirm, docs.stripe.com/api/payment_intents/confirm), or none. */
-export async function methodFromData(ctx: SemanticsContext, data: unknown): Promise<string | undefined> {
-  if (!data || typeof data !== 'object') return undefined;
-  const d = data as Row;
-  const type = typeof d.type === 'string' ? d.type : 'card';
-  const made = await created(ctx, PM, {}, {
-    type, customer: null, livemode: false, metadata: {},
-    billing_details: { ...noBilling, ...((d.billing_details as Row | undefined) ?? {}) },
-    ...paymentMethodSubObject(type, d),
-    // what follows its card's success (a dispute, funds straight to available), as a PaymentMethod created directly carries
-    ...(type === 'card' && afterSuccessOf(ctx, d.card) ? { _afterSuccess: afterSuccessOf(ctx, d.card) } : {}),
-  });
-  return String(made.id);
-}
-
-/** Whether an intent sets up or pays with a bank account by micro-deposits because it asks for them:
- *  payment_method_options[us_bank_account][verification_method]=microdeposits with a us_bank_account method
- *  ("Microdeposit only verification", docs.stripe.com/payments/ach-direct-debit/set-up-payment). */
-export function microdepositsAsked(ctx: SemanticsContext, params: Row, intent: Row, pm: string | undefined): boolean {
-  const options = ((params.payment_method_options ?? intent.payment_method_options) as Row | undefined)?.us_bank_account as Row | undefined;
-  return options?.verification_method === 'microdeposits' && !!pm && ctx.get(PM, pm)?.type === 'us_bank_account';
-}

package/src/semantics/plans.ts

@@ -1,131 +0,0 @@
-// Plan semantics. Stripe's Prices API "replaces the Plans API and is backwards compatible" (docs.stripe.com/api/plans/create),
-// and "Existing plans can be used wherever recurring prices are accepted", a plan being one "which can be used
-// interchangeably with a price" (docs.stripe.com/billing/migration/migrating-prices). So a plan is stored as the recurring
-// price it is, under the plan's id, and the Plans API answers recurring prices in the plan's shape: a plan made here is
-// read, listed, updated and subscribed to as a price, and a recurring price made through the Prices API is a plan.
-// The plan's id: "An identifier randomly generated by Stripe ... You can optionally override this ID, but the ID must be
-// unique across all plans in your Stripe account" (the create page's `id`). `amount_decimal` is "Same as `amount`, but
-// accepts a decimal value with at most 12 decimal places. Only one of `amount` and `amount_decimal` can be set", and the
-// plan answers it as "a decimal string", its `amount` "a whole integer if possible" (spec/openapi.json.gz, the plan
-// object). Plan writes send the plan events, plan.created / plan.updated / plan.deleted, each carrying the plan object
-// (docs.stripe.com/api/events/types; the write hook renders it, ../stripe-twin.ts afterStripeWrite). "Deleting plans
-// means new subscribers can't be added. Existing subscribers aren't affected." (docs.stripe.com/api/plans/delete), and
-// deleting one twice is an error. Where the documentation stops and the twin decides: a minted plan id is `plan_` over
-// the price counter, a duplicate id is refused with resource_already_exists, the refusals are worded by the twin, and only
-// the per_unit scheme is modelled (a tiered plan is refused, naming the gap); a deleted plan is gone from the Plans API
-// while the recurring price it was stays readable through the Prices API, inactive, so the subscription items that name
-// it still resolve (the docs do not say what the Prices API answers for it).
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { asBool } from '../stripe-twin.ts';
-import { at, created, fail, kept, list, newest, type Row } from './shared.ts';
-
-const INTERVALS = new Set(['day', 'week', 'month', 'year']);
-
-/** A recurring price in the plan object's shape (the create page's example response). */
-export function planOf(price: Row): Row {
-  const r = (price.recurring ?? {}) as Row;
-  const amount = typeof price.unit_amount === 'number' ? price.unit_amount : null;
-  const decimal = typeof price.unit_amount_decimal === 'string' ? price.unit_amount_decimal : amount === null ? null : String(amount);
-  return {
-    id: price.id, object: 'plan', active: price.active ?? true, amount, amount_decimal: decimal,
-    billing_scheme: price.billing_scheme ?? 'per_unit', created: price.created, currency: price.currency, interval: r.interval ?? null,
-    interval_count: r.interval_count ?? 1, livemode: false, metadata: price.metadata ?? {}, meter: r.meter ?? null, nickname: price.nickname ?? null,
-    product: price.product, tiers_mode: price.tiers_mode ?? null, transform_usage: price.transform_quantity ?? null,
-    trial_period_days: r.trial_period_days ?? null, usage_type: r.usage_type ?? 'licensed',
-  };
-}
-
-/** Metadata after an update: an empty value unsets the key, an empty `metadata` unsets them all. */
-function metadataAfter(was: Row, given: unknown): Row {
-  if (given === '' || given === null || typeof given !== 'object') return {};
-  const next: Row = { ...was };
-  for (const [k, v] of Object.entries(given as Row)) if (v === '' || v === null) delete next[k]; else next[k] = v;
-  return next;
-}
-
-const planMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such plan: '${id}'`, 404, 'resource_missing');
-/** A recurring price the Plans API still answers: one whose plan was deleted is not a plan any more. */
-const recurring = (ctx: SemanticsContext, p: Row | undefined): p is Row => !!p && !!p.recurring && kept(ctx, 'price', p, '_plan_deleted') !== true;
-
-const createPlan: Semantics = async (ctx) => {
-  const p = ctx.params;
-  for (const name of ['currency', 'interval', 'product']) if (p[name] === undefined || p[name] === '') return fail(ctx, `Missing required param: ${name}.`, 400, 'parameter_missing');
-  if (!INTERVALS.has(String(p.interval))) return fail(ctx, `Invalid interval: must be one of day, week, month, or year`, 400, 'parameter_invalid_string');
-  if (p.billing_scheme === 'tiered') return fail(ctx, 'Tiered plans are not modelled by this twin; create a tiered price instead.', 400, 'parameter_invalid_string');
-  if (p.amount === undefined && p.amount_decimal === undefined) return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
-  if (p.amount !== undefined && p.amount_decimal !== undefined) return fail(ctx, 'Only one of `amount` and `amount_decimal` can be set.', 400, 'parameter_invalid');
-  const id = typeof p.id === 'string' && p.id ? p.id : ctx.mint('price').replace(/^price_/, 'plan_');
-  if (ctx.get('price', id)) return fail(ctx, `Plan already exists: '${id}'`, 400, 'resource_already_exists');
-  // "The product whose pricing the created plan will represent. This can either be the ID of an existing product, or a
-  // dictionary containing fields used to create a service product"
-  let product: string;
-  if (p.product && typeof p.product === 'object') {
-    product = String((await created(ctx, 'product', p.product as Row, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: ctx.now() })).id);
-  } else {
-    product = String(p.product);
-    if (!ctx.get('product', product)) return fail(ctx, `No such product: '${product}'`, 400, 'resource_missing');
-  }
-  // the decimal is kept as given; the whole amount is its integer when it is one
-  const decimal = p.amount_decimal !== undefined ? String(p.amount_decimal) : String(Math.trunc(Number(p.amount)));
-  const unit = Number.isInteger(Number(decimal)) ? Number(decimal) : null;
-  const price = await created(ctx, 'price', {
-    id, product, currency: String(p.currency).toLowerCase(), unit_amount: unit, unit_amount_decimal: decimal,
-    recurring: { interval: p.interval, interval_count: Math.trunc(Number(p.interval_count ?? 1)), usage_type: p.usage_type ?? 'licensed', trial_period_days: p.trial_period_days !== undefined ? Math.trunc(Number(p.trial_period_days)) : null, meter: p.meter ?? null },
-    ...(p.nickname !== undefined ? { nickname: p.nickname } : {}), ...(p.metadata !== undefined ? { metadata: p.metadata } : {}),
-    ...(p.active !== undefined ? { active: asBool(p.active) } : {}),
-  }, { active: true, livemode: false, billing_scheme: 'per_unit', type: 'recurring', metadata: {}, lookup_key: null, nickname: null, tax_behavior: 'unspecified' }, { operation: 'plan.create' });
-  return ctx.reply(planOf(price));
-};
-
-const retrievePlan: Semantics = async (ctx) => {
-  const price = ctx.get('price', at(ctx, 'plan'));
-  return recurring(ctx, price) ? ctx.reply(planOf(price)) : planMissing(ctx, at(ctx, 'plan'));
-};
-
-// "Updates the specified plan by setting the values of the parameters passed. Any parameters not provided are left
-// unchanged. By design, you cannot change a plan's ID, amount, currency, or billing cycle." (docs.stripe.com/api/plans/update):
-// active, metadata ("Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an
-// empty value to `metadata`"), nickname, product, trial_period_days
-const updatePlan: Semantics = async (ctx) => {
-  const id = at(ctx, 'plan');
-  const price = ctx.get('price', id);
-  if (!recurring(ctx, price)) return planMissing(ctx, id);
-  const p = ctx.params;
-  if (typeof p.product === 'string' && !ctx.get('product', p.product)) return fail(ctx, `No such product: '${p.product}'`, 400, 'resource_missing');
-  const fields: Row = {
-    ...(p.active !== undefined ? { active: asBool(p.active) } : {}),
-    ...(p.nickname !== undefined ? { nickname: p.nickname } : {}),
-    ...(p.metadata !== undefined ? { metadata: metadataAfter((price.metadata ?? {}) as Row, p.metadata) } : {}),
-    ...(typeof p.product === 'string' ? { product: p.product } : {}),
-    ...(p.trial_period_days !== undefined ? { recurring: { ...(price.recurring as Row), trial_period_days: Math.trunc(Number(p.trial_period_days)) } } : {}),
-  };
-  const next = await ctx.write('price', id, fields, 'plan.update');
-  return ctx.reply(planOf(next));
-};
-
-const deletePlan: Semantics = async (ctx) => {
-  const id = at(ctx, 'plan');
-  if (!recurring(ctx, ctx.get('price', id))) return planMissing(ctx, id);
-  // existing subscribers keep it: the price stays, inactive, and only the plan is gone
-  const price = ctx.get('price', id)!;
-  if (price.active !== false) ctx.legal('price', 'active', 'DeletePlansPlan', 'true', 'false', id);
-  await ctx.write('price', id, { active: false, _plan_deleted: true }, 'plan.delete');
-  return ctx.reply({ id, object: 'plan', deleted: true });
-};
-
-const listPlans: Semantics = async (ctx) => {
-  const p = ctx.params;
-  const plans = newest(ctx, 'price').filter((x) => recurring(ctx, x))
-    .filter((x) => p.active === undefined || asBool(x.active) === asBool(p.active))
-    .filter((x) => p.product === undefined || x.product === p.product)
-    .map(planOf);
-  return list(ctx, 'price', plans);
-};
-
-export const plans: Record<string, Semantics> = {
-  PostPlans: createPlan,
-  GetPlans: listPlans,
-  GetPlansPlan: retrievePlan,
-  PostPlansPlan: updatePlan,
-  DeletePlansPlan: deletePlan,
-};

package/src/semantics/platform.ts

@@ -1,220 +0,0 @@
-// Semantics for Stripe's smaller products: Climate (a fixed product and supplier catalog, and
-// orders against it), Financial Connections (sessions, linked accounts, their transactions),
-// PAN forwarding requests, and Reporting (a report-type catalog and report runs, which the twin
-// completes at once). Lists and retrieves of what is stored are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { at, created, fail, list, newest, path, where, type Row } from './shared.ts';
-
-// ── Climate: Stripe's catalog is managed and account-independent. The twin serves the catalog Stripe's reference
-// publishes (docs.stripe.com/api/climate/product/object, /api/climate/supplier/object): Frontier's 2027 offtake
-// portfolio at $550 a ton plus Frontier's service fees of $16.50 (3%), 18,000 tons, from Charm Industrial.
-// Where the documentation stops and the twin decides: the catalog is that one product and supplier. ──
-
-const CLIMATE_SUPPLIERS = [
-  { id: 'climsup_charm_industrial', name: 'Charm Industrial', removal_pathway: 'biomass_carbon_removal_and_storage', info_url: 'https://frontierclimate.com/portfolio/charm-industrial', locations: [{ city: 'San Francisco', country: 'US', latitude: 37.7749, longitude: -122.4194, region: 'CA' }] },
-] as const;
-const CLIMATE_PRODUCTS = [
-  { id: 'climsku_frontier_offtake_portfolio_2027', name: "Frontier's 2027 offtake portfolio", subtotal: 55000, fees: 1650, currency: 'usd', delivery_year: 2027, metric_tons_available: '18000', created: 1881439203, suppliers: ['climsup_charm_industrial'] },
-] as const;
-const supplierView = (s: (typeof CLIMATE_SUPPLIERS)[number]): Row => ({ id: s.id, object: 'climate.supplier', name: s.name, removal_pathway: s.removal_pathway, info_url: s.info_url, locations: s.locations, livemode: false });
-const productView = (p: (typeof CLIMATE_PRODUCTS)[number]): Row => ({
-  id: p.id, object: 'climate.product', name: p.name, livemode: false, delivery_year: p.delivery_year,
-  metric_tons_available: p.metric_tons_available, created: p.created,
-  current_prices_per_metric_ton: { [p.currency]: { amount_fees: p.fees, amount_subtotal: p.subtotal, amount_total: p.subtotal + p.fees } },
-  suppliers: p.suppliers.map((id) => supplierView(CLIMATE_SUPPLIERS.find((s) => s.id === id)!)),
-});
-const catalog = (ctx: SemanticsContext, data: Row[]): Response => ctx.reply({ object: 'list', url: path(ctx), has_more: false, data });
-
-const climateProduct: Semantics = async (ctx) => {
-  const p = CLIMATE_PRODUCTS.find((x) => x.id === at(ctx, 'product'));
-  return p ? ctx.reply(productView(p)) : fail(ctx, `No such product: '${at(ctx, 'product')}'`, 404, 'resource_missing');
-};
-const climateSupplier: Semantics = async (ctx) => {
-  const s = CLIMATE_SUPPLIERS.find((x) => x.id === at(ctx, 'supplier'));
-  return s ? ctx.reply(supplierView(s)) : fail(ctx, `No such supplier: '${at(ctx, 'supplier')}'`, 404, 'resource_missing');
-};
-
-const ORDER = 'climate.order';
-const orderMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such order: '${id}'`, 404, 'resource_missing');
-
-// exactly one of amount or metric_tons; Frontier's fees are the product's per-ton share (3%: the create page's
-// example charges 17 on a 550 subtotal, "Total amount of Frontier's service fees", the order object), rounded to the
-// cent; the order is confirmed when made and delivers in the product's delivery year
-const createOrder: Semantics = async (ctx) => {
-  const product = typeof ctx.params.product === 'string' ? ctx.params.product : '';
-  if (!product) return fail(ctx, 'Missing required param: product.', 400, 'parameter_missing');
-  const prod = CLIMATE_PRODUCTS.find((x) => x.id === product);
-  if (!prod) return fail(ctx, `No such product: '${product}'`, 400, 'resource_missing');
-  const hasTons = ctx.params.metric_tons !== undefined;
-  if (hasTons === (ctx.params.amount !== undefined)) return fail(ctx, 'You must provide exactly one of `amount` or `metric_tons`.', 400, 'parameter_missing');
-  const metricTons = hasTons ? Number(ctx.params.metric_tons) : Number(ctx.params.amount) / prod.subtotal;
-  const amountSubtotal = Math.round(metricTons * prod.subtotal);
-  const amountFees = Math.round((amountSubtotal * prod.fees) / prod.subtotal);
-  return ctx.reply(
-    await created(ctx, ORDER, {}, {
-      object: 'climate.order', livemode: false, status: 'confirmed', product, certificate: null,
-      amount_subtotal: amountSubtotal, amount_fees: amountFees, amount_total: amountSubtotal + amountFees,
-      currency: prod.currency, metric_tons: String(metricTons),
-      beneficiary: ctx.params.beneficiary && typeof ctx.params.beneficiary === 'object' ? ctx.params.beneficiary : { public_name: 'Stripe Climate' },
-      confirmed_at: ctx.now(), canceled_at: null, delivered_at: null, delayed_at: null,
-      product_substituted_at: null, cancellation_reason: null,
-      expected_delivery_year: prod.delivery_year,
-      delivery_details: [], metadata: ctx.params.metadata && typeof ctx.params.metadata === 'object' ? ctx.params.metadata : {},
-    }),
-  );
-};
-
-const cancelOrder: Semantics = async (ctx) => {
-  const id = at(ctx, 'order');
-  const o = ctx.get(ORDER, id);
-  if (!o) return orderMissing(ctx, id);
-  const refused = ctx.legal(ORDER, 'status', 'PostClimateOrdersOrderCancel', o.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  return ctx.reply(await ctx.write(ORDER, id, { status: 'canceled', canceled_at: ctx.now(), cancellation_reason: 'requested' }, 'climate_order.canceled'));
-};
-
-// only the beneficiary and metadata change
-const updateOrder: Semantics = async (ctx) => {
-  const id = at(ctx, 'order');
-  if (!ctx.get(ORDER, id)) return orderMissing(ctx, id);
-  const patch: Row = {};
-  if (ctx.params.beneficiary !== undefined) patch.beneficiary = ctx.params.beneficiary;
-  if (ctx.params.metadata !== undefined) patch.metadata = ctx.params.metadata;
-  return ctx.reply(await ctx.write(ORDER, id, patch, 'climate_order.updated'));
-};
-
-// ── Financial Connections: a session is created for an account holder and its permissions; accounts
-// are linked in the authentication flow Stripe.js opens (../screens/financial-connections.tsx) ──
-
-const FCS = 'financial_connections.session';
-const FCA = 'financial_connections.account';
-const FCT = 'financial_connections.transaction';
-
-const createSession: Semantics = async (ctx) => {
-  const holder = ctx.params.account_holder && typeof ctx.params.account_holder === 'object' ? (ctx.params.account_holder as Row) : null;
-  if (!holder) return fail(ctx, 'Missing required param: account_holder.', 400, 'parameter_missing');
-  const perms = Array.isArray(ctx.params.permissions) ? ctx.params.permissions.map(String) : typeof ctx.params.permissions === 'string' ? [ctx.params.permissions] : [];
-  if (perms.length === 0) return fail(ctx, 'Missing required param: permissions.', 400, 'parameter_missing');
-  const id = ctx.mint(FCS);
-  return ctx.reply(
-    await created(ctx, FCS, { id }, {
-      object: 'financial_connections.session', livemode: false, client_secret: `fcsess_${id}_secret_twin`,
-      account_holder: holder, permissions: perms, prefetch: Array.isArray(ctx.params.prefetch) ? ctx.params.prefetch : null,
-      filters: ctx.params.filters && typeof ctx.params.filters === 'object' ? ctx.params.filters : null,
-      return_url: typeof ctx.params.return_url === 'string' ? ctx.params.return_url : null,
-      accounts: { object: 'list', has_more: false, url: `/v1/financial_connections/accounts?session=${id}`, data: [] },
-    }),
-  );
-};
-
-// a session's accounts are the ones linked to it now
-const session: Semantics = async (ctx) => {
-  const id = at(ctx, 'session');
-  const s = ctx.get(FCS, id);
-  if (!s) return fail(ctx, `No such financial connections session: '${id}'`, 404, 'resource_missing');
-  return ctx.reply({ ...s, accounts: { object: 'list', has_more: false, url: `/v1/financial_connections/accounts?session=${id}`, data: newest(ctx, FCA).filter((a) => a.session === id) } });
-};
-
-const accounts: Semantics = async (ctx) =>
-  list(ctx, FCA, where(ctx, newest(ctx, FCA), { session: (a, v) => a.session === v, account_holder: (a, v) => (a.account_holder as Row | undefined)?.customer === v }));
-
-const disconnect: Semantics = async (ctx) => {
-  const id = at(ctx, 'account');
-  const a = ctx.get(FCA, id);
-  if (!a) return fail(ctx, `No such account: '${id}'`, 404, 'resource_missing');
-  const refused = ctx.legal(FCA, 'status', 'PostFinancialConnectionsAccountsAccountDisconnect', a.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  return ctx.reply(await ctx.write(FCA, id, { status: 'disconnected' }, 'fc_account.disconnected'));
-};
-
-const transactions: Semantics = async (ctx) => {
-  if (typeof ctx.params.account !== 'string' || !ctx.params.account) return fail(ctx, 'Missing required param: account.', 400, 'parameter_missing');
-  return list(ctx, FCT, newest(ctx, FCT).filter((t) => t.account === ctx.params.account));
-};
-
-// ── forwarding: the twin answers a deterministic destination response; it makes no network call ──
-
-const forward: Semantics = async (ctx) => {
-  const pm = typeof ctx.params.payment_method === 'string' ? ctx.params.payment_method : '';
-  if (!pm) return fail(ctx, 'Missing required param: payment_method.', 400, 'parameter_missing');
-  const url = typeof ctx.params.url === 'string' ? ctx.params.url : '';
-  if (!url) return fail(ctx, 'Missing required param: url.', 400, 'parameter_missing');
-  return ctx.reply(
-    await created(ctx, 'forwarding.request', {}, {
-      object: 'forwarding.request', livemode: false, payment_method: pm, url, replacements: Array.isArray(ctx.params.replacements) ? ctx.params.replacements.map(String) : [],
-      request_context: { destination_duration: 42, destination_ip_address: '127.0.0.1' },
-      request_details: { http_method: 'POST', url, headers: [], body: '[redacted]' },
-      response_details: { status: 200, headers: [], body: '{"approved":true}' },
-    }),
-  );
-};
-
-// ── Reporting: a representative subset of Stripe's report types; a run succeeds at once ──
-
-const REPORT_TYPES: Array<{ id: string; name: string }> = [
-  { id: 'balance.summary.1', name: 'Balance summary' },
-  { id: 'balance_change_from_activity.summary.1', name: 'Balance change from activity (summary)' },
-  { id: 'payouts.summary.1', name: 'Payouts (summary)' },
-  { id: 'payout_reconciliation.by_id.itemized.4', name: 'Payout reconciliation (itemized)' },
-];
-const reportTypeView = (t: { id: string; name: string }): Row => ({
-  id: t.id, object: 'reporting.report_type', name: t.name, version: 1,
-  data_available_start: 0, data_available_end: 0, default_columns: null, updated: 0, livemode: false,
-});
-
-const reportType: Semantics = async (ctx) => {
-  const t = REPORT_TYPES.find((x) => x.id === at(ctx, 'report_type'));
-  return t ? ctx.reply(reportTypeView(t)) : fail(ctx, `No such report type: '${at(ctx, 'report_type')}'`, 404, 'resource_missing');
-};
-
-// report_type names the report; parameters (the interval, the columns) shape it (docs.stripe.com/api/reporting/report_run/create)
-const runReport: Semantics = async (ctx) => {
-  const p = ctx.params.parameters && typeof ctx.params.parameters === 'object' ? (ctx.params.parameters as Row) : {};
-  const type = typeof ctx.params.report_type === 'string' ? ctx.params.report_type : '';
-  if (!type) return fail(ctx, 'Missing required param: report_type.', 400, 'parameter_missing');
-  if (!REPORT_TYPES.some((t) => t.id === type)) return fail(ctx, `Invalid report type: '${type}'.`, 400, 'parameter_invalid_string_enum');
-  // a run starts pending with no result (finishReportRuns completes it)
-  return ctx.reply(await created(ctx, 'reporting.report_run', { parameters: p }, { status: 'pending', report_type: type, livemode: false, error: null, succeeded_at: null, result: null }));
-};
-
-/** Each pending report run completes, caught up before anything is answered: "When the run completes, Stripe updates
- *  the object, and it has a status of succeeded. It also has a nested result object, containing a URL that you can use
- *  to access the file", the guide's example a File of purpose report_run and type csv (docs.stripe.com/reports/api).
- *  "Most runs complete within a few minutes" (the same page). Where the documentation stops and the twin decides: a run
- *  completes one minute after it was created (the guide's example: created 1580832900, succeeded_at 1580832960), and
- *  its CSV holds the report type's header row alone (its size that row's bytes). */
-export async function finishReportRuns(ctx: SemanticsContext): Promise<void> {
-  for (const run of ctx.rowsRaw('reporting.report_run')) {
-    if (run.status !== 'pending') continue;
-    const done = Number(run.created) + 60;
-    if (Number(ctx.now()) < done) continue;
-    const id = String(run.id);
-    const header = 'category,currency,description,net_amount\n';
-    const file = await created(ctx, 'file', { purpose: 'report_run' }, {
-      filename: `${String(run.report_type)}_${id}.csv`, size: header.length, type: 'csv', title: null, expires_at: null, url: null,
-      links: { object: 'list', data: [], has_more: false, url: '' },
-    });
-    await ctx.write('file', String(file.id), { url: `https://files.twin.local/v1/files/${String(file.id)}/contents` }, 'file.updated');
-    ctx.legal('reporting.report_run', 'status', ctx.call.operation.id, 'pending', 'succeeded', id, 'vendor');
-    await ctx.write('reporting.report_run', id, { status: 'succeeded', succeeded_at: done, result: ctx.get('file', String(file.id)) }, 'reporting.report_run.succeeded');
-  }
-}
-
-export const platform: Record<string, Semantics> = {
-  GetClimateProducts: async (ctx) => catalog(ctx, CLIMATE_PRODUCTS.map(productView)),
-  GetClimateProductsProduct: climateProduct,
-  GetClimateSuppliers: async (ctx) => catalog(ctx, CLIMATE_SUPPLIERS.map(supplierView)),
-  GetClimateSuppliersSupplier: climateSupplier,
-  PostClimateOrders: createOrder,
-  PostClimateOrdersOrderCancel: cancelOrder,
-  PostClimateOrdersOrder: updateOrder,
-  PostFinancialConnectionsSessions: createSession,
-  GetFinancialConnectionsSessionsSession: session,
-  GetFinancialConnectionsAccounts: accounts,
-  PostFinancialConnectionsAccountsAccountDisconnect: disconnect,
-  GetFinancialConnectionsTransactions: transactions,
-  PostForwardingRequests: forward,
-  GetReportingReportTypes: async (ctx) => catalog(ctx, REPORT_TYPES.map(reportTypeView)),
-  GetReportingReportTypesReportType: reportType,
-  PostReportingReportRuns: runReport,
-};