@volter/twin-stripe 3.0.0 → 3.0.2

package/src/semantics/subscriptions.ts

@@ -1,17 +1,18 @@
 // Stripe's subscriptions 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 { deletedDiscount, type Row } from '../engine/common.ts';
-import { itemQuantity, keptAfter } from '../engine/renewals.ts';
-import { addBillingInterval, applyCouponDiscount, asBool, buildDiscount, buildSubscriptionItemsList, declineFor, mintClientSecret, nowUnix, priceAmount, resolveSubscriptionBillingInterval, resolveTrial, subscriptionCouponParam, subscriptionHasPrice, subscriptionItemEntries } from '../engine/stripe.ts';
+import { type Row } from '../engine/common.ts';
+import { keptAfter } from '../engine/renewals.ts';
+import { asBool, nowUnix, subscriptionCouponParam, subscriptionHasPrice, subscriptionItemEntries } from '../engine/stripe.ts';
 import { pauseCollection, SUB } from '../engine/subscriptions.ts';
-import { advanceBilling, applyItemChanges, applyTrialEnd, at, clockNow, collectSubscriptionInvoice, created, draftSubscriptionInvoice, expanded, fail, finalizedFields, finder, firstPaymentRefused, itemChangesRefused, list, mintCharge, newest, redeemCoupon, replacedDiscounts, search, spendOnceCoupon, storeItems, subMissing, trialEndBlocked, trialEndRefused, where } from './shared.ts';
-
+import { resourceView, advanceBilling, applyItemChanges, applyTrialEnd, at, clockNow, collectSubscriptionInvoice, expanded, itemChangesRefused, list, newest, redeemCoupon, replacedDiscounts, subMissing, trialEndBlocked, trialEndRefused, where } from './shared.ts';
+import { deletedDiscount } from '../engine/common.ts';
+import { fail } from './shared.ts';
 // canceling keeps the subscription, now canceled, stamped with when it was canceled and ended
 // (https://docs.stripe.com/api/subscriptions/object#subscription_object-canceled_at, #subscription_object-ended_at)
 export async function DeleteSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'subscription_exposed_id');
-  const sub = ctx.get(SUB, id);
+  const sub = resourceView(ctx, SUB, id);
   if (!sub) return subMissing(ctx, id);
   const refused = ctx.legal(SUB, 'status', 'DeleteSubscriptionsSubscriptionExposedId', sub.status, undefined, id);
   if (refused) return ctx.refuse(refused);
@@ -21,7 +22,7 @@ export async function DeleteSubscriptionsSubscriptionExposedId(ctx: HandlerConte
   // `"reason": "cancellation_requested"` (docs.stripe.com/api/subscriptions/cancel)
   const given = ctx.params.cancellation_details && typeof ctx.params.cancellation_details === 'object' ? (ctx.params.cancellation_details as Row) : {};
   const cancellation_details = { comment: given.comment ?? null, feedback: given.feedback ?? null, reason: 'cancellation_requested' };
-  return ctx.reply(await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel'));
+  return ctx.reply(ctx.expand(SUB, await ctx.write(SUB, id, { status: 'canceled', canceled_at: now, ended_at: now, cancellation_details }, 'subscription.cancel')));
 }
 
 export async function GetSubscriptions(ctx: HandlerContext): Promise<Response> {
@@ -33,153 +34,18 @@ export async function GetSubscriptions(ctx: HandlerContext): Promise<Response> {
   }));
 }
 
-export async function GetSubscriptionsSearch(ctx: HandlerContext): Promise<Response> {
-  await advanceBilling(ctx);
-  return search(ctx, SUB);
-}
-
 export async function GetSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'subscription_exposed_id');
   await advanceBilling(ctx, (sub) => sub.id === id);
-  const sub = ctx.get(SUB, id);
+  const sub = resourceView(ctx, SUB, id);
   return sub ? ctx.reply(expanded(ctx, SUB, sub)) : subMissing(ctx, id);
 }
 
