@yougrowai/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YouGrow.AI Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @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.
+
+```sh
+npm install @yougrowai/node
+```
+
+Node 18 or later, no dependencies. Server-side only: your secret must never
+reach a browser or app bundle.
+
+> 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.
+
+## Send events
+
+```ts
+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
+});
+
+// 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
+});
+yg.track({ userId: user.id, event: "user.signed_up" });
+
+// As onboarding progresses
+yg.stepCompleted(user.id, "create_brand");
+
+await yg.flush(); // or let it flush automatically (every 20 messages / 5 s)
+```
+
+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.
+
+### Reserved events
+
+| 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 |
+
+Other event names (lower-case, dotted, e.g. `report.exported`) are recorded as
+milestones.
+
+## Answer context requests
+
+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.
+
+```ts
+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
+});
+
+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" });
+  if (!v.ok) return res.status(401).end();
+
+  const { userId } = JSON.parse(rawBody);
+  const u = await loadOnboardingState(userId);
+  res.type("json").send(
+    contextResponse({
+      steps: u.steps, // [{ id, label, done, url }]
+      nextStep: u.nextStep,
+      facts: [{ id: "sov", label: "Share of voice", value: 12, unit: "%" }],
+      insights: [{ id: "sov", sentence: "Across 4 AI engines you appear in 12% of answers.", factIds: ["sov"] }],
+      // exit: { reason: "staff" } stops lifecycle email for this user
+    }),
+  );
+});
+```
+
+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.
+
+Numbers about the user appear only in your facts and insight sentences. YouGrow
+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.
+
+## Without the SDK
+
+**Events you send** are signed with your secret, over the exact request body:
+
+```
+X-YouGrow-Key-Id:    <key id>
+X-YouGrow-Timestamp: <unix seconds>
+X-YouGrow-Signature: v1=<hex HMAC-SHA256(secret, "events:<timestamp>.<raw body>")>
+```
+
+Requests more than five minutes out are refused.
+
+**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`
+   matches. Cache that file per its `Cache-Control`.
+2. `iss` is `https://yougrow.ai`, 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.
+
+## Credentials
+
+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).

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @yougrowai/node — send your product's user events to YouGrow lifecycle journeys.
+ *
+ *   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();
+ *
+ * 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.
+ */
+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;
+export interface YouGrowOptions {
+    keyId: string;
+    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. */
+    maxRetries?: 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 TrackInput {
+    userId: string;
+    event: string;
+    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;
+    }>;
+}
+export declare class YouGrowError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+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;
+    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;
+}

