@volter/twin-stripe 0.1.1 → 2.0.0

package/dist/src/semantics/payment-links.js

@@ -0,0 +1,133 @@
+import { asBool, lineItemEntries, paginate, resolveLineItem } from "../stripe-twin.js";
+import { draftInvoiceFor } from "./invoices.js";
+import { at, created, fail, finder, list, newest, path, where } from "./shared.js";
+/** The request's line items resolved against their prices, or the refusal for a missing price. */
+function resolved(ctx) {
+    const entries = lineItemEntries(ctx.params);
+    const items = [];
+    for (let i = 0; i < entries.length; i++) {
+        const { item, priceMissing } = resolveLineItem(entries[i], i, 'usd', finder(ctx));
+        if (priceMissing)
+            return fail(ctx, `No such price: '${priceMissing}'`, 400, 'resource_missing');
+        items.push(item);
+    }
+    return items;
+}
+/** A page of the line items a stored object carries. */
+function linePage(ctx, holder) {
+    const li = holder.line_items;
+    const { page, hasMore } = paginate(Array.isArray(li?.data) ? li.data : [], ctx.params);
+    return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
+}
+const PL = 'payment_link';
+const linkMissing = (ctx, id) => fail(ctx, `No such payment link: '${id}'`, 404, 'resource_missing');
+const createLink = async (ctx) => {
+    if (lineItemEntries(ctx.params).length === 0)
+        return fail(ctx, 'Missing required param: line_items.', 400, 'parameter_missing');
+    const items = resolved(ctx);
+    if (items instanceof Response)
+        return items;
+    const id = ctx.mint(PL);
+    const { line_items: _li, ...rest } = ctx.params;
+    return ctx.reply(await created(ctx, PL, { ...rest, id }, {
+        active: ctx.params.active !== undefined ? asBool(ctx.params.active) : true,
+        url: `https://buy.twin.local/${id}`, livemode: false, metadata: {},
+        // Stripe's defaults for what the link was not given (docs.stripe.com/api/payment-link/create)
+        allow_promotion_codes: false, automatic_tax: { enabled: false, liability: null }, billing_address_collection: 'auto',
+        custom_fields: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null },
+        customer_creation: 'if_required', payment_method_collection: 'always', phone_number_collection: { enabled: false },
+        shipping_options: [], submit_type: 'auto', tax_id_collection: { enabled: false, required: 'never' },
+        line_items: { object: 'list', data: items, has_more: false, url: `/v1/payment_links/${id}/line_items` },
+        currency: items[0]?.currency ?? 'usd',
+        after_completion: { type: 'redirect', redirect: typeof ctx.params.after_completion === 'object' ? ctx.params.after_completion : null },
+    }));
+};
+const listLinks = async (ctx) => list(ctx, PL, where(ctx, newest(ctx, PL), { active: (p, v) => asBool(p.active) === asBool(v) }));
+const linkLines = async (ctx) => {
+    const p = ctx.get(PL, at(ctx, 'payment_link'));
+    return p ? linePage(ctx, p) : linkMissing(ctx, at(ctx, 'payment_link'));
+};
+// ── quotes ──
+const quoteMissing = (ctx, id) => fail(ctx, `No such quote: '${id}'`, 404, 'resource_missing');
+const createQuote = async (ctx) => {
+    const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
+    if (!customer)
+        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+    if (!ctx.row('customer', customer, { withDeleted: true }))
+        return fail(ctx, `No such customer: '${customer}'`, 400, 'resource_missing');
+    const items = resolved(ctx);
+    if (items instanceof Response)
+        return items;
+    const subtotal = items.reduce((s, it) => s + it.amount_subtotal, 0);
+    const id = ctx.mint('quote');
+    const { line_items: _li, ...rest } = ctx.params;
+    return ctx.reply(await created(ctx, 'quote', { ...rest, id }, {
+        status: 'draft', customer, currency: items[0]?.currency ?? 'usd', livemode: false, metadata: {},
+        amount_subtotal: subtotal, amount_total: subtotal,
+        // Stripe's defaults (docs.stripe.com/api/quotes/create); what is paid up front is the whole quote, and the twin bills in classic mode
+        automatic_tax: { enabled: false, liability: null, provider: null, status: null }, collection_method: 'charge_automatically', discounts: [],
+        invoice_settings: { days_until_due: null, issuer: { type: 'self' } },
+        subscription_data: { billing_mode: { type: 'classic' }, description: null, effective_date: null, metadata: null, trial_period_days: null },
+        computed: { recurring: null, upfront: { amount_subtotal: subtotal, amount_total: subtotal, total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 } } },
+        line_items: { object: 'list', data: items, has_more: false, url: `/v1/quotes/${id}/line_items` },
+        total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 },
+        expires_at: Number(ctx.now()) + 30 * 24 * 3600,
+        number: null, invoice: null, subscription: null,
+        status_transitions: { accepted_at: null, canceled_at: null, finalized_at: null },
+    }));
+};
+const quoteLines = async (ctx) => {
+    const q = ctx.get('quote', at(ctx, 'quote'));
+    return q ? linePage(ctx, q) : quoteMissing(ctx, at(ctx, 'quote'));
+};
+// Stripe streams the PDF; the twin answers a stable reference to it
+const pdf = async (ctx) => {
+    const id = at(ctx, 'quote');
+    if (!ctx.get('quote', id))
+        return quoteMissing(ctx, id);
+    return ctx.reply({ object: 'quote_pdf', url: `https://files.twin.local/quotes/${id}.pdf` });
+};
+function move(action, operationId) {
+    return async (ctx) => {
+        const id = at(ctx, 'quote');
+        const q = ctx.get('quote', id);
+        if (!q)
+            return quoteMissing(ctx, id);
+        const refused = ctx.legal('quote', 'status', operationId, q.status, undefined, id);
+        if (refused)
+            return ctx.refuse(refused);
+        const now = ctx.now();
+        const stamp = action === 'finalize' ? { finalized_at: now } : action === 'accept' ? { accepted_at: now } : { canceled_at: now };
+        // "Accepted quotes automatically generate an invoice, subscription, or subscription schedule"; "Quotes without
+        // recurring prices: A draft invoice is created with auto_advance set to false" (docs.stripe.com/quotes/overview),
+        // the quote its parent ("Details about the quote that generated this invoice", the served spec). Where the
+        // documentation stops and the twin decides: a quote with recurring prices makes no subscription yet.
+        let made = {};
+        if (action === 'accept') {
+            const lines = q.line_items?.data ?? [];
+            const recurring = lines.some((l) => l.price && typeof l.price === 'object' && l.price.recurring);
+            if (!recurring && typeof q.customer === 'string') {
+                const invoice = await draftInvoiceFor(ctx, q.customer, String(q.currency ?? 'usd'), { type: 'quote_details', quote_details: { quote: id }, subscription_details: null }, lines.map((l) => ({ price: l.price, quantity: Number(l.quantity) || 1, amount: Number(l.amount_subtotal ?? l.amount_total) || 0, description: l.description })));
+                made = { invoice };
+            }
+        }
+        return ctx.reply(await ctx.write('quote', id, {
+            status: action === 'finalize' ? 'open' : action === 'accept' ? 'accepted' : 'canceled',
+            status_transitions: { ...(q.status_transitions ?? {}), ...stamp },
+            ...(action === 'finalize' ? { number: `QT-${id.toUpperCase()}` } : {}),
+            ...made,
+        }, `quote.${action}`));
+    };
+}
+export const paymentLinks = {
+    PostPaymentLinks: createLink,
+    GetPaymentLinks: listLinks,
+    GetPaymentLinksPaymentLinkLineItems: linkLines,
+    PostQuotes: createQuote,
+    GetQuotesQuoteLineItems: quoteLines,
+    GetQuotesQuoteComputedUpfrontLineItems: quoteLines,
+    GetQuotesQuotePdf: pdf,
+    PostQuotesQuoteFinalize: move('finalize', 'PostQuotesQuoteFinalize'),
+    PostQuotesQuoteAccept: move('accept', 'PostQuotesQuoteAccept'),
+    PostQuotesQuoteCancel: move('cancel', 'PostQuotesQuoteCancel'),
+};

