waterline-sdk

TypeScript ingestion SDK for Waterline — connect your AI spend to your revenue, customer by customer.

The SDK is asynchronous and fire-and-forget: it never blocks your app and never throws. If Waterline is unreachable, your product keeps running. It reports metadata only — never prompts or responses.

Install

npm install waterline-sdk

ESM-only, Node 18+. Using an AI coding agent to integrate this? Point it at AGENTS.md — it has the exact wiring, rules, and pitfalls.

Usage

import { init, track, identify, withCustomer, shutdown } from "waterline-sdk";

// Once, at startup.
init({
  endpoint: "https://ingest.waterline.dev",
  apiKey: process.env.WATERLINE_API_KEY,
  env: "prod",
});

// Attribute events to a customer via context propagation — no threaded parameter.
// A middleware typically wraps each request in withCustomer(...).
withCustomer("cus_acme", () => {
  // Tell Waterline who this customer is, so the dashboard shows a real name and
  // unit economics instead of an opaque id. Metadata only — call it again on change.
  // Passing email and/or stripeCustomerId lets Waterline join cost to revenue
  // automatically — no manual reconciliation. See "Linking to Stripe" below.
  identify({
    name: "Acme Corp",
    seats: 25,
    model: "Pro",
    email: "[email protected]",
    stripeCustomerId: "cus_123", // if your app already created the Stripe customer
  });

  track({
    kind: "llm",
    model: "gpt-4o",
    runId: "run_123",
    success: true,
    usage: { inputTokens: 1200, outputTokens: 340 },
  });
});

// You can also attribute a single call explicitly, without the context.
identify({ name: "Beta LLC", seats: 3 }, "cus_beta");
track({ kind: "embedding", model: "text-embedding-3-small", customerId: "cus_beta" });

// On graceful shutdown, flush what's left.
await shutdown();

API

• init(config) — create the client and start the background flush loop.
• track(event) — enqueue an event. Never throws, never blocks.
• identify(traits, customerId?) — attach name / seats / model to a customer. Never throws, never blocks.
• withCustomer(customerId, fn) — run fn within an ambient customer context.
• flush() — send all queued events now. Never rejects.
• shutdown() — stop the timer and flush. Safe to call when not initialized.

Cost is computed server-side from the reported usage — the SDK never sends cost.

Linking to Stripe (no manual reconciliation)

Waterline joins each customer's AI cost to their Stripe revenue. You link them once, in code — never by hand, and never per end-user. Best to worst:

1. identify({ stripeCustomerId }) — when your app created the Stripe customer and has its id. Exact, instant, scales to millions. The Stripe id belongs here and only here — never on a track event.
2. identify({ email }) — Waterline auto-matches to the Stripe customer with the same email. Great when you don't hold the Stripe id.
3. Stripe metadata — stamp your internal id on the Stripe customer (metadata.waterline_id = <your customer id>); Waterline finds it automatically.

Anything left unmatched shows up in the dashboard's reconciliation screen for a one-off manual link. Matching is only ever done on a unique correspondence — an ambiguous email is left for you to resolve, never guessed.

Event kinds

llm · embedding · vectordb · sandbox · search · stt · tts · image