@yougrowai/node 0.1.0 → 0.3.0

package/README.md

@@ -1,21 +1,36 @@
 # @yougrowai/node
 
-Connect your product to YouGrow lifecycle journeys. Your server sends YouGrow
-what your users do (sign-ups, onboarding steps). YouGrow then asks your server
-for fresh context just before it emails someone.
+Keep your users' state in YouGrow lifecycle journeys, and verify the requests
+YouGrow sends you. Your server tells YouGrow who each user is and how far
+they've got: sign-up, onboarding steps, facts, opt-outs. YouGrow decides which
+journeys they're in, and what to send them when.
+
+**Full documentation: https://yougrow.ai/developers.** The published package and
+https://yougrow.ai/developers are the contract. The source on GitHub isn't: its
+main branch can be ahead of what's been released.
+
+> **2026-09-25:** API v1 (`POST /api/v1/events`, HMAC signing) was removed.
+> 0.3.0 is the client for API v2; 0.1.x only spoke v1, so upgrade to keep
+> sending. See [Upgrading from 0.1.x](#upgrading-from-01x).
 
 ```sh
 npm install @yougrowai/node
 ```
 
-Node 18 or later, no dependencies. Server-side only: your secret must never
-reach a browser or app bundle.
+Node 18 or later, no dependencies. It works with `import` (ESM) and `require`
+(CommonJS), e.g. in Cloud Functions compiled to CommonJS:
+
+```js
+const { YouGrow } = require("@yougrowai/node");
+const { createVerifier, contextResponse } = require("@yougrowai/node/server");
+```
 
-> Status: 0.x. The wire protocol is stable; the SDK's API may still change
-> before 1.0. The same signing works from any language; see "Without the SDK"
-> below.
+Server-side only: your secret must never reach a browser or app bundle.
 
-## Send events
+> Status: 0.x. The HTTP API is versioned (`/api/v2`); the SDK's own API may
+> still change before 1.0.
+
+## Quick start
 
 ```ts
 import { YouGrow } from "@yougrowai/node";
@@ -23,45 +38,209 @@ import { YouGrow } from "@yougrowai/node";
 const yg = new YouGrow({
   keyId: process.env.YOUGROW_KEY_ID!,   // from Products → your connection
   secret: process.env.YOUGROW_SECRET!,  // shown once; keep it server-side
+  origin: process.env.YOUGROW_ORIGIN,   // optional; defaults to https://yougrow.ai
+});
+
+// At sign-up: who they are, and the basis for emailing them
+await yg.users.update(user.id, {
+  email: user.email,
+  firstName: user.firstName,
+  timezone: user.timezone,               // IANA, e.g. "Europe/London"
+  signedUpAt: user.createdAt.toISOString(),
+  consent: "soft_opt_in",                // consent | soft_opt_in | corporate_subscriber | none
 });
 
-// On sign-up
-yg.identify({
-  userId: user.id,
-  traits: { email: user.email, firstName: user.firstName, timezone: "Europe/London", plan: "free" },
-  consent: { basis: "soft_opt_in" }, // consent | soft_opt_in | corporate_subscriber | none
+// As they get going: onboarding steps, facts and traits, in the same kind of update
+await yg.users.update(user.id, {
+  steps: { create_brand: new Date().toISOString() },
+  facts: { competitors_tracked: 3 },
+  traits: { plan: "pro" },
 });
-yg.track({ userId: user.id, event: "user.signed_up" });
 
-// As onboarding progresses
-yg.stepCompleted(user.id, "create_brand");
+// They turned lifecycle email off in your product's settings
+await yg.users.update(user.id, { subscribed: false });
 
-await yg.flush(); // or let it flush automatically (every 20 messages / 5 s)
+// Staff, test accounts, invited teammates: never email them
+await yg.users.update(user.id, { excluded: { reason: "staff" } });
+
+// They deleted their account: erase them from YouGrow too
+await yg.users.delete(user.id);
 ```
 
-Messages are batched (at most 100 per request) and retried with backoff on
-network errors, 429 and 5xx. Every message has a `messageId`, so a retry is
-never double-counted.
+Each call resolves once YouGrow has answered; nothing is sent in the
+background. For `userId`, use your own stable user id, not an email address
+(which can change).
 
-### Reserved events
+### A scheduled sync
 
-| Event | Meaning |
-|---|---|
-| `user.signed_up` | Starts sign-up journeys |
-| `onboarding.step_completed` | `properties.step` is the step id from your catalog |
-| `onboarding.completed` | Every onboarding step is done |
-| `email_preferences.updated` | `properties.category` + `properties.subscribed` |
-| `user.deleted` | Erase this user and their history |
+`users.batch` takes any number of users. It sends them 100 per request, one
+request after another, and returns one result for the lot:
+
+```ts
+const result = await yg.users.batch(
+  accounts.map((a) => ({
+    userId: a.id,
+    steps: { create_brand: a.brandCreatedAt?.toISOString() ?? null },
+    facts: { competitors_tracked: a.competitorCount },
+    updatedAt: a.updatedAt.toISOString(),
+  })),
+);
+// { applied: 248, ignored: 1, failed: 1,
+//   results: [{ index: 17, userId: "u_42", status: "failed", reason: "invalid", fields: [{ path, message }] }, …] }
+```
+
+One bad item never fails the rest. `results` lists only the ignored and failed
+items; `index` is the item's position in the array you passed. If any item
+fails, one `console.warn` line says how many, with the first few user ids and
+reasons (never the data you sent). Pass `{ quiet: true }` to skip that line, or
+`{ throwOnItemError: true }` to get a `YouGrowBatchError` instead, carrying the
+result as `err.result`, once every item has been sent.
+
+If a request fails outright (a 401, say, or a 5xx that outlasts the retries),
+`users.batch` rejects there. The requests before it were applied, and sending
+the whole batch again is harmless. Requests are also kept under the API's
+512 KB body limit; an item too big for any request fails as `body_too_large`.
+
+### Events (optional)
+
+Journeys run on state, so events are optional. Use them for milestones worth
+branching on:
+
+```ts
+await yg.events.track(user.id, "report.exported", {
+  properties: { format: "pdf" },                  // optional, up to 4 KB
+  occurredAt: new Date().toISOString(),           // optional
+  idempotencyKey: `report.exported:${report.id}`, // optional: the same key is recorded once
+});
+// { recorded: true, duplicate: false }
+```
+
+Event names are lower-case and dotted. The user must exist first: an event for
+a user YouGrow hasn't seen rejects with a 404 (`not_found`). Without an
+`idempotencyKey`, the SDK sends a random one per call, so its own retries never
+record an event twice. A key that was already recorded resolves
+`{ recorded: false, duplicate: true }`. The v1 lifecycle events (`user.signed_up`,
+`onboarding.step_completed`, …) are state now, and sending one is refused
+(400); see [Upgrading from 0.1.x](#upgrading-from-01x).
+
+## How an update merges
+
+`users.update` sends the user's state as a JSON Merge Patch (RFC 7396):
+
+- Fields you send replace YouGrow's; fields you leave out stay as they are.
+- `null` clears a field: `{ lastName: null }`.
+- `steps`, `facts` and `traits` merge key by key. `{ steps: { invite_team: "…" } }`
+  adds that step and keeps the others; `{ traits: { plan: null } }` removes
+  just `plan`.
+- A step's value is when it was done (`null`: not done). Timestamps are ISO 8601
+  with a zone (`Z` or `+01:00`), e.g. from `toISOString()`.
+- `email`, `firstName`, `lastName`, `timezone` and `locale` are fields of their
+  own, never traits. Unknown fields are refused (400), so a typo can't be
+  silently dropped.
+- Up to 50 steps, 50 facts and 50 traits per user. Step ids are lower-case
+  letters, digits, `_` and `-`; trait keys start with a letter.
+
+A user YouGrow hasn't seen is created by their first update.
+`users.get(userId)` returns the state as YouGrow holds it, plus what YouGrow
+decided: journey `enrolments`, and `optOuts` (unsubscribes made in YouGrow's
+emails, which hold until the person lifts them; the API can't). It returns
+`null` for a user YouGrow doesn't know.
+
+## Stale writes
+
+Set `updatedAt` to when you read the state you're sending. YouGrow ignores a
+write older than the newest one it applied, so a slow retry or an out-of-order
+job can't overwrite fresher state:
+
+```ts
+const r = await yg.users.update(user.id, { traits: { plan: user.plan }, updatedAt: user.updatedAt.toISOString() });
+if (!r.applied) console.info(r.reason); // "stale_write" (with storedUpdatedAt) or "deleted_later"
+```
+
+An ignored write isn't an error: the call resolves with `applied: false` (in a
+batch, the item is `ignored`). Writes without `updatedAt` always apply.
+
+`users.delete` erases the user and their history. It always succeeds, even for
+a user YouGrow never saw, so it's safe to repeat. A later write whose
+`updatedAt` is from before the deletion is ignored (`deleted_later`); any other
+write starts a fresh person, so stop sending a user once you've deleted them.
 
-Other event names (lower-case, dotted, e.g. `report.exported`) are recorded as
-milestones.
+## Errors, retries and timeouts
 
-## Answer context requests
+Every method returns a promise; await it.
 
-Before an email, YouGrow sends your context endpoint a `POST` about one user.
-It carries `Authorization: Bearer <JWT>`, signed with **YouGrow's** private key.
-You verify it against YouGrow's published public keys. Your secret isn't
-involved, so nothing you store can be used to forge a request from YouGrow.
+- A request that takes more than 10 s is abandoned. Timeouts, network errors,
+  429 and 5xx are retried (3 times by default) with jittered backoff, waiting
+  at most 5 s between tries; a 429's `Retry-After` is honoured up to that cap.
+  Retries are safe: updates and deletes are idempotent, and events carry an
+  idempotency key.
+- Any other error status rejects straight away with a `YouGrowError`: `status`,
+  `code` (the API's `error`, e.g. `invalid`, `unauthorized`, `body_too_large`),
+  `fields` for a 400, and a message such as
+  `YouGrow API 400 invalid: traits.plan: …`. A 429 or 5xx that outlasts the
+  retries rejects the same way; a network error or timeout rejects with that
+  error.
+- A user id the API can't take (empty, over 256 characters, `"batch"`, `"."`
+  or `".."`) rejects with a `TypeError` before anything is sent.
+
+```ts
+import { YouGrowError } from "@yougrowai/node";
+
+try {
+  await yg.users.update(user.id, patch);
+} catch (err) {
+  if (err instanceof YouGrowError && err.status === 400) console.error(err.message, err.fields); // [{ path, message }]
+  throw err;
+}
+```
+
+| Option | Default | |
+|---|---|---|
+| `origin` | `https://yougrow.ai` | YouGrow's origin. Set it (e.g. from `YOUGROW_ORIGIN`) when you're connected to another YouGrow instance, such as staging or a self-hosted one. |
+| `timeoutMs` | `10000` | Abandon a request after this long; it's retried like a network error. |
+| `maxRetries` | `3` | Retries per request for network errors, timeouts, 429 and 5xx. |
+| `maxRetryWaitMs` | `5000` | The longest wait between retries. `Retry-After` is honoured up to this. |
+| `fetch` | global `fetch` | A custom fetch (tests, proxies). |
+
+A request that keeps failing takes at most `(maxRetries + 1) × timeoutMs`, plus
+the waits between retries. For a function with a short time limit, lower
+`timeoutMs` or `maxRetries`. If a large sync is rate-limited (429), raise
+`maxRetryWaitMs` (e.g. to `60000`) so its retries wait for the limit to reset.
+
+## Serverless
+
+Every call is awaited: nothing is queued, nothing is sent in the background,
+and there's nothing to flush or close. Once the promise resolves, YouGrow has
+the update, so your function can return straight after:
+
+```ts
+const yg = new YouGrow({ keyId: process.env.YOUGROW_KEY_ID!, secret: process.env.YOUGROW_SECRET! }); // once, outside the handler
+
+export const onSignup = functions.auth.user().onCreate(async (user) => {
+  await yg.users.update(user.uid, {
+    email: user.email ?? null,
+    signedUpAt: new Date(user.metadata.creationTime).toISOString(),
+  });
+});
+```
+
+## Runtimes
+
+Node 18 or later, as ESM or CommonJS. Edge runtimes (Vercel Edge Functions,
+Next.js edge routes and middleware, Cloudflare Workers) aren't supported yet,
+because the SDK uses `node:crypto`. Use a Node runtime route or function.
+
+## Verify YouGrow's requests
+
+YouGrow calls your server too: your context endpoint, just before it emails
+someone, and your webhook endpoint. Every such request carries
+`Authorization: Bearer <JWT>`, signed with **YouGrow's** private key. You
+verify it against YouGrow's published public keys. Your secret isn't involved,
+so nothing you store can be used to forge a request from YouGrow.
+
+### Answer context requests
+
+Before an email, YouGrow sends your context endpoint a `POST` about one user:
 
 ```ts
 import { createVerifier, contextResponse } from "@yougrowai/node/server";
@@ -69,15 +248,15 @@ import { createVerifier, contextResponse } from "@yougrowai/node/server";
 // Once, at startup. keyId is the token's audience: tokens for other connections fail.
 const verifier = createVerifier({
   keyId: process.env.YOUGROW_KEY_ID!,
-  // issuer: "https://<dev origin>"  // staging only; defaults to https://yougrow.ai
+  origin: process.env.YOUGROW_ORIGIN, // optional; the same value as the client's
 });
 
 app.post("/yougrow/context", express.raw({ type: "application/json" }), async (req, res) => {
-  const rawBody = req.body.toString("utf8");
-  const v = await verifier.verify({ headers: req.headers, rawBody, direction: "context" });
+  // Verify the RAW body (here a Buffer) before parsing it.
+  const v = await verifier.verify({ headers: req.headers, rawBody: req.body, direction: "context" });
   if (!v.ok) return res.status(401).end();
 
-  const { userId } = JSON.parse(rawBody);
+  const { userId } = JSON.parse(req.body.toString("utf8"));
   const u = await loadOnboardingState(userId);
   res.type("json").send(
     contextResponse({
@@ -91,15 +270,20 @@ app.post("/yougrow/context", express.raw({ type: "application/json" }), async (r
 });
 ```
 
-The verifier fetches `https://yougrow.ai/.well-known/jwks.json` once. It caches
-the keys for as long as their `Cache-Control` allows, and refetches early when
-a token names a key it hasn't seen. That means YouGrow can rotate its keys
-without any change on your side.
+`verify` takes the body exactly as received, as a string or a Buffer (e.g.
+`req.rawBody` in Firebase Cloud Functions), never re-serialised JSON. Plain
+header objects match in any case (e.g. API Gateway's `event.headers`). How to
+read the raw body in each framework: https://yougrow.ai/developers/security.
+
+The verifier fetches `<origin>/.well-known/jwks.json` once. It caches the keys
+for as long as their `Cache-Control` allows, and refetches early when a token
+names a key it hasn't seen. That means YouGrow can rotate its keys without any
+change on your side.
 
 Numbers about the user appear only in your facts and insight sentences. YouGrow
 never invents them.
 
-## Webhooks
+### Webhooks
 
 YouGrow tells your webhook endpoint about preference changes, e.g. an
 unsubscribe from onboarding tips. Verify it with
@@ -108,29 +292,50 @@ token, `id` in the body) are unique, so you can drop duplicates.
 
 ## Without the SDK
 
-**Events you send** are signed with your secret, over the exact request body:
+**The API** is HTTPS and JSON, with HTTP Basic auth: your key id as the
+username, your secret as the password.
 
-```
-X-YouGrow-Key-Id:    <key id>
-X-YouGrow-Timestamp: <unix seconds>
-X-YouGrow-Signature: v1=<hex HMAC-SHA256(secret, "events:<timestamp>.<raw body>")>
+```sh
+curl -X PATCH "https://yougrow.ai/api/v2/users/u_123" \
+  -u "$YOUGROW_KEY_ID:$YOUGROW_SECRET" \
+  -H "content-type: application/json" \
+  -d '{"email":"alex@example.com","signedUpAt":"2026-09-25T10:00:00Z","consent":"soft_opt_in"}'
 ```
 
-Requests more than five minutes out are refused.
+`PATCH`, `GET` and `DELETE /api/v2/users/{userId}` (URL-encode the id),
+`POST /api/v2/users/batch` with `{ "users": [{ "userId": "…", …patch }] }`
+(1–100 users), and `POST /api/v2/users/{userId}/events`. The full reference is
+at https://yougrow.ai/developers.
 
 **Requests YouGrow sends you** carry a JWT. Use any JWT library, then check:
 
 1. `alg` is `ES256` (reject anything else, including `none`). Verify the
-   signature with the key from `<issuer>/.well-known/jwks.json` whose `kid`
+   signature with the key from `<origin>/.well-known/jwks.json` whose `kid`
    matches. Cache that file per its `Cache-Control`.
-2. `iss` is `https://yougrow.ai`, and `aud` is your key id.
+2. `iss` is YouGrow's origin (`https://yougrow.ai` unless you're connected to
+   another instance), and `aud` is your key id.
 3. `dir` is `context` or `webhook`, matching the endpoint that received it.
 4. `exp` hasn't passed, allowing about 60 s of clock skew. `exp − iat` is at
    most 300.
 5. `body_sha256` is the base64url SHA-256 of the raw body you received.
 
-`test/vectors.json` (included in this package) holds reference signatures and
-tokens for checking your own implementation.
+`test/vectors.json` (included in this package) holds reference tokens for
+checking your own verifier.
+
+## Upgrading from 0.1.x
+
+| 0.1.x (API v1) | 0.3.0 (API v2) |
+|---|---|
+| `identify({ userId, traits, consent })` | `users.update(userId, { email, firstName, …, consent, traits })`: profile fields are top-level, and `consent` is the basis itself, e.g. `"soft_opt_in"` |
+| `track({ event: "user.signed_up" })` | `signedUpAt` in `users.update` |
+| `stepCompleted(userId, step)`, `onboarding.completed` | `steps: { [step]: doneAt }` in `users.update` |
+| `email_preferences.updated` | `subscribed` in `users.update` |
+| `user.deleted` | `users.delete(userId)` |
+| Any other `track()` | `events.track(userId, event, { properties })` |
+| `flush()`, `close()`, `flushAt`, `flushIntervalMs`, `onError` | Gone with the queue: every method is awaited, and rejects if it fails |
+| `sign`, `HEADERS`, `endpoint` | Gone: requests use HTTP Basic auth, to paths under `origin` |
+
+`@yougrowai/node/server` (`createVerifier`, `contextResponse`) is unchanged.
 
 ## Credentials
 
@@ -138,3 +343,7 @@ Create a connection in YouGrow (**Products → Connect a product**) to get a key
 id and a secret. Store them in your server's environment or secret manager as
 `YOUGROW_KEY_ID` and `YOUGROW_SECRET`. Use a separate connection, with its own
 key and secret, for each environment (e.g. staging and production).
+
+If your connection is on a YouGrow instance other than https://yougrow.ai (e.g.
+a staging or self-hosted one), also set `YOUGROW_ORIGIN` to its origin, and
+pass it as `origin` to both `new YouGrow()` and `createVerifier()`.

