@volter/twin-stripe 2.0.38 → 3.0.0

package/src/semantics/billing.ts

@@ -1,216 +0,0 @@
-// Billing semantics: meters (how usage events aggregate), the meter events that report usage and
-// the summaries that aggregate them, prepaid credit grants and the balance they leave, and usage
-// alerts. The machines in ../manifest.ts say how a meter and an alert move. Lists and retrieves
-// with no scoping of their own are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { at, created, fail, list, newest, path, where, type Row } from './shared.ts';
-
-const METER = 'billing.meter';
-const meterMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such meter: '${id}'`, 404, 'resource_missing');
-const objectOf = (v: unknown): Row => (v && typeof v === 'object' ? (v as Row) : {});
-
-// a meter needs a display name, the event name it counts, and how it aggregates (sum or count)
-const createMeter: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const displayName = typeof params.display_name === 'string' ? params.display_name : '';
-  if (!displayName) return fail(ctx, 'Missing required param: display_name.', 400, 'parameter_missing');
-  if (!((params.event_name as string) ?? '')) return fail(ctx, 'Missing required param: event_name.', 400, 'parameter_missing');
-  const formula = objectOf(params.default_aggregation).formula;
-  if (typeof formula !== 'string' || !formula) return fail(ctx, 'Missing required param: default_aggregation[formula] (sum or count).', 400, 'parameter_missing');
-  return ctx.reply(
-    await created(ctx, METER, params, {
-      status: 'active', livemode: false,
-      customer_mapping: (params.customer_mapping as object) ?? { event_payload_key: 'stripe_customer_id', type: 'by_id' },
-      event_time_window: (params.event_time_window as string) ?? null,
-      value_settings: (params.value_settings as object) ?? { event_payload_key: 'value' },
-      status_transitions: { deactivated_at: null }, updated: ctx.now(),
-    }),
-  );
-};
-
-function activation(kind: 'deactivate' | 'reactivate'): Semantics {
-  return async (ctx) => {
-    const id = at(ctx, 'id');
-    const m = ctx.get(METER, id);
-    if (!m) return meterMissing(ctx, id);
-    const refused = ctx.legal(METER, 'status', kind === 'deactivate' ? 'PostBillingMetersIdDeactivate' : 'PostBillingMetersIdReactivate', m.status, undefined, id);
-    if (refused) return ctx.refuse(refused);
-    const fields = { ...(kind === 'deactivate' ? { status: 'inactive', status_transitions: { deactivated_at: ctx.now() } } : { status: 'active', status_transitions: { deactivated_at: null } }), updated: ctx.now() };
-    return ctx.reply(await ctx.write(METER, id, fields, `billing_meter.${kind}`));
-  };
-}
-
-// a meter event has no id of its own on Stripe (it carries an `identifier`); its object is billing.meter_event
-const reportUsage: Semantics = async (ctx) => {
-  const params = ctx.params;
-  if (typeof params.event_name !== 'string' || !params.event_name) return fail(ctx, 'Missing required param: event_name.', 400, 'parameter_missing');
-  const payload = objectOf(params.payload);
-  const body = await created(ctx, 'billing.meter_event', { ...params }, {
-    livemode: false, timestamp: params.timestamp !== undefined ? Math.trunc(Number(params.timestamp)) : ctx.now(),
-    identifier: payload.identifier ?? null, payload,
-  });
-  return ctx.reply({ ...body, object: 'billing.meter_event' });
-};
-
-// the meter's events for one customer in [start_time, end_time), aggregated by its formula
-const eventSummaries: Semantics = async (ctx) => {
-  const id = at(ctx, 'id');
-  const m = ctx.get(METER, id);
-  if (!m) return meterMissing(ctx, id);
-  const params = ctx.params;
-  const customer = typeof params.customer === 'string' ? params.customer : '';
-  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-  if (params.start_time === undefined) return fail(ctx, 'Missing required param: start_time.', 400, 'parameter_missing');
-  if (params.end_time === undefined) return fail(ctx, 'Missing required param: end_time.', 400, 'parameter_missing');
-  const startTime = Math.trunc(Number(params.start_time) || 0);
-  const endTime = Math.trunc(Number(params.end_time) || 0);
-  // "Must be aligned with minute boundaries" (start_time, end_time); "For hourly granularity, start and end times must
-  // align with hour boundaries … For daily granularity, … with UTC day boundaries (00:00 UTC)" (value_grouping_window;
-  // the served spec). Where the documentation stops and the twin decides: Stripe documents no error for it, so the
-  // twin answers a 400 naming the parameter and the boundary.
-  const window = params.value_grouping_window === 'hour' ? 3600 : params.value_grouping_window === 'day' ? 86_400 : 60;
-  const unit = window === 3600 ? 'hour' : window === 86_400 ? 'UTC day' : 'minute';
-  for (const [name, t] of [['start_time', startTime], ['end_time', endTime]] as const) {
-    if (t % window !== 0) return fail(ctx, `Invalid ${name}: ${t} is not aligned with ${unit} boundaries.`, 400);
-  }
-  const mapKey = typeof objectOf(m.customer_mapping).event_payload_key === 'string' ? String(objectOf(m.customer_mapping).event_payload_key) : 'stripe_customer_id';
-  const valueKey = typeof objectOf(m.value_settings).event_payload_key === 'string' ? String(objectOf(m.value_settings).event_payload_key) : 'value';
-  const formula = (objectOf(m.default_aggregation).formula as string) ?? 'sum';
-  let aggregate = 0;
-  for (const ev of ctx.rowsRaw('billing.meter_event', { withDeleted: true })) {
-    if (ev.event_name !== String(m.event_name ?? '')) continue;
-    const ts = Number(ev.timestamp) || 0;
-    if (ts < startTime || ts >= endTime) continue;
-    const payload = objectOf(ev.payload);
-    if (String(payload[mapKey] ?? '') !== customer) continue;
-    aggregate += formula === 'count' ? 1 : Number(payload[valueKey]) || 0;
-  }
-  return ctx.reply({
-    object: 'list', url: path(ctx), has_more: false,
-    data: [{ id: `mtrusg_twin_${id}_${customer}`, object: 'billing.meter_event_summary', meter: id, aggregated_value: aggregate, start_time: startTime, end_time: endTime, livemode: false }],
-  });
-};
-
-// ── credit grants: a customer's prepaid credit, paid or promotional, in a monetary amount ──
-
-const GRANT = 'billing.credit_grant';
-const grantMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such credit grant: '${id}'`, 404, 'resource_missing');
-
-const createGrant: Semantics = async (ctx) => {
-  const params = ctx.params;
-  const customer = typeof params.customer === 'string' ? 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 category = typeof params.category === 'string' ? params.category : '';
-  if (category !== 'paid' && category !== 'promotional') return fail(ctx, 'Invalid category: must be paid or promotional.', 400, 'parameter_invalid_string_enum');
-  const monetary = params.amount && typeof params.amount === 'object' ? objectOf((params.amount as Row).monetary) : undefined;
-  if (!monetary || monetary.value === undefined || monetary.currency === undefined) return fail(ctx, 'Missing required param: amount[monetary][value] and amount[monetary][currency].', 400, 'parameter_missing');
-  return ctx.reply(
-    await created(ctx, GRANT, { customer }, {
-      category, livemode: false, name: params.name ?? null,
-      amount: { type: 'monetary', monetary: { currency: String(monetary.currency), value: Math.trunc(Number(monetary.value) || 0) } },
-      applicability_config: params.applicability_config && typeof params.applicability_config === 'object' ? params.applicability_config : { scope: { price_type: 'metered' } },
-      effective_at: params.effective_at !== undefined ? Math.trunc(Number(params.effective_at)) : ctx.now(),
-      expires_at: params.expires_at !== undefined ? Math.trunc(Number(params.expires_at)) : null,
-      priority: params.priority !== undefined ? Math.trunc(Number(params.priority)) : 50,
-      voided_at: null, metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {}, updated: ctx.now(),
-    }),
-  );
-};
-
-// expiring or voiding a grant stamps the instant; it no longer counts toward the balance
-function endGrant(kind: 'expire' | 'void'): Semantics {
-  return async (ctx) => {
-    const id = at(ctx, 'id');
-    if (!ctx.get(GRANT, id)) return grantMissing(ctx, id);
-    return ctx.reply(await ctx.write(GRANT, id, { ...(kind === 'void' ? { voided_at: ctx.now() } : { expires_at: ctx.now() }), updated: ctx.now() }, `credit_grant.${kind}`));
-  };
-}
-
-// only the expiry and metadata change
-const updateGrant: Semantics = async (ctx) => {
-  const id = at(ctx, 'id');
-  if (!ctx.get(GRANT, id)) return grantMissing(ctx, id);
-  const patch: Row = { updated: ctx.now() };
-  if (ctx.params.expires_at !== undefined) patch.expires_at = Math.trunc(Number(ctx.params.expires_at));
-  if (ctx.params.metadata !== undefined) patch.metadata = ctx.params.metadata;
-  return ctx.reply(await ctx.write(GRANT, id, patch, 'credit_grant.update'));
-};
-
-// the customer's live (unvoided, unexpired) monetary grants, summed per currency
-const creditBalance: 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 now = Number(ctx.now());
-  const byCurrency: Record<string, number> = {};
-  for (const g of ctx.rows(GRANT)) {
-    if (g.customer !== customer || g.voided_at != null) continue;
-    if (typeof g.expires_at === 'number' && g.expires_at <= now) continue;
-    const monetary = objectOf(objectOf(g.amount).monetary);
-    const cur = String(monetary.currency ?? 'usd');
-    byCurrency[cur] = (byCurrency[cur] ?? 0) + (Number(monetary.value) || 0);
-  }
-  const balances = Object.entries(byCurrency).map(([currency, value]) => ({
-    available_balance: { type: 'monetary', monetary: { currency, value } },
-    ledger_balance: { type: 'monetary', monetary: { currency, value } },
-  }));
-  return ctx.reply({ object: 'billing.credit_balance_summary', customer, balances, livemode: false });
-};
-
-// ── alerts: a usage threshold on a meter ──
-
-const ALERT = 'billing.alert';
-
-const createAlert: Semantics = async (ctx) => {
-  const params = ctx.params;
-  if (params.alert_type !== 'usage_threshold') return fail(ctx, 'Invalid alert_type: must be usage_threshold.', 400, 'parameter_invalid_string_enum');
-  if (typeof params.title !== 'string' || !params.title) return fail(ctx, 'Missing required param: title.', 400, 'parameter_missing');
-  const ut = params.usage_threshold && typeof params.usage_threshold === 'object' ? (params.usage_threshold as Row) : undefined;
-  if (!ut || ut.gte === undefined || typeof ut.meter !== 'string') return fail(ctx, 'Missing required param: usage_threshold[gte] and usage_threshold[meter].', 400, 'parameter_missing');
-  // the spec requires recurrence too (one_time: the alert fires once)
-  if (ut.recurrence === undefined || ut.recurrence === '') return fail(ctx, 'Missing required param: usage_threshold[recurrence].', 400, 'parameter_missing');
-  if (!ctx.get(METER, ut.meter)) return fail(ctx, `No such meter: '${ut.meter}'`, 400, 'resource_missing');
-  return ctx.reply(
-    await created(ctx, ALERT, {}, {
-      alert_type: 'usage_threshold', livemode: false, status: 'active', title: params.title,
-      usage_threshold: { gte: Math.trunc(Number(ut.gte) || 0), meter: ut.meter, recurrence: String(ut.recurrence), filters: null },
-    }),
-  );
-};
-
-const listAlerts: Semantics = async (ctx) =>
-  list(ctx, ALERT, where(ctx, newest(ctx, ALERT), {
-    alert_type: (a, v) => a.alert_type === v,
-    meter: (a, v) => objectOf(a.usage_threshold).meter === v,
-  }));
-
-function alertMove(kind: 'activate' | 'deactivate' | 'archive', operationId: string): Semantics {
-  return async (ctx) => {
-    const id = at(ctx, 'id');
-    const a = ctx.get(ALERT, id);
-    if (!a) return fail(ctx, `No such alert: '${id}'`, 404, 'resource_missing');
-    const refused = ctx.legal(ALERT, 'status', operationId, a.status, undefined, id);
-    if (refused) return ctx.refuse(refused);
-    const status = kind === 'activate' ? 'active' : kind === 'deactivate' ? 'inactive' : 'archived';
-    return ctx.reply(await ctx.write(ALERT, id, { status }, `billing_alert.${kind}`));
-  };
-}
-
-export const billing: Record<string, Semantics> = {
-  PostBillingMeters: createMeter,
-  PostBillingMetersIdDeactivate: activation('deactivate'),
-  PostBillingMetersIdReactivate: activation('reactivate'),
-  PostBillingMeterEvents: reportUsage,
-  GetBillingMetersIdEventSummaries: eventSummaries,
-  PostBillingCreditGrants: createGrant,
-  PostBillingCreditGrantsIdExpire: endGrant('expire'),
-  PostBillingCreditGrantsIdVoid: endGrant('void'),
-  PostBillingCreditGrantsId: updateGrant,
-  GetBillingCreditBalanceSummary: creditBalance,
-  PostBillingAlerts: createAlert,
-  GetBillingAlerts: listAlerts,
-  PostBillingAlertsIdActivate: alertMove('activate', 'PostBillingAlertsIdActivate'),
-  PostBillingAlertsIdDeactivate: alertMove('deactivate', 'PostBillingAlertsIdDeactivate'),
-  PostBillingAlertsIdArchive: alertMove('archive', 'PostBillingAlertsIdArchive'),
-};