-export async function PostSubscriptions(ctx: HandlerContext): Promise<Response> {
-  const params = ctx.params;
-  const customer = typeof params.customer === 'string' ? params.customer : '';
-  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-  if (!ctx.get('customer', customer)) return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-  const now = clockNow(ctx, customer);
-  const badTrial = trialEndRefused(ctx, params.trial_end, now);
-  if (badTrial) return badTrial;
-  // a coupon (or discounts[0][coupon]) must exist; it becomes the subscription's discount
-  const couponId = subscriptionCouponParam(params);
-  let discounts: Row[] = [];
-  if (couponId) {
-    const coupon = ctx.get('coupon', couponId);
-    if (!coupon) return fail(ctx, `No such coupon: '${couponId}'`, 400, 'resource_missing');
-    discounts = [buildDiscount(coupon, customer, now)];
-  }
-  // a trial is the current period; otherwise one billing interval of the first item's price. The
-  // period sits top-level: this twin's default API version predates basil moving it onto items.
-  const trial = resolveTrial(params, now);
-  const itemEntries = subscriptionItemEntries(params.items);
-  const { interval, interval_count } = resolveSubscriptionBillingInterval(itemEntries, finder(ctx));
-  const periodStart = trial ? trial.start : now;
-  const periodEnd = trial ? trial.end : addBillingInterval(now, interval, interval_count);
-  const subId = typeof params.id === 'string' && params.id ? params.id : ctx.mint(SUB);
-  const itemsList = buildSubscriptionItemsList(itemEntries, subId, now, finder(ctx));
-  const itemsData = itemsList.data as Row[];
-  const currency = typeof params.currency === 'string' && params.currency ? params.currency : 'usd';
-
-  // Stripe opens a subscription's first invoice at once (a trialing one has nothing due yet) and, by
-  // payment_behavior (docs.stripe.com/api/subscriptions/create#create_subscription-payment_behavior):
-  // allow_incomplete (the default) charges the default payment method now, and without one, or on a decline,
-  // leaves the subscription incomplete with the invoice open; error_if_incomplete refuses the create instead;
-  // default_incomplete never charges, leaving a PaymentIntent the frontend confirms.
-  const behavior = typeof params.payment_behavior === 'string' ? params.payment_behavior : 'allow_incomplete';
-  const needsFirstInvoice = !trial;
-  const holder = ctx.get('customer', customer) ?? {};
-  const payWith = behavior === 'default_incomplete' ? undefined
-    : (typeof params.default_payment_method === 'string' ? params.default_payment_method : undefined) ?? ((holder.invoice_settings as Row | undefined)?.default_payment_method as string | undefined) ?? undefined;
-  const declined = payWith ? declineFor(finder(ctx), { payment_method: payWith }) : undefined;
-  let subtotal = 0;
-  for (const it of itemsData) {
-    const price = it.price && typeof it.price === 'object' ? (it.price as Row) : undefined;
-    subtotal += priceAmount(price, itemQuantity(it));
-  }
-  const coupon = discounts[0]?.coupon as Row | undefined;
-  const discountAmount = applyCouponDiscount(subtotal, coupon);
-  const invoiceTotal = Math.max(0, subtotal - discountAmount);
-  // a $0 first invoice is paid at once and needs no PaymentIntent
-  const isFree = invoiceTotal <= 0;
-  const pays = needsFirstInvoice && !isFree && !!payWith && !declined;
-  if (needsFirstInvoice && !isFree && !pays && behavior === 'error_if_incomplete') return firstPaymentRefused(ctx, declined);
-  // minted first so the subscription names its latest_invoice in its own create (a trial's $0 invoice too)
-  const invoiceId = needsFirstInvoice ? ctx.mint('invoice') : null;
-  const trialInvoiceId = needsFirstInvoice ? null : ctx.mint('invoice');
-  const piId = needsFirstInvoice && !isFree ? ctx.mint('payment_intent') : null;
-
-  const { coupon: _c, discounts: _ds, trial_period_days: _tpd, trial_end: _te, items: _items, id: _id, ...rest } = params;
-  const sub = await created(ctx, SUB, { ...rest, id: subId }, {
-    status: trial ? 'trialing' : needsFirstInvoice && !isFree && !pays ? 'incomplete' : 'active',
-    livemode: false, currency, collection_method: 'charge_automatically',
-    // a trial's end is the billing anchor: "The `billing_cycle_anchor` will be updated to the `trial_end` value"
-    // (docs.stripe.com/api/subscriptions/create#create_subscription-trial_end)
-    cancel_at_period_end: false, start_date: now, billing_cycle_anchor: trial ? trial.end : now, metadata: {},
-    discounts: discounts.map((d) => ({ ...d, subscription: subId })), billing_schedules: [],
-    ...(trial ? { trial_start: trial.start, trial_end: trial.end } : { trial_start: null, trial_end: null }),
-    current_period_start: periodStart, current_period_end: periodEnd,
-    items: itemsList,
-    latest_invoice: invoiceId ?? trialInvoiceId,
-    automatic_tax: { enabled: false, liability: null },
-    billing_mode: { type: 'classic' },
-    invoice_settings: { issuer: { type: 'self' } },
-  });
-  await storeItems(ctx, subId, itemsData);
-  if (discounts.length) await redeemCoupon(ctx, couponId);
-  // a customer billed for the first time takes the subscription's currency
-  if (!holder.currency) await ctx.write('customer', customer, { currency }, 'customer.update');
-  if (!invoiceId) {
-    // a trial's subscription still opens an invoice at once: "An immediate invoice is still created, but the amount is 0"
-    // (docs.stripe.com/billing/subscriptions/trials/free-trials); finalizing it spends a once coupon (renewals.ts)
-    const trialInvoice = await draftSubscriptionInvoice(ctx, ctx.get(SUB, subId) ?? sub, { start: periodStart, end: periodEnd, reason: 'subscription_create', trial: true, ...(trialInvoiceId ? { id: trialInvoiceId } : {}) });
-    await collectSubscriptionInvoice(ctx, trialInvoice, now, 'api');
-    return ctx.reply(expanded(ctx, SUB, ctx.get(SUB, subId) ?? sub));
-  }
-  // the default payment method pays the first invoice now: its charge (with its ledger entry) comes first
-  const chargeId = pays && piId ? await mintCharge(ctx, piId, { currency, customer, payment_method: payWith, invoice: invoiceId }, invoiceTotal) : null;
-
-  const invoiceLines = itemsData.map((it, i) => {
-    const price = it.price && typeof it.price === 'object' ? (it.price as Row) : undefined;
-    const quantity = itemQuantity(it);
-    return {
-      id: `il_twin_${invoiceId}_${i + 1}`, object: 'line_item', type: 'subscription',
-      amount: priceAmount(price, quantity), currency, quantity, proration: false,
-      price: it.price ?? null, subscription: subId, invoice_item: null, subscription_item: it.id ?? null,
-      period: { start: periodStart, end: periodEnd }, description: null,
-    };
-  });
-  await created(ctx, 'invoice', {
-    id: invoiceId,
-    ...finalizedFields(ctx, { id: invoiceId, customer }, now),
-    status: isFree || pays ? 'paid' : 'open', livemode: false, currency, collection_method: 'charge_automatically',
-    auto_advance: !(isFree || pays), attempt_count: payWith && !isFree ? 1 : 0, attempted: !isFree && behavior !== 'default_incomplete',
-    customer, subscription: subId, billing_reason: 'subscription_create', charge: chargeId,
-    amount_due: invoiceTotal, amount_paid: isFree || pays ? invoiceTotal : 0, amount_remaining: isFree || pays ? 0 : invoiceTotal,
-    amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
-    subtotal, total: invoiceTotal, starting_balance: 0,
-    post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
-    period_start: periodStart, period_end: periodEnd,
-    default_tax_rates: [], discounts: discounts[0] ? [discounts[0]] : [],
-    lines: { object: 'list', data: invoiceLines, has_more: false, total_count: invoiceLines.length, url: `/v1/invoices/${invoiceId}/lines` },
-    automatic_tax: { enabled: false, liability: null, status: null },
-    status_transitions: { finalized_at: now, marked_uncollectible_at: null, paid_at: isFree || pays ? now : null, voided_at: null },
-    issuer: { type: 'self' },
-    payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
-    payment_intent: piId,
-  }, {});
-  if (piId) {
-    // paid by the default payment method, or waiting on one (declined, absent, or collected client-side)
-    await created(ctx, 'payment_intent', { id: piId, amount: invoiceTotal, currency, customer, invoice: invoiceId, ...(payWith ? { payment_method: pays ? payWith : null } : {}) }, {
-      status: pays ? 'succeeded' : 'requires_payment_method', client_secret: mintClientSecret(piId, await ctx.secret(`client-secret:${piId}`)), livemode: false,
-      capture_method: 'automatic', amount_capturable: 0, amount_received: pays ? invoiceTotal : 0, next_action: null,
-      latest_charge: chargeId,
-      last_payment_error: declined ? { type: 'card_error', code: declined.code, decline_code: declined.decline_code ?? null, message: declined.message, payment_method: { id: payWith } } : null,
-      automatic_payment_methods: null, payment_method_types: ['card', 'link'], payment_method_options: {},
-    });
-  }
-  // the first invoice is finalized: the `once` coupon it took is spent (renewals.ts spendOnceCoupon)
-  await spendOnceCoupon(ctx, ctx.get('invoice', invoiceId) ?? {});
-  return ctx.reply(expanded(ctx, SUB, ctx.get(SUB, subId) ?? sub));
-}
-
 export async function PostSubscriptionsSubscriptionExposedId(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'subscription_exposed_id');
   // a period that has already ended renews (or a trial that has, ends) before the update applies (renewals.ts)
   await advanceBilling(ctx, (s) => s.id === id);
