@vxil/sdk 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -802,6 +802,11 @@ export interface JobRunEventPayload {
     attempt: number;
     level?: 'error';
     state?: 'broken';
+    /** `job.dead_lettered` only, and only when something other than the
+     *  executor killed the run: `reaped` (the stuck-run reaper) or
+     *  `queue_backstop` (the queue's own retries ran out). Absent when the run
+     *  exhausted its attempts normally. */
+    reason?: 'reaped' | 'queue_backstop';
 }
 /** Event name → typed `data`, for the events that settle work you started.
  *  `VxilEventPayload<'job.generation.failed'>` names one; everything else on
@@ -814,6 +819,121 @@ export interface VxilEventPayloads {
     'job.dead_lettered': JobRunEventPayload;
 }
 export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
+/** The `trigger` label on the envelope. The config spells two of them in
+ *  camelCase (`cmsHook`, `authHook`); on the wire they are kebab-case. */
+export type FunctionEnvelopeTrigger = 'http' | 'cms-hook' | 'auth-hook' | 'queue' | 'cron' | 'webhook';
+/** The audiences a function's scoped callback tokens are minted for — one per
+ *  feature its declared scopes reach. `control-plane` carries `users:*` /
+ *  `usage:read` only. There is deliberately no `functions` audience: a function
+ *  cannot call another function. */
+export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane';
+/** One short-lived scoped token per audience your scopes imply
+ *  (`env.scoped_jwts.cms`, `env.scoped_jwts['control-plane']`); an audience your
+ *  scopes do not reach is absent. Send it as `Authorization: Bearer …` to
+ *  `vxil_base`. */
+export type FunctionScopedJwts = {
+    [A in FunctionCallbackAudience]?: string;
+};
+/** The verified end-user an `http` invocation carries when the caller presented
+ *  a vxil-auth session. */
+export interface FunctionEndUser {
+    id: string;
+    sid: string;
+    /** the step-up epoch, when the session has one */
+    elv?: number;
+}
+/** The fields every invocation carries, whatever fired it. */
+export interface FunctionEnvelopeBase {
+    tenant_id: string;
+    request_id: string;
+    /** Stable across redeliveries of the same event: delivery is at-least-once,
+     *  so dedupe your writes on it. */
+    idempotency_key: string;
+    /** The edge to call vxil back through. */
+    vxil_base: string;
+    scoped_jwts: FunctionScopedJwts;
+    /** Your declared per-function secrets (`secrets: ['secret:<name>']`), keyed by
+     *  bare name and resolved at invoke time. */
+    secrets: Record<string, string>;
+}
+/** `payload` of a `cms-hook` invocation. It carries no field values: re-read
+ *  the item by `item_id`. */
+export interface CmsHookTriggerPayload {
+    /** `cms.item.created` or `cms.item.updated` for a binding that names a
+     *  collection; a binding without one also sees the other `cms.item.*` events */
+    event: string;
+    collection: string;
+    item_id: string;
+}
+/** `payload` of an `auth-hook` invocation: the event's own fields plus
+ *  `event`. `auth.user.created` → `{ user_id, method, is_anonymous }`;
+ *  `auth.session.created` → `{ user_id, session_id }`; `auth.session.revoked`
+ *  adds `reason`; `auth.signin.failure` → `{ email_hash | user_id, reason }`. */
+export interface AuthHookTriggerPayload {
+    event: string;
+    user_id?: string;
+    [field: string]: unknown;
+}
+/** `payload` of a `webhook` invocation: one platform event under the binding's
+ *  `source` prefix. `D` is the event's own payload (see `VxilEventPayload`). */
+export interface WebhookTriggerPayload<D = Record<string, unknown>> {
+    event: string;
+    audit_id: number | null;
+    occurred_at: string | null;
+    actor: string | null;
+    surface: string | null;
+    /** the event's payload; `{ truncated: true }` when it was larger than the
+     *  function's webhook payload bound, null when the event carried none */
+    data: D | {
+        truncated: true;
+    } | null;
+}
+/** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
+ *  parameters on a GET). */
+export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
+    trigger: 'http';
+    /** present only when the caller presented a verified end-user session */
+    end_user?: FunctionEndUser;
+    payload: P;
+}
+export interface CmsHookFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'cms-hook';
+    payload: CmsHookTriggerPayload;
+}
+export interface AuthHookFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'auth-hook';
+    payload: AuthHookTriggerPayload;
+}
+/** `payload` is exactly what the job was enqueued with. */
+export interface QueueFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
+    trigger: 'queue';
+    payload: P;
+}
+/** A schedule tick carries no data: `payload` is `{}`. */
+export interface CronFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'cron';
+    payload: Record<string, unknown>;
+}
+export interface WebhookFunctionEnvelope<D = Record<string, unknown>> extends FunctionEnvelopeBase {
+    trigger: 'webhook';
+    payload: WebhookTriggerPayload<D>;
+}
+/** The invocation envelope, discriminated on `trigger`. `P` types the `http`
+ *  body and the `queue` payload. A function bound to one trigger can name its
+ *  member directly (`CmsHookFunctionEnvelope`, `WebhookFunctionEnvelope<D>`). */
+export type FunctionEnvelope<P = unknown> = HttpFunctionEnvelope<P> | CmsHookFunctionEnvelope | AuthHookFunctionEnvelope | QueueFunctionEnvelope<P> | CronFunctionEnvelope | WebhookFunctionEnvelope;
+/** The body the jobs engine POSTs to a run's `target_url` (signed with
+ *  `X-Vxil-Jobs-Signature`; verify it with the secret from
+ *  `jobs.signingSecret()`). Redelivered attempts carry the same `run_id` and a
+ *  higher `attempt`. */
+export interface JobDelivery<P = unknown> {
+    run_id: string;
+    job_name: string;
+    /** 1-based */
+    attempt: number;
+    /** exactly what the run was enqueued with */
+    payload: P;
+}
 /** A re-minted mid-stream connect token (GET /v1/ai/generations/{id}/token). */
 export interface AiStreamToken {
     generation_id: string;
@@ -2616,6 +2736,34 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 user_id: string;
                 session: AuthSession;
             }>;