package/dist/src/semantics/payment-methods.d.ts

@@ -0,0 +1,20 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** 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 declare function paymentMethodDetails(ctx: SemanticsContext, ref: unknown): Row | undefined;
+/** Whether a payment method can be attached: a stored one, or a documented test name that attaching mints. */
+export declare const attachable: (ctx: SemanticsContext, id: string) => boolean;
+export declare function attachPaymentMethod(ctx: SemanticsContext, id: string, customer: string): Promise<Row>;
+/** 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 declare function materializeTestMethod(ctx: SemanticsContext, id: string, customer: string | null): Promise<Row>;
+export declare const paymentMethods: Record<string, Semantics>;
+/** 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 declare function methodFromData(ctx: SemanticsContext, data: unknown): Promise<string | undefined>;
+/** 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 declare function microdepositsAsked(ctx: SemanticsContext, params: Row, intent: Row, pm: string | undefined): boolean;

package/dist/src/semantics/payment-methods.js

@@ -0,0 +1,138 @@
+import { declineFor, paymentMethodSubObject, TEST_TOKEN_DECLINES } from "../stripe-twin.js";
+import { AFTER_SUCCESS_CARDS, afterSuccessOf } from "./after-payment.js";
+import { at, created, fail } from "./shared.js";
+const PM = 'payment_method';
+const noBilling = { address: null, email: null, name: null, phone: null };
+const pmMissing = (ctx, id) => 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 = 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 : {};
+    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 = {
+    ...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, ref) {
+    let card;
+    // 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] ?? {};
+        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;
+        if (stored)
+            card = stored;
+        else
+            card = testCardOf(ref);
+    }
+    else if (ref && typeof ref === 'object')
+        card = paymentMethodSubObject('card', { card: ref }).card;
+    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, id) => !!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) {
+    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, brand: test.brand };
+}
+export async function attachPaymentMethod(ctx, id, customer) {
+    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, id, customer) {
+    const card = TEST_PM_CARDS[id] ?? { brand: 'visa', number: '4242424242424242' };
+    const sub = paymentMethodSubObject('card', { card: { number: card.number } });
+    sub.card.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 = 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 = async (ctx) => {
+    const m = ctx.get(PM, at(ctx, 'payment_method'));
+    return m ? ctx.reply(m) : pmMissing(ctx, at(ctx, 'payment_method'));
+};
+const detach = 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 = {
+    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, data) {
+    if (!data || typeof data !== 'object')
+        return undefined;
+    const d = data;
+    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 ?? {}) },
+        ...paymentMethodSubObject(type, d),
+    });
+    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, params, intent, pm) {
+    const options = (params.payment_method_options ?? intent.payment_method_options)?.us_bank_account;
+    return options?.verification_method === 'microdeposits' && !!pm && ctx.get(PM, pm)?.type === 'us_bank_account';
+}

package/dist/src/semantics/plans.d.ts

@@ -0,0 +1,5 @@
+import type { Semantics } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** A recurring price in the plan object's shape (the create page's example response). */
+export declare function planOf(price: Row): Row;
+export declare const plans: Record<string, Semantics>;

