@aimearn/webhook-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @aimearn/webhook-sdk changelog
+
+## 0.1.0 — initial release
+
+- `AimearnClient` with `orderCompleted` / `orderShipped` /
+  `orderRefunded` / `orderCancelled` methods.
+- HMAC-SHA256 request signing + response-signature verification
+  (5-minute replay window).
+- Exponential-backoff retry policy (1s → 60s, 24 attempts ≈ 24h).
+- Typed error hierarchy keyed on `WebhookDelivery.result` enum:
+  `AimearnAuthError`, `AimearnValidationError`,
+  `AimearnNotFoundError`, `AimearnForbiddenError`,
+  `AimearnConflictError`, `AimearnPlatformError`.
+- Auto-generated ULID-shaped `eventId`s; brand-supplied IDs are
+  preserved when provided.
+- Browser entry: `captureReferralFromUrl`,
+  `getStoredReferralCode`, `clearReferralCode` for the
+  `?aimearn=…` cookie-based affiliate-link capture flow. ~1KB
+  gzipped, no external deps.
+- Full docs at `/docs/sdk` in the host Next.js app.
+- Runnable Express demo at `examples/webhook-sdk-express/`.
+
+Targets webhook contract `v1`. SDK majors will lag spec majors —
+deprecation window will be published when a breaking spec change
+lands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aim Earn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @aimearn/webhook-sdk
+
+Brand SDK for the Aim Earn webhook ingest API.
+
+Wraps:
+- HMAC-SHA256 request signing + response-signature verification
+- Exponential-backoff retries on 5xx / 429 / network errors
+- ULID-shaped `eventId` auto-generation for idempotent retries
+- Typed error hierarchy keyed on `WebhookDelivery.result`
+- Browser entry for the affiliate-link `?aimearn=…` capture flow
+
+## Install
+
+```bash
+npm install @aimearn/webhook-sdk
+```
+
+(or via the workspace symlink in this monorepo).
+
+## Server-side usage
+
+```ts
+import { AimearnClient } from "@aimearn/webhook-sdk";
+
+const client = new AimearnClient({
+  keyId: process.env.AIMEARN_KEY_ID!,
+  secret: process.env.AIMEARN_WEBHOOK_SECRET!,
+  endpoint: "https://webhooks.aimearn.platform.com",
+});
+
+const result = await client.orderCompleted({
+  orderId: "ord_12345",
+  data: {
+    items: [
+      { productId: "shopwave-sku-789", quantity: 1, unitPriceCents: 19900 },
+    ],
+    subtotalCents: 19900,
+    currency: "SGD",
+    country: "SG",
+    referralCode: "XX0025",
+    customer: { name: "Jane Doe", email: "jane@example.com" },
+  },
+});
+// → { status: "accepted", orderId: "shopwave#ord_12345", matchedItems: 1 }
+```
+
+Methods: `orderCompleted`, `orderShipped`, `orderRefunded`, `orderCancelled`.
+
+## Browser usage (affiliate-link capture)
+
+```ts
+// On every page load
+import { captureReferralFromUrl } from "@aimearn/webhook-sdk/browser";
+captureReferralFromUrl();
+
+// At checkout
+import { getStoredReferralCode } from "@aimearn/webhook-sdk/browser";
+const referralCode = getStoredReferralCode();   // "XX0025" or null
+```
+
+ESM-only, ~1KB gzipped, no external deps.
+
+## Documentation
+
+Full docs live in the host Next.js app under `/docs/sdk`:
+
+```bash
+npm run dev
+# → http://localhost:3000/docs/sdk
+```
+
+Or browse the source: [`docs/sdk/*.mdx`](https://github.com/aimearn/aim-earn/tree/features/order-pipeline/app/docs/sdk).
+
+## Build
+
+```bash
+# From the monorepo root:
+npm run build:sdk
+
+# Or inside this package:
+npm run build
+```
+
+Produces:
+
+| Path | Use |
+|---|---|
+| `dist/index.js` | Server entry, ESM |
+| `dist/index.cjs` | Server entry, CJS |
+| `dist/index.d.ts` | Server entry types |
+| `dist/browser/index.js` | Browser entry, ESM |
+| `dist/browser/index.d.ts` | Browser entry types |
+
+## Engines
+
+Requires Node.js 20+ (Node 24 LTS preferred). Node 18 is EOL.
+
+## Tests
+
+```bash
+npm test
+```
+
+54 unit tests covering signing, retry, eventId, errors, client, and
+browser cookies (Vitest + jsdom).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/browser/index.d.ts

@@ -0,0 +1,70 @@
+interface SetCookieOptions {
+    /** Number of days until expiry. Default 30. */
+    ttlDays?: number;
+    /** Cookie path. Default "/". */
+    path?: string;
+    /** Domain attribute (e.g. ".acme.com"). Defaults to host-only. */
+    domain?: string;
+    /** Same-site policy. Default "Lax" — covers normal cross-page nav. */
+    sameSite?: "Strict" | "Lax" | "None";
+    /** Secure flag. Default true (assumes HTTPS storefront). */
+    secure?: boolean;
+}
+declare function setCookie(name: string, value: string, options?: SetCookieOptions): void;
+declare function getCookie(name: string): string | null;
+declare function deleteCookie(name: string, options?: Pick<SetCookieOptions, "path" | "domain">): void;
+
+declare const BROWSER_SDK_VERSION = "0.1.0";
+/** Default URL parameter name. Brands can override per-call. */
+declare const DEFAULT_QUERY_PARAM = "aimearn";
+/** Default cookie name. Brands can override per-call. */
+declare const DEFAULT_COOKIE_NAME = "aimearn_referral";
+interface CaptureOptions {
+    /** Query string parameter to read. Default "aimearn". */
+    queryParam?: string;
+    /** Cookie name to write. Default "aimearn_referral". */
+    cookieName?: string;
+    /** Cookie TTL in days. Default 30. */
+    ttlDays?: number;
+    /** Cookie domain (e.g. ".acme.com"). Defaults to host-only. */
+    domain?: string;
+    /**
+     * Override the URL to read from. Defaults to `window.location.href`.
+     * Useful for tests or for processing a deep-linked URL the storefront
+     * received from a campaign.
+     */
+    url?: string;
+    /**
+     * If true, even an empty `?aimearn=` value will overwrite an existing
+     * cookie. Default false (preserves the previously-captured code).
+     */
+    allowEmptyOverwrite?: boolean;
+}
+/**
+ * Reads the `?aimearn=…` query param (or configured equivalent) and
+ * writes it to a first-party cookie. Returns the captured code, or
+ * null if none was present in the URL.
+ *
+ * Idempotent — calling repeatedly is fine; the cookie is just rewritten
+ * with a fresh expiry. Never throws on SSR (no-op when document is
+ * undefined).
+ */
+declare function captureReferralFromUrl(options?: CaptureOptions): string | null;
+/**
+ * Reads the previously-captured referral code from the cookie. Returns
+ * null when no cookie has been set, when the cookie has expired, or in
+ * SSR contexts.
+ */
+declare function getStoredReferralCode(cookieName?: string): string | null;
+/**
+ * Deletes the referral cookie. Typical use: after the brand
+ * successfully POSTed `order.completed` with the referral code on it,
+ * clear the cookie so a future visit without an `?aimearn=` param
+ * doesn't replay an already-attributed sale.
+ */
+declare function clearReferralCode(cookieName?: string, options?: {
+    domain?: string;
+    path?: string;
+}): void;
+
+export { BROWSER_SDK_VERSION, type CaptureOptions, DEFAULT_COOKIE_NAME, DEFAULT_QUERY_PARAM, captureReferralFromUrl, clearReferralCode, deleteCookie, getCookie, getStoredReferralCode, setCookie };

package/dist/browser/index.js

@@ -0,0 +1,100 @@
+// src/browser/cookies.ts
+var DEFAULTS = {
+  ttlDays: 30,
+  path: "/",
+  sameSite: "Lax",
+  secure: true
+};
+function ssr() {
+  return typeof document === "undefined";
+}
+function setCookie(name, value, options = {}) {
+  if (ssr()) return;
+  const cfg = { ...DEFAULTS, ...options };
+  const expires = new Date(
+    Date.now() + cfg.ttlDays * 24 * 60 * 60 * 1e3
+  ).toUTCString();
+  const parts = [
+    `${encodeURIComponent(name)}=${encodeURIComponent(value)}`,
+    `Expires=${expires}`,
+    `Path=${cfg.path}`,
+    `SameSite=${cfg.sameSite}`
+  ];
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  if (cfg.secure) parts.push("Secure");
+  document.cookie = parts.join("; ");
+}
+function getCookie(name) {
+  if (ssr()) return null;
+  const target = encodeURIComponent(name);
+  const cookies = document.cookie ? document.cookie.split(";") : [];
+  for (const raw of cookies) {
+    const eq = raw.indexOf("=");
+    if (eq < 0) continue;
+    const k = raw.slice(0, eq).trim();
+    if (k !== target) continue;
+    const v = raw.slice(eq + 1).trim();
+    try {
+      return decodeURIComponent(v);
+    } catch {
+      return v;
+    }
+  }
+  return null;
+}
+function deleteCookie(name, options = {}) {
+  if (ssr()) return;
+  const parts = [
+    `${encodeURIComponent(name)}=`,
+    `Expires=Thu, 01 Jan 1970 00:00:00 GMT`,
+    `Path=${options.path ?? "/"}`
+  ];
+  if (options.domain) parts.push(`Domain=${options.domain}`);
+  document.cookie = parts.join("; ");
+}
+
+// src/browser/index.ts
+var BROWSER_SDK_VERSION = "0.1.0";
+var DEFAULT_QUERY_PARAM = "aimearn";
+var DEFAULT_COOKIE_NAME = "aimearn_referral";
+function captureReferralFromUrl(options = {}) {
+  const queryParam = options.queryParam ?? DEFAULT_QUERY_PARAM;
+  const cookieName = options.cookieName ?? DEFAULT_COOKIE_NAME;
+  if (typeof window === "undefined") return null;
+  const href = options.url ?? window.location.href;
+  let url;
+  try {
+    url = new URL(href);
+  } catch {
+    return null;
+  }
+  const value = url.searchParams.get(queryParam);
+  if (value === null) return null;
+  const trimmed = value.trim();
+  if (trimmed === "" && !options.allowEmptyOverwrite) {
+    return null;
+  }
+  setCookie(cookieName, trimmed, {
+    ttlDays: options.ttlDays,
+    domain: options.domain
+  });
+  return trimmed;
+}
+function getStoredReferralCode(cookieName = DEFAULT_COOKIE_NAME) {
+  return getCookie(cookieName);
+}
+function clearReferralCode(cookieName = DEFAULT_COOKIE_NAME, options = {}) {
+  deleteCookie(cookieName, options);
+}
+export {
+  BROWSER_SDK_VERSION,
+  DEFAULT_COOKIE_NAME,
+  DEFAULT_QUERY_PARAM,
+  captureReferralFromUrl,
+  clearReferralCode,
+  deleteCookie,
+  getCookie,
+  getStoredReferralCode,
+  setCookie
+};
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/browser/cookies.ts","../../src/browser/index.ts"],"sourcesContent":["// Tiny first-party cookie helpers, browser-only. No external deps so\n// the bundle stays small (target <2KB gzipped).\n\nexport interface SetCookieOptions {\n  /** Number of days until expiry. Default 30. */\n  ttlDays?: number;\n  /** Cookie path. Default \"/\". */\n  path?: string;\n  /** Domain attribute (e.g. \".acme.com\"). Defaults to host-only. */\n  domain?: string;\n  /** Same-site policy. Default \"Lax\" — covers normal cross-page nav. */\n  sameSite?: \"Strict\" | \"Lax\" | \"None\";\n  /** Secure flag. Default true (assumes HTTPS storefront). */\n  secure?: boolean;\n}\n\nconst DEFAULTS: Required<Omit<SetCookieOptions, \"domain\">> = {\n  ttlDays: 30,\n  path: \"/\",\n  sameSite: \"Lax\",\n  secure: true,\n};\n\nfunction ssr(): boolean {\n  return typeof document === \"undefined\";\n}\n\nexport function setCookie(\n  name: string,\n  value: string,\n  options: SetCookieOptions = {},\n): void {\n  if (ssr()) return;\n  const cfg = { ...DEFAULTS, ...options };\n  const expires = new Date(\n    Date.now() + cfg.ttlDays * 24 * 60 * 60 * 1000,\n  ).toUTCString();\n  const parts = [\n    `${encodeURIComponent(name)}=${encodeURIComponent(value)}`,\n    `Expires=${expires}`,\n    `Path=${cfg.path}`,\n    `SameSite=${cfg.sameSite}`,\n  ];\n  if (options.domain) parts.push(`Domain=${options.domain}`);\n  if (cfg.secure) parts.push(\"Secure\");\n  document.cookie = parts.join(\"; \");\n}\n\nexport function getCookie(name: string): string | null {\n  if (ssr()) return null;\n  const target = encodeURIComponent(name);\n  const cookies = document.cookie ? document.cookie.split(\";\") : [];\n  for (const raw of cookies) {\n    const eq = raw.indexOf(\"=\");\n    if (eq < 0) continue;\n    const k = raw.slice(0, eq).trim();\n    if (k !== target) continue;\n    const v = raw.slice(eq + 1).trim();\n    try {\n      return decodeURIComponent(v);\n    } catch {\n      return v;\n    }\n  }\n  return null;\n}\n\nexport function deleteCookie(\n  name: string,\n  options: Pick<SetCookieOptions, \"path\" | \"domain\"> = {},\n): void {\n  if (ssr()) return;\n  const parts = [\n    `${encodeURIComponent(name)}=`,\n    `Expires=Thu, 01 Jan 1970 00:00:00 GMT`,\n    `Path=${options.path ?? \"/\"}`,\n  ];\n  if (options.domain) parts.push(`Domain=${options.domain}`);\n  document.cookie = parts.join(\"; \");\n}\n","// Browser entry — affiliate-link capture flow.\n//\n// Brand storefronts read the `?aimearn=<inviteCode>` query param when\n// a buyer lands from an affiliate's share link, persist it in a\n// first-party cookie (default 30 days), then echo it back as\n// `data.referralCode` on the `order.completed` webhook so commission\n// attribution works.\n//\n// Spec: docs/superpowers/specs/2026-04-29-webhook-ingest-design.md §6.2.\n\nimport { deleteCookie, getCookie, setCookie } from \"./cookies\";\n\nexport const BROWSER_SDK_VERSION = \"0.1.0\";\n\n/** Default URL parameter name. Brands can override per-call. */\nexport const DEFAULT_QUERY_PARAM = \"aimearn\";\n\n/** Default cookie name. Brands can override per-call. */\nexport const DEFAULT_COOKIE_NAME = \"aimearn_referral\";\n\nexport interface CaptureOptions {\n  /** Query string parameter to read. Default \"aimearn\". */\n  queryParam?: string;\n  /** Cookie name to write. Default \"aimearn_referral\". */\n  cookieName?: string;\n  /** Cookie TTL in days. Default 30. */\n  ttlDays?: number;\n  /** Cookie domain (e.g. \".acme.com\"). Defaults to host-only. */\n  domain?: string;\n  /**\n   * Override the URL to read from. Defaults to `window.location.href`.\n   * Useful for tests or for processing a deep-linked URL the storefront\n   * received from a campaign.\n   */\n  url?: string;\n  /**\n   * If true, even an empty `?aimearn=` value will overwrite an existing\n   * cookie. Default false (preserves the previously-captured code).\n   */\n  allowEmptyOverwrite?: boolean;\n}\n\n/**\n * Reads the `?aimearn=…` query param (or configured equivalent) and\n * writes it to a first-party cookie. Returns the captured code, or\n * null if none was present in the URL.\n *\n * Idempotent — calling repeatedly is fine; the cookie is just rewritten\n * with a fresh expiry. Never throws on SSR (no-op when document is\n * undefined).\n */\nexport function captureReferralFromUrl(\n  options: CaptureOptions = {},\n): string | null {\n  const queryParam = options.queryParam ?? DEFAULT_QUERY_PARAM;\n  const cookieName = options.cookieName ?? DEFAULT_COOKIE_NAME;\n\n  // SSR guard — return null silently.\n  if (typeof window === \"undefined\") return null;\n\n  const href = options.url ?? window.location.href;\n  let url: URL;\n  try {\n    url = new URL(href);\n  } catch {\n    return null;\n  }\n\n  const value = url.searchParams.get(queryParam);\n  if (value === null) return null;\n\n  // Treat whitespace-only as empty.\n  const trimmed = value.trim();\n  if (trimmed === \"\" && !options.allowEmptyOverwrite) {\n    return null;\n  }\n\n  setCookie(cookieName, trimmed, {\n    ttlDays: options.ttlDays,\n    domain: options.domain,\n  });\n  return trimmed;\n}\n\n/**\n * Reads the previously-captured referral code from the cookie. Returns\n * null when no cookie has been set, when the cookie has expired, or in\n * SSR contexts.\n */\nexport function getStoredReferralCode(\n  cookieName: string = DEFAULT_COOKIE_NAME,\n): string | null {\n  return getCookie(cookieName);\n}\n\n/**\n * Deletes the referral cookie. Typical use: after the brand\n * successfully POSTed `order.completed` with the referral code on it,\n * clear the cookie so a future visit without an `?aimearn=` param\n * doesn't replay an already-attributed sale.\n */\nexport function clearReferralCode(\n  cookieName: string = DEFAULT_COOKIE_NAME,\n  options: { domain?: string; path?: string } = {},\n): void {\n  deleteCookie(cookieName, options);\n}\n\n// Re-export cookie primitives in case brands need them for adjacent\n// flows (e.g. tracking a checkout step). No backward-compat promise on\n// these — the public API is the three functions above.\nexport { setCookie, getCookie, deleteCookie } from \"./cookies\";\n"],"mappings":";AAgBA,IAAM,WAAuD;AAAA,EAC3D,SAAS;AAAA,EACT,MAAM;AAAA,EACN,UAAU;AAAA,EACV,QAAQ;AACV;AAEA,SAAS,MAAe;AACtB,SAAO,OAAO,aAAa;AAC7B;AAEO,SAAS,UACd,MACA,OACA,UAA4B,CAAC,GACvB;AACN,MAAI,IAAI,EAAG;AACX,QAAM,MAAM,EAAE,GAAG,UAAU,GAAG,QAAQ;AACtC,QAAM,UAAU,IAAI;AAAA,IAClB,KAAK,IAAI,IAAI,IAAI,UAAU,KAAK,KAAK,KAAK;AAAA,EAC5C,EAAE,YAAY;AACd,QAAM,QAAQ;AAAA,IACZ,GAAG,mBAAmB,IAAI,CAAC,IAAI,mBAAmB,KAAK,CAAC;AAAA,IACxD,WAAW,OAAO;AAAA,IAClB,QAAQ,IAAI,IAAI;AAAA,IAChB,YAAY,IAAI,QAAQ;AAAA,EAC1B;AACA,MAAI,QAAQ,OAAQ,OAAM,KAAK,UAAU,QAAQ,MAAM,EAAE;AACzD,MAAI,IAAI,OAAQ,OAAM,KAAK,QAAQ;AACnC,WAAS,SAAS,MAAM,KAAK,IAAI;AACnC;AAEO,SAAS,UAAU,MAA6B;AACrD,MAAI,IAAI,EAAG,QAAO;AAClB,QAAM,SAAS,mBAAmB,IAAI;AACtC,QAAM,UAAU,SAAS,SAAS,SAAS,OAAO,MAAM,GAAG,IAAI,CAAC;AAChE,aAAW,OAAO,SAAS;AACzB,UAAM,KAAK,IAAI,QAAQ,GAAG;AAC1B,QAAI,KAAK,EAAG;AACZ,UAAM,IAAI,IAAI,MAAM,GAAG,EAAE,EAAE,KAAK;AAChC,QAAI,MAAM,OAAQ;AAClB,UAAM,IAAI,IAAI,MAAM,KAAK,CAAC,EAAE,KAAK;AACjC,QAAI;AACF,aAAO,mBAAmB,CAAC;AAAA,IAC7B,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEO,SAAS,aACd,MACA,UAAqD,CAAC,GAChD;AACN,MAAI,IAAI,EAAG;AACX,QAAM,QAAQ;AAAA,IACZ,GAAG,mBAAmB,IAAI,CAAC;AAAA,IAC3B;AAAA,IACA,QAAQ,QAAQ,QAAQ,GAAG;AAAA,EAC7B;AACA,MAAI,QAAQ,OAAQ,OAAM,KAAK,UAAU,QAAQ,MAAM,EAAE;AACzD,WAAS,SAAS,MAAM,KAAK,IAAI;AACnC;;;ACnEO,IAAM,sBAAsB;AAG5B,IAAM,sBAAsB;AAG5B,IAAM,sBAAsB;AAiC5B,SAAS,uBACd,UAA0B,CAAC,GACZ;AACf,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,aAAa,QAAQ,cAAc;AAGzC,MAAI,OAAO,WAAW,YAAa,QAAO;AAE1C,QAAM,OAAO,QAAQ,OAAO,OAAO,SAAS;AAC5C,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,IAAI;AAAA,EACpB,QAAQ;AACN,WAAO;AAAA,EACT;AAEA,QAAM,QAAQ,IAAI,aAAa,IAAI,UAAU;AAC7C,MAAI,UAAU,KAAM,QAAO;AAG3B,QAAM,UAAU,MAAM,KAAK;AAC3B,MAAI,YAAY,MAAM,CAAC,QAAQ,qBAAqB;AAClD,WAAO;AAAA,EACT;AAEA,YAAU,YAAY,SAAS;AAAA,IAC7B,SAAS,QAAQ;AAAA,IACjB,QAAQ,QAAQ;AAAA,EAClB,CAAC;AACD,SAAO;AACT;AAOO,SAAS,sBACd,aAAqB,qBACN;AACf,SAAO,UAAU,UAAU;AAC7B;AAQO,SAAS,kBACd,aAAqB,qBACrB,UAA8C,CAAC,GACzC;AACN,eAAa,YAAY,OAAO;AAClC;","names":[]}

package/dist/index.cjs

@@ -0,0 +1,338 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  AimearnAuthError: () => AimearnAuthError,
+  AimearnClient: () => AimearnClient,
+  AimearnConflictError: () => AimearnConflictError,
+  AimearnError: () => AimearnError,
+  AimearnForbiddenError: () => AimearnForbiddenError,
+  AimearnNotFoundError: () => AimearnNotFoundError,
+  AimearnPlatformError: () => AimearnPlatformError,
+  AimearnValidationError: () => AimearnValidationError,
+  REPLAY_WINDOW_SECONDS: () => REPLAY_WINDOW_SECONDS,
+  SDK_VERSION: () => SDK_VERSION,
+  backoffDelayMs: () => backoffDelayMs,
+  errorFromResponse: () => errorFromResponse,
+  generateEventId: () => generateEventId,
+  isRetriable: () => isRetriable,
+  parseSignatureHeader: () => parseSignatureHeader,
+  resolveRetryConfig: () => resolveRetryConfig,
+  signRequest: () => signRequest,
+  verifyResponseSignature: () => verifyResponseSignature
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/eventId.ts
+var import_node_crypto = require("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 = (0, import_node_crypto.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
+var import_node_crypto2 = require("crypto");
+var REPLAY_WINDOW_SECONDS = 300;
+function signRequest(secret, rawBody, now = Math.floor(Date.now() / 1e3)) {
+  const v1 = (0, import_node_crypto2.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 = (0, import_node_crypto2.createHmac)("sha256", secret).update(`${sig.t}.${responseBody}`).digest("hex");
+  if (expected.length !== sig.v1.length) return false;
+  return (0, import_node_crypto2.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";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AimearnAuthError,
+  AimearnClient,
+  AimearnConflictError,
+  AimearnError,
+  AimearnForbiddenError,
+  AimearnNotFoundError,
+  AimearnPlatformError,
+  AimearnValidationError,
+  REPLAY_WINDOW_SECONDS,
+  SDK_VERSION,
+  backoffDelayMs,
+  errorFromResponse,
+  generateEventId,
+  isRetriable,
+  parseSignatureHeader,
+  resolveRetryConfig,
+  signRequest,
+  verifyResponseSignature
+});
+//# sourceMappingURL=index.cjs.map