-  const sub = ctx.get(SUB, id);
+  const sub = resourceView(ctx, SUB, id);
   if (!sub) return subMissing(ctx, id);
   const params = ctx.params;
   const now = clockNow(ctx, sub.customer);
@@ -223,5 +89,19 @@ export async function PostSubscriptionsSubscriptionExposedId(ctx: HandlerContext
     fields.status = pays ? 'active' : 'past_due';
     if (fields.discounts !== undefined) fields.discounts = keptAfter(fields.discounts as Row[], ctx.get('invoice', trial.invoice) ?? {});
   }
-  return ctx.reply(await ctx.write(SUB, id, fields, op));
+  return ctx.reply(ctx.expand(SUB, await ctx.write(SUB, id, fields, op)));
+}
+
+
+
+export async function DeleteSubscriptionsSubscriptionExposedIdDiscount(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'subscription_exposed_id');
+  const sub = resourceView(ctx, SUB, id);
+  if (!sub) return subMissing(ctx, id);
+  // source: spec:DeleteSubscriptionsSubscriptionExposedIdDiscount "Removes the currently applied discount on a subscription."
+  const current = ((sub.discounts as unknown[] | undefined) ?? [])[0] ?? sub.discount;
+  // Where the documentation stops and the twin decides: a subscription with no discount answers its absence as a missing resource.
+  if (!current) return fail(ctx, `No active discount for subscription: '${id}'`, 404, 'resource_missing');
+  await ctx.write(SUB, id, { discounts: [] }, 'subscription.update');
+  return ctx.reply(deletedDiscount(typeof current === 'string' ? { id: current } : { ...(current as Row), subscription: id }, nowUnix(ctx.occurredAt)));
 }