package/dist/index.js

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import { HEADERS, sign } from "./signing.js";
+/**
+ * @yougrowai/node — send your product's user events to YouGrow lifecycle journeys.
+ *
+ *   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();
+ *
+ * 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.
+ */
+export { HEADERS, sign } from "./signing.js";
+const MAX_BATCH = 100;
+export class YouGrowError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "YouGrowError";
+    }
+}
+export class YouGrow {
+    keyId;
+    secret;
+    endpoint;
+    flushAt;
+    flushIntervalMs;
+    maxRetries;
+    fetchImpl;
+    onError;
+    queue = [];
+    timer = null;
+    constructor(opts) {
+        if (!opts.keyId || !opts.secret)
+            throw new Error("YouGrow: keyId and secret are required");
+        this.keyId = opts.keyId;
+        this.secret = opts.secret;
+        this.endpoint = opts.endpoint ?? "https://yougrow.ai/api/v1/events";
+        this.flushAt = Math.min(Math.max(opts.flushAt ?? 20, 1), MAX_BATCH);
+        this.flushIntervalMs = opts.flushIntervalMs ?? 5000;
+        this.maxRetries = opts.maxRetries ?? 3;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.onError = opts.onError;
+    }
+    /** Who the user is: email, name, timezone, plan… plus the consent basis. Returns the messageId. */
+    identify(input) {
+        return this.enqueue({
+            type: "identify",
+            messageId: input.messageId ?? randomUUID(),
+            userId: input.userId,
+            timestamp: iso(input.timestamp),
+            traits: input.traits ?? {},
+            ...(input.consent ? { consent: input.consent } : {}),
+        });
+    }
+    /** Something the user did. Returns the messageId. */
+    track(input) {
+        return this.enqueue({
+            type: "track",
+            messageId: input.messageId ?? randomUUID(),
+            userId: input.userId,
+            timestamp: iso(input.timestamp),
+            event: input.event,
+            properties: input.properties ?? {},
+            ...(input.traits ? { traits: input.traits } : {}),
+        });
+    }
+    /** Shorthand for the reserved `onboarding.step_completed` event. */
+    stepCompleted(userId, step, timestamp) {
+        return this.track({ userId, event: "onboarding.step_completed", properties: { step }, timestamp });
+    }
+    /** Send everything queued. Resolves with one result per request. */
+    async flush() {
+        this.clearTimer();
+        const results = [];
+        while (this.queue.length > 0) {
+            const batch = this.queue.splice(0, MAX_BATCH);
+            results.push(await this.send(batch));
+        }
+        return results;
+    }
+    /** Flush and stop the background timer (call on shutdown). */
+    async close() {
+        return this.flush();
+    }
+    enqueue(msg) {
+        this.queue.push(msg);
+        if (this.queue.length >= this.flushAt) {
+            void this.flush().catch((err) => this.onError?.(err));
+        }
+        else if (this.flushIntervalMs > 0 && !this.timer) {
+            this.timer = setTimeout(() => {
+                this.timer = null;
+                void this.flush().catch((err) => this.onError?.(err));
+            }, this.flushIntervalMs);
+            this.timer.unref?.();
+        }
+        return msg.messageId;
+    }
+    clearTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+    async send(batch) {
+        const body = JSON.stringify({ batch });
+        for (let attempt = 0;; attempt += 1) {
+            // Sign every attempt afresh: the timestamp must stay inside the 5-minute window.
+            const ts = Math.floor(Date.now() / 1000);
+            let res;
+            try {
+                res = await this.fetchImpl(this.endpoint, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        [HEADERS.keyId]: this.keyId,
+                        [HEADERS.timestamp]: String(ts),
+                        [HEADERS.signature]: sign(this.secret, "events", ts, body),
+                    },
+                    body,
+                });
+            }
+            catch (err) {
+                if (attempt >= this.maxRetries)
+                    throw err;
+                await backoff(attempt);
+                continue;
+            }
+            if (res.status === 202 || res.ok)
+                return (await res.json());
+            const retryable = res.status === 429 || res.status >= 500;
+            if (!retryable || attempt >= this.maxRetries) {
+                const data = await res.json().catch(() => undefined);
+                const code = data?.error ?? `http_${res.status}`;
+                throw new YouGrowError(`YouGrow ingest failed: ${code}`, res.status, data);
+            }
+            await backoff(attempt, res.headers.get("retry-after"));
+        }
+    }
+}
+function iso(t) {
+    if (t === undefined)
+        return new Date().toISOString();
+    return typeof t === "string" ? t : t.toISOString();
+}
+/** Exponential backoff with full jitter; honours Retry-After (seconds). */
+function backoff(attempt, retryAfter) {
+    const hinted = retryAfter && /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1000 : 0;
+    const ms = hinted || Math.random() * Math.min(500 * 2 ** attempt, 10_000);
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/jwt.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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
+ *
+ * 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;
+    rawBody: string;
+    nowMs?: number;
+}): JwtResult;

package/dist/jwt.js

@@ -0,0 +1,74 @@
+import { createHash, createPublicKey, verify as cryptoVerify } from "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;
+    }
+}
+export 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. */
+export function tokenKid(token) {
+    const header = decodeJson(token.split(".")[0] ?? "");
+    return header && typeof header.kid === "string" ? header.kid : null;
+}
+export 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 = createPublicKey({ key: { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y }, format: "jwk" });
+        valid =
+            signature.length === 64 &&
+                cryptoVerify("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 hash = createHash("sha256").update(input.rawBody, "utf8").digest("base64url");
+    if (c.body_sha256 !== hash)
+        return { ok: false, reason: "body_mismatch" };
+    return { ok: true, claims: c };
+}

package/dist/server.d.ts

