@volter/twin-stripe 2.0.37 → 3.0.0

package/src/semantics/refunds.ts

@@ -1,218 +1,15 @@
-// Refund semantics. A refund always names what it took money out of and lands there: a refund
-// naming nothing, an id nobody minted, or more than the charge has left is refused as Stripe
-// refuses it. The machine in ../manifest.ts says only a refund waiting on the customer
-// (requires_action) may be canceled. List and update are the derived core's.
-//
-// Refunding a destination charge can take back the connected account's share (reverse_transfer: a reversal of the
-// charge's transfer, in proportion to the refund) and the platform's (refund_application_fee: a refund of the
-// application fee, in proportion) (docs.stripe.com/api/refunds/create#create_refund-reverse_transfer,
-// docs.stripe.com/connect/destination-charges#issue-refunds). Where the documentation stops and the twin decides: the
-// twin's destination charge transfers the amount less the fee (the fee is kept back rather than collected from the
-// connected account), so a fee refund moves no money of its own; the reversal and the refund settle both shares.
-//
-// A payment made by bank transfer (from the customer's cash balance) is refunded to the customer's bank account: Stripe
-// emails the customer (instructions_email, else the customer's email) for their bank details and the refund waits in
-// requires_action, moving no money, until they answer; only then can it still be canceled. With origin=customer_balance
-// it goes back to the cash balance at once (docs.stripe.com/payments/customer-balance/refunding,
-// docs.stripe.com/api/refunds/cancel). Where the documentation stops and the twin decides: the customer never answers
-// the email in the World, and its link expires 30 days on.
-//
-// An uncaptured charge holds an authorization, not money. A PaymentIntent's is not refunded: "the charge attached to the
-// PaymentIntent remains uncaptured and can't be refunded directly. You must cancel the PaymentIntent"
-// (docs.stripe.com/refunds), which releases it (charges.ts cancelAuthorization). A charge made with capture=false is
-// released by its refund, as its authorization would be "automatically refunded if uncaptured" (spec/openapi.json.gz,
-// `capture_before`): refunded in full, no balance moved, and its capture refused afterwards. Where the documentation
-// stops and the twin decides: the refusal's code (payment_intent_unexpected_state) and wording, and that a refund of a
-// capture=false charge releases the whole authorization, so an `amount` short of it is refused.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { releaseAuthorization } from './charges.ts';
-import { actingAccount, availableAt, fundsDueBetween, settleRefund, settleTransferReversal } from './ledger.ts';
-import { asBool } from '../stripe-twin.ts';
-import { at, at_, created, fail, newest, refundDestination, type Row } from './shared.ts';
+// Stripe's refunds operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { at, refundCharge, refundMissing, target } from './shared.ts';
 
