@volter/twin-stripe 2.0.38 → 3.0.0

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

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

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

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

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

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

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

@@ -1,47 +0,0 @@
-import { type SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** A customer's now: its test clock's frozen time when it is on one (docs.stripe.com/billing/testing/test-clocks), the
- *  World's otherwise. */
-export declare function clockNow(ctx: SemanticsContext, customer: unknown): number;
-/** What a subscription's invoices charge: its own default payment method, else its customer's. */
-export declare function payerOf(ctx: SemanticsContext, sub: Row): string | undefined;
-/** An item's quantity as it bills: 1 when none is set, and 0 when 0 is (a quantity of 0 bills nothing). */
-export declare function itemQuantity(it: Row): number;
-/** The subscription's discounts with a `once` coupon's spent: "When a subscription uses a coupon with `duration=once`, the
- *  coupon is considered used after the invoice finalizes and is removed from the subscription's `discounts` array"
- *  (docs.stripe.com/billing/subscriptions/coupons#coupon-duration). */
-export declare function unspentDiscounts(discounts: unknown): Row[];
-/** A subscription whose invoice has just been finalized: the `once` coupon that invoice took is spent, and a once coupon
- *  it did not take (added after it was drafted) stays for the next (unspentDiscounts). */
-export declare function spendOnceCoupon(ctx: SemanticsContext, invoice: Row): Promise<void>;
-/** A subscription's discounts after `invoice` finalizes: less the `once` coupons it took. */
-export declare function keptAfter(discounts: Row[], invoice: Row): Row[];
-/** A draft invoice for one period of a subscription, its lines the subscription's items and any one-time lines `once`
- *  gives it (a Checkout session's one-time prices, "on the initial invoice only", docs.stripe.com/api/checkout/sessions/
- *  create#create_checkout_session-line_items), under the subscription's discount. Answers the invoice id. */
-export declare function draftSubscriptionInvoice(ctx: SemanticsContext, sub: Row, o: {
-    start: number;
-    end: number;
-    reason: 'subscription_create' | 'subscription_cycle' | 'subscription_update';
-    trial?: boolean;
-    once?: Row[];
-    id?: string;
-}): Promise<string>;
-/** Finalize a subscription's draft invoice at `at` and charge what its subscription pays with. The move is time's (a
- *  renewal), the customer's (the Checkout page they paid on) or the API's (an update that ends a trial, which names the
- *  payer, may ask for no attempt, and moves the subscription itself: semantics/subscriptions.ts applyTrialEnd). Answers
- *  whether it was paid. */
-export declare function collectSubscriptionInvoice(ctx: SemanticsContext, invoiceId: string, at: number, actor: 'time' | 'external' | 'api', opts?: {
-    payer?: string;
-    attempt?: boolean;
-}): Promise<boolean>;
-/** Pay a subscription's open invoice with `paymentMethod` (the customer on the portal, `external`): the charge on the
- *  invoice's PaymentIntent, the invoice paid, a past_due subscription active. Answers the decline, if the card is refused. */
-export declare function payOpenInvoice(ctx: SemanticsContext, invoiceId: string, paymentMethod: string): Promise<{
-    code: string;
-    message: string;
-} | undefined>;
-/** Time's moves on subscriptions, caught up to each customer's clock in the order they fell due, each made at the
- *  moment it was due: a period that ended renews (a trial's end among them) or, set to cancel, cancels; a renewal
- *  drafted an hour or more ago is finalized and charged. */
-export declare function advanceBilling(ctx: SemanticsContext, only?: (sub: Row) => boolean): Promise<void>;