@volter/twin-stripe 0.1.2 → 2.0.1

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

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const products: Record<string, Semantics>;

package/dist/src/semantics/products.js

@@ -0,0 +1,140 @@
+import { asBool } from "../stripe-twin.js";
+import { at, created, fail, kept, list, newest, where } from "./shared.js";
+const productMissing = (ctx, id) => fail(ctx, `No such product: '${id}'`, 404, 'resource_missing');
+const createProduct = async (ctx) => ctx.reply(await created(ctx, 'product', ctx.params, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: ctx.now() }));
+const listProducts = async (ctx) => list(ctx, 'product', where(ctx, newest(ctx, 'product'), {
+    active: (p, v) => asBool(p.active) === asBool(v),
+    ids: (p, v) => (Array.isArray(v) ? v.map(String).includes(String(p.id)) : String(p.id) === String(v)),
+}));
+// a product with prices cannot be deleted; Stripe says to deactivate it instead
+/** A product deleted while it has prices: "Deleting a product is only possible if it has no prices associated with it"
+ *  (docs.stripe.com/api/products/delete). */
+function pricedProductRefused(ctx) {
+    return fail(ctx, 'You cannot delete the product because it has one or more prices. Deactivate the product instead.', 400, 'resource_already_exists');
+}
+const deleteProduct = async (ctx) => {
+    const id = at(ctx, 'id');
+    if (!ctx.get('product', id))
+        return productMissing(ctx, id);
+    if (ctx.rows('price').some((p) => p.product === id))
+        return pricedProductRefused(ctx);
+    await ctx.write('product', id, { deleted: true }, 'product.delete');
+    return ctx.reply({ id, object: 'product', deleted: true });
+};
+// ── features: an entitlements feature granted to a product, at most once ──
+/** A feature attached to a product that already has it. */
+function alreadyAttached(ctx) {
+    return fail(ctx, 'This feature is already attached to the product.', 400, 'resource_already_exists');
+}
+const attachFeature = async (ctx) => {
+    const product = at(ctx, 'product');
+    if (!ctx.get('product', product))
+        return productMissing(ctx, product);
+    const feature = typeof ctx.params.entitlement_feature === 'string' ? ctx.params.entitlement_feature : '';
+    if (!feature)
+        return fail(ctx, 'Missing required param: entitlement_feature.', 400, 'parameter_missing');
+    const feat = ctx.get('entitlements_feature', feature);
+    if (!feat)
+        return fail(ctx, `No such feature: '${feature}'`, 400, 'resource_missing');
+    if (ctx.rowsRaw('product_feature').some((pf) => pf._product === product && pf._feature === feature))
+        return alreadyAttached(ctx);
+    // Stripe answers the feature itself as the product feature's entitlement_feature (docs.stripe.com/api/product-feature/object)
+    return ctx.reply(await created(ctx, 'product_feature', { _product: product, _feature: feature }, {
+        livemode: false,
+        entitlement_feature: { id: feature, object: 'entitlements.feature', name: feat.name, lookup_key: feat.lookup_key, active: feat.active, metadata: feat.metadata ?? {}, livemode: false },
+    }));
+};
+const features = async (ctx) => {
+    const product = at(ctx, 'product');
+    if (!ctx.get('product', product))
+        return productMissing(ctx, product);
+    return list(ctx, 'product_feature', newest(ctx, 'product_feature').filter((pf) => kept(ctx, 'product_feature', pf, '_product') === product));
+};
+const productFeature = (ctx) => {
+    const pf = ctx.get('product_feature', at(ctx, 'id'));
+    // the product a feature is attached to is its address, not a field Stripe answers
+    return pf && kept(ctx, 'product_feature', pf, '_product') === at(ctx, 'product') ? pf : undefined;
+};
+const featureMissing = (ctx) => fail(ctx, `No such product feature: '${at(ctx, 'id')}'`, 404, 'resource_missing');
+const feature = async (ctx) => {
+    const pf = productFeature(ctx);
+    return pf ? ctx.reply(pf) : featureMissing(ctx);
+};
+const detachFeature = async (ctx) => {
+    if (!productFeature(ctx))
+        return featureMissing(ctx);
+    const id = at(ctx, 'id');
+    // when it came off the product: a subscription keeps it until its next period (semantics/entitlements.ts)
+    await ctx.write('product_feature', id, { deleted: true, _removed_at: Number(ctx.now()) }, 'product_feature.delete');
+    return ctx.reply({ id, object: 'product_feature', deleted: true });
+};
+// ── prices ──
+/** A tiered price: tiers_mode and tiers, each tier with up_to and a unit or flat amount; no single unit_amount, and
+ *  the last tier's up_to null (∞) (docs.stripe.com/products-prices/pricing-models#tiered-pricing). */
+async function tieredPrice(ctx, params) {
+    const mode = typeof params.tiers_mode === 'string' ? params.tiers_mode : '';
+    if (mode !== 'graduated' && mode !== 'volume')
+        return fail(ctx, 'Missing required param: tiers_mode (graduated or volume).', 400, 'parameter_missing');
+    const rawTiers = Array.isArray(params.tiers) ? params.tiers : [];
+    if (rawTiers.length === 0)
+        return fail(ctx, 'Missing required param: tiers.', 400, 'parameter_missing');
+    const tiers = rawTiers.map((t) => {
+        const upToRaw = t.up_to;
+        return {
+            up_to: upToRaw === 'inf' || upToRaw === undefined || upToRaw === null ? null : Math.trunc(Number(upToRaw)),
+            unit_amount: t.unit_amount !== undefined ? Math.trunc(Number(t.unit_amount)) : null,
+            unit_amount_decimal: t.unit_amount !== undefined ? String(Math.trunc(Number(t.unit_amount))) : null,
+            flat_amount: t.flat_amount !== undefined ? Math.trunc(Number(t.flat_amount)) : null,
+            flat_amount_decimal: t.flat_amount !== undefined ? String(Math.trunc(Number(t.flat_amount))) : null,
+        };
+    });
+    if (tiers.some((t) => t.unit_amount === null && t.flat_amount === null))
+        return fail(ctx, 'Each tier must specify a unit_amount or flat_amount.', 400, 'parameter_invalid_empty');
+    const { tiers: _t, ...rest } = params;
+    return ctx.reply(await created(ctx, 'price', { ...rest, billing_scheme: 'tiered', tiers_mode: mode, tiers, unit_amount: null }, { active: true, livemode: false, type: rest.recurring ? 'recurring' : 'one_time', metadata: {} }));
+}
+const createPrice = async (ctx) => {
+    const params = ctx.params;
+    // the product must exist
+    const product = typeof params.product === 'string' ? params.product : '';
+    if (!product || !ctx.get('product', product))
+        return fail(ctx, `No such product: '${product}'`, 400, 'resource_missing');
+    // a tiered price needs tiers_mode and tiers, each tier with up_to and a unit or flat amount; it
+    // has no single unit_amount, and its last tier's up_to is null (∞)
+    const scheme = typeof params.billing_scheme === 'string' ? params.billing_scheme : 'per_unit';
+    if (scheme === 'tiered')
+        return tieredPrice(ctx, params);
+    // a price that recurs is billed by subscriptions; any other is paid once. Its recurring block answers what the create
+    // left out as Stripe does: `usage_type` "Defaults to `licensed`", and the create example's answer
+    // (docs.stripe.com/api/prices/create) carries `"interval_count": 1, "trial_period_days": null`; a meter only a metered
+    // price names
+    if (params.recurring && typeof params.recurring === 'object') {
+        const r = params.recurring;
+        params.recurring = { ...r, interval_count: r.interval_count !== undefined ? Math.trunc(Number(r.interval_count)) : 1, usage_type: r.usage_type ?? 'licensed', trial_period_days: r.trial_period_days !== undefined ? Math.trunc(Number(r.trial_period_days)) : null, meter: r.meter ?? null };
+    }
+    return ctx.reply(await created(ctx, 'price', params, { active: true, livemode: false, billing_scheme: 'per_unit', type: params.recurring ? 'recurring' : 'one_time', metadata: {} }));
+};
+// `type` is not stored (it collides with the tree's discriminator), so `recurring` stands for it
+const listPrices = async (ctx) => list(ctx, 'price', where(ctx, newest(ctx, 'price'), {
+    active: (p, v) => asBool(p.active) === asBool(v),
+    product: (p, v) => p.product === v,
+    currency: (p, v) => p.currency === v,
+    type: (p, v) => (v === 'recurring' ? !!p.recurring : !p.recurring),
+    lookup_keys: (p, v) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String(p.lookup_key)),
+}));
+const retrievePrice = async (ctx) => {
+    const p = ctx.get('price', at(ctx, 'price'));
+    return p ? ctx.reply(p) : fail(ctx, `No such price: '${at(ctx, 'price')}'`, 404, 'resource_missing');
+};
+export const products = {
+    PostProducts: createProduct,
+    GetProducts: listProducts,
+    DeleteProductsId: deleteProduct,
+    PostProductsProductFeatures: attachFeature,
+    GetProductsProductFeatures: features,
+    GetProductsProductFeaturesId: feature,
+    DeleteProductsProductFeaturesId: detachFeature,
+    PostPrices: createPrice,
+    GetPrices: listPrices,
+    GetPricesPrice: retrievePrice,
+};

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

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const radar: Record<string, Semantics>;

