@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

npm install @aimearn/webhook-sdk

(or via the workspace symlink in this monorepo).

Server-side usage

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: "[email protected]" },
  },
});
// → { status: "accepted", orderId: "shopwave#ord_12345", matchedItems: 1 }

Methods: orderCompleted, orderShipped, orderRefunded, orderCancelled.

Browser usage (affiliate-link capture)

// 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:

npm run dev
# → http://localhost:3000/docs/sdk

Or browse the source: docs/sdk/*.mdx.

Build

# 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

npm test

54 unit tests covering signing, retry, eventId, errors, client, and browser cookies (Vitest + jsdom).

License

MIT — see LICENSE.