@foir/sdk 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -108,6 +108,40 @@ nobody asking for `@foir/sdk` gets it early. The push that carries the commit to
 
 Changes on `dev` that have not been published to npm.
 
+## [0.13.0] — 2026-10-01
+
+Published under npm's `next` tag from `dev`, because it calls parts of the
+platform that production serves from the next promotion; `latest` moves to it
+then.
+
+### Added
+
+- **`operations.start`** on the app client (`@foir/sdk/app`): a webhook
+  delivery starts a run of one of the app's own operations, with an input, and
+  is answered with the run's id without waiting for it. For work a delivery
+  cannot do in place: a delivery is not a run, so it holds none of the
+  authority the platform gives only inside one, and it has the few seconds its
+  vendor waits. Only the token a delivery arrived with may call it.
+  `idempotencyKey` names one delivery, so a redelivery does not start the work
+  twice. `concurrencyKey` names work of which one run should be in flight at a
+  time: a start under it joins the run in flight and starts nothing, and once
+  that run has ended the next start is a new run. A start under a key is
+  retried when it gets no answer; one under no key is asked once.
+  `AppOperationStart` and `AppStartedOperation` are its types.
+- **`records.list`** on the app client: the records matching a filter, in an
+  order, at most `first` of them, with `hasMore` saying the filter matched more.
+  For work an app hands out in turn, such as the next ten people waiting: list
+  them, then update the ones listed by id. A model's list is named by its
+  plural, which its operator may set, so the first list a client makes reads
+  the data API's surface descriptor (`GET /v1/manifest`) as the same token,
+  once. `AppRecordList` is its query's type.
+
+### Changed
+
+- **Breaking: `OperationTrigger.type` gains `'webhook'`**, the trigger of a run
+  a delivery started with `operations.start`. A `switch` over the four earlier
+  values that TypeScript checked as exhaustive needs a case for it.
+
 ## [0.12.0] — 2026-10-01
 
 Breaking changes under the pre-1.0 note, so this release is a MINOR. Published

package/dist/app/client.d.ts

@@ -260,6 +260,25 @@ export interface AppClient {
         } | {
             id: string;
         }, fields: readonly string[]): Promise<AppRecord | null>;
+        /**
+         * The records matching a filter, in an order, at most `first` of them. For
+         * work handed out in turn, such as the next ten people waiting: list them,
+         * then update the ones listed by id.
+         *
+         * `where` is the model's typed filter and `orderBy` names model fields, as
+         * `updateMany` takes them. The platform orders by `createdAt`, `updatedAt`,
+         * `naturalKey` and `id`, and by a field the model indexes; ordering by any
+         * other is refused, naming it. `hasMore` says the filter matched more than
+         * were answered. Like `read`, it sees the PUBLISHED version.
+         *
+         * The name of a model's list is the operator's to set, so the first list a
+         * client makes asks the data API what this token is served (`GET
+         * /v1/manifest`), once.
+         */
+        list(model: string, query: AppRecordList): Promise<{
+            records: AppRecord[];
+            hasMore: boolean;
+        }>;
         /** Delete one record by its platform id, which only a read supplies. */
         delete(model: string, id: string): Promise<{
             deleted: boolean;
@@ -365,6 +384,61 @@ export interface AppClient {
             stale: boolean;
         }>;
     };
+    operations: {
+        /**
+         * Start a run of one of this app's own operations, from a webhook
+         * delivery. The run is queued and dispatched as a hook's is, and this
+         * answers with its id without waiting for it.
+         *
+         * For work a delivery cannot do in place. A delivery is not a run, so it
+         * holds none of the authority the platform gives only inside one (setting
+         * a customer's consent is one), and it has the few seconds its vendor
+         * waits. Hand the work to an operation and answer the vendor.
+         *
+         * Only the token a delivery arrived with may call it, for an operation
+         * that is active at the install. An operation's own token is refused: it
+         * carries that operation's capabilities and no other's.
+         */
+        start(operationKey: string, options?: AppOperationStart): Promise<AppStartedOperation>;
+    };
+}
+export interface AppRecordList {
+    /** The model's typed filter, by model field key. Absent matches every record. */
+    where?: JsonObject;
+    /** The order, most significant first. The record id breaks every tie. */
+    orderBy?: ReadonlyArray<{
+        field: string;
+        direction?: 'asc' | 'desc';
+    }>;
+    /** How many to answer, at most. */
+    first: number;
+    /** The model fields to read on each record. Its id, natural key and owner always come back. */
+    fields?: readonly string[];
+}
+export interface AppOperationStart {
+    /** The run's input. */
+    input?: JsonObject;
+    /**
+     * Names one delivery, so the vendor's redelivery of it does not start the
+     * work twice: pass the delivery's own id.
+     */
+    idempotencyKey?: string;
+    /**
+     * Names work of which one run should be in flight at a time. While a run of
+     * the operation started under the key is in flight, a start under it joins
+     * that run and starts nothing; once that run has ended, the next start is a
+     * new run. For work that recurs and must not overlap, where an idempotency
+     * key would adopt the first run for ever.
+     */
+    concurrencyKey?: string;
+}
+export interface AppStartedOperation {
+    /** The run: the one this call started, joined or adopted. */
+    executionId: string;
+    /** True when `concurrencyKey` matched a run in flight, so nothing was started. */
+    joined: boolean;
+    /** True when `idempotencyKey` matched a run in flight or completed, so nothing was started. */
+    deduplicated: boolean;
 }
 /** Build the client an installed app calls Foir with. See the module doc. */
 export declare function createAppClient(config: AppClientConfig): AppClient;