+            /** Keep a session pair usable: when it expires within `skewSeconds`
+             *  (default 300) — or `expires_at` is missing/unparseable, or already past
+             *  — rotate it through `refresh` and return the NEW pair with
+             *  `refreshed: true`; otherwise return it unchanged, with no request.
+             *  Store the pair again whenever `refreshed` is true (the old refresh
+             *  token is revoked by the rotation).
+             *
+             *  The window is capped at half the token's own lifetime (iat→exp, read
+             *  from the session JWT; 60 s for an opaque token), so a short session
+             *  TTL never makes every call rotate. Concurrent calls for the same
+             *  refresh token in one process share ONE rotation, and for 30 s after it
+             *  settles a call still carrying the OLD pair gets the new pair (no second
+             *  request) while a call with the just-minted pair gets it back unchanged.
+             *  A refresh that fails (revoked, expired, or already rotated by another
+             *  process) throws the `VxilError` — treat it as "sign in again".
+             *
+             *  Call it on a client whose key carries `auth:signin` — normally the
+             *  sign-in key, in server mode. An end-user-mode client sends its
+             *  X-Vxil-End-User token with the rotation only while that token is the
+             *  pair's own and still has 10 s left; otherwise the rotation goes out
+             *  without it, which a thin-client (`end_user_required`) key cannot do.
+             *  See https://vxil.com/docs/guide/09-security-and-multitenancy. */
+            ensureFresh: (pair: AuthSession, opts?: {
+                skewSeconds?: number;
+            }) => Promise<{
+                session: AuthSession;
+                refreshed: boolean;
+            }>;
             revoke: (token: string) => Promise<void>;
             /** "Sign out everywhere": revoke EVERY live session of a user in one call
              *  (one statement, one batched edge-cache write; each session's

package/dist/index.js

@@ -50,6 +50,69 @@ export class VxilError extends Error {
 /** The run states no later write can move — what `waitForRun` and an
  *  async+wait invoke resolve `done: true` on. */
 export const JOB_TERMINAL_STATES = new Set(['succeeded', 'failed', 'dead', 'cancelled']);
