@yougrowai/node 0.3.0 → 0.4.0

package/README.md

@@ -10,8 +10,8 @@ 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).
+> 0.3.0 and later are 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
@@ -41,6 +41,9 @@ const yg = new YouGrow({
   origin: process.env.YOUGROW_ORIGIN,   // optional; defaults to https://yougrow.ai
 });
 
+// Check the key (e.g. when you deploy): which connection and environment it's for
+const { connection } = await yg.me(); // { name, environment: "production", status: "active", … }
+
 // At sign-up: who they are, and the basis for emailing them
 await yg.users.update(user.id, {
   email: user.email,
@@ -135,8 +138,10 @@ record an event twice. A key that was already recorded resolves
 - 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.
+  own, never traits. An invalid one doesn't sink the update: the rest applies,
+  that field keeps its stored value, and the result lists it in
+  `ignoredFields`. Anything else invalid, including an unknown field, is
+  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.
 
@@ -178,8 +183,13 @@ Every method returns a promise; await it.
   `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.
+  retries rejects the same way, and so does a network failure or timeout
+  (`status` 0, `code` `network_error` or `timeout`, the original error as
+  `cause`).
+- `err.retryable` says whether trying again later may work: true for a 429, a
+  5xx, a timeout or a network failure. In a queue worker, or a trigger with
+  retries on, rethrow those so the work is redelivered, and log the rest: a
+  400 won't succeed as it is. Every write is safe to repeat.
 - A user id the API can't take (empty, over 256 characters, `"batch"`, `"."`
   or `".."`) rejects with a `TypeError` before anything is sent.
 
@@ -189,8 +199,9 @@ 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;
+  if (err instanceof YouGrowError && err.retryable) throw err; // 429, 5xx, timeout, network: let it be retried
+  if (err instanceof YouGrowError) console.error(err.message, err.fields); // e.g. a 400: [{ path, message }]; fix it
+  else throw err;
 }
 ```
 
@@ -285,10 +296,20 @@ never invents them.
 
 ### Webhooks
 
-YouGrow tells your webhook endpoint about preference changes, e.g. an
-unsubscribe from onboarding tips. Verify it with
-`verifier.verify({ …, direction: "webhook" })`. Webhook ids (`jti` in the
-token, `id` in the body) are unique, so you can drop duplicates.
+YouGrow tells your webhook endpoint about changes to mirror. Verify each request
+with `verifier.verify({ …, direction: "webhook" })`, then read the body as a
+`WebhookEvent` (a type from `@yougrowai/node/server`):
+
+- `email_preferences.updated`: the person unsubscribed from one of YouGrow's
+  emails (`data.scope` is `all` or `category`).
+- `email.suppressed`: YouGrow stopped emailing them, because their address
+  hard-bounced (`data.reason` `hard_bounce`) or they reported an email as spam
+  (`complaint`).
+- `connection.test`: the Test webhook button.
+
+Reply 2xx to any type you don't handle. Webhook ids (`jti` in the token, `id` in
+the body) are unique and the same on every retry, so you can drop duplicates.
+API writes never trigger a webhook, so echoing a change back can't loop.
 
 ## Without the SDK
 
@@ -322,9 +343,17 @@ at https://yougrow.ai/developers.
 `test/vectors.json` (included in this package) holds reference tokens for
 checking your own verifier.
 
+## Upgrading from 0.3
+
+- A network failure or timeout that outlasts the retries now rejects with a
+  `YouGrowError` (`status` 0, `code` `network_error` or `timeout`) instead of
+  the raw error, which is its `cause`.
+- New: `yg.me()`, `err.retryable`, `ignoredFields` on update results (and
+  `fields_ignored` in batch results), and the `WebhookEvent` type.
+
 ## Upgrading from 0.1.x
 
-| 0.1.x (API v1) | 0.3.0 (API v2) |
+| 0.1.x (API v1) | 0.3.0 and later (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` |

package/dist/cjs/index.d.ts

@@ -81,9 +81,12 @@ export interface UserView extends UserState {
 }
 /** 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 = {
+export type PatchResponse = 
+/** `ignoredFields`: profile fields whose value was invalid, so left as they were; the rest applied. */
+{
     applied: true;
     user: UserState;
+    ignoredFields?: FieldError[];
 } | {
     applied: false;
     reason: SkipReason;
@@ -103,15 +106,30 @@ 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. */
+    /**
+     * The ignored and failed items, and applied ones whose invalid profile fields were
+     * left as they were (reason `fields_ignored`). `index` is the item's position in your array.
+     */
     results: Array<{
         index: number;
         userId: string | null;
-        status: "ignored" | "failed";
+        status: "applied" | "ignored" | "failed";
         reason: string;
         fields?: FieldError[];
     }>;
 }
+/** The connection behind your key (`GET /api/v2/me`). */
+export interface MeResponse {
+    connection: {
+        id: string;
+        name: string;
+        environment: "staging" | "production" | null;
+        status: "active" | "paused" | "revoked";
+    };
+    keyId: string;
+    /** A new secret was issued in the last 24 hours; the previous one works until then. */
+    rotating: boolean;
+}
 export interface EventResult {
     recorded: boolean;
     duplicate: boolean;
@@ -166,15 +184,26 @@ 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. */
+/**
+ * The API refused a request, or it still failed after the retries: a 429, a 5xx,
+ * or a timeout or network failure (`status` 0, `code` `timeout` or `network_error`).
+ */
 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. */
+    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), `timeout` or `network_error`, or `http_<status>`. */
     readonly code: string;
     /** For a 400: which fields were wrong, and why. */
     readonly fields?: FieldError[];
-    constructor(message: string, status: number, body?: unknown | undefined);
+    /**
+     * True for a 429, a 5xx, a timeout or a network failure: trying again later may
+     * work, so a queue or trigger should rethrow it for redelivery. Anything else
+     * (a 400, 401, 404…) won't succeed as it is.
+     */
+    readonly retryable: boolean;
+    constructor(message: string, status: number, body?: unknown | undefined, options?: {
+        cause?: unknown;
+    });
 }
 /** From `users.batch` with `throwOnItemError`: some items failed. The rest were applied; `result` says which. */
 export declare class YouGrowBatchError extends Error {
@@ -186,4 +215,9 @@ export declare class YouGrow {
     readonly users: UsersApi;
     readonly events: EventsApi;
     constructor(opts: YouGrowOptions);
+    /**
+     * The connection behind your key: its name, environment and status. A credential
+     * check — and a way to catch a key from the wrong environment — before you send.
+     */
+    me(): Promise<MeResponse>;
 }

package/dist/cjs/index.js

@@ -11,16 +11,25 @@ const BATCH_ENVELOPE_BYTES = '{"users":[]}'.length;
 const MAX_USER_ID = 256;
 /** The longest delay a Node timer accepts. */
 const MAX_TIMER_MS = 2_147_483_647;
-/** The API refused a request, or still failed (429, 5xx) after the retries. */
+/**
+ * The API refused a request, or it still failed after the retries: a 429, a 5xx,
+ * or a timeout or network failure (`status` 0, `code` `timeout` or `network_error`).
+ */
 class YouGrowError extends Error {
     status;
     body;
-    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), or `http_<status>` when the body has none. */
+    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), `timeout` or `network_error`, or `http_<status>`. */
     code;
     /** For a 400: which fields were wrong, and why. */
     fields;
-    constructor(message, status, body) {
-        super(message);
+    /**
+     * True for a 429, a 5xx, a timeout or a network failure: trying again later may
+     * work, so a queue or trigger should rethrow it for redelivery. Anything else
+     * (a 400, 401, 404…) won't succeed as it is.
+     */
+    retryable;
+    constructor(message, status, body, options) {
+        super(message, options);
         this.status = status;
         this.body = body;
         this.name = "YouGrowError";
@@ -28,6 +37,7 @@ class YouGrowError extends Error {
         this.code = typeof b?.error === "string" ? b.error : `http_${status}`;
         if (Array.isArray(b?.fields))
             this.fields = b.fields;
+        this.retryable = status === 0 || status === 429 || status >= 500;
     }
 }
 exports.YouGrowError = YouGrowError;
@@ -90,6 +100,13 @@ class YouGrow {
             },
         };
     }
+    /**
+     * The connection behind your key: its name, environment and status. A credential
+     * check — and a way to catch a key from the wrong environment — before you send.
+     */
+    async me() {
+        return (await this.#send("GET", "/api/v2/me"));
+    }
     async #patchMany(items, opts = {}) {
         if (!Array.isArray(items))
             throw new TypeError("YouGrow: users.batch takes an array of { userId, ...patch }");
@@ -137,7 +154,7 @@ class YouGrow {
             catch (err) {
                 // Network error or timeout.
                 if (attempt >= this.#maxRetries)
-                    throw err;
+                    throw transportError(err);
                 await sleep(this.#retryWait(attempt));
                 continue;
             }
@@ -212,6 +229,12 @@ function failureSummary(r, count) {
     return `users.batch: ${r.failed} of ${count} users failed${shown.length > 0 ? ` (${shown.join(", ")})` : ""}`;
 }
 /** e.g. "YouGrow API 400 invalid: traits.plan: …". */
+/** A timeout or network failure that outlasted the retries: status 0, retryable, the original error as `cause`. */
+function transportError(err) {
+    const code = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError") ? "timeout" : "network_error";
+    const detail = err instanceof Error ? err.message : String(err);
+    return new YouGrowError(`YouGrow API ${code}: ${detail}`, 0, { error: code }, { cause: err });
+}
 function apiError(status, body) {
     const b = asRecord(body);
     const fields = Array.isArray(b?.fields) ? b.fields : [];

package/dist/cjs/server.d.ts

@@ -28,6 +28,30 @@ export type VerifyResult = {
     ok: false;
     reason: JwtFailure | "keys_unavailable";
 };
+/** What YouGrow POSTs to your webhook endpoint: one of these, by `type`. Reply 2xx to any type you don't handle. */
+export type WebhookEvent = WebhookEnvelope<"email_preferences.updated", 
+/** The person unsubscribed from one of YouGrow's emails: from one category, or all of them. */
+{
+    userId: string;
+    category: string;
+    subscribed: false;
+    scope: "all" | "category";
+    source: string;
+}>
+/** YouGrow stopped emailing the person: their address hard-bounced, or they reported an email as spam. */
+ | WebhookEnvelope<"email.suppressed", {
+    userId: string;
+    reason: "hard_bounce" | "complaint";
+}>
+/** The Test webhook button. */
+ | WebhookEnvelope<"connection.test", Record<string, never>>;
+export interface WebhookEnvelope<T extends string, D> {
+    /** Unique per webhook, and the same on every retry: drop ones you've seen. */
+    id: string;
+    type: T;
+    createdAt: string;
+    data: D;
+}
 export interface VerifierOptions {
     /** Your connection's key id — the token's audience. */
     keyId: string;

package/dist/index.d.ts

@@ -81,9 +81,12 @@ export interface UserView extends UserState {
 }
 /** 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 = {
+export type PatchResponse = 
+/** `ignoredFields`: profile fields whose value was invalid, so left as they were; the rest applied. */
+{
     applied: true;
     user: UserState;
+    ignoredFields?: FieldError[];
 } | {
     applied: false;
     reason: SkipReason;
@@ -103,15 +106,30 @@ 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. */
+    /**
+     * The ignored and failed items, and applied ones whose invalid profile fields were
+     * left as they were (reason `fields_ignored`). `index` is the item's position in your array.
+     */
     results: Array<{
         index: number;
         userId: string | null;
-        status: "ignored" | "failed";
+        status: "applied" | "ignored" | "failed";
         reason: string;
         fields?: FieldError[];
     }>;
 }
+/** The connection behind your key (`GET /api/v2/me`). */
+export interface MeResponse {
+    connection: {
+        id: string;
+        name: string;
+        environment: "staging" | "production" | null;
+        status: "active" | "paused" | "revoked";
+    };
+    keyId: string;
+    /** A new secret was issued in the last 24 hours; the previous one works until then. */
+    rotating: boolean;
+}
 export interface EventResult {
     recorded: boolean;
     duplicate: boolean;
@@ -166,15 +184,26 @@ 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. */
+/**
+ * The API refused a request, or it still failed after the retries: a 429, a 5xx,
+ * or a timeout or network failure (`status` 0, `code` `timeout` or `network_error`).
+ */
 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. */
+    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), `timeout` or `network_error`, or `http_<status>`. */
     readonly code: string;
     /** For a 400: which fields were wrong, and why. */
     readonly fields?: FieldError[];
-    constructor(message: string, status: number, body?: unknown | undefined);
+    /**
+     * True for a 429, a 5xx, a timeout or a network failure: trying again later may
+     * work, so a queue or trigger should rethrow it for redelivery. Anything else
+     * (a 400, 401, 404…) won't succeed as it is.
+     */
+    readonly retryable: boolean;
+    constructor(message: string, status: number, body?: unknown | undefined, options?: {
+        cause?: unknown;
+    });
 }
 /** From `users.batch` with `throwOnItemError`: some items failed. The rest were applied; `result` says which. */
 export declare class YouGrowBatchError extends Error {
@@ -186,4 +215,9 @@ export declare class YouGrow {
     readonly users: UsersApi;
     readonly events: EventsApi;
     constructor(opts: YouGrowOptions);
+    /**
+     * The connection behind your key: its name, environment and status. A credential
+     * check — and a way to catch a key from the wrong environment — before you send.
+     */
+    me(): Promise<MeResponse>;
 }

package/dist/index.js

@@ -8,16 +8,25 @@ const BATCH_ENVELOPE_BYTES = '{"users":[]}'.length;
 const MAX_USER_ID = 256;
 /** The longest delay a Node timer accepts. */
 const MAX_TIMER_MS = 2_147_483_647;
-/** The API refused a request, or still failed (429, 5xx) after the retries. */
+/**
+ * The API refused a request, or it still failed after the retries: a 429, a 5xx,
+ * or a timeout or network failure (`status` 0, `code` `timeout` or `network_error`).
+ */
 export class YouGrowError extends Error {
     status;
     body;
-    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), or `http_<status>` when the body has none. */
+    /** The API's error code (`invalid`, `unauthorized`, `rate_limited`…), `timeout` or `network_error`, or `http_<status>`. */
     code;
     /** For a 400: which fields were wrong, and why. */
     fields;
-    constructor(message, status, body) {
-        super(message);
+    /**
+     * True for a 429, a 5xx, a timeout or a network failure: trying again later may
+     * work, so a queue or trigger should rethrow it for redelivery. Anything else
+     * (a 400, 401, 404…) won't succeed as it is.
+     */
+    retryable;
+    constructor(message, status, body, options) {
+        super(message, options);
         this.status = status;
         this.body = body;
         this.name = "YouGrowError";
@@ -25,6 +34,7 @@ export class YouGrowError extends Error {
         this.code = typeof b?.error === "string" ? b.error : `http_${status}`;
         if (Array.isArray(b?.fields))
             this.fields = b.fields;
+        this.retryable = status === 0 || status === 429 || status >= 500;
     }
 }
 /** From `users.batch` with `throwOnItemError`: some items failed. The rest were applied; `result` says which. */
@@ -85,6 +95,13 @@ export class YouGrow {
             },
         };
     }
+    /**
+     * The connection behind your key: its name, environment and status. A credential
+     * check — and a way to catch a key from the wrong environment — before you send.
+     */
+    async me() {
+        return (await this.#send("GET", "/api/v2/me"));
+    }
     async #patchMany(items, opts = {}) {
         if (!Array.isArray(items))
             throw new TypeError("YouGrow: users.batch takes an array of { userId, ...patch }");
@@ -132,7 +149,7 @@ export class YouGrow {
             catch (err) {
                 // Network error or timeout.
                 if (attempt >= this.#maxRetries)
-                    throw err;
+                    throw transportError(err);
                 await sleep(this.#retryWait(attempt));
                 continue;
             }
@@ -206,6 +223,12 @@ function failureSummary(r, count) {
     return `users.batch: ${r.failed} of ${count} users failed${shown.length > 0 ? ` (${shown.join(", ")})` : ""}`;
 }
 /** e.g. "YouGrow API 400 invalid: traits.plan: …". */
+/** A timeout or network failure that outlasted the retries: status 0, retryable, the original error as `cause`. */
+function transportError(err) {
+    const code = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError") ? "timeout" : "network_error";
+    const detail = err instanceof Error ? err.message : String(err);
+    return new YouGrowError(`YouGrow API ${code}: ${detail}`, 0, { error: code }, { cause: err });
+}
 function apiError(status, body) {
     const b = asRecord(body);
     const fields = Array.isArray(b?.fields) ? b.fields : [];

package/dist/server.d.ts

@@ -28,6 +28,30 @@ export type VerifyResult = {
     ok: false;
     reason: JwtFailure | "keys_unavailable";
 };
+/** What YouGrow POSTs to your webhook endpoint: one of these, by `type`. Reply 2xx to any type you don't handle. */
+export type WebhookEvent = WebhookEnvelope<"email_preferences.updated", 
+/** The person unsubscribed from one of YouGrow's emails: from one category, or all of them. */
+{
+    userId: string;
+    category: string;
+    subscribed: false;
+    scope: "all" | "category";
+    source: string;
+}>
+/** YouGrow stopped emailing the person: their address hard-bounced, or they reported an email as spam. */
+ | WebhookEnvelope<"email.suppressed", {
+    userId: string;
+    reason: "hard_bounce" | "complaint";
+}>
+/** The Test webhook button. */
+ | WebhookEnvelope<"connection.test", Record<string, never>>;
+export interface WebhookEnvelope<T extends string, D> {
+    /** Unique per webhook, and the same on every retry: drop ones you've seen. */
+    id: string;
+    type: T;
+    createdAt: string;
+    data: D;
+}
 export interface VerifierOptions {
     /** Your connection's key id — the token's audience. */
     keyId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yougrowai/node",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Keep your users' state in YouGrow lifecycle journeys, and verify the requests YouGrow sends you.",
   "license": "MIT",
   "author": "YouGrow.AI Limited",
@@ -22,7 +22,8 @@
     "./server": {
       "import": { "types": "./dist/server.d.ts", "default": "./dist/server.js" },
       "require": { "types": "./dist/cjs/server.d.ts", "default": "./dist/cjs/server.js" }
-    }
+    },
+    "./package.json": "./package.json"
   },
   "typesVersions": {
     "*": { "server": ["./dist/cjs/server.d.ts"] }