@volter/twin-stripe 2.0.38 → 3.0.0

package/src/semantics/entitlements.ts

@@ -1,51 +1,10 @@
-// Entitlements semantics: features (unique by lookup_key) that products grant, and the features a
-// customer is entitled to now, derived from its live subscriptions' products. Feature retrieve is
-// the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { asBool, subscriptionItemPairs } from '../stripe-twin.ts';
-import { at, created, fail, list, newest, path, where, type Row, kept } from './shared.ts';
-
-const FEAT = 'entitlements.feature';
-
-/** A feature whose lookup_key an unarchived feature already has: "A unique key you provide as your own system identifier"
- *  (docs.stripe.com/api/entitlements/feature/create). */
-function lookupKeyTaken(ctx: SemanticsContext, lookupKey: string): Response {
-  return fail(ctx, `A feature with lookup_key '${lookupKey}' already exists.`, 400, 'resource_already_exists');
-}
-
-const create: Semantics = async (ctx) => {
-  const params = ctx.params;
-  if (typeof params.name !== 'string' || !params.name) return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
-  const lookupKey = typeof params.lookup_key === 'string' ? params.lookup_key : '';
-  if (!lookupKey) return fail(ctx, 'Missing required param: lookup_key.', 400, 'parameter_missing');
-  if (ctx.rowsRaw(FEAT, { withDeleted: true }).some((f) => f.lookup_key === lookupKey && !f._archived)) return lookupKeyTaken(ctx, lookupKey);
-  return ctx.reply(
-    await created(ctx, FEAT, {}, {
-      name: params.name, lookup_key: lookupKey, active: true, livemode: false,
-      metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
-    }),
-  );
-};
-
-const listFeatures: Semantics = async (ctx) =>
-  list(ctx, FEAT, where(ctx, newest(ctx, FEAT), {
-    lookup_key: (f, v) => f.lookup_key === v,
-    archived: (f, v) => asBool(kept(ctx, FEAT, f, '_archived')) === asBool(v),
-  }));
-
-// name, active and metadata change
-const update: Semantics = async (ctx) => {
-  const id = at(ctx, 'id');
-  if (!ctx.get(FEAT, id)) return ctx.notFound(FEAT, id);
-  const patch: Row = {};
-  if (ctx.params.name !== undefined) patch.name = ctx.params.name;
-  if (ctx.params.active !== undefined) {
-    patch.active = asBool(ctx.params.active);
-    patch._archived = undefined;
-  }
-  if (ctx.params.metadata !== undefined) patch.metadata = ctx.params.metadata;
-  return ctx.reply(await ctx.write(FEAT, id, patch, 'entitlements_feature.update'));
-};
+// Stripe's entitlements 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 { FEAT } from '../engine/entitlements.ts';
+import { asBool, subscriptionItemPairs } from '../engine/stripe.ts';
+import { at, created, fail, kept, list, lookupKeyTaken, newest, path, where } from './shared.ts';
 
 // a customer is entitled to every feature granted to a product its live subscriptions bill, as the product stood when
 // the subscription's current period began: "When a customer purchases or subscribes to a product with an attached