+/** `vx.auth.sessions.ensureFresh` rotates a pair this many seconds before it
+ *  expires unless the call names its own `skewSeconds`. */
+const ENSURE_FRESH_SKEW_SECONDS = 300;
+/** The window never exceeds this fraction of the token's own lifetime (iat→exp
+ *  from the session JWT), so a short session TTL cannot make every call rotate. */
+const ENSURE_FRESH_MAX_WINDOW_FRACTION = 0.5;
+/** Cap for a token whose lifetime cannot be read (an opaque, non-JWT token). */
+const ENSURE_FRESH_OPAQUE_MAX_SKEW_SECONDS = 60;
+/** An end-user-mode client keeps its X-Vxil-End-User token on the rotation
+ *  while that token has at least this long left (a thin-client key has no
+ *  server-mode fallback at the edge); closer to expiry it rotates in server mode. */
+const ENSURE_FRESH_HEADER_MARGIN_MS = 10_000;
+/** A settled rotation stays readable this long: a request that arrives just
+ *  after the winner still carrying the OLD pair adopts the winner's pair
+ *  instead of re-sending a revoked refresh token, and a pair this process just
+ *  minted is never rotated again inside the window (bounds rotations to one
+ *  per window per session per process whatever the clocks say). */
+const ENSURE_FRESH_GRACE_MS = 30_000;
+/** Rotations keyed by (edge base, OLD refresh token), shared by every client in
+ *  the process. `until` is Infinity while in flight and settle-time + grace
+ *  after a success; a failure is dropped at once. */
+const refreshRotations = new Map();
+/** (edge base, NEW refresh token) → the time until which that just-minted pair
+ *  is returned unchanged even if it already looks due. */
+const refreshJustMinted = new Map();
+function sweepRefreshCaches(now) {
+    for (const [k, r] of refreshRotations)
+        if (r.until <= now)
+            refreshRotations.delete(k);
+    for (const [k, until] of refreshJustMinted)
+        if (until <= now)
+            refreshJustMinted.delete(k);
+}
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/** iat→exp of a session JWT in seconds, read WITHOUT verification (it only
+ *  schedules the refresh); undefined for an opaque or malformed token. No
+ *  atob: the SDK also runs on React Native builds that lack it. */
+function sessionLifetimeSeconds(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts[1] || parts[1].length > 8192)
+        return undefined;
+    let acc = 0;
+    let bits = 0;
+    let json = '';
+    for (const ch of parts[1].replace(/=+$/, '')) {
+        const v = B64URL.indexOf(ch);
+        if (v < 0)
+            return undefined;
+        acc = ((acc << 6) | v) & 0xffff;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            json += String.fromCharCode((acc >> bits) & 0xff);
+        }
+    }
+    try {
+        const p = JSON.parse(json);
+        if (typeof p.iat === 'number' && typeof p.exp === 'number' && p.exp > p.iat)
+            return p.exp - p.iat;
+    }
+    catch { /* not a JWT payload */ }
+    return undefined;
+}
 const DEFAULT_BASE = 'https://api.vxil.com';
 /** Normalize the `expand` option to the `$expand` query value: a comma-joined
  *  list (the server's spelling), or `undefined` when nothing is expanded so the
@@ -788,6 +851,69 @@ export class Vxil {
             verify: async (token) => (await this.call('POST', '/v1/auth/sessions/verify', { token })).data,
             /** Rotates the refresh token: store the returned pair, discard the old one. */
             refresh: async (refreshToken) => (await this.call('POST', '/v1/auth/sessions/refresh', { refresh_token: refreshToken })).data,
