@volter/twin-stripe 0.1.2 → 2.0.1

package/src/semantics/payment-methods.ts

@@ -0,0 +1,145 @@
+// 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

@@ -0,0 +1,131 @@
+// 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

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