@@ -0,0 +1,108 @@
+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, before parsing it.
+ *
+ *   const verifier = createVerifier({ keyId: process.env.YOUGROW_KEY_ID! });
+ *   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";
+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";
+};
+export interface VerifierOptions {
+    /** Your connection's key id — the token's audience. */
+    keyId: string;
+    /** YouGrow's origin. Defaults to https://yougrow.ai; use the dev origin for staging. */
+    issuer?: string;
+    /** Pin the key set instead of fetching it (tests, air-gapped setups). */
+    jwks?: {
+        keys: Jwk[];
+    };
+    fetch?: typeof fetch;
+}
+export interface Verifier {
+    verify(input: {
+        headers: HeaderBag;
+        rawBody: string;
+        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;

package/dist/server.js

@@ -0,0 +1,121 @@
+import { tokenFromAuthorization, tokenKid, verifyJwt } from "./jwt.js";
+export const DEFAULT_ISSUER = "https://yougrow.ai";
+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 (typeof h.get === "function")
+        return h.get(name);
+    const bag = h;
+    const v = bag[name] ?? bag[name.toLowerCase()];
+    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.
+ */
+export function createVerifier(opts) {
+    const issuer = (opts.issuer ?? DEFAULT_ISSUER).replace(/\/+$/, "");
+    if (!opts.jwks && !/^https:\/\//.test(issuer) && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(issuer)) {
+        throw new Error("createVerifier: issuer 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) {
+            const token = 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 ? 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 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.
+ */
+export 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/signing.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Request signing for events your product sends to YouGrow:
+ *
+ *   X-YouGrow-Signature: v1=<hex HMAC-SHA256(secret, `events:${timestamp}.${rawBody}`)>
+ *
+ * Timestamps are unix seconds; requests more than five minutes off are refused.
+ * Pinned by test/vectors.json.
+ *
+ * Requests YouGrow sends YOU (context pulls, webhooks) are not signed with your
+ * secret: they carry a JWT signed with YouGrow's own key. Verify those with
+ * `createVerifier` from "@yougrowai/node/server".
+ */
+export type Direction = "events";
+export declare const HEADERS: {
+    readonly keyId: "x-yougrow-key-id";
+    readonly timestamp: "x-yougrow-timestamp";
+    readonly signature: "x-yougrow-signature";
+};
+export declare function sign(secret: string, direction: Direction, timestampSec: number, rawBody: string): string;

package/dist/signing.js

@@ -0,0 +1,10 @@
+import { createHmac } from "node:crypto";
+export const HEADERS = {
+    keyId: "x-yougrow-key-id",
+    timestamp: "x-yougrow-timestamp",
+    signature: "x-yougrow-signature",
+};
+export function sign(secret, direction, timestampSec, rawBody) {
+    const mac = createHmac("sha256", secret).update(`${direction}:${timestampSec}.${rawBody}`).digest("hex");
+    return `v1=${mac}`;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@yougrowai/node",
+  "version": "0.1.0",
+  "description": "Send your product's user events to YouGrow lifecycle journeys, and answer its signed context and webhook requests.",
+  "license": "MIT",
+  "author": "YouGrow.AI Limited",
+  "homepage": "https://github.com/ygai-jezl/vizzyblmrkt/tree/main/sdk/node#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ygai-jezl/vizzyblmrkt.git",
+    "directory": "sdk/node"
+  },
+  "keywords": ["yougrow", "lifecycle-email", "onboarding", "events", "webhooks", "jwks"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./server": { "types": "./dist/server.d.ts", "default": "./dist/server.js" }
+  },
+  "files": ["dist", "test/vectors.json", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  }
+}

package/test/vectors.json

@@ -0,0 +1,69 @@
+{
+  "description": "Signing vectors for the YouGrow product-connection protocol. 'vectors': product -> platform events, signature = 'v1=' + hex(HMAC-SHA256(secret, 'events:' + timestamp + '.' + body)), generated with openssl. 'outbound': platform -> product ES256 JWTs (context pulls, webhooks), signed once with a throwaway P-256 key whose private half was discarded; only the public JWK is kept. Both the server and the SDK test suites must accept every outbound token at nowMs and reject the listed tamperings.",
+  "vectors": [
+    {
+      "secret": "ygs_test_secret_one",
+      "direction": "events",
+      "timestamp": 1758455000,
+      "body": "{\"batch\":[{\"type\":\"identify\",\"messageId\":\"m1\",\"userId\":\"u1\",\"timestamp\":\"2026-09-21T10:00:00Z\",\"traits\":{\"email\":\"alex@acme.test\"}}]}",
+      "signature": "v1=d4bdf726960d10a135b3493f4074b3d3d3773a23ec49955d6efb720bcd2ef914"
+    },
+    {
+      "secret": "ygs_test_secret_two",
+      "direction": "events",
+      "timestamp": 1758455123,
+      "body": "{\"batch\":[{\"type\":\"track\",\"messageId\":\"m2\",\"userId\":\"ü-用户\",\"timestamp\":\"2026-09-21T10:00:00+01:00\",\"event\":\"user.signed_up\"}]}",
+      "signature": "v1=fadcda4cd874e1ad19b1f7059cca902b54afdfe9032c10dcfdffa75cc450b317"
+    },
+    {
+      "secret": "ygs_test_secret_one",
+      "direction": "events",
+      "timestamp": 1758455000,
+      "body": "",
+      "signature": "v1=aae9033d246c64b2e62a630910f59e35531cfb71d5b1a4da90a1002323979eae"
+    }
+  ],
+  "outbound": {
+    "issuer": "https://yougrow.ai",
+    "audience": "ygk_vectorsvectorsvectors0",
+    "nowMs": 1758455060000,
+    "jwks": {
+      "keys": [
+        {
+          "kty": "EC",
+          "crv": "P-256",
+          "x": "-QAJ7DPGd56eA18mz_P75umV_83b9gcmDJeh1CRhlZc",
+          "y": "N8BGeFW7xO2eAGQKykRfbc2j-M-F-uz52LgY2zmkpoY",
+          "kid": "5xivU6qt3oe7kdhSXWNXkkRwxoB3J-N4Mn1OGMN2KH4",
+          "alg": "ES256",
+          "use": "sig"
+        }
+      ]
+    },
+    "tokens": [
+      {
+        "direction": "context",
+        "body": "{\"userId\":\"u1\",\"purpose\":\"test\",\"requestId\":\"r1\"}",
+        "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjV4aXZVNnF0M29lN2tkaFNYV05Ya2tSd3hvQjNKLU40TW4xT0dNTjJLSDQifQ.eyJpc3MiOiJodHRwczovL3lvdWdyb3cuYWkiLCJhdWQiOiJ5Z2tfdmVjdG9yc3ZlY3RvcnN2ZWN0b3JzMCIsImlhdCI6MTc1ODQ1NTAwMCwiZXhwIjoxNzU4NDU1MzAwLCJqdGkiOiJyMSIsImRpciI6ImNvbnRleHQiLCJib2R5X3NoYTI1NiI6InZpMzRxQ0FaMGhHSFNrZ2lhbzZxUGlDYW5RdWJjZFhDX1FraU40RHpfM0EifQ.bvJgcsxbVfjbdGOqwVpVUmQy4Pcchh0lErXTIRFbQYRVFi2imw_SzEzyFvVEPRVILl1mFYnL4fQNyCMkjW_gTg"
+      },
+      {
+        "direction": "webhook",
+        "body": "{\"id\":\"wh_1\",\"type\":\"email_preferences.updated\",\"createdAt\":\"2026-09-21T10:00:00Z\",\"data\":{\"userId\":\"u1\",\"category\":\"onboarding\",\"subscribed\":false}}",
+        "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjV4aXZVNnF0M29lN2tkaFNYV05Ya2tSd3hvQjNKLU40TW4xT0dNTjJLSDQifQ.eyJpc3MiOiJodHRwczovL3lvdWdyb3cuYWkiLCJhdWQiOiJ5Z2tfdmVjdG9yc3ZlY3RvcnN2ZWN0b3JzMCIsImlhdCI6MTc1ODQ1NTAwMCwiZXhwIjoxNzU4NDU1MzAwLCJqdGkiOiJ3aF8xIiwiZGlyIjoid2ViaG9vayIsImJvZHlfc2hhMjU2IjoiNjdCLWRsN1hXQTRmRkZyU3VLSkNsZGViWjJQZUJlUEZUbTlDdE5UR1pjWSJ9.DmVqL1DHK8kzNpeHmgJ3pUIQPLBkWoIVkSze88eEe2uYaapz2igRBGA6fXVPLALLi1j1vrJgUOtC9F7AHxAuRw"
+      }
+    ],
+    "der": {
+      "message": "kms-der-vector",
+      "der": "MEYCIQDWzM6yGiXD+ByzGupa6bgWJSjRcyPZKgs9iLoIaIVs8QIhAO4ufgQ9yvfciUelapmJ4N6eM7HWIDmAsYwn3DjRKE3X",
+      "publicJwk": {
+        "kty": "EC",
+        "crv": "P-256",
+        "x": "-QAJ7DPGd56eA18mz_P75umV_83b9gcmDJeh1CRhlZc",
+        "y": "N8BGeFW7xO2eAGQKykRfbc2j-M-F-uz52LgY2zmkpoY",
+        "kid": "5xivU6qt3oe7kdhSXWNXkkRwxoB3J-N4Mn1OGMN2KH4",
+        "alg": "ES256",
+        "use": "sig"
+      }
+    }
+  }
+}