+            /** Keep a session pair usable: when it expires within `skewSeconds`
+             *  (default 300) — or `expires_at` is missing/unparseable, or already past
+             *  — rotate it through `refresh` and return the NEW pair with
+             *  `refreshed: true`; otherwise return it unchanged, with no request.
+             *  Store the pair again whenever `refreshed` is true (the old refresh
+             *  token is revoked by the rotation).
+             *
+             *  The window is capped at half the token's own lifetime (iat→exp, read
+             *  from the session JWT; 60 s for an opaque token), so a short session
+             *  TTL never makes every call rotate. Concurrent calls for the same
+             *  refresh token in one process share ONE rotation, and for 30 s after it
+             *  settles a call still carrying the OLD pair gets the new pair (no second
+             *  request) while a call with the just-minted pair gets it back unchanged.
+             *  A refresh that fails (revoked, expired, or already rotated by another
+             *  process) throws the `VxilError` — treat it as "sign in again".
+             *
+             *  Call it on a client whose key carries `auth:signin` — normally the
+             *  sign-in key, in server mode. An end-user-mode client sends its
+             *  X-Vxil-End-User token with the rotation only while that token is the
+             *  pair's own and still has 10 s left; otherwise the rotation goes out
+             *  without it, which a thin-client (`end_user_required`) key cannot do.
+             *  See https://vxil.com/docs/guide/09-security-and-multitenancy. */
+            ensureFresh: async (pair, opts = {}) => {
+                const skew = opts.skewSeconds ?? ENSURE_FRESH_SKEW_SECONDS;
+                if (typeof skew !== 'number' || !Number.isFinite(skew) || skew < 0) {
+                    throw new VxilError(0, 'invalid_argument', 'ensureFresh: skewSeconds must be a finite number ≥ 0.');
+                }
+                const now = Date.now();
+                const key = `${this.base}\n${pair.refresh_token}`;
+                // A pair this process already rotated (or is rotating): its tokens are
+                // revoked, so the answer is the winner's pair whatever expires_at says.
+                const prior = pair.refresh_token ? refreshRotations.get(key) : undefined;
+                if (prior && prior.until > now)
+                    return { session: await prior.session, refreshed: true };
+                const lifetime = sessionLifetimeSeconds(pair.token);
+                const window = lifetime !== undefined
+                    ? Math.min(skew, lifetime * ENSURE_FRESH_MAX_WINDOW_FRACTION)
+                    : Math.min(skew, ENSURE_FRESH_OPAQUE_MAX_SKEW_SECONDS);
+                const expMs = Date.parse(pair.expires_at);
+                if (Number.isFinite(expMs) && expMs - now > window * 1000)
+                    return { session: pair, refreshed: false };
+                if (pair.refresh_token && (refreshJustMinted.get(key) ?? 0) > now)
+                    return { session: pair, refreshed: false };
+                if (!pair.refresh_token) {
+                    throw new VxilError(0, 'refresh_token_missing', 'ensureFresh: the session is due for refresh but the pair carries no refresh_token.', 'Store both halves of the pair a sign-in returns (token + refresh_token), or sign in again.');
+                }
+                const keepEndUser = this.endUserToken !== undefined && this.endUserToken === pair.token
+                    && Number.isFinite(expMs) && expMs - now >= ENSURE_FRESH_HEADER_MARGIN_MS;
+                const client = this.endUserToken && !keepEndUser ? this.asEndUser(undefined) : this;
+                sweepRefreshCaches(now);
+                const entry = {
+                    session: client.call('POST', '/v1/auth/sessions/refresh', { refresh_token: pair.refresh_token }).then((r) => r.data.session),
+                    until: Number.POSITIVE_INFINITY,
+                };
+                entry.session.then((fresh) => {
+                    entry.until = Date.now() + ENSURE_FRESH_GRACE_MS;
+                    if (fresh.refresh_token)
+                        refreshJustMinted.set(`${this.base}\n${fresh.refresh_token}`, entry.until);
+                }, () => { if (refreshRotations.get(key) === entry)
+                    refreshRotations.delete(key); });
+                refreshRotations.set(key, entry);
+                return { session: await entry.session, refreshed: true };
+            },
             revoke: async (token) => {
                 await this.call('POST', '/v1/auth/sessions/revoke', { token });
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",