@firedrill-tools/stripe 0.1.1

package/firedrill/tools/stripe/lib/objects.mjs

@@ -0,0 +1,229 @@
+// Rendering stored rows as Stripe API objects (private fields stripped, `livemode` stamped from the actor,
+// derived fields recomputed) and `expand[]` handling from a fixed allow-list. Reads state, never writes it.
+
+import { allRows, getRow, invalid, livemode, nowSeconds } from "./state.mjs";
+
+const PREFIX_NAMESPACES = {
+  cus: "customers",
+  pm: "payment_methods",
+  pi: "payment_intents",
+  ch: "charges",
+  re: "refunds",
+  prod: "products",
+  price: "prices",
+  ii: "invoice_items",
+  in: "invoices",
+  sub: "subscriptions",
+};
+
+export const TYPES = Object.freeze({
+  customers: "customer",
+  payment_methods: "payment_method",
+  payment_intents: "payment_intent",
+  charges: "charge",
+  refunds: "refund",
+  products: "product",
+  prices: "price",
+  invoice_items: "invoiceitem",
+  invoices: "invoice",
+  subscriptions: "subscription",
+});
+
+/** Expandable properties per object type (one level; parents are expanded implicitly). */
+export const EXPANDABLE = Object.freeze({
+  balance: [],
+  customer: ["invoice_settings.default_payment_method"],
+  payment_method: ["customer"],
+  payment_intent: ["customer", "payment_method", "latest_charge"],
+  charge: ["customer", "payment_intent", "payment_method", "refunds"],
+  refund: ["charge", "payment_intent"],
+  product: ["default_price"],
+  price: ["product"],
+  invoiceitem: ["customer", "invoice"],
+  invoice: ["customer", "default_payment_method", "payments.data.payment.payment_intent", "lines.data.pricing.price_details.price", "parent.subscription_details.subscription"],
+  subscription: ["customer", "default_payment_method", "latest_invoice", "latest_invoice.payments.data.payment.payment_intent"],
+});
+
+/** Per-call view: the actor's mode plus memoised derived data (past-due customers). */
+export function makeView(context) {
+  const view = { context, now: nowSeconds(context), livemode: livemode(context), memo: {} };
+  return view;
+}
+
+function pastDueCustomers(view) {
+  if (view.memo.pastDue === undefined) {
+    const set = new Set();
+    for (const invoice of allRows(view.context, "invoices")) {
+      if (invoice.status === "open" && typeof invoice.due_date === "number" && invoice.due_date < view.now) set.add(invoice.customer);
+    }
+    view.memo.pastDue = set;
+  }
+  return view.memo.pastDue;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Renderers
+// ---------------------------------------------------------------------------------------------
+
+export function renderCustomer(view, row) {
+  return { ...row, delinquent: row.delinquent === true || pastDueCustomers(view).has(row.id), livemode: view.livemode };
+}
+
+export function renderPaymentMethod(view, row) {
+  const { outcome, ...rest } = row;
+  void outcome;
+  return { ...rest, livemode: view.livemode };
+}
+
+export function renderPaymentIntent(view, row) {
+  const { invoice, ...rest } = row;
+  void invoice;
+  const value = { ...rest, livemode: view.livemode };
+  if (value.last_payment_error !== null && typeof value.last_payment_error.payment_method === "string") {
+    const method = getRow(view.context, "payment_methods", value.last_payment_error.payment_method);
+    value.last_payment_error = { ...value.last_payment_error, payment_method: method === null ? value.last_payment_error.payment_method : renderPaymentMethod(view, method) };
+  }
+  return value;
+}
+
+export function renderCharge(view, row) {
+  return { ...row, livemode: view.livemode };
+}
+
+export function renderRefund(view, row) {
+  void view;
+  return { ...row };
+}
+
+export function renderProduct(view, row) {
+  return { ...row, livemode: view.livemode };
+}
+
+export function renderPrice(view, row) {
+  return { ...row, livemode: view.livemode };
+}
+
+export function renderInvoiceItem(view, row) {
+  return { ...row, livemode: view.livemode };
+}
+
+export function renderInvoice(view, row) {
+  return {
+    ...row,
+    livemode: view.livemode,
+    lines: { ...row.lines, data: row.lines.data.map((line) => ({ ...line, livemode: view.livemode })) },
+    payments: { ...row.payments, data: row.payments.data.map((payment) => ({ ...payment, livemode: view.livemode })) },
+  };
+}
+
+export function renderSubscription(view, row) {
+  return {
+    ...row,
+    livemode: view.livemode,
+    items: {
+      ...row.items,
+      data: row.items.data.map((item) => ({ ...item, price: { ...item.price, livemode: view.livemode }, plan: { ...item.plan, livemode: view.livemode } })),
+    },
+  };
+}
+
+const RENDERERS = {
+  customers: renderCustomer,
+  payment_methods: renderPaymentMethod,
+  payment_intents: renderPaymentIntent,
+  charges: renderCharge,
+  refunds: renderRefund,
+  products: renderProduct,
+  prices: renderPrice,
+  invoice_items: renderInvoiceItem,
+  invoices: renderInvoice,
+  subscriptions: renderSubscription,
+};
+
+export function renderRow(view, namespace, row) {
+  return RENDERERS[namespace](view, row);
+}
+
+/** Render the object an id refers to (by prefix), or return the id when it cannot be resolved. */
+export function renderById(view, id) {
+  if (typeof id !== "string") return id;
+  const prefix = id.split("_", 1)[0];
+  const namespace = Object.hasOwn(PREFIX_NAMESPACES, prefix) ? PREFIX_NAMESPACES[prefix] : undefined;
+  if (namespace === undefined) return id;
+  const row = getRow(view.context, namespace, id);
+  return row === null ? id : renderRow(view, namespace, row);
+}
+
+/** Refunds shown inline in an expanded `charge.refunds` list; Stripe embeds the first page and sets `has_more`. */
+export const EMBEDDED_REFUNDS = 10;
+
+/**
+ * The expandable `refunds` list of a charge, computed from the `refunds` namespace. Refunds are grouped by charge
+ * once per call (a charges list expanding `data.refunds` scans the namespace once, not once per charge), newest
+ * first; like Stripe, the embedded list carries the first `EMBEDDED_REFUNDS` with `has_more` and `total_count`, and
+ * the rest are listed with `GET /v1/refunds?charge=`.
+ */
+export function chargeRefunds(view, chargeId) {
+  if (view.memo.refundsByCharge === undefined) {
+    const groups = new Map();
+    for (const refund of allRows(view.context, "refunds")) {
+      const group = groups.get(refund.charge);
+      if (group === undefined) groups.set(refund.charge, [refund]);
+      else group.push(refund);
+    }
+    for (const group of groups.values()) group.sort((left, right) => (right.created - left.created) || (left.id < right.id ? 1 : -1));
+    view.memo.refundsByCharge = groups;
+  }
+  const all = view.memo.refundsByCharge.get(chargeId) ?? [];
+  const data = all.slice(0, EMBEDDED_REFUNDS).map((refund) => renderRefund(view, refund));
+  return { object: "list", data, has_more: all.length > data.length, total_count: all.length, url: `/v1/charges/${chargeId}/refunds` };
+}
+
+// ---------------------------------------------------------------------------------------------
+// expand[]
+// ---------------------------------------------------------------------------------------------
+
+/** Validate `expand` against the allow-list of `type` (`data.` prefix for lists); returns the normalised paths. */
+export function validateExpand(context, expand, type, isList = false) {
+  if (expand === undefined) return [];
+  if (!Array.isArray(expand) || expand.some((entry) => typeof entry !== "string")) {
+    return invalid(context, "Invalid array: expand must be an array of strings.", "parameter_invalid", "expand");
+  }
+  const allowed = EXPANDABLE[type] ?? [];
+  const paths = [];
+  for (const raw of expand) {
+    let path = raw;
+    if (isList) {
+      if (!path.startsWith("data.")) return invalid(context, `This property cannot be expanded (${raw}). Expand list items with the 'data.' prefix.`, "parameter_invalid", "expand");
+      path = path.slice("data.".length);
+    }
+    if (!allowed.includes(path)) return invalid(context, `This property cannot be expanded (${raw}).`, "parameter_invalid", "expand");
+    paths.push(path);
+  }
+  return paths.sort((left, right) => left.split(".").length - right.split(".").length);
+}
+
+function expandInto(view, target, segments, special) {
+  if (target === null || typeof target !== "object") return target;
+  const [head, ...rest] = segments;
+  if (target.object === "list" && head === "data" && Array.isArray(target.data)) {
+    return { ...target, data: target.data.map((item) => expandInto(view, item, rest, special)) };
+  }
+  if (rest.length === 0) {
+    if (head === "refunds" && special === "charge") return { ...target, refunds: chargeRefunds(view, target.id) };
+    return { ...target, [head]: renderById(view, target[head]) };
+  }
+  let child = target[head];
+  if (typeof child === "string") child = renderById(view, child);
+  return { ...target, [head]: expandInto(view, child, rest, special) };
+}
+
+/** Apply validated expand paths to a rendered object or list. */
+export function applyExpand(view, value, paths, type, isList = false) {
+  let out = value;
+  for (const path of paths) {
+    const segments = (isList ? "data." + path : path).split(".");
+    out = expandInto(view, out, segments, type);
+  }
+  return out;
+}

package/firedrill/tools/stripe/lib/periods.mjs

@@ -0,0 +1,41 @@
+// Billing-period arithmetic on UTC calendar fields. Only `Date.UTC` and explicit epoch construction are used;
+// nothing here reads the wall clock.
+
+export const DAY = 86_400;
+
+export const INTERVALS = Object.freeze(["day", "week", "month", "year"]);
+export const MAX_INTERVAL_COUNT = Object.freeze({ day: 365, week: 52, month: 12, year: 1 });
+
+function utcFields(seconds) {
+  const date = new Date(seconds * 1_000);
+  return {
+    year: date.getUTCFullYear(),
+    month: date.getUTCMonth(),
+    day: date.getUTCDate(),
+    hour: date.getUTCHours(),
+    minute: date.getUTCMinutes(),
+    second: date.getUTCSeconds(),
+  };
+}
+
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+
+/** `seconds` advanced by `count` intervals; month/year steps clamp to the last day of the target month. */
+export function addInterval(seconds, interval, count) {
+  if (interval === "day") return seconds + count * DAY;
+  if (interval === "week") return seconds + count * 7 * DAY;
+  const fields = utcFields(seconds);
+  const months = interval === "year" ? count * 12 : count;
+  const total = fields.year * 12 + fields.month + months;
+  const year = Math.floor(total / 12);
+  const month = total - year * 12;
+  const day = Math.min(fields.day, daysInMonth(year, month));
+  return Math.floor(Date.UTC(year, month, day, fields.hour, fields.minute, fields.second) / 1_000);
+}
+
+/** ISO-8601 (`2026-09-14T09:00:00Z`) for logs and messages. */
+export function isoSeconds(seconds) {
+  return new Date(seconds * 1_000).toISOString().replace(/\.000Z$/, "Z");
+}

package/firedrill/tools/stripe/lib/size.mjs

@@ -0,0 +1,55 @@
+// Response byte budget. The framework refuses any HTTP route response larger than 1 MiB (answering an opaque 500
+// after the operation committed), so list pages are filled by the encoded UTF-8 size of the objects actually
+// returned, and a single object that cannot fit answers Stripe's own `invalid_request_error` instead.
+// Sizes are UTF-8 bytes of `JSON.stringify` output, computed from code points (no Buffer in behavior modules).
+
+import { invalid } from "./state.mjs";
+
+/** Largest encoded single object (with its expansions) this Tool returns, alone or as one list item. */
+export const OBJECT_BYTE_BUDGET = 900_000;
+/**
+ * Bytes of list items (objects plus separators) one page may carry. At least `OBJECT_BYTE_BUDGET`, so every object
+ * that can be retrieved alone can also be listed; the list envelope, headers and a route's `url` rewrite fit in the
+ * remaining space below the framework's 1 MiB response cap.
+ */
+export const PAGE_BYTE_BUDGET = 950_000;
+
+/** UTF-8 byte length of a string: 1-3 bytes per BMP code unit, 4 per surrogate pair, 3 for a lone surrogate. */
+export function utf8Bytes(text) {
+  let bytes = 0;
+  const length = text.length;
+  for (let index = 0; index < length; index += 1) {
+    const unit = text.charCodeAt(index);
+    if (unit < 0x80) bytes += 1;
+    else if (unit < 0x800) bytes += 2;
+    else if (unit >= 0xd800 && unit <= 0xdbff && index + 1 < length) {
+      const next = text.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+/** Encoded JSON size of a value, in UTF-8 bytes. */
+export function jsonBytes(value) {
+  const text = JSON.stringify(value);
+  return text === undefined ? 0 : utf8Bytes(text);
+}
+
+/** Fail with `invalid_request_error` naming `what` ("The invoice in_…", "This object") and its encoded size. */
+export function tooLargeObject(context, what, bytes) {
+  return invalid(
+    context,
+    `${what} is too large to return in one response (${bytes} bytes; the limit is ${OBJECT_BYTE_BUDGET} bytes). Reduce its metadata or text fields, or request fewer expansions.`,
+    "parameter_invalid",
+  );
+}
+
+/** Return `value` when its encoded body fits the object budget, otherwise fail with the declared error. */
+export function requireFits(context, value, what) {
+  const bytes = jsonBytes(value);
+  return bytes > OBJECT_BYTE_BUDGET ? tooLargeObject(context, what, bytes) : value;
+}

package/firedrill/tools/stripe/lib/state.mjs

@@ -0,0 +1,230 @@
+// Declared-error helpers, bounded scans, virtual-time seconds, permissions and list pagination. Every function
+// is pure or reads `context`; nothing keeps module-level state.
+import { OBJECT_BYTE_BUDGET, PAGE_BYTE_BUDGET, jsonBytes, tooLargeObject } from "./size.mjs";
+
+
+export const SCAN_STEP = 500;
+export const SCAN_CAP = 10_000;
+export const MAX_LIST_LIMIT = 100;
+export const DEFAULT_LIST_LIMIT = 10;
+
+const OBJECT_NAMES = {
+  customers: "customer",
+  payment_methods: "PaymentMethod",
+  payment_intents: "PaymentIntent",
+  charges: "charge",
+  refunds: "refund",
+  products: "product",
+  prices: "price",
+  invoice_items: "invoiceitem",
+  invoices: "invoice",
+  subscriptions: "subscription",
+  subscription_items: "subscription_item",
+};
+
+// ---------------------------------------------------------------------------------------------
+// Declared errors
+// ---------------------------------------------------------------------------------------------
+
+export function fail(context, code, message, details) {
+  return context.fail(details === undefined ? { code, message } : { code, message, details });
+}
+
+/** 400 `invalid_request_error` for a parameter problem; `stripeCode` is Stripe's `error.code`. */
+export function invalid(context, message, stripeCode = "parameter_invalid", param) {
+  return fail(context, "INVALID_REQUEST", message, { code: stripeCode, ...(param === undefined ? {} : { param }) });
+}
+
+export function parameterMissing(context, param) {
+  return invalid(context, `Missing required param: ${param}.`, "parameter_missing", param);
+}
+
+export function parameterUnknown(context, param) {
+  return invalid(context, `Received unknown parameter: ${param}`, "parameter_unknown", param);
+}
+
+export function invalidInteger(context, param, value) {
+  return invalid(context, `Invalid integer: ${String(value)}`, "parameter_invalid_integer", param);
+}
+
+export function invalidEmpty(context, param) {
+  return invalid(context, `You passed an empty string for '${param}'. We assume empty values are an attempt to unset a parameter; however '${param}' cannot be unset. You should remove '${param}' from your request or supply a non-empty value.`, "parameter_invalid_empty", param);
+}
+
+/** 404 `resource_missing`: `No such customer: 'cus_x'`. */
+export function resourceMissing(context, namespace, id, param) {
+  const name = OBJECT_NAMES[namespace] ?? namespace;
+  return fail(context, "RESOURCE_MISSING", `No such ${name}: '${String(id)}'`, { code: "resource_missing", param: param ?? (name === "PaymentMethod" ? "payment_method" : name === "PaymentIntent" ? "payment_intent" : name) });
+}
+
+/** 400 `invalid_request_error` for a status-machine violation. */
+export function invalidState(context, message, stripeCode) {
+  return fail(context, "INVALID_STATE", message, stripeCode === undefined ? {} : { code: stripeCode });
+}
+
+export function tooLarge(context, namespace) {
+  return invalid(context, `This synthetic account holds more than ${SCAN_CAP} ${namespace} rows; the Tool refuses to answer with a truncated list.`, "state_bound_exceeded");
+}
+
+// ---------------------------------------------------------------------------------------------
+// Permissions and mode (actor attributes)
+// ---------------------------------------------------------------------------------------------
+
+export const PERMISSION_GROUPS = Object.freeze(["balance", "customers", "payment_methods", "payment_intents", "charges", "refunds", "products", "invoices", "subscriptions"]);
+const LEVELS = { none: 0, read: 1, write: 2 };
+
+export function permissionLevel(context, group) {
+  const permissions = context.actor.attributes?.permissions;
+  if (typeof permissions !== "object" || permissions === null || Array.isArray(permissions)) return "write";
+  const level = permissions[group];
+  return level === "read" || level === "write" ? level : "none";
+}
+
+function accountId(context) {
+  const account = context.state.get("meta", "account");
+  return account !== null && typeof account.id === "string" ? account.id : "acct_synthetic";
+}
+
+/** Fail `PERMISSION_DENIED` unless the actor's restricted-key permissions cover `group: level`. */
+export function requirePermission(context, group, level) {
+  const granted = permissionLevel(context, group);
+  if (LEVELS[granted] >= LEVELS[level]) return;
+  return fail(
+    context,
+    "PERMISSION_DENIED",
+    `This API key does not have the required permissions for this endpoint on account ${accountId(context)}. Having the '${group}: ${level}' permission would allow this request to continue.`,
+    { group, level },
+  );
+}
+
+export function requirePermissions(context, pairs) {
+  for (const [group, level] of pairs) requirePermission(context, group, level);
+}
+
+export function livemode(context) {
+  return context.actor.attributes?.livemode === true;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Time
+// ---------------------------------------------------------------------------------------------
+
+export function nowSeconds(context) {
+  return Math.floor(context.clock.nowUs() / 1_000_000);
+}
+
+// ---------------------------------------------------------------------------------------------
+// Scans
+// ---------------------------------------------------------------------------------------------
+
+/** Every row of a namespace in row-id (creation) order; fails when the bound is exceeded. */
+export function allRows(context, namespace) {
+  const rows = [];
+  let after;
+  for (;;) {
+    const batch = context.state.scan(namespace, { ...(after === undefined ? {} : { afterRowId: after }), limit: SCAN_STEP });
+    if (batch.length === 0) return rows;
+    for (const record of batch) {
+      after = record.rowId;
+      rows.push(record.value);
+      if (rows.length >= SCAN_CAP) return tooLarge(context, namespace);
+    }
+    if (batch.length < SCAN_STEP) return rows;
+  }
+}
+
+export function getRow(context, namespace, id) {
+  return typeof id === "string" && id.length > 0 && id.length <= 255 ? context.state.get(namespace, id) : null;
+}
+
+export function requireRow(context, namespace, id, param) {
+  if (typeof id !== "string" || id.length === 0) return parameterMissing(context, param ?? OBJECT_NAMES[namespace] ?? namespace);
+  const row = getRow(context, namespace, id);
+  return row === null ? resourceMissing(context, namespace, id, param) : row;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Lists (newest first, cursor pagination)
+// ---------------------------------------------------------------------------------------------
+
+function compareNewestFirst(left, right) {
+  if (left.created !== right.created) return right.created - left.created;
+  return left.id < right.id ? 1 : left.id > right.id ? -1 : 0;
+}
+
+export function validateLimit(context, limit) {
+  if (limit === undefined) return DEFAULT_LIST_LIMIT;
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIST_LIMIT) {
+    return invalid(context, `Invalid integer: ${String(limit)}. limit must be between 1 and ${MAX_LIST_LIMIT}.`, "parameter_invalid_integer", "limit");
+  }
+  return limit;
+}
+
+/** `created`/`due_date` style range filter: an integer (equality) or `{ gt, gte, lt, lte }`. */
+export function matchesRange(value, filter, context, param) {
+  if (filter === undefined) return true;
+  if (typeof filter === "number") {
+    if (!Number.isInteger(filter)) return invalidInteger(context, param, filter);
+    return value === filter;
+  }
+  if (typeof filter !== "object" || filter === null || Array.isArray(filter)) return invalidInteger(context, param, filter);
+  if (value === null || value === undefined) return false;
+  for (const [key, bound] of Object.entries(filter)) {
+    if (!["gt", "gte", "lt", "lte"].includes(key)) return parameterUnknown(context, `${param}[${key}]`);
+    if (!Number.isInteger(bound)) return invalidInteger(context, `${param}[${key}]`, bound);
+    if (key === "gt" && !(value > bound)) return false;
+    if (key === "gte" && !(value >= bound)) return false;
+    if (key === "lt" && !(value < bound)) return false;
+    if (key === "lte" && !(value <= bound)) return false;
+  }
+  return true;
+}
+
+/**
+ * Paginate `rows` (already filtered) newest first. Cursors must name an existing row of the namespace
+ * (Stripe answers `resource_missing` on the cursor otherwise); the page is everything after/before that row in
+ * list order, so a cursor outside the filtered set still positions correctly.
+ *
+ * `render` returns the object exactly as the response carries it (expansions included). Pages are filled by count
+ * (`limit`) and by the encoded UTF-8 size of those objects (`PAGE_BYTE_BUDGET`): a page stops before the object that
+ * would pass the budget and answers `has_more: true`, so the next `starting_after` (last object) or `ending_before`
+ * (first object) resumes exactly at the first object not returned. Backward pages are filled from the cursor
+ * outward. One object larger than `OBJECT_BYTE_BUDGET` answers `invalid_request_error`, never a truncated page.
+ */
+export function paginate(context, namespace, rows, input, url, render) {
+  const limit = validateLimit(context, input.limit);
+  if (input.starting_after !== undefined && input.ending_before !== undefined) {
+    return invalid(context, "You cannot specify both starting_after and ending_before.", "parameter_invalid", "starting_after");
+  }
+  const sorted = [...rows].sort(compareNewestFirst);
+  if (input.ending_before !== undefined) {
+    const cursor = requireRow(context, namespace, input.ending_before, "ending_before");
+    const before = sorted.filter((row) => compareNewestFirst(row, cursor) < 0);
+    const { data, taken } = fillPage(context, namespace, before.length, limit, (step) => before[before.length - 1 - step], render);
+    return { object: "list", data: data.reverse(), has_more: taken < before.length, url };
+  }
+  let candidates = sorted;
+  if (input.starting_after !== undefined) {
+    const cursor = requireRow(context, namespace, input.starting_after, "starting_after");
+    candidates = sorted.filter((row) => compareNewestFirst(row, cursor) > 0);
+  }
+  const { data, taken } = fillPage(context, namespace, candidates.length, limit, (step) => candidates[step], render);
+  return { object: "list", data, has_more: taken < candidates.length, url };
+}
+
+/** Render up to `limit` of `count` rows (`rowAt(step)`, nearest the cursor first) within the page byte budget. */
+function fillPage(context, namespace, count, limit, rowAt, render) {
+  const data = [];
+  let bytes = 0;
+  while (data.length < limit && data.length < count) {
+    const row = rowAt(data.length);
+    const item = render(row);
+    const itemBytes = jsonBytes(item);
+    if (itemBytes > OBJECT_BYTE_BUDGET) return tooLargeObject(context, `The ${OBJECT_NAMES[namespace] ?? namespace} ${row.id}`, itemBytes);
+    const size = itemBytes + 1;
+    if (bytes + size > PAGE_BYTE_BUDGET) break;
+    bytes += size;
+    data.push(item);
+  }
+  return { data, taken: data.length };
+}