package/src/semantics/test_helpers.ts

@@ -4,50 +4,116 @@ import type { HandlerContext } from '@volter/world-core';
 import type { Row } from '../engine/common.ts';
 import { AUTH, CARD, cardId, CH, historyEntry, holderId, merchantData, TXN } from '../engine/issuing.ts';
 import { isValidApiVersion, nowUnix, spendingControlsViolation, TWIN_API_VERSION } from '../engine/stripe.ts';
-import { READER } from '../engine/terminal.ts';
-import { CLOCK } from '../engine/test-clocks.ts';
-import { FA, TX } from '../engine/treasury.ts';
 import { stripeEventMatches } from '../engine/webhooks.ts';
-import { answeredByEndpoint, approvedAtOnce, askForAuthorization, at, authMissing, balanceOf, capture, cashBalance, created, customerMissing, fail, holdForCapture, issuingRefusal, mintCharge, nothingToPresent, readerMissing, received, reconcile, review, withCard } from './shared.ts';
-
-/** A test clock deleted with what lives on it: "Deleting the simulation also deletes the test customers associated
- *  with the clock and cancels their subscriptions" (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage). */
-export async function DeleteTestHelpersTestClocksTestClock(ctx: HandlerContext): Promise<Response> {
-  const id = at(ctx, 'test_clock');
-  if (!ctx.get(CLOCK, id)) return fail(ctx, `No such test clock: '${id}'`, 404, 'resource_missing');
-  const now = Number(nowUnix(ctx.occurredAt));
-  for (const c of ctx.rows('customer').filter((c) => c.test_clock === id)) {
-    for (const sub of ctx.rows('subscription').filter((s) => s.customer === c.id && s.status !== 'canceled')) {
-      ctx.legal('subscription', 'status', 'DeleteTestHelpersTestClocksTestClock', String(sub.status), 'canceled', String(sub.id));
-      await ctx.write('subscription', String(sub.id), { status: 'canceled', canceled_at: now, ended_at: now }, 'subscription.cancel');
-    }
-    await ctx.write('customer', String(c.id), { deleted: true }, 'customer.deleted');
-  }
-  await ctx.write(CLOCK, id, { deleted: true }, 'test_clock.deleted');
-  return ctx.reply({ id, object: 'test_helpers.test_clock', deleted: true });
+import { answeredByEndpoint, approvedAtOnce, askForAuthorization, at, authMissing, balanceOf, capture, created, fail, issuingRefusal, withCard } from './shared.ts';
+export async function PostTestHelpersIssuingAuthorizations(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  const card = typeof params.card === 'string' ? params.card : '';
+  if (!card) return fail(ctx, 'Missing required param: card.', 400, 'parameter_missing');
+  const c = ctx.get(CARD, card);
+  if (!c) return fail(ctx, `No such card: '${card}'`, 400, 'resource_missing');
+  if (params.amount === undefined) return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
+  const amount = Math.trunc(Number(params.amount) || 0);
+  const currency = String(params.currency ?? c.currency ?? 'usd');
+  const createdSec = Number(nowUnix(ctx.occurredAt));
+  const cardholderId = holderId(c);
+  const merchant = merchantData(params.merchant_data);
+  const isAmountControllable = params.is_amount_controllable === true;
+  const authMethod = typeof params.authorization_method === 'string' ? params.authorization_method : 'online';
+  if (!['chip', 'contactless', 'keyed_in', 'online', 'swipe'].includes(authMethod)) return issuingRefusal(ctx, 'authorization_method');
+  const merchantAmount = params.merchant_amount !== undefined ? Math.trunc(Number(params.merchant_amount) || 0) : amount;
+  const merchantCurrency = typeof params.merchant_currency === 'string' ? params.merchant_currency : currency;
+  const authId = ctx.mint(AUTH);
+  const baseFields: Row = {
+    amount, amount_details: null, authorization_method: authMethod,
+    balance_transactions: [], transactions: [],
+    currency, fleet: null, fuel: null, livemode: false,
+    merchant_amount: merchantAmount, merchant_currency: merchantCurrency, merchant_data: merchant,
+    metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
+    network_data: null,
+    verification_data: {
+      address_line1_check: 'not_provided', address_postal_code_check: 'not_provided',
+      authentication_exemption: null, cvc_check: 'match', expiry_check: 'match',
+      postal_code: null, three_d_secure: null,
+    },
+    wallet: null,
+  };
+  const subject = { id: authId, card, cardholder: cardholderId };
+  const entry = (o: { amount: number; approved: boolean; reason: string; reasonMessage: string | null }) => historyEntry({ ...o, currency, createdSec, merchantAmount, merchantCurrency });
+  const decline = async (reason: string, reasonMessage: string | null) =>
+    ctx.reply(withCard(ctx, await created(ctx, AUTH, subject, { ...baseFields, status: 'closed', approved: false, pending_request: null, request_history: [entry({ amount, approved: false, reason, reasonMessage })] })));
+  if (c.status === 'canceled') return decline('card_canceled', 'The card has been canceled.');
+  // source: https://docs.stripe.com/api/issuing/cards/create "Defaults to inactive"
+  // source: spec:/components/schemas/issuing_authorization_request/properties/reason/enum "card_inactive"
+  if (c.status !== 'active') return decline('card_inactive', 'The card is inactive.');
+  // what earlier approved authorizations on the card (or cardholder) already spent, for the limits
+  const prior = (key: 'card' | 'cardholder', value: string) =>
+    ctx.rows(AUTH).filter((a) => a[key] === value && a.approved === true)
+      .map((a) => ({ amount: Number(a.amount) || 0, created: Number(a.created) || 0, category: String((a.merchant_data as Row | undefined)?.category ?? '') }));
+  const controlsOpts = { amount, category: String(merchant.category ?? ''), country: merchant.country == null ? null : String(merchant.country), nowSec: createdSec };
+  const cardholderRow = cardholderId ? ctx.get(CH, cardholderId) : undefined;
+  const violation =
+    spendingControlsViolation(c.spending_controls, { ...controlsOpts, priorApproved: prior('card', card) }) ??
+    spendingControlsViolation(cardholderRow?.spending_controls, { ...controlsOpts, priorApproved: prior('cardholder', cardholderId) });
+  if (violation) return decline('spending_controls', violation);
+  // an authorization is paid from the Issuing balance, and declined when it cannot cover it
+  // (docs.stripe.com/issuing/funding/balance)
+  if ((balanceOf(ctx).issuing.get(currency) ?? 0) < amount) return decline('insufficient_funds', 'Your Issuing balance does not have enough funds for this authorization.');
+  const pendingRequest = {
+    amount, amount_details: null, currency, is_amount_controllable: isAmountControllable,
+    merchant_amount: merchantAmount, merchant_currency: merchantCurrency, network_risk_score: null,
+  };
+  const endpoint = ctx.rows('webhook_endpoint').find((w) => w.status === 'enabled' && stripeEventMatches(w.enabled_events, 'issuing_authorization.request'));
+  // no real-time enrollment: "If you don't have a real-time authorization webhook, we approve the authorization without
+  // sending the issuing_authorization.request" (docs.stripe.com/issuing/purchases/authorizations), its outcome
+  // card_active, "approved according to your default Issuing settings"
+  if (!endpoint) return approvedAtOnce(ctx, subject, baseFields, amount, entry({ amount, approved: true, reason: 'card_active', reasonMessage: null }));
+  // the request event's authorization carries pending_request, non-null only during the request
+  const requestObject = withCard(ctx, { object: 'issuing.authorization', id: authId, created: createdSec, ...baseFields, card, cardholder: cardholderId, status: 'pending', approved: false, pending_request: pendingRequest, request_history: [] });
+  // the request asked of the endpoint and the stored event are one event under one id
+  const pinned = ctx.call.request.headers.get('stripe-version');
+  const requestEvent = {
+    id: ctx.mint('event'), object: 'event', api_version: pinned && isValidApiVersion(pinned) ? pinned : TWIN_API_VERSION, created: createdSec,
+    data: { object: requestObject }, livemode: false, pending_webhooks: 1, request: { id: null, idempotency_key: null }, type: 'issuing_authorization.request',
+  };
+  await ctx.write('event', requestEvent.id, requestEvent, 'event.record');
+  const outcome = await askForAuthorization(ctx, String(endpoint.url), requestEvent, String(endpoint.secret ?? ''));
+  // a request no one answered (the World refused the delivery, it failed, or it timed out) is not a decision: the
+  // authorization stays pending with its request, for the deprecated approve or decline "within the timeout window of
+  // the real-time authorization flow" (the served spec), until lapseRealtimeRequests decides it when the window ends
+  if (outcome.kind === 'timeout') return ctx.reply(withCard(ctx, await created(ctx, AUTH, subject, { ...baseFields, status: 'pending', approved: false, request_history: [], pending_request: pendingRequest })));
+  return answeredByEndpoint(ctx, outcome, { subject, fields: baseFields, amount, controllable: isAmountControllable, entry, decline });
 }
-
-export async function PostTestHelpersTestClocks(ctx: HandlerContext): Promise<Response> {
-  if (ctx.params.frozen_time === undefined) return fail(ctx, 'Missing required param: frozen_time.', 400, 'parameter_missing');
-  const frozen = Math.trunc(Number(ctx.params.frozen_time) || 0);
-  // "Simulations are automatically deleted 30 days after you create them" (docs.stripe.com/billing/testing/test-clocks/
-  // api-advanced-usage): from its creation on the account's clock, not its frozen time
-  return ctx.reply(await created(ctx, CLOCK, { name: ctx.params.name ?? null }, { frozen_time: frozen, status: 'ready', status_details: {}, livemode: false, deletes_after: Number(nowUnix(ctx.occurredAt)) + 30 * 24 * 3600 }));
-}
-
-export async function PostTestHelpersTestClocksTestClockAdvance(ctx: HandlerContext): Promise<Response> {
-  const id = at(ctx, 'test_clock');
-  const clock = ctx.get(CLOCK, id);
-  if (!clock) return fail(ctx, `No such test clock: '${id}'`, 404, 'resource_missing');
-  if (ctx.params.frozen_time === undefined) return fail(ctx, 'Missing required param: frozen_time.', 400, 'parameter_missing');
-  const to = Math.trunc(Number(ctx.params.frozen_time) || 0);
-  if (to <= Number(clock.frozen_time)) return fail(ctx, 'frozen_time must be after the current clock time.', 400, 'parameter_invalid');
-  const refused = ctx.legal(CLOCK, 'status', 'PostTestHelpersTestClocksTestClockAdvance', clock.status, 'advancing', id);
+export async function PostTestHelpersIssuingAuthorizationsAuthorizationCapture(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'authorization');
+  const auth = ctx.get(AUTH, id);
+  if (!auth) return authMissing(ctx, id);
+  if (auth.approved !== true || auth.status !== 'pending') return issuingRefusal(ctx, 'not_capturable', auth);
+  const closeAuthorization = ctx.params.close_authorization !== false;
+  const refused = ctx.legal(AUTH, 'status', 'PostTestHelpersIssuingAuthorizationsAuthorizationCapture', auth.status, closeAuthorization ? 'closed' : 'pending');
   if (refused) return ctx.refuse(refused);
-  // "After a successful API request or Dashboard operation, it takes a few seconds to advance to the specified time"
-  // (docs.stripe.com/billing/testing/test-clocks/api-advanced-usage): the advance answers advancing toward its target,
-  // and finishClockAdvances completes it ADVANCE_SECONDS of World time later; an advance asked meanwhile is refused
-  // test_clock_not_ready (the machine's refusal).
-  return ctx.reply(await ctx.write(CLOCK, id, { status: 'advancing', status_details: { advancing: { target_frozen_time: to } } }, 'test_clock.advancing'));
+  const txns = Array.isArray(auth.transactions) ? auth.transactions : [];
+  const capturedSoFar = txns.map((t) => ctx.get(TXN, String(t))).reduce((s, t) => s + Math.abs(Number(t?.amount) || 0), 0);
+  const remaining = (Number(auth.amount) || 0) - capturedSoFar;
+  const captureAmount = ctx.params.capture_amount !== undefined ? Math.trunc(Number(ctx.params.capture_amount) || 0) : remaining;
+  if (captureAmount <= 0 || captureAmount > remaining) return fail(ctx, 'Invalid capture_amount: must be a positive integer no greater than the uncaptured authorized amount.', 400, 'parameter_invalid_integer');
+  // the capture releases what the approval held and debits the transaction; a capture that closes the authorization
+  // releases ALL it still holds, the uncaptured rest included: the amount is held "until the authorization is either
+  // captured, voided, or expired without capture" (docs.stripe.com/issuing/purchases/authorizations), and a closed
+  // authorization can be captured no further (close_authorization "Defaults to true. Set to false to enable
+  // multi-capture flows", the served spec). A capture that keeps it open releases only what it captured.
+  const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+  const released = closeAuthorization ? remaining : captureAmount;
+  const release = await created(ctx, 'balance_transaction', {}, {
+    amount: released, currency, fee: 0, net: released, type: 'issuing_authorization_release',
+    status: 'available', balance_type: 'issuing', reporting_category: 'issuing_authorization_release',
+    available_on: nowUnix(ctx.occurredAt), fee_details: [], source: id,
+  });
+  const captured = await capture(ctx, id, { ...auth, card: cardId(auth) }, captureAmount);
+  return ctx.reply(withCard(ctx, await ctx.write(AUTH, id, {
+      status: closeAuthorization ? 'closed' : 'pending',
+      transactions: [...txns, captured.txnId],
+      balance_transactions: [...(Array.isArray(auth.balance_transactions) ? auth.balance_transactions : []), release.id, captured.btId],
+    }, 'issuing_authorization.updated'),
+  ));
 }
-

package/src/semantics/transfers.ts

@@ -4,8 +4,7 @@ import type { HandlerContext } from '@volter/world-core';
 import type { Row } from '../engine/common.ts';
 import { nowUnix, validateMoney } from '../engine/stripe.ts';
 import { emptyList } from '../engine/transfers.ts';
-import { at, created, fail, giveBack, list, newest, refusePayout, send, settledSourceRefused, settleTransfer, settleTransferReversal, transferMissing, transfersInactive } from './shared.ts';
-
+import { created, fail, refusePayout, send, settledSourceRefused, settleTransfer, transfersInactive } from './shared.ts';
 export async function PostTransfers(ctx: HandlerContext): Promise<Response> {
   const bad = validateMoney(ctx.params);
   if (bad) return send(ctx, bad);
@@ -51,4 +50,3 @@ export async function PostTransfers(ctx: HandlerContext): Promise<Response> {
     }),
   );
 }
