@firedrill-tools/stripe 0.1.1

package/firedrill/tools/stripe/ops/catalog.mjs

@@ -0,0 +1,203 @@
+// Products and prices. Prices are immutable in this Tool (no `prices.update`); `lookup_key` is unique among
+// active prices as in Stripe.
+
+import { nextId } from "../lib/ids.mjs";
+import { decimalString } from "../lib/money.mjs";
+import { applyExpand, makeView, renderPrice, renderProduct, validateExpand } from "../lib/objects.mjs";
+import { INTERVALS, MAX_INTERVAL_COUNT } from "../lib/periods.mjs";
+import { allRows, getRow, invalid, matchesRange, paginate, parameterMissing, parameterUnknown, requirePermission, requireRow, resourceMissing } from "../lib/state.mjs";
+import { isPlainObject, mergeMetadata, optionalBoolean, optionalEnum, optionalInteger, optionalString, optionalStringArray, rejectMangled, requireCurrency, requireInteger, requireString } from "../lib/validate.mjs";
+
+const TAX_BEHAVIOR = ["unspecified", "inclusive", "exclusive"];
+
+// ---------------------------------------------------------------------------------------------
+// Products
+// ---------------------------------------------------------------------------------------------
+
+function productFields(context, input, current) {
+  return {
+    name: current === null ? requireString(context, input, "name", 250) : input.name === undefined ? current.name : requireString(context, input, "name", 250),
+    description: optionalString(context, input, "description", current === null ? null : current.description, 40_000),
+    active: optionalBoolean(context, input, "active", current === null ? true : current.active),
+    metadata: mergeMetadata(context, input.metadata, current === null ? {} : current.metadata),
+    unit_label: optionalString(context, input, "unit_label", current === null ? null : current.unit_label, 12),
+    images: optionalStringArray(context, input, "images", current === null ? [] : current.images),
+  };
+}
+
+export function productsCreate(input, context) {
+  requirePermission(context, "products", "write");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "product");
+  const fields = productFields(context, input, null);
+  if (fields.images.length > 8) return invalid(context, "You can specify up to 8 images.", "parameter_invalid", "images");
+  if (input.default_price !== undefined) {
+    return invalid(context, "default_price cannot be set when creating a product because no price of the product exists yet; create the price, then update the product.", "parameter_invalid", "default_price");
+  }
+  const id = nextId(context, "prod");
+  const product = {
+    id,
+    object: "product",
+    active: fields.active,
+    created: view.now,
+    default_price: null,
+    description: fields.description,
+    images: fields.images,
+    livemode: view.livemode,
+    marketing_features: [],
+    metadata: fields.metadata,
+    name: fields.name,
+    package_dimensions: null,
+    shippable: null,
+    statement_descriptor: null,
+    tax_code: null,
+    type: "service",
+    unit_label: fields.unit_label,
+    updated: view.now,
+    url: null,
+  };
+  context.state.put("products", id, product);
+  return applyExpand(view, renderProduct(view, product), expand, "product");
+}
+
+export function productsRetrieve(input, context) {
+  requirePermission(context, "products", "read");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "product");
+  const product = requireRow(context, "products", input.product, "product");
+  return applyExpand(view, renderProduct(view, product), expand, "product");
+}
+
+export function productsUpdate(input, context) {
+  requirePermission(context, "products", "write");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "product");
+  const current = requireRow(context, "products", input.product, "product");
+  const fields = productFields(context, input, current);
+  if (fields.images.length > 8) return invalid(context, "You can specify up to 8 images.", "parameter_invalid", "images");
+  let defaultPrice = current.default_price;
+  if (input.default_price !== undefined) {
+    if (input.default_price === "" || input.default_price === null) defaultPrice = null;
+    else {
+      const price = getRow(context, "prices", input.default_price);
+      if (price === null || price.product !== current.id) {
+        return invalid(context, `The price '${String(input.default_price)}' does not belong to product '${current.id}'.`, "parameter_invalid", "default_price");
+      }
+      if (!price.active) return invalid(context, `The price '${price.id}' is not active and cannot be the default price.`, "parameter_invalid", "default_price");
+      defaultPrice = price.id;
+    }
+  }
+  const product = { ...current, ...fields, default_price: defaultPrice, updated: view.now };
+  context.state.put("products", product.id, product);
+  return applyExpand(view, renderProduct(view, product), expand, "product");
+}
+
+export function productsList(input, context) {
+  requirePermission(context, "products", "read");
+  rejectMangled(context, input, ["ids"]);
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "product", true);
+  const active = optionalBoolean(context, input, "active", undefined);
+  const ids = optionalStringArray(context, input, "ids", undefined);
+  const rows = allRows(context, "products").filter(
+    (product) => (active === undefined || product.active === active) && (ids === undefined || ids.includes(product.id)) && matchesRange(product.created, input.created, context, "created"),
+  );
+  return paginate(context, "products", rows, input, "/v1/products", (row) => applyExpand(view, renderProduct(view, row), expand, "product"));
+}
+
+// ---------------------------------------------------------------------------------------------
+// Prices
+// ---------------------------------------------------------------------------------------------
+
+function recurringInput(context, value) {
+  if (value === undefined) return null;
+  if (!isPlainObject(value)) return invalid(context, "Invalid recurring: must be a hash.", "parameter_invalid", "recurring");
+  for (const key of Object.keys(value)) {
+    if (!["interval", "interval_count", "trial_period_days"].includes(key)) return parameterUnknown(context, `recurring[${key}]`);
+  }
+  if (value.interval === undefined) return parameterMissing(context, "recurring[interval]");
+  if (!INTERVALS.includes(value.interval)) return invalid(context, `Invalid recurring[interval]: must be one of ${INTERVALS.join(", ")}`, "parameter_invalid", "recurring[interval]");
+  const count = optionalInteger(context, value, "interval_count", 1, { min: 1 });
+  if (count > MAX_INTERVAL_COUNT[value.interval]) {
+    return invalid(context, `The maximum billing interval is one year; recurring[interval_count] for '${value.interval}' must be at most ${MAX_INTERVAL_COUNT[value.interval]}.`, "parameter_invalid", "recurring[interval_count]");
+  }
+  const trial = optionalInteger(context, value, "trial_period_days", null, { min: 1, max: 730 });
+  return { interval: value.interval, interval_count: count, meter: null, trial_period_days: trial, usage_type: "licensed" };
+}
+
+export function pricesCreate(input, context) {
+  requirePermission(context, "products", "write");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "price");
+  const productId = requireString(context, input, "product", 255);
+  const product = getRow(context, "products", productId);
+  if (product === null) return resourceMissing(context, "products", productId, "product");
+  const currency = requireCurrency(context, input.currency);
+  const unitAmount = requireInteger(context, input, "unit_amount", { min: 0, max: 99_999_999 });
+  const recurring = recurringInput(context, input.recurring);
+  const nickname = optionalString(context, input, "nickname", null, 250);
+  const lookupKey = optionalString(context, input, "lookup_key", null, 200);
+  const active = optionalBoolean(context, input, "active", true);
+  const metadata = mergeMetadata(context, input.metadata);
+  const taxBehavior = optionalEnum(context, input, "tax_behavior", TAX_BEHAVIOR, "unspecified");
+  if (lookupKey !== null && active) {
+    const clash = allRows(context, "prices").find((price) => price.active && price.lookup_key === lookupKey);
+    if (clash !== undefined) {
+      return invalid(context, `An active price with lookup_key '${lookupKey}' already exists (${clash.id}). Pass transfer_lookup_key=true to move it, or choose another key.`, "resource_already_exists", "lookup_key");
+    }
+  }
+  const id = nextId(context, "price");
+  const price = {
+    id,
+    object: "price",
+    active,
+    billing_scheme: "per_unit",
+    created: view.now,
+    currency,
+    custom_unit_amount: null,
+    livemode: view.livemode,
+    lookup_key: lookupKey,
+    metadata,
+    nickname,
+    product: product.id,
+    recurring,
+    tax_behavior: taxBehavior,
+    tiers_mode: null,
+    transform_quantity: null,
+    type: recurring === null ? "one_time" : "recurring",
+    unit_amount: unitAmount,
+    unit_amount_decimal: decimalString(unitAmount),
+  };
+  context.state.put("prices", id, price);
+  return applyExpand(view, renderPrice(view, price), expand, "price");
+}
+
+export function pricesRetrieve(input, context) {
+  requirePermission(context, "products", "read");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "price");
+  const price = requireRow(context, "prices", input.price, "price");
+  return applyExpand(view, renderPrice(view, price), expand, "price");
+}
+
+export function pricesList(input, context) {
+  requirePermission(context, "products", "read");
+  rejectMangled(context, input, ["product", "lookup_keys", "currency", "type"]);
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "price", true);
+  const product = optionalString(context, input, "product", undefined, 255);
+  const active = optionalBoolean(context, input, "active", undefined);
+  const type = optionalEnum(context, input, "type", ["one_time", "recurring"], undefined);
+  const currency = input.currency === undefined ? undefined : requireCurrency(context, input.currency);
+  const lookupKeys = optionalStringArray(context, input, "lookup_keys", undefined);
+  const rows = allRows(context, "prices").filter(
+    (price) =>
+      (product === undefined || price.product === product) &&
+      (active === undefined || price.active === active) &&
+      (type === undefined || price.type === type) &&
+      (currency === undefined || price.currency === currency) &&
+      (lookupKeys === undefined || (price.lookup_key !== null && lookupKeys.includes(price.lookup_key))) &&
+      matchesRange(price.created, input.created, context, "created"),
+  );
+  return paginate(context, "prices", rows, input, "/v1/prices", (row) => applyExpand(view, renderPrice(view, row), expand, "price"));
+}