-// 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: SemanticsContext): Response {
-  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: SemanticsContext, customer: string, currency: string, amount: number, refundId: string): Promise<void> {
-  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: SemanticsContext, charge: Row, amount: number, remaining: number, params: Row): Promise<Response> {
-  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: SemanticsContext, charge: Row, params: Row): Promise<Response> {
-  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 as unknown[] | undefined) ?? []).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 as Row | null | undefined)?.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: number): number => Math.round((whole * amount) / (total || 1));
-  let transferReversal: string | null = 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 as Row | undefined) ?? { object: 'list', data: [], has_more: false, total_count: 0 };
-    const data = [...(((list.data as unknown[]) ?? [])), 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 as Row | undefined) ?? { object: 'list', data: [], has_more: false, total_count: 0 };
-      const data = [...(((list.data as unknown[]) ?? [])), 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: SemanticsContext): Promise<void> {
-  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: SemanticsContext): Row | Response {
-  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');
+export async function GetRefundsRefund(ctx: HandlerContext): Promise<Response> {
+  const r = ctx.get('refund', at(ctx, 'refund'));
+  return r ? ctx.reply(r) : refundMissing(ctx, at(ctx, 'refund'));
 }
 
-const create: Semantics = async (ctx) => {
+export async function PostRefunds(ctx: HandlerContext): Promise<Response> {
   const ch = target(ctx);
   return ch instanceof Response ? ch : refundCharge(ctx, ch, ctx.params);
-};
-
-const refundMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such refund: '${id}'`, 404, 'resource_missing');
-
-const retrieve: Semantics = 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: Semantics = 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: Record<string, Semantics> = {
-  PostRefunds: create,
-  GetRefundsRefund: retrieve,
-  PostRefundsRefundCancel: cancel,
-};

package/src/semantics/setup_intents.ts

@@ -0,0 +1,45 @@
+// Stripe's setup_intents operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { SI } from '../engine/setup-intents.ts';
+import { asBool, microdepositsNextAction, mintClientSecret, requiresMicrodeposits, verifyMicrodeposits } from '../engine/stripe.ts';
+import { at, attachable, attachPaymentMethod, confirmOnly, created, fail, load, mergeUpdate, methodFromData, microdepositsAsked, mintMandate, send } from './shared.ts';
+
+export async function PostSetupIntents(ctx: HandlerContext): Promise<Response> {
+  // mandate_data and return_url each "can only be used with `confirm=true`" (the served spec; shared.ts confirmOnly)
+  const unconfirmed = confirmOnly(ctx, ['mandate_data', 'return_url'], asBool(ctx.params.confirm));
+  if (unconfirmed) return unconfirmed;
+  // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
+  const id = typeof ctx.params.id === 'string' && ctx.params.id ? ctx.params.id : ctx.mint(SI);
+  // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
+  const hasMethod = typeof ctx.params.payment_method === 'string' && ctx.params.payment_method !== '';
+  if (hasMethod) ctx.legal(SI, 'status', 'PostSetupIntents', 'requires_payment_method', 'requires_confirmation', id);
+  return ctx.reply(
+    // allowed_payment_method_types in the served version names the methods (docs.stripe.com/api/setup_intents/create)
+    await created(ctx, SI, { ...ctx.params, ...(Array.isArray(ctx.params.allowed_payment_method_types) ? { payment_method_types: ctx.params.allowed_payment_method_types.map(String) } : {}), id }, {
+      status: hasMethod ? 'requires_confirmation' : 'requires_payment_method', usage: 'off_session', client_secret: mintClientSecret(id, await ctx.secret(`client-secret:${id}`)), payment_method_types: ['card'],
+      next_action: null, latest_attempt: null, last_setup_error: null, livemode: false,
+    }),
+  );
+}
+
+// a bank account that needs micro-deposit verification waits in requires_action; anything else succeeds. The confirm's
+// payment_method_data and mandate_data are instructions, not fields of the SetupIntent.
+export async function PostSetupIntentsIntentConfirm(ctx: HandlerContext): Promise<Response> {
+  const loaded = load(ctx, 'PostSetupIntentsIntentConfirm');
+  if ('answer' in loaded) return loaded.answer;
+  const si = loaded.si;
+  const id = String(si.id);
+  const given = ctx.params;
+  const { payment_method_data: data, mandate_data: _mandate, ...fields } = given;
+  const made = await methodFromData(ctx, data);
+  const pm = made ?? (typeof ctx.params.payment_method === 'string' ? ctx.params.payment_method : typeof si.payment_method === 'string' ? si.payment_method : undefined);
+  if (si.status !== 'requires_action' && (requiresMicrodeposits(ctx.params, si) || microdepositsAsked(ctx, ctx.params, si, pm))) {
+    return ctx.reply(await ctx.write(SI, id, mergeUpdate(ctx, SI, id, { ...fields, ...(pm ? { payment_method: pm } : {}), status: 'requires_action', next_action: microdepositsNextAction() }), 'setup_intent.requires_action'));
+  }
+  // a setup for a customer saves the method to them (docs.stripe.com/payments/save-and-reuse): its payment method is attached
+  const customer = typeof si.customer === 'string' ? si.customer : undefined;
+  const saved = pm && customer && attachable(ctx, pm) && ctx.get('payment_method', pm)?.customer !== customer ? String((await attachPaymentMethod(ctx, pm, customer)).id) : pm;
+  return ctx.reply(await ctx.write(SI, id, mergeUpdate(ctx, SI, id, { ...fields, ...(saved ? { payment_method: saved } : {}), status: 'succeeded' }), 'setup_intent.confirm'));
+}
+