-

package/src/semantics/webhook_endpoints.ts

@@ -0,0 +1,27 @@
+// Stripe's webhook_endpoints 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 { asBool } from '../engine/stripe.ts';
+import { WE } from '../engine/webhook-endpoints.ts';
+import { created, fail } from './shared.ts';
+// an endpoint is enabled at once and signs each event with a secret of its own, answered by this create alone (the
+// around answers no other read of it)
+export async function PostWebhookEndpoints(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  // source: spec:PostWebhookEndpoints "The URL of the webhook endpoint."
+  if (typeof params.url !== 'string' || params.url === '') return fail(ctx, 'Missing required param: url.', 400, 'parameter_missing');
+  // source: spec:PostWebhookEndpoints "The list of events to enable for this endpoint."
+  if (params.enabled_events === undefined || params.enabled_events === '' || (Array.isArray(params.enabled_events) && !params.enabled_events.length)) return fail(ctx, 'Missing required param: enabled_events.', 400, 'parameter_missing');
+  const id = ctx.mint(WE);
+  // source: spec:/components/schemas/webhook_endpoint/properties/secret/description "The endpoint's secret, used to generate"
+  const secret = `whsec_${(await ctx.secret(`webhook-endpoint-secret:${id}`)).replace(/[^A-Za-z0-9]/g, '').slice(0, 32)}`;
+  return ctx.reply(await created(ctx, WE, { ...params, id }, {
+    url: params.url, enabled_events: Array.isArray(params.enabled_events) ? params.enabled_events.map(String) : [String(params.enabled_events)],
+    // source: spec:/components/schemas/webhook_endpoint/properties/status/description "The status of the webhook."
+    status: 'enabled', livemode: false, metadata: {}, application: null,
+    api_version: typeof params.api_version === 'string' ? params.api_version : null,
+    description: typeof params.description === 'string' ? params.description : null,
+    // source: spec:PostWebhookEndpoints "Whether this endpoint should receive events from connected accounts"
+    connect: asBool(params.connect), secret,
+  }));
+}