package/firedrill/tools/stripe/ops/customers.mjs

@@ -0,0 +1,241 @@
+// Customers and payment methods. Cards are synthetic: Stripe's published test ids materialise real
+// `payment_methods` rows when attached or confirmed, exactly as Stripe's test mode does.
+
+import { cardDetails, testCard } from "../lib/cards.mjs";
+import { invoicePrefix, nextId, nextSequence, renderId } from "../lib/ids.mjs";
+import { applyExpand, makeView, renderCustomer, renderPaymentMethod, validateExpand } from "../lib/objects.mjs";
+import { allRows, getRow, invalidState, matchesRange, paginate, parameterMissing, parameterUnknown, requirePermission, requirePermissions, requireRow, resourceMissing } from "../lib/state.mjs";
+import { isPlainObject, mergeMetadata, normalizeAddress, normalizeShipping, optionalEnum, optionalString, optionalStringArray, rejectMangled, validateEmail } from "../lib/validate.mjs";
+
+const TAX_EXEMPT = ["none", "exempt", "reverse"];
+const EMPTY_ADDRESS = Object.freeze({ city: null, country: null, line1: null, line2: null, postal_code: null, state: null });
+
+// ---------------------------------------------------------------------------------------------
+// Payment method helpers (shared with payments and billing)
+// ---------------------------------------------------------------------------------------------
+
+/** A test id (`pm_card_*`) → `{ card }`; a materialised row → `{ row }`; anything else fails `RESOURCE_MISSING`. */
+export function resolvePaymentMethod(context, view, id, param = "payment_method") {
+  if (typeof id !== "string" || id.length === 0) return parameterMissing(context, param);
+  const card = testCard(id);
+  if (card !== undefined) {
+    if (view.livemode) return resourceMissing(context, "payment_methods", id, param);
+    return { card, testId: id };
+  }
+  const row = getRow(context, "payment_methods", id);
+  if (row === null) return resourceMissing(context, "payment_methods", id, param);
+  return { row };
+}
+
+function billingDetails(customer) {
+  if (customer === null) return { address: { ...EMPTY_ADDRESS }, email: null, name: null, phone: null };
+  return { address: customer.address === null ? { ...EMPTY_ADDRESS } : { ...customer.address }, email: customer.email, name: customer.name, phone: customer.phone };
+}
+
+/** Create a `payment_methods` row for a catalogue card, optionally attached to `customer` (a row or null). */
+export function materializeCard(context, view, card, customer) {
+  const id = nextId(context, "pm");
+  const row = {
+    id,
+    object: "payment_method",
+    allow_redisplay: "unspecified",
+    billing_details: billingDetails(customer),
+    card: cardDetails(card),
+    created: view.now,
+    customer: customer === null ? null : customer.id,
+    livemode: view.livemode,
+    metadata: {},
+    type: "card",
+    outcome: card.outcome,
+  };
+  context.state.put("payment_methods", id, row);
+  return row;
+}
+
+/** Attach a resolved method to a customer, materialising test cards; fails when it belongs to someone. */
+export function attachMethod(context, view, resolved, customer) {
+  if (resolved.card !== undefined) return materializeCard(context, view, resolved.card, customer);
+  if (resolved.row.customer !== null) {
+    return invalidState(context, "The payment method you provided has already been attached to a customer.", "payment_method_already_attached");
+  }
+  const row = { ...resolved.row, customer: customer.id, billing_details: billingDetails(customer) };
+  context.state.put("payment_methods", row.id, row);
+  return row;
+}
+
+/** Resolve an id that must name a method attached to `customer` (for defaults); returns the row. */
+export function requireAttachedMethod(context, view, id, customer, param) {
+  const resolved = resolvePaymentMethod(context, view, id, param);
+  if (resolved.card !== undefined || resolved.row.customer !== customer.id) {
+    return invalidState(context, `The payment method '${id}' is not attached to customer '${customer.id}'. Attach it first with /v1/payment_methods/:id/attach.`, "payment_method_unattached");
+  }
+  return resolved.row;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Customers
+// ---------------------------------------------------------------------------------------------
+
+function newCustomerRow(view, sequence, fields) {
+  return {
+    id: renderId("cus", sequence),
+    object: "customer",
+    address: fields.address,
+    balance: 0,
+    created: view.now,
+    currency: null,
+    default_source: null,
+    delinquent: false,
+    description: fields.description,
+    email: fields.email,
+    invoice_prefix: invoicePrefix(sequence),
+    invoice_settings: { custom_fields: null, default_payment_method: null, footer: null, rendering_options: null },
+    livemode: view.livemode,
+    metadata: fields.metadata,
+    name: fields.name,
+    next_invoice_sequence: 1,
+    phone: fields.phone,
+    preferred_locales: fields.preferred_locales,
+    shipping: fields.shipping,
+    tax_exempt: fields.tax_exempt,
+    test_clock: null,
+  };
+}
+
+function invoiceSettingsInput(context, input) {
+  const settings = input.invoice_settings;
+  if (settings === undefined) return undefined;
+  if (!isPlainObject(settings)) return parameterUnknown(context, "invoice_settings");
+  for (const key of Object.keys(settings)) if (key !== "default_payment_method") return parameterUnknown(context, `invoice_settings[${key}]`);
+  return settings.default_payment_method;
+}
+
+export function customersCreate(input, context) {
+  requirePermission(context, "customers", "write");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "customer");
+  const fields = {
+    name: optionalString(context, input, "name", null, 256),
+    email: validateEmail(context, optionalString(context, input, "email", null, 512)),
+    description: optionalString(context, input, "description", null),
+    phone: optionalString(context, input, "phone", null, 20),
+    address: normalizeAddress(context, input.address),
+    shipping: normalizeShipping(context, input.shipping),
+    metadata: mergeMetadata(context, input.metadata),
+    preferred_locales: optionalStringArray(context, input, "preferred_locales", []),
+    tax_exempt: optionalEnum(context, input, "tax_exempt", TAX_EXEMPT, "none"),
+  };
+  const defaultMethod = invoiceSettingsInput(context, input);
+  const sequence = nextSequence(context);
+  const customer = newCustomerRow(view, sequence, fields);
+  if (input.payment_method !== undefined) {
+    const resolved = resolvePaymentMethod(context, view, input.payment_method);
+    if (defaultMethod !== undefined && defaultMethod !== "" && defaultMethod !== input.payment_method) {
+      return invalidState(context, `The payment method '${defaultMethod}' is not attached to this customer.`, "payment_method_unattached");
+    }
+    const method = attachMethod(context, view, resolved, customer);
+    customer.invoice_settings.default_payment_method = method.id;
+    if (method.billing_details.name === null && method.billing_details.email === null) {
+      context.state.put("payment_methods", method.id, { ...method, billing_details: billingDetails(customer) });
+    }
+  } else if (defaultMethod !== undefined && defaultMethod !== "") {
+    return invalidState(context, `The payment method '${defaultMethod}' is not attached to this customer.`, "payment_method_unattached");
+  }
+  context.state.put("customers", customer.id, customer);
+  return applyExpand(view, renderCustomer(view, customer), expand, "customer");
+}
+
+export function customersRetrieve(input, context) {
+  requirePermission(context, "customers", "read");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "customer");
+  const customer = requireRow(context, "customers", input.customer, "customer");
+  return applyExpand(view, renderCustomer(view, customer), expand, "customer");
+}
+
+export function customersUpdate(input, context) {
+  requirePermission(context, "customers", "write");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "customer");
+  const current = requireRow(context, "customers", input.customer, "customer");
+  const next = {
+    ...current,
+    name: optionalString(context, input, "name", current.name, 256),
+    email: validateEmail(context, optionalString(context, input, "email", current.email, 512)),
+    description: optionalString(context, input, "description", current.description),
+    phone: optionalString(context, input, "phone", current.phone, 20),
+    address: normalizeAddress(context, input.address, "address", current.address),
+    shipping: normalizeShipping(context, input.shipping, current.shipping),
+    metadata: mergeMetadata(context, input.metadata, current.metadata),
+    preferred_locales: optionalStringArray(context, input, "preferred_locales", current.preferred_locales),
+    tax_exempt: optionalEnum(context, input, "tax_exempt", TAX_EXEMPT, current.tax_exempt),
+    invoice_settings: { ...current.invoice_settings },
+  };
+  const defaultMethod = invoiceSettingsInput(context, input);
+  if (defaultMethod !== undefined) {
+    if (defaultMethod === "" || defaultMethod === null) next.invoice_settings.default_payment_method = null;
+    else next.invoice_settings.default_payment_method = requireAttachedMethod(context, view, defaultMethod, current, "invoice_settings[default_payment_method]").id;
+  }
+  next.delinquent = renderCustomer(view, current).delinquent;
+  context.state.put("customers", next.id, next);
+  return applyExpand(view, renderCustomer(view, next), expand, "customer");
+}
+
+export function customersList(input, context) {
+  requirePermission(context, "customers", "read");
+  rejectMangled(context, input, ["email"]);
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "customer", true);
+  const email = optionalString(context, input, "email", undefined, 512);
+  const rows = allRows(context, "customers").filter(
+    (customer) => (email === undefined || email === null || customer.email === email) && matchesRange(customer.created, input.created, context, "created"),
+  );
+  return paginate(context, "customers", rows, input, "/v1/customers", (row) => applyExpand(view, renderCustomer(view, row), expand, "customer"));
+}
+
+// ---------------------------------------------------------------------------------------------
+// Payment methods
+// ---------------------------------------------------------------------------------------------
+
+export function paymentMethodsList(input, context) {
+  requirePermission(context, "payment_methods", "read");
+  rejectMangled(context, input, ["customer", "type"]);
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "payment_method", true);
+  const customer = requireRow(context, "customers", input.customer, "customer");
+  const type = optionalString(context, input, "type", undefined, 64);
+  const rows = type !== undefined && type !== "card" ? [] : allRows(context, "payment_methods").filter((method) => method.customer === customer.id);
+  return paginate(context, "payment_methods", rows, input, "/v1/payment_methods", (row) => applyExpand(view, renderPaymentMethod(view, row), expand, "payment_method"));
+}
+
+export function paymentMethodsAttach(input, context) {
+  requirePermissions(context, [["payment_methods", "write"], ["customers", "read"]]);
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "payment_method");
+  const customer = requireRow(context, "customers", input.customer, "customer");
+  const resolved = resolvePaymentMethod(context, view, input.payment_method);
+  const method = attachMethod(context, view, resolved, customer);
+  return applyExpand(view, renderPaymentMethod(view, method), expand, "payment_method");
+}
+
+export function paymentMethodsDetach(input, context) {
+  requirePermission(context, "payment_methods", "write");
+  const view = makeView(context);
+  const expand = validateExpand(context, input.expand, "payment_method");
+  const method = requireRow(context, "payment_methods", input.payment_method, "payment_method");
+  if (method.customer === null) {
+    return invalidState(context, "A payment method cannot be detached because it is not attached to a customer.", "payment_method_unattached");
+  }
+  const customer = getRow(context, "customers", method.customer);
+  if (customer !== null && customer.invoice_settings.default_payment_method === method.id) {
+    context.state.put("customers", customer.id, { ...customer, invoice_settings: { ...customer.invoice_settings, default_payment_method: null } });
+  }
+  for (const subscription of allRows(context, "subscriptions")) {
+    if (subscription.default_payment_method === method.id && subscription.status !== "canceled") {
+      context.state.put("subscriptions", subscription.id, { ...subscription, default_payment_method: null });
+    }
+  }
+  const detached = { ...method, customer: null, billing_details: billingDetails(null) };
+  context.state.put("payment_methods", detached.id, detached);
+  return applyExpand(view, renderPaymentMethod(view, detached), expand, "payment_method");
+}

package/firedrill/tools/stripe/ops/dashboard.mjs

@@ -0,0 +1,29 @@
+// Dashboard context for the browser app: the simulated account, the world's virtual time, the caller's mode and
+// restricted-key permission levels. Read-only, never fails, and reachable only as the canonical operation
+// (there is no Stripe REST route for it); the app uses it so "today" never comes from the browser clock.
+
+import { PERMISSION_GROUPS, nowSeconds, permissionLevel, livemode } from "../lib/state.mjs";
+import { API_VERSION } from "../lib/wire.mjs";
+import { accountInfo } from "./payments.mjs";
+
+export function dashboardContext(input, context) {
+  void input;
+  const permissions = {};
+  for (const group of PERMISSION_GROUPS) permissions[group] = permissionLevel(context, group);
+  const account = accountInfo(context);
+  return {
+    object: "dashboard.context",
+    account: {
+      id: account.id,
+      business_name: account.business_name,
+      country: account.country,
+      default_currency: account.default_currency,
+      statement_descriptor: account.statement_descriptor,
+      support_email: account.support_email,
+    },
+    now: nowSeconds(context),
+    livemode: livemode(context),
+    permissions,
+    api_version: API_VERSION,
+  };
+}