@foir/sdk 0.30.0 → 0.31.0

package/dist/server/operation-types.d.ts

@@ -83,28 +83,21 @@ export interface OperationContinuationBlock {
 }
 /**
  * Callback context the platform hands the endpoint when it dispatches an
- * ASYNC operation. Everything the endpoint needs to call back is here: the
- * address, the token, the key this run signs with, and the per-operation
- * mutation names, so the endpoint derives none of them from the operation key.
+ * ASYNC operation. Everything the endpoint needs to reply is here: where, the
+ * token, and the key this run signs with.
  */
 export interface OperationCallback {
     /**
-     * The address to report to, e.g. https://api.foir.dev/graphql. Empty when the
+     * Where the run replies: its own reply route, e.g.
+     * https://api.foir.dev/v1/steps/<executionId>/reply. Empty when the
      * platform that dispatched has no public address of its own configured;
-     * `createCallbackClient` then reports to the `apiUrl` it is given.
+     * `createCallbackClient` then replies at the `apiUrl` it is given.
      */
-    gqlEndpoint: string;
+    endpoint: string;
     /** Bearer token for the Authorization header (Ed25519, single execution scope) */
     token: string;
     /** RFC3339 expiry — extensions can short-circuit work past this. */
     expiresAt: string;
-    /** Per-op typed mutation names the extension should call back with. */
-    mutations: {
-        complete: string;
-        fail: string;
-        progress: string;
-        cancel: string;
-    };
     /**
      * The operation keys that led to this run, its own last. Present when the
      * run was caused by another operation's work.

package/dist/server.js

@@ -730,8 +730,11 @@ function stepUpRequired(error) {
   if (!(error instanceof FoirRequestError)) return null;
   for (const item of error.graphQLErrors ?? []) {
     if (item.extensions?.code !== "STEP_UP_REQUIRED") continue;
-    const asked = item.extensions.stepUp;
-    if (asked === "second_factor" || asked === "sign_in_method") return asked;
+    const kind = item.extensions.stepUp;
+    if (kind === "proof" || kind === "second_factor" || kind === "sign_in_method") {
+      const url = item.extensions.stepUpUrl;
+      return { kind, url: typeof url === "string" && url !== "" ? url : null };
+    }
   }
   return null;
 }
@@ -952,131 +955,96 @@ async function withFoirRetry(fn, policy = {}) {
   }
 }
 
+// src/runs/step-reply.ts
+async function replyToStep(reply, body, opts = {}) {
+  if (!reply?.token || !reply.signingKey || !reply.endpoint) {
+    throw new Error("replyToStep: the step was handed no reply, so it cannot answer");
+  }
+  return sendReply(reply.endpoint, reply.token, reply.signingKey, body, opts);
+}
+async function sendReply(endpoint, token, signingKey, body, opts = {}) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  if (!fetchImpl) throw new Error("replyToStep: no fetch available; pass opts.fetch on runtimes without a global fetch");
+  const payload = JSON.stringify(body);
+  const signature = await hmacSha256Hex(signingKey, payload);
+  return withFoirRetry(async () => {
+    let resp;
+    try {
+      resp = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+          "X-Foir-Signature": `sha256=${signature}`
+        },
+        body: payload,
+        ...opts.signal ? { signal: opts.signal } : {}
+      });
+    } catch (err) {
+      if (opts.signal?.aborted) throw err;
+      throw new FoirRequestError("the reply got no answer", { cause: err });
+    }
+    if (!resp.ok) {
+      throw new FoirRequestError(`the reply was refused with HTTP ${resp.status}: ${await resp.text()}`, { status: resp.status });
+    }
+    const out = await resp.json();
+    if (!out || typeof out.status !== "string") {
+      throw new FoirRequestError("the reply was answered with nothing", { status: resp.status });
+    }
+    return { status: out.status, cancelled: out.cancelled === true, applied: out.applied === true };
+  }, opts.retry);
+}
+async function hmacSha256Hex(secret, body) {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
 // src/server/callback-client.ts
 function createCallbackClient(callback, opts) {
   const { executionId } = opts;
-  const fetchImpl = opts.fetch ?? globalThis.fetch;
-  if (!fetchImpl) {
-    throw new Error(
-      "createCallbackClient: no fetch available; pass opts.fetch on runtimes without a global fetch"
-    );
-  }
   if (!executionId) throw new Error("createCallbackClient: executionId is required");
-  if (!callback?.token || !callback?.mutations) {
+  if (!callback?.token) {
     throw new Error("createCallbackClient: callback block is missing required fields");
   }
-  if (!callback.gqlEndpoint && !opts.apiUrl) {
+  if (!callback.endpoint && !opts.apiUrl) {
     throw new Error(
-      "createCallbackClient: nowhere to report to. The dispatch named no callback.gqlEndpoint and no apiUrl was passed."
+      "createCallbackClient: nowhere to reply. The dispatch named no callback.endpoint and no apiUrl was passed."
     );
   }
-  const endpoint = callback.gqlEndpoint || foirApiEndpoint(opts.apiUrl ?? "", "/graphql");
+  const endpoint = callback.endpoint || foirApiEndpoint(opts.apiUrl ?? "", `/v1/steps/${encodeURIComponent(executionId)}/reply`);
   const signingSecret = opts.signingSecret || callback.signingKey;
   if (!signingSecret) {
     throw new Error(
       "createCallbackClient: nothing to sign with. The dispatch carried no callback.signingKey and no signingSecret was passed."
     );
   }
-  const post = async (mutationName, fields, variables) => {
-    const query = `mutation ${mutationName}Mutation($id: String!${fieldArgsForMutation(mutationName, variables)}) { ${mutationName}(id: $id${fieldArgsCallSite(mutationName, variables)}) { ${fields} } }`;
-    const body = JSON.stringify({
-      query,
-      variables: { id: executionId, ...variables }
-    });
-    const signature = await hmacSha256Hex(signingSecret, body);
-    return withFoirRetry(async () => {
-      let resp;
-      try {
-        resp = await fetchImpl(endpoint, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${callback.token}`,
-            "X-Foir-Signature": `sha256=${signature}`
-          },
-          body,
-          ...opts.signal ? { signal: opts.signal } : {}
-        });
-      } catch (err) {
-        if (opts.signal?.aborted) throw err;
-        throw new FoirRequestError(`callback ${mutationName} got no answer`, { cause: err });
-      }
-      if (!resp.ok) {
-        throw new FoirRequestError(
-          `callback ${mutationName} failed with HTTP ${resp.status}: ${await resp.text()}`,
-          { status: resp.status }
-        );
-      }
-      const json = await resp.json();
-      if (json.errors?.length) {
-        throw new FoirRequestError(`callback ${mutationName} GraphQL error: ${json.errors[0].message}`, {
-          status: resp.status,
-          graphQLErrors: json.errors
-        });
-      }
-      const out = json.data?.[mutationName];
-      if (!out) {
-        throw new FoirRequestError(`callback ${mutationName} returned no data`, { status: resp.status });
-      }
-      return out;
-    }, opts.retry);
-  };
+  const send = (body) => sendReply(endpoint, callback.token, signingSecret, body, {
+    ...opts.fetch ? { fetch: opts.fetch } : {},
+    ...opts.retry ? { retry: opts.retry } : {},
+    ...opts.signal ? { signal: opts.signal } : {}
+  });
   return {
-    complete: (result) => post(callback.mutations.complete, "status cancelled", { result }),
-    fail: (code, message, options = {}) => post(callback.mutations.fail, "status cancelled", {
-      code,
-      message,
-      retryable: options.retryable,
-      details: options.details
+    complete: (result) => send({ result: result ?? null }),
+    fail: (code, message, options = {}) => send({
+      failure: {
+        code,
+        message,
+        ...options.retryable === void 0 ? {} : { retryable: options.retryable },
+        ...options.details === void 0 ? {} : { details: options.details }
+      }
     }),
-    progress: (update) => post(callback.mutations.progress, "status cancelled applied", {
-      pct: update.pct,
-      message: update.message,
-      metadata: update.metadata
+    progress: (update) => send({
+      progress: {
+        ...update.pct === void 0 ? {} : { percent: update.pct },
+        ...update.message === void 0 ? {} : { message: update.message },
+        ...update.metadata === void 0 ? {} : { metadata: update.metadata }
+      }
     }),
-    cancel: () => post(callback.mutations.cancel, "status cancelled", {})
+    cancel: () => send({ cancel: {} })
   };
 }
-function fieldArgsForMutation(mutationName, vars) {
-  const parts = [];
-  for (const key of Object.keys(vars)) {
-    if (vars[key] === void 0) continue;
-    parts.push(`, $${key}: ${graphQLTypeFor(mutationName, key)}`);
-  }
-  return parts.join("");
-}
-function fieldArgsCallSite(_mutationName, vars) {
-  const parts = [];
-  for (const key of Object.keys(vars)) {
-    if (vars[key] === void 0) continue;
-    parts.push(`, ${key}: $${key}`);
-  }
-  return parts.join("");
-}
-function graphQLTypeFor(mutationName, key) {
-  if (key === "code" || key === "message") return "String!";
-  if (key === "pct") return "Int";
-  if (key === "retryable") return "Boolean";
-  if (key === "details" || key === "metadata") return "JSON";
-  if (key === "result") {
-    const base = mutationName.replace(/^complete/, "").replace(/Execution$/, "");
-    return `${base}ExecutionResultInput!`;
-  }
-  if (key === "message") return "String";
-  return "String";
-}
-async function hmacSha256Hex(secret, body) {
-  const enc = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    enc.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
-  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
-}
 
 // src/transport/key-kind.ts
 var KEY_PREFIXES = [
@@ -1836,6 +1804,7 @@ export {
   recordsCreateModels,
   recordsReadModels,
   recordsWriteModels,
+  replyToStep,
   requireScopedToken,
   stepUpRequired,
   verifyScopedToken,

package/dist/transport/foir-http.d.ts

@@ -62,7 +62,17 @@ export type FoirErrorCode = 'INVALID_ARGUMENT' | 'NOT_FOUND' | 'ALREADY_EXISTS'
  * flow) and retry; `sign_in_method`, sign in again with a method the
  * organization the request stands in accepts.
  */
-export type FoirStepUp = 'second_factor' | 'sign_in_method';
+export type FoirStepUp = 'proof' | 'second_factor' | 'sign_in_method';
+/** A step-up a refusal asks for, and the hosted page to prove it on. */
+export interface FoirStepUpAsk {
+    kind: FoirStepUp;
+    /**
+     * Fóir's hosted step-up page, where the refusal names one: send the user
+     * there with `return_to` added to its query, and ask again when they come
+     * back. Its token is in the fragment.
+     */
+    url: string | null;
+}
 export interface FoirErrorExtensions {
     /** Stable machine-readable code. Branch on this, never on `message`. */
     code?: FoirErrorCode | string;
@@ -72,6 +82,8 @@ export interface FoirErrorExtensions {
     retryAfter?: number;
     /** On `STEP_UP_REQUIRED`: what the signed-in user must do before retrying. */
     stepUp?: FoirStepUp;
+    /** On `STEP_UP_REQUIRED`, where the refusal names one: the hosted step-up page. */
+    stepUpUrl?: string;
     [key: string]: unknown;
 }
 export interface FoirGraphQLErrorItem {
@@ -126,11 +138,13 @@ export interface FoirRateLimitSnapshot {
 }
 /**
  * What an error asks of the signed-in user before the request can succeed, or
- * null: an organization's sign-in rules turned the session away, because it
- * requires a second factor the session has not proven (`second_factor`) or does
- * not accept how the user signed in (`sign_in_method`).
+ * null: a change to their factors needs a fresh proof (`proof`), or an
+ * organization's sign-in rules turned the session away, because it requires a
+ * second factor the session has not proven (`second_factor`) or does not
+ * accept how the user signed in (`sign_in_method`). `url` is the hosted page
+ * to prove it on, where the refusal names one.
  */
-export declare function stepUpRequired(error: unknown): FoirStepUp | null;
+export declare function stepUpRequired(error: unknown): FoirStepUpAsk | null;
 export declare class FoirRequestError extends Error {
     /** HTTP status code, when the request failed at the HTTP layer. */
     readonly status?: number;
@@ -224,7 +238,7 @@ export interface FoirRequestOptions {
     /**
      * User bearer token. api-public still needs the `x-api-key` to resolve
      * the project; the bearer adds the user identity for self-scoped reads
-     * (e.g. `myProfile`). Used by `@foir/sdk/auth`'s post-login profile fetch.
+     * (e.g. `myProfile`). Used by `@foir/sdk/auth`'s signed-in profile fetch.
      */
     bearerToken?: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -186,8 +186,8 @@
     "ws": "^8.18.0",
     "y-websocket": "^3.0.0",
     "yjs": "^13.6.30",
-    "@foir/proto-ts": "0.109.0",
-    "@foir/access-vocab": "0.0.0"
+    "@foir/access-vocab": "0.0.0",
+    "@foir/proto-ts": "0.109.0"
   },
   "engines": {
     "node": ">=18.0.0"