@volter/twin-stripe 2.0.37 → 3.0.0

package/src/semantics/credit-notes.ts

@@ -1,168 +0,0 @@
-// Credit note semantics. A credit note credits part of an invoice: pre_payment while the invoice
-// is unpaid (it lowers what is owed), post_payment once paid. The invoice carries the sums of its
-// issued credit notes, re-derived on every change so voiding one returns the invoice to where it
-// was. The machine in ../manifest.ts says a credit note is voided once. The list is the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { paginate } from '../stripe-twin.ts';
-import { refundCharge } from './refunds.ts';
-import { at, created, fail, path, type Row } from './shared.ts';
-
-const CN = 'credit_note';
-const noteMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such credit note: '${id}'`, 404, 'resource_missing');
-
-/** The credit note the request describes (the `amount` form: one custom line), or Stripe's refusal. */
-function build(ctx: SemanticsContext, id: string): Row | Response {
-  const params = ctx.params;
-  const invoiceId = typeof params.invoice === 'string' ? params.invoice : '';
-  if (!invoiceId) return fail(ctx, 'Missing required param: invoice.', 400, 'parameter_missing');
-  const invoice = ctx.get('invoice', invoiceId);
-  if (!invoice) return fail(ctx, `No such invoice: '${invoiceId}'`, 404, 'resource_missing');
-  if (params.amount === undefined) return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
-  const amount = Number(params.amount);
-  if (!Number.isInteger(amount) || amount <= 0) return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
-  const vendorType = invoice.status === 'paid' ? 'post_payment' : 'pre_payment';
-  const outOfBand = Number(params.out_of_band_amount) || 0;
-  // a paid invoice's credit is paid back: "The sum of refunds, customer balance credits, and outside of Stripe credits
-  // must equal the post_payment_amount" (docs.stripe.com/api/credit_notes/create); the message's wording is the twin's
-  if (vendorType === 'post_payment') {
-    const split = (Number(params.refund_amount) || 0) + (Number(params.credit_amount) || 0) + outOfBand;
-    if (split !== amount) return fail(ctx, `The sum of refund_amount, credit_amount and out_of_band_amount (${split}) must equal the credit note's post_payment_amount (${amount}).`, 400, 'parameter_invalid_integer');
-  }
-  const line = {
-    object: 'credit_note_line_item', id: `cnli_${id}_1`, type: 'custom_line_item',
-    amount, description: typeof params.memo === 'string' ? params.memo : null,
-    // a custom line credits no invoice line: invoice_line_item ("ID of the invoice line item being credited") is left
-    // out, the served spec not letting it be null
-    discount_amount: 0, discount_amounts: [], livemode: false,
-    pretax_credit_amounts: [], quantity: null, tax_rates: [], taxes: [],
-    unit_amount: null, unit_amount_decimal: null,
-  };
-  return {
-    amount, amount_shipping: 0, created: ctx.now(), currency: typeof invoice.currency === 'string' ? invoice.currency : 'usd', customer: typeof invoice.customer === 'string' ? invoice.customer : null,
-    customer_balance_transaction: null,
-    // "The date when this credit note is in effect. Same as `created` unless overwritten" (the served spec)
-    discount_amount: 0, discount_amounts: [], effective_at: params.effective_at !== undefined ? Number(params.effective_at) : ctx.now(), invoice: invoiceId,
-    lines: { object: 'list', data: [line], has_more: false, total_count: 1, url: `/v1/credit_notes/${id}/lines` },
-    livemode: false, memo: params.memo ?? null, metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
-    number: `${invoiceId}-CN-01`, out_of_band_amount: outOfBand || null,
-    pdf: `https://files.twin.local/credit_notes/${id}.pdf`,
-    post_payment_amount: vendorType === 'post_payment' ? amount : 0,
-    pre_payment_amount: vendorType === 'pre_payment' ? amount : 0,
-    pretax_credit_amounts: [],
-    reason: typeof params.reason === 'string' ? params.reason : null,
-    refunds: [], shipping_cost: null, status: 'issued',
-    subtotal: amount, subtotal_excluding_tax: amount,
-    type: vendorType, total: amount, total_excluding_tax: amount, total_taxes: [],
-    voided_at: null,
-  };
-}
-
-/** The invoice's credit-note sums, from its issued credit notes; a pre-payment credit lowers what is owed. */
-async function syncInvoice(ctx: SemanticsContext, invoiceId: string): Promise<void> {
-  const inv = ctx.get('invoice', invoiceId);
-  if (!inv) return;
-  let pre = 0;
-  let post = 0;
-  for (const cn of ctx.rows(CN)) {
-    if (cn.invoice !== invoiceId || cn.status === 'void') continue;
-    if (cn.type === 'post_payment') post += Number(cn.amount) || 0;
-    else pre += Number(cn.amount) || 0;
-  }
-  const total = Number(inv.total ?? inv.amount_due) || 0;
-  const paid = Number(inv.amount_paid) || 0;
-  await ctx.write('invoice', invoiceId, { pre_payment_credit_notes_amount: pre, post_payment_credit_notes_amount: post, amount_remaining: Math.max(0, total - paid - pre) }, 'invoice.update');
-}
-
-// the preview computes the credit note without keeping it
-const preview: Semantics = async (ctx) => {
-  const id = 'cn_preview';
-  const cn = build(ctx, id);
-  return cn instanceof Response ? cn : ctx.reply({ object: CN, ...cn, id });
-};
-
-/** What a post-payment credit pays back: "Refunds: create a new refund (using refund_amount)"; "Customer balance credit:
- *  credit the customer's balance (using credit_amount) which will be automatically applied to their next invoice when
- *  it's finalized" (docs.stripe.com/api/credit_notes/create). The refund is made on the invoice's charge as a refund
- *  call makes it (refunds.ts); the credit is a customer balance transaction of type credit_note. Where the documentation
- *  stops and the twin decides: the refund carries no reason of its own. */
-async function payBack(ctx: SemanticsContext, id: string, cn: Row): Promise<Row | Response> {
-  const params = ctx.params;
-  const out: Row = {};
-  const refundAmount = Number(params.refund_amount) || 0;
-  if (refundAmount > 0) {
-    const invoice = ctx.get('invoice', String(cn.invoice));
-    const pi = typeof invoice?.payment_intent === 'string' ? ctx.get('payment_intent', invoice.payment_intent) : undefined;
-    const chargeId = typeof invoice?.charge === 'string' ? invoice.charge : typeof pi?.latest_charge === 'string' ? pi.latest_charge : undefined;
-    const charge = chargeId ? ctx.get('charge', chargeId) : undefined;
-    if (!charge) return fail(ctx, 'This invoice was not paid with a charge that can be refunded.', 400, 'invoice_no_charge_to_refund');
-    const answer = await refundCharge(ctx, charge, { amount: refundAmount });
-    if (answer.status >= 400) return answer;
-    const refund = (await answer.json()) as Row;
-    out.refunds = [{ amount_refunded: refundAmount, refund: refund.id, type: 'refund', payment_record_refund: null }];
-  }
-  const creditAmount = Number(params.credit_amount) || 0;
-  const customer = typeof cn.customer === 'string' ? cn.customer : undefined;
-  if (creditAmount > 0 && customer) {
-    const ending = (Number(ctx.get('customer', customer)?.balance) || 0) - creditAmount;
-    const txn = await created(ctx, 'customer_balance_transaction', { customer, amount: -creditAmount, currency: cn.currency, credit_note: id, invoice: cn.invoice }, {
-      ending_balance: ending, type: 'credit_note', livemode: false, metadata: {}, description: null, checkout_session: null,
-    });
-    await ctx.write('customer', customer, { balance: ending }, `customer.balance_adjusted:${String(txn.id)}`);
-    out.customer_balance_transaction = txn.id;
-  }
-  return out;
-}
-
-const create: Semantics = async (ctx) => {
-  const id = ctx.mint(CN);
-  const cn = build(ctx, id);
-  if (cn instanceof Response) return cn;
-  const paid = cn.type === 'post_payment' ? await payBack(ctx, id, cn) : {};
-  if (paid instanceof Response) return paid;
-  const body = await created(ctx, CN, { id, ...cn, ...paid }, {});
-  await syncInvoice(ctx, String(cn.invoice));
-  return ctx.reply(body);
-};
-
-const retrieve: Semantics = async (ctx) => {
-  const c = ctx.get(CN, at(ctx, 'id'));
-  return c ? ctx.reply(c) : noteMissing(ctx, at(ctx, 'id'));
-};
-
-const lines: Semantics = async (ctx) => {
-  const c = ctx.get(CN, at(ctx, 'credit_note'));
-  if (!c) return noteMissing(ctx, at(ctx, 'credit_note'));
-  const l = c.lines as { data?: Row[] } | undefined;
-  const { page, hasMore } = paginate(Array.isArray(l?.data) ? l!.data! : [], ctx.params);
-  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
-};
-
-const voidNote: Semantics = async (ctx) => {
-  const id = at(ctx, 'id');
-  const c = ctx.get(CN, id);
-  if (!c) return noteMissing(ctx, id);
-  const refused = ctx.legal(CN, 'status', 'PostCreditNotesIdVoid', c.status, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  const voided = await ctx.write(CN, id, { status: 'void', voided_at: ctx.now() }, 'credit_note.void');
-  if (typeof c.invoice === 'string') await syncInvoice(ctx, c.invoice);
-  return ctx.reply(voided);
-};
-
-// only the memo and metadata change
-const update: Semantics = async (ctx) => {
-  const id = at(ctx, 'id');
-  if (!ctx.get(CN, id)) return noteMissing(ctx, id);
-  const patch: Row = {};
-  if (ctx.params.memo !== undefined) patch.memo = ctx.params.memo;
-  if (ctx.params.metadata !== undefined) patch.metadata = ctx.params.metadata;
-  return ctx.reply(await ctx.write(CN, id, patch, 'credit_note.update'));
-};
-
-export const creditNotes: Record<string, Semantics> = {
-  GetCreditNotesPreview: preview,
-  PostCreditNotes: create,
-  GetCreditNotesId: retrieve,
-  GetCreditNotesCreditNoteLines: lines,
-  PostCreditNotesIdVoid: voidNote,
-  PostCreditNotesId: update,
-};

package/src/semantics/ephemeral-keys.ts

@@ -1,34 +0,0 @@
-// Ephemeral key semantics: the short-lived key the mobile SDKs use, scoped to exactly one object.
-// It needs the Stripe-Version header; its secret is answered only by the create; deleting it
-// expires it early.
-import type { Semantics } from '@volter/world-core';
-import { at, fail } from './shared.ts';
-
-const create: Semantics = async (ctx) => {
-  const version = ctx.call.request.headers.get('stripe-version');
-  if (!version) return fail(ctx, 'You must pass the `Stripe-Version` header (e.g. via the apiVersion option) when creating an ephemeral key.', 400, 'parameter_missing');
-  const params = ctx.params;
-  const scopes: Array<[string, string]> = [];
-  if (typeof params.customer === 'string' && params.customer) scopes.push(['customer', params.customer]);
-  if (typeof params.issuing_card === 'string' && params.issuing_card) scopes.push(['issuing.card', params.issuing_card]);
-  if (typeof params.verification_session === 'string' && params.verification_session) scopes.push(['identity.verification_session', params.verification_session]);
-  if (scopes.length !== 1) return fail(ctx, 'You must pass exactly one of `customer`, `issuing_card`, or `verification_session`.', 400, 'parameter_missing');
-  const [scope, scopedId] = scopes[0]!;
-  if (scope === 'customer' && !ctx.get('customer', scopedId)) return fail(ctx, `No such customer: '${scopedId}'`, 400, 'resource_missing');
-  const id = ctx.mint('ephemeral_key');
-  const now = Number(ctx.now());
-  const associated_objects = [{ type: scope, id: scopedId }];
-  await ctx.write('ephemeral_key', id, { object: 'ephemeral_key', created: now, expires: now + 3600, livemode: false, associated_objects }, 'ephemeral_key.create');
-  return ctx.reply({ id, object: 'ephemeral_key', created: now, expires: now + 3600, livemode: false, secret: `ek_test_twin_${id}`, associated_objects });
-};
-
-const expire: Semantics = async (ctx) => {
-  const id = at(ctx, 'key');
-  if (!ctx.get('ephemeral_key', id)) return fail(ctx, `No such ephemeral key: '${id}'`, 404, 'resource_missing');
-  return ctx.reply(await ctx.write('ephemeral_key', id, { expires: ctx.now() }, 'ephemeral_key.delete'));
-};
-
-export const ephemeralKeys: Record<string, Semantics> = {
-  PostEphemeralKeys: create,
-  DeleteEphemeralKeysKey: expire,
-};

package/src/semantics/files.ts

@@ -1,143 +0,0 @@
-// File, file link, Identity and billing-portal semantics. A file is the uploaded document's object
-// (the twin keeps no bytes); a file link is answered, not kept. An Identity verification session is
-// created here and verified through the twin's own helper outside Stripe's surface; its reports
-// are the derived core's to list and read, as are file list and retrieve, session retrieve and
-// portal-configuration retrieve.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { asBool } from '../stripe-twin.ts';
-import { actingAccount } from './ledger.ts';
-import { at, created, fail, filePurposeRefused, list, mergeUpdate, newest, where, type Row } from './shared.ts';
-
-/** The type Stripe answers for an uploaded file: "The returned file type (for example, csv, pdf, jpg, or png)"
- *  (docs.stripe.com/api/files/object). Where the documentation stops and the twin decides: read from the name's
- *  extension (jpeg as jpg), and null for a name without one. */
-function fileType(name: string): string | null {
-  const ext = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
-  return ext ? (ext === 'jpeg' ? 'jpg' : ext) : null;
-}
-
-// multipart on Stripe; the file is described by the part uploaded: its name, its size in bytes and its type
-const createFile: Semantics = async (ctx) => {
-  const purpose = typeof ctx.params.purpose === 'string' ? ctx.params.purpose : '';
-  if (!purpose) return fail(ctx, 'Missing required param: purpose.', 400, 'parameter_missing');
-  const part = ctx.params.file && typeof ctx.params.file === 'object' ? (ctx.params.file as { name?: unknown; type?: unknown; size?: unknown }) : undefined;
-  const filename = typeof ctx.params.file === 'string' ? ctx.params.file : typeof part?.name === 'string' ? part.name : 'twin_upload';
-  const made = await created(ctx, 'file', { purpose }, {
-    filename, size: typeof part?.size === 'number' ? part.size : 0,
-    type: fileType(filename), title: null, expires_at: null, url: null,
-    links: { object: 'list', data: [], has_more: false, total_count: 0, url: '' },
-  });
-  await syncLinks(ctx, String(made.id));
-  return ctx.reply(ctx.get('file', String(made.id))!);
-};
-
-/** A file's links, kept in step with the links made to it, at the address Stripe lists them
- *  (/v1/file_links?file=…, the File object's example). */
-async function syncLinks(ctx: SemanticsContext, fileId: string): Promise<void> {
-  const data = newest(ctx, 'file_link').filter((l) => l.file === fileId);
-  await ctx.write('file', fileId, { links: { object: 'list', data, has_more: false, url: `/v1/file_links?file=${fileId}` } }, 'file.links_synced');
-}
-
-/** The purposes a file link may be made to: "The file's `purpose` must be one of the following: …" (the served
- *  spec, POST /v1/file_links `file`). */
-const LINKABLE = ['business_icon', 'business_logo', 'customer_signature', 'dispute_evidence', 'finance_report_run', 'financial_account_statement', 'identity_document_downloadable', 'issuing_regulatory_reporting', 'pci_document', 'selfie', 'sigma_scheduled_query', 'tax_document_user_upload', 'terminal_android_apk', 'terminal_reader_splashscreen'] as const;
-
-// `file` is required; a link is kept, has its own public url, and is listed on its file
-const createFileLink: Semantics = async (ctx) => {
-  if (ctx.params.file === undefined || ctx.params.file === '') return fail(ctx, 'Missing required param: file.', 400, 'parameter_missing');
-  const fileId = String(ctx.params.file);
-  const refused = filePurposeRefused(ctx, 'file', LINKABLE);
-  if (refused) return refused;
-  const id = ctx.mint('file_link');
-  const link = await created(ctx, 'file_link', { ...ctx.params, id, file: fileId }, {
-    url: `https://files.twin.local/links/${id}`, expired: false, livemode: false, metadata: {},
-    expires_at: ctx.params.expires_at !== undefined ? Number(ctx.params.expires_at) : null,
-  });
-  await syncLinks(ctx, fileId);
-  return ctx.reply(link);
-};
-
-// the person verifies at the session's url, Stripe Identity's hosted page (../screens/identity.tsx)
-const createVerificationSession: Semantics = async (ctx) => {
-  const id = ctx.mint('identity.verification_session');
-  return ctx.reply(await created(ctx, 'identity.verification_session', { ...ctx.params, id }, {
-    status: 'requires_input', livemode: false, client_secret: `${id}_secret_twin`, url: `https://verify.stripe.com/start/${id}`,
-    last_error: null, last_verification_report: null, verified_outputs: null, return_url: ctx.params.return_url ?? null,
-  }));
-};
-
-// ── the customer portal ──
-
-// the configuration defaults to the account's default one
-const createPortalSession: Semantics = async (ctx) => {
-  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');
-  const configuration = typeof ctx.params.configuration === 'string' && ctx.params.configuration
-    ? ctx.params.configuration
-    : (ctx.rowsRaw('billing_portal.configuration', { withDeleted: true }).find((c) => c.is_default)?.id ?? 'bpc_twin_default');
-  const id = ctx.mint('billing_portal.session');
-  return ctx.reply(
-    await created(ctx, 'billing_portal.session', {
-      id, customer, configuration, return_url: ctx.params.return_url ?? null, url: `https://billing.stripe.com/p/session/${id}`,
-      locale: ctx.params.locale ?? null, on_behalf_of: ctx.params.on_behalf_of ?? null, livemode: false,
-      // the account the session was made on (Stripe-Account), whose name the portal shows (screens/portal.tsx)
-      ...(actingAccount(ctx) ? { _brand_account: actingAccount(ctx) } : {}),
-    }, {}),
-  );
-};
-
-const PBC = 'billing_portal.configuration';
-
-/** A portal configuration's features, each filled where the request leaves it: every feature is answered (the served
- *  spec requires all five), as the create page's example answers a request that sets only customer_update and
- *  invoice_history: payment_method_update disabled, subscription_cancel disabled at_period_end with proration_behavior
- *  none and its five default reasons, subscription_update disabled with no allowed updates and proration_behavior none
- *  (docs.stripe.com/api/customer_portal/configurations/create); trial_update_behavior "Defaults to a value of
- *  `end_trial` if you don't set it during creation" (the served spec). Where the documentation stops and the twin
- *  decides: a feature the request leaves out is disabled, and schedule_at_period_end has no conditions. */
-const PORTAL_FEATURES: Row = {
-  customer_update: { allowed_updates: [], enabled: false },
-  invoice_history: { enabled: false },
-  payment_method_update: { enabled: false, payment_method_configuration: null },
-  subscription_cancel: { cancellation_reason: { enabled: false, options: ['too_expensive', 'missing_features', 'switched_service', 'unused', 'other'] }, enabled: false, mode: 'at_period_end', proration_behavior: 'none' },
-  subscription_update: { default_allowed_updates: [], enabled: false, proration_behavior: 'none', schedule_at_period_end: { conditions: [] }, trial_update_behavior: 'end_trial' },
-};
-const filled = (base: unknown, given: unknown): unknown => {
-  if (!given || typeof given !== 'object' || Array.isArray(given) || !base || typeof base !== 'object' || Array.isArray(base)) return given === undefined ? base : given;
-  const out: Row = { ...(base as Row) };
-  for (const [k, v] of Object.entries(given as Row)) out[k] = filled((base as Row)[k], v);
-  return out;
-};
-
-const createPortalConfiguration: Semantics = async (ctx) =>
-  ctx.reply(
-    await created(ctx, PBC, { ...ctx.params, business_profile: filled({ headline: null, privacy_policy_url: null, terms_of_service_url: null }, ctx.params.business_profile), features: filled(PORTAL_FEATURES, ctx.params.features) }, {
-      active: true, is_default: false, livemode: false,
-      login_page: { enabled: false, url: null },
-      metadata: {}, default_return_url: ctx.params.default_return_url ?? null,
-      updated: ctx.now(),
-    }),
-  );
-
-const listPortalConfigurations: Semantics = async (ctx) =>
-  list(ctx, PBC, where(ctx, newest(ctx, PBC), {
-    active: (c, v) => asBool(c.active) === asBool(v),
-    is_default: (c, v) => asBool(c.is_default) === asBool(v),
-  }));
-
-const updatePortalConfiguration: Semantics = async (ctx) => {
-  const id = at(ctx, 'configuration');
-  if (!ctx.get(PBC, id)) return ctx.notFound(PBC, id);
-  return ctx.reply(await ctx.write(PBC, id, mergeUpdate(ctx, PBC, id, { ...ctx.params, updated: ctx.now() }), 'billing_portal.configuration.update'));
-};
-
-export const files: Record<string, Semantics> = {
-  PostFiles: createFile,
-  PostFileLinks: createFileLink,
-  PostIdentityVerificationSessions: createVerificationSession,
-  PostBillingPortalSessions: createPortalSession,
-  PostBillingPortalConfigurations: createPortalConfiguration,
-  GetBillingPortalConfigurations: listPortalConfigurations,
-  PostBillingPortalConfigurationsConfiguration: updatePortalConfiguration,
-};