@volter/twin-stripe 3.0.0 → 3.0.2

package/src/semantics/invoices.ts

@@ -2,34 +2,79 @@
 // handler contract's context, computing with the engine (../engine/).
 import type { HandlerContext } from '@volter/world-core';
 import type { Row } from '../engine/common.ts';
-import { collectsThroughIntent, draft, INV, linesOf, prorationLines, sumLines, transitions } from '../engine/invoices.ts';
-import { addBillingInterval, applyCouponDiscount, asBool, cardError, declineFor, nowUnix, paginate, priceAmount, subscriptionItemPairs } from '../engine/stripe.ts';
-import { activatedByPayment, at, created, editLines, expanded, fail, finalizedFields, finder, invoiceMissing, invoicesLoad, mintCharge, newest, nothingToPayWith, openPaymentIntent, path, pullPendingItem, search, send, spendOnceCoupon } from './shared.ts';
-
-// only a draft is deleted; a finalized invoice is voided instead
-export async function DeleteInvoicesInvoice(ctx: HandlerContext): Promise<Response> {
-  const loaded = invoicesLoad(ctx, 'DeleteInvoicesInvoice');
-  if ('answer' in loaded) return loaded.answer;
-  const id = String(loaded.inv.id);
-  await ctx.write(INV, id, { deleted: true }, 'invoice.deleted');
-  return ctx.reply({ id, object: 'invoice', deleted: true });
-}
-
+import { INV, transitions } from '../engine/invoices.ts';
+import { asBool, cardError, declineFor, nowUnix } from '../engine/stripe.ts';
+import { resourceView, activatedByPayment, at, expanded, finalizeForPayment, finder, invoiceMissing, invoicesLoad, mintCharge, nothingToPayWith, send } from './shared.ts';
+import { draft, prorationLines, sumLines } from '../engine/invoices.ts';
+import { addBillingInterval, applyCouponDiscount, priceAmount } from '../engine/stripe.ts';
+import { created, fail, newest, pendingPreviewLines, pullPendingItem } from './shared.ts';
 export async function GetInvoicesInvoice(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'invoice');
   const inv = ctx.get(INV, id);
   return inv ? ctx.reply(expanded(ctx, INV, inv)) : invoiceMissing(ctx, id);
 }
 
-// the invoice's lines, a page at a time
-export async function GetInvoicesInvoiceLines(ctx: HandlerContext): Promise<Response> {
+// paying charges a payment method (the one passed, the invoice's default, or the customer's) unless
+// the payment is recorded out of band; a declining card answers 402 and leaves the invoice open. A
+// paid invoice settles the PaymentIntent finalize opened, and names the charge that took the money.
+export async function PostInvoicesInvoicePay(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'invoice');
-  const inv = ctx.get(INV, id);
-  if (!inv) return invoiceMissing(ctx, id);
-  const { page, hasMore } = paginate(linesOf(inv), ctx.params);
-  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page.map((l) => ({ invoice: id, ...l })) });
+  const found = ctx.get(INV, id);
+  if (!found) return invoiceMissing(ctx, id);
+  const refused = ctx.legal(INV, 'status', 'PostInvoicesInvoicePay', found.status, undefined, id);
+  if (refused) return ctx.refuse(refused);
+  // paying a draft finalizes it first, as its finalize does (its number, and the PaymentIntent it collects through)
+  // source: https://docs.stripe.com/invoicing/integration "To finalize a draft invoice, use the Dashboard, send it to the customer, or pay it."
+  const inv = found.status === 'draft' ? await finalizeForPayment(ctx, found, id) : found;
+  const params = ctx.params;
+  const paidOutOfBand = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
+  const payer = ctx.get('customer', String(inv.customer ?? ''));
+  const customerDefault = (payer?.invoice_settings as Row | undefined)?.default_payment_method || payer?.default_source;
+  if (!paidOutOfBand && !params.payment_method && !params.source && !inv.default_payment_method && !inv.default_source && !customerDefault) return nothingToPayWith(ctx);
+  // what it charges: the method passed, else the invoice's default, its subscription's, then its customer's
+  // (docs.stripe.com/api/invoices/pay#pay_invoice-payment_method)
+  const subscription = typeof inv.subscription === 'string' ? resourceView(ctx, 'subscription', inv.subscription) : undefined;
+  const decline = declineFor(finder(ctx), params, { payment_method: inv.default_payment_method ?? subscription?.default_payment_method ?? customerDefault });
+  const intent = typeof inv.payment_intent === 'string' ? ctx.get('payment_intent', inv.payment_intent) : undefined;
+  if (decline) return send(ctx, cardError(decline, intent ? { payment_intent: intent } : {}));
+  const amountPaid = Number(inv.total ?? inv.amount_due) || 0;
+  let body = await ctx.write(INV, id, {
+    // paid outside Stripe, the invoice counts it as such: `amount_paid_off_stripe`, "Amount, in cents (or local
+    // equivalent), that was paid on the invoice outside of Stripe" (served spec, invoice), the only place the served
+    // version shows it now that basil renders no `paid_out_of_band` (../engine/version.ts)
+    status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
+    ...(paidOutOfBand ? { amount_paid_off_stripe: amountPaid } : {}),
+    status_transitions: { ...transitions(inv), paid_at: nowUnix(ctx.occurredAt) },
+  }, 'invoice.pay');
+  if (!paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {
+    const pi = ctx.get('payment_intent', inv.payment_intent);
+    if (pi && pi.status !== 'succeeded' && !ctx.legal('payment_intent', 'status', 'PostInvoicesInvoicePay', pi.status)) {
+      const chargeId = await mintCharge(ctx, inv.payment_intent, { ...pi, invoice: id, ...(typeof params.payment_method === 'string' ? { payment_method: params.payment_method } : {}) }, amountPaid);
+      await ctx.write('payment_intent', inv.payment_intent, { status: 'succeeded', amount_received: amountPaid, amount_capturable: 0, next_action: null, latest_charge: chargeId }, 'payment_intent.succeeded');
+      body = await ctx.write(INV, id, { charge: chargeId }, 'invoice.update');
+    }
+  }
+  // a subscription waiting on this invoice (incomplete on its first, past_due on a failed renewal) is active once it is paid
+  const subId = typeof inv.subscription === 'string' ? inv.subscription : undefined;
+  const sub = subId ? resourceView(ctx, 'subscription', subId) : undefined;
+  if (subId && sub && (sub.status === 'incomplete' || sub.status === 'past_due') && !ctx.legal('subscription', 'status', 'PostInvoicesInvoicePay', sub.status, 'active', subId)) await activatedByPayment(ctx, subId);
+  return ctx.reply(expanded(ctx, INV, ctx.get(INV, id) ?? body));
 }
 
