@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/semantics/customers.js

@@ -1,18 +1,28 @@
-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 { at, attachable, attachPaymentMethod, created, customerDiscount, customerMissing, expanded, fail, list, newest, redeemCoupon, search, where } 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)));
 }
-/** 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) => {
+// the payment methods attached to a customer (customers.listPaymentMethods), optionally by `type`
+export async function GetCustomersCustomerPaymentMethods(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);
+}
+export async function GetCustomersSearch(ctx) {
+    return search(ctx, 'customer');
+}
+export async function PostCustomers(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;
@@ -23,7 +33,8 @@ const create = async (ctx) => {
     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)
@@ -31,139 +42,10 @@ const create = async (ctx) => {
     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) => {
-    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) => {
+export async function PostCustomersCustomerBalanceTransactions(ctx) {
     const customer = at(ctx, 'customer');
     if (!ctx.get('customer', customer))
         return customerMissing(ctx, customer);
@@ -184,246 +66,4 @@ const createBalanceTransaction = async (ctx) => {
     // 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');
-    }
-    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' },
-    };
 }
-// 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/disputes.d.ts

@@ -1,2 +1,2 @@
-import type { Semantics } from '@volter/world-core';
-export declare const disputes: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetDisputesDispute(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/disputes.js

@@ -1,51 +1,5 @@
-import { asBool } from "../stripe-twin.js";
-import { settleDisputeWon } from "./ledger.js";
-import { at, fail } from "./shared.js";
-const disputeMissing = (ctx, id) => fail(ctx, `No such dispute: '${id}'`, 404, 'resource_missing');
-const retrieve = async (ctx) => {
+import { at, disputesDisputeMissing } from "./shared.js";
+export async function GetDisputesDispute(ctx) {
     const d = ctx.get('dispute', at(ctx, 'dispute'));
-    return d ? ctx.reply(d) : disputeMissing(ctx, at(ctx, 'dispute'));
-};
-const close = async (ctx) => {
-    const id = at(ctx, 'dispute');
-    const d = ctx.get('dispute', id);
-    if (!d)
-        return disputeMissing(ctx, id);
-    const refused = ctx.legal('dispute', 'status', 'PostDisputesDisputeClose', d.status, undefined, id);
-    if (refused)
-        return ctx.refuse(refused);
-    return ctx.reply(await ctx.write('dispute', id, { status: 'lost' }, 'dispute.close'));
-};
-/** Evidence staged without submitting it (submit=false), or on a dispute already under review or decided. */
-async function keepEvidence(ctx, id, fields) {
-    return ctx.reply(await ctx.write('dispute', id, fields, 'dispute.update'));
+    return d ? ctx.reply(d) : disputesDisputeMissing(ctx, at(ctx, 'dispute'));
 }
-const update = async (ctx) => {
-    const id = at(ctx, 'dispute');
-    const d = ctx.get('dispute', id);
-    if (!d)
-        return disputeMissing(ctx, id);
-    const params = ctx.params;
-    const given = params.evidence && typeof params.evidence === 'object' ? params.evidence : {};
-    const evidence = { ...(d.evidence ?? {}), ...given };
-    const fields = { evidence, ...(params.metadata && typeof params.metadata === 'object' ? { metadata: { ...(d.metadata ?? {}), ...params.metadata } } : {}) };
-    const submit = params.submit === undefined ? true : asBool(params.submit);
-    const review = d.status === 'warning_needs_response' ? 'warning_under_review' : 'under_review';
-    if (!submit || ctx.legal('dispute', 'status', 'PostDisputesDispute', d.status, review, id))
-        return keepEvidence(ctx, id, fields);
-    const details = d.evidence_details ?? {};
-    let body = await ctx.write('dispute', id, { ...fields, status: review, evidence_details: { ...details, has_evidence: true, submission_count: (Number(details.submission_count) || 0) + 1 } }, 'charge.dispute.updated');
-    const text = String(evidence.uncategorized_text ?? '');
-    const decided = review === 'under_review' ? (text.includes('winning_evidence') ? 'won' : text.includes('losing_evidence') ? 'lost' : undefined) : undefined;
-    if (decided && !ctx.legal('dispute', 'status', 'PostDisputesDispute', review, decided, id, 'vendor')) {
-        const bt = decided === 'won' ? await settleDisputeWon(ctx, id, Number(d.amount) || 0, String(d.currency ?? 'usd')) : undefined;
-        const kept = (ctx.get('dispute', id)?.balance_transactions ?? []);
-        body = await ctx.write('dispute', id, { status: decided, ...(bt ? { balance_transactions: [...kept, ctx.get('balance_transaction', bt) ?? bt] } : {}) }, 'charge.dispute.closed');
-    }
-    return ctx.reply(body);
-};
-export const disputes = {
-    GetDisputesDispute: retrieve,
-    PostDisputesDispute: update,
-    PostDisputesDisputeClose: close,
-};

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>;

