@foir/sdk 0.9.0 → 0.11.0

package/dist/server.js

@@ -238,13 +238,93 @@ async function requireScopedToken(request, options) {
       403
     );
   }
+  const rawContext = request.headers.get(CONTEXT_HEADER);
   return {
     claims,
     subject,
-    context: parseContextHeader(request.headers.get(CONTEXT_HEADER))
+    context: parseContextHeader(rawContext),
+    // The token handed over is the one verified above, not a fresh read of the
+    // header, so the client presents exactly what this guard accepted.
+    dispatch: { token: () => token, context: rawContext }
   };
 }
 
+// src/server/read-dispatch.ts
+var OperationPayloadError = class extends Error {
+  status;
+  constructor(message) {
+    super(message);
+    this.name = "OperationPayloadError";
+    this.status = 400;
+  }
+};
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function refuse(message) {
+  throw new OperationPayloadError(`[foir] not an operation dispatch body: ${message}`);
+}
+function requireString(from, key, where, allowEmpty = false) {
+  const value = from[key];
+  if (typeof value !== "string" || !allowEmpty && value === "") {
+    refuse(`${where}.${key} is ${describe(value)}, expected a${allowEmpty ? "" : " non-empty"} string`);
+  }
+  return value;
+}
+function describe(value) {
+  if (value === void 0) return "missing";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return `a ${typeof value}`;
+}
+async function readDispatch(request) {
+  let text;
+  try {
+    text = await request.text();
+  } catch (err) {
+    throw new OperationPayloadError(
+      `[foir] could not read the dispatch body (has something already consumed it?): ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    refuse("the body is not JSON");
+  }
+  if (!isObject(body)) refuse(`the body is ${describe(body)}, expected a JSON object`);
+  if (typeof body.executionId !== "string" || typeof body.operationKey !== "string") {
+    refuse(
+      "it has no executionId and operationKey. The platform sends the run, not the input: the caller's input is under `input`"
+    );
+  }
+  requireString(body, "executionId", "body");
+  requireString(body, "operationKey", "body");
+  const trigger = body.trigger;
+  if (!isObject(trigger)) refuse(`body.trigger is ${describe(trigger)}, expected an object`);
+  requireString(trigger, "type", "body.trigger");
+  const context = body.context;
+  if (!isObject(context)) refuse(`body.context is ${describe(context)}, expected an object`);
+  requireString(context, "tenantId", "body.context");
+  requireString(context, "projectId", "body.context");
+  requireString(context, "userId", "body.context", true);
+  requireString(context, "timestamp", "body.context");
+  if (context.customerId !== void 0) requireString(context, "customerId", "body.context");
+  const input = body.input;
+  if (input !== null && !isObject(input)) {
+    refuse(`body.input is ${describe(input)}, expected an object`);
+  }
+  const payload = { ...body, input: input ?? {} };
+  for (const block of ["content", "record", "triggerContext", "callback"]) {
+    const value = payload[block];
+    if (value === void 0) continue;
+    if (value === null) {
+      delete payload[block];
+      continue;
+    }
+    if (!isObject(value)) refuse(`body.${block} is ${describe(value)}, expected an object`);
+  }
+  return payload;
+}
+
 // src/server/callback-client.ts
 function createCallbackClient(callback, opts) {
   const { executionId, signingSecret } = opts;
@@ -351,6 +431,20 @@ var FoirRequestError = class extends Error {
   status;
   /** GraphQL errors, when the request failed with a no-data error envelope. */
   graphQLErrors;
+  /**
+   * The `data` the server did return, when a STRICT read refused a partial
+   * response. Present only on that path: without it, opting into strictness
+   * would trade a silent wrong answer for a thrown one that discards the answer,
+   * and a caller that wants to log what it nearly rendered could not.
+   */
+  partialData;
+  /**
+   * The selections the server stripped, when the refusal was a pruned document
+   * rather than a partial error. Same purpose as `partialData`: a caller that
+   * wants to log what it nearly rendered, or name the offending path in a
+   * developer-facing message, has it without re-parsing anything.
+   */
+  prunedSelections;
   cause;
   constructor(message, options) {
     super(message);
@@ -358,6 +452,8 @@ var FoirRequestError = class extends Error {
     this.cause = options?.cause;
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
+    this.partialData = options?.partialData;
+    this.prunedSelections = options?.prunedSelections;
   }
   /**
    * The code of the first error, if the response carried one.
@@ -412,16 +508,46 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
 }
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    if (input.orgUrl) {
+      headers["X-Org-Url"] = input.orgUrl;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -438,6 +564,403 @@ function foirApiEndpoint(apiUrl, path) {
   return base + path;
 }
 
+// src/data/transport.ts
+async function resolveBearerToken(config) {
+  const source = config.bearerToken;
+  if (typeof source === "function") return await source() ?? void 0;
+  return source ?? void 0;
+}
+async function resolveDispatchToken(dispatch) {
+  const token = (await dispatch.token())?.trim();
+  if (!token) {
+    throw new FoirRequestError(
+      "[foir] the dispatch token provider returned no token. A client built from a dispatch calls Foir as that operation and holds no other credential. Build it from the token the endpoint was handed: `(await requireScopedToken(request)).dispatch`."
+    );
+  }
+  return token;
+}
+async function resolveFoirAuth(config) {
+  if (config.dispatch !== void 0) {
+    return {
+      headers: buildFoirHeaders({
+        dispatchToken: await resolveDispatchToken(config.dispatch),
+        dispatchContext: config.dispatch.context ?? void 0,
+        extra: config.headers
+      })
+    };
+  }
+  const bearerToken = await resolveBearerToken(config);
+  return {
+    headers: buildFoirHeaders({
+      apiKey: config.apiKey,
+      draftChannel: config.channel === "draft",
+      bearerToken,
+      orgId: config.orgId,
+      orgUrl: config.orgUrl,
+      extra: config.headers
+    }),
+    key: { apiKey: config.apiKey, bearerToken }
+  };
+}
+
+// src/data/ws-transport.ts
+var GQL = {
+  connectionInit: "connection_init",
+  connectionAck: "connection_ack",
+  ping: "ping",
+  pong: "pong",
+  subscribe: "subscribe",
+  next: "next",
+  error: "error",
+  complete: "complete"
+};
+var SUBPROTOCOL = "graphql-transport-ws";
+var OPEN_READY_STATE = 1;
+var DEFAULT_RECONNECT = {
+  maxAttempts: Infinity,
+  initialDelayMs: 500,
+  maxDelayMs: 15e3,
+  jitter: 0.25
+};
+function foirSocketEndpoint(apiUrl) {
+  const trimmed = apiUrl.replace(/\/+$/, "").replace(/\/graphql$/, "");
+  return `${trimmed.replace(/^http/, "ws")}/graphql/ws`;
+}
+var FoirSocketTransport = class {
+  config;
+  policy;
+  registrations = /* @__PURE__ */ new Map();
+  socket = null;
+  acknowledged = false;
+  connecting = false;
+  attempt = 0;
+  nextId = 0;
+  disposed = false;
+  keepAlive = null;
+  retryTimer = null;
+  constructor(config) {
+    if (config.dispatch !== void 0) {
+      throw new FoirRequestError(
+        "[foir] a client built from a dispatch token cannot subscribe. The subscription socket authenticates an api key, an admin token or a customer bearer, and has no path for a dispatch token. Queries and mutations made as the operation go to /graphql and work as they are."
+      );
+    }
+    this.config = config;
+    this.policy = { ...DEFAULT_RECONNECT, ...config.reconnect ?? {} };
+  }
+  /**
+   * Start a subscription.
+   *
+   * Returns synchronously so a caller can hold the handle immediately, while
+   * the connect and the handshake proceed in the background. A subscription
+   * registered before the socket is acknowledged is sent the moment it is —
+   * which is the same path a reconnect takes, so the ordinary case and the
+   * recovery case exercise one piece of code.
+   */
+  subscribe(request, handlers) {
+    if (this.disposed) {
+      throw new FoirRequestError("[foir] this client has been disposed; create a new one");
+    }
+    this.nextId += 1;
+    const id = String(this.nextId);
+    this.registrations.set(id, {
+      id,
+      request,
+      handlers,
+      sent: false,
+      established: false
+    });
+    this.ensureConnected();
+    this.flush();
+    return {
+      unsubscribe: () => this.cancel(id)
+    };
+  }
+  /** Close the socket and drop every subscription. */
+  dispose() {
+    this.disposed = true;
+    this.registrations.clear();
+    this.teardownSocket(true);
+  }
+  /** Live subscription count. Exposed for tests and diagnostics. */
+  get size() {
+    return this.registrations.size;
+  }
+  // -------------------------------------------------------------------------
+  // Connection
+  // -------------------------------------------------------------------------
+  ensureConnected() {
+    if (this.disposed || this.socket || this.connecting) return;
+    this.connecting = true;
+    const factory = this.config.webSocketImpl ?? defaultWebSocketFactory();
+    const url = this.config.wsUrl ?? foirSocketEndpoint(this.config.apiUrl);
+    let socket;
+    try {
+      socket = factory(url, SUBPROTOCOL);
+    } catch (cause) {
+      this.connecting = false;
+      this.scheduleReconnect(
+        new FoirRequestError(`[foir] could not open a WebSocket to ${url}: ${String(cause)}`)
+      );
+      return;
+    }
+    this.socket = socket;
+    socket.onopen = () => {
+      void this.sendConnectionInit(socket);
+    };
+    socket.onmessage = (event) => this.receive(event.data);
+    socket.onerror = () => {
+    };
+    socket.onclose = () => this.handleClose();
+  }
+  async sendConnectionInit(socket) {
+    this.connecting = false;
+    try {
+      const { headers } = await resolveFoirAuth(this.config);
+      const { "Content-Type": _contentType, ...params } = headers;
+      const extra = await this.config.connectionParams?.() ?? {};
+      this.send(socket, {
+        type: GQL.connectionInit,
+        payload: { ...params, ...extra }
+      });
+    } catch (cause) {
+      this.failAll(
+        new FoirRequestError(`[foir] could not resolve the subscription credential: ${String(cause)}`)
+      );
+      this.teardownSocket(true);
+    }
+  }
+  handleClose() {
+    const wasAcknowledged = this.acknowledged;
+    this.teardownSocket(false);
+    if (this.disposed || this.registrations.size === 0) return;
+    for (const registration of this.registrations.values()) {
+      registration.sent = false;
+    }
+    this.scheduleReconnect(
+      new FoirRequestError(
+        wasAcknowledged ? "[foir] the subscription socket closed and could not be re-established" : "[foir] the subscription socket closed before the credential was accepted"
+      )
+    );
+  }
+  scheduleReconnect(error) {
+    if (this.disposed || this.registrations.size === 0) return;
+    if (this.attempt >= this.policy.maxAttempts) {
+      this.failAll(error);
+      return;
+    }
+    const exponent = Math.min(this.attempt, 20);
+    const base = Math.min(
+      this.policy.initialDelayMs * 2 ** exponent,
+      this.policy.maxDelayMs
+    );
+    const delay = base + base * this.policy.jitter * Math.random();
+    this.attempt += 1;
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      this.ensureConnected();
+    }, delay);
+    const timer = this.retryTimer;
+    if (typeof timer?.unref === "function") timer.unref();
+  }
+  teardownSocket(closeIt) {
+    if (this.keepAlive !== null) {
+      clearInterval(this.keepAlive);
+      this.keepAlive = null;
+    }
+    if (this.retryTimer !== null) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+    const socket = this.socket;
+    this.socket = null;
+    this.acknowledged = false;
+    this.connecting = false;
+    if (!socket) return;
+    socket.onopen = null;
+    socket.onmessage = null;
+    socket.onerror = null;
+    socket.onclose = null;
+    if (closeIt) {
+      try {
+        socket.close(1e3, "client disposed");
+      } catch {
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Frames
+  // -------------------------------------------------------------------------
+  receive(data) {
+    if (typeof data !== "string") return;
+    let message;
+    try {
+      message = JSON.parse(data);
+    } catch {
+      return;
+    }
+    switch (message.type) {
+      case GQL.connectionAck:
+        this.acknowledged = true;
+        this.attempt = 0;
+        this.startKeepAlive();
+        this.flush();
+        return;
+      case GQL.ping:
+        if (this.socket) this.send(this.socket, { type: GQL.pong });
+        return;
+      case GQL.pong:
+        return;
+      case GQL.next: {
+        const registration = message.id ? this.registrations.get(message.id) : void 0;
+        if (!registration) return;
+        const payload = message.payload;
+        const root = payload?.data;
+        if (!root) return;
+        const keys = Object.keys(root);
+        if (keys.length !== 1) return;
+        registration.handlers.onData(root[keys[0]]);
+        return;
+      }
+      case GQL.error: {
+        const error = new FoirRequestError(`[foir] subscription refused: ${describe2(message.payload)}`, {
+          graphQLErrors: graphQLErrorItems(message.payload)
+        });
+        if (!message.id) {
+          this.failAll(error);
+          this.teardownSocket(true);
+          return;
+        }
+        const registration = this.registrations.get(message.id);
+        this.registrations.delete(message.id);
+        registration?.handlers.onError?.(error);
+        this.closeIfIdle();
+        return;
+      }
+      case GQL.complete: {
+        if (!message.id) return;
+        const registration = this.registrations.get(message.id);
+        this.registrations.delete(message.id);
+        registration?.handlers.onComplete?.();
+        this.closeIfIdle();
+        return;
+      }
+      default:
+        return;
+    }
+  }
+  /**
+   * Send every registration the current socket has not yet been told about.
+   *
+   * This IS the resubscribe path. A reconnect clears `sent` on every
+   * registration and lands here, so a subscription re-established after a drop
+   * takes the same code as one opened for the first time — there is no second
+   * implementation that can be correct in one case and wrong in the other.
+   */
+  flush() {
+    const socket = this.socket;
+    if (!socket || !this.acknowledged || socket.readyState !== OPEN_READY_STATE) return;
+    for (const registration of this.registrations.values()) {
+      if (registration.sent) continue;
+      this.send(socket, {
+        id: registration.id,
+        type: GQL.subscribe,
+        payload: registration.request
+      });
+      registration.sent = true;
+      if (registration.established) {
+        registration.handlers.onReconnect?.();
+      } else {
+        registration.established = true;
+      }
+    }
+  }
+  cancel(id) {
+    const registration = this.registrations.get(id);
+    if (!registration) return;
+    this.registrations.delete(id);
+    if (this.socket && registration.sent && this.socket.readyState === OPEN_READY_STATE) {
+      this.send(this.socket, { id, type: GQL.complete });
+    }
+    this.closeIfIdle();
+  }
+  /**
+   * Close the socket once nothing is using it.
+   *
+   * A socket held open with no subscriptions is a connection the server has to
+   * keep, a keepalive timer that keeps a serverless invocation alive, and
+   * nothing in return.
+   */
+  closeIfIdle() {
+    if (this.registrations.size === 0) this.teardownSocket(true);
+  }
+  failAll(error) {
+    const registrations = [...this.registrations.values()];
+    this.registrations.clear();
+    for (const registration of registrations) {
+      registration.handlers.onError?.(error);
+    }
+  }
+  /**
+   * Client-side keepalive.
+   *
+   * The server pings on its own timer and this client answers, which is enough
+   * for the server to know the client is alive. This is the other direction:
+   * an idle subscription can sit for hours with no events, and a proxy that
+   * times out idle sockets will drop it. A periodic `ping` keeps it warm, and
+   * the pong that comes back proves the path is still there.
+   */
+  startKeepAlive() {
+    if (this.keepAlive !== null) clearInterval(this.keepAlive);
+    this.keepAlive = setInterval(() => {
+      const socket = this.socket;
+      if (!socket || socket.readyState !== OPEN_READY_STATE) return;
+      this.send(socket, { type: GQL.ping });
+    }, 2e4);
+    const timer = this.keepAlive;
+    if (typeof timer?.unref === "function") timer.unref();
+  }
+  send(socket, message) {
+    try {
+      socket.send(JSON.stringify(message));
+    } catch {
+    }
+  }
+};
+function defaultWebSocketFactory() {
+  const Impl = globalThis.WebSocket;
+  if (typeof Impl !== "function") {
+    throw new FoirRequestError(
+      "[foir] no WebSocket implementation is available in this runtime. Pass one as `webSocketImpl` \u2014 e.g. `webSocketImpl: (url, protocols) => new WebSocket(url, protocols)` from the `ws` package on Node < 22."
+    );
+  }
+  return (url, protocols) => new Impl(url, protocols);
+}
+function graphQLErrorItems(payload) {
+  const list = Array.isArray(payload) ? payload : payload == null ? [] : [payload];
+  const items = [];
+  for (const entry of list) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const { message, path, extensions } = entry;
+    if (extensions === void 0 && path === void 0) continue;
+    items.push({
+      message: typeof message === "string" ? message : describe2(entry),
+      ...Array.isArray(path) ? { path } : {},
+      ...typeof extensions === "object" && extensions !== null ? { extensions } : {}
+    });
+  }
+  return items.length > 0 ? items : void 0;
+}
+function describe2(payload) {
+  if (payload == null) return "no reason given";
+  if (typeof payload === "string") return payload;
+  if (Array.isArray(payload)) return payload.map(describe2).join("; ");
+  if (typeof payload === "object") {
+    const message = payload.message;
+    if (typeof message === "string") return message;
+  }
+  return JSON.stringify(payload);
+}
+
 // src/server/events-client.ts
 var FOIR_EVENTS_PATH = "/v1/events";
 var FOIR_EVENTS_SCOPE = "events:list.project";
@@ -486,7 +1009,7 @@ function assertOperatorKey(apiKey) {
   }
   if (!key.startsWith("sk_")) {
     throw new FoirRequestError(
-      `[foir] createEventsClient: apiKey must be an sk_ secret key (sk_ or sk_t_), got a key starting "${key.slice(0, 4)}". The event log is reachable by an sk_ api key or an admin session only.`
+      `[foir] createEventsClient: apiKey must be an sk_ secret key, got a key starting "${key.slice(0, 4)}". The event log is reachable by an sk_ api key or an admin session only.`
     );
   }
   return key;
@@ -629,7 +1152,74 @@ function createEventsClient(config) {
       after = page.nextCursor;
     }
   }
-  return { list, stream };
+  let socket = null;
+  let live = 0;
+  function subscribe(params) {
+    const { after, events, onData, onError, onComplete, onReconnect } = params;
+    socket ??= new FoirSocketTransport({
+      apiUrl: config.apiUrl,
+      apiKey,
+      ...config.headers ? { headers: config.headers } : {},
+      ...config.wsUrl ? { wsUrl: config.wsUrl } : {},
+      ...config.webSocketImpl ? { webSocketImpl: config.webSocketImpl } : {},
+      ...config.reconnect ? { reconnect: config.reconnect } : {}
+    });
+    const variables = {
+      ...after !== void 0 ? { after: readSeq(after, "after") } : {},
+      ...events && events.length > 0 ? { events } : {}
+    };
+    live += 1;
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      live -= 1;
+      if (live === 0 && socket) {
+        socket.dispose();
+        socket = null;
+      }
+    };
+    const handle = socket.subscribe(
+      { query: EVENTS_SUBSCRIPTION, variables },
+      {
+        onData: (event) => {
+          if (typeof event?.seq === "number" && event.seq > (variables.after ?? 0)) {
+            variables.after = event.seq;
+          }
+          onData(event);
+        },
+        onError: (error) => {
+          release();
+          onError?.(asEventsSocketError(error, variables.after));
+        },
+        onComplete: () => {
+          release();
+          onComplete?.();
+        },
+        ...onReconnect ? { onReconnect } : {}
+      }
+    );
+    return {
+      unsubscribe: () => {
+        handle.unsubscribe();
+        release();
+      }
+    };
+  }
+  return { list, stream, subscribe };
+}
+var EVENTS_SUBSCRIPTION = "subscription FoirEvents($after: EventSeq, $events: [String!]) {\n  events(after: $after, events: $events) {\n    id\n    seq\n    event\n    payload\n    actor { kind ref }\n    causationChain\n    createdAt\n  }\n}";
+function asEventsSocketError(error, requestedCursor) {
+  for (const item of error.graphQLErrors ?? []) {
+    if (item.extensions?.code !== "cursor_expired") continue;
+    const resumeFrom = item.extensions.resumeFrom;
+    return new FoirEventCursorExpiredError(`[foir] events: cursor expired: ${item.message}`, {
+      status: 410,
+      ...typeof resumeFrom === "number" ? { resumeFrom } : {},
+      ...requestedCursor !== void 0 ? { requestedCursor } : {}
+    });
+  }
+  return error;
 }
 export {
   FOIR_EVENTS_PATH,
@@ -637,6 +1227,7 @@ export {
   FOIR_EVENTS_SCOPE,
   FoirEventCursorExpiredError,
   FoirRequestError,
+  OperationPayloadError,
   ScopedTokenError,
   ServerClientError,
   createCallbackClient,
@@ -649,6 +1240,7 @@ export {
   isFoirUnauthenticated,
   parseContextHeader,
   parseSubject,
+  readDispatch,
   recordsReadModels,
   recordsWriteModels,
   requireScopedToken,