TypeScript SDK.

One package, one function, three optional fields. The SDK handles auth, retries on transient errors, and batching — you call ingest and walk away.

Install

One dep, one env var.

$ pnpm add @ingestlayer/sdk
# or: npm install @ingestlayer/sdk · yarn add @ingestlayer/sdk

# .env
INGESTLAYER_KEY=il_live_***

Works in Node 18+, Bun, Deno, and modern browsers. Reads INGESTLAYER_KEY from the environment by default; pass configure({ apiKey }) if you need to override.

ingest()

The one call.

import { ingest } from "@ingestlayer/sdk";

await ingest("user.signup", {
  email:  user.email,
  plan:   user.intendedPlan,
  source: "marketing-site",
});

Signature: ingest(type: string, payload: object, options?: { idempotencyKey?, timestamp? }). Returns when the proxy 202s — at that point the event is durable. Throws on 4xx or persistent 5xx.

await ingest(
  "order.placed",
  { order_id: o.id, amount: o.amount, currency: o.currency },
  {
    idempotencyKey: o.id,            // dedupe at the gate
    timestamp:      o.created_at,    // backdate to when it happened
  },
);

idempotencyKey dedupes at the gate over the configured window — usually 24h. timestamp overrides the received_at; defaults to now().

Batch

Bundle when you can.

import { ingestBatch } from "@ingestlayer/sdk";

await ingestBatch([
  { type: "user.signup", payload: { email: a.email } },
  { type: "user.signup", payload: { email: b.email } },
  { type: "user.signup", payload: { email: c.email } },
]);
// one HTTP round trip; up to 500 events per batch

One HTTP round trip per batch. Useful in cron jobs, imports, or anywhere you accumulate events before sending. Per-event idempotency keys still work — pass idempotencyKey on each entry.

Errors

What the SDK throws.

import { ingest, IngestError } from "@ingestlayer/sdk";

try {
  await ingest("user.signup", { email });
} catch (err) {
  if (err instanceof IngestError && err.status === 429) {
    // rate-limited; the SDK already retried once. wait and try again.
  } else {
    throw err;
  }
}

IngestError carries the HTTP status and the proxy's error body. The SDK retries once on 5xx with a short backoff; persistent failures throw. 401 / 403 / 413 throw immediately — they aren't going to fix themselves.

Browser

The same call, with caveats.

The SDK works in browsers, but you probably don't want your INGESTLAYER_KEY in client bundles. Use a thin server proxy that forwards authenticated calls, or scope keys narrowly per-environment and accept the visibility tradeoff.