package/dist/app/index.d.ts

@@ -21,7 +21,7 @@
  * The manifest's own messages are on `@foir/sdk/app/contract`.
  */
 export { createAppClient } from './client';
-export type { AppBinding, AppClient, AppClientConfig, AppConsentChange, AppCustomerEraseResult, AppCustomerSaveResult, AppFieldMapping, AppInstallConfig, AppNotification, AppRecord, AppStatusReport, AppSyncDirection, AppUpsertResult, AppWhoami, } from './client';
+export type { AppBinding, AppClient, AppClientConfig, AppConsentChange, AppCustomerEraseResult, AppCustomerSaveResult, AppFieldMapping, AppInstallConfig, AppNotification, AppOperationStart, AppRecord, AppRecordList, AppStartedOperation, AppStatusReport, AppSyncDirection, AppUpsertResult, AppWhoami, } from './client';
 export { appCustomerUnlinkedOf, appLookupConflictOf, isAppFieldWithheld } from './errors';
 export type { AppLookupConflict } from './errors';
 export { appModelFieldName, appModelTypeName, appSelectorEnumValue } from './naming';

package/dist/app.js

@@ -337,6 +337,83 @@ function createAppClient(config) {
   const refuse = (message) => {
     throw new FoirRequestError(`[foir] ${message}`);
   };
+  let surface;
+  function served() {
+    surface ??= withFoirRetry(async () => {
+      const token = (await config.dispatch.token())?.trim();
+      if (!token) {
+        throw new FoirRequestError(
+          "[foir] the dispatch token provider returned no token. An app client calls as the token it was built from."
+        );
+      }
+      let res;
+      try {
+        res = await doFetch(foirApiEndpoint(config.apiUrl, "/v1/manifest"), {
+          ...config.requestInit,
+          method: "GET",
+          headers: buildFoirHeaders({ dispatchToken: token, dispatchContext: config.dispatch.context ?? void 0 })
+        });
+      } catch (err) {
+        throw new FoirRequestError("[foir] network error", { cause: err });
+      }
+      if (!res.ok) {
+        throw new FoirRequestError(`[foir] GET /v1/manifest failed: HTTP ${res.status} ${res.statusText}`, { status: res.status });
+      }
+      return await res.json();
+    }, config.retry).catch((error) => {
+      surface = void 0;
+      throw error;
+    });
+    return surface;
+  }
+  async function listMany(model, query) {
+    if (!Number.isInteger(query.first) || query.first < 1) refuse(`a list of ${model} asked for ${query.first} records; it takes a whole number of at least 1`);
+    const op = (await served()).models?.[model]?.ops?.["findMany"];
+    const name = op?.field;
+    if (!name) {
+      return refuse(
+        `this token is not served a list of ${model}: the operation it was minted for declares no read of that model`
+      );
+    }
+    const type = appModelTypeName(model);
+    const fields = query.fields ?? [];
+    const unselectable = fields.filter((key) => !isSelectableFieldKey(key));
+    if (unselectable.length > 0) refuse(`a list of ${model} asked for fields that cannot be selected: ${unselectable.join(", ")}`);
+    const orderBy = (query.orderBy ?? []).map((entry) => {
+      if (!isSelectableFieldKey(entry.field)) refuse(`a list of ${model} was ordered by "${entry.field}", which is not a field name`);
+      return { [entry.field]: entry.direction === "desc" ? "DESC" : "ASC" };
+    });
+    const answer = await field(
+      name,
+      `query AppListRecords($where: ${op?.argTypes?.["where"] ?? `${type}WhereInput`}, $orderBy: ${op?.argTypes?.["orderBy"] ?? `[${type}OrderByInput]`}, $first: Int) { ${name}(where: $where, orderBy: $orderBy, first: $first) { edges { node { ${[RECORD_ID_FIELD, RECORD_NATURAL_KEY_FIELD, RECORD_OWNER_FIELD, ...fields].join(" ")} } } pageInfo { hasNextPage } } }`,
+      {
+        first: query.first,
+        ...query.where && Object.keys(query.where).length > 0 ? { where: query.where } : {},
+        ...orderBy.length > 0 ? { orderBy } : {}
+      }
+    );
+    if (!answer || !Array.isArray(answer.edges)) return refuse(`${name} reported no error and returned no list`);
+    const records = answer.edges.map((edge) => {
+      const node = edge?.node;
+      const id = node?.[RECORD_ID_FIELD];
+      if (!node || typeof id !== "string" || id === "") return refuse(`${name} answered a record carrying no id`);
+      const values = {};
+      for (const key2 of fields) {
+        const got = node[key2];
+        if (got !== void 0) values[key2] = got;
+      }
+      const key = node[RECORD_NATURAL_KEY_FIELD];
+      const owner = node[RECORD_OWNER_FIELD];
+      return {
+        id,
+        naturalKey: typeof key === "string" && key !== "" ? key : null,
+        ownerId: typeof owner === "string" && owner !== "" ? owner : null,
+        fields: values,
+        unreadable: []
+      };
+    });
+    return { records, hasMore: answer.pageInfo?.hasNextPage === true };
+  }
   async function readOne(model, by, fields) {
     const byId = "id" in by;
     const value = byId ? by.id : by.naturalKey;
@@ -512,6 +589,7 @@ function createAppClient(config) {
         };
       },
       read: readOne,
+      list: listMany,
       async delete(model, id) {
         if (id === "") refuse(`a record delete on ${model} was given an empty id`);
         const name = `delete${appModelTypeName(model)}`;
@@ -705,6 +783,36 @@ function createAppClient(config) {
         if (!answer) return refuse("setCustomerConsent reported no error and answered nothing");
         return { stale: answer.stale === true };
       }
+    },
+    operations: {
+      async start(operationKey, options = {}) {
+        const key = operationKey.trim();
+        if (key === "") refuse("an operation was started with no key");
+        const params = ["$operationKey: String!"];
+        const args = ["operationKey: $operationKey"];
+        const variables = { operationKey: key };
+        if (options.input !== void 0) {
+          params.push("$input: JSON");
+          args.push("input: $input");
+          variables.input = options.input;
+        }
+        if (options.idempotencyKey !== void 0) {
+          params.push("$idempotencyKey: String");
+          args.push("idempotencyKey: $idempotencyKey");
+          variables.idempotencyKey = options.idempotencyKey;
+        }
+        if (options.concurrencyKey !== void 0) {
+          params.push("$concurrencyKey: String");
+          args.push("concurrencyKey: $concurrencyKey");
+          variables.concurrencyKey = options.concurrencyKey;
+        }
+        const document = `mutation AppStartOperation(${params.join(", ")}) { startOperation(${args.join(", ")}) { executionId joined deduplicated } }`;
+        const keyed = Boolean(options.idempotencyKey || options.concurrencyKey);
+        const data = keyed ? await run(document, variables) : await send(document, variables);
+        const answer = data["startOperation"];
+        if (!answer?.executionId) return refuse("startOperation reported no error and named no run");
+        return { executionId: answer.executionId, joined: answer.joined === true, deduplicated: answer.deduplicated === true };
+      }
     }
   };
 }

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

@@ -127,9 +127,11 @@ export interface OperationCallback {
  * - `lifecycle`: a hook on a platform event (a record published, an operation
  *   completed).
  * - `schedule`: a cron schedule firing.
+ * - `webhook`: an app's webhook delivery handing its work to this operation
+ *   (`operations.start` on the app client).
  */
 export interface OperationTrigger {
-    type: 'ui' | 'api' | 'lifecycle' | 'schedule';
+    type: 'ui' | 'api' | 'lifecycle' | 'schedule' | 'webhook';
 }
 /**
  * The record block a caller attached to a run, forwarded as the caller wrote

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {