@yougrowai/node 0.1.0 → 0.4.0

package/dist/cjs/server.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ISSUER = void 0;
+exports.createVerifier = createVerifier;
+exports.contextResponse = contextResponse;
+const jwt_js_1 = require("./jwt.js");
+const origin_js_1 = require("./origin.js");
+/** YouGrow's default origin: the `iss` of its tokens. */
+exports.DEFAULT_ISSUER = origin_js_1.DEFAULT_ORIGIN;
+const JWKS_PATH = "/.well-known/jwks.json";
+const MIN_CACHE_MS = 60_000;
+const MAX_CACHE_MS = 24 * 3600_000;
+const DEFAULT_CACHE_MS = 3600_000;
+/** An unknown kid refetches the keys at most this often. */
+const REFETCH_COOLDOWN_MS = 60_000;
+function header(h, name) {
+    if (!h)
+        return null;
+    if (typeof h.get === "function")
+        return h.get(name);
+    const bag = h;
+    let v = bag[name] ?? bag[name.toLowerCase()];
+    if (v === undefined) {
+        // Plain objects can keep the sender's casing (e.g. API Gateway REST events): match any case.
+        const lower = name.toLowerCase();
+        v = Object.entries(bag).find(([k, value]) => value !== undefined && k.toLowerCase() === lower)?.[1];
+    }
+    return Array.isArray(v) ? (v[0] ?? null) : (v ?? null);
+}
+function cacheMs(cacheControl) {
+    const m = /max-age=(\d+)/.exec(cacheControl ?? "");
+    const ms = m ? Number(m[1]) * 1000 : DEFAULT_CACHE_MS;
+    return Math.min(MAX_CACHE_MS, Math.max(MIN_CACHE_MS, ms));
+}
+/**
+ * A verifier for one connection. It fetches YouGrow's public keys once, caches
+ * them as long as their Cache-Control allows, and refetches early (rate-limited)
+ * when a token names a key it hasn't seen — so YouGrow's key rotations need no
+ * change on your side. If a refresh fails it keeps using the keys it has.
+ */
+function createVerifier(opts) {
+    if (opts.origin && opts.issuer && (0, origin_js_1.originOf)(opts.origin) !== (0, origin_js_1.originOf)(opts.issuer)) {
+        throw new Error("createVerifier: origin and issuer differ (issuer is an alias of origin); pass origin only");
+    }
+    const issuer = (0, origin_js_1.originOf)(opts.origin || opts.issuer);
+    if (!opts.jwks && !(0, origin_js_1.isSecureOrigin)(issuer))
+        throw new Error("createVerifier: origin must be https");
+    if (!opts.keyId)
+        throw new Error("createVerifier: keyId is required");
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    let keys = opts.jwks?.keys ?? null;
+    let expiresAt = opts.jwks ? Number.POSITIVE_INFINITY : 0;
+    let lastFetchAt = Number.NEGATIVE_INFINITY;
+    let inflight = null;
+    async function refresh(now) {
+        if (opts.jwks)
+            return;
+        inflight ??= (async () => {
+            lastFetchAt = now;
+            try {
+                const res = await doFetch(`${issuer}${JWKS_PATH}`, { signal: AbortSignal.timeout(5000), redirect: "error" });
+                if (!res.ok)
+                    return;
+                const body = (await res.json());
+                if (!Array.isArray(body.keys))
+                    return;
+                keys = body.keys;
+                expiresAt = Date.now() + cacheMs(res.headers.get("cache-control"));
+            }
+            catch {
+                // Keep the keys we have (if any); the next request tries again.
+            }
+            finally {
+                inflight = null;
+            }
+        })();
+        await inflight;
+    }
+    return {
+        async verify(input) {
+            if (typeof input.rawBody !== "string" && !ArrayBuffer.isView(input.rawBody)) {
+                throw new TypeError("verify: rawBody must be the raw request body (a string or Buffer), not parsed JSON");
+            }
+            const token = (0, jwt_js_1.tokenFromAuthorization)(header(input.headers, "authorization"));
+            const now = Date.now();
+            const sinceFetch = now - lastFetchAt;
+            if (token && (keys ? now >= expiresAt && sinceFetch >= REFETCH_COOLDOWN_MS : sinceFetch >= 5000)) {
+                await refresh(now);
+            }
+            const kid = token ? (0, jwt_js_1.tokenKid)(token) : null;
+            if (token && kid && keys && !keys.some((k) => k.kid === kid) && Date.now() - lastFetchAt >= REFETCH_COOLDOWN_MS) {
+                await refresh(now);
+            }
+            if (token && !keys)
+                return { ok: false, reason: "keys_unavailable" };
+            return (0, jwt_js_1.verifyJwt)({
+                token,
+                keys: keys ?? [],
+                issuer,
+                audience: opts.keyId,
+                direction: input.direction,
+                rawBody: input.rawBody,
+                nowMs: input.nowMs,
+            });
+        },
+    };
+}
+/**
+ * Build a context response body. Throws on values YouGrow would reject, so
+ * mistakes show up in your logs rather than as a failed context pull.
+ */
+function contextResponse(input) {
+    const steps = input.steps ?? [];
+    const facts = input.facts ?? [];
+    const insights = input.insights ?? [];
+    if (steps.length > 20)
+        throw new Error("contextResponse: at most 20 steps");
+    if (facts.length > 50)
+        throw new Error("contextResponse: at most 50 facts");
+    if (insights.length > 20)
+        throw new Error("contextResponse: at most 20 insights");
+    for (const i of insights) {
+        if (i.sentence.length > 300)
+            throw new Error(`contextResponse: insight ${i.id} is over 300 characters`);
+    }
+    const asOf = input.asOf === undefined ? new Date() : input.asOf;
+    const body = JSON.stringify({
+        asOf: typeof asOf === "string" ? asOf : asOf.toISOString(),
+        steps,
+        nextStep: input.nextStep ?? null,
+        facts,
+        insights,
+        ...(input.consent ? { consent: input.consent } : {}),
+        ...(input.hold ? { hold: input.hold } : {}),
+        ...(input.exit ? { exit: input.exit } : {}),
+    });
+    if (Buffer.byteLength(body, "utf8") > 64 * 1024)
+        throw new Error("contextResponse: over 64 KB");
+    return body;
+}

package/dist/index.d.ts

@@ -1,89 +1,223 @@
 /**
- * @yougrowai/node — send your product's user events to YouGrow lifecycle journeys.
+ * @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! });
- *   yg.identify({ userId: user.id, traits: { email: user.email }, consent: { basis: "soft_opt_in" } });
- *   yg.track({ userId: user.id, event: "user.signed_up" });
- *   await yg.flush();
+ *   await yg.users.update(user.id, { email: user.email, signedUpAt: user.createdAt.toISOString(), consent: "soft_opt_in" });
  *
- * Server-side only (the secret signs every request). Messages are batched (≤100
- * per request) and retried with backoff on network errors, 429 and 5xx. Every
- * message carries a messageId, so a retried or duplicated send is harmless.
+ * 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 { HEADERS, sign, type Direction } from "./signing.js";
 export type ConsentBasis = "consent" | "soft_opt_in" | "corporate_subscriber" | "none";
-export type TraitValue = string | number | boolean | null;
+/**
+ * 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 = 
+/** `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;
+    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;
+    /**
+     * 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: "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;
+}
 export interface YouGrowOptions {
+    /** Your connection's key id (`ygk_…`). */
     keyId: string;
+    /** Its secret (`ygs_…`). Server-side only. */
     secret: string;
-    /** Ingest URL. Defaults to https://yougrow.ai/api/v1/events. */
-    endpoint?: string;
-    /** Flush automatically once this many messages are queued (max 100). */
-    flushAt?: number;
-    /** Flush automatically this long after the first queued message. 0 = manual only. */
-    flushIntervalMs?: number;
-    /** Retries per batch for network errors, 429 and 5xx. */
+    /**
+     * 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;
-    /** Called when a background flush fails. */
-    onError?: (err: Error) => void;
 }
-export interface IdentifyInput {
-    userId: string;
-    traits?: Record<string, TraitValue>;
-    consent?: {
-        basis: ConsentBasis;
-        source?: string;
-    };
-    timestamp?: Date | string;
-    messageId?: string;
+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 TrackInput {
-    userId: string;
-    event: string;
+export interface TrackOptions {
     properties?: Record<string, unknown>;
-    traits?: Record<string, TraitValue>;
-    timestamp?: Date | string;
-    messageId?: string;
-}
-export interface IngestResult {
-    accepted: number;
-    duplicates: number;
-    rejected: Array<{
-        index: number;
-        messageId: string | null;
-        reason: string;
-    }>;
+    /** 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 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;
-    constructor(message: string, status: number, body?: unknown | undefined);
+    /** 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[];
+    /**
+     * 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 {
+    readonly result: BatchResponse;
+    constructor(message: string, result: BatchResponse);
 }
 export declare class YouGrow {
-    private readonly keyId;
-    private readonly secret;
-    private readonly endpoint;
-    private readonly flushAt;
-    private readonly flushIntervalMs;
-    private readonly maxRetries;
-    private readonly fetchImpl;
-    private readonly onError?;
-    private queue;
-    private timer;
+    #private;
+    readonly users: UsersApi;
+    readonly events: EventsApi;
     constructor(opts: YouGrowOptions);
-    /** Who the user is: email, name, timezone, plan… plus the consent basis. Returns the messageId. */
-    identify(input: IdentifyInput): string;
-    /** Something the user did. Returns the messageId. */
-    track(input: TrackInput): string;
-    /** Shorthand for the reserved `onboarding.step_completed` event. */
-    stepCompleted(userId: string, step: string, timestamp?: Date | string): string;
-    /** Send everything queued. Resolves with one result per request. */
-    flush(): Promise<IngestResult[]>;
-    /** Flush and stop the background timer (call on shutdown). */
-    close(): Promise<IngestResult[]>;
-    private enqueue;
-    private clearTimer;
-    private send;
+    /**
+     * 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>;
 }