package/dist/src/semantics/doors.js

@@ -0,0 +1,73 @@
+import { platformAccountDefault } from "../engine/connect.js";
+import { accountSettings, PLATFORM_ACCOUNT_ID } from "../engine/stripe.js";
+import { balanceBody, payDuePayouts, settleDueEntries } from "./shared.js";
+/** 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 async function account(ctx) {
+    const ex = ctx.get('account', PLATFORM_ACCOUNT_ID);
+    const given = ctx.params;
+    const { type: _t, settings: rawSettings, business_profile: rawProfile, ...rest } = given;
+    const { id: _id, ...base } = platformAccountDefault();
+    const fields = {
+        ...(ex ? {} : base),
+        ...rest,
+        settings: accountSettings(rawSettings, ex?.settings),
+        ...(rawProfile && typeof rawProfile === 'object' ? { business_profile: { ...(ex?.business_profile ?? {}), ...rawProfile } } : {}),
+    };
+    return ctx.reply(await ctx.write('account', PLATFORM_ACCOUNT_ID, fields, 'account.update'));
+}
+/** 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 async function drain(ctx) {
+    const accounts = [undefined, ...ctx.rows('account').map((a) => String(a.id)).filter((id) => id !== PLATFORM_ACCOUNT_ID)];
+    const delivered = [];
+    for (const account of accounts) {
+        for (const id of await payDuePayouts(ctx, account))
+            delivered.push({ type: 'payout.paid', id, ...(account ? { account } : {}) });
+        if ((await settleDueEntries(ctx, account)).some((t) => Number(t.net) > 0)) {
+            // the notice the event is sent for: the account's Balance, which has no id of its own (./events.ts renders it)
+            await ctx.write('_balance_notice', `${account ?? PLATFORM_ACCOUNT_ID}:${ctx.occurredAt}`, { account: account ?? null, balance: balanceBody(ctx, account) }, 'balance.available');
+            delivered.push({ type: 'balance.available', ...(account ? { account } : {}) });
+        }
+    }
+    return Response.json({ delivered });
+}
+/** 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. */
+// source: https://docs.stripe.com/keys "Publishable keys"
+export async function appCredentials(ctx) {
+    const secretKey = `sk_test_51${(await ctx.secret('stripe-platform-key:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 96)}`;
+    const publishableKey = `pk_test_51${(await ctx.secret('stripe-publishable-key:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 96)}`;
+    if (!ctx.rowsRaw('_platform_key').some((k) => k.id === 'secret:app' && k._sha256 === ctx.crypto.sha256(secretKey))) {
+        await ctx.record('_platform_key', { kind: 'secret', _sha256: ctx.crypto.sha256(secretKey), created: ctx.occurredAt, deleted: false }, 'secret:app');
+        await ctx.record('_platform_key', { kind: 'publishable', _sha256: ctx.crypto.sha256(publishableKey), created: ctx.occurredAt, deleted: false }, 'publishable:app');
+    }
+    // the signing secrets the application verifies its webhooks with, its account's and its Connect endpoint's: an
+    // endpoint made for it (the webhookEndpoints door) is signed with the one of its kind, so the two agree
+    return Response.json({ secret_key: secretKey, publishable_key: publishableKey, webhook_secret: await appEndpointSecret(ctx, false), connect_webhook_secret: await appEndpointSecret(ctx, true) }, { status: 201 });
+}
+/** The signing secret the World's application is issued for its account's endpoints, or for its Connect endpoint. */
+const appEndpointSecret = async (ctx, connect) => `whsec_${(await ctx.secret(connect ? 'stripe-webhook-secret:connect' : 'stripe-webhook-secret:app')).replace(/[^A-Za-z0-9]/g, '').slice(0, 32)}`;
+/** 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. */
+// source: https://docs.stripe.com/webhooks "register a webhook endpoint, Stripe pushes real-time data to it when"
+export async function webhookEndpoints(ctx) {
+    const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {});
+    if (typeof b.url !== 'string' || !/^https?:\/\//.test(b.url) || !Array.isArray(b.events) || !b.events.length)
+        return Response.json({ error: 'a url and its events are required' }, { status: 400 });
+    const connect = b.connect === true;
+    const id = ctx.mint('webhook_endpoint');
+    const secret = await appEndpointSecret(ctx, connect);
+    await ctx.write('webhook_endpoint', id, { id, object: 'webhook_endpoint', url: b.url, enabled_events: b.events.map(String), status: 'enabled', connect, livemode: false, metadata: {}, api_version: null, application: null, description: null, secret, created: Math.floor(Date.parse(ctx.occurredAt) / 1000) }, 'webhook_endpoint.create');
+    return Response.json({ id, secret }, { status: 201 });
+}

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

@@ -1,2 +1,2 @@
-import type { Semantics } from '@volter/world-core';
-export declare const entitlements: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetEntitlementsActiveEntitlements(ctx: HandlerContext): Promise<Response>;