@yougrowai/node 0.1.0 → 0.4.0

package/dist/cjs/index.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YouGrow = exports.YouGrowBatchError = exports.YouGrowError = void 0;
+const node_crypto_1 = require("node:crypto");
+const origin_js_1 = require("./origin.js");
+const USERS_PATH = "/api/v2/users";
+/** The API's limits: users per batch request, and bytes per request body. */
+const MAX_BATCH = 100;
+const MAX_BODY_BYTES = 512 * 1024;
+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 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`…), `timeout` or `network_error`, or `http_<status>`. */
+    code;
+    /** For a 400: which fields were wrong, and why. */
+    fields;
+    /**
+     * 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";
+        const b = asRecord(body);
+        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;
+/** From `users.batch` with `throwOnItemError`: some items failed. The rest were applied; `result` says which. */
+class YouGrowBatchError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+        this.name = "YouGrowBatchError";
+    }
+}
+exports.YouGrowBatchError = YouGrowBatchError;
+class YouGrow {
+    users;
+    events;
+    #origin;
+    /** Private (#), so logging the client never prints the credentials. */
+    #authorization;
+    #timeoutMs;
+    #maxRetries;
+    #maxRetryWaitMs;
+    #fetch;
+    constructor(opts) {
+        if (!opts.keyId || !opts.secret)
+            throw new Error("YouGrow: keyId and secret are required");
+        this.#origin = (0, origin_js_1.originOf)(opts.origin);
+        if (!(0, origin_js_1.isSecureOrigin)(this.#origin))
+            throw new Error("YouGrow: origin must be https, e.g. https://yougrow.ai");
+        this.#authorization = `Basic ${Buffer.from(`${opts.keyId}:${opts.secret}`, "utf8").toString("base64")}`;
+        this.#timeoutMs = whole(opts.timeoutMs, 10_000, 1, MAX_TIMER_MS);
+        this.#maxRetries = whole(opts.maxRetries, 3, 0, Number.MAX_SAFE_INTEGER);
+        this.#maxRetryWaitMs = whole(opts.maxRetryWaitMs, 5_000, 0, MAX_TIMER_MS);
+        this.#fetch = opts.fetch ?? globalThis.fetch;
+        this.users = {
+            update: async (userId, patch) => (await this.#send("PATCH", userPath(userId), JSON.stringify(patch))),
+            batch: (items, batchOpts) => this.#patchMany(items, batchOpts),
+            get: async (userId) => {
+                try {
+                    return (await this.#send("GET", userPath(userId)));
+                }
+                catch (err) {
+                    // Only the API's own "no such user": a 404 from anything else (e.g. a wrong origin) still throws.
+                    if (err instanceof YouGrowError && err.status === 404 && err.code === "not_found")
+                        return null;
+                    throw err;
+                }
+            },
+            delete: async (userId) => {
+                await this.#send("DELETE", userPath(userId));
+            },
+        };
+        this.events = {
+            track: async (userId, event, options = {}) => {
+                const path = `${userPath(userId)}/events`;
+                const { properties, occurredAt } = options;
+                // One key for every attempt, so a retry is never recorded twice.
+                const body = { event, properties, occurredAt, idempotencyKey: options.idempotencyKey ?? (0, node_crypto_1.randomUUID)() };
+                return (await this.#send("POST", path, JSON.stringify(body)));
+            },
+        };
+    }
+    /**
+     * 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 }");
+        const total = { applied: 0, ignored: 0, failed: 0, results: [] };
+        for (const chunk of chunks(items)) {
+            if (chunk.bytes > MAX_BODY_BYTES) {
+                // One item bigger than any request may be: it can't be valid, so it fails here.
+                const userId = asRecord(items[chunk.start])?.userId;
+                total.failed += 1;
+                total.results.push({ index: chunk.start, userId: typeof userId === "string" ? userId : null, status: "failed", reason: "body_too_large" });
+                continue;
+            }
+            const r = (await this.#send("POST", `${USERS_PATH}/batch`, `{"users":[${chunk.json.join(",")}]}`));
+            total.applied += r.applied;
+            total.ignored += r.ignored;
+            total.failed += r.failed;
+            for (const item of r.results)
+                total.results.push({ ...item, index: chunk.start + item.index });
+        }
+        if (total.failed > 0) {
+            const summary = failureSummary(total, items.length);
+            if (opts.throwOnItemError)
+                throw new YouGrowBatchError(`YouGrow ${summary}`, total);
+            if (!opts.quiet)
+                console.warn(`[@yougrowai/node] ${summary}`);
+        }
+        return total;
+    }
+    /**
+     * One request, retried on network errors, timeouts, 429 and 5xx. Resolves
+     * with the JSON body (none for DELETE); an error status throws a YouGrowError.
+     */
+    async #send(method, path, body) {
+        const headers = { authorization: this.#authorization, accept: "application/json" };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const doFetch = this.#fetch; // called unbound: some fetch implementations refuse another `this`
+        for (let attempt = 0;; attempt += 1) {
+            let res;
+            let text;
+            try {
+                res = await doFetch(`${this.#origin}${path}`, { method, headers, body, signal: AbortSignal.timeout(this.#timeoutMs) });
+                text = await res.text(); // under the same deadline
+            }
+            catch (err) {
+                // Network error or timeout.
+                if (attempt >= this.#maxRetries)
+                    throw transportError(err);
+                await sleep(this.#retryWait(attempt));
+                continue;
+            }
+            const data = parseJson(text);
+            if (res.ok) {
+                if (method !== "DELETE" && !asRecord(data)) {
+                    throw new YouGrowError(`YouGrow API ${res.status}: the response isn't JSON (is origin right?)`, res.status);
+                }
+                return data;
+            }
+            if ((res.status === 429 || res.status >= 500) && attempt < this.#maxRetries) {
+                await sleep(this.#retryWait(attempt, res.headers.get("retry-after")));
+                continue;
+            }
+            throw apiError(res.status, data);
+        }
+    }
+    /** Retry-After (seconds) if given, else exponential backoff with full jitter; never over maxRetryWaitMs. */
+    #retryWait(attempt, retryAfter) {
+        const seconds = retryAfter?.trim();
+        if (seconds && /^\d+$/.test(seconds))
+            return Math.min(Number(seconds) * 1000, this.#maxRetryWaitMs);
+        return Math.random() * Math.min(500 * 2 ** attempt, this.#maxRetryWaitMs);
+    }
+}
+exports.YouGrow = YouGrow;
+/** `/api/v2/users/{userId}`, refusing an id the API can't take before anything is sent. */
+function userPath(userId) {
+    const problem = userIdProblem(userId);
+    if (problem)
+        throw new TypeError(`YouGrow: userId ${problem}`);
+    return `${USERS_PATH}/${encodeURIComponent(userId)}`;
+}
+function userIdProblem(userId) {
+    if (typeof userId !== "string")
+        return "must be a string";
+    if (userId.length === 0)
+        return "is empty";
+    if (userId.length > MAX_USER_ID)
+        return `is over ${MAX_USER_ID} characters`;
+    // "batch" is a route; "." and ".." vanish from a URL path.
+    if (userId === "batch" || userId === "." || userId === "..")
+        return `can't be "${userId}"`;
+    return null;
+}
+/**
+ * Consecutive runs of batch items, one request each: at most 100 users and
+ * 512 KB of body. A run over the limit is a single item too big to send.
+ */
+function* chunks(items) {
+    let chunk = { start: 0, json: [], bytes: BATCH_ENVELOPE_BYTES };
+    for (let i = 0; i < items.length; i += 1) {
+        const json = JSON.stringify(items[i]) ?? "null";
+        const size = Buffer.byteLength(json, "utf8");
+        // + 1 for the comma before it.
+        if (chunk.json.length === MAX_BATCH || (chunk.json.length > 0 && chunk.bytes + 1 + size > MAX_BODY_BYTES)) {
+            yield chunk;
+            chunk = { start: i, json: [], bytes: BATCH_ENVELOPE_BYTES };
+        }
+        chunk.bytes += (chunk.json.length > 0 ? 1 : 0) + size;
+        chunk.json.push(json);
+    }
+    if (chunk.json.length > 0)
+        yield chunk;
+}
+/** e.g. "users.batch: 2 of 250 users failed (u3: invalid, u17: invalid)". Ids and reasons only, never the data. */
+function failureSummary(r, count) {
+    const failed = r.results.filter((x) => x.status === "failed");
+    const shown = failed.slice(0, 3).map((x) => `${x.userId ?? `item ${x.index}`}: ${x.reason}`);
+    if (failed.length > 3)
+        shown.push(`+${failed.length - 3} more`);
+    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 : [];
+    let detail = fields
+        .slice(0, 3)
+        .map((f) => `${f.path}: ${f.message}`)
+        .join("; ");
+    if (fields.length > 3)
+        detail += `; +${fields.length - 3} more`;
+    if (!detail && typeof b?.message === "string")
+        detail = b.message;
+    const code = typeof b?.error === "string" ? ` ${b.error}` : "";
+    return new YouGrowError(`YouGrow API ${status}${code}${detail ? `: ${detail}` : ""}`, status, body);
+}
+function asRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+function parseJson(text) {
+    try {
+        return text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A whole number in [min, max] from an option; unset or not a number means the default. */
+function whole(value, fallback, min, max) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.min(Math.max(Math.floor(value), min), max) : fallback;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/cjs/jwt.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Verifies the token YouGrow puts on every request it sends your server
+ * (context pulls, webhooks):
+ *
+ *   Authorization: Bearer <JWT>     alg ES256, kid = one of YouGrow's published keys
+ *   iss  YouGrow's origin (its keys are at `${iss}/.well-known/jwks.json`)
+ *   aud  your connection's key id
+ *   dir  "context" | "webhook"
+ *   iat / exp   at most 5 minutes apart
+ *   jti  unique per request
+ *   body_sha256  base64url SHA-256 of the exact raw body (the bytes as received)
+ *
+ * Signature first, then every claim. Pinned by test/vectors.json.
+ */
+export type RequestDirection = "context" | "webhook";
+export interface Jwk {
+    kty: string;
+    crv?: string;
+    x?: string;
+    y?: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+}
+export type JwtFailure = "missing_token" | "malformed" | "unsupported_alg" | "unknown_key" | "bad_signature" | "wrong_issuer" | "wrong_audience" | "wrong_direction" | "expired" | "not_yet_valid" | "body_mismatch";
+export interface YouGrowClaims {
+    iss: string;
+    aud: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    dir: RequestDirection;
+    body_sha256: string;
+}
+export type JwtResult = {
+    ok: true;
+    claims: YouGrowClaims;
+} | {
+    ok: false;
+    reason: JwtFailure;
+};
+export declare function tokenFromAuthorization(value: string | null | undefined): string | null;
+/** The kid in a token's header, without trusting anything else in it. */
+export declare function tokenKid(token: string): string | null;
+export declare function verifyJwt(input: {
+    token: string | null;
+    keys: Jwk[];
+    issuer: string;
+    audience: string;
+    direction: RequestDirection;
+    /** The bytes as received; a string is hashed as UTF-8. */
+    rawBody: string | Uint8Array;
+    nowMs?: number;
+}): JwtResult;

package/dist/cjs/jwt.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenFromAuthorization = tokenFromAuthorization;
+exports.tokenKid = tokenKid;
+exports.verifyJwt = verifyJwt;
+const node_crypto_1 = require("node:crypto");
+const MAX_LIFETIME_SEC = 300;
+const LEEWAY_SEC = 60;
+function decodeJson(part) {
+    try {
+        const v = JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+        return v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+function tokenFromAuthorization(value) {
+    const m = /^Bearer\s+([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\s*$/.exec(value ?? "");
+    return m ? m[1] : null;
+}
+/** The kid in a token's header, without trusting anything else in it. */
+function tokenKid(token) {
+    const header = decodeJson(token.split(".")[0] ?? "");
+    return header && typeof header.kid === "string" ? header.kid : null;
+}
+function verifyJwt(input) {
+    if (!input.token)
+        return { ok: false, reason: "missing_token" };
+    const parts = input.token.split(".");
+    if (parts.length !== 3)
+        return { ok: false, reason: "malformed" };
+    const [h, p, s] = parts;
+    const header = decodeJson(h);
+    if (!header)
+        return { ok: false, reason: "malformed" };
+    // Pin the algorithm: never let the token choose (no "none", no HMAC).
+    if (header.alg !== "ES256")
+        return { ok: false, reason: "unsupported_alg" };
+    const jwk = input.keys.find((k) => k.kid === header.kid && k.kty === "EC" && k.crv === "P-256");
+    if (!jwk?.x || !jwk.y)
+        return { ok: false, reason: "unknown_key" };
+    const signature = Buffer.from(s, "base64url");
+    let valid = false;
+    try {
+        const key = (0, node_crypto_1.createPublicKey)({ key: { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y }, format: "jwk" });
+        valid =
+            signature.length === 64 &&
+                (0, node_crypto_1.verify)("sha256", Buffer.from(`${h}.${p}`), { key, dsaEncoding: "ieee-p1363" }, signature);
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        return { ok: false, reason: "bad_signature" };
+    const c = decodeJson(p);
+    if (!c)
+        return { ok: false, reason: "malformed" };
+    if (c.iss !== input.issuer)
+        return { ok: false, reason: "wrong_issuer" };
+    if (c.aud !== input.audience)
+        return { ok: false, reason: "wrong_audience" };
+    if (c.dir !== input.direction)
+        return { ok: false, reason: "wrong_direction" };
+    if (typeof c.iat !== "number" || typeof c.exp !== "number" || typeof c.jti !== "string") {
+        return { ok: false, reason: "malformed" };
+    }
+    if (c.exp - c.iat > MAX_LIFETIME_SEC)
+        return { ok: false, reason: "malformed" };
+    const nowSec = Math.floor((input.nowMs ?? Date.now()) / 1000);
+    if (nowSec > c.exp + LEEWAY_SEC)
+        return { ok: false, reason: "expired" };
+    if (nowSec < c.iat - LEEWAY_SEC)
+        return { ok: false, reason: "not_yet_valid" };
+    const bytes = typeof input.rawBody === "string" ? Buffer.from(input.rawBody, "utf8") : input.rawBody;
+    const hash = (0, node_crypto_1.createHash)("sha256").update(bytes).digest("base64url");
+    if (c.body_sha256 !== hash)
+        return { ok: false, reason: "body_mismatch" };
+    return { ok: true, claims: c };
+}

package/dist/cjs/origin.d.ts

@@ -0,0 +1,11 @@
+/**
+ * YouGrow's origin, shared by the client (its requests go to `${origin}/api/v2/…`)
+ * and the verifier (tokens carry `iss: origin`; keys are at
+ * `${origin}/.well-known/jwks.json`). Pass the same value to both, e.g. from
+ * YOUGROW_ORIGIN, when you're connected to another YouGrow instance.
+ */
+export declare const DEFAULT_ORIGIN = "https://yougrow.ai";
+/** Without trailing slashes. Unset or empty means DEFAULT_ORIGIN. */
+export declare function originOf(value: string | undefined): string;
+/** https, or plain http on localhost for local development. */
+export declare function isSecureOrigin(origin: string): boolean;

package/dist/cjs/origin.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * YouGrow's origin, shared by the client (its requests go to `${origin}/api/v2/…`)
+ * and the verifier (tokens carry `iss: origin`; keys are at
+ * `${origin}/.well-known/jwks.json`). Pass the same value to both, e.g. from
+ * YOUGROW_ORIGIN, when you're connected to another YouGrow instance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ORIGIN = void 0;
+exports.originOf = originOf;
+exports.isSecureOrigin = isSecureOrigin;
+exports.DEFAULT_ORIGIN = "https://yougrow.ai";
+/** Without trailing slashes. Unset or empty means DEFAULT_ORIGIN. */
+function originOf(value) {
+    return (value || exports.DEFAULT_ORIGIN).replace(/\/+$/, "");
+}
+/** https, or plain http on localhost for local development. */
+function isSecureOrigin(origin) {
+    return /^https:\/\//.test(origin) || /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin);
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/server.d.ts

@@ -0,0 +1,145 @@
+import { type Jwk, type JwtFailure, type RequestDirection, type YouGrowClaims } from "./jwt.js";
+/**
+ * Helpers for the two endpoints YouGrow calls on YOUR server:
+ *
+ *  - the context endpoint (direction "context"): before an email, YouGrow asks
+ *    for one user's onboarding steps, facts and insight sentences;
+ *  - the webhook endpoint (direction "webhook"): YouGrow tells you about
+ *    preference changes, e.g. an unsubscribe.
+ *
+ * Every such request carries `Authorization: Bearer <JWT>` signed with
+ * YouGrow's private key. Your secret is NOT involved — you verify against
+ * YouGrow's public keys, so nothing you store can be used to forge YouGrow.
+ * Always verify against the RAW body (the exact bytes received, as a Buffer or
+ * string), before parsing it.
+ *
+ *   const verifier = createVerifier({ keyId: process.env.YOUGROW_KEY_ID!, origin: process.env.YOUGROW_ORIGIN });
+ *   const v = await verifier.verify({ headers: req.headers, rawBody, direction: "context" });
+ *   if (!v.ok) return res.status(401).end();
+ */
+export type { Jwk, RequestDirection, YouGrowClaims } from "./jwt.js";
+/** YouGrow's default origin: the `iss` of its tokens. */
+export declare const DEFAULT_ISSUER = "https://yougrow.ai";
+type HeaderBag = Headers | Record<string, string | string[] | undefined>;
+export type VerifyResult = {
+    ok: true;
+    claims: YouGrowClaims;
+} | {
+    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;
+    /**
+     * YouGrow's origin: the same value as the client's `origin`, e.g. from
+     * YOUGROW_ORIGIN. Defaults to https://yougrow.ai. Tokens must carry it as
+     * `iss`, and the keys are fetched from `${origin}/.well-known/jwks.json`.
+     */
+    origin?: string;
+    /** Alias of `origin` (its 0.1 name). */
+    issuer?: string;
+    /** Pin the key set instead of fetching it (tests, air-gapped setups). */
+    jwks?: {
+        keys: Jwk[];
+    };
+    fetch?: typeof fetch;
+}
+export interface Verifier {
+    /**
+     * Check one request. `rawBody` is the exact body received — a string, or the
+     * bytes (e.g. a Buffer) — never re-serialised JSON. Plain header objects
+     * match in any case; Fetch `Headers` already do.
+     */
+    verify(input: {
+        headers: HeaderBag;
+        rawBody: string | Uint8Array;
+        direction: RequestDirection;
+        nowMs?: number;
+    }): Promise<VerifyResult>;
+}
+/**
+ * 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.
+ */
+export declare function createVerifier(opts: VerifierOptions): Verifier;
+export interface ContextStep {
+    id: string;
+    label: string;
+    done: boolean;
+    doneAt?: string | null;
+    url?: string | null;
+    blocked?: string | null;
+}
+export interface ContextFact {
+    id: string;
+    label: string;
+    value: string | number | boolean;
+    unit?: string | null;
+    display?: string | null;
+    source?: string | null;
+    observedAt?: string | null;
+}
+export interface ContextInsight {
+    id: string;
+    /** A complete, TRUE sentence — the only place numbers about the user appear. */
+    sentence: string;
+    factIds?: string[];
+    weight?: number;
+    supportsStep?: string | null;
+}
+export interface ContextInput {
+    asOf?: Date | string;
+    steps?: ContextStep[];
+    nextStep?: {
+        id: string;
+        label: string;
+        url?: string | null;
+    } | null;
+    facts?: ContextFact[];
+    insights?: ContextInsight[];
+    consent?: {
+        basis: "consent" | "soft_opt_in" | "corporate_subscriber" | "none";
+        categories?: Record<string, boolean>;
+    } | null;
+    /** Don't email this user yet (e.g. data still loading). */
+    hold?: {
+        until?: string | null;
+        reason: string;
+    } | null;
+    /** Stop all lifecycle email for this user (e.g. staff, pending deletion). */
+    exit?: {
+        reason: string;
+    } | null;
+}
+/**
+ * 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.
+ */
+export declare function contextResponse(input: ContextInput): string;