@aimearn/webhook-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,294 @@
+// src/eventId.ts
+import { randomBytes } from "crypto";
+var ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+var ENCODING_LEN = ENCODING.length;
+var TIME_LEN = 10;
+var RANDOM_LEN = 16;
+function encodeTime(now, len) {
+  let out = "";
+  let n = now;
+  for (let i = len - 1; i >= 0; i--) {
+    const mod = n % ENCODING_LEN;
+    out = ENCODING[mod] + out;
+    n = (n - mod) / ENCODING_LEN;
+  }
+  return out;
+}
+function encodeRandom(len) {
+  const bytes = randomBytes(len);
+  let out = "";
+  for (let i = 0; i < len; i++) {
+    out += ENCODING[bytes[i] & 31];
+  }
+  return out;
+}
+function generateEventId(now = Date.now()) {
+  return `evt_${encodeTime(now, TIME_LEN)}${encodeRandom(RANDOM_LEN)}`;
+}
+
+// src/signing.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var REPLAY_WINDOW_SECONDS = 300;
+function signRequest(secret, rawBody, now = Math.floor(Date.now() / 1e3)) {
+  const v1 = createHmac("sha256", secret).update(`${now}.${rawBody}`).digest("hex");
+  return `t=${now},v1=${v1}`;
+}
+function parseSignatureHeader(header) {
+  if (!header) return null;
+  let t = null;
+  let v1 = null;
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) return null;
+    const k = part.slice(0, eq).trim();
+    const v = part.slice(eq + 1).trim();
+    if (k === "t") {
+      const parsed = Number(v);
+      if (!Number.isFinite(parsed) || parsed <= 0) return null;
+      t = parsed;
+    } else if (k === "v1") {
+      if (!/^[0-9a-f]{64}$/.test(v)) return null;
+      v1 = v;
+    }
+  }
+  if (t === null || v1 === null) return null;
+  return { t, v1 };
+}
+function verifyResponseSignature(secret, headerValue, responseBody, nowSeconds = Math.floor(Date.now() / 1e3)) {
+  const sig = parseSignatureHeader(headerValue);
+  if (!sig) return false;
+  if (Math.abs(nowSeconds - sig.t) > REPLAY_WINDOW_SECONDS) return false;
+  const expected = createHmac("sha256", secret).update(`${sig.t}.${responseBody}`).digest("hex");
+  if (expected.length !== sig.v1.length) return false;
+  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
+}
+
+// src/errors.ts
+var AimearnError = class extends Error {
+  code;
+  status;
+  responseBody;
+  constructor(code, message, status, responseBody) {
+    super(message);
+    this.name = "AimearnError";
+    this.code = code;
+    this.status = status;
+    this.responseBody = responseBody;
+  }
+};
+var AimearnAuthError = class extends AimearnError {
+  constructor(code, message, status = 401, responseBody) {
+    super(code, message, status, responseBody);
+    this.name = "AimearnAuthError";
+  }
+};
+var AimearnValidationError = class extends AimearnError {
+  constructor(code, message, status = 400, responseBody) {
+    super(code, message, status, responseBody);
+    this.name = "AimearnValidationError";
+  }
+};
+var AimearnNotFoundError = class extends AimearnError {
+  constructor(code, message, status = 404, responseBody) {
+    super(code, message, status, responseBody);
+    this.name = "AimearnNotFoundError";
+  }
+};
+var AimearnForbiddenError = class extends AimearnError {
+  constructor(code, message, status = 403, responseBody) {
+    super(code, message, status, responseBody);
+    this.name = "AimearnForbiddenError";
+  }
+};
+var AimearnConflictError = class extends AimearnError {
+  constructor(code, message, status = 409, responseBody) {
+    super(code, message, status, responseBody);
+    this.name = "AimearnConflictError";
+  }
+};
+var AimearnPlatformError = class extends AimearnError {
+  constructor(code, message, status = 500, responseBody) {
+    super(code, message, status, responseBody);
+    this.name = "AimearnPlatformError";
+  }
+};
+var ERROR_CTOR_BY_STATUS = {
+  400: AimearnValidationError,
+  401: AimearnAuthError,
+  403: AimearnForbiddenError,
+  404: AimearnNotFoundError,
+  409: AimearnConflictError,
+  413: AimearnValidationError,
+  429: AimearnPlatformError
+};
+function errorFromResponse(status, body) {
+  const errorCode = typeof body === "object" && body !== null && "error" in body && typeof body.error === "string" ? body.error : "internal_error";
+  const Ctor = ERROR_CTOR_BY_STATUS[status] ?? (status >= 500 ? AimearnPlatformError : AimearnError);
+  return new Ctor(
+    errorCode,
+    `Aim Earn ${status}: ${errorCode}`,
+    status,
+    body
+  );
+}
+
+// src/retry.ts
+var DEFAULTS = {
+  maxAttempts: 24,
+  baseDelayMs: 1e3,
+  maxDelayMs: 6e4,
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+function resolveRetryConfig(config) {
+  return { ...DEFAULTS, ...config ?? {} };
+}
+function isRetriable(status) {
+  return status === 0 || status === 429 || status >= 500;
+}
+function backoffDelayMs(attempt, config) {
+  if (attempt <= 1) return 0;
+  const raw = config.baseDelayMs * 2 ** (attempt - 2);
+  return Math.min(raw, config.maxDelayMs);
+}
+
+// src/client.ts
+var ROUTE = "/api/webhooks/order";
+var AimearnClient = class {
+  config;
+  constructor(config) {
+    if (!config.keyId) throw new Error("AimearnClient: keyId is required.");
+    if (!config.secret) throw new Error("AimearnClient: secret is required.");
+    if (!config.endpoint) throw new Error("AimearnClient: endpoint is required.");
+    this.config = {
+      keyId: config.keyId,
+      secret: config.secret,
+      endpoint: config.endpoint.replace(/\/$/, ""),
+      fetch: config.fetch ?? globalThis.fetch.bind(globalThis),
+      retry: resolveRetryConfig(config.retry)
+    };
+  }
+  orderCompleted(input) {
+    return this.send("order.completed", input);
+  }
+  orderShipped(input) {
+    return this.send("order.shipped", input);
+  }
+  orderRefunded(input) {
+    return this.send("order.refunded", input);
+  }
+  orderCancelled(input) {
+    return this.send("order.cancelled", input);
+  }
+  async send(type, input) {
+    const envelope = {
+      eventId: input.eventId ?? generateEventId(),
+      type,
+      occurredAt: input.occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      orderId: input.orderId,
+      data: input.data,
+      metadata: input.metadata ?? null
+    };
+    const rawBody = JSON.stringify(envelope);
+    const url = `${this.config.endpoint}${ROUTE}`;
+    return this.executeWithRetry(url, rawBody);
+  }
+  async executeWithRetry(url, rawBody) {
+    const { maxAttempts, sleep } = this.config.retry;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const delayMs = backoffDelayMs(attempt, this.config.retry);
+      if (delayMs > 0) await sleep(delayMs);
+      try {
+        return await this.attemptOnce(url, rawBody);
+      } catch (err) {
+        if (!(err instanceof AimearnError)) throw err;
+        lastError = err;
+        if (!isRetriable(err.status)) {
+          throw err;
+        }
+      }
+    }
+    throw lastError ?? new AimearnPlatformError(
+      "internal_error",
+      "AimearnClient retry budget exhausted with no error captured.",
+      500
+    );
+  }
+  async attemptOnce(url, rawBody) {
+    const sigHeader = signRequest(this.config.secret, rawBody);
+    let response;
+    try {
+      response = await this.config.fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Aimearn-Key-Id": this.config.keyId,
+          "X-Aimearn-Signature": sigHeader
+        },
+        body: rawBody
+      });
+    } catch (err) {
+      throw new AimearnPlatformError(
+        "network_error",
+        `Network error during webhook POST: ${err.message ?? err}`,
+        0
+      );
+    }
+    const responseBody = await response.text();
+    if (response.status >= 200 && response.status < 300) {
+      const sigOk = verifyResponseSignature(
+        this.config.secret,
+        response.headers.get("x-aimearn-response-signature"),
+        responseBody
+      );
+      if (!sigOk) {
+        throw new AimearnPlatformError(
+          "response_signature_failed",
+          `Aim Earn response signature missing or invalid (HTTP ${response.status}).`,
+          response.status,
+          responseBody
+        );
+      }
+      try {
+        return JSON.parse(responseBody);
+      } catch {
+        throw new AimearnPlatformError(
+          "internal_error",
+          "Aim Earn returned 2xx with an unparseable JSON body.",
+          response.status,
+          responseBody
+        );
+      }
+    }
+    let parsed = responseBody;
+    try {
+      parsed = JSON.parse(responseBody);
+    } catch {
+    }
+    throw errorFromResponse(response.status, parsed);
+  }
+};
+
+// src/index.ts
+var SDK_VERSION = "0.1.0";
+export {
+  AimearnAuthError,
+  AimearnClient,
+  AimearnConflictError,
+  AimearnError,
+  AimearnForbiddenError,
+  AimearnNotFoundError,
+  AimearnPlatformError,
+  AimearnValidationError,
+  REPLAY_WINDOW_SECONDS,
+  SDK_VERSION,
+  backoffDelayMs,
+  errorFromResponse,
+  generateEventId,
+  isRetriable,
+  parseSignatureHeader,
+  resolveRetryConfig,
+  signRequest,
+  verifyResponseSignature
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/eventId.ts","../src/signing.ts","../src/errors.ts","../src/retry.ts","../src/client.ts","../src/index.ts"],"sourcesContent":["// Stripe-style ULID-shaped idempotency key, formatted as\n// `evt_<26-char-base32-crockford>`. Same external shape as our backend\n// uses, but generated client-side so brands can collapse retries from\n// the same call site naturally — re-issuing the same `eventId` against\n// the platform is idempotent (the ingest Lambda's\n// `attribute_not_exists(orderId)` guard catches duplicates).\n//\n// Deliberately not pulling in the `ulid` npm package — keeping the\n// SDK dependency-free at runtime keeps the install size small and\n// avoids supply-chain surface. The implementation below is a faithful\n// 48-bit-time + 80-bit-randomness ULID with Crockford base32, matching\n// the spec at https://github.com/ulid/spec.\n\nimport { randomBytes } from \"node:crypto\";\n\nconst ENCODING = \"0123456789ABCDEFGHJKMNPQRSTVWXYZ\"; // Crockford base32\nconst ENCODING_LEN = ENCODING.length;\nconst TIME_LEN = 10;\nconst RANDOM_LEN = 16;\n\nfunction encodeTime(now: number, len: number): string {\n  let out = \"\";\n  let n = now;\n  for (let i = len - 1; i >= 0; i--) {\n    const mod = n % ENCODING_LEN;\n    out = ENCODING[mod] + out;\n    n = (n - mod) / ENCODING_LEN;\n  }\n  return out;\n}\n\nfunction encodeRandom(len: number): string {\n  // 1 byte = 256 values; we map each to one of 32 base32 chars by\n  // taking the low 5 bits. Equivalent randomness density.\n  const bytes = randomBytes(len);\n  let out = \"\";\n  for (let i = 0; i < len; i++) {\n    out += ENCODING[bytes[i] & 31];\n  }\n  return out;\n}\n\n/**\n * Returns a fresh idempotency key of shape `evt_<ULID>`.\n * 48-bit timestamp (millisecond precision) + 80-bit randomness.\n * Sortable lexicographically by creation time.\n */\nexport function generateEventId(now: number = Date.now()): string {\n  return `evt_${encodeTime(now, TIME_LEN)}${encodeRandom(RANDOM_LEN)}`;\n}\n","// HMAC-SHA256 signing + verification for the Aim Earn webhook contract.\n// Spec: 2026-04-29-webhook-ingest-design.md §5.\n//\n// Request:\n//   X-Aimearn-Signature: t=<unix>,v1=<hex>\n//   v1 = HMAC-SHA256(secret, `${t}.${rawBody}`)\n//\n// Response:\n//   X-Aimearn-Response-Signature: same shape; same per-brand secret.\n//\n// Brand SDK side: we sign every outbound request and verify every\n// inbound response. Replay window 300s.\n\nimport { createHmac, timingSafeEqual } from \"node:crypto\";\n\nexport const REPLAY_WINDOW_SECONDS = 300;\n\n/**\n * Builds the `X-Aimearn-Signature` header value for a request body.\n * Caller supplies the raw body bytes — never re-serialize after\n * signing, or the platform's HMAC verify will fail.\n */\nexport function signRequest(\n  secret: string,\n  rawBody: string,\n  now: number = Math.floor(Date.now() / 1000),\n): string {\n  const v1 = createHmac(\"sha256\", secret)\n    .update(`${now}.${rawBody}`)\n    .digest(\"hex\");\n  return `t=${now},v1=${v1}`;\n}\n\nexport interface ParsedSignature {\n  t: number;\n  v1: string;\n}\n\n/**\n * Parses a `t=<unix>,v1=<hex>` header. Returns null on any malformed\n * input — caller treats null as \"missing/unverifiable signature.\"\n */\nexport function parseSignatureHeader(\n  header: string | undefined | null,\n): ParsedSignature | null {\n  if (!header) return null;\n\n  let t: number | null = null;\n  let v1: string | null = null;\n  for (const part of header.split(\",\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq < 0) return null;\n    const k = part.slice(0, eq).trim();\n    const v = part.slice(eq + 1).trim();\n    if (k === \"t\") {\n      const parsed = Number(v);\n      if (!Number.isFinite(parsed) || parsed <= 0) return null;\n      t = parsed;\n    } else if (k === \"v1\") {\n      // 64 lowercase hex chars for SHA-256.\n      if (!/^[0-9a-f]{64}$/.test(v)) return null;\n      v1 = v;\n    }\n  }\n  if (t === null || v1 === null) return null;\n  return { t, v1 };\n}\n\n/**\n * Verifies the platform's response signature against the response\n * body bytes. Returns true on match, false on any failure (missing\n * header, stale timestamp, mismatched HMAC). Brand SDK must reject\n * 2xx responses without a verifiable signature; 4xx/5xx may be\n * accepted as platform-level errors per spec §5.5.\n */\nexport function verifyResponseSignature(\n  secret: string,\n  headerValue: string | undefined | null,\n  responseBody: string,\n  nowSeconds: number = Math.floor(Date.now() / 1000),\n): boolean {\n  const sig = parseSignatureHeader(headerValue);\n  if (!sig) return false;\n  if (Math.abs(nowSeconds - sig.t) > REPLAY_WINDOW_SECONDS) return false;\n\n  const expected = createHmac(\"sha256\", secret)\n    .update(`${sig.t}.${responseBody}`)\n    .digest(\"hex\");\n\n  if (expected.length !== sig.v1.length) return false;\n  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));\n}\n","// Typed error hierarchy mapping platform `WebhookDelivery.result`\n// values onto SDK-side error classes. Brand error handlers can switch\n// on `error.code` (the wire-format result string) or use `instanceof`.\n//\n// Spec: 2026-04-29-webhook-ingest-design.md §10.1 retry contract.\n\nexport type AimearnErrorCode =\n  | \"signature_failed\"\n  | \"parse_error\"\n  | \"duplicate\"\n  | \"country_not_published\"\n  | \"product_not_found\"\n  | \"unknown_referral\"\n  | \"discarded\"\n  | \"brand_not_found\"\n  | \"brand_disabled\"\n  | \"missing_key_id\"\n  | \"rate_limited\"\n  | \"body_too_large\"\n  | \"unknown_event_type\"\n  | \"unknown_order\"\n  | \"brand_mismatch\"\n  | \"cancelled_after_shipment\"\n  | \"invalid_item_index\"\n  | \"subtotal_mismatch\"\n  | \"too_many_items\"\n  // SDK-side codes for failure modes that don't reach the platform:\n  | \"network_error\"\n  | \"response_signature_failed\"\n  | \"internal_error\";\n\nexport class AimearnError extends Error {\n  readonly code: AimearnErrorCode;\n  readonly status: number;\n  readonly responseBody?: unknown;\n\n  constructor(\n    code: AimearnErrorCode,\n    message: string,\n    status: number,\n    responseBody?: unknown,\n  ) {\n    super(message);\n    this.name = \"AimearnError\";\n    this.code = code;\n    this.status = status;\n    this.responseBody = responseBody;\n  }\n}\n\n/** 401 — signature/auth failure. Brand should fix secret/clock; do NOT retry. */\nexport class AimearnAuthError extends AimearnError {\n  constructor(code: AimearnErrorCode, message: string, status = 401, responseBody?: unknown) {\n    super(code, message, status, responseBody);\n    this.name = \"AimearnAuthError\";\n  }\n}\n\n/** 400 — payload schema violation. Brand-side bug; do NOT retry. */\nexport class AimearnValidationError extends AimearnError {\n  constructor(code: AimearnErrorCode, message: string, status = 400, responseBody?: unknown) {\n    super(code, message, status, responseBody);\n    this.name = \"AimearnValidationError\";\n  }\n}\n\n/** 404 — referenced order or brand not found. Brand should re-check IDs; do NOT retry. */\nexport class AimearnNotFoundError extends AimearnError {\n  constructor(code: AimearnErrorCode, message: string, status = 404, responseBody?: unknown) {\n    super(code, message, status, responseBody);\n    this.name = \"AimearnNotFoundError\";\n  }\n}\n\n/** 403 — brand disabled / brand-mismatch. Escalate to platform admin. */\nexport class AimearnForbiddenError extends AimearnError {\n  constructor(code: AimearnErrorCode, message: string, status = 403, responseBody?: unknown) {\n    super(code, message, status, responseBody);\n    this.name = \"AimearnForbiddenError\";\n  }\n}\n\n/** 409 — state-machine violation (e.g. order.cancelled after shipment). */\nexport class AimearnConflictError extends AimearnError {\n  constructor(code: AimearnErrorCode, message: string, status = 409, responseBody?: unknown) {\n    super(code, message, status, responseBody);\n    this.name = \"AimearnConflictError\";\n  }\n}\n\n/** 5xx / network — platform-side error. SDK retries automatically up to the configured limit. */\nexport class AimearnPlatformError extends AimearnError {\n  constructor(code: AimearnErrorCode, message: string, status = 500, responseBody?: unknown) {\n    super(code, message, status, responseBody);\n    this.name = \"AimearnPlatformError\";\n  }\n}\n\nconst ERROR_CTOR_BY_STATUS: Record<number, typeof AimearnError> = {\n  400: AimearnValidationError,\n  401: AimearnAuthError,\n  403: AimearnForbiddenError,\n  404: AimearnNotFoundError,\n  409: AimearnConflictError,\n  413: AimearnValidationError,\n  429: AimearnPlatformError,\n};\n\n/**\n * Converts an HTTP error response into the right SDK error class.\n * `code` is the platform's `error` field from the response body; falls\n * back to `internal_error` if the body shape is unexpected.\n */\nexport function errorFromResponse(\n  status: number,\n  body: unknown,\n): AimearnError {\n  const errorCode =\n    typeof body === \"object\" &&\n    body !== null &&\n    \"error\" in body &&\n    typeof (body as { error: unknown }).error === \"string\"\n      ? ((body as { error: AimearnErrorCode }).error)\n      : \"internal_error\";\n\n  const Ctor =\n    ERROR_CTOR_BY_STATUS[status] ??\n    (status >= 500 ? AimearnPlatformError : AimearnError);\n\n  return new Ctor(\n    errorCode,\n    `Aim Earn ${status}: ${errorCode}`,\n    status,\n    body,\n  );\n}\n","// Exponential-backoff retry policy for the SDK's outbound POSTs.\n// Spec: 2026-04-29-webhook-ingest-design.md §10.1.\n//\n// 2xx → return result\n// 4xx (except 429) → throw immediately, no retry\n// 429 / 5xx / network → retry with exponential backoff\n//\n// Default: 1s, 2s, 4s, 8s, 16s, 32s, 60s, 60s, … up to 24 attempts ≈ 24h.\n\nexport interface RetryConfig {\n  /** Maximum number of total attempts (including the first). Default 24. */\n  maxAttempts?: number;\n  /** Base delay in milliseconds. Default 1000. */\n  baseDelayMs?: number;\n  /** Cap individual delay; default 60_000ms. */\n  maxDelayMs?: number;\n  /**\n   * Hook for tests / cancellation. Receives the milliseconds the SDK\n   * intends to sleep; should resolve after that delay (or reject to\n   * abort the retry loop).\n   */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst DEFAULTS: Required<RetryConfig> = {\n  maxAttempts: 24,\n  baseDelayMs: 1000,\n  maxDelayMs: 60_000,\n  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),\n};\n\nexport function resolveRetryConfig(\n  config?: RetryConfig,\n): Required<RetryConfig> {\n  return { ...DEFAULTS, ...(config ?? {}) };\n}\n\n/**\n * Returns true if the platform's HTTP status (or the SDK's network-error\n * sentinel of 0) should trigger a retry.\n *\n *   - 0    — fetch threw; treat as retriable network failure\n *   - 429  — explicit rate-limit; back off and retry\n *   - 5xx  — platform-side error; retry per spec §10.1\n */\nexport function isRetriable(status: number): boolean {\n  return status === 0 || status === 429 || status >= 500;\n}\n\n/**\n * Pure delay-curve calculator. Attempt number is 1-indexed (the\n * first retry — i.e. the 2nd total attempt — uses attempt=2).\n */\nexport function backoffDelayMs(\n  attempt: number,\n  config: Required<RetryConfig>,\n): number {\n  // Exponential: base * 2^(attempt - 1). attempt=1 → no delay (initial\n  // call); attempt=2 → base; attempt=3 → 2*base; ...\n  if (attempt <= 1) return 0;\n  const raw = config.baseDelayMs * 2 ** (attempt - 2);\n  return Math.min(raw, config.maxDelayMs);\n}\n","// Aim Earn webhook client. Brand-facing API surface:\n//\n//   const client = new AimearnClient({ keyId, secret, endpoint });\n//   await client.orderCompleted({ orderId, data: {...} });\n//   await client.orderShipped({ orderId, data: {...} });\n//   await client.orderRefunded({ orderId, data: {...} });\n//   await client.orderCancelled({ orderId, data: {...} });\n//\n// Each method:\n//   1. Builds the envelope (auto-generates eventId via ULID if omitted)\n//   2. Serializes once to a stable string (the same bytes get signed)\n//   3. Signs with HMAC-SHA256 over `${t}.${rawBody}` per spec §5\n//   4. POSTs with X-Aimearn-Key-Id + X-Aimearn-Signature\n//   5. Retries 5xx/429 with exponential backoff up to maxAttempts\n//   6. Verifies the X-Aimearn-Response-Signature on 2xx (throws if missing/invalid)\n//   7. Returns the parsed AcceptedResponse, or throws a typed AimearnError\n\nimport { generateEventId } from \"./eventId\";\nimport { signRequest, verifyResponseSignature } from \"./signing\";\nimport {\n  AimearnError,\n  AimearnPlatformError,\n  errorFromResponse,\n} from \"./errors\";\nimport {\n  backoffDelayMs,\n  isRetriable,\n  resolveRetryConfig,\n  type RetryConfig,\n} from \"./retry\";\nimport type {\n  AcceptedResponse,\n  Envelope,\n  OrderCancelledInput,\n  OrderCompletedInput,\n  OrderRefundedInput,\n  OrderShippedInput,\n  WireEventType,\n} from \"./types\";\n\nexport interface AimearnClientConfig {\n  /** Brand identifier registered with Aim Earn. Sent as X-Aimearn-Key-Id. */\n  keyId: string;\n  /**\n   * Cleartext webhook secret returned by the Aim Earn admin\n   * `rotateBrandWebhookSecret` mutation. Used to sign requests and\n   * verify response signatures. NEVER log this.\n   */\n  secret: string;\n  /**\n   * Full base URL, e.g. `https://webhooks.aimearn.platform.com` or the\n   * sandbox auto-generated `https://abc123.execute-api.region.amazonaws.com`.\n   */\n  endpoint: string;\n  /** Optional fetch override for testing / non-Node runtimes. Defaults to global fetch. */\n  fetch?: typeof globalThis.fetch;\n  retry?: RetryConfig;\n}\n\nconst ROUTE = \"/api/webhooks/order\";\n\nexport class AimearnClient {\n  private readonly config: Required<\n    Pick<AimearnClientConfig, \"keyId\" | \"secret\" | \"endpoint\">\n  > & {\n    fetch: typeof globalThis.fetch;\n    retry: ReturnType<typeof resolveRetryConfig>;\n  };\n\n  constructor(config: AimearnClientConfig) {\n    if (!config.keyId) throw new Error(\"AimearnClient: keyId is required.\");\n    if (!config.secret) throw new Error(\"AimearnClient: secret is required.\");\n    if (!config.endpoint) throw new Error(\"AimearnClient: endpoint is required.\");\n\n    this.config = {\n      keyId: config.keyId,\n      secret: config.secret,\n      endpoint: config.endpoint.replace(/\\/$/, \"\"),\n      fetch: config.fetch ?? globalThis.fetch.bind(globalThis),\n      retry: resolveRetryConfig(config.retry),\n    };\n  }\n\n  orderCompleted(input: OrderCompletedInput): Promise<AcceptedResponse> {\n    return this.send(\"order.completed\", input);\n  }\n\n  orderShipped(input: OrderShippedInput): Promise<AcceptedResponse> {\n    return this.send(\"order.shipped\", input);\n  }\n\n  orderRefunded(input: OrderRefundedInput): Promise<AcceptedResponse> {\n    return this.send(\"order.refunded\", input);\n  }\n\n  orderCancelled(input: OrderCancelledInput): Promise<AcceptedResponse> {\n    return this.send(\"order.cancelled\", input);\n  }\n\n  private async send<TData>(\n    type: WireEventType,\n    input: {\n      orderId: string;\n      eventId?: string;\n      occurredAt?: string;\n      data: TData;\n      metadata?: Record<string, unknown> | null;\n    },\n  ): Promise<AcceptedResponse> {\n    const envelope: Envelope<TData> = {\n      eventId: input.eventId ?? generateEventId(),\n      type,\n      occurredAt: input.occurredAt ?? new Date().toISOString(),\n      orderId: input.orderId,\n      data: input.data,\n      metadata: input.metadata ?? null,\n    };\n    const rawBody = JSON.stringify(envelope);\n\n    const url = `${this.config.endpoint}${ROUTE}`;\n\n    return this.executeWithRetry(url, rawBody);\n  }\n\n  private async executeWithRetry(\n    url: string,\n    rawBody: string,\n  ): Promise<AcceptedResponse> {\n    const { maxAttempts, sleep } = this.config.retry;\n    let lastError: AimearnError | undefined;\n\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      const delayMs = backoffDelayMs(attempt, this.config.retry);\n      if (delayMs > 0) await sleep(delayMs);\n\n      try {\n        return await this.attemptOnce(url, rawBody);\n      } catch (err) {\n        if (!(err instanceof AimearnError)) throw err;\n        lastError = err;\n\n        if (!isRetriable(err.status)) {\n          throw err;\n        }\n        // Retriable — fall through to next iteration.\n      }\n    }\n\n    throw (\n      lastError ??\n      new AimearnPlatformError(\n        \"internal_error\",\n        \"AimearnClient retry budget exhausted with no error captured.\",\n        500,\n      )\n    );\n  }\n\n  private async attemptOnce(\n    url: string,\n    rawBody: string,\n  ): Promise<AcceptedResponse> {\n    const sigHeader = signRequest(this.config.secret, rawBody);\n\n    let response: Response;\n    try {\n      response = await this.config.fetch(url, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          \"X-Aimearn-Key-Id\": this.config.keyId,\n          \"X-Aimearn-Signature\": sigHeader,\n        },\n        body: rawBody,\n      });\n    } catch (err) {\n      // Network failure — retriable per spec §10.1. Wrap as\n      // AimearnPlatformError(status:0) so the retry loop catches it.\n      throw new AimearnPlatformError(\n        \"network_error\",\n        `Network error during webhook POST: ${(err as Error).message ?? err}`,\n        0,\n      );\n    }\n\n    const responseBody = await response.text();\n\n    // Verify response signature on 2xx — required per spec §5.5 brand\n    // contract. Missing/invalid signature on a 2xx is a fatal trust\n    // boundary violation.\n    if (response.status >= 200 && response.status < 300) {\n      const sigOk = verifyResponseSignature(\n        this.config.secret,\n        response.headers.get(\"x-aimearn-response-signature\"),\n        responseBody,\n      );\n      if (!sigOk) {\n        throw new AimearnPlatformError(\n          \"response_signature_failed\",\n          `Aim Earn response signature missing or invalid (HTTP ${response.status}).`,\n          response.status,\n          responseBody,\n        );\n      }\n      try {\n        return JSON.parse(responseBody) as AcceptedResponse;\n      } catch {\n        throw new AimearnPlatformError(\n          \"internal_error\",\n          \"Aim Earn returned 2xx with an unparseable JSON body.\",\n          response.status,\n          responseBody,\n        );\n      }\n    }\n\n    // 4xx / 5xx — parse the error body if possible and throw the\n    // typed error class.\n    let parsed: unknown = responseBody;\n    try {\n      parsed = JSON.parse(responseBody);\n    } catch {\n      // Leave parsed as the raw string.\n    }\n    throw errorFromResponse(response.status, parsed);\n  }\n}\n","// @aimearn/webhook-sdk public surface (server entry).\n//\n// Spec: docs/superpowers/specs/2026-04-29-webhook-ingest-design.md\n// Docs: /docs/sdk in the host app\n\nexport const SDK_VERSION = \"0.1.0\";\n\nexport { AimearnClient } from \"./client\";\nexport type { AimearnClientConfig } from \"./client\";\n\nexport { generateEventId } from \"./eventId\";\nexport {\n  signRequest,\n  verifyResponseSignature,\n  parseSignatureHeader,\n  REPLAY_WINDOW_SECONDS,\n} from \"./signing\";\n\nexport {\n  AimearnError,\n  AimearnAuthError,\n  AimearnValidationError,\n  AimearnNotFoundError,\n  AimearnForbiddenError,\n  AimearnConflictError,\n  AimearnPlatformError,\n  errorFromResponse,\n} from \"./errors\";\nexport type { AimearnErrorCode } from \"./errors\";\n\nexport {\n  isRetriable,\n  backoffDelayMs,\n  resolveRetryConfig,\n} from \"./retry\";\nexport type { RetryConfig } from \"./retry\";\n\nexport type {\n  WireEventType,\n  CompletedItem,\n  CustomerInfo,\n  CompletedData,\n  ShippedData,\n  RefundedData,\n  CancelledData,\n  Envelope,\n  OrderCompletedInput,\n  OrderShippedInput,\n  OrderRefundedInput,\n  OrderCancelledInput,\n  AcceptedResponse,\n} from \"./types\";\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@aimearn/webhook-sdk",
+  "version": "0.1.0",
+  "description": "Brand SDK for the Aim Earn webhook ingest API — HMAC signing, response verification, retries, idempotency.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "aimearn",
+    "webhook",
+    "affiliate",
+    "commission",
+    "sdk",
+    "hmac",
+    "ecommerce"
+  ],
+  "homepage": "https://github.com/sangium47/aim-earn/tree/master/packages/webhook-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sangium47/aim-earn.git",
+    "directory": "packages/webhook-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/sangium47/aim-earn/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5"
+  }
+}