@volter/twin-stripe 0.1.1 → 2.0.0

package/src/semantics/webhook-endpoints.ts

@@ -0,0 +1,87 @@
+// Webhook endpoint semantics: registering a URL and the events it subscribes to. Delivery reads
+// the endpoints from the tree, signing each POST with the endpoint's own secret; a disabled one
+// (the machine in ../manifest.ts) receives nothing. Endpoint list, retrieve and delete are the derived core's.
+//
+// The Events API lists and retrieves the stored events of the account a request acts for: an event of a connected
+// account carries it ("Each event for a connected account contains a top-level `account` property that identifies the
+// connected account. Because the connected account owns the object that triggered the event, you must make API
+// requests for that object as the connected account", docs.stripe.com/connect/webhooks; the event's `account`: "The
+// connected account that originates the event", spec/openapi.json.gz), so a request with the Stripe-Account header
+// sees that account's events and one without it the platform's, those with no `account`. Where the documentation
+// stops and the twin decides: a platform request does not see its connected accounts' events.
+import { worldEnvValue, type Semantics, type SemanticsContext } from '@volter/world-core';
+import { asBool } from '../stripe-twin.ts';
+import { actingAccount } from './ledger.ts';
+import { at, created, fail, inRange, list, newest, where, type Row } from './shared.ts';
+
+const WE = 'webhook_endpoint';
+
+// The signing secret is the World's where the World set one. Stripe mints an endpoint's secret and the app is given it
+// (the dashboard, `stripe listen`); in a World the app's env is the World's, made at boot, so the World's value is the
+// one the app verifies with, and an endpoint the app registers is signed with it: the twin's decision, since Stripe
+// lets no one choose a secret. A Connect endpoint (`connect`) takes a Connect name first. Only a value the World sets
+// counts (worldEnvValue), never one the caller's shell passes through; with none (a twin outside a World) the twin
+// mints, as Stripe does.
+const ACCOUNT_SECRET_ENV = ['STRIPE_WEBHOOK_SECRET', 'STRIPE_WEBHOOK_SIGNING_SECRET', 'STRIPE_ENDPOINT_SECRET', 'STRIPE_WEBHOOK_SECRET_KEY', 'NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET'];
+const CONNECT_SECRET_ENV = ['STRIPE_CONNECT_WEBHOOK_SECRET', 'STRIPE_WEBHOOK_SECRET_CONNECT', 'STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET'];
+export function worldEndpointSecret(connect: boolean): string | undefined {
+  for (const name of connect ? [...CONNECT_SECRET_ENV, ...ACCOUNT_SECRET_ENV] : ACCOUNT_SECRET_ENV) { const value = worldEnvValue(name); if (value) return value; }
+  return undefined;
+}
+
+const create: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const url = typeof params.url === 'string' ? params.url : '';
+  if (!url) return fail(ctx, 'Missing required param: url.', 400, 'parameter_missing');
+  const enabledEvents = Array.isArray(params.enabled_events) ? params.enabled_events.map(String) : typeof params.enabled_events === 'string' ? [params.enabled_events] : undefined;
+  if (!enabledEvents || enabledEvents.length === 0) return fail(ctx, 'Missing required param: enabled_events.', 400, 'parameter_missing');
+  const id = ctx.mint(WE);
+  return ctx.reply(
+    await created(ctx, WE, { ...params, id }, {
+      url, enabled_events: enabledEvents, status: 'enabled', livemode: false, metadata: {},
+      api_version: '2024-06-20', application: null, description: typeof params.description === 'string' ? params.description : null,
+      secret: worldEndpointSecret(asBool(params.connect)) ?? `whsec_twin_${id}`,
+    }),
+  );
+};
+
+// `disabled` switches delivery off (status disabled) and back on; it is a parameter, not a field
+const update: Semantics = async (ctx) => {
+  const id = at(ctx, 'webhook_endpoint');
+  const we = ctx.get(WE, id);
+  if (!we) return ctx.notFound(WE, id);
+  const { disabled, ...fields }: Row = { ...ctx.params };
+  if (Array.isArray(ctx.params.enabled_events)) fields.enabled_events = ctx.params.enabled_events.map(String);
+  if (disabled !== undefined) return switchDelivery(ctx, id, we, fields, asBool(disabled));
+  return ctx.reply(await ctx.write(WE, id, fields, 'webhook_endpoint.update'));
+};
+
+/** `disabled` switches delivery off or back on (docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled). */
+async function switchDelivery(ctx: SemanticsContext, id: string, we: Row, fields: Row, off: boolean): Promise<Response> {
+  const status = off ? 'disabled' : 'enabled';
+  const refused = ctx.legal(WE, 'status', 'PostWebhookEndpointsWebhookEndpoint', we.status, status, id);
+  if (refused) return ctx.refuse(refused);
+  return ctx.reply(await ctx.write(WE, id, { ...fields, status }, 'webhook_endpoint.update'));
+}
+
+/** Whether a stored event is the acting account's (no `account`: the platform's). */
+const ownEvent = (ctx: SemanticsContext, e: Row): boolean => (typeof e.account === 'string' ? e.account : undefined) === actingAccount(ctx);
+
+const listEvents: Semantics = async (ctx) =>
+  list(ctx, 'event', where(ctx, newest(ctx, 'event').filter((e) => ownEvent(ctx, e)), {
+    type: (e, v) => e.type === v,
+    types: (e, v) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String(e.type)),
+    created: (e, v) => inRange(e.created, v),
+  }));
+
+const retrieveEvent: Semantics = async (ctx) => {
+  const e = ctx.get('event', at(ctx, 'id'));
+  return e && ownEvent(ctx, e) ? ctx.reply(e) : ctx.notFound('event', at(ctx, 'id'));
+};
+
+export const webhookEndpoints: Record<string, Semantics> = {
+  GetEvents: listEvents,
+  GetEventsId: retrieveEvent,
+  PostWebhookEndpoints: create,
+  PostWebhookEndpointsWebhookEndpoint: update,
+};

package/src/stripe-budget.ts

@@ -1,7 +1,7 @@
 // Stripe's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
 // bindings `liveStripeExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
 // window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
-// lives ONCE in the vendor-agnostic kernel (`@volter/twin` → `rateBudget.ts`). Read that module's
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
 // header for the full rationale AND for the honest list of what the guard does not guarantee (an
 // injected clock or ledger path still defeats it — it guards carelessness, not malice).
 //
@@ -54,7 +54,7 @@ import {
   type RateBudgetOptions,
   type RateBudgetReservation,
   type RateBudgetSnapshot,
-} from '@volter/twin';
+} from '@volter/world-core';
 
 const VENDOR = 'stripe';
 
@@ -175,7 +175,7 @@ export class StripeBudget extends RateBudget {
 
 /** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
  *  which one refused, and `err.kind` says why. */
-export { RateBudgetError as StripeBudgetError } from '@volter/twin';
-export type { RateBudgetErrorKind as StripeBudgetErrorKind } from '@volter/twin';
+export { RateBudgetError as StripeBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as StripeBudgetErrorKind } from '@volter/world-core';
 export type StripeBudgetReservation = RateBudgetReservation;
 export type StripeBudgetSnapshot = RateBudgetSnapshot;