package/src/server.ts

@@ -1,7 +1,6 @@
 // FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
 import { serveHttp, type PackFetchOptions } from '@volter/world-core';
 import { createStripeFetch } from './fetch.ts';
-
 export async function createStripeTwinServer(options: PackFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {
   const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createStripeFetch(options) });
   return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };

package/dist/generated/pack-facts.json

@@ -1,94 +0,0 @@
-{
-  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
-  "packs": {
-    "stripe": {
-      "adoption": {
-        "pypi": [
-          "stripe"
-        ],
-        "sdks": [
-          "stripe"
-        ],
-        "envStems": [
-          "STRIPE",
-          "NEXTPRIVATESTRIPE"
-        ]
-      },
-      "hosts": [
-        {
-          "host": "api.stripe.com"
-        },
-        {
-          "host": "checkout.stripe.com",
-          "pathPattern": "^/c/pay/"
-        },
-        {
-          "host": "billing.stripe.com",
-          "pathPattern": "^/p/session/"
-        },
-        {
-          "host": "connect.stripe.com",
-          "pathPattern": "^/setup/|^/oauth/(authorize|token|deauthorize)/?$"
-        },
-        {
-          "host": "dashboard.stripe.com",
-          "pathPattern": "^/settings/public/?$|^/(test/)?settings/connect(/onboarding-options/oauth)?/?$"
-        },
-        {
-          "host": "verify.stripe.com",
-          "pathPattern": "^/start/"
-        },
-        {
-          "host": "js.stripe.com",
-          "pathPattern": "^/v3/financial-connections/|^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$"
-        }
-      ],
-      "archetype": "crud",
-      "protocol": {
-        "declared": "3",
-        "major": 3,
-        "standing": "current"
-      },
-      "transport": "rest",
-      "resources": [
-        "charge",
-        "customer",
-        "payment_intent",
-        "setup_intent",
-        "payment_method",
-        "subscription",
-        "price",
-        "product",
-        "invoice",
-        "invoiceitem",
-        "refund",
-        "event"
-      ],
-      "credentialDoor": {
-        "path": "/_twin/app-credentials",
-        "body": {},
-        "fill": {
-          "STRIPE_SECRET_KEY": "secret_key",
-          "STRIPE_API_KEY": "secret_key",
-          "STRIPE_PRIVATE_KEY": "secret_key",
-          "BILLING_STRIPE_API_KEY": "secret_key",
-          "STRIPE_PUBLISHABLE_KEY": "publishable_key",
-          "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY": "publishable_key",
-          "NEXT_PUBLIC_STRIPE_PUBLIC_KEY": "publishable_key",
-          "NEXT_PUBLIC_STRIPE_KEY": "publishable_key",
-          "STRIPE_WEBHOOK_SECRET": "webhook_secret",
-          "STRIPE_WEBHOOK_SIGNING_SECRET": "webhook_secret",
-          "STRIPE_ENDPOINT_SECRET": "webhook_secret",
-          "STRIPE_WEBHOOK_SECRET_KEY": "webhook_secret",
-          "NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET": "webhook_secret",
-          "BILLING_STRIPE_WEBHOOK_SECRET": "webhook_secret",
-          "STRIPE_CONNECT_WEBHOOK_SECRET": "connect_webhook_secret",
-          "STRIPE_WEBHOOK_SECRET_CONNECT": "connect_webhook_secret",
-          "STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET": "connect_webhook_secret"
-        }
-      },
-      "serveExport": "createStripeTwinServer"
-    }
-  },
-  "undeclared": []
-}

