@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/semantics/coupons.js

@@ -1,15 +1,5 @@
-import { asBool } from "../stripe-twin.js";
-import { at_, created, fail, list, newest, where } from "./shared.js";
-/** A coupon for a fixed amount off, in its currency (docs.stripe.com/api/coupons/create#create_coupon-amount_off). */
-function amountOffOf(ctx, params) {
-    const amountOff = Number(params.amount_off);
-    if (!Number.isInteger(amountOff) || amountOff <= 0)
-        return fail(ctx, 'Invalid integer: amount_off must be a positive integer.', 400, 'parameter_invalid_integer');
-    if (params.currency === undefined || params.currency === '')
-        return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
-    return amountOff;
-}
-const createCoupon = async (ctx) => {
+import { amountOffOf, created, fail } from "./shared.js";
+export async function PostCoupons(ctx) {
     const params = ctx.params;
     const hasPct = params.percent_off !== undefined;
     const hasAmt = params.amount_off !== undefined;
@@ -41,52 +31,4 @@ const createCoupon = async (ctx) => {
         redeem_by: params.redeem_by !== undefined ? Number(params.redeem_by) : null,
         applies_to: null,
     }));
-};
-// a code the caller does not give is derived from the promotion code's id
-const createPromotionCode = async (ctx) => {
-    // what it promotes: promotion[type]=coupon and promotion[coupon] (2025-09-30.clover,
-    // docs.stripe.com/changelog/clover/2025-09-30/polymorphic-coupon), or the top-level coupon a caller pinned to an
-    // earlier version sends; the twin keeps the coupon's id on the code for its rules
-    const { promotion, coupon: legacy, ...params } = ctx.params;
-    const promo = promotion && typeof promotion === 'object' ? promotion : undefined;
-    if (promo && promo.type !== 'coupon')
-        return fail(ctx, 'Invalid promotion[type]: must be coupon.', 400, 'parameter_invalid_string_enum');
-    const coupon = typeof promo?.coupon === 'string' ? promo.coupon : typeof legacy === 'string' ? legacy : '';
-    if (!coupon)
-        return fail(ctx, promo ? 'Missing required param: promotion[coupon].' : 'Missing required param: promotion.', 400, 'parameter_missing');
-    if (!ctx.get('coupon', coupon))
-        return fail(ctx, `No such coupon: '${coupon}'`, 400, 'resource_missing');
-    const id = ctx.mint('promotion_code');
-    const code = typeof params.code === 'string' && params.code ? params.code : `TWIN${id.toUpperCase().replace(/[^A-Z0-9]/g, '')}`;
-    return ctx.reply(await created(ctx, 'promotion_code', { ...params, coupon, promotion: { type: 'coupon', coupon }, id, code }, {
-        active: params.active !== undefined ? asBool(params.active) : true,
-        customer: typeof params.customer === 'string' ? params.customer : null,
-        expires_at: params.expires_at !== undefined ? Number(params.expires_at) : null,
-        max_redemptions: params.max_redemptions !== undefined ? Number(params.max_redemptions) : null,
-        times_redeemed: 0, livemode: false, metadata: {}, restrictions: { first_time_transaction: false, minimum_amount: null, minimum_amount_currency: null },
-    }));
-};
-/** Time's lapsing of coupons, caught up to the World's clock: a valid coupon whose redeem_by has passed is no longer
- *  valid from that moment (manifest.ts). Where the documentation stops and the twin decides: the lapse sends no event
- *  (the events page names none for it). */
-export async function lapseCoupons(ctx) {
-    const now = Number(ctx.now());
-    for (const c of ctx.rowsRaw('coupon')) {
-        if (c.valid !== true || typeof c.redeem_by !== 'number' || c.redeem_by > now)
-            continue;
-        const t = await at_(ctx)(c.redeem_by);
-        t.legal('coupon', 'valid', ctx.call.operation.id, 'true', 'false', String(c.id), 'time');
-        await t.write('coupon', String(c.id), { valid: false }, 'coupon.lapsed');
-    }
 }
-const listPromotionCodes = async (ctx) => list(ctx, 'promotion_code', where(ctx, newest(ctx, 'promotion_code'), {
-    code: (p, v) => p.code === v,
-    active: (p, v) => asBool(p.active) === asBool(v),
-    coupon: (p, v) => p.coupon === v,
-    customer: (p, v) => p.customer === v,
-}));
-export const coupons = {
-    PostCoupons: createCoupon,
-    PostPromotionCodes: createPromotionCode,
-    GetPromotionCodes: listPromotionCodes,
-};

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