package/dist/cjs/index.d.ts

@@ -0,0 +1,189 @@
+/**
+ * @yougrowai/node — keep your users' state in YouGrow lifecycle journeys (API v2).
+ *
+ *   const yg = new YouGrow({ keyId: process.env.YOUGROW_KEY_ID!, secret: process.env.YOUGROW_SECRET! });
+ *   await yg.users.update(user.id, { email: user.email, signedUpAt: user.createdAt.toISOString(), consent: "soft_opt_in" });
+ *
+ * Server-side only: the secret authenticates every request (HTTP Basic). Each
+ * method resolves once its request is done (a batch's, one per 100 users), with
+ * nothing queued or sent in the background, so it's safe in serverless
+ * functions. A request is abandoned after `timeoutMs` and retried with capped,
+ * jittered backoff on network errors, timeouts, 429 and 5xx; any other error
+ * status throws a YouGrowError straight away.
+ */
+export type ConsentBasis = "consent" | "soft_opt_in" | "corporate_subscriber" | "none";
+/**
+ * Any subset of a user's state, as a JSON Merge Patch (RFC 7396): fields sent
+ * replace YouGrow's, fields left out stay, `null` clears, and `steps`, `facts`
+ * and `traits` merge key by key. Timestamps are ISO 8601 with a zone, e.g.
+ * `new Date().toISOString()`.
+ */
+export interface UserPatch {
+    email?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    /** An IANA time zone, e.g. "Europe/London". */
+    timezone?: string | null;
+    /** A BCP 47 locale, e.g. "en-GB". */
+    locale?: string | null;
+    /** When the account was created. Starts sign-up journeys while inside their window. */
+    signedUpAt?: string;
+    /** The legal basis for marketing email. */
+    consent?: ConsentBasis | null;
+    /** false = the person opted out of lifecycle email in your product. */
+    subscribed?: boolean;
+    /** Never email this person, in any journey (staff, test accounts, invited teammates). */
+    excluded?: {
+        reason: string;
+    } | null;
+    /** Onboarding step id → when it was done (null: not done). */
+    steps?: Record<string, string | null>;
+    /** Fact id → its latest value (null removes it). */
+    facts?: Record<string, number | string | boolean | null>;
+    /** Anything else journeys branch on (null removes a key). */
+    traits?: Record<string, string | number | boolean | null>;
+    /** When you read this state. A write older than the stored one is ignored. */
+    updatedAt?: string;
+}
+/** A user's state as YouGrow holds it. */
+export interface UserState {
+    userId: string;
+    email: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    timezone: string | null;
+    locale: string | null;
+    signedUpAt: string | null;
+    consent: ConsentBasis | null;
+    subscribed: boolean;
+    excluded: {
+        reason: string;
+    } | null;
+    steps: Record<string, string>;
+    facts: Record<string, string | number | boolean>;
+    traits: Record<string, string | number | boolean>;
+    updatedAt: string | null;
+}
+/** `users.get` adds what YouGrow decided: journeys and opt-outs. */
+export interface UserView extends UserState {
+    enrolments: Array<{
+        journeyId: string;
+        status: string;
+        mode: string;
+        enrolledAt: string;
+    }>;
+    /** Unsubscribes made in YouGrow's emails. They hold until the person lifts them; the API can't. */
+    optOuts: Array<{
+        scope: "all" | "category";
+        category: string | null;
+        at: string | null;
+    }>;
+}
+/** Why a write was ignored: older than the stored state, or than the user's deletion. */
+export type SkipReason = "stale_write" | "deleted_later";
+export type PatchResponse = {
+    applied: true;
+    user: UserState;
+} | {
+    applied: false;
+    reason: SkipReason;
+    storedUpdatedAt?: string | null;
+    user?: UserState;
+};
+/** What was wrong with one field, e.g. `{ path: "traits.plan", message: "…" }`. */
+export interface FieldError {
+    path: string;
+    message: string;
+}
+/** One user in `users.batch`: their id plus a patch. */
+export interface BatchItem extends UserPatch {
+    userId: string;
+}
+export interface BatchResponse {
+    applied: number;
+    ignored: number;
+    failed: number;
+    /** Only the ignored and failed items; applied ones are counted. `index` is the item's position in your array. */
+    results: Array<{
+        index: number;
+        userId: string | null;
+        status: "ignored" | "failed";
+        reason: string;
+        fields?: FieldError[];
+    }>;
+}
+export interface EventResult {
+    recorded: boolean;
+    duplicate: boolean;
+}
+export interface YouGrowOptions {
+    /** Your connection's key id (`ygk_…`). */
+    keyId: string;
+    /** Its secret (`ygs_…`). Server-side only. */
+    secret: string;
+    /**
+     * YouGrow's origin, e.g. from YOUGROW_ORIGIN. Defaults to https://yougrow.ai;
+     * set it when you're connected to another YouGrow instance (staging, self-hosted).
+     */
+    origin?: string;
+    /** Abandon a request after this long (default 10000); it's retried like a network error. */
+    timeoutMs?: number;
+    /** Retries per request for network errors, timeouts, 429 and 5xx (default 3). */
+    maxRetries?: number;
+    /** Longest wait between retries (default 5000), even when Retry-After asks for more. */
+    maxRetryWaitMs?: number;
+    /** Custom fetch (tests, proxies). */
+    fetch?: typeof fetch;
+}
+export interface BatchOptions {
+    /** Don't log the console.warn line about failed items. */
+    quiet?: boolean;
+    /** Throw a YouGrowBatchError, carrying the result, if any item failed. Every item is still sent. */
+    throwOnItemError?: boolean;
+}
+export interface TrackOptions {
+    properties?: Record<string, unknown>;
+    /** When it happened (ISO 8601 with a zone). */
+    occurredAt?: string;
+    /** The same key is recorded once. Defaults to a random key per call, so the SDK's own retries never count twice. */
+    idempotencyKey?: string;
+}
+export interface UsersApi {
+    /** Merge a patch into one user's state; creates the user if YouGrow hasn't seen them. */
+    update(userId: string, patch: UserPatch): Promise<PatchResponse>;
+    /**
+     * Patch any number of users, 100 per request, one request after another. One
+     * bad item never fails the rest: the result lists the ignored and failed ones,
+     * and failures are logged in one console.warn line (see BatchOptions).
+     */
+    batch(items: readonly BatchItem[], opts?: BatchOptions): Promise<BatchResponse>;
+    /** The user's state, journeys and opt-outs, or null if YouGrow doesn't know them. */
+    get(userId: string): Promise<UserView | null>;
+    /** Erase the user and their history. Safe to repeat, and for users YouGrow never saw. */
+    delete(userId: string): Promise<void>;
+}
+export interface EventsApi {
+    /** Record a milestone, e.g. "report.exported". Optional: journeys run on state. */
+    track(userId: string, event: string, opts?: TrackOptions): Promise<EventResult>;
+}
+/** The API refused a request, or still failed (429, 5xx) after the retries. */
+export declare class YouGrowError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), or `http_<status>` when the body has none. */
+    readonly code: string;
+    /** For a 400: which fields were wrong, and why. */
+    readonly fields?: FieldError[];
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+/** From `users.batch` with `throwOnItemError`: some items failed. The rest were applied; `result` says which. */
+export declare class YouGrowBatchError extends Error {
+    readonly result: BatchResponse;
+    constructor(message: string, result: BatchResponse);
+}
+export declare class YouGrow {
+    #private;
+    readonly users: UsersApi;
+    readonly events: EventsApi;
+    constructor(opts: YouGrowOptions);
+}