@foir/sdk 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -95,8 +95,12 @@ move or drop that `.npmrc`, tag by hand:
 git tag sdk-v<version> && git push origin sdk-v<version>
 ```
 
-The tag must point at a commit on `main`: `main` is what is released, and a tag
-on `dev` would publish unreviewed work to npm.
+Where the tagged commit is decides the npm tag it goes out under. A tag on a
+commit `main` holds publishes as `latest`. A tag on a commit only `dev` holds
+publishes as `next`: use it when a release needs something production does not
+serve until the next promotion, so the version can be installed by name and
+nobody asking for `@foir/sdk` gets it early. The push that carries the commit to
+`main` moves `latest` onto it.
 
 ---
 
@@ -104,6 +108,131 @@ on `dev` would publish unreviewed work to npm.
 
 Changes on `dev` that have not been published to npm.
 
+## [0.12.0] — 2026-10-01
+
+Breaking changes under the pre-1.0 note, so this release is a MINOR. 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
+
+- **`@foir/sdk/app`**, a new subpath: everything an app built on Foir asks of
+  the platform, as one client. An app is a service the platform dispatches to,
+  holding the token each dispatch arrives with.
+  - `createAppClient({ apiUrl, dispatch })` calls the data API with that token:
+    `whoami`, `install.config`, `install.credentials`,
+    `install.writeCredentials`, `install.reportStatus`, `records.upsert`,
+    `read`, `delete`, `refresh`, `rename`, `updateMany` and `aggregate`,
+    `records.customer.save`, `read`, `erase` and `identities`,
+    `customers.ensure`, `notifications.send` and `notifications.setConsent`, and
+    `request` for a document of your own. Nothing is checked before a call: what
+    the token may do is the platform's to hold it to, and a refusal is a
+    `FoirRequestError` carrying the platform's answer.
+  - `appLookupConflictOf`, `appCustomerUnlinkedOf` and `isAppFieldWithheld` read
+    the refusals an app acts on, as data.
+  - `readAppDispatch` and `readCredentialProbe` read the two bodies the platform
+    posts to an app, and `redeemExchangeTicket` trades an OAuth exchange ticket
+    for the token that writes the install's credentials.
+  - `validateAppManifest({ apiUrl, apiKey, manifest })` asks the platform
+    whether it would accept a manifest, as a dry run, and answers with every
+    issue and where it is. Any key may ask, a publishable one included.
+  - `APP_CAPABILITIES`, `APP_RECORD_CAPABILITY_PREFIXES` and `APP_HOOK_EVENTS`
+    are the capabilities an operation may declare and the events a hook may
+    name, with their types, generated from the platform's contract.
+  - `appModelTypeName`, `appModelFieldName`, `appSelectorEnumValue` and
+    `isSelectableFieldKey` name a model's fields on the data API from its key,
+    and `RECORD_KEY_RULE` and `recordKeyRefusal` state what a record key may be.
+- **`@foir/sdk/app/contract`**, a new subpath: the manifest and discovery
+  contracts as the messages the platform decodes them with (`AppConfigSchema`,
+  `DiscoveryResultSchema` and what they are built from). Building a manifest
+  from them means a key the platform does not accept cannot be written. It
+  needs `@bufbuild/protobuf`, an optional peer dependency nothing else in the
+  package asks for.
+- **`createScopedTokenVerifier`** in `@foir/sdk/server`, for a long-lived
+  service: it keeps the platform's signing keys, refreshes them in the
+  background, keeps serving the ones it holds through an outage, and looks
+  again at most once per cooldown when a token names a key it has not seen.
+  `requireScopedToken` takes it as `verifier`. `ScopedTokenUnavailableError` is
+  what it throws when it has no keys to judge a token by.
+- **`requireScopedToken` answers more about who is calling.** The ingress it
+  resolves with gains `orgId` (the organisation level the token was minted at,
+  `null` when it states none), `customerId`, `expiresAt` and `tokenId`.
+  `ScopedTokenError` gains `reason` (`missing`, `invalid`, `forbidden` or
+  `unavailable`), and its `status` may now be 503: keys that cannot be fetched
+  are this service's outage, which the platform retries, and not a verdict on
+  the token. `FOIR_TOKEN_HEADER` and `FOIR_CONTEXT_HEADER` name the two dispatch
+  headers.
+- **`createCallbackClient` needs no signing secret.** It signs with the run's
+  own key, `callback.signingKey`, which the platform sends with every ASYNC
+  dispatch, so `signingSecret` is now optional and is the key used only when
+  passed. It takes `apiUrl`, used when a dispatch names no address to report
+  to, `retry`, and `signal`. A call the platform did not answer, or answered
+  with a 5xx or a 429, is tried again, with the same signed bytes.
+- **`@foir/sdk/placement`**, a new subpath for an app's own admin console shown
+  inside Foir's as a full-page placement. `connectPlacement` tells the console
+  the page is ready, takes the token it posts into the frame (only from the
+  consoles you list), keeps it fresh, and gives you `request`, `can` and
+  `onSignedOut`. `placementFrameAncestors` builds the `frame-ancestors` value a
+  page must send to be shown at all, and `FOIR_CONSOLE_ORIGINS` names the
+  consoles per environment. `PLACEMENT_MESSAGE` and the message types are the
+  protocol the console speaks. Additive: no existing export changes.
+- **`continueRun`** in `@foir/sdk/server`, for an ASYNC operation whose work is
+  longer than one call: it answers the dispatch with a continuation (a cursor,
+  and optionally a delay and progress), and the platform queues the next slice
+  with a fresh callback, handing it the cursor. `CONTINUATION_MEDIA_TYPE`,
+  `MAX_CONTINUATION_CURSOR_BYTES` and `MAX_CONTINUATION_DELAY_MS` state the
+  contract, `Continuation` is its type, and `OperationContinuationBlock` is the
+  envelope block a slice reads its cursor from (`readDispatch` validates it).
+  Additive: no existing export changes.
+- **`FoirAuthDowngradedError`** and **`FoirSessionExpiredError`**, exported from
+  `@foir/sdk/data`, `@foir/sdk/server`, `@foir/sdk/auth` and `@foir/sdk/client`,
+  and **`refreshSessionOnce`** in `@foir/sdk/auth`. `requireAuth` takes an
+  optional `env`, and the data client's config takes `refreshBearer`.
+- **`visitor`** on the data client: the address of the visitor a server
+  rendering pages is calling for, or a function resolving it per request, sent
+  as `X-Foir-Visitor-IP` so the public API's per-visitor limit applies to that
+  visitor. From a secret key holding `visitors:forward`; a client built from a
+  public key is refused it. The SDK reads no address off a request: pass the one
+  your host guarantees. `FoirVisitorSource` and `FOIR_VISITOR_IP_HEADER` are
+  exported from `@foir/sdk/data`.
+
+### Changed
+
+- **Breaking: a scoped token's app is everything after the second `|` of its
+  subject.** `verifyScopedToken` required exactly three `|`-separated parts,
+  none empty, so it refused a token whose app name holds a `|`, and one minted
+  for a project and no app. The platform splits on the first two: both now
+  verify, and `appName` is `''` for a token that names no app.
+- **Breaking: `createCallbackClient` throws `FoirRequestError`**, where it threw
+  a plain `Error`, so a caller can tell a refusal (`status`, `graphQLErrors`)
+  from a call that got no answer. It also throws when it is built with nothing
+  to sign with, or with nowhere to report to.
+- **Breaking: a refusal in a 200 is not retryable.**
+  `FoirRequestError.retryable` was true for any error with no HTTP status, which
+  is the shape of a network fault and also of a GraphQL refusal answered with a
+  200. A refusal is now retryable only when its code is `RATE_LIMITED`,
+  `UNAVAILABLE` or `TIMEOUT`; a stripped selection never is.
+- **Breaking: a signed-in request is no longer handed the signed-out answer.**
+  A bearer the server cannot verify is not refused: the request is served as
+  nobody, and the response says so in `extensions.auth`. The SDK used to warn
+  and return that answer as though it were the signed-in one.
+  - `authedOp` and `authedRequest` now treat it like a 401. They refresh the
+    session once, retry once, and fail with `FoirSessionExpiredError` when it
+    cannot be renewed. A token this environment never issued fails the same way,
+    without a refresh.
+  - Requests that find the session lapsed together share one refresh, because a
+    refresh token rotates when it is spent.
+  - The data client, for a request that sent a bearer, fails with
+    `FoirAuthDowngradedError`. Give it `refreshBearer` and it renews the bearer
+    once and asks again, failing with `FoirSessionExpiredError` when the session
+    is over.
+  - A request that sent no bearer is untouched.
+- **A refresh that names no customer keeps the session's identity.**
+  `saveSession` used to write the customer id and email unconditionally, so a
+  refresh answered without them left a valid token beside an empty identity, and
+  `requireAuth` turned the session away. Given `env`, `requireAuth` now reads a
+  missing identity once from `currentUser` rather than failing.
+
 ## [0.11.0] — 2026-09-26
 
 Breaking changes under the pre-1.0 note, so this release is a MINOR:

package/dist/app/client.d.ts

@@ -0,0 +1,371 @@
+/**
+ * The client an installed app calls Foir with.
+ *
+ * An app is installed in many projects, and each install maps the app's
+ * sources onto whichever models that project's operator chose. So an app has
+ * no schema to generate a client from: it learns the model keys at request
+ * time, from the install's own configuration, and names them in each call.
+ * `createFoirClient` is the client for an endpoint that knows its project;
+ * this is the one for an endpoint that does not.
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { verifier });
+ * const foir = createAppClient({ apiUrl, dispatch });
+ * const config = await foir.install.config();
+ * const products = config.sources.find((source) => source.key === 'product');
+ * await foir.records.upsert({ model: products.model, naturalKey: handle, data });
+ * ```
+ *
+ * The credential is the token the dispatch carried, and nothing else. Every
+ * call goes to the data API as that token, so what it may do is exactly what
+ * the operation declared. NOTHING IS CHECKED HERE FIRST: the client does not
+ * read the token, and a call the token cannot make is refused by the platform,
+ * whose answer is the error thrown (see `./errors`).
+ *
+ * A client is cheap and holds no state. Build one per dispatch and let it go
+ * with the request, so a credential revoked in Foir stops working on the next
+ * call rather than whenever a cache expires.
+ */
+import type { FoirDispatchCredential } from '../data/transport';
+import { type FoirRetryPolicy } from '../transport/retry';
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+type JsonObject = {
+    [key: string]: Json;
+};
+export interface AppClientConfig {
+    /** The data API's origin, e.g. `https://api.foir.dev`. */
+    apiUrl: string;
+    /**
+     * The token to call as: `dispatch` from `requireScopedToken`, the token an
+     * exchange ticket was redeemed for (`redeemExchangeTicket`), or an ASYNC
+     * run's callback token (`{ token: () => payload.callback.token }`), which
+     * keeps writing records after the dispatch token has expired.
+     */
+    dispatch: FoirDispatchCredential;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Extra init for every request, e.g. an abort signal. */
+    requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
+    /**
+     * How a call that got no answer, a 5xx or a 429 is tried again. Three
+     * attempts unless told otherwise; `{ attempts: 1 }` turns it off. Every call
+     * here is safe to repeat except a notification sent without an
+     * `idempotencyKey`, which a retry after a lost answer can deliver twice.
+     */
+    retry?: FoirRetryPolicy;
+}
+/** Which way one mapped field is allowed to move. */
+export type AppSyncDirection = 'SOURCE_ONLY' | 'SINK_ONLY' | 'BIDIRECTIONAL';
+export interface AppFieldMapping {
+    /** The app's own field name, from its manifest. */
+    appField: string;
+    /** The project model's field key. */
+    modelField: string;
+    /**
+     * SINK_ONLY means the operator has said Foir owns the field: a value from
+     * the app's side must not be written over it. An unrecognised direction
+     * reads as SINK_ONLY, which withholds the field rather than writing on a
+     * guess.
+     */
+    direction: AppSyncDirection;
+}
+/** One of the operator's mappings: a source or sink of the app onto a model. */
+export interface AppBinding {
+    /** The app's source or sink name. */
+    key: string;
+    /** The project model the operator mapped it onto. */
+    model: string;
+    /** The model field the app's records are keyed on. Empty when the mapping names none. */
+    naturalKey: string;
+    fields: AppFieldMapping[];
+    /** REFERENCE: Foir reads the source's fields live. SYNC: it holds a copy. A sink is a copy. */
+    mode: 'SYNC' | 'REFERENCE';
+}
+/** An install's own configuration, as the operator left it. */
+export interface AppInstallConfig {
+    name: string;
+    enabled: boolean;
+    middlewareUrl: string;
+    targetModels: string[];
+    /** The address the app's vendor is told to deliver webhooks to. Empty when the app declares none. */
+    webhookUrl: string;
+    /** The operator's answers to the manifest's settings schema. */
+    settings: JsonObject;
+    sources: AppBinding[];
+    sinks: AppBinding[];
+}
+/**
+ * The status an install reports. Leaving out `subscriptionHealth`,
+ * `authStatus`, `deletionStrategy` or `extra` keeps the stored value; leaving
+ * out any of the `lastSync*` or `lastError*` fields clears it. So send the
+ * sync fields together or not at all.
+ */
+export interface AppStatusReport {
+    lastSyncAt?: string;
+    lastSyncDurationMs?: number;
+    lastSyncRecordCount?: number;
+    /** null clears the field. */
+    lastError?: string | null;
+    lastErrorAt?: string | null;
+    subscriptionHealth?: 'healthy' | 'degraded' | 'failed';
+    authStatus?: 'authenticated' | 'unverified' | 'stale' | 'expired';
+    deletionStrategy?: string;
+    /** Replaced whole on every report that carries it. */
+    extra?: JsonObject;
+}
+/** A record as a read by model key answers it. */
+export interface AppRecord {
+    /** The platform's own id. What `records.delete` takes. */
+    id: string;
+    naturalKey: string | null;
+    /** The customer the record belongs to, or null. */
+    ownerId: string | null;
+    /** The fields that were asked for and could be read, by model field key. */
+    fields: JsonObject;
+    /** Fields that were asked for and could not be selected, so the answer says nothing about them. */
+    unreadable: string[];
+}
+export interface AppUpsertResult {
+    /** The record as the platform holds it now. */
+    record: Record<string, unknown>;
+    /** The platform's own id for it, when the answer carried one. */
+    id: string | null;
+    created: boolean;
+    /** True when nothing was written because Foir already holds a newer copy (`sourceModifiedAt`). */
+    stale: boolean;
+}
+export type AppCustomerSaveResult = (AppUpsertResult & {
+    unlinked: false;
+    customerCreated: boolean;
+}) | {
+    unlinked: true;
+};
+export interface AppCustomerEraseResult {
+    recordDeleted: boolean;
+    identityRemoved: boolean;
+    customerDeleted: boolean;
+    /** Another sign-in method, or something else they own; null when the customer went or none was found. */
+    customerKeptBecause: string | null;
+}
+export interface AppNotification {
+    customerId: string;
+    /** The in-app title, and the email's subject when `email` names none. */
+    title: string;
+    message?: string;
+    /** A notification category the project defines. */
+    category?: string;
+    actionUrl?: string;
+    imageUrl?: string;
+    /** The email, when the send should reach one. Without it, in-app and push only. */
+    email?: {
+        subject?: string;
+        body: string;
+        ctas?: ReadonlyArray<{
+            label: string;
+            url: string;
+        }>;
+    };
+    /** Makes the send safe to repeat: the same key from the same operation tells the customer once. */
+    idempotencyKey?: string;
+}
+export interface AppConsentChange {
+    customerId: string;
+    /** A notification category the project makes opt-in. */
+    category: string;
+    /** The channel the consent is for, as the project's preferences name it (for example `email`). */
+    channel: string;
+    enabled: boolean;
+    /**
+     * When the change was made at its source, as an RFC 3339 time. The platform
+     * keeps the latest it has taken and writes nothing for an older one,
+     * answering `stale`.
+     */
+    sourceModifiedAt?: string;
+}
+/** What the calling token is, and what it is served. Read from the platform, never off the token. */
+export interface AppWhoami {
+    /** The app the token acts for, when it acts for one. */
+    app: string | null;
+    /** The capabilities the token carries. */
+    capabilities: string[];
+    /** The models its record capabilities name, by verb. */
+    models: {
+        read: string[];
+        write: string[];
+        delete: string[];
+        publish: string[];
+    };
+    /** The scopes its calls are held to. */
+    effective: string[];
+    expiresAt: string | null;
+}
+export interface AppClient {
+    /**
+     * Run a hand-written document as the app and answer its whole `data`. For a
+     * field this client has no method for. A read asking for something the token
+     * is not served throws rather than answering the rest without it.
+     */
+    request<T = Record<string, unknown>>(document: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * What the platform says this token is and may do. For an app that has to
+     * SHOW that; a call the token cannot make needs no check first, since the
+     * platform's refusal already says why.
+     */
+    whoami(): Promise<AppWhoami>;
+    /** The install this token acts for: its configuration, its credential, its status. */
+    install: {
+        /** The operator's settings and mappings. Needs `config:read`. */
+        config(): Promise<AppInstallConfig>;
+        /**
+         * The install's credential, by the manifest's credential field names.
+         * Values are always strings. Needs `secrets:read.app`.
+         */
+        credentials(): Promise<Record<string, string>>;
+        /**
+         * Write or rotate credential fields. An empty value is skipped, not
+         * cleared, and a call naming no non-empty field is refused. Needs
+         * `secrets:put.app`.
+         */
+        writeCredentials(values: Record<string, string>): Promise<void>;
+        /** Report the install's health. Needs `status:write`. See {@link AppStatusReport}. */
+        reportStatus(status: AppStatusReport): Promise<void>;
+    };
+    /** Records of a model the install maps, named by its key. */
+    records: {
+        /**
+         * Write the record at a natural key, making it when there is none.
+         * `ownerId` names the customer it belongs to (needs
+         * `records:attribute:<model>`); `sourceModifiedAt` is when the object this
+         * mirrors last changed at its source, so an older copy arriving late is
+         * not written.
+         */
+        upsert(input: {
+            model: string;
+            naturalKey: string;
+            data: JsonObject;
+            ownerId?: string;
+            sourceModifiedAt?: string;
+        }): Promise<AppUpsertResult>;
+        /**
+         * One record by natural key or by id, or null. It reads the PUBLISHED
+         * version: on a model with publishing, a record that was never published
+         * reads as null, the same as one that does not exist. A field that cannot
+         * be selected as written is reported in `unreadable` rather than failing
+         * the read.
+         */
+        read(model: string, by: {
+            naturalKey: string;
+        } | {
+            id: string;
+        }, fields: readonly string[]): Promise<AppRecord | null>;
+        /** Delete one record by its platform id, which only a read supplies. */
+        delete(model: string, id: string): Promise<{
+            deleted: boolean;
+        }>;
+        /**
+         * Drop what the data API has cached for one record, by natural key or id,
+         * so its next read resolves it again. False when Foir holds no such
+         * record. For a source read live from its host.
+         */
+        refresh(model: string, idOrKey: string): Promise<{
+            refreshed: boolean;
+        }>;
+        /**
+         * Change the natural key of the one record a filter matches. The platform
+         * refuses a filter matching none or several, and a key already held.
+         */
+        rename(model: string, where: JsonObject, naturalKey: string): Promise<void>;
+        /**
+         * Update every record matching a filter, in one call. `where` and `data`
+         * are the model's typed filter and update, by model field key. An empty
+         * filter is refused: it would change every record.
+         */
+        updateMany(model: string, input: {
+            where: JsonObject;
+            data: JsonObject;
+            idempotencyKey?: string;
+        }): Promise<{
+            count: number;
+            ids: string[];
+        }>;
+        /**
+         * How many records match, grouped by one field, counted by the platform.
+         * It groups only by an indexed field, largest group first; `truncated`
+         * says `limit` cut the list short.
+         */
+        aggregate(model: string, query: {
+            groupBy: string;
+            where?: JsonObject;
+            limit?: number;
+        }): Promise<{
+            groups: Array<{
+                key: string | null;
+                count: number;
+            }>;
+            truncated: boolean;
+        }>;
+        /**
+         * The record of a customer the app names by identity: their id at the
+         * external system, which is also the subject of their sign-in with it. For
+         * a source that declares an identity. The platform finds the customer
+         * through the sign-in the install pairs with the source, at the install's
+         * level, and never by email.
+         */
+        customer: {
+            /**
+             * Merge `data` into the customer's record, making the record when they
+             * have none, and the customer when `email` is given and nobody holds the
+             * identity. An identity nobody holds, with no email, is `{ unlinked:
+             * true }`: nothing was written, and they are known once they sign in.
+             */
+            save(input: {
+                model: string;
+                identity: string;
+                data: JsonObject;
+                email?: string;
+                sourceModifiedAt?: string;
+            }): Promise<AppCustomerSaveResult>;
+            /** The customer's record, or null when nobody holds the identity or they hold no record. */
+            read(model: string, identity: string): Promise<AppRecord | null>;
+            /**
+             * Erase what the app holds for the customer, as a privacy request asks:
+             * their record and the identity's link, and the customer when nothing
+             * else is attached to them. Needs `customers:write` as well.
+             */
+            erase(model: string, identity: string): Promise<AppCustomerEraseResult>;
+            /**
+             * The other direction: the identities a customer the app names by id
+             * signs in with there, most recently seen first. Empty when they sign in
+             * with none. For an app acting on an event that names the Foir customer.
+             */
+            identities(model: string, customerId: string): Promise<string[]>;
+        };
+    };
+    customers: {
+        /**
+         * The customer who has this email at the install's level, made when there
+         * is none. The same customer every time for one email. Needs
+         * `customers:write`.
+         */
+        ensure(email: string): Promise<{
+            id: string;
+            email: string;
+        }>;
+    };
+    notifications: {
+        /** Tell a customer something. Needs `notifications:write`. */
+        send(notification: AppNotification): Promise<void>;
+        /**
+         * Set a named customer's consent in an opt-in category. Needs
+         * `notifications:consent`, which only an operation's token carries.
+         */
+        setConsent(change: AppConsentChange): Promise<{
+            stale: boolean;
+        }>;
+    };
+}
+/** Build the client an installed app calls Foir with. See the module doc. */
+export declare function createAppClient(config: AppClientConfig): AppClient;
+export {};

package/dist/app/contract/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The app contract, as the messages the platform itself reads and writes.
+ *
+ * A manifest is `AppConfig`, and a discovery answer is `DiscoveryResult`. They
+ * are generated from the same definitions the platform decodes them with, so a
+ * manifest built with `create(AppConfigSchema, …)` and written with `toJson`
+ * cannot carry a key the platform would refuse: it would not compile.
+ *
+ * ```ts
+ * import { create, toJson } from '@bufbuild/protobuf';
+ * import { AppConfigSchema } from '@foir/sdk/app/contract';
+ *
+ * const manifest = create(AppConfigSchema, { name: 'my-app', version: '1.0.0' });
+ * const served = toJson(AppConfigSchema, manifest, { useProtoFieldName: true });
+ * ```
+ *
+ * These are protobuf-es messages, so this subpath needs `@bufbuild/protobuf`
+ * installed beside the SDK; the rest of the SDK does not. The messages follow
+ * the platform's contract, which only ever grows: a field or a message can
+ * appear in any release, and none is removed without a breaking one.
+ */
+export * from './proto/apps/v1/apps_pb.js';
+export * from './proto/apps/v1/discovery_pb.js';