package/dist/src/engine/billing.d.ts

@@ -1,5 +0,0 @@
-import type { Row } from './common.js';
-export declare const METER = "billing.meter";
-export declare const objectOf: (v: unknown) => Row;
-export declare const GRANT = "billing.credit_grant";
-export declare const ALERT = "billing.alert";

package/dist/src/engine/billing.js

@@ -1,6 +0,0 @@
-export const METER = 'billing.meter';
-export const objectOf = (v) => (v && typeof v === 'object' ? v : {});
-// ── credit grants: a customer's prepaid credit, paid or promotional, in a monetary amount ──
-export const GRANT = 'billing.credit_grant';
-// ── alerts: a usage threshold on a meter ──
-export const ALERT = 'billing.alert';

package/dist/src/engine/charges.d.ts

@@ -1,6 +0,0 @@
-import type { Row } from './common.js';
-/** The create's parameters as the charge keeps them: without `card`, the request's card details ("A token, like the ones
- *  returned by Stripe.js", or a hash of the number, expiry and CVC). The Charge object has no `card` property (served
- *  spec, charge); the card it was made with is its payment_method_details. Kept, it answered the card's full number and
- *  CVC back on every read of the charge. */
-export declare function withoutCard(params: Row): Row;

package/dist/src/engine/charges.js

