@volter/twin-stripe 0.1.2 → 2.0.1

package/src/semantics/disputes.ts

@@ -0,0 +1,62 @@
+// Dispute semantics. A dispute is Stripe's to open, when a charge's cardholder disputes it: the test cards
+// that are disputed open one as their charge succeeds (./after-payment.ts). It is then listed, retrieved,
+// updated with evidence and closed. Closing concedes it (status → lost), the machine's move in
+// ../manifest.ts. Evidence is submitted with the update unless `submit` is false
+// (docs.stripe.com/api/disputes/update#update_dispute-submit), and the bank then decides it: in test mode, evidence whose
+// uncategorized_text is `winning_evidence` wins it and `losing_evidence` loses it (docs.stripe.com/testing#evidence);
+// a won dispute returns the disputed amount. Where the documentation stops and the twin decides: the bank decides at
+// once, and any other evidence leaves the dispute under review. List is the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { asBool } from '../stripe-twin.ts';
+import { settleDisputeWon } from './ledger.ts';
+import { at, fail, type Row } from './shared.ts';
+
+const disputeMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such dispute: '${id}'`, 404, 'resource_missing');
+
+const retrieve: Semantics = async (ctx) => {
+  const d = ctx.get('dispute', at(ctx, 'dispute'));
+  return d ? ctx.reply(d) : disputeMissing(ctx, at(ctx, 'dispute'));
+};
+
+const close: Semantics = async (ctx) => {
+  const id = at(ctx, 'dispute');
+  const d = ctx.get('dispute', id);
+  if (!d) return disputeMissing(ctx, id);
+  const refused = ctx.legal('dispute', 'status', 'PostDisputesDisputeClose', d.status, undefined, id);
+  if (refused) return ctx.refuse(refused);
+  return ctx.reply(await ctx.write('dispute', id, { status: 'lost' }, 'dispute.close'));
+};
+
+/** Evidence staged without submitting it (submit=false), or on a dispute already under review or decided. */
+async function keepEvidence(ctx: SemanticsContext, id: string, fields: Row): Promise<Response> {
+  return ctx.reply(await ctx.write('dispute', id, fields, 'dispute.update'));
+}
+
+const update: Semantics = async (ctx) => {
+  const id = at(ctx, 'dispute');
+  const d = ctx.get('dispute', id);
+  if (!d) return disputeMissing(ctx, id);
+  const params = ctx.params;
+  const given = params.evidence && typeof params.evidence === 'object' ? (params.evidence as Row) : {};
+  const evidence = { ...((d.evidence as Row | undefined) ?? {}), ...given };
+  const fields: Row = { evidence, ...(params.metadata && typeof params.metadata === 'object' ? { metadata: { ...((d.metadata as Row | undefined) ?? {}), ...(params.metadata as Row) } } : {}) };
+  const submit = params.submit === undefined ? true : asBool(params.submit);
+  const review = d.status === 'warning_needs_response' ? 'warning_under_review' : 'under_review';
+  if (!submit || ctx.legal('dispute', 'status', 'PostDisputesDispute', d.status, review, id)) return keepEvidence(ctx, id, fields);
+  const details = (d.evidence_details as Row | undefined) ?? {};
+  let body = await ctx.write('dispute', id, { ...fields, status: review, evidence_details: { ...details, has_evidence: true, submission_count: (Number(details.submission_count) || 0) + 1 } }, 'charge.dispute.updated');
+  const text = String(evidence.uncategorized_text ?? '');
+  const decided = review === 'under_review' ? (text.includes('winning_evidence') ? 'won' : text.includes('losing_evidence') ? 'lost' : undefined) : undefined;
+  if (decided && !ctx.legal('dispute', 'status', 'PostDisputesDispute', review, decided, id, 'vendor')) {
+    const bt = decided === 'won' ? await settleDisputeWon(ctx, id, Number(d.amount) || 0, String(d.currency ?? 'usd')) : undefined;
+    const kept = ((ctx.get('dispute', id)?.balance_transactions as unknown[] | undefined) ?? []);
+    body = await ctx.write('dispute', id, { status: decided, ...(bt ? { balance_transactions: [...kept, ctx.get('balance_transaction', bt) ?? bt] } : {}) }, 'charge.dispute.closed');
+  }
+  return ctx.reply(body);
+};
+
+export const disputes: Record<string, Semantics> = {
+  GetDisputesDispute: retrieve,
+  PostDisputesDispute: update,
+  PostDisputesDisputeClose: close,
+};

package/src/semantics/entitlements.ts

@@ -0,0 +1,94 @@
+// 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'));
+};
+
+// 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
+// feature, Stripe creates and manages an Active Entitlement for that customer and feature"; "Existing subscriptions will
+// 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) => {
+  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');
+  // each product a live subscription bills, with the start of the period it is billed for
+  const productIds = new Map<string, number>();
+  for (const sub of newest(ctx, 'subscription')) {
+    // a subscription entitles while it runs: not before its first payment (incomplete), nor once it has ended
+    // (docs.stripe.com/billing/entitlements; past_due keeps access during retries — that edge is the twin's reading)
+    if (sub.customer !== customer || !['active', 'trialing', 'past_due'].includes(String(sub.status))) continue;
+    const periodStart = Number(sub.current_period_start ?? sub.start_date ?? sub.created ?? 0);
+    for (const it of subscriptionItemPairs(sub)) {
+      const price = ctx.get('price', it.price);
+      if (price && typeof price.product === 'string') productIds.set(price.product, Math.max(productIds.get(price.product) ?? -Infinity, periodStart));
+    }
+  }
+  const seen = new Set<string>();
+  const data: Row[] = [];
+  for (const pf of ctx.rowsRaw('product_feature', { withDeleted: true })) {
+    const periodStart = productIds.get(String(pf._product));
+    if (periodStart === undefined) continue;
+    // attached by the period's start, and not removed before it
+    if (Number(pf._created ?? 0) > periodStart) continue;
+    if (pf.deleted && !(Number(pf._removed_at) > periodStart)) continue;
+    const featId = String(pf._feature ?? (pf.entitlement_feature as Row | undefined)?.id ?? pf.entitlement_feature);
+    if (seen.has(featId)) continue;
+    seen.add(featId);
+    const feat = ctx.get(FEAT, featId);
+    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/ephemeral-keys.ts

@@ -0,0 +1,34 @@
+// 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

@@ -0,0 +1,143 @@
+// 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,
+};