+// sending a draft finalizes it; any other invoice keeps its status and records the send
+
+export async function PostInvoicesInvoiceVoid(ctx: HandlerContext): Promise<Response> {
+  const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceVoid');
+  if ('answer' in loaded) return loaded.answer;
+  const inv = loaded.inv;
+  const body = await ctx.write(INV, String(inv.id), { status: 'void', status_transitions: { ...transitions(inv), voided_at: nowUnix(ctx.occurredAt) } }, 'invoice.void');
+  return ctx.reply(expanded(ctx, INV, body));
+}
+
+
+
+// the invoice's lines, a page at a time
+
 // a new invoice pulls in the customer's pending items only when asked: pending_invoice_items_behavior "Defaults to
 // `exclude` if the parameter is omitted" (docs.stripe.com/api/invoices/create)
 export async function PostInvoices(ctx: HandlerContext): Promise<Response> {
@@ -53,21 +98,21 @@ export async function PostInvoices(ctx: HandlerContext): Promise<Response> {
   return ctx.reply(pending.length > 0 ? (ctx.get(INV, invoiceId) ?? inv) : inv);
 }
 
+
+
 /**
  * A preview of the next invoice for a customer or subscription (create_preview), computed and never
  * stored: the subscription's items at their prices, the customer's pending items, the subscription's
- * discount, and with `subscription_details.proration_date` a credit for the unused period against a
- * charge for the new one (split evenly: there is no clock here to measure the remaining fraction).
+ * discount, and an update's unused-time credit and remaining-time charge at the old and new prices.
  */
 export async function PostInvoicesCreatePreview(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
-  const prorationDate = (params.subscription_details as Row | undefined)?.proration_date;
   const now = Number(nowUnix(ctx.occurredAt));
   let subId = typeof params.subscription === 'string' ? params.subscription : '';
   let customer = typeof params.customer === 'string' ? params.customer : '';
   let sub: Row | undefined;
   if (subId) {
-    sub = ctx.get('subscription', subId);
+    sub = resourceView(ctx, 'subscription', subId);
     if (!sub) return fail(ctx, `No such subscription: '${subId}'`, 404, 'resource_missing');
     customer = customer || String(sub.customer ?? '');
   } else if (customer) {
@@ -81,17 +126,48 @@ export async function PostInvoicesCreatePreview(ctx: HandlerContext): Promise<Re
   // the upcoming invoice bills the subscription's next period, its "subscription renewal charges"
   // (docs.stripe.com/api/invoices/create_preview): from the current period's end, one billing interval long
   const renewsAt = sub && Number(sub.current_period_end) > 0 ? Number(sub.current_period_end) : now;
-  const itemRows = sub ? ctx.rows('subscription_item').filter((r) => r.subscription === subId) : [];
+  let itemRows = sub ? ctx.rows('subscription_item').filter((r) => r.subscription === subId) : [];
+  const details = params.subscription_details as Row | undefined;
+  const previousItems = itemRows;
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "The default value is"
+  const behavior = details?.proration_behavior ?? 'create_prorations';
+  // source: https://docs.stripe.com/billing/subscriptions/prorations "The prorated amount is calculated as soon as the API updates the subscription."
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "forces the proration to be calculated as though the update was done at the specified time."
+  const prorationTime = details?.proration_date === undefined ? now : Number(details.proration_date);
+  const periodStart = Number(sub?.current_period_start ?? now);
+  const periodEnd = Number(sub?.current_period_end ?? now);
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "The time given must be within the current subscription period"
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "cannot be set to"
+  if (details?.proration_date !== undefined && (behavior === 'none' || !sub || !Array.isArray(details.items) || prorationTime < periodStart || prorationTime > periodEnd)) return fail(ctx, 'Invalid subscription_details[proration_date] for this subscription preview.', 400, 'parameter_invalid_integer');
+  // source: spec:/paths/~1v1~1invoices~1create_preview/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/subscription_details/description "The subscription creation or modification params to apply as a preview."
+  // Preview changes are local to this calculation: the subscription and its stored items are never changed.
+  if (Array.isArray(details?.items)) {
+    itemRows = itemRows.map(item => ({ ...item }));
+    for (const change of details.items as Row[]) {
+      const index = change.id ? itemRows.findIndex(item => item.id === change.id) : -1;
+      if (change.id && index < 0) return fail(ctx, `No such subscription_item: '${change.id}'`, 400, 'resource_missing');
+      if (asBool(change.deleted)) { if (index >= 0) itemRows.splice(index, 1); continue; }
+      const previous = index >= 0 ? itemRows[index]! : {};
+      const priceId = typeof change.price === 'string' ? change.price : typeof previous.price === 'string' ? previous.price : (previous.price as Row | undefined)?.id;
+      const price = typeof priceId === 'string' ? ctx.get('price', priceId) : undefined;
+      if (!price) return fail(ctx, `No such price: '${priceId ?? ''}'`, 400, 'resource_missing');
+      const quantity = change.quantity === undefined ? Number(previous.quantity ?? 1) : Number(change.quantity);
+      const previewItem = { ...previous, price, quantity };
+      if (index >= 0) itemRows[index] = previewItem; else itemRows.push(previewItem);
+    }
+  }
   const out: Row[] = [];
   let subtotal = 0;
   let period = now + 30 * 24 * 3600;
   if (sub) {
-    for (const { price: priceId, quantity } of subscriptionItemPairs(sub)) {
+    for (const previewItem of itemRows) {
+      const priceId = typeof previewItem.price === 'string' ? previewItem.price : String((previewItem.price as Row | undefined)?.id ?? '');
+      const quantity = Number(previewItem.quantity) || 0;
       const price = ctx.get('price', priceId);
       const amount = priceAmount(price, quantity);
       const recurring = (price?.recurring as Row | undefined) ?? {};
       period = recurring.interval ? addBillingInterval(renewsAt, recurring.interval as Parameters<typeof addBillingInterval>[1], Number(recurring.interval_count) || 1) : period;
-      const item = itemRows.find((r) => (typeof r.price === 'string' ? r.price : (r.price as Row | undefined)?.id) === priceId);
+      const item = previewItem;
       subtotal += amount;
       out.push({
         id: `il_twin_${priceId}`, object: 'line_item', type: 'subscription', amount, currency,
@@ -99,17 +175,30 @@ export async function PostInvoicesCreatePreview(ctx: HandlerContext): Promise<Re
         period: { start: renewsAt, end: period }, description: `${quantity} × ${(price?.nickname as string) ?? priceId}`,
       });
     }
-    if (prorationDate !== undefined && subtotal > 0) prorationLines(out, subtotal, currency, now, period);
   }
-  for (const ii of newest(ctx, 'invoiceitem', 'date')) {
-    if (ii.customer !== customer || ii.invoice) continue;
-    out.push({ id: `il_${String(ii.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(ii.amount) || 0, currency, quantity: Number(ii.quantity) || 1, proration: false, invoice_item: ii.id, period: ii.period ?? { start: now, end: now }, description: (ii.description as string) ?? null });
-  }
-  subtotal = sumLines(out);
   const subDiscount = Array.isArray(sub?.discounts) && sub!.discounts.length ? (sub!.discounts as Row[])[0] : undefined;
   const coupon = subDiscount && typeof subDiscount.coupon === 'object' ? (subDiscount.coupon as Row) : undefined;
-  const discountAmount = applyCouponDiscount(Math.max(0, subtotal), coupon);
-  const total = Math.max(0, subtotal - discountAmount);
+  // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "Disable creating prorations in this request."
+  // source: https://docs.stripe.com/billing/subscriptions/prorations "creates a non-proration debit, even when the debit covers a partial billing period."
+  if (sub && Array.isArray(details?.items) && behavior !== 'none' && sub.status !== 'trialing') {
+    const before = previousItems.map(item => {
+      const priceId = typeof item.price === 'string' ? item.price : String((item.price as Row).id);
+      const price = ctx.get('price', priceId);
+      return { id: `il_twin_${priceId}`, object: 'line_item', type: 'subscription', amount: priceAmount(price, Number(item.quantity ?? 1)), currency,
+        price: price ?? priceId, quantity: Number(item.quantity ?? 1), subscription: subId, subscription_item: item.id,
+        period: { start: item.current_period_start ?? periodStart, end: item.current_period_end ?? periodEnd } };
+    });
+    const after = out.map(line => ({ ...line, period: { start: periodStart, end: periodEnd } }));
+    const prorations = prorationLines(before, after, prorationTime, periodStart, periodEnd, coupon);
+    // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "Always invoice immediately for prorations."
+    if (behavior === 'always_invoice' && prorations.length) out.splice(0, out.length, ...prorations);
+    else out.unshift(...prorations);
+  }
+  out.push(...pendingPreviewLines(ctx, customer, currency, now));
+  subtotal = sumLines(out);
+  // source: https://docs.stripe.com/billing/subscriptions/prorations "no additional discounts are applied to the proration line items themselves"
+  const discountAmount = applyCouponDiscount(Math.max(0, sumLines(out.filter(line => !line.proration))), coupon);
+  const total = subtotal - discountAmount;
   return ctx.reply({
     ...draft(now),
     // "For preview invoices created using the create preview endpoint, this id will be prefixed with `upcoming_in`"
@@ -118,94 +207,10 @@ export async function PostInvoicesCreatePreview(ctx: HandlerContext): Promise<Re
     object: 'invoice', id: `upcoming_${ctx.mint(INV)}`, customer, subscription: subId || null, currency,
     billing_reason: subId ? 'upcoming' : 'manual',
     created: now, period_start: now, period_end: period,
-    subtotal, total, amount_due: total, amount_paid: 0, amount_remaining: total,
+    subtotal, total, amount_due: Math.max(0, total), amount_paid: 0, amount_remaining: Math.max(0, total),
     starting_balance: 0, ending_balance: null,
     discounts: discountAmount > 0 && subDiscount ? [subDiscount] : [],
     total_discount_amounts: discountAmount > 0 ? [{ amount: discountAmount, discount: subDiscount?.id ?? null }] : [],
     lines: { object: 'list', url: '/v1/invoices/create_preview/lines', has_more: false, total_count: out.length, data: out },
   });
 }
-
-export async function PostInvoicesInvoiceFinalize(ctx: HandlerContext): Promise<Response> {
-  const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceFinalize');
-  if ('answer' in loaded) return loaded.answer;
-  const inv = loaded.inv;
-  const id = String(inv.id);
-  const piId = collectsThroughIntent(inv) ? ctx.mint('payment_intent') : null;
-  const body = await ctx.write(INV, id, { ...finalizedFields(ctx, inv, Number(nowUnix(ctx.occurredAt))), status: 'open', status_transitions: { ...transitions(inv), finalized_at: nowUnix(ctx.occurredAt) }, payment_intent: piId }, 'invoice.finalize');
-  if (piId) await openPaymentIntent(ctx, piId, inv, id);
-  // a subscription's invoice finalized spends the once coupon it took (renewals.ts spendOnceCoupon)
-  await spendOnceCoupon(ctx, inv);
-  return ctx.reply(expanded(ctx, INV, body));
-}
-
-// paying charges a payment method (the one passed, the invoice's default, or the customer's) unless
-// the payment is recorded out of band; a declining card answers 402 and leaves the invoice open. A
-// paid invoice settles the PaymentIntent finalize opened, and names the charge that took the money.
-export async function PostInvoicesInvoicePay(ctx: HandlerContext): Promise<Response> {
-  const id = at(ctx, 'invoice');
-  const inv = ctx.get(INV, id);
-  if (!inv) return invoiceMissing(ctx, id);
-  const refused = ctx.legal(INV, 'status', 'PostInvoicesInvoicePay', inv.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  const params = ctx.params;
-  const paidOutOfBand = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
-  const payer = ctx.get('customer', String(inv.customer ?? ''));
-  const customerDefault = (payer?.invoice_settings as Row | undefined)?.default_payment_method || payer?.default_source;
-  if (!paidOutOfBand && !params.payment_method && !params.source && !inv.default_payment_method && !inv.default_source && !customerDefault) return nothingToPayWith(ctx);
-  // what it charges: the method passed, else the invoice's default, its subscription's, then its customer's
-  // (docs.stripe.com/api/invoices/pay#pay_invoice-payment_method)
-  const subscription = typeof inv.subscription === 'string' ? ctx.get('subscription', inv.subscription) : undefined;
-  const decline = declineFor(finder(ctx), params, { payment_method: inv.default_payment_method ?? subscription?.default_payment_method ?? customerDefault });
-  const intent = typeof inv.payment_intent === 'string' ? ctx.get('payment_intent', inv.payment_intent) : undefined;
-  if (decline) return send(ctx, cardError(decline, intent ? { payment_intent: intent } : {}));
-  const amountPaid = Number(inv.total ?? inv.amount_due) || 0;
-  let body = await ctx.write(INV, id, {
-    // paid outside Stripe, the invoice counts it as such: `amount_paid_off_stripe`, "Amount, in cents (or local
-    // equivalent), that was paid on the invoice outside of Stripe" (served spec, invoice), the only place the served
-    // version shows it now that basil renders no `paid_out_of_band` (../engine/version.ts)
-    status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
-    ...(paidOutOfBand ? { amount_paid_off_stripe: amountPaid } : {}),
-    status_transitions: { ...transitions(inv), paid_at: nowUnix(ctx.occurredAt) },
-  }, 'invoice.pay');
-  if (!paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {
-    const pi = ctx.get('payment_intent', inv.payment_intent);
-    if (pi && pi.status !== 'succeeded' && !ctx.legal('payment_intent', 'status', 'PostInvoicesInvoicePay', pi.status)) {
-      const chargeId = await mintCharge(ctx, inv.payment_intent, { ...pi, invoice: id, ...(typeof params.payment_method === 'string' ? { payment_method: params.payment_method } : {}) }, amountPaid);
-      await ctx.write('payment_intent', inv.payment_intent, { status: 'succeeded', amount_received: amountPaid, amount_capturable: 0, next_action: null, latest_charge: chargeId }, 'payment_intent.succeeded');
-      body = await ctx.write(INV, id, { charge: chargeId }, 'invoice.update');
-    }
-  }
-  // a subscription waiting on this invoice (incomplete on its first, past_due on a failed renewal) is active once it is paid
-  const subId = typeof inv.subscription === 'string' ? inv.subscription : undefined;
-  const sub = subId ? ctx.get('subscription', subId) : undefined;
-  if (subId && sub && (sub.status === 'incomplete' || sub.status === 'past_due') && !ctx.legal('subscription', 'status', 'PostInvoicesInvoicePay', sub.status, 'active', subId)) await activatedByPayment(ctx, subId);
-  return ctx.reply(expanded(ctx, INV, body));
-}
-
-// sending a draft finalizes it; any other invoice keeps its status and records the send
-export async function PostInvoicesInvoiceSend(ctx: HandlerContext): Promise<Response> {
-  const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceSend');
-  if ('answer' in loaded) return loaded.answer;
-  const inv = loaded.inv;
-  const id = String(inv.id);
-  const becameOpen = inv.status === 'draft';
-  const piId = collectsThroughIntent(inv) ? ctx.mint('payment_intent') : null;
-  const now = nowUnix(ctx.occurredAt);
-  const body = await ctx.write(INV, id, {
-    status: becameOpen ? 'open' : (inv.status as string), _sent: true, _sent_at: now,
-    status_transitions: { ...transitions(inv), ...(becameOpen ? { finalized_at: now } : {}) },
-    ...(becameOpen ? { payment_intent: piId } : {}),
-  }, 'invoice.sent');
-  if (piId) await openPaymentIntent(ctx, piId, inv, id);
-  if (becameOpen) await spendOnceCoupon(ctx, inv);
-  return ctx.reply(expanded(ctx, INV, body));
-}
-
-export async function PostInvoicesInvoiceVoid(ctx: HandlerContext): Promise<Response> {
-  const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceVoid');
-  if ('answer' in loaded) return loaded.answer;
-  const inv = loaded.inv;
-  const body = await ctx.write(INV, String(inv.id), { status: 'void', status_transitions: { ...transitions(inv), voided_at: nowUnix(ctx.occurredAt) } }, 'invoice.void');
-  return ctx.reply(expanded(ctx, INV, body));
-}

package/src/semantics/issuing.ts

@@ -0,0 +1,74 @@
+// Stripe's issuing 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 type { Row } from '../engine/common.ts';
+import { CARD, CH, cardNumberOf, cvcOf } from '../engine/issuing.ts';
+import { emptySpendingControls, normalizeSpendingControls, nowUnix } from '../engine/stripe.ts';
+import { at, created, fail, issuingDecide, issuingRefusal, send } from './shared.ts';
+
+export async function GetIssuingCardsCard(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'card');
+  const card = ctx.get(CARD, id);
+  if (!card) return fail(ctx, `No such card: '${id}'`, 404, 'resource_missing');
+  const expand = Array.isArray(ctx.params.expand) ? ctx.params.expand.map(String) : [];
+  // source: spec:/components/schemas/issuing.card/properties/number/description "For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with"
+  const virtual = card.type === 'virtual';
+  const shown: Row = { ...card };
+  if (virtual && expand.includes('number')) shown.number = cardNumberOf(await ctx.secret(`issuing-card-number:${id}`));
+  // source: spec:/components/schemas/issuing.card/properties/cvc/description "The card's CVC. For security reasons, this is only available for virtual cards"
+  if (virtual && expand.includes('cvc')) shown.cvc = cvcOf(await ctx.secret(`issuing-card-cvc:${id}`));
+  return ctx.reply(ctx.expand(CARD, shown));
+}
+
+export async function PostIssuingAuthorizationsAuthorizationApprove(ctx: HandlerContext): Promise<Response> {
+  return issuingDecide(true)(ctx);
+}
+
+export async function PostIssuingAuthorizationsAuthorizationDecline(ctx: HandlerContext): Promise<Response> {
+  return issuingDecide(false)(ctx);
+}
+
+export async function PostIssuingCards(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  // source: spec:PostIssuingCards "The currency for the card."
+  if (params.currency === undefined || params.currency === '') return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
+  const cardType = typeof params.type === 'string' ? params.type : '';
+  if (!cardType) return fail(ctx, 'Missing required param: type.', 400, 'parameter_missing');
+  // source: spec:PostIssuingCards "The type of card to issue."
+  if (cardType !== 'virtual' && cardType !== 'physical') return fail(ctx, "Invalid type: must be one of 'virtual' or 'physical'.", 400, 'parameter_invalid_string_enum');
+  // the card answers its cardholder in full (the served spec's issuing.card.cardholder is the Cardholder object)
+  const holder = typeof params.cardholder === 'string' ? params.cardholder : '';
+  const cardholder = holder ? ctx.get(CH, holder) : undefined;
+  if (holder && !cardholder) return fail(ctx, `No such cardholder: '${holder}'`, 400, 'resource_missing');
+  const controls = normalizeSpendingControls(params.spending_controls, typeof params.currency === 'string' ? params.currency : null);
+  if (controls.error) return send(ctx, controls.error);
+  const id = ctx.mint(CARD);
+  const number = cardNumberOf(await ctx.secret(`issuing-card-number:${id}`));
+  // Where the documentation stops and the twin decides: a card expires three years after it is issued, at the end of
+  // the month it was issued in.
+  const issued = new Date(Number(nowUnix(ctx.occurredAt)) * 1000);
+  return ctx.reply(ctx.expand(CARD, await created(ctx, CARD, { ...params, id, cardholder: holder || null, spending_controls: controls.controls ?? emptySpendingControls() }, {
+    // source: https://docs.stripe.com/api/issuing/cards/create "Whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to inactive."
+    status: typeof params.status === 'string' ? params.status : 'inactive',
+    livemode: false, metadata: {}, brand: 'Visa', last4: number.slice(-4),
+    exp_month: issued.getUTCMonth() + 1, exp_year: issued.getUTCFullYear() + 3,
+    cancellation_reason: null, replacement_for: null, replacement_reason: null, shipping: null, wallets: null,
+  })));
+}
+
+// source: spec:PostIssuingCardsCard "Any parameters not provided will be left unchanged."
+export async function PostIssuingCardsCard(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'card');
+  const card = ctx.get(CARD, id);
+  if (!card) return fail(ctx, `No such card: '${id}'`, 404, 'resource_missing');
+  const { expand: _expand, ...fields } = ctx.params;
+  // source: spec:/paths/~1v1~1issuing~1cards~1{card}/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/status "Dictates whether authorizations can be approved on this card."
+  if (fields.status !== undefined && !['active', 'inactive', 'canceled'].includes(String(fields.status))) return issuingRefusal(ctx, 'card_status');
+  if (fields.status !== undefined) {
+    const refused = ctx.legal(CARD, 'status', 'PostIssuingCardsCard', card.status, String(fields.status), id);
+    if (refused) return ctx.refuse(refused);
+  }
+  const controls = normalizeSpendingControls(fields.spending_controls, String(card.currency), card.spending_controls as Row);
+  if (controls.error) return send(ctx, controls.error);
+  return ctx.reply(ctx.expand(CARD, await ctx.write(CARD, id, { ...fields, ...(controls.controls ? { spending_controls: controls.controls } : {}) }, 'issuing.card.update')));
+}

package/src/semantics/payment_intents.ts

@@ -1,11 +1,10 @@
 // Stripe's payment_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 type { Row } from '../engine/common.ts';
 import { PI, TYPES_GIVEN } from '../engine/payment-intents.ts';
-import { asBool, mintClientSecret, nowUnix, validateMoney, verifyMicrodeposits } from '../engine/stripe.ts';
-import { afterCharge, beginBankDebit, cancelAuthorization, captureAuthorization, confirmIntent, confirmOnly, fundFromCashBalance, incrementTooSmall, methodFromData, mintCharge, mintMandate, payInvoiceOf, paymentIntentsLoad, paymentIntentsSend, search } from './shared.ts';
-
+import { asBool, mintClientSecret, nowUnix, validateMoney } from '../engine/stripe.ts';
+import { confirmIntent, intentFields, confirmOnly, methodFromData, paymentIntentsSend } from './shared.ts';
+import { cancelAuthorization, paymentIntentsLoad } from './shared.ts';
 export async function PostPaymentIntents(ctx: HandlerContext): Promise<Response> {
   const params = ctx.params;
   const bad = validateMoney(params);
@@ -51,15 +50,20 @@ export async function PostPaymentIntents(ctx: HandlerContext): Promise<Response>
       payment_method_types,
       ...(Array.isArray(params.allowed_payment_method_types) ? { allowed_payment_method_types: payment_method_types } : {}),
       payment_method_options: (params.payment_method_options as object) ?? {},
-      ...rest,
+      ...intentFields(rest),
     },
     'payment_intent.create',
   );
   if (Array.isArray(given)) await ctx.record(TYPES_GIVEN, { payment_intent: id }, id);
-  if (asBool(confirmNow)) return confirmIntent(ctx, body, {});
+  if (asBool(confirmNow)) return confirmIntent(ctx, body, { ...params, payment_method: rest.payment_method });
   return ctx.reply(ctx.expand(PI, body));
 }
 
+
+// source: spec:GetPaymentIntentsSearch "Search for PaymentIntents"
+
+
+
 export async function PostPaymentIntentsIntentCancel(ctx: HandlerContext): Promise<Response> {
   const loaded = paymentIntentsLoad(ctx, 'PostPaymentIntentsIntentCancel');
   if ('answer' in loaded) return loaded.answer;
@@ -70,14 +74,3 @@ export async function PostPaymentIntentsIntentCancel(ctx: HandlerContext): Promi
   if (held && held.captured === false && held.refunded !== true) await cancelAuthorization(ctx, held);
   return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(loaded.pi.id), { status: 'canceled', cancellation_reason, amount_capturable: 0 }, 'payment_intent.canceled')));
 }
-
-export async function PostPaymentIntentsIntentConfirm(ctx: HandlerContext): Promise<Response> {
-  const loaded = paymentIntentsLoad(ctx, 'PostPaymentIntentsIntentConfirm');
-  if ('answer' in loaded) return loaded.answer;
-  const given = ctx.params;
-  const { expand: _e, payment_method_data: data, mandate_data: _mandate, ...params } = given;
-  // a confirm's payment_method_data makes the method it pays with; neither it nor mandate_data is a field of the intent
-  const made = await methodFromData(ctx, data);
-  return confirmIntent(ctx, loaded.pi, made ? { ...params, payment_method: made } : params);
-}
-

package/src/semantics/payment_methods.ts

@@ -1,11 +1,8 @@
 // Stripe's payment_methods 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 type { Row } from '../engine/common.ts';
-import { noBilling, PM } from '../engine/payment-methods.ts';
-import { declineFor, paymentMethodSubObject } from '../engine/stripe.ts';
-import { afterSuccessOf, at, attachable, attachPaymentMethod, created, fail, pmMissing } from './shared.ts';
-
+import { PM } from '../engine/payment-methods.ts';
+import { at, pmMissing } from './shared.ts';
 export async function GetPaymentMethodsPaymentMethod(ctx: HandlerContext): Promise<Response> {
   const m = ctx.get(PM, at(ctx, 'payment_method'));
   return m ? ctx.reply(m) : pmMissing(ctx, at(ctx, 'payment_method'));
@@ -14,27 +11,7 @@ export async function GetPaymentMethodsPaymentMethod(ctx: HandlerContext): Promi
 // the raw card number, cvc and bank account number are never echoed: the modeled sub-object is
 // what the PaymentMethod carries, with the decline outcome its card implies, so a later charge
 // naming it only by id declines the same way
-export async function PostPaymentMethods(ctx: HandlerContext): Promise<Response> {
-  const params = ctx.params;
-  const pmType = typeof params.type === 'string' ? params.type : 'card';
-  const { card: _card, sepa_debit: _sepa, us_bank_account: _ach, type: _t, ...rest } = params;
-  const sub = paymentMethodSubObject(pmType, params);
-  const declineOutcome = pmType === 'card' ? (declineFor(() => undefined, params) ?? null) : null;
-  // and what Stripe does after its card succeeds (a dispute, a review), which a later charge naming it by id brings
-  const afterSuccess = pmType === 'card' ? afterSuccessOf(ctx, params.card) : undefined;
-  // the billing details the create gives are the method's (docs.stripe.com/api/payment_methods/create#create_payment_method-billing_details)
-  const given = rest.billing_details && typeof rest.billing_details === 'object' ? (rest.billing_details as Row) : {};
-  return ctx.reply(await created(ctx, PM, { ...rest, type: pmType, customer: null, livemode: false, billing_details: { ...noBilling, ...given }, ...sub, _declineOutcome: declineOutcome, ...(afterSuccess ? { _afterSuccess: afterSuccess } : {}) }, {}));
-}
 
-export async function PostPaymentMethodsPaymentMethodAttach(ctx: HandlerContext): Promise<Response> {
-  const id = at(ctx, 'payment_method');
-  const customer = typeof ctx.params.customer === 'string' ? ctx.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}'`, 400, 'resource_missing');
-  if (!attachable(ctx, id)) return pmMissing(ctx, id);
-  return ctx.reply(await attachPaymentMethod(ctx, id, customer));
-}
 
 export async function PostPaymentMethodsPaymentMethodDetach(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'payment_method');

package/src/semantics/payouts.ts

@@ -1,10 +1,8 @@
 // Stripe's payouts 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 { inRange } from '../engine/common.ts';
 import { validateMoney } from '../engine/stripe.ts';
-import { account, asOf, at, created, fail, kept, list, newest, noExternalAccount, payoutBank, payoutDefaults, payoutMissing, refusePayout, send, settlePayout, where } from './shared.ts';
-
+import { account, asOf, created, kept, list, newest, fail, noExternalAccount, payoutBank, payoutDefaults, refusePayout, send, settlePayout } from './shared.ts';
 export async function PostPayouts(ctx: HandlerContext): Promise<Response> {
   const bad = validateMoney(ctx.params);
   if (bad) return send(ctx, bad);
@@ -21,3 +19,11 @@ export async function PostPayouts(ctx: HandlerContext): Promise<Response> {
   return ctx.reply(await created(ctx, 'payout', { ...ctx.params, id }, { status: 'pending', ...payoutDefaults(ctx), balance_transaction: bt, destination: acct ? payoutBank(ctx, acct, currency) : null, ...(acct ? { _account: acct } : {}) }));
 }
 
+
+// source: https://docs.stripe.com/connect/authentication "Stripe-Account header"
+// source: https://docs.stripe.com/payouts "paid"
+export async function GetPayouts(ctx: HandlerContext): Promise<Response> {
+  const acct = account(ctx);
+  const payouts = newest(ctx, 'payout').filter((p) => (kept(ctx, 'payout', p, '_account') ?? null) === (acct ?? null));
+  return list(ctx, 'payout', payouts.map((p) => asOf(ctx, p)));
+}

package/src/semantics/prices.ts

@@ -4,7 +4,6 @@ import type { HandlerContext } from '@volter/world-core';
 import type { Row } from '../engine/common.ts';
 import { asBool } from '../engine/stripe.ts';
 import { at, created, fail, list, newest, tieredPrice, where } from './shared.ts';
-
 // `type` is not stored (it collides with the tree's discriminator), so `recurring` stands for it
 export async function GetPrices(ctx: HandlerContext): Promise<Response> {
   return list(ctx, 'price', where(ctx, newest(ctx, 'price'), {

package/src/semantics/products.ts

@@ -2,16 +2,7 @@
 // handler contract's context, computing with the engine (../engine/).
 import type { HandlerContext } from '@volter/world-core';
 import { asBool, nowUnix } from '../engine/stripe.ts';
-import { alreadyAttached, at, created, fail, search, featureMissing, kept, list, newest, pricedProductRefused, productFeature, productMissing, where } from './shared.ts';
-
-export async function DeleteProductsId(ctx: HandlerContext): Promise<Response> {
-  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 });
-}
-
+import { created, list, newest, where } from './shared.ts';
 export async function GetProducts(ctx: HandlerContext): Promise<Response> {
   return list(ctx, 'product', where(ctx, newest(ctx, 'product'), {
     active: (p, v) => asBool(p.active) === asBool(v),
@@ -23,8 +14,7 @@ export async function PostProducts(ctx: HandlerContext): Promise<Response> {
   return ctx.reply(await created(ctx, 'product', ctx.params, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: nowUnix(ctx.occurredAt) }));
 }
 
-/** `GET /v1/products/search?query=`: the products Stripe's search language selects (Ponder's catalog probes). */
+/** `GET /v1/products/search?query=`: the products Stripe's search language selects. */
 // source: spec:GetProductsSearch "Search for products you’ve previously created using Stripe’s"
-export async function GetProductsSearch(ctx: HandlerContext): Promise<Response> {
-  return search(ctx, 'product');
-}
+
+// source: spec:PostProductsProductFeatures "Creates a product_feature"

package/src/semantics/promotion_codes.ts

@@ -3,7 +3,6 @@
 import type { HandlerContext } from '@volter/world-core';
 import { asBool } from '../engine/stripe.ts';
 import { created, fail, list, newest, where } from './shared.ts';
-
 export async function GetPromotionCodes(ctx: HandlerContext): Promise<Response> {
   return list(ctx, 'promotion_code', where(ctx, newest(ctx, 'promotion_code'), {
     code: (p, v) => p.code === v,

package/src/semantics/radar.ts

@@ -2,8 +2,7 @@
 // handler contract's context, computing with the engine (../engine/).
 import type { HandlerContext } from '@volter/world-core';
 import { VL, VLI } from '../engine/radar.ts';
-import { at, created, fail, list, listMissing, newest, radarSyncItems } from './shared.ts';
-
+import { created, fail, listMissing, radarSyncItems } from './shared.ts';
 export async function PostRadarValueListItems(ctx: HandlerContext): Promise<Response> {
   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');
@@ -13,4 +12,3 @@ export async function PostRadarValueListItems(ctx: HandlerContext): Promise<Resp
   await radarSyncItems(ctx, listId);
   return ctx.reply(item);
 }
-

package/src/semantics/refunds.ts

@@ -1,15 +1,6 @@
-// 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';
-
-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'));
-}
-
+import { type HandlerContext } from '@volter/world-core';
+import { refundCharge, target } from './shared.ts';
 export async function PostRefunds(ctx: HandlerContext): Promise<Response> {
   const ch = target(ctx);
   return ch instanceof Response ? ch : refundCharge(ctx, ch, ctx.params);
 }
-