@@ -1,6 +1,5 @@
-import type { Semantics } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** What a new customer answers before any invoice: its invoice_prefix and a next_invoice_sequence of 1, a zero balance,
- *  no metadata (docs.stripe.com/api/customers/object). */
-export declare const newCustomer: (id: string) => Row;
-export declare const customers: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetCustomersCustomer(ctx: HandlerContext): Promise<Response>;
+export declare function GetCustomersSearch(ctx: HandlerContext): Promise<Response>;
+export declare function PostCustomers(ctx: HandlerContext): Promise<Response>;
+export declare function PostCustomersCustomer(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/customers.js

@@ -1,429 +1,63 @@
-import { buildDiscount } from "../stripe-twin.js";
-import { invoicePrefix } from "./invoices.js";
-import { mintCharge } from "./payment-intents.js";
-import { attachable, attachPaymentMethod } from "./payment-methods.js";
-import { at, created, deletedDiscount, expanded, fail, list, newest, redeemCoupon, search, where } from "./shared.js";
-const customerMissing = (ctx, id) => fail(ctx, `No such customer: '${id}'`, 404, 'resource_missing');
-/** The discount a customer's `coupon` makes, a parameter of API versions before the served one. */
-function customerDiscount(ctx, couponId) {
-    const coupon = ctx.get('coupon', couponId);
-    return coupon ? buildDiscount(coupon, '', Number(ctx.now())) : fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
+import { newCustomer } from "../engine/customers.js";
+import { nowUnix } from "../engine/stripe.js";
+import { at, attachable, attachPaymentMethod, created, customerMissing, expanded, fail, search } from "./shared.js";
+// "If it’s for a deleted Customer, a subset of the customer’s information is returned, including a `deleted` property
+// that’s set to true" (docs.stripe.com/api/customers/retrieve)
+export async function GetCustomersCustomer(ctx) {
+    const id = at(ctx, 'customer');
+    const row = ctx.row('customer', id, { withDeleted: true });
+    if (!row)
+        return customerMissing(ctx, id);
+    if (row.deleted === true)
+        return ctx.reply({ id, object: 'customer', deleted: true });
+    return ctx.reply(expanded(ctx, 'customer', ctx.get('customer', id)));
+}
+export async function GetCustomersSearch(ctx) {
+    return search(ctx, 'customer');
 }
-/** What a new customer answers before any invoice: its invoice_prefix and a next_invoice_sequence of 1, a zero balance,
- *  no metadata (docs.stripe.com/api/customers/object). */
-export const newCustomer = (id) => ({ invoice_prefix: invoicePrefix(id), next_invoice_sequence: 1, balance: 0, metadata: {}, invoice_settings: {} });
-const create = async (ctx) => {
-    // a `coupon` on create materializes the discount object on the customer (the coupon must exist)
-    const couponId = typeof ctx.params.coupon === 'string' ? ctx.params.coupon : '';
-    const discount = couponId ? customerDiscount(ctx, couponId) : null;
-    if (discount instanceof Response)
-        return discount;
+export async function PostCustomers(ctx) {
     // `payment_method` attaches that method to the new customer; it is not a field of the customer
     // (docs.stripe.com/api/customers/create#create_customer-payment_method)
     const pmId = typeof ctx.params.payment_method === 'string' ? ctx.params.payment_method : '';
     if (pmId && !attachable(ctx, pmId))
         return fail(ctx, `No such PaymentMethod: '${pmId}'`, 400, 'resource_missing');
-    const { coupon: _c, payment_method: _pm, ...rest } = ctx.params;
+    const given = ctx.params;
+    const { coupon: _c, payment_method: _pm, ...rest } = given;
     const id = ctx.mint('customer');
-    const customer = await created(ctx, 'customer', { ...rest, id }, { livemode: false, discount: discount ? { ...discount, customer: id } : null, ...newCustomer(id) });
-    if (discount)
-        await redeemCoupon(ctx, couponId);
+    const customer = await created(ctx, 'customer', { ...rest, id }, { livemode: false, discount: null, ...newCustomer(id) });
+    // source: https://docs.stripe.com/billing/customer/balance "Represents the starting value of the customer invoice balance when a customer is created using the API with a non-zero invoice balance."
+    if (Number(customer.balance ?? 0) !== 0) {
+        await created(ctx, 'customer_balance_transaction', {
+            customer: id, amount: Number(customer.balance), ending_balance: Number(customer.balance),
+            currency: customer.currency ?? 'usd', type: 'initial', description: null, metadata: {},
+            livemode: false, invoice: null, credit_note: null, checkout_session: null, customer_account: null,
+        }, {});
+    }
     if (pmId)
         await attachPaymentMethod(ctx, pmId, String(customer.id));
     return ctx.reply(customer);
-};
-const searchCustomers = async (ctx) => search(ctx, 'customer');
-// "If it’s for a deleted Customer, a subset of the customer’s information is returned, including a `deleted` property
-// that’s set to true" (docs.stripe.com/api/customers/retrieve)
-const retrieve = async (ctx) => {
-    const id = at(ctx, 'customer');
-    const row = ctx.row('customer', id, { withDeleted: true });
-    if (!row)
-        return customerMissing(ctx, id);
-    if (row.deleted === true)
-        return ctx.reply({ id, object: 'customer', deleted: true });
-    return ctx.reply(expanded(ctx, 'customer', ctx.get('customer', id)));
-};
-// the payment methods attached to a customer (customers.listPaymentMethods), optionally by `type`
-const paymentMethods = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    const items = where(ctx, newest(ctx, 'payment_method').filter((m) => m.customer === customer), { type: (m, v) => m.type === v });
-    return list(ctx, 'payment_method', items);
-};
-const paymentMethod = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    const m = ctx.get('payment_method', at(ctx, 'payment_method'));
-    return m && m.customer === customer ? ctx.reply(m) : fail(ctx, `No such PaymentMethod: '${at(ctx, 'payment_method')}'`, 404, 'resource_missing');
-};
-// removing the customer's discount answers the deleted-discount stub
-const deleteDiscount = async (ctx) => {
+}
+// ── the credit-balance ledger: a negative amount is a credit; `ending_balance` is the running sum,
+// mirrored onto the customer's `balance` ──
+// source: spec:PostCustomersCustomer "Updates the specified customer by setting the values of the parameters passed."
+export async function PostCustomersCustomer(ctx) {
     const id = at(ctx, 'customer');
     const customer = ctx.get('customer', id);
     if (!customer)
         return customerMissing(ctx, id);
-    const discount = customer.discount;
-    if (!discount)
-        return fail(ctx, `No active discount for customer: '${id}'`, 404, 'resource_missing');
-    await ctx.write('customer', id, { discount: null }, 'customer.update');
-    return ctx.reply(deletedDiscount(discount, ctx.now()));
-};
-// ── tax ids: a customer's, keyed under it; `type` and `value` are required ──
-// An EU VAT number is its country's prefix and that country's format (the European Commission's VIES formats,
-// ec.europa.eu/taxation_customs/vies); Stripe refuses one that does not fit as tax_id_invalid
-// (docs.stripe.com/error-codes#tax-id-invalid). The message's wording is the twin's.
-const EU_VAT = {
-    AT: /^U\d{8}$/, BE: /^[01]\d{9}$/, BG: /^\d{9,10}$/, CY: /^\d{8}[A-Z]$/, CZ: /^\d{8,10}$/, DE: /^\d{9}$/, DK: /^\d{8}$/,
-    EE: /^\d{9}$/, EL: /^\d{9}$/, ES: /^[A-Z0-9]\d{7}[A-Z0-9]$/, FI: /^\d{8}$/, FR: /^[A-Z0-9]{2}\d{9}$/, HR: /^\d{11}$/,
-    HU: /^\d{8}$/, IE: /^(\d{7}[A-W][A-I]?|\d[A-Z+*]\d{5}[A-W])$/, IT: /^\d{11}$/, LT: /^(\d{9}|\d{12})$/, LU: /^\d{8}$/,
-    LV: /^\d{11}$/, MT: /^\d{8}$/, NL: /^\d{9}B\d{2}$/, PL: /^\d{10}$/, PT: /^\d{9}$/, RO: /^\d{2,10}$/, SE: /^\d{12}$/,
-    SI: /^\d{8}$/, SK: /^\d{10}$/, XI: /^(\d{9}|\d{12}|GD\d{3}|HA\d{3})$/,
-};
-const euVatCountry = (value) => {
-    const v = value.replace(/[\s.-]/g, '').toUpperCase();
-    const prefix = v.slice(0, 2);
-    const format = EU_VAT[prefix];
-    return format && format.test(v.slice(2)) ? (prefix === 'EL' ? 'GR' : prefix) : undefined;
-};
-/** The tax ID types Stripe checks against a government register: "Stripe automatically validates all Australian
- *  Business Numbers (ABNs)", "all European Value-Added-Tax (EU VAT) numbers" (VIES) and "all UK Value-Added-Tax (GB VAT)
- *  numbers" (HMRC); a verification's status "is pending, verified, unverified, or unavailable", and "When automatic
- *  validation is unavailable, you must manually verify the tax ID" (docs.stripe.com/billing/customer/tax-ids). Any other
- *  type answers unavailable; one of these waits pending. */
-const AUTO_VALIDATED = new Set(['au_abn', 'eu_vat', 'gb_vat']);
-/** A tax ID for its owner: the account itself, or one of its customers. */
-async function makeTaxId(ctx, customer) {
-    const { owner: _owner, ...params } = ctx.params;
-    if (params.type === undefined || params.type === '')
-        return fail(ctx, 'Missing required param: type.', 400, 'parameter_missing');
-    if (params.value === undefined || params.value === '')
-        return fail(ctx, 'Missing required param: value.', 400, 'parameter_missing');
-    const vatCountry = params.type === 'eu_vat' ? euVatCountry(String(params.value)) : undefined;
-    if (params.type === 'eu_vat' && !vatCountry)
-        return ctx.refuse({ status: 400, code: 'tax_id_invalid', param: 'value', message: `Invalid value for eu_vat.` });
-    return ctx.reply(await created(ctx, 'tax_id', { ...params, ...(customer ? { customer } : {}) }, {
-        livemode: false,
-        country: vatCountry ?? (typeof params.country === 'string' ? params.country : null),
-        owner: customer ? { type: 'customer', customer } : { type: 'self' },
-        verification: { status: AUTO_VALIDATED.has(String(params.type)) ? 'pending' : 'unavailable', verified_address: null, verified_name: null },
-    }));
-}
-const createTaxId = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    return makeTaxId(ctx, customer);
-};
-/** The owner a top-level tax-ID call names: the account itself unless `owner[type]=customer` names a customer
- *  (docs.stripe.com/api/tax_ids/list: owner defaults to self). */
-function ownerOf(ctx) {
-    const owner = (ctx.params.owner ?? {});
-    const type = String(owner.type ?? 'self');
-    if (type === 'self')
-        return {};
-    if (type !== 'customer')
-        return fail(ctx, `Invalid owner[type]: must be one of self or customer.`, 400, 'parameter_invalid_string_enum');
-    const customer = typeof owner.customer === 'string' ? owner.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: owner[customer].', 400, 'parameter_missing');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    return { customer };
-}
-const createOwnedTaxId = async (ctx) => {
-    const owner = ownerOf(ctx);
-    return owner instanceof Response ? owner : makeTaxId(ctx, owner.customer);
-};
-const listOwnedTaxIds = async (ctx) => {
-    const owner = ownerOf(ctx);
-    if (owner instanceof Response)
-        return owner;
-    return list(ctx, 'tax_id', newest(ctx, 'tax_id').filter((t) => (owner.customer ? t.customer === owner.customer : !t.customer)));
-};
-const taxIds = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    return list(ctx, 'tax_id', newest(ctx, 'tax_id').filter((t) => t.customer === customer));
-};
-const taxId = async (ctx) => {
-    const t = ctx.get('tax_id', at(ctx, 'id'));
-    return t && t.customer === at(ctx, 'customer') ? ctx.reply(t) : fail(ctx, `No such tax_id: '${at(ctx, 'id')}'`, 404, 'resource_missing');
-};
-const deleteTaxId = async (ctx) => {
-    const id = at(ctx, 'id');
-    const t = ctx.get('tax_id', id);
-    if (!t || t.customer !== at(ctx, 'customer'))
-        return fail(ctx, `No such tax_id: '${id}'`, 404, 'resource_missing');
-    await ctx.write('tax_id', id, { deleted: true }, 'tax_id.delete');
-    return ctx.reply({ id, object: 'tax_id', deleted: true });
-};
-// ── the credit-balance ledger: a negative amount is a credit; `ending_balance` is the running sum,
-// mirrored onto the customer's `balance` ──
-const createBalanceTransaction = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    const params = ctx.params;
-    if (params.amount === undefined)
-        return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
-    const amount = Number(params.amount);
-    if (!Number.isInteger(amount))
-        return fail(ctx, 'Invalid integer: amount.', 400, 'parameter_invalid_integer');
-    if (params.currency === undefined || params.currency === '')
-        return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
-    const prior = ctx.rows('customer_balance_transaction').filter((t) => t.customer === customer).reduce((s, t) => s + (Number(t.amount) || 0), 0);
-    const ending = prior + amount;
-    const body = await created(ctx, 'customer_balance_transaction', { ...params, customer, amount }, {
-        ending_balance: ending, type: 'adjustment', livemode: false, metadata: {},
-        description: params.description ?? null, credit_note: null, invoice: null, checkout_session: null,
-    });
-    // keyed by the new transaction so two adjustments at one instant are two writes, the last winning
-    await ctx.write('customer', customer, { balance: ending }, `customer.balance_adjusted:${String(body.id)}`);
-    return ctx.reply(body);
-};
-const balanceTransactions = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    return list(ctx, 'customer_balance_transaction', newest(ctx, 'customer_balance_transaction').filter((t) => t.customer === customer));
-};
-const balanceTransaction = async (ctx) => {
-    const t = ctx.get('customer_balance_transaction', at(ctx, 'transaction'));
-    return t && t.customer === at(ctx, 'customer') ? ctx.reply(t) : fail(ctx, `No such balance transaction: '${at(ctx, 'transaction')}'`, 404, 'resource_missing');
-};
-// ── the cash balance: per-currency sums of the funding ledger, and the reconciliation setting ──
-function cashBalance(ctx, customer) {
-    const byCurrency = {};
-    for (const t of ctx.rows('customer_cash_balance_transaction')) {
-        if (t.customer !== customer)
-            continue;
-        const cur = String(t.currency ?? 'usd');
-        byCurrency[cur] = (byCurrency[cur] ?? 0) + (Number(t.net_amount) || 0);
-    }
-    const cust = ctx.row('customer', customer);
-    const mode = typeof cust?._cash_balance_mode === 'string' ? cust._cash_balance_mode : 'automatic';
-    return {
-        object: 'cash_balance', customer,
-        available: Object.keys(byCurrency).length ? byCurrency : null,
-        settings: { reconciliation_mode: mode, using_merchant_default: mode === 'merchant_default' },
-        livemode: false,
-    };
-}
-const getCashBalance = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    return ctx.reply(cashBalance(ctx, customer));
-};
-const updateCashBalance = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    const settings = ctx.params.settings && typeof ctx.params.settings === 'object' ? ctx.params.settings : {};
-    const mode = typeof settings.reconciliation_mode === 'string' ? settings.reconciliation_mode : 'automatic';
-    if (!['automatic', 'manual', 'merchant_default'].includes(mode))
-        return fail(ctx, 'Invalid settings[reconciliation_mode].', 400, 'parameter_invalid_string_enum');
-    await ctx.write('customer', customer, { _cash_balance_mode: mode }, 'cash_balance.updated');
-    return ctx.reply(cashBalance(ctx, customer));
-};
-const cashBalanceTransactions = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    return list(ctx, 'customer_cash_balance_transaction', newest(ctx, 'customer_cash_balance_transaction').filter((t) => t.customer === customer));
-};
-/** Automatic reconciliation (docs.stripe.com/payments/customer-balance/reconciliation): funds that arrive pay the
- *  customer's open invoices that take bank transfers (payment_method_types customer_balance), the one whose number
- *  the transfer's reference names first, then the oldest. Where the documentation stops and the twin decides: an
- *  invoice is paid only when the balance covers all of what remains; a smaller balance waits for more funds. */
-async function reconcile(ctx, customer, currency, reference) {
-    const takesTransfers = (inv) => inv.payment_settings?.payment_method_types?.includes('customer_balance') === true;
-    const open = ctx.rows('invoice').filter((inv) => inv.customer === customer && inv.status === 'open' && String(inv.currency ?? 'usd') === currency && takesTransfers(inv))
-        .sort((a, b) => (reference && a.number === reference ? -1 : reference && b.number === reference ? 1 : Number(a.created) - Number(b.created)));
-    for (const inv of open) {
-        const available = Number((cashBalance(ctx, customer).available ?? {})[currency] ?? 0);
-        const amount = Number(inv.amount_remaining ?? inv.amount_due) || 0;
-        if (amount <= 0 || available < amount)
-            continue;
-        const id = String(inv.id);
-        if (ctx.legal('invoice', 'status', 'PostTestHelpersCustomersCustomerFundCashBalance', inv.status, 'paid', id))
-            continue;
-        // the payment the balance makes: the invoice's own PaymentIntent (every invoice finalized with an amount due has one,
-        // semantics/invoices.ts), paid from the cash balance, its charge, and the ledger's entry
-        const piId = String(inv.payment_intent);
-        await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'applied_to_payment', net_amount: -amount, ending_balance: available - amount, applied_to_payment: { payment_intent: piId }, livemode: false });
-        const charge = await mintCharge(ctx, piId, { currency, customer, invoice: id }, amount);
-        await ctx.write('payment_intent', piId, { status: 'succeeded', amount_received: amount, latest_charge: charge }, 'payment_intent.succeeded');
-        await ctx.write('invoice', id, {
-            status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0, payment_intent: piId, charge,
-            status_transitions: { ...(inv.status_transitions ?? {}), paid_at: ctx.now() },
-        }, 'invoice.paid');
-    }
-}
-// test mode's stand-in for a bank transfer arriving (docs.stripe.com/payments/customer-balance/funding#test):
-// the customer's cash balance is funded by `amount`, and in automatic reconciliation the funds pay what waits on them
-const fundCashBalance = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    const amount = Math.trunc(Number(ctx.params.amount) || 0);
-    if (amount <= 0)
-        return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
-    const currency = typeof ctx.params.currency === 'string' ? ctx.params.currency : '';
-    if (!currency)
-        return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
-    const before = Number((cashBalance(ctx, customer).available ?? {})[currency] ?? 0);
-    const reference = typeof ctx.params.reference === 'string' ? ctx.params.reference : null;
-    const funded = await created(ctx, 'customer_cash_balance_transaction', { customer }, {
-        currency, type: 'funded', net_amount: amount, ending_balance: before + amount, livemode: false,
-        funded: { bank_transfer: { reference, type: 'us_bank_transfer', us_bank_transfer: { network: 'ach', sender_name: null } } },
-    });
-    if (cashBalance(ctx, customer).settings.reconciliation_mode !== 'manual')
-        await reconcile(ctx, customer, currency, reference);
-    return ctx.reply(funded);
-};
-const cashBalanceTransaction = async (ctx) => {
-    const t = ctx.get('customer_cash_balance_transaction', at(ctx, 'transaction'));
-    return t && t.customer === at(ctx, 'customer') ? ctx.reply(t) : fail(ctx, `No such cash balance transaction: '${at(ctx, 'transaction')}'`, 404, 'resource_missing');
-};
-// ── legacy sources: attaching a token mints a card with only the safe fields; the first becomes
-// the customer's default_source, and detaching the default promotes the next ──
-const attachSource = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    const c = ctx.get('customer', customer);
-    if (!c)
-        return customerMissing(ctx, customer);
-    const src = typeof ctx.params.source === 'string' ? ctx.params.source : '';
-    if (!src)
-        return fail(ctx, 'Missing required param: source.', 400, 'parameter_missing');
-    // a card token becomes the card it carries, the token spent: "you can only use tokens once" (the served spec's
-    // token.used); any other source reference keeps the twin's stand-in card
-    const token = src.startsWith('tok_') ? ctx.get('token', src) : undefined;
-    if (token?.used === true)
-        return fail(ctx, `You cannot use a Stripe token more than once: ${src}.`, 400, 'token_already_used');
-    const tokenCard = token?.card && typeof token.card === 'object' ? token.card : undefined;
-    const last4 = String(4242 + ctx.rows('source').length + 1).slice(-4);
-    const body = await created(ctx, 'source', { customer, ...(tokenCard ? { id: String(tokenCard.id) } : {}) }, tokenCard
-        ? { ...tokenCard, customer, _source_token: src }
-        : { object: 'card', last4, brand: 'Visa', exp_month: 12, exp_year: 2030, funding: 'credit', country: 'US', metadata: {}, _source_token: src });
-    if (token)
-        await ctx.write('token', src, { used: true }, 'token.used');
-    const existing = ctx.rows('source').filter((s) => s.customer === customer);
-    if (!c.default_source || existing.length === 1)
-        await ctx.write('customer', customer, { default_source: body.id }, 'customer.updated');
-    return ctx.reply(body);
-};
-const sources = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    if (!ctx.get('customer', customer))
-        return customerMissing(ctx, customer);
-    const items = newest(ctx, 'source').filter((s) => s.customer === customer);
-    return list(ctx, 'source', typeof ctx.params.object === 'string' ? items.filter((s) => s.object === ctx.params.object) : items);
-};
-/** The customer's source the path names, or undefined. */
-const customerSource = (ctx) => {
-    const s = ctx.get('source', at(ctx, 'id'));
-    return s && s.customer === at(ctx, 'customer') ? s : undefined;
-};
-const sourceMissing = (ctx) => fail(ctx, `No such source: '${at(ctx, 'id')}'`, 404, 'resource_missing');
-const source = async (ctx) => {
-    const s = customerSource(ctx);
-    return s ? ctx.reply(s) : sourceMissing(ctx);
-};
-const updateSource = async (ctx) => {
-    if (!customerSource(ctx))
-        return sourceMissing(ctx);
-    return ctx.reply(await ctx.write('source', at(ctx, 'id'), ctx.params, 'source.updated'));
-};
-const detachSource = async (ctx) => {
-    const customer = at(ctx, 'customer');
-    const id = at(ctx, 'id');
-    const c = ctx.get('customer', customer);
-    const s = customerSource(ctx);
-    if (!c || !s)
-        return sourceMissing(ctx);
-    await ctx.write('source', id, { deleted: true, customer: null }, 'source.detached');
-    if (c.default_source === id) {
-        const remaining = ctx.rows('source').filter((x) => x.customer === customer && x.id !== id);
-        await ctx.write('customer', customer, { default_source: remaining[0]?.id ?? null }, 'customer.updated');
+    const { customer: _pathCustomer, ...fields } = ctx.params;
+    // source: https://docs.stripe.com/billing/customer/balance "All modifications to the invoice balance are recorded as Transactions"
+    // source: https://docs.stripe.com/billing/customer/balance "All Transactions created with the API or in the Dashboard have a type value of adjustment"
+    if (typeof fields.balance === 'number' && fields.balance !== Number(customer.balance ?? 0)) {
+        const balance = fields.balance;
+        await created(ctx, 'customer_balance_transaction', {
+            customer: id, amount: balance - Number(customer.balance ?? 0), ending_balance: balance,
+            // Stripe inherits the customer's billing currency. Where no invoice has set it, this World's invoice currency is USD.
+            currency: customer.currency ?? 'usd', type: 'adjustment',
+            description: null, metadata: {}, livemode: false,
+            invoice: null, credit_note: null, checkout_session: null, customer_account: null,
+            created: nowUnix(ctx.occurredAt),
+        }, {});
     }
-    return ctx.reply({ id, object: s.object ?? 'card', deleted: true });
-};
-// ── the top-level Source: `type` is required; a card is chargeable at once, anything else pending ──
-const createSource = async (ctx) => {
-    const params = ctx.params;
-    const srcType = typeof params.type === 'string' ? params.type : '';
-    if (!srcType)
-        return fail(ctx, 'Missing required param: type.', 400, 'parameter_missing');
-    return ctx.reply(await created(ctx, 'source', { customer: null }, {
-        object: 'source',
-        status: srcType === 'card' ? 'chargeable' : 'pending',
-        flow: srcType === 'card' ? 'none' : 'receiver',
-        usage: params.usage ?? 'reusable',
-        currency: typeof params.currency === 'string' ? params.currency : null,
-        livemode: false,
-        type: srcType,
-        client_secret: `src_client_secret_twin_${ctx.rows('source').length + 1}`,
-        owner: params.owner && typeof params.owner === 'object' ? params.owner : { name: null, email: null, address: null, phone: null, verified_name: null, verified_email: null, verified_address: null, verified_phone: null },
-        metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
-        statement_descriptor: null,
-        ...(srcType === 'ach_credit_transfer' ? achCreditTransfer(ctx) : {}),
-    }));
-};
-/** An ACH credit transfer source's account for the customer to wire to, and its receiver flow, as the sources create
- *  page's example answers one (docs.stripe.com/api/sources/create): a test account number, "TEST BANK", routing
- *  110000000 and SWIFT TSTEZ122; the receiver's address "routing-account" with nothing yet charged, received or
- *  returned, refund attributes by email and missing. Where the documentation stops and the twin decides: the account
- *  number is the source's own. */
-function achCreditTransfer(ctx) {
-    const account = `test_${String(ctx.rows('source').length + 1).padStart(12, '0')}`;
-    return {
-        ach_credit_transfer: { account_number: account, bank_name: 'TEST BANK', fingerprint: `twin_acct_${account}`, refund_account_holder_name: null, refund_account_holder_type: null, refund_routing_number: null, routing_number: '110000000', swift_code: 'TSTEZ122' },
-        receiver: { address: `110000000-${account}`, amount_charged: 0, amount_received: 0, amount_returned: 0, refund_attributes_method: 'email', refund_attributes_status: 'missing' },
-    };
+    return ctx.reply(ctx.expand('customer', await ctx.write('customer', id, fields, 'customer.update')));
 }
-// a Source update changes only its metadata and owner
-const updateTopSource = async (ctx) => {
-    const id = at(ctx, 'source');
-    if (!ctx.get('source', id))
-        return fail(ctx, `No such source: '${id}'`, 404, 'resource_missing');
-    const patch = {};
-    if (ctx.params.metadata !== undefined)
-        patch.metadata = ctx.params.metadata;
-    if (ctx.params.owner !== undefined)
-        patch.owner = ctx.params.owner;
-    return ctx.reply(await ctx.write('source', id, patch, 'source.updated'));
-};
-export const customers = {
-    PostCustomers: create,
-    GetCustomersCustomer: retrieve,
-    GetCustomersSearch: searchCustomers,
-    GetCustomersCustomerPaymentMethods: paymentMethods,
-    GetCustomersCustomerPaymentMethodsPaymentMethod: paymentMethod,
-    DeleteCustomersCustomerDiscount: deleteDiscount,
-    PostCustomersCustomerTaxIds: createTaxId,
-    PostTaxIds: createOwnedTaxId,
-    GetTaxIds: listOwnedTaxIds,
-    GetCustomersCustomerTaxIds: taxIds,
-    GetCustomersCustomerTaxIdsId: taxId,
-    DeleteCustomersCustomerTaxIdsId: deleteTaxId,
-    PostCustomersCustomerBalanceTransactions: createBalanceTransaction,
-    GetCustomersCustomerBalanceTransactions: balanceTransactions,
-    GetCustomersCustomerBalanceTransactionsTransaction: balanceTransaction,
-    GetCustomersCustomerCashBalance: getCashBalance,
-    PostCustomersCustomerCashBalance: updateCashBalance,
-    GetCustomersCustomerCashBalanceTransactions: cashBalanceTransactions,
-    GetCustomersCustomerCashBalanceTransactionsTransaction: cashBalanceTransaction,
-    PostTestHelpersCustomersCustomerFundCashBalance: fundCashBalance,
-    PostCustomersCustomerSources: attachSource,
-    GetCustomersCustomerSources: sources,
-    GetCustomersCustomerSourcesId: source,
-    PostCustomersCustomerSourcesId: updateSource,
-    DeleteCustomersCustomerSourcesId: detachSource,
-    PostSources: createSource,
-    PostSourcesSource: updateTopSource,
-};

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

@@ -0,0 +1,23 @@
+import type { HandlerContext } from '@volter/world-core';
+/** The platform's own account settings (its payout schedule, its public name) change on Stripe's Dashboard, which has no
+ *  API: this stands in for that page. The account is Stripe's default until the page first changes it (the same default
+ *  GET /v1/account answers); a hash is merged into what the account holds, as an update merges it. */
+export declare function account(ctx: HandlerContext): Promise<Response>;
+/** Time's events, sent when a caller drives them (a runner's drainer): what time settled on each account is written —
+ *  payouts whose arrival date came (pending → paid, sent as payout.paid) and funds that came due (pending → available),
+ *  for which the account is sent one balance.available ("Occurs whenever your Stripe balance has been updated (e.g., when
+ *  a charge is available to be paid out)", docs.stripe.com/api/events/types) carrying its Balance, when an entry that
+ *  settled adds to it ("This event is not fired for negative transactions", the same page); a connected account's
+ *  events go to Connect endpoints. A read already sees these moves; the drain is what makes Stripe's events about them
+ *  arrive. Answers what it sent. */
+export declare function drain(ctx: HandlerContext): Promise<Response>;
+/** POST /_twin/app-credentials: the platform's API keys as the dashboard's API keys page shows them, a secret key and a
+ *  publishable key (`sk_test_…`, `pk_test_…`), held by their SHA-256, and the signing secrets its webhook endpoints
+ *  are made with. The runtime issues them to a World's applications at every boot (the descriptor's credentialDoor), so
+ *  the answer is the same each time: the account's one pair of keys, made the first time. Where the documentation
+ *  stops: the keys' length and alphabet after the prefix. */
+export declare function appCredentials(ctx: HandlerContext): Promise<Response>;
+/** POST /_twin/webhook-endpoints {url, events, connect?}: an endpoint added on the Dashboard's Webhooks page, the events
+ *  it takes, signed with the secret the World's application is issued (./doors.ts `appCredentials`): the twin's
+ *  decision, since Stripe mints an endpoint's secret and lets no one choose one. */
+export declare function webhookEndpoints(ctx: HandlerContext): Promise<Response>;