@agentsbloom/sdk 0.4.0 → 0.5.0

package/lib/money.js

@@ -0,0 +1,283 @@
+/**
+ * Exact money handling for the AgentsBloom SDK.
+ *
+ * Why this file exists
+ * -------------------
+ * Every monetary value in the previous implementation was an IEEE-754
+ * double, and the conversion to minor units was `Math.round(Number(x) * 100)`.
+ * That is wrong in a way that costs real money:
+ *
+ *     1.005 * 100 === 100.49999999999999   ->  Math.round -> 100   ($1.00)
+ *     1.015 * 100 === 101.49999999999999   ->  Math.round -> 101   ($1.01)
+ *     2.675 * 100 === 267.49999999999994   ->  Math.round -> 267   ($2.67)
+ *
+ * A price that a human wrote as $1.005 is silently charged as $1.00, and the
+ * same wrong number is what gets hashed into a Cart Mandate. Budget
+ * comparisons had the same problem from the other direction: `orderTotal >
+ * maxBudget` on doubles can accept a total that is a fraction of a cent over
+ * the authorized cap, and accumulating `sum += q * u` across a large cart can
+ * exceed 2^53 and lose precision entirely.
+ *
+ * The fix is to never multiply a float. Values arrive as decimal strings or
+ * numbers, are converted to their exact shortest decimal representation, and
+ * are then shifted by the required number of places using integer (BigInt)
+ * arithmetic with explicit half-up rounding.
+ *
+ * Everything here is total: nothing throws for bad input, it returns `null`
+ * so callers make a deliberate fail-closed decision.
+ */
+
+/**
+ * ISO 4217 currencies whose minor unit is NOT two decimal places. Anything
+ * absent from this table is treated as exponent 2, which is correct for the
+ * overwhelming majority of codes.
+ */
+const CURRENCY_EXPONENTS = new Map(Object.entries({
+  // Zero-decimal currencies.
+  BIF: 0, CLP: 0, DJF: 0, GNF: 0, ISK: 0, JPY: 0, KMF: 0, KRW: 0, PYG: 0,
+  RWF: 0, UGX: 0, UYI: 0, VND: 0, VUV: 0, XAF: 0, XOF: 0, XPF: 0,
+  // Three-decimal currencies.
+  BHD: 3, IQD: 3, JOD: 3, KWD: 3, LYD: 3, OMR: 3, TND: 3,
+  // Four-decimal currencies.
+  CLF: 4, UYW: 4,
+}));
+
+/**
+ * Internal comparison scale. Six places is more than any real currency needs
+ * (the deepest ISO 4217 minor unit is four), so scaling both sides of a
+ * budget comparison to micros is exact for every currency without needing to
+ * know which currency is in play.
+ */
+export const COMPARISON_SCALE = 6;
+
+/** Longest accepted numeric input; guards BigInt work on hostile input. */
+const MAX_NUMERIC_LENGTH = 32;
+
+/** Hard ceiling on a single monetary amount (1 trillion major units). */
+const MAX_MAJOR_UNITS = 1_000_000_000_000n;
+
+/**
+ * Returns the number of minor-unit decimal places for a currency code.
+ *
+ * @param {unknown} currency
+ * @returns {number}
+ */
+export function currencyExponent(currency) {
+  const code = normalizeCurrencyCode(currency);
+  if (!code) return 2;
+  return CURRENCY_EXPONENTS.has(code) ? CURRENCY_EXPONENTS.get(code) : 2;
+}
+
+/**
+ * Normalizes a currency code to uppercase, or returns null when it is not a
+ * syntactically valid ISO 4217 alphabetic code.
+ *
+ * @param {unknown} currency
+ * @returns {string|null}
+ */
+export function normalizeCurrencyCode(currency) {
+  if (typeof currency !== 'string') return null;
+  const code = currency.trim().toUpperCase();
+  return /^[A-Z]{3}$/.test(code) ? code : null;
+}
+
+/**
+ * Converts a number or numeric string to its exact decimal representation,
+ * expanding exponent notation. Returns null for anything non-finite or
+ * malformed.
+ *
+ * `String(n)` gives JavaScript's shortest round-trip decimal, which is the
+ * value the developer actually wrote for any literal they could have typed —
+ * so this is a faithful, not lossy, starting point.
+ *
+ * @param {unknown} value
+ * @returns {string|null} e.g. '-12.345'
+ */
+export function toDecimalString(value) {
+  let text;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return null;
+    text = String(value);
+  } else if (typeof value === 'bigint') {
+    text = value.toString();
+  } else if (typeof value === 'string') {
+    text = value.trim();
+  } else {
+    return null;
+  }
+
+  if (text === '' || text.length > MAX_NUMERIC_LENGTH) return null;
+
+  const match = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d{1,3}))?$/.exec(text);
+  if (!match) return null;
+  const [, rawSign, rawInt = '', rawFrac = '', rawExp] = match;
+  if (rawInt === '' && rawFrac === '') return null;
+
+  const sign = rawSign === '-' ? '-' : '';
+  let digits = `${rawInt}${rawFrac}`;
+  // Decimal point position measured from the left of `digits`.
+  let pointIndex = rawInt.length;
+
+  if (rawExp !== undefined) {
+    pointIndex += Number(rawExp);
+  }
+
+  if (pointIndex <= 0) {
+    digits = '0'.repeat(1 - pointIndex) + digits;
+    pointIndex = 1;
+  }
+  if (pointIndex > digits.length) {
+    digits += '0'.repeat(pointIndex - digits.length);
+  }
+
+  const intPart = digits.slice(0, pointIndex).replace(/^0+(?=\d)/, '');
+  const fracPart = digits.slice(pointIndex).replace(/0+$/, '');
+  return fracPart ? `${sign}${intPart}.${fracPart}` : `${sign}${intPart}`;
+}
+
+/**
+ * Converts a monetary value to an exact integer scaled by 10^scale, rounding
+ * half away from zero. Returns null when the value is not a finite number,
+ * is malformed, or exceeds the sanity ceiling.
+ *
+ * @param {unknown} value
+ * @param {number} scale - number of decimal places to keep
+ * @returns {bigint|null}
+ */
+export function toScaledBigInt(value, scale) {
+  if (!Number.isInteger(scale) || scale < 0 || scale > 12) return null;
+  const decimal = toDecimalString(value);
+  if (decimal === null) return null;
+
+  const negative = decimal.startsWith('-');
+  const unsigned = negative ? decimal.slice(1) : decimal;
+  const [intPart, fracPart = ''] = unsigned.split('.');
+
+  if (intPart.length > 16) return null;
+
+  const kept = fracPart.slice(0, scale).padEnd(scale, '0');
+  const dropped = fracPart.slice(scale);
+
+  let scaled = BigInt(`${intPart}${kept}` || '0');
+  // Half-up rounding on the discarded remainder: '5...' rounds away from zero.
+  if (dropped.length > 0 && dropped.charCodeAt(0) >= 0x35) {
+    scaled += 1n;
+  }
+
+  if (scaled > MAX_MAJOR_UNITS * 10n ** BigInt(scale)) return null;
+  return negative ? -scaled : scaled;
+}
+
+/**
+ * Converts a monetary value to the exact minor units of a currency
+ * (cents for USD, yen for JPY, fils for KWD).
+ *
+ * @param {unknown} value
+ * @param {unknown} currency
+ * @returns {bigint|null}
+ */
+export function toMinorUnits(value, currency) {
+  return toScaledBigInt(value, currencyExponent(currency));
+}
+
+/**
+ * Converts a monetary value to hundredths of the major unit.
+ *
+ * Used by `canonicalCartHash`, whose wire format (`ac1_`, field `u`) is
+ * defined as hundredths regardless of the currency's real minor unit. That
+ * definition is fixed for cross-SDK byte compatibility — the agent SDK, the
+ * PHP core, and every merchant must agree — so this deliberately does NOT
+ * consult `currencyExponent`. Only the ROUNDING is corrected relative to the
+ * old `Math.round(x * 100)`.
+ *
+ * @param {unknown} value
+ * @returns {number|null} an exact integer, or null when unrepresentable
+ */
+export function toHundredths(value) {
+  const scaled = toScaledBigInt(value, 2);
+  if (scaled === null) return null;
+  if (scaled > BigInt(Number.MAX_SAFE_INTEGER) || scaled < -BigInt(Number.MAX_SAFE_INTEGER)) {
+    return null;
+  }
+  return Number(scaled);
+}
+
+/**
+ * Compares two monetary amounts exactly.
+ *
+ * Both sides are converted to micros with half-up rounding, so this is exact
+ * for every ISO 4217 currency and immune to the float artifacts that made
+ * `Number(orderTotal) > Number(maxBudget)` unreliable.
+ *
+ * @param {unknown} left
+ * @param {unknown} right
+ * @returns {-1|0|1|null} null when either side is not a valid amount
+ */
+export function compareAmounts(left, right) {
+  const a = toScaledBigInt(left, COMPARISON_SCALE);
+  const b = toScaledBigInt(right, COMPARISON_SCALE);
+  if (a === null || b === null) return null;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * Strict parse of a client- or handler-supplied monetary amount.
+ *
+ * This is the gate that closes the budget-enforcement bypass: the old code
+ * did `Number(orderTotal) > Number(maxBudget)`, and `Number('abc')` is `NaN`,
+ * for which every comparison is false. A malformed total therefore passed the
+ * budget check instead of failing it. Callers must treat `null` as "reject".
+ *
+ * @param {unknown} value
+ * @param {object} [options]
+ * @param {boolean} [options.allowZero=true]
+ * @param {boolean} [options.allowNegative=false]
+ * @returns {{ decimal: string, micros: bigint }|null}
+ */
+export function parseAmount(value, options = {}) {
+  const { allowZero = true, allowNegative = false } = options;
+  // Reject booleans and empty-ish values that Number() would happily coerce.
+  if (typeof value === 'boolean' || value === null || value === undefined) return null;
+  if (typeof value === 'string' && value.trim() === '') return null;
+  if (typeof value !== 'number' && typeof value !== 'string' && typeof value !== 'bigint') return null;
+
+  const decimal = toDecimalString(value);
+  if (decimal === null) return null;
+  const micros = toScaledBigInt(decimal, COMPARISON_SCALE);
+  if (micros === null) return null;
+  if (!allowNegative && micros < 0n) return null;
+  if (!allowZero && micros === 0n) return null;
+  return { decimal, micros };
+}
+
+/**
+ * Formats a scaled integer back to a decimal string.
+ *
+ * @param {bigint} scaled
+ * @param {number} scale
+ * @returns {string}
+ */
+export function formatScaled(scaled, scale) {
+  const negative = scaled < 0n;
+  const digits = (negative ? -scaled : scaled).toString().padStart(scale + 1, '0');
+  const intPart = digits.slice(0, digits.length - scale);
+  const fracPart = scale > 0 ? digits.slice(digits.length - scale).replace(/0+$/, '') : '';
+  return `${negative ? '-' : ''}${intPart}${fracPart ? `.${fracPart}` : ''}`;
+}
+
+/**
+ * Sums a list of `{ quantity, unitHundredths }` line items exactly.
+ *
+ * @param {Array<{ quantity: number, unitHundredths: number }>} items
+ * @returns {number|null} total in hundredths, or null on overflow
+ */
+export function sumLineItems(items) {
+  let total = 0n;
+  for (const item of items) {
+    total += BigInt(item.quantity) * BigInt(item.unitHundredths);
+    if (total > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+  }
+  return Number(total);
+}

package/lib/outcomes.js

@@ -1,108 +1,108 @@
-/**
- * Payment-outcome reporting (migration 011 / POST /api/outcomes).
- *
- * AgentsBloom is the middleman: the merchant's gateway keys stay on THEIR
- * servers, inside THEIR webhook handlers. That also means payment outcomes
- * (paid / declined / chargeback) happen where we cannot see them - so this
- * module lets the merchant's existing webhook handler report the outcome
- * with one line. Those reports are what turn risk-core's decline-rate rules
- * from theory into data, and what powers the dashboard's outcome analytics.
- *
- * Keys never leave the merchant: they only ever send order references,
- * statuses, and optional amounts.
- */
-
-const DEFAULT_STATUSES = ['paid', 'declined', 'refunded', 'chargeback', 'disputed', 'canceled'];
-
-/**
- * Maps a Stripe webhook event to an outcome report body. Returns null for
- * events that carry no outcome signal, so handlers can do:
- *
- *   const report = stripeEventToOutcome(event);
- *   if (report) await reportPaymentOutcome(report);
- */
-export function stripeEventToOutcome(event) {
-  const type = event?.type;
-  const wrap = (status, extra = {}) => {
-    const obj = event?.data?.object ?? {};
-    return {
-      orderRef:
-        obj.metadata?.orderRef ??
-        obj.client_reference_id ??
-        obj.id,
-      gateway: 'stripe',
-      status,
-      amount: typeof obj.amount_total === 'number'
-        ? obj.amount_total / 100
-        : typeof obj.amount === 'number'
-          ? obj.amount / 100
-          : undefined,
-      currency: typeof obj.currency === 'string' ? obj.currency : undefined,
-      reason: extra.reason ?? obj.failure_message ?? null,
-      occurredAt: event?.created ? new Date(event.created * 1000).toISOString() : undefined,
-    };
-  };
-  switch (type) {
-    case 'checkout.session.completed':
-      return wrap('paid');
-    case 'invoice.payment_failed':
-    case 'charge.failed': {
-      const rep = wrap('declined');
-      rep.reason = event?.data?.object?.failure_message ?? event?.data?.object?.failure_code ?? null;
-      return rep;
-    }
-    case 'charge.refunded':
-      return wrap('refunded');
-    case 'charge.dispute.created':
-      return wrap('chargeback');
-    default:
-      return null;
-  }
-}
-
-/**
- * Creates a reporter bound to your AgentsBloom account key.
- *
- * @param {object} options
- * @param {string} options.apiKey - partner API key (ag_live_... / ag_test_...)
- * @param {string} [options.collectorUrl] - backend base URL
- *   (default https://api.agentsbloom.com)
- * @param {(url:string, init:object)=>Promise<Response>} [options.fetchImpl]
- */
-export function createOutcomeReporter({ apiKey, collectorUrl, fetchImpl } = {}) {
-  const base = String(collectorUrl || process.env.AGENTSBLOOM_API_URL || 'https://api.agentsbloom.com').replace(/\/$/, '');
-  const doFetch = fetchImpl ?? fetch;
-
-  async function report(body) {
-    if (!apiKey) throw new Error('createOutcomeReporter requires your AgentsBloom apiKey');
-    if (!body || !body.orderRef || !DEFAULT_STATUSES.includes(body.status)) {
-      throw new Error('reportPaymentOutcome requires orderRef and status (paid|declined|refunded|chargeback|disputed|canceled)');
-    }
-    const res = await doFetch(`${base}/api/outcomes`, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        authorization: `Bearer ${apiKey}`,
-      },
-      body: JSON.stringify({
-        gateway: 'stripe',
-        ...body,
-      }),
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => '');
-      throw new Error(`outcome report failed: HTTP ${res.status} ${text.slice(0, 200)}`);
-    }
-    return res.json();
-  }
-
-  /** Reports a raw Stripe webhook event (no-op for non-outcome events). */
-  async function captureStripeOutcome(stripeEvent) {
-    const body = stripeEventToOutcome(stripeEvent);
-    if (!body) return { skipped: true };
-    return report(body);
-  }
-
-  return { report, captureStripeOutcome };
-}
+/**
+ * Payment-outcome reporting (migration 011 / POST /api/outcomes).
+ *
+ * AgentsBloom is the middleman: the merchant's gateway keys stay on THEIR
+ * servers, inside THEIR webhook handlers. That also means payment outcomes
+ * (paid / declined / chargeback) happen where we cannot see them - so this
+ * module lets the merchant's existing webhook handler report the outcome
+ * with one line. Those reports are what turn risk-core's decline-rate rules
+ * from theory into data, and what powers the dashboard's outcome analytics.
+ *
+ * Keys never leave the merchant: they only ever send order references,
+ * statuses, and optional amounts.
+ */
+
+const DEFAULT_STATUSES = ['paid', 'declined', 'refunded', 'chargeback', 'disputed', 'canceled'];
+
+/**
+ * Maps a Stripe webhook event to an outcome report body. Returns null for
+ * events that carry no outcome signal, so handlers can do:
+ *
+ *   const report = stripeEventToOutcome(event);
+ *   if (report) await reportPaymentOutcome(report);
+ */
+export function stripeEventToOutcome(event) {
+  const type = event?.type;
+  const wrap = (status, extra = {}) => {
+    const obj = event?.data?.object ?? {};
+    return {
+      orderRef:
+        obj.metadata?.orderRef ??
+        obj.client_reference_id ??
+        obj.id,
+      gateway: 'stripe',
+      status,
+      amount: typeof obj.amount_total === 'number'
+        ? obj.amount_total / 100
+        : typeof obj.amount === 'number'
+          ? obj.amount / 100
+          : undefined,
+      currency: typeof obj.currency === 'string' ? obj.currency : undefined,
+      reason: extra.reason ?? obj.failure_message ?? null,
+      occurredAt: event?.created ? new Date(event.created * 1000).toISOString() : undefined,
+    };
+  };
+  switch (type) {
+    case 'checkout.session.completed':
+      return wrap('paid');
+    case 'invoice.payment_failed':
+    case 'charge.failed': {
+      const rep = wrap('declined');
+      rep.reason = event?.data?.object?.failure_message ?? event?.data?.object?.failure_code ?? null;
+      return rep;
+    }
+    case 'charge.refunded':
+      return wrap('refunded');
+    case 'charge.dispute.created':
+      return wrap('chargeback');
+    default:
+      return null;
+  }
+}
+
+/**
+ * Creates a reporter bound to your AgentsBloom account key.
+ *
+ * @param {object} options
+ * @param {string} options.apiKey - partner API key (ag_live_... / ag_test_...)
+ * @param {string} [options.collectorUrl] - backend base URL
+ *   (default https://api.agentsbloom.com)
+ * @param {(url:string, init:object)=>Promise<Response>} [options.fetchImpl]
+ */
+export function createOutcomeReporter({ apiKey, collectorUrl, fetchImpl } = {}) {
+  const base = String(collectorUrl || process.env.AGENTSBLOOM_API_URL || 'https://api.agentsbloom.com').replace(/\/$/, '');
+  const doFetch = fetchImpl ?? fetch;
+
+  async function report(body) {
+    if (!apiKey) throw new Error('createOutcomeReporter requires your AgentsBloom apiKey');
+    if (!body || !body.orderRef || !DEFAULT_STATUSES.includes(body.status)) {
+      throw new Error('reportPaymentOutcome requires orderRef and status (paid|declined|refunded|chargeback|disputed|canceled)');
+    }
+    const res = await doFetch(`${base}/api/outcomes`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        gateway: 'stripe',
+        ...body,
+      }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new Error(`outcome report failed: HTTP ${res.status} ${text.slice(0, 200)}`);
+    }
+    return res.json();
+  }
+
+  /** Reports a raw Stripe webhook event (no-op for non-outcome events). */
+  async function captureStripeOutcome(stripeEvent) {
+    const body = stripeEventToOutcome(stripeEvent);
+    if (!body) return { skipped: true };
+    return report(body);
+  }
+
+  return { report, captureStripeOutcome };
+}