@@ -53,7 +12,7 @@ const update: Semantics = async (ctx) => {
 // create active entitlements for any product feature changes at the start of the next billing period"
 // (docs.stripe.com/billing/entitlements). Where the documentation stops and the twin decides: a feature removed from a
 // product is kept, the same way, until the next period begins.
-const activeEntitlements: Semantics = async (ctx) => {
+export async function GetEntitlementsActiveEntitlements(ctx: HandlerContext): Promise<Response> {
   const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
   if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
   if (!ctx.row('customer', customer, { withDeleted: true })) return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
@@ -84,11 +43,5 @@ const activeEntitlements: Semantics = async (ctx) => {
     if (feat) data.push({ id: `ent_twin_${customer}_${featId}`, object: 'entitlements.active_entitlement', feature: featId, lookup_key: feat.lookup_key, livemode: false });
   }
   return ctx.reply({ object: 'list', url: path(ctx), has_more: false, data });
-};
+}
 
-export const entitlements: Record<string, Semantics> = {
-  PostEntitlementsFeatures: create,
-  GetEntitlementsFeatures: listFeatures,
-  PostEntitlementsFeaturesId: update,
-  GetEntitlementsActiveEntitlements: activeEntitlements,
-};

package/src/semantics/events.ts

@@ -0,0 +1,44 @@
+// Stripe's Events API (the events family: the account's stored events, which the kernel keeps as each is sent), and how
+// Stripe renders the events its writes send (`data` and `values`, bound in the manifest's `events`).
+import type { EventWrite, HandlerContext, WriteHookContext } from '@volter/world-core';
+import { inRange } from '../engine/common.ts';
+import { planOf } from '../engine/plans.ts';
+import { embedIssuingAuthorizationCard, isValidApiVersion, PLATFORM_ACCOUNT_ID, TWIN_API_VERSION } from '../engine/stripe.ts';
+import { render } from '../engine/version.ts';
+import { at, connectionRevoked, finder, list, newest, ownEvent, where } from './shared.ts';
+
+// ── the events Stripe's writes send (the manifest's `events`: ./shared.ts STRIPE_EVENTS) ──
+
+/** An event's `data`: the object the write concerns, as Stripe sends it in the event's API version. A plan is stored as
+ *  the recurring price it is, and its own events carry the plan object; an Issuing authorization carries its full card;
+ *  the balance notice the drain writes carries the account's Balance. */
+export function data(ctx: WriteHookContext, write: EventWrite): Record<string, unknown> {
+  const object = write.storedType === '_balance_notice' ? (write.body.balance as Record<string, unknown>)
+    : write.storedType === 'price' && write.operation.startsWith('plan.') ? planOf(write.body)
+    : write.storedType === 'issuing_authorization' ? embedIssuingAuthorizationCard({ ...write.body }, finder(ctx))
+    : write.body;
+  return { object: render(object, eventVersion(write)) as Record<string, unknown> };
+}
+
+/** An event's further envelope values: the connected account it is about ("Each event for a connected account contains
+ *  a top-level `account` property that identifies the connected account", docs.stripe.com/connect/webhooks) — the
+ *  account a request acts as (Stripe-Account), a connected account's own account.updated, or the account whose books the
+ *  written row is kept on (its `_account`) — and the API version it is rendered in. A connected account whose OAuth
+ *  connection was revoked "can't be accessed by your platform" (docs.stripe.com/connect/oauth-reference): its events are
+ *  kept but no longer sent (`$send: false`), except the account.application.deauthorized that says so. */
+export function values(ctx: WriteHookContext, write: EventWrite, type: string): Record<string, unknown> {
+  const id = write.body.id;
+  const kept = typeof id === 'string' ? ctx.rowsRaw(write.storedType, { withDeleted: true }).find((r) => r.id === id)?._account : undefined;
+  const account = write.request?.headers.get('stripe-account')
+    ?? (write.storedType === 'account' && typeof id === 'string' && id !== PLATFORM_ACCOUNT_ID ? id : undefined)
+    ?? (write.storedType === '_balance_notice' && typeof write.body.account === 'string' ? write.body.account : undefined)
+    ?? (typeof kept === 'string' ? kept : undefined);
+  const withheld = account !== undefined && type !== 'account.application.deauthorized' && connectionRevoked(ctx, account);
+  return { $account: account, $version: eventVersion(write), ...(withheld ? { $send: false } : {}) };
+}
+
+/** The API version an event is rendered in: the one the writing request pinned, when it is one, else the served one. */
+const eventVersion = (write: EventWrite): string => {
+  const pinned = write.request?.headers.get('stripe-version');
+  return pinned && isValidApiVersion(pinned) ? pinned : TWIN_API_VERSION;
+};

package/src/semantics/index.ts

@@ -0,0 +1,111 @@
+// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families' files (each
+// handler named as its operation). Do not edit; add a handler to its family's file and generate again.
+import type { Handler } from '@volter/world-core';
+import * as account_links from './account_links.ts';
+import * as accounts from './accounts.ts';
+import * as apps from './apps.ts';
+import * as balance from './balance.ts';
+import * as balance_transactions from './balance_transactions.ts';
+import * as billing_portal from './billing_portal.ts';
+import * as charges from './charges.ts';
+import * as checkout from './checkout.ts';
+import * as coupons from './coupons.ts';
+import * as customers from './customers.ts';
+import * as disputes from './disputes.ts';
+import * as entitlements from './entitlements.ts';
+import * as invoice_payments from './invoice_payments.ts';
+import * as invoiceitems from './invoiceitems.ts';
+import * as invoices from './invoices.ts';
+import * as payment_intents from './payment_intents.ts';
+import * as payment_methods from './payment_methods.ts';
+import * as payouts from './payouts.ts';
+import * as prices from './prices.ts';
+import * as products from './products.ts';
+import * as promotion_codes from './promotion_codes.ts';
+import * as radar from './radar.ts';
+import * as refunds from './refunds.ts';
+import * as setup_intents from './setup_intents.ts';
+import * as subscription_items from './subscription_items.ts';
+import * as subscription_schedules from './subscription_schedules.ts';
+import * as subscriptions from './subscriptions.ts';
+import * as test_helpers from './test_helpers.ts';
+import * as transfers from './transfers.ts';
+
+export const stripeSemantics: Record<string, Handler> = {
+  DeleteInvoiceitemsInvoiceitem: invoiceitems.DeleteInvoiceitemsInvoiceitem,
+  DeleteInvoicesInvoice: invoices.DeleteInvoicesInvoice,
+  DeleteProductsId: products.DeleteProductsId,
+  DeleteSubscriptionItemsItem: subscription_items.DeleteSubscriptionItemsItem,
+  DeleteSubscriptionsSubscriptionExposedId: subscriptions.DeleteSubscriptionsSubscriptionExposedId,
+  DeleteTestHelpersTestClocksTestClock: test_helpers.DeleteTestHelpersTestClocksTestClock,
+  GetAccountsAccountExternalAccounts: accounts.GetAccountsAccountExternalAccounts,
+  GetAppsSecretsFind: apps.GetAppsSecretsFind,
+  GetBalance: balance.GetBalance,
+  GetBalanceTransactions: balance_transactions.GetBalanceTransactions,
+  GetBillingPortalConfigurations: billing_portal.GetBillingPortalConfigurations,
+  GetCharges: charges.GetCharges,
+  GetChargesCharge: charges.GetChargesCharge,
+  GetCustomersCustomer: customers.GetCustomersCustomer,
+  GetCustomersCustomerPaymentMethods: customers.GetCustomersCustomerPaymentMethods,
+  GetCustomersSearch: customers.GetCustomersSearch,
+  GetDisputesDispute: disputes.GetDisputesDispute,
+  GetEntitlementsActiveEntitlements: entitlements.GetEntitlementsActiveEntitlements,
+  GetInvoicePayments: invoice_payments.GetInvoicePayments,
+  GetInvoicesInvoice: invoices.GetInvoicesInvoice,
+  GetInvoicesInvoiceLines: invoices.GetInvoicesInvoiceLines,
+  GetPaymentMethodsPaymentMethod: payment_methods.GetPaymentMethodsPaymentMethod,
+  GetPrices: prices.GetPrices,
+  GetPricesPrice: prices.GetPricesPrice,
+  GetProducts: products.GetProducts,
+  GetProductsSearch: products.GetProductsSearch,
+  GetPromotionCodes: promotion_codes.GetPromotionCodes,
+  GetRefundsRefund: refunds.GetRefundsRefund,
+  GetSubscriptionItemsItem: subscription_items.GetSubscriptionItemsItem,
+  GetSubscriptionSchedulesSchedule: subscription_schedules.GetSubscriptionSchedulesSchedule,
+  GetSubscriptions: subscriptions.GetSubscriptions,
+  GetSubscriptionsSearch: subscriptions.GetSubscriptionsSearch,
+  GetSubscriptionsSubscriptionExposedId: subscriptions.GetSubscriptionsSubscriptionExposedId,
+  PostAccountLinks: account_links.PostAccountLinks,
+  PostAccounts: accounts.PostAccounts,
+  PostAccountsAccountLoginLinks: accounts.PostAccountsAccountLoginLinks,
+  PostAppsSecrets: apps.PostAppsSecrets,
+  PostAppsSecretsDelete: apps.PostAppsSecretsDelete,
+  PostBillingPortalConfigurations: billing_portal.PostBillingPortalConfigurations,
+  PostBillingPortalConfigurationsConfiguration: billing_portal.PostBillingPortalConfigurationsConfiguration,
+  PostBillingPortalSessions: billing_portal.PostBillingPortalSessions,
+  PostCheckoutSessions: checkout.PostCheckoutSessions,
+  PostCheckoutSessionsSessionExpire: checkout.PostCheckoutSessionsSessionExpire,
+  PostCoupons: coupons.PostCoupons,
+  PostCustomers: customers.PostCustomers,
+  PostCustomersCustomerBalanceTransactions: customers.PostCustomersCustomerBalanceTransactions,
+  PostInvoiceitems: invoiceitems.PostInvoiceitems,
+  PostInvoices: invoices.PostInvoices,
+  PostInvoicesCreatePreview: invoices.PostInvoicesCreatePreview,
+  PostInvoicesInvoiceFinalize: invoices.PostInvoicesInvoiceFinalize,
+  PostInvoicesInvoicePay: invoices.PostInvoicesInvoicePay,
+  PostInvoicesInvoiceSend: invoices.PostInvoicesInvoiceSend,
+  PostInvoicesInvoiceVoid: invoices.PostInvoicesInvoiceVoid,
+  PostPaymentIntents: payment_intents.PostPaymentIntents,
+  PostPaymentIntentsIntentCancel: payment_intents.PostPaymentIntentsIntentCancel,
+  PostPaymentIntentsIntentConfirm: payment_intents.PostPaymentIntentsIntentConfirm,
+  PostPaymentMethods: payment_methods.PostPaymentMethods,
+  PostPaymentMethodsPaymentMethodAttach: payment_methods.PostPaymentMethodsPaymentMethodAttach,
+  PostPaymentMethodsPaymentMethodDetach: payment_methods.PostPaymentMethodsPaymentMethodDetach,
+  PostPayouts: payouts.PostPayouts,
+  PostPrices: prices.PostPrices,
+  PostProducts: products.PostProducts,
+  PostPromotionCodes: promotion_codes.PostPromotionCodes,
+  PostRadarValueListItems: radar.PostRadarValueListItems,
+  PostRefunds: refunds.PostRefunds,
+  PostSetupIntents: setup_intents.PostSetupIntents,
+  PostSetupIntentsIntentConfirm: setup_intents.PostSetupIntentsIntentConfirm,
+  PostSubscriptionItems: subscription_items.PostSubscriptionItems,
+  PostSubscriptionItemsItem: subscription_items.PostSubscriptionItemsItem,
+  PostSubscriptionSchedules: subscription_schedules.PostSubscriptionSchedules,
+  PostSubscriptionSchedulesScheduleRelease: subscription_schedules.PostSubscriptionSchedulesScheduleRelease,
+  PostSubscriptions: subscriptions.PostSubscriptions,
+  PostSubscriptionsSubscriptionExposedId: subscriptions.PostSubscriptionsSubscriptionExposedId,
+  PostTestHelpersTestClocks: test_helpers.PostTestHelpersTestClocks,
+  PostTestHelpersTestClocksTestClockAdvance: test_helpers.PostTestHelpersTestClocksTestClockAdvance,
+  PostTransfers: transfers.PostTransfers,
+};

package/src/semantics/invoice_payments.ts

@@ -0,0 +1,18 @@
+// Stripe's invoice_payments 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 { INV, invoicePayment } from '../engine/invoices.ts';
+import { at, fail, list, newest } from './shared.ts';
+
+export async function GetInvoicePayments(ctx: HandlerContext): Promise<Response> {
+  const p = ctx.params;
+  const wanted = (p.payment as Row | undefined)?.payment_intent;
+  const items = newest(ctx, INV)
+    .filter((inv) => typeof p.invoice !== 'string' || inv.id === p.invoice)
+    .map(invoicePayment).filter((x): x is Row => !!x)
+    .filter((x) => typeof wanted !== 'string' || (x.payment as Row).payment_intent === wanted)
+    .filter((x) => typeof p.status !== 'string' || x.status === p.status);
+  return list(ctx, 'invoice_payment', items);
+}
+

package/src/semantics/invoiceitems.ts

@@ -0,0 +1,59 @@
+// Stripe's invoiceitems 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 { INV, linesOf } from '../engine/invoices.ts';
+import { nowUnix } from '../engine/stripe.ts';
+import { at, created, fail, invoiceMissing, itemMissing, pricedItem, resyncDraftLines, writeLines } from './shared.ts';
+
+// an item is deleted only while its invoice is still editable
+export async function DeleteInvoiceitemsInvoiceitem(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'invoiceitem');
+  const it = ctx.get('invoiceitem', id);
+  if (!it) return itemMissing(ctx, id);
+  const onInvoice = typeof it.invoice === 'string' ? ctx.get(INV, it.invoice) : undefined;
+  if (onInvoice && onInvoice.status !== 'draft') return fail(ctx, 'You cannot delete an invoice item that is attached to an invoice that is no longer editable.', 400, 'invoice_not_editable');
+  await ctx.write('invoiceitem', id, { deleted: true }, 'invoiceitem.delete');
+  if (typeof it.invoice === 'string') await resyncDraftLines(ctx, it.invoice);
+  return ctx.reply({ id, object: 'invoiceitem', deleted: true });
+}
+
+export async function PostInvoiceitems(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  const now = Number(nowUnix(ctx.occurredAt));
+  const qty = Number(params.quantity) || 1;
+  // the served version names the price in `pricing[price]` ("The pricing information for the invoice item", the served
+  // spec); an older version sends `price`. It is kept as the item's price, which the answer renders as `pricing`
+  // (../engine/version.ts)
+  const { pricing: pricingParam, ...stored } = params;
+  const given = (pricingParam as Row | undefined)?.price;
+  const priceRef = typeof given === 'string' && given ? given : typeof params.price === 'string' ? params.price : '';
+  const priced = priceRef ? pricedItem(ctx, priceRef, qty) : undefined;
+  if (priced instanceof Response) return priced;
+  const resolvedAmount = priced?.amount;
+  let resolvedCurrency = priced?.currency;
+  // only a draft invoice takes new items
+  const invoiceRef = typeof params.invoice === 'string' ? params.invoice : '';
+  let target: Row | undefined;
+  if (invoiceRef) {
+    target = ctx.get(INV, invoiceRef);
+    if (!target) return invoiceMissing(ctx, invoiceRef);
+    if (target.status !== 'draft') return fail(ctx, `This invoice cannot have invoice items added because it has status ${String(target.status)}.`, 400, 'invoice_not_editable');
+    if (resolvedCurrency === undefined && typeof target.currency === 'string') resolvedCurrency = target.currency;
+  }
+  // an invoice item is dated by `date`, not `created`; its currency is the price's, else the invoice's
+  const item = await created(ctx, 'invoiceitem', { ...stored, ...(priceRef ? { price: priceRef } : {}) }, {
+    livemode: false, discountable: true, proration: false, quantity: qty, quantity_decimal: String(qty),
+    period: { start: now, end: now }, currency: resolvedCurrency ?? 'usd',
+    ...(resolvedAmount !== undefined ? { amount: resolvedAmount } : {}),
+  }, { timeField: 'date' });
+  if (target) {
+    await writeLines(ctx, invoiceRef, [...linesOf(target), {
+      id: `il_${String(item.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(item.amount) || 0, currency: String(target.currency ?? item.currency ?? 'usd'),
+      quantity: qty, proration: false, invoice_item: item.id, price: item.price ?? null,
+      period: item.period ?? { start: now, end: now }, description: (item.description as string) ?? null,
+    }]);
+  }
+  return ctx.reply(item);
+}
+