@foir/sdk 0.30.0 → 0.31.0

package/dist/react.js

@@ -943,7 +943,7 @@ async function fetchFoirManifest(config, options = {}) {
 
 // src/auth/ops.ts
 var AUTH_OPS = {
-  // Pre-credential reads a login screen renders itself from.
+  // Pre-credential reads a sign-in screen renders itself from.
   authConfig: "authConfig",
   authProviders: "authProviders",
   defaultAuthProvider: "defaultAuthProvider",
@@ -955,17 +955,15 @@ var AUTH_OPS = {
   // they hold. `./access` reads it.
   whoami: "whoami",
   // Methods.
-  login: "login",
+  signIn: "signIn",
   register: "register",
   requestOTP: "requestOTP",
-  loginWithOTP: "loginWithOTP",
   // Session lifecycle.
   refreshToken: "refreshToken",
-  logout: "logout",
+  signOut: "signOut",
   joinWaitlist: "joinWaitlist",
   // Password management and account lifecycle.
   requestPasswordReset: "requestPasswordReset",
-  resetPassword: "resetPassword",
   updatePassword: "updatePassword",
   deleteMyAccount: "deleteMyAccount",
   // Ending their own membership where the request stands.
@@ -979,10 +977,10 @@ var AUTH_OPS = {
   mySessions: "mySessions",
   endMySession: "endMySession",
   signOutEverywhere: "signOutEverywhere",
-  // Their email addresses: one added is kept once the code it was sent proves it.
+  // Their email addresses: one added is kept once the code it was sent comes
+  // back on the step addMyAddress answers, on its own route (proveMyAddress).
   myAddresses: "myAddresses",
   addMyAddress: "addMyAddress",
-  proveMyAddress: "proveMyAddress",
   makeMyAddressPrimary: "makeMyAddressPrimary",
   removeMyAddress: "removeMyAddress",
   // A copy of their own data.
@@ -993,10 +991,8 @@ var AUTH_OPS = {
   disconnectSignInMethod: "disconnectSignInMethod",
   // Their second factors. A change needs one proven first, by a step-up.
   myFactors: "myFactors",
-  beginStepUp: "beginStepUp",
-  completeStepUp: "completeStepUp",
+  stepUp: "stepUp",
   beginFactorEnrollment: "beginFactorEnrollment",
-  completeFactorEnrollment: "completeFactorEnrollment",
   removeFactor: "removeFactor",
   renameFactor: "renameFactor",
   makeRecoveryCodes: "makeRecoveryCodes",
@@ -1010,13 +1006,7 @@ var AUTH_OPS = {
   // Founding one. Present in a manifest only when the project opted in.
   registerOrganization: "registerOrganization",
   // External identity providers.
-  loginWithProvider: "loginWithProvider",
-  providerCallback: "providerCallback",
-  providerVerifyOTP: "providerVerifyOTP",
-  // A provider sign-in that names an address somebody already holds, waiting
-  // for the code sent to it.
-  confirmProviderLink: "confirmProviderLink",
-  resendProviderLinkCode: "resendProviderLinkCode"
+  signInWithProvider: "signInWithProvider"
 };
 function authClientConfig(env, options) {
   const apiKey = resolveFoirApiKey(env);
@@ -1076,35 +1066,101 @@ function stripUndefined(args) {
   return out;
 }
 
+// src/auth/steps.ts
+async function postSignInStep(env, path, body, stepToken) {
+  const apiUrl = env.PLATFORM_API_URL;
+  if (!apiUrl) {
+    throw new FoirRequestError("[foir] no api url configured: set PLATFORM_API_URL");
+  }
+  const headers = { "Content-Type": "application/json" };
+  if (stepToken) headers["X-Foir-Token"] = stepToken;
+  const res = await fetch(foirApiEndpoint(apiUrl, path), {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body)
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message = typeof data.error === "string" ? data.error : `[foir] POST ${path} failed: HTTP ${res.status}`;
+    const code = typeof data.code === "string" ? data.code : void 0;
+    const extensions = {};
+    if (code) extensions.code = code;
+    if (data.signIn && typeof data.signIn === "object") extensions.signIn = data.signIn;
+    if (data.providerSignIn && typeof data.providerSignIn === "object") extensions.providerSignIn = data.providerSignIn;
+    throw new FoirRequestError(message, {
+      status: res.status,
+      graphQLErrors: Object.keys(extensions).length > 0 ? [{ message, extensions }] : void 0
+    });
+  }
+  return data;
+}
+
 // src/auth/auth.ts
 var TOKEN_KEY = "foir:token";
 var REFRESH_KEY = "foir:refreshToken";
 var USER_ID_KEY = "foir:userId";
 var EMAIL_KEY = "foir:email";
-async function login(env, vars) {
-  return authOp(env, AUTH_OPS.login, vars);
-}
-async function register(env, vars) {
-  return authOp(env, AUTH_OPS.register, vars);
-}
 async function requestOTP(env, email) {
   return authOp(env, AUTH_OPS.requestOTP, { email });
 }
-async function loginWithOTP(env, vars) {
-  return authOp(env, AUTH_OPS.loginWithOTP, vars);
+async function codeSignIn(env, vars) {
+  const signedIn = await postSignInStep(env, `/v1/sign-ins/${encodeURIComponent(vars.step.id)}/code`, { code: vars.otp }, vars.step.token);
+  return {
+    token: signedIn.accessToken ?? "",
+    refreshToken: signedIn.refreshToken ?? "",
+    userId: signedIn.user?.id ?? "",
+    email: signedIn.user?.email ?? ""
+  };
 }
-async function refreshTokens(env, refreshToken) {
+async function rotateTokens(env, refreshToken) {
   return authOp(env, AUTH_OPS.refreshToken, { refreshToken });
 }
-async function loginWithProvider(env, input) {
-  return authOp(env, AUTH_OPS.loginWithProvider, { input });
+async function signInWithProvider(adapter, env, input) {
+  const started = await authOp(
+    env,
+    AUTH_OPS.signInWithProvider,
+    { input }
+  );
+  if (started.step) await adapter.set(PROVIDER_STEP_KEY, JSON.stringify(started.step));
+  else await adapter.unset(PROVIDER_STEP_KEY);
+  return { redirectUrl: started.redirectUrl ?? null };
+}
+async function finishProviderSignIn(adapter, env, input) {
+  const step = await keptProviderStep(adapter, "no provider sign-in was started here: start one before finishing it");
+  return signedInOnStep(adapter, env, step, "provider", {
+    providerKey: input.providerKey,
+    code: input.code,
+    state: input.state
+  });
 }
-async function providerCallback(env, input) {
-  return authOp(env, AUTH_OPS.providerCallback, { input });
+var PROVIDER_STEP_KEY = "foir:providerStep";
+async function keptProviderStep(adapter, missing) {
+  const raw = await adapter.get(PROVIDER_STEP_KEY);
+  if (raw) {
+    try {
+      const step = JSON.parse(raw);
+      if (typeof step.id === "string" && typeof step.token === "string") return step;
+    } catch {
+    }
+  }
+  throw new Error(`[foir] ${missing}`);
+}
+async function signedInOnStep(adapter, env, step, route, body) {
+  const signedIn = await postSignInStep(env, `/v1/sign-ins/${encodeURIComponent(step.id)}/${route}`, body, step.token);
+  await adapter.unset(PROVIDER_STEP_KEY);
+  return saveSession(adapter, {
+    token: signedIn.accessToken ?? "",
+    refreshToken: signedIn.refreshToken ?? "",
+    userId: signedIn.userId ?? "",
+    email: signedIn.email ?? ""
+  });
 }
 async function getAuthProviders(env) {
   return authOp(env, AUTH_OPS.authProviders);
 }
+async function endSignIn(env, options) {
+  return authOp(env, AUTH_OPS.signOut, void 0, options);
+}
 async function saveSession(adapter, result) {
   await adapter.set(TOKEN_KEY, result.token);
   await adapter.set(REFRESH_KEY, result.refreshToken);
@@ -1131,19 +1187,29 @@ async function getSessionUser(adapter) {
   return { id, email: email ?? "" };
 }
 async function signInWithPassword(adapter, env, vars) {
-  return saveSession(adapter, await login(env, vars));
+  return saveSession(adapter, await authOp(env, AUTH_OPS.signIn, vars));
 }
 async function signUpWithPassword(env, vars) {
-  await register(env, vars);
+  return authOp(env, AUTH_OPS.register, vars);
 }
 async function signInWithOTP(adapter, env, vars) {
-  return saveSession(adapter, await loginWithOTP(env, vars));
+  return saveSession(adapter, await codeSignIn(env, vars));
+}
+async function signOut(adapter, env) {
+  const token = await getSessionToken(adapter);
+  if (token) {
+    try {
+      await endSignIn(env, { bearerToken: token });
+    } catch {
+    }
+  }
+  await clearSession(adapter);
 }
 async function refreshSession(adapter, env) {
   const refreshToken = await adapter.get(REFRESH_KEY) ?? null;
   if (!refreshToken) return null;
   try {
-    const result = await refreshTokens(env, refreshToken);
+    const result = await rotateTokens(env, refreshToken);
     await saveSession(adapter, result);
     return { token: result.token, refreshToken: result.refreshToken };
   } catch {
@@ -1447,14 +1513,14 @@ function hasScope(access, scope) {
 
 // src/auth/session-client.ts
 var DEFAULT_SESSION_PATH = "/session/token";
-var DEFAULT_LOGOUT_PATH = "/session/logout";
+var DEFAULT_SIGN_OUT_PATH = "/session/logout";
 var DEFAULT_REFRESH_SKEW_SECONDS = 60;
 var MIN_REFRESH_DELAY_MS = 5e3;
 var CSRF_HEADER = { "X-Foir-Session": "1" };
 function createFoirSessionClient(config) {
   const forApp = config.clientId ? `?client_id=${encodeURIComponent(config.clientId)}` : "";
   const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH}${forApp}`;
-  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}${forApp}`;
+  const signOutUrl = `${trimSlash(config.loginOrigin)}${config.signOutPath ?? DEFAULT_SIGN_OUT_PATH}${forApp}`;
   const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
   let cached = null;
   let inflight = null;
@@ -1550,7 +1616,7 @@ function createFoirSessionClient(config) {
     },
     async signOut() {
       try {
-        await fetch(logoutUrl, {
+        await fetch(signOutUrl, {
           method: "POST",
           credentials: "include",
           headers: { ...CSRF_HEADER }
@@ -1635,18 +1701,18 @@ function FoirProvider({
   }, []);
   const loginOrigin = hostedSession?.loginOrigin;
   const sessionPath = hostedSession?.sessionPath;
-  const logoutPath = hostedSession?.logoutPath;
+  const signOutPath = hostedSession?.signOutPath;
   const refreshSkewSeconds = hostedSession?.refreshSkewSeconds;
   const hosted = useMemo(() => {
     if (!loginOrigin) return null;
     return createFoirSessionClient({
       loginOrigin,
       sessionPath,
-      logoutPath,
+      signOutPath,
       refreshSkewSeconds,
       onSignOut: () => apply(null)
     });
-  }, [loginOrigin, sessionPath, logoutPath, refreshSkewSeconds, apply]);
+  }, [loginOrigin, sessionPath, signOutPath, refreshSkewSeconds, apply]);
   useEffect(() => {
     let cancelled = false;
     void (async () => {
@@ -1685,33 +1751,41 @@ function FoirProvider({
     },
     [apply, assertTokenMode]
   );
-  const register2 = useCallback(
-    (vars) => {
-      assertTokenMode("register");
-      return signUpWithPassword(envRef.current, vars);
+  const stepsRef = useRef(/* @__PURE__ */ new Map());
+  const stepKey = (email) => email.trim().toLowerCase();
+  const signUp = useCallback(
+    async (vars) => {
+      assertTokenMode("signUp");
+      stepsRef.current.set(stepKey(vars.email), await signUpWithPassword(envRef.current, vars));
     },
     [assertTokenMode]
   );
   const requestOtp = useCallback(
-    (email) => {
+    async (email) => {
       assertTokenMode("requestOtp");
-      return requestOTP(envRef.current, email);
+      stepsRef.current.set(stepKey(email), await requestOTP(envRef.current, email));
+      return true;
     },
     [assertTokenMode]
   );
   const signInWithOtp = useCallback(
     async (vars) => {
       assertTokenMode("signInWithOtp");
-      const c = await signInWithOTP(adapterRef.current, envRef.current, vars);
+      const step = stepsRef.current.get(stepKey(vars.email));
+      if (!step) {
+        throw new Error("[foir] no code was sent to this address here: call requestOtp or signUp first");
+      }
+      const c = await signInWithOTP(adapterRef.current, envRef.current, { step, otp: vars.otp });
+      stepsRef.current.delete(stepKey(vars.email));
       apply(c);
       return c;
     },
     [apply, assertTokenMode]
   );
-  const signInWithProvider = useCallback(
+  const signInWithProvider2 = useCallback(
     async (providerKey, opts) => {
       assertTokenMode("signInWithProvider");
-      const res = await loginWithProvider(envRef.current, {
+      const res = await signInWithProvider(adapterRef.current, envRef.current, {
         providerKey,
         ...opts
       });
@@ -1721,11 +1795,10 @@ function FoirProvider({
     },
     [assertTokenMode]
   );
-  const completeProviderLogin = useCallback(
+  const finishProviderSignIn2 = useCallback(
     async (input) => {
-      assertTokenMode("completeProviderLogin");
-      const result = await providerCallback(envRef.current, input);
-      const c = await saveSession(adapterRef.current, result);
+      assertTokenMode("finishProviderSignIn");
+      const c = await finishProviderSignIn(adapterRef.current, envRef.current, input);
       apply(c);
       return c;
     },
@@ -1736,7 +1809,7 @@ function FoirProvider({
       await hosted.signOut();
       return;
     }
-    await clearSession(adapterRef.current);
+    await signOut(adapterRef.current, envRef.current);
     apply(null);
   }, [apply, hosted]);
   const refresh = useCallback(async () => {
@@ -1788,7 +1861,7 @@ function FoirProvider({
     return ok;
   }, [refresh, loadAccess, accessWasRead]);
   const getProviders = useCallback(() => getAuthProviders(envRef.current), []);
-  const hostedSignInUrl = useMemo(
+  const hostedSignInUrl2 = useMemo(
     () => hosted ? (returnTo, options) => hosted.signInUrl(returnTo, options) : null,
     [hosted]
   );
@@ -1803,16 +1876,16 @@ function FoirProvider({
       env,
       adapter: adapterRef.current,
       signIn,
-      register: register2,
+      signUp,
       requestOtp,
       signInWithOtp,
-      signInWithProvider,
-      completeProviderLogin,
+      signInWithProvider: signInWithProvider2,
+      finishProviderSignIn: finishProviderSignIn2,
       signOut: signOut2,
       refresh: refreshWithAccess,
       getToken,
       getProviders,
-      hostedSignInUrl
+      hostedSignInUrl: hostedSignInUrl2
     }),
     [
       status,
@@ -1823,16 +1896,16 @@ function FoirProvider({
       ensureAccess,
       env,
       signIn,
-      register2,
+      signUp,
       requestOtp,
       signInWithOtp,
-      signInWithProvider,
-      completeProviderLogin,
+      signInWithProvider2,
+      finishProviderSignIn2,
       signOut2,
       refreshWithAccess,
       getToken,
       getProviders,
-      hostedSignInUrl
+      hostedSignInUrl2
     ]
   );
   return /* @__PURE__ */ jsx(FoirContext.Provider, { value, children });
@@ -1877,29 +1950,29 @@ function useFoirAccess() {
 function useFoirAuth() {
   const {
     signIn,
-    register: register2,
+    signUp,
     requestOtp,
     signInWithOtp,
-    signInWithProvider,
-    completeProviderLogin,
+    signInWithProvider: signInWithProvider2,
+    finishProviderSignIn: finishProviderSignIn2,
     signOut: signOut2,
     refresh,
     getToken,
     getProviders,
-    hostedSignInUrl
+    hostedSignInUrl: hostedSignInUrl2
   } = useFoirContext();
   return {
     signIn,
-    register: register2,
+    signUp,
     requestOtp,
     signInWithOtp,
-    signInWithProvider,
-    completeProviderLogin,
+    signInWithProvider: signInWithProvider2,
+    finishProviderSignIn: finishProviderSignIn2,
     signOut: signOut2,
     refresh,
     getToken,
     getProviders,
-    hostedSignInUrl
+    hostedSignInUrl: hostedSignInUrl2
   };
 }
 
@@ -1927,7 +2000,7 @@ function OAuthButtons({
   className,
   onError
 }) {
-  const { getProviders, signInWithProvider } = useFoirAuth();
+  const { getProviders, signInWithProvider: signInWithProvider2 } = useFoirAuth();
   const [providers, setProviders] = useState2([]);
   useEffect2(() => {
     let cancelled = false;
@@ -1943,7 +2016,7 @@ function OAuthButtons({
   );
   if (shown.length === 0) return null;
   const start = (p) => {
-    void signInWithProvider(p.key, { returnTo, redirectUri }).catch(
+    void signInWithProvider2(p.key, { returnTo, redirectUri }).catch(
       (err) => onError?.(err)
     );
   };
@@ -1996,7 +2069,7 @@ function SignIn({
   const [error, setError] = useState3(null);
   const styled = !className;
   if (hostedUrl) {
-    return /* @__PURE__ */ jsx3("div", { className, "data-foir-signin": true, children: /* @__PURE__ */ jsx3("a", { href: hostedUrl, "data-foir-hosted-login": true, style: styled ? submitStyle : void 0, children: "Sign in" }) });
+    return /* @__PURE__ */ jsx3("div", { className, "data-foir-signin": true, children: /* @__PURE__ */ jsx3("a", { href: hostedUrl, "data-foir-hosted-sign-in": true, style: styled ? submitStyle : void 0, children: "Sign in" }) });
   }
   const finish = (user) => {
     onSignIn?.(user);
@@ -2306,7 +2379,6 @@ function noteArgs(subject, body, anchorField) {
   const args = {
     subjectType: "record",
     subjectId: subject.recordId,
-    subjectModelKey: subject.modelKey,
     body
   };
   if (anchorField) args.anchorField = anchorField;
@@ -2320,7 +2392,7 @@ async function uploadFeedbackAttachment(client, screenshot, fetchImpl = globalTh
     );
   }
   const ticket = readUploadTicket(
-    await files.createFileUpload({
+    await files.uploadFile({
       filename: screenshotFilename(screenshot.mimeType),
       mimeType: screenshot.mimeType,
       // The blob's own size, never a number computed alongside it: this is what
@@ -2339,24 +2411,35 @@ async function uploadFeedbackAttachment(client, screenshot, fetchImpl = globalTh
       `[foir] uploading the screenshot failed: HTTP ${res.status} ${res.statusText}. The note was not written.`
     );
   }
-  const confirmed = await files.confirmFileUpload({ uploadId: ticket.uploadId });
-  const id = confirmed?.id;
+  const landed = await fetchImpl(ticket.landedEndpoint, {
+    method: "POST",
+    headers: { "X-Foir-Token": ticket.landedToken }
+  });
+  if (!landed.ok) {
+    throw new Error(
+      `[foir] the screenshot's upload was refused when it landed: HTTP ${landed.status} ${landed.statusText}. The note was not written.`
+    );
+  }
+  const settled = await landed.json().catch(() => null);
+  const id = settled?.id;
   if (typeof id !== "string" || id === "") {
     throw new Error(
-      "[foir] confirmFileUpload answered without a file id, so there is nothing to attach the note to. The note was not written."
+      "[foir] the upload landed and was answered without a file id, so there is nothing to attach the note to. The note was not written."
     );
   }
   return id;
 }
 function readUploadTicket(result) {
-  const uploadId = result?.uploadId;
-  const uploadUrl = result?.uploadUrl;
-  if (typeof uploadId !== "string" || typeof uploadUrl !== "string" || !uploadId || !uploadUrl) {
+  const r = result;
+  const uploadUrl = r?.uploadUrl;
+  const landedEndpoint = r?.landed?.endpoint;
+  const landedToken = r?.landed?.token;
+  if (typeof uploadUrl !== "string" || !uploadUrl || typeof landedEndpoint !== "string" || !landedEndpoint || typeof landedToken !== "string" || !landedToken) {
     throw new Error(
-      "[foir] createFileUpload answered without an uploadId and uploadUrl, so the screenshot has nowhere to go. The note was not written."
+      "[foir] uploadFile answered without an uploadUrl and a way to say the bytes landed, so the screenshot has nowhere to go. The note was not written."
     );
   }
-  return { uploadId, uploadUrl };
+  return { uploadUrl, landedEndpoint, landedToken };
 }
 function readCreatedNote(result) {
   const note = result;

package/dist/runs/step-reply.d.ts

@@ -0,0 +1,81 @@
+/**
+ * A step's reply to its run.
+ *
+ * A step that answers later replies with the token its run handed it alone,
+ * signed with the key that came with it, at the address that came with it:
+ * an operation's endpoint, a local development session forwarding a
+ * dispatch, or the page of a run's own caller answering a call to one of its
+ * tools. Nobody else holds such a token, so a reply reaches the one step it
+ * was minted for.
+ *
+ * Each reply is POSTed to the step's own reply route as the contract's reply
+ * itself (`{"result": ...}` and the rest), and carries:
+ *   - `Authorization: Bearer <reply.token>`
+ *   - `X-Foir-Signature: sha256=<hex>`, the HMAC-SHA256 of the raw request
+ *     body under `reply.signingKey`.
+ *
+ * A reply that gets no answer, or a 5xx or a 429, is tried again: every reply
+ * is safe to repeat, and a step whose reply is lost waits until its time is up.
+ */
+import { type FoirRetryPolicy } from '../transport/retry';
+/** How a step replies to its run, as the platform hands it to whoever runs the step. */
+export interface StepReply {
+    token: string;
+    signingKey: string;
+    /** The step's own reply route at the data API. */
+    endpoint: string;
+    /** ISO-8601. After it the token is refused. */
+    expiresAt?: string | null;
+}
+/** A step's reply, in the runs contract's own shape: exactly one of these. */
+export type StepReplyBody = {
+    result: unknown;
+} | {
+    progress: {
+        percent?: number;
+        message?: string;
+        metadata?: Record<string, unknown>;
+    };
+} | {
+    failure: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    };
+} | {
+    continuation: Record<string, unknown>;
+}
+/** The step stops its own run. */
+ | {
+    cancel: Record<string, never>;
+};
+/** What the platform made of a reply. */
+export interface StepReplyResult {
+    /** The step's status after the reply: running, held, completed, failed, cancelled, timed_out or pending. */
+    status: string;
+    /** True when the step had been cancelled, so the reply was not taken. */
+    cancelled: boolean;
+    /** False when the reply changed nothing: the step had ended, or progress came out of order. */
+    applied: boolean;
+}
+/** Reply to a run from one of its steps, with the reply its run handed it. */
+export declare function replyToStep(reply: StepReply, body: StepReplyBody, opts?: {
+    fetch?: typeof fetch;
+    retry?: FoirRetryPolicy;
+    signal?: AbortSignal;
+}): Promise<StepReplyResult>;
+/**
+ * Send one reply to a step's reply route, signed with `signingKey`. Shared by
+ * `replyToStep` and the async endpoint's callback client.
+ */
+export declare function sendReply(endpoint: string, token: string, signingKey: string, body: StepReplyBody, opts?: {
+    fetch?: typeof fetch;
+    retry?: FoirRetryPolicy;
+    signal?: AbortSignal;
+}): Promise<StepReplyResult>;
+/**
+ * The lowercase hex HMAC-SHA256 of a body, through Web Crypto, so it runs in
+ * a browser, a worker and Node alike.
+ */
+export declare function hmacSha256Hex(secret: string, body: string): Promise<string>;

package/dist/server/callback-client.d.ts

@@ -4,7 +4,7 @@
  * The platform dispatches with `mode='async'` and includes a `callback`
  * block in the operation payload. The extension acks 202, kicks the work
  * off in its own durable runtime (CF Queue, BullMQ, etc.), and later
- * calls back with one of:
+ * replies at the run's own reply route (`callback.endpoint`) with one of:
  *
  *   - `complete(result)` — operation succeeded; result conforms to the
  *     operation's `output_schema` (per-op typed via codegen).
@@ -27,18 +27,15 @@
  * with a 5xx or a 429, is tried again: a report that is lost leaves the run to
  * be closed by the platform's watchdog as timed out, and every one of these
  * calls is safe to repeat.
- *
- * Both response body shape and content-type follow the GraphQL spec —
- * extensions importing this client receive typed result data.
  */
-import { type FoirRetryPolicy } from '../transport/retry';
+import type { FoirRetryPolicy } from '../transport/retry';
 import type { OperationCallback } from './operation-types.js';
-/** Shape of a successful response from any callback mutation. */
+/** What the platform made of a reply. */
 export interface CallbackResult {
     /**
-     * Status as seen by the platform AFTER the call. One of:
-     * pending|dispatched|running|completed|failed|cancelled|timed_out|progress_stale.
-     * Always set even on idempotent / cancelled calls.
+     * The run's status as the platform sees it AFTER the call: pending,
+     * running, completed, failed, cancelled or timed_out. Always set, even on
+     * a repeated or a cancelled call.
      */
     status: string;
     /**
@@ -48,16 +45,14 @@ export interface CallbackResult {
      */
     cancelled: boolean;
     /**
-     * Progress mutations only: false when the monotonic guard rejected an
-     * out-of-order update. Extensions can use this to detect packet
-     * reordering without erroring; missing on complete/fail/cancel.
+     * False when the reply changed nothing: the run had already ended, or a
+     * progress report came out of order (the monotonic guard dropped it).
      */
     applied?: boolean;
 }
 /**
  * Per-operation callback client. `TResult` is the operation's typed result
- * shape — supply the type generated by graphql-codegen against the
- * api-public schema (`Complete{Op}ExecutionMutationVariables['result']`).
+ * shape, the operation's output type.
  */
 export interface CallbackClient<TResult = unknown> {
     complete(result: TResult): Promise<CallbackResult>;
@@ -97,9 +92,9 @@ export interface CallbackClient<TResult = unknown> {
  * told otherwise; `{ attempts: 1 }` turns it off).
  *
  * `apiUrl` is the Foir API origin the endpoint is configured with. The
- * dispatch names the address to report to and that address is the one used; a
+ * dispatch names the address to reply at and that address is the one used; a
  * platform with no public address of its own configured names none, and the
- * run then reports to the data API at `apiUrl`.
+ * run then replies at its route under `apiUrl`.
  */
 export declare function createCallbackClient<TResult = unknown>(callback: OperationCallback, opts: {
     executionId: string;

package/dist/server/index.d.ts

@@ -9,6 +9,8 @@ export type { OperationPayload, OperationTrigger, OperationRecordContext, Operat
 export { continueRun, CONTINUATION_MEDIA_TYPE, MAX_CONTINUATION_CURSOR_BYTES, MAX_CONTINUATION_DELAY_MS, type Continuation, } from './continue-run';
 export { createCallbackClient } from './callback-client';
 export type { CallbackClient, CallbackResult } from './callback-client';
+export { replyToStep } from '../runs/step-reply';
+export type { StepReply, StepReplyBody, StepReplyResult } from '../runs/step-reply';
 export { createEventsClient, FoirEventCursorExpiredError, isFoirEventCursorExpired, FOIR_EVENTS_PATH, FOIR_EVENTS_SCOPE, FOIR_EVENTS_RETENTION_DAYS, } from './events-client';
 export type { FoirEvent, FoirEventActor, FoirEventPage, FoirEventRetention, FoirEventsClient, FoirEventsClientConfig, FoirEventsListParams, FoirEventsStreamParams, FoirEventsSubscribeParams, } from './events-client';
 export type { FoirSubscription, FoirSubscriptionHandlers } from '../data/ws-transport';