package/dist/src/semantics/plans.js

@@ -0,0 +1,121 @@
+import { asBool } from "../stripe-twin.js";
+import { at, created, fail, kept, list, newest } from "./shared.js";
+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) {
+    const r = (price.recurring ?? {});
+    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, given) {
+    if (given === '' || given === null || typeof given !== 'object')
+        return {};
+    const next = { ...was };
+    for (const [k, v] of Object.entries(given))
+        if (v === '' || v === null)
+            delete next[k];
+        else
+            next[k] = v;
+    return next;
+}
+const planMissing = (ctx, id) => 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, p) => !!p && !!p.recurring && kept(ctx, 'price', p, '_plan_deleted') !== true;
+const createPlan = 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;
+    if (p.product && typeof p.product === 'object') {
+        product = String((await created(ctx, 'product', p.product, { 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 = 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 = 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 = {
+        ...(p.active !== undefined ? { active: asBool(p.active) } : {}),
+        ...(p.nickname !== undefined ? { nickname: p.nickname } : {}),
+        ...(p.metadata !== undefined ? { metadata: metadataAfter((price.metadata ?? {}), p.metadata) } : {}),
+        ...(typeof p.product === 'string' ? { product: p.product } : {}),
+        ...(p.trial_period_days !== undefined ? { recurring: { ...price.recurring, 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 = 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 = 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 = {
+    PostPlans: createPlan,
+    GetPlans: listPlans,
+    GetPlansPlan: retrievePlan,
+    PostPlansPlan: updatePlan,
+    DeletePlansPlan: deletePlan,
+};

package/dist/src/semantics/platform.d.ts

@@ -0,0 +1,9 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+/** 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 declare function finishReportRuns(ctx: SemanticsContext): Promise<void>;
+export declare const platform: Record<string, Semantics>;

package/dist/src/semantics/platform.js

@@ -0,0 +1,206 @@
+import { at, created, fail, list, newest, path, where } from "./shared.js";
+// ── 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' }] },
+];
+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'] },
+];
+const supplierView = (s) => ({ 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) => ({
+    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, data) => ctx.reply({ object: 'list', url: path(ctx), has_more: false, data });
+const climateProduct = 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 = 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, id) => 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 = 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 = 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 = async (ctx) => {
+    const id = at(ctx, 'order');
+    if (!ctx.get(ORDER, id))
+        return orderMissing(ctx, id);
+    const patch = {};
+    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 = async (ctx) => {
+    const holder = ctx.params.account_holder && typeof ctx.params.account_holder === 'object' ? ctx.params.account_holder : 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 = 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 = async (ctx) => list(ctx, FCA, where(ctx, newest(ctx, FCA), { session: (a, v) => a.session === v, account_holder: (a, v) => a.account_holder?.customer === v }));
+const disconnect = 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 = 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 = 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 = [
+    { 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: 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 = 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 = async (ctx) => {
+    const p = ctx.params.parameters && typeof ctx.params.parameters === 'object' ? ctx.params.parameters : {};
+    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) {
+    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 = {
+    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,
+};