package/dist/src/semantics/radar.js

@@ -0,0 +1,83 @@
+import { at, created, fail, list, newest } from "./shared.js";
+const approve = async (ctx) => {
+    const id = at(ctx, 'review');
+    const r = ctx.get('review', id);
+    if (!r)
+        return fail(ctx, `No such review: '${id}'`, 404, 'resource_missing');
+    const refused = ctx.legal('review', 'open', 'PostReviewsReviewApprove', r.open === true, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    return ctx.reply(await ctx.write('review', id, { open: false, closed_reason: 'approved', reason: 'approved' }, 'review.closed'));
+};
+const VL = 'radar.value_list';
+const VLI = 'radar.value_list_item';
+const listMissing = (ctx, id, status = 404) => fail(ctx, `No such radar value list: '${id}'`, status, 'resource_missing');
+const createList = async (ctx) => {
+    const params = ctx.params;
+    if (params.alias === undefined || params.alias === '')
+        return fail(ctx, 'Missing required param: alias.', 400, 'parameter_missing');
+    if (params.name === undefined || params.name === '')
+        return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
+    const made = await created(ctx, VL, params, {
+        item_type: typeof params.item_type === 'string' ? params.item_type : 'string', livemode: false, metadata: {},
+        created_by: 'twin', list_items: { object: 'list', data: [], has_more: false, url: '' },
+    });
+    await syncItems(ctx, String(made.id));
+    return ctx.reply(ctx.get(VL, String(made.id)));
+};
+/** A value list's list_items, "List of items contained within this value list" (the served spec), kept in step with
+ *  its items, at the address the fixture names (/v1/radar/value_list_items?value_list=…). */
+async function syncItems(ctx, listId) {
+    const data = newest(ctx, VLI).filter((i) => i.value_list === listId);
+    await ctx.write(VL, listId, { list_items: { object: 'list', data, has_more: false, url: `/v1/radar/value_list_items?value_list=${listId}` } }, 'radar.value_list.items_synced');
+}
+const updateList = async (ctx) => {
+    const id = at(ctx, 'value_list');
+    if (!ctx.row(VL, id, { withDeleted: true }))
+        return listMissing(ctx, id);
+    return ctx.reply(await ctx.write(VL, id, ctx.params, 'radar.value_list.updated'));
+};
+const deleteList = async (ctx) => {
+    const id = at(ctx, 'value_list');
+    if (!ctx.row(VL, id, { withDeleted: true }))
+        return listMissing(ctx, id);
+    await ctx.write(VL, id, { deleted: true }, 'radar.value_list.deleted');
+    return ctx.reply({ id, object: 'radar.value_list', deleted: true });
+};
+const addItem = async (ctx) => {
+    const listId = typeof ctx.params.value_list === 'string' ? ctx.params.value_list : '';
+    if (!listId)
+        return fail(ctx, 'Missing required param: value_list.', 400, 'parameter_missing');
+    if (!ctx.row(VL, listId, { withDeleted: true }))
+        return listMissing(ctx, listId, 400);
+    if (ctx.params.value === undefined || ctx.params.value === '')
+        return fail(ctx, 'Missing required param: value.', 400, 'parameter_missing');
+    const item = await created(ctx, VLI, { value_list: listId, value: ctx.params.value }, { livemode: false, created_by: 'twin' });
+    await syncItems(ctx, listId);
+    return ctx.reply(item);
+};
+const items = async (ctx) => {
+    const listId = typeof ctx.params.value_list === 'string' ? ctx.params.value_list : '';
+    if (!listId)
+        return fail(ctx, 'Missing required param: value_list.', 400, 'parameter_missing');
+    return list(ctx, VLI, newest(ctx, VLI).filter((i) => i.value_list === listId));
+};
+const removeItem = async (ctx) => {
+    const id = at(ctx, 'item');
+    const was = ctx.row(VLI, id, { withDeleted: true });
+    if (!was)
+        return fail(ctx, `No such radar value list item: '${id}'`, 404, 'resource_missing');
+    await ctx.write(VLI, id, { deleted: true }, 'radar.value_list_item.deleted');
+    if (typeof was.value_list === 'string' && ctx.get(VL, was.value_list))
+        await syncItems(ctx, was.value_list);
+    return ctx.reply({ id, object: 'radar.value_list_item', deleted: true });
+};
+export const radar = {
+    PostReviewsReviewApprove: approve,
+    PostRadarValueLists: createList,
+    PostRadarValueListsValueList: updateList,
+    DeleteRadarValueListsValueList: deleteList,
+    PostRadarValueListItems: addItem,
+    GetRadarValueListItems: items,
+    DeleteRadarValueListItemsItem: removeItem,
+};

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

@@ -0,0 +1,9 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+export declare function refundCharge(ctx: SemanticsContext, charge: Row, params: Row): Promise<Response>;
+/** Time's settling of held refunds, caught up to the World's clock: each refund held for want of balance, oldest first,
+ *  is made at the first moment the account's available balance covers it (the funds that come due then), its debit
+ *  written then, as `refund.updated`. Where the documentation stops and the twin decides: a held refund is made the
+ *  moment the balance covers it. */
+export declare function settleHeldRefunds(ctx: SemanticsContext): Promise<void>;
+export declare const refunds: Record<string, Semantics>;

package/dist/src/semantics/refunds.js

@@ -0,0 +1,195 @@
+import { releaseAuthorization } from "./charges.js";
+import { actingAccount, availableAt, fundsDueBetween, settleRefund, settleTransferReversal } from "./ledger.js";
+import { asBool } from "../stripe-twin.js";
+import { at, at_, created, fail, newest, refundDestination } from "./shared.js";
+// the reasons a caller may give; `expired_uncaptured_charge` is Stripe's own
+const REFUND_REASONS = new Set(['duplicate', 'fraudulent', 'requested_by_customer']);
+/**
+ * Create a refund and land it on its charge. An omitted amount is the whole remaining balance. The
+ * charge's write records `charge.refunded`, the event Stripe sends carrying the charge's new totals;
+ * `refunded` is true only at the full amount.
+ */
+/** A reason Stripe does not take (docs.stripe.com/api/refunds/create#create_refund-reason). */
+function badReason(ctx) {
+    return fail(ctx, `Invalid refund reason: must be one of ${[...REFUND_REASONS].join(', ')}.`, 400, 'parameter_invalid_string_enum');
+}
+/** A bank-transfer payment refunded with origin=customer_balance goes back to the cash balance
+ *  (docs.stripe.com/payments/customer-balance/refunding). */
+async function backToCashBalance(ctx, customer, currency, amount, refundId) {
+    const before = ctx.rows('customer_cash_balance_transaction').filter((t) => t.customer === customer && String(t.currency) === currency).reduce((n, t) => n + (Number(t.net_amount) || 0), 0);
+    await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'refunded_from_payment', net_amount: amount, ending_balance: before + amount, refunded_from_payment: { refund: refundId }, livemode: false });
+}
+/** A capture=false charge's refund, which releases its whole authorization (see the header). */
+async function refundUncaptured(ctx, charge, amount, remaining, params) {
+    if (amount < remaining)
+        return fail(ctx, `Charge ${String(charge.id)} is uncaptured: refunding it releases the whole authorization (${remaining}).`, 400, 'amount_too_small');
+    const { reason, metadata } = params;
+    return ctx.reply(await releaseAuthorization(ctx, charge, ctx.call.operation.id, { ...(reason !== undefined ? { reason } : {}), ...(metadata !== undefined ? { metadata } : {}) }));
+}
+export async function refundCharge(ctx, charge, params) {
+    const chargeId = String(charge.id);
+    const total = Number(charge.amount) || 0;
+    const already = Number(charge.amount_refunded) || 0;
+    const remaining = Math.max(0, total - already);
+    const amount = params.amount === undefined ? remaining : Math.trunc(Number(params.amount));
+    if (!Number.isFinite(amount) || amount <= 0)
+        return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+    if (amount > remaining)
+        return fail(ctx, `Refund amount (${amount}) is greater than unrefunded amount on charge (${remaining}).`, 400, 'amount_too_large');
+    if (params.reason !== undefined && !REFUND_REASONS.has(String(params.reason)))
+        return badReason(ctx);
+    // an authorization is released, never refunded out of the balance: a PaymentIntent's by cancelling the intent, a
+    // capture=false charge's by its refund (refundUncaptured)
+    if (charge.captured === false && typeof charge.payment_intent === 'string')
+        return fail(ctx, `Charge ${chargeId} is uncaptured and can't be refunded directly; cancel its PaymentIntent (${charge.payment_intent}) to release the authorization.`, 400, 'payment_intent_unexpected_state');
+    if (charge.captured === false)
+        return refundUncaptured(ctx, charge, amount, remaining, params);
+    const refunded = already + amount;
+    // the refund that takes the rest refunds the charge: the charge machine's move under this operation
+    if (refunded >= total && charge.refunded !== true) {
+        const refused = ctx.legal('charge', 'refunded', ctx.call.operation.id, 'false', 'true', chargeId);
+        if (refused)
+            return ctx.refuse(refused);
+    }
+    // a refund has no `livemode` field; it debits the balance at once
+    const refundId = ctx.mint('refund');
+    const currency = String(charge.currency ?? 'usd');
+    const pi = typeof charge.payment_intent === 'string' ? ctx.get('payment_intent', charge.payment_intent) : undefined;
+    const byTransfer = (pi?.payment_method_types ?? []).includes('customer_balance');
+    const toCashBalance = byTransfer && params.origin === 'customer_balance';
+    const awaitsBank = byTransfer && !toCashBalance;
+    const now = Number(ctx.now());
+    const customer = typeof charge.customer === 'string' ? charge.customer : typeof pi?.customer === 'string' ? pi.customer : undefined;
+    const emailTo = typeof params.instructions_email === 'string' ? params.instructions_email : (customer ? ctx.get('customer', customer)?.email : undefined) ?? null;
+    // "Refunds use your available Stripe balance (not including pending amounts). If your available balance doesn't
+    // cover the amount of the refund, Stripe holds the refund as pending for card transactions ... until your Stripe
+    // balance becomes sufficient" (docs.stripe.com/refunds): the refund waits, moving no money, until the balance covers
+    // it (settleHeldRefunds). Where the documentation stops and the twin decides: a refund of another payment method
+    // short of balance is not modelled (Stripe fails it); the twin makes it as a card's.
+    const account = actingAccount(ctx);
+    const isCard = charge.payment_method_details?.type === 'card';
+    const held = !awaitsBank && !toCashBalance && isCard && availableAt(ctx, account, currency, now) < amount;
+    if (held)
+        ctx.legal('refund', 'status', ctx.call.operation.id, 'succeeded', 'pending', refundId);
+    const bt = awaitsBank || held ? null : await settleRefund(ctx, refundId, amount, currency);
+    if (toCashBalance && customer)
+        await backToCashBalance(ctx, customer, currency, amount, refundId);
+    const { reverse_transfer: reverseTransfer, refund_application_fee: refundFee, instructions_email: _email, origin: _origin, ...stored } = params;
+    const share = (whole) => Math.round((whole * amount) / (total || 1));
+    let transferReversal = null;
+    const transfer = typeof charge.transfer === 'string' ? ctx.get('transfer', charge.transfer) : undefined;
+    if (reverseTransfer !== undefined && asBool(reverseTransfer) && transfer) {
+        const back = Math.min(share(Number(transfer.amount) || 0), (Number(transfer.amount) || 0) - (Number(transfer.amount_reversed) || 0));
+        const trr = await created(ctx, 'transfer_reversal', { amount: back, currency, transfer: transfer.id }, { balance_transaction: null, destination_payment_refund: null, source_refund: refundId, metadata: {} });
+        const trrBt = await settleTransferReversal(ctx, String(trr.id), back, currency, String(transfer.destination));
+        const reversal = await ctx.write('transfer_reversal', String(trr.id), { balance_transaction: trrBt }, 'transfer_reversal.updated');
+        const reversed = (Number(transfer.amount_reversed) || 0) + back;
+        const list = transfer.reversals ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+        const data = [...((list.data ?? [])), reversal];
+        await ctx.write('transfer', String(transfer.id), { amount_reversed: reversed, reversed: reversed >= (Number(transfer.amount) || 0), reversals: { ...list, data, total_count: data.length, url: `/v1/transfers/${String(transfer.id)}/reversals` } }, 'transfer.reversed');
+        transferReversal = String(trr.id);
+    }
+    const fee = typeof charge.application_fee === 'string' ? ctx.get('application_fee', charge.application_fee) : undefined;
+    if (refundFee !== undefined && asBool(refundFee) && fee) {
+        const feeTotal = Number(fee.amount) || 0;
+        const back = Math.min(share(feeTotal), feeTotal - (Number(fee.amount_refunded) || 0));
+        const done = (Number(fee.amount_refunded) || 0) + back;
+        if (!(done >= feeTotal && fee.refunded !== true && ctx.legal('application_fee', 'refunded', ctx.call.operation.id, 'false', 'true', String(fee.id)))) {
+            const fr = await created(ctx, 'fee_refund', { amount: back, currency, fee: fee.id }, { balance_transaction: null, metadata: {} });
+            const list = fee.refunds ?? { object: 'list', data: [], has_more: false, total_count: 0 };
+            const data = [...((list.data ?? [])), fr];
+            await ctx.write('application_fee', String(fee.id), { amount_refunded: done, refunded: done >= feeTotal, refunds: { ...list, data, total_count: data.length, url: `/v1/application_fees/${String(fee.id)}/refunds` } }, 'application_fee.refunded');
+        }
+    }
+    const body = await created(ctx, 'refund', {
+        ...stored, id: refundId, charge: chargeId, amount, currency, transfer_reversal: transferReversal,
+        ...(typeof charge.payment_intent === 'string' ? { payment_intent: charge.payment_intent } : {}),
+    }, {
+        status: awaitsBank ? 'requires_action' : held ? 'pending' : 'succeeded', metadata: {}, reason: null, receipt_number: null,
+        ...(held ? { pending_reason: 'insufficient_funds', _account: account ?? null } : {}),
+        balance_transaction: bt, source_transfer_reversal: null,
+        // a bank transfer's refund goes to the customer's bank (a us_bank_transfer) or back to its cash balance
+        // (customer_cash_balance): "If this is a `us_bank_transfer` refund, this hash contains the transaction specific details",
+        // "If this is a `customer_cash_balance` refund ..." (docs.stripe.com/api/refunds/object, destination_details)
+        ...(byTransfer
+            ? { destination_details: toCashBalance ? { type: 'customer_cash_balance', customer_cash_balance: {} } : { type: 'us_bank_transfer', us_bank_transfer: { reference: null, reference_status: null } } }
+            : refundDestination(charge, 'refund')),
+        ...(awaitsBank ? { next_action: { type: 'display_details', display_details: { email_sent: { email_sent_at: now, email_sent_to: emailTo }, expires_at: now + 30 * 86_400 } } } : {}),
+    });
+    await ctx.write('charge', chargeId, { amount_refunded: refunded, refunded: refunded >= total }, 'charge.refunded');
+    return ctx.reply(body);
+}
+/** Time's settling of held refunds, caught up to the World's clock: each refund held for want of balance, oldest first,
+ *  is made at the first moment the account's available balance covers it (the funds that come due then), its debit
+ *  written then, as `refund.updated`. Where the documentation stops and the twin decides: a held refund is made the
+ *  moment the balance covers it. */
+export async function settleHeldRefunds(ctx) {
+    const now = Number(ctx.now());
+    const heldRefunds = ctx.rowsRaw('refund').filter((r) => r.status === 'pending' && r.pending_reason === 'insufficient_funds').sort((a, b) => Number(a.created) - Number(b.created));
+    for (const r of heldRefunds) {
+        const account = typeof r._account === 'string' ? r._account : undefined;
+        const currency = String(r.currency ?? 'usd');
+        const amount = Number(r.amount) || 0;
+        const when = [Number(r.created), ...fundsDueBetween(ctx, account, currency, Number(r.created), now)].find((t) => availableAt(ctx, account, currency, t) >= amount);
+        if (when === undefined)
+            continue;
+        const c = await at_(ctx)(when);
+        c.legal('refund', 'status', ctx.call.operation.id, 'pending', 'succeeded', String(r.id), 'vendor');
+        const bt = await settleRefund(c, String(r.id), amount, currency, account ?? null);
+        await c.write('refund', String(r.id), { status: 'succeeded', pending_reason: null, balance_transaction: bt }, 'refund.updated');
+    }
+}
+/** The charge a refund aims at: named directly, or reached through its PaymentIntent. */
+function target(ctx) {
+    const chargeId = typeof ctx.params.charge === 'string' ? ctx.params.charge : '';
+    const piId = typeof ctx.params.payment_intent === 'string' ? ctx.params.payment_intent : '';
+    if (!chargeId && !piId)
+        return fail(ctx, 'One of `charge` or `payment_intent` is required.', 400, 'parameter_missing');
+    if (chargeId)
+        return ctx.get('charge', chargeId) ?? fail(ctx, `No such charge: '${chargeId}'`, 404, 'resource_missing');
+    const pi = ctx.get('payment_intent', piId);
+    if (!pi)
+        return fail(ctx, `No such payment_intent: '${piId}'`, 404, 'resource_missing');
+    const latest = typeof pi.latest_charge === 'string' ? pi.latest_charge : undefined;
+    const ch = (latest ? ctx.get('charge', latest) : undefined) ?? newest(ctx, 'charge').find((c) => c.payment_intent === piId);
+    return ch ?? fail(ctx, `This PaymentIntent does not have a successful charge to refund. Its status is ${String(pi.status)}.`, 400, 'payment_intent_unexpected_state');
+}
+const create = async (ctx) => {
+    const ch = target(ctx);
+    return ch instanceof Response ? ch : refundCharge(ctx, ch, ctx.params);
+};
+const refundMissing = (ctx, id) => fail(ctx, `No such refund: '${id}'`, 404, 'resource_missing');
+const retrieve = async (ctx) => {
+    const r = ctx.get('refund', at(ctx, 'refund'));
+    return r ? ctx.reply(r) : refundMissing(ctx, at(ctx, 'refund'));
+};
+// a canceled pending refund gives its money back to the charge: pending funds were already taken out
+const cancel = async (ctx) => {
+    const id = at(ctx, 'refund');
+    const r = ctx.get('refund', id);
+    if (!r)
+        return refundMissing(ctx, id);
+    const refused = ctx.legal('refund', 'status', 'PostRefundsRefundCancel', r.status, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    // next_action says what a refund "needs to continue processing" "If the refund has a status of requires_action"
+    // (docs.stripe.com/api/refunds/object): a canceled one needs nothing
+    const canceled = await ctx.write('refund', id, { status: 'canceled', next_action: null }, 'refund.updated');
+    const chargeId = typeof r.charge === 'string' ? r.charge : '';
+    const ch = chargeId ? ctx.get('charge', chargeId) : undefined;
+    if (ch) {
+        const total = Number(ch.amount) || 0;
+        const back = Math.max(0, (Number(ch.amount_refunded) || 0) - (Number(r.amount) || 0));
+        const refunded = back > 0 && back >= total;
+        // a charge the canceled refund had fully refunded is no longer refunded
+        if (refunded !== (ch.refunded === true))
+            ctx.legal('charge', 'refunded', 'PostRefundsRefundCancel', String(ch.refunded === true), String(refunded), chargeId);
+        await ctx.write('charge', chargeId, { amount_refunded: back, refunded }, 'charge.update');
+    }
+    return ctx.reply(canceled);
+};
+export const refunds = {
+    PostRefunds: create,
+    GetRefundsRefund: retrieve,
+    PostRefundsRefundCancel: cancel,
+};

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

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