@scaletrail/connector 0.0.0-stage → 0.1.0

package/src/signature.js

@@ -0,0 +1,123 @@
+// Request signing: HMAC-SHA256(secret, "<timestamp>.<raw body>"), hex, sent as "v1=<hex>".
+// Uses Web Crypto only, so it runs unchanged in Cloudflare Workers, Deno, Bun and Node 20+.
+
+import { VERSION } from './version.js';
+
+export const TIMESTAMP_TOLERANCE_SECONDS = 300;
+
+const KEY_ID_RE = /^ck_[0-9a-f]{24}$/;
+const SIGNATURE_RE = /^v1=([0-9a-f]{64})$/;
+const CONNECTOR_RE = /^[\x21-\x7e][\x20-\x7e]{0,119}$/;
+const enc = new TextEncoder();
+
+/**
+ * @param {string|Uint8Array|ArrayBuffer} body
+ * @returns {Uint8Array}
+ */
+export function toBytes(body) {
+  if (typeof body === 'string') return enc.encode(body);
+  if (body instanceof Uint8Array) return body;
+  if (body instanceof ArrayBuffer) return new Uint8Array(body);
+  throw new TypeError('body must be a string, Uint8Array or ArrayBuffer');
+}
+
+function toHex(buf) {
+  return Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+function assertSecret(secret) {
+  if (typeof secret !== 'string' || secret.length === 0) throw new TypeError('secret must be a non-empty string');
+}
+
+// The signing secret belongs on the shop's server. A page that could sign requests would hand the
+// secret to every visitor.
+function assertServerSide() {
+  if (typeof globalThis.window !== 'undefined' && typeof globalThis.document !== 'undefined') {
+    throw new Error('signing must run on the server, never in a browser');
+  }
+}
+
+function assertTimestamp(timestamp) {
+  if (!Number.isInteger(timestamp) || timestamp < 1e9 || timestamp >= 1e10) {
+    throw new TypeError('timestamp must be Unix seconds with 10 digits');
+  }
+}
+
+/**
+ * Signature of a request body as 64 lower-case hex characters.
+ * @param {string} secret  signing secret
+ * @param {number} timestamp  Unix seconds
+ * @param {string|Uint8Array|ArrayBuffer} body  the exact bytes that are sent
+ * @returns {Promise<string>}
+ */
+export async function computeSignature(secret, timestamp, body) {
+  assertServerSide();
+  assertSecret(secret);
+  assertTimestamp(timestamp);
+  const raw = toBytes(body);
+  const prefix = enc.encode(`${timestamp}.`);
+  const msg = new Uint8Array(prefix.length + raw.length);
+  msg.set(prefix, 0);
+  msg.set(raw, prefix.length);
+  const key = await globalThis.crypto.subtle.importKey(
+    'raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
+  );
+  return toHex(await globalThis.crypto.subtle.sign('HMAC', key, msg));
+}
+
+/**
+ * Value for the X-ST-Connector header: the shop's own name and version plus this package.
+ * @param {string} [name]  e.g. "my-shop/2.3.0"
+ * @returns {string}
+ */
+export function connectorHeader(name) {
+  const own = `st-connector/${VERSION}`;
+  const value = name ? `${name} ${own}` : own;
+  if (value.length > 120 || !CONNECTOR_RE.test(value)) {
+    throw new TypeError('connector name must be printable ASCII, at most 120 characters in total');
+  }
+  return value;
+}
+
+/**
+ * Headers for a signed request.
+ * @param {{keyId: string, secret: string, body: string|Uint8Array|ArrayBuffer, timestamp?: number, connector?: string}} opts
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function signRequest({ keyId, secret, body, timestamp = Math.floor(Date.now() / 1000), connector }) {
+  if (typeof keyId !== 'string' || !KEY_ID_RE.test(keyId)) throw new TypeError('keyId must look like ck_ plus 24 hex characters');
+  const signature = await computeSignature(secret, timestamp, body);
+  return {
+    'Content-Type': 'application/json',
+    'X-ST-Key-Id': keyId,
+    'X-ST-Timestamp': String(timestamp),
+    'X-ST-Signature': `v1=${signature}`,
+    'X-ST-Connector': connectorHeader(connector),
+  };
+}
+
+function hexEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+/**
+ * Checks a signature the way ScaleTrail does: format, time window, constant-time comparison.
+ * Meant for tests and mock servers. Never throws; any problem is false.
+ * @param {{secret: string, timestamp: number|string, body: string|Uint8Array|ArrayBuffer, signature: string, nowMs?: number}} opts
+ * @returns {Promise<boolean>}
+ */
+export async function verifySignature({ secret, timestamp, body, signature, nowMs = Date.now() }) {
+  try {
+    const ts = typeof timestamp === 'string' && /^\d{10}$/.test(timestamp) ? Number(timestamp) : timestamp;
+    if (!Number.isInteger(ts)) return false;
+    if (Math.abs(Math.floor(nowMs / 1000) - ts) > TIMESTAMP_TOLERANCE_SECONDS) return false;
+    const m = typeof signature === 'string' ? SIGNATURE_RE.exec(signature) : null;
+    if (!m) return false;
+    return hexEqual(await computeSignature(secret, ts, body), m[1]);
+  } catch {
+    return false;
+  }
+}

package/src/types.d.ts

@@ -0,0 +1,256 @@
+// Generated from the ScaleTrail Connector API v1 JSON Schema. Do not edit by hand.
+// Schema version 1.0.0-draft.6.
+
+export type Cents = number;
+
+export type CentsOrNull = number | null;
+
+export type Datetime = string;
+
+export type DatetimeMs = string;
+
+export type DatetimeOrNull = string | null;
+
+export type Id = string;
+
+export type IdOrNull = string | null;
+
+export type OrderId = string;
+
+export type RefundId = string;
+
+export type Trailiq = string | null;
+
+export type Text = string | null;
+
+export type Uuid = string | null;
+
+export type ClickId = string | null;
+
+export type Currency = string;
+
+export type Country = string | null;
+
+export type Percent = number | null;
+
+export interface OrderMessage {
+  order: Order;
+}
+
+export interface EventMessage {
+  event: EventAddToCart | EventLoginIdentity;
+}
+
+export interface RedactMessage {
+  redact: Redact;
+}
+
+export interface Order {
+  schema_version: "1";
+  order_id: OrderId;
+  order_number?: IdOrNull;
+  origin?: "native" | "migrated";
+  created_at: Datetime;
+  updated_at: DatetimeMs;
+  paid_at?: DatetimeOrNull;
+  status: "pending" | "processing" | "on-hold" | "completed" | "cancelled" | "refunded" | "failed";
+  sales_channel: string;
+  is_test: boolean;
+  currency: Currency;
+  language?: string | null;
+  totals: Totals;
+  items: Item[];
+  discounts?: Discount[];
+  payments?: Payment[];
+  shipments?: Shipment[];
+  refunds?: Refund[];
+  subscription?: null | Subscription;
+  customer: Customer;
+  billing_address?: null | Address;
+  shipping_address?: null | Address;
+  attribution?: null | Attribution;
+  client?: null | Client;
+  consent?: null | Consent;
+}
+
+export interface Totals {
+  total_cents: Cents;
+  subtotal_cents?: CentsOrNull;
+  shipping_cents?: CentsOrNull;
+  discount_cents?: CentsOrNull;
+  tax_cents?: CentsOrNull;
+  taxes_included?: boolean | null;
+  tax_lines?: {
+    rate: number;
+    base_cents?: CentsOrNull;
+    tax_cents: Cents;
+  }[];
+}
+
+export interface Item {
+  line_id: Id;
+  product_id: Id;
+  variant_id?: IdOrNull;
+  sku?: string | null;
+  name: string;
+  quantity: number;
+  unit_price_cents: Cents;
+  line_total_cents: Cents;
+  line_discount_cents?: CentsOrNull;
+  tax_rate?: Percent;
+  unit_cost_cents?: CentsOrNull;
+  category?: Text;
+  is_subscription?: boolean | null;
+}
+
+export interface Discount {
+  source: "coupon" | "rule" | "loyalty_points" | "tier" | "gift_card" | "manual";
+  amount_cents: Cents;
+  code?: string | null;
+  rule_id?: IdOrNull;
+  label?: Text;
+  line_ids?: Id[];
+}
+
+export interface Payment {
+  gateway_id: string;
+  method?: Text;
+  amount_cents: Cents;
+  fee_cents?: CentsOrNull;
+  fee_source?: "provider" | "estimated" | null;
+  status?: "authorized" | "captured" | "failed" | "refunded" | null;
+  captured_at?: DatetimeOrNull;
+}
+
+export interface Shipment {
+  shipment_id: Id;
+  method?: string | null;
+  postage_cents?: CentsOrNull;
+  weight_grams?: number | null;
+  created_at?: DatetimeOrNull;
+}
+
+export interface Refund {
+  refund_id: RefundId;
+  created_at: Datetime;
+  amount_cents: Cents;
+  tax_cents?: CentsOrNull;
+  shipping_cents?: CentsOrNull;
+  reason?: Text;
+  items?: {
+    line_id: Id;
+    quantity: number;
+    amount_cents?: CentsOrNull;
+  }[];
+}
+
+export interface Subscription {
+  subscription_id: Id;
+  is_renewal: boolean;
+  renewal_number?: number | null;
+  status?: "active" | "paused" | "cancelled" | "payment_failed" | null;
+  interval?: string | null;
+  started_at?: DatetimeOrNull;
+}
+
+export interface Customer {
+  customer_id: Id;
+  is_guest?: boolean | null;
+  email?: string | null;
+  phone?: string | null;
+  first_name?: Text;
+  last_name?: Text;
+  order_count?: number | null;
+  first_order_at?: DatetimeOrNull;
+}
+
+export interface Address {
+  street?: Text;
+  postcode?: string | null;
+  city?: Text;
+  region?: Text;
+  country?: Country;
+}
+
+export interface Attribution {
+  sa_uid?: Uuid;
+  click_ids?: {
+    gclid?: ClickId;
+    gbraid?: ClickId;
+    wbraid?: ClickId;
+    fbclid?: ClickId;
+    ttclid?: ClickId;
+    msclkid?: ClickId;
+    oppref?: ClickId;
+    trailiq?: Trailiq;
+    epik?: ClickId;
+    srsltid?: ClickId;
+  };
+  utm?: {
+    source?: string | null;
+    medium?: string | null;
+    campaign?: string | null;
+    content?: string | null;
+    term?: string | null;
+    id?: string | null;
+  };
+  landing_url?: string | null;
+  referrer?: string | null;
+  browser_ids?: {
+    ga?: string | null;
+    fbp?: string | null;
+    fbc?: string | null;
+    ttp?: string | null;
+  };
+  captured_at?: DatetimeOrNull;
+}
+
+export interface Client {
+  ip?: string | null;
+  user_agent?: string | null;
+}
+
+export interface Consent {
+  source: "cookiebot" | "tcf" | "custom" | "none";
+  statistics?: boolean | null;
+  marketing?: boolean | null;
+  captured_at?: DatetimeOrNull;
+}
+
+export interface EventAddToCart {
+  type: "add_to_cart";
+  event_id: string;
+  occurred_at: Datetime;
+  sa_uid?: Uuid;
+  product_id: Id;
+  variant_id?: IdOrNull;
+  sku?: string | null;
+  name?: Text;
+  quantity: number;
+  unit_price_cents: Cents;
+  currency: Currency;
+  page_url?: string | null;
+  client?: null | Client;
+}
+
+export interface EventLoginIdentity {
+  type: "login_identity";
+  event_id: Id;
+  occurred_at: Datetime;
+  sa_uid?: Uuid;
+  customer_id: Id;
+  email?: string | null;
+  phone?: string | null;
+  first_name?: Text;
+  last_name?: Text;
+}
+
+export interface Redact {
+  customer_id: Id;
+  email?: string | null;
+  phone?: string | null;
+  order_ids?: Id[];
+  requested_at: Datetime;
+}
+
+export type ConnectorMessage = OrderMessage | EventMessage | RedactMessage;

package/src/types.js

@@ -0,0 +1,2 @@
+// Types only: the declarations are in types.d.ts. This module exists so the import path resolves.
+export {};

package/src/uuid.js

@@ -0,0 +1,38 @@
+// Visitor IDs: UUID v7 (RFC 9562) for new IDs, v4 and v7 accepted when reading.
+//
+// A UUID v7 starts with a 48-bit millisecond timestamp, so it is predictable in part. Use it for
+// visitor IDs only, never as a secret or token.
+
+const VISITOR_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[47][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/**
+ * New UUID v7.
+ * @param {number} [nowMs] Unix time in milliseconds (default: now)
+ * @returns {string}
+ */
+export function uuidV7(nowMs = Date.now()) {
+  const tsHex = BigInt(Math.floor(nowMs)).toString(16).padStart(12, '0').slice(-12);
+  const rand = globalThis.crypto.getRandomValues(new Uint8Array(10));
+  rand[0] = (rand[0] & 0x0f) | 0x70; // version 7
+  rand[2] = (rand[2] & 0x3f) | 0x80; // variant 10xx
+  const r = Array.from(rand, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `${tsHex.slice(0, 8)}-${tsHex.slice(8, 12)}-${r.slice(0, 4)}-${r.slice(4, 8)}-${r.slice(8, 20)}`;
+}
+
+/**
+ * True for a UUID v4 or v7 in canonical form (any case).
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isVisitorId(value) {
+  return typeof value === 'string' && value.length === 36 && VISITOR_ID_RE.test(value);
+}
+
+/**
+ * Visitor ID in the form the API expects (lower case), or null if invalid.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function normalizeVisitorId(value) {
+  return isVisitorId(value) ? value.toLowerCase() : null;
+}

package/src/validate.js

@@ -0,0 +1,154 @@
+// Validates messages against the Connector API v1 JSON Schema, with the same rules the API applies.
+// Supports exactly the JSON Schema draft-07 keywords the schema uses; loading fails on any other.
+// Results are field paths only, e.g. "order.items[0].quantity", never values.
+//
+// strict: unknown fields are errors (the API does this for ?dry_run=1). Without strict, unknown
+// fields are ignored, as the API does for live requests.
+
+import { SCHEMA } from './schema.js';
+
+const MAX_PATHS = 50;
+
+const MESSAGE_DEFS = Object.freeze({
+  orders: 'order_message',
+  events: 'event_message',
+  redact: 'redact_message',
+});
+
+const SUPPORTED = new Set([
+  '$schema', '$id', '$ref', 'title', 'description', 'version', 'definitions',
+  'type', 'enum', 'pattern', 'minLength', 'maxLength', 'minimum', 'maximum', 'required',
+  'properties', 'additionalProperties', 'items', 'minItems', 'maxItems', 'oneOf',
+]);
+
+function assertSupportedSchema(schema) {
+  (function walk(node, path, inProps) {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+    for (const [k, v] of Object.entries(node)) {
+      if (!inProps && !SUPPORTED.has(k)) throw new Error(`schema keyword not supported: '${k}' at ${path}`);
+      if (k === 'properties' || k === 'definitions') {
+        for (const [name, sub] of Object.entries(v)) walk(sub, `${path}/${k}/${name}`, false);
+      } else if (k === 'oneOf' || (k === 'items' && Array.isArray(v))) {
+        v.forEach((sub, i) => walk(sub, `${path}/${k}/${i}`, false));
+      } else if (k === 'items' || k === 'additionalProperties') {
+        walk(v, `${path}/${k}`, false);
+      }
+    }
+  })(schema, '#', false);
+}
+assertSupportedSchema(SCHEMA);
+
+const regexCache = new Map();
+function regexFor(pattern) {
+  let re = regexCache.get(pattern);
+  if (!re) {
+    re = new RegExp(pattern);
+    regexCache.set(pattern, re);
+  }
+  return re;
+}
+
+function resolve(ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) throw new Error('only local $ref is supported');
+  return ref.slice(2).split('/').reduce((node, key) => node?.[key], SCHEMA);
+}
+
+function typeOf(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  if (typeof v === 'number') return Number.isInteger(v) ? 'integer' : 'number';
+  return typeof v;
+}
+
+function typeMatches(actual, wanted) {
+  return wanted === actual || (wanted === 'number' && actual === 'integer');
+}
+
+function fieldPath(base, key) {
+  return base ? `${base}.${key}` : key;
+}
+
+function check(node, value, path, errors, strict) {
+  if (node.$ref) return check(resolve(node.$ref), value, path, errors, strict);
+  if (node.oneOf) {
+    const results = node.oneOf.map((sub) => {
+      const e = [];
+      check(sub, value, path, e, strict);
+      return e;
+    });
+    const hits = results.filter((e) => e.length === 0).length;
+    if (hits === 1) return;
+    if (hits === 0) {
+      // Report the closest branch so the path points at the field, not at its parent. A branch
+      // that already fails on its own type counts as further away.
+      const own = path || '$';
+      const score = (e) => e.length + (e.length === 1 && e[0] === own ? 0.5 : 0);
+      errors.push(...results.reduce((a, b) => (score(b) < score(a) ? b : a)));
+      return;
+    }
+    errors.push(path || '$');
+    return;
+  }
+  const actual = typeOf(value);
+  if (node.type) {
+    const wanted = Array.isArray(node.type) ? node.type : [node.type];
+    if (!wanted.some((w) => typeMatches(actual, w))) {
+      errors.push(path || '$');
+      return;
+    }
+  }
+  if (node.enum && !node.enum.includes(value)) {
+    errors.push(path || '$');
+    return;
+  }
+  if (actual === 'string') {
+    // Length before pattern: an oversized value never reaches the regex.
+    if (node.maxLength !== undefined && value.length > node.maxLength) { errors.push(path || '$'); return; }
+    if (node.minLength !== undefined && value.length < node.minLength) { errors.push(path || '$'); return; }
+    if (node.pattern && !regexFor(node.pattern).test(value)) { errors.push(path || '$'); return; }
+  }
+  if (actual === 'integer' || actual === 'number') {
+    if (node.minimum !== undefined && value < node.minimum) { errors.push(path || '$'); return; }
+    if (node.maximum !== undefined && value > node.maximum) { errors.push(path || '$'); return; }
+  }
+  if (actual === 'object') {
+    for (const key of node.required || []) {
+      if (!Object.hasOwn(value, key)) errors.push(fieldPath(path, key));
+    }
+    const props = node.properties || {};
+    for (const [key, v] of Object.entries(value)) {
+      if (Object.hasOwn(props, key)) check(props[key], v, fieldPath(path, key), errors, strict);
+      else if (strict && node.additionalProperties === false) errors.push(fieldPath(path, key));
+    }
+  }
+  if (actual === 'array') {
+    if (node.minItems !== undefined && value.length < node.minItems) { errors.push(path || '$'); return; }
+    if (node.maxItems !== undefined && value.length > node.maxItems) { errors.push(path || '$'); return; }
+    if (node.items) value.forEach((v, i) => check(node.items, v, `${path}[${i}]`, errors, strict));
+  }
+}
+
+/**
+ * Field paths that are invalid for a route. Empty array means valid. At most 50, no duplicates.
+ * @param {'orders'|'events'|'redact'} route
+ * @param {unknown} message  parsed JSON body, e.g. {order: {...}}
+ * @param {{strict?: boolean}} [opts]
+ * @returns {string[]}
+ */
+export function validateMessage(route, message, { strict = true } = {}) {
+  const def = MESSAGE_DEFS[route];
+  if (!def) throw new TypeError("route must be 'orders', 'events' or 'redact'");
+  const errors = [];
+  check({ $ref: `#/definitions/${def}` }, message, '', errors, strict);
+  return [...new Set(errors)].slice(0, MAX_PATHS);
+}
+
+/** @param {unknown} message @param {{strict?: boolean}} [opts] */
+export const validateOrderMessage = (message, opts) => validateMessage('orders', message, opts);
+/** @param {unknown} message @param {{strict?: boolean}} [opts] */
+export const validateEventMessage = (message, opts) => validateMessage('events', message, opts);
+/** @param {unknown} message @param {{strict?: boolean}} [opts] */
+export const validateRedactMessage = (message, opts) => validateMessage('redact', message, opts);
+
+/** Schema version this package validates against. */
+export const SCHEMA_VERSION = SCHEMA.version;

package/src/version.js

@@ -0,0 +1,2 @@
+// Kept in sync with package.json by a test.
+export const VERSION = '0.1.0';