@@ -1,13 +0,0 @@
-// A charge is written as the event Stripe sends for it (docs.stripe.com/api/events/types; Stripe has no
-// `charge.created`): charge.succeeded, "Occurs whenever a charge is successful", for one made or authorized
-// (capture=false: its status is succeeded, captured false), and charge.failed, "Occurs whenever a failed charge attempt
-// occurs", for a declined attempt. The twin makes no pending charge (charge.pending, "Occurs whenever a pending charge is
-// created"): its charges settle when made.
-/** The create's parameters as the charge keeps them: without `card`, the request's card details ("A token, like the ones
- *  returned by Stripe.js", or a hash of the number, expiry and CVC). The Charge object has no `card` property (served
- *  spec, charge); the card it was made with is its payment_method_details. Kept, it answered the card's full number and
- *  CVC back on every read of the charge. */
-export function withoutCard(params) {
-    const { card: _card, ...rest } = params;
-    return rest;
-}

package/dist/src/engine/connect-settings.d.ts

@@ -1,16 +0,0 @@
-/** The platform's test client_id: the World's one platform (acct_twin_self) is the application it names. */
-export declare const PLATFORM_CLIENT_ID = "ca_twin_self";
-export declare const SETTINGS_URL = "https://dashboard.stripe.com/settings/connect/onboarding-options/oauth";
-/** The page's addresses: the docs' own, its test-mode link, and Connect's settings root. */
-export declare const CONNECT_SETTINGS_PATH: RegExp;
-export declare const SETTINGS = "_connect_oauth_settings";
-export type ConnectOAuthSettings = {
-    oauth_enabled: boolean;
-    redirect_uris: string[];
-};
-/** The redirect URIs a form's field names, or the first one refused and why. */
-export declare function redirectUris(field: string): {
-    uris: string[];
-} | {
-    refused: string;
-};

package/dist/src/engine/connect-settings.js

@@ -1,26 +0,0 @@
-// The platform's Connect OAuth settings (its client_id, whether OAuth is on, its redirect URIs), which the Dashboard's
-// settings page saves (../screens/dashboard.tsx) and connect.stripe.com/oauth/authorize reads (../screens/connect-oauth.tsx).
-/** The platform's test client_id: the World's one platform (acct_twin_self) is the application it names. */
-export const PLATFORM_CLIENT_ID = 'ca_twin_self';
-export const SETTINGS_URL = 'https://dashboard.stripe.com/settings/connect/onboarding-options/oauth';
-/** The page's addresses: the docs' own, its test-mode link, and Connect's settings root. */
-export const CONNECT_SETTINGS_PATH = /^\/(test\/)?settings\/connect(\/onboarding-options\/oauth)?\/?$/;
-export const SETTINGS = '_connect_oauth_settings';
-/** The redirect URIs a form's field names, or the first one refused and why. */
-export function redirectUris(field) {
-    const uris = [...new Set(field.split(/[\n,]/).map((s) => s.trim()).filter(Boolean))];
-    for (const uri of uris) {
-        let url;
-        try {
-            url = new URL(uri);
-        }
-        catch {
-            return { refused: `${uri} is not a valid URL.` };
-        }
-        if (url.protocol !== 'https:' && url.protocol !== 'http:')
-            return { refused: `${uri} must use http or https.` };
-        if (uri.includes('#'))
-            return { refused: `${uri} must not contain a fragment.` };
-    }
-    return { uris };
-}

package/dist/src/engine/coupons.js

@@ -1,5 +0,0 @@
-"use strict";
-// Coupon and PromotionCode semantics. A coupon is exactly one of percent_off or amount_off (with
-// its currency) over a duration; a promotion code is a customer-facing code for an existing
-// coupon, active until switched off (the machine in ../manifest.ts). Coupon list, retrieve, update
-// and delete and promotion-code retrieve and update (`active`, the machine) are the derived core's.

package/dist/src/engine/credit-notes.d.ts

@@ -1 +0,0 @@
-export declare const CN = "credit_note";