@foir/sdk 0.10.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,8 +108,355 @@ 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:
+`OperationPayload` now describes the body the platform actually sends,
+`FoirClientConfig` is a union of two credentials, a record write resolves to
+`FoirWriteResult`, an option field's union is its declared values, and the
+generated module, the drift check and `FoirSchemaDrift` are keyed on the
+surface version instead of the schema counter.
+
+### Added
+
+- The data client takes an operation's dispatch token as its credential, so an
+  operation endpoint calls Foir AS the operation and holds no key.
+
+  ```ts
+  import { createFoirClient } from '@foir/sdk/data';
+  import { readDispatch, requireScopedToken } from '@foir/sdk/server';
+  // foir types --operation checkout --out src/checkout.generated.ts
+  import * as generated from './checkout.generated';
+
+  export async function POST(request: Request) {
+    const { dispatch } = await requireScopedToken(request, {
+      expectedProjectId: process.env.FOIR_PROJECT_ID,
+    });
+    const { input } = await readDispatch<{ email: string }>(request);
+    const foir = createFoirClient({ apiUrl: process.env.PLATFORM_API_URL!, dispatch, generated });
+    // ...
+  }
+  ```
+
+  A dispatch client requires `generated`, and only a module generated for an
+  operation: `foir types --operation <key>` types the surface that operation's
+  token is served (`GET /v1/manifest?operation=<key>`) and exports
+  `foirCredential` naming it. A key client refuses such a module, a dispatch
+  client refuses a key's module, and a dispatch whose `X-Foir-Context` names
+  another operation than the module is refused, each at the type and at
+  construction. New on `@foir/sdk/data`: `FoirOperationCredential`,
+  `FoirKeyGeneratedModule` and `FoirOperationGeneratedModule`.
+
+  A client built with `dispatch` sends the token as `X-Foir-Token`, with the
+  dispatch's `X-Foir-Context`, and never sends `x-api-key`. api-public accepts
+  the token as a caller in its own right and builds the schema from the
+  capabilities the operation declared, so the generated client works unchanged
+  over it: queries, mutations and `execute<Op>`. `dispatch.token` is a provider
+  read before every request, not a string captured once. There is no key
+  fallback: a provider that yields nothing fails the request.
+
+  New on `@foir/sdk/data`: `FoirDispatchCredential`, `FoirKeyClientConfig` and
+  `FoirDispatchClientConfig`. New on `@foir/sdk/server`: `dispatch` on the
+  result of `requireScopedToken`, which is the token it verified as a ready
+  credential.
+
+  Two things a dispatch client does not do. It does not subscribe: the
+  subscription socket authenticates a key, an admin token or a customer bearer
+  and has no path for a dispatch token, so `onChange` and friends throw, naming
+  why. And it takes no key-side option (`apiKey`, `bearerToken`, `orgId`,
+  `channel`, the socket options), because the token carries its own customer,
+  organization and channel; each is a compile error and a runtime refusal.
+
+- `readDispatch(request)` and `OperationPayloadError` on `@foir/sdk/server`.
+
+  An operation endpoint had no typed reader for its own dispatch, and the body
+  is the run, not the input: reading it as the input finds nothing and refuses
+  every call on a missing field. `readDispatch` parses the body into
+  `OperationPayload`, checks the fields that identify a dispatch, and refuses
+  anything else with `OperationPayloadError` (`status` 400), naming what is
+  wrong. It keeps every key the platform sent, typed or not. `input` is always
+  an object: a run started with no input, which the platform sends as `null`,
+  reads as `{}`.
+
+- `FoirWriteResult<R>` on `@foir/sdk/data`: `{ record, replayed }`, what a
+  record write answers with.
+
+- `fetchFoirManifest(config, { operation })` asks for the surface an
+  operation's dispatch token is served instead of the credential's own, which
+  is described to a key that can author the operation (`operations:write`).
+  `fetchFoirManifest` takes `FoirRequestConfig`, the credential and transport
+  half of a client config, so a manifest is fetched without a generated module;
+  `FoirManifestRequestOptions` and `FoirRequestConfig` are new on
+  `@foir/sdk/data`.
+
+- `FoirRecordOwner` on `@foir/sdk/data`: `{ id, ownerId, ownerKind }`, what
+  `setOwner` answers with. An operation that declares `records:attribute:<model>`
+  hands a record to another customer with `foir.<model>.setOwner({ id, ownerId })`,
+  and names the owner of a record it creates with `create({ input, ownerId })`.
+  The answer carries the owner and not the record, because an operation acting
+  for the previous holder may no longer read it.
+
+- `orgUrl` names the organization a client acts in by the address of the page
+  it is for, sent as `X-Org-Url`, beside `orgId`. An app serving many
+  organizations from its own addresses (a path each, a subdomain each, or a
+  domain an organization brought) passes the page URL with the publishable key
+  it already ships, and the server finds the organization whose registered
+  address is the longest prefix of that URL. Also on `FoirRequestOptions` and
+  the auth ops' options. A URL no organization's address covers answers
+  `NOT_FOUND` as an unknown `orgId` does, and a request naming one takes the
+  origin lane.
+
+  ```ts
+  const foir = createFoirClient({ apiUrl, apiKey, generated, orgUrl: window.location.href });
+  ```
+
+  The same answer is available up front as the `resolveOrganizationAddress(url)`
+  query.
+
+### Changed
+
+- `requestOperation` (the editor SDK) no longer gives up after 60 seconds. A
+  blocking operation is now a direct call the platform ends at the operation's
+  own timeout, and the host answers every request with that outcome, so the
+  editor's own clock could only report as failed an operation that went on to
+  complete. The promise settles when the host answers.
+
+- **Breaking (types).** `OperationPayload` matches the platform's
+  `buildOperationPayload` field for field. Code that read a field the platform
+  never sent now fails to compile, which is the point:
+
+  - `credentials` and `config` are removed. The platform stopped sending them
+    when scoped-token dispatch replaced credentials in the body; an app reads
+    its secrets through the dispatch token.
+  - `executionId` is required. It is always sent.
+  - `content`, `record`, `triggerContext` and `callback` are optional and are
+    absent, never `null`, when not sent. `content` is an object.
+  - `OperationRecordContext` is `Record<string, unknown>`. The platform forwards
+    the block as the caller wrote it and shapes none of it; the previous `data`
+    and `metadata` members were never guaranteed.
+  - `OperationTrigger` is `{ type: 'ui' | 'api' | 'lifecycle' | 'schedule' }`,
+    the platform's own four values. `fieldKey`, `fieldType` and the `field`
+    trigger were never sent; caller context arrives in `triggerContext`.
+  - `OperationContext.userId` is a string that is always present (empty for a
+    hook's run), and `locale` is removed.
+  - `OperationPayload` takes a type parameter for `input`.
+  - `callback` is documented as ASYNC only. A blocking (SYNC) dispatch carries
+    no callback: the endpoint's response body is the result. `callback` gains
+    `causationChain`.
+
+- **Breaking (types).** `FoirClientConfig` is `FoirKeyClientConfig |
+  FoirDispatchClientConfig`. A config literal with an `apiKey` is unchanged.
+  Code that `extends FoirClientConfig` in an interface should extend
+  `FoirKeyClientConfig`, and code that reads `config.apiKey` off a
+  `FoirClientConfig` sees `string | undefined`.
+
+- A client with `dispatch` refuses a credential header in `headers`
+  (`x-api-key`, `Authorization`, `X-Foir-Token`, `X-Foir-Context`), whatever its
+  case. A key client's `headers` are unchanged.
+
+- `fetchFoirManifest` resolves the credential before the request rather than
+  inside it, so a `bearerToken` provider that throws surfaces its own error
+  instead of `[foir] network error`, as it already did on `/graphql`.
+
+- **`create`, `update` and `rename` resolve to `FoirWriteResult`, not the
+  record.** The data API's `create<Model>`, `update<Model>` and
+  `rename<Model>` now return `<Model>WritePayload`, the record beside
+  `replayed`, and a typed call returns that payload as it came. `replayed` is
+  true when the call's `idempotencyKey` was already used by an earlier attempt
+  of the same write: nothing was written this time, and `record` is as the
+  first attempt left it. Read the record from `.record`:
+
+  ```ts
+  const { record, replayed } = await foir.order.update({ where, data, idempotencyKey });
+  if (replayed) {
+    // The first attempt's answer. Nothing was applied by this call.
+  }
+  ```
+
+  A generated schema types these ops as `{ kind: 'write' }`; re-run
+  `foir types`.
+
+- `FoirUpdateManyPayload` carries `replayed`, with the same meaning.
+
+- **An option field's generated union is the declared values.** The data API
+  serves an option value exactly as the config declares it (`orderSlip`, not
+  `ORDERSLIP`), so the union `foir types` prints from the manifest is the
+  config's own strings. Re-run `foir types`; a comparison against the
+  upper-cased names no longer type-checks, and never matched a stored value.
+
+- **Schema drift compares the surface version, not the schema counter.**
+
+  `GET /v1/manifest` now serves `surfaceVersion`: a hash over exactly the
+  sections `foir types` reads, so it moves if and only if regenerating the types
+  would write a different file. Beside it, `surfaceHashes` carries the
+  components that version is folded from, one per model, namespace, union
+  expansion and the subscriptions. `schemaVersion` stays on the manifest and
+  keeps meaning what it always did server-side: the invalidation counter that
+  keys the ETag and the response cache.
+
+  The client used to pin generated types to that counter. Every write that
+  could change a response bumps it, so pushing an operation, a role or a key
+  reported drift, and under the strict default the next typed call threw,
+  though nothing the client prints had moved. A false alarm and a real one had
+  the same remedy, so nobody learned which they had. Now a drift is reported
+  only when the surface moved, and it names what moved: "Changed since: model
+  `page`." Every drift is real, so the message says `foir types` and no longer
+  suggests `strictSchemaDrift: false`, which is never the remedy.
+
+  What changes for a caller:
+
+  - The generated module exports `foirSurfaceVersion` and `foirSurfaceHashes`
+    in place of `foirSchemaVersion`, and `FoirGeneratedModule` requires them. A
+    module generated before this is refused at construction by name. **Re-run
+    `foir types`** with a current `@foir/cli` as part of the upgrade.
+  - `createFoirClient`'s `schemaVersion` option is now `surfaceVersion`, with
+    `surfaceHashes` beside it. Only a client wired field by field sets them;
+    one passing `generated` gets both from the module.
+  - `FoirSchemaDefinition.schemaVersion` is now `surfaceVersion: string`.
+  - `FoirSchemaDrift.generated` and `.server` are the two surface versions, as
+    strings, and `.changed` lists the components that moved (`models.page`).
+    An `onSchemaDrift` handler logging the numbers logs the hashes instead.
+  - `foirDriftIsActionable` (`@foir/sdk/live`) treats any difference as
+    actionable: a hash has no ahead or behind, and a rollback is another
+    surface like any other.
+  - `FoirManifest` gains `surfaceVersion` and `surfaceHashes`.
+
 ---
 
+### Fixed
+
+- A response in which no root field answered now throws `FoirRequestError`
+  with the server's errors. It used to count as partial data. Every
+  `execute<Op>` payload is nullable, so a failed operation run came back as
+  `{ r: null }` beside its error, and the typed call resolved to `null` with the
+  refusal only logged. The partial-errors default is unchanged wherever at least
+  one root field answered, and a null root with no error is still an answer.
+
 ## [0.10.0] — 2026-09-22
 
 Two breaking changes under the pre-1.0 note, so a MINOR: `fetchHostedSession`

package/README.md

@@ -79,9 +79,17 @@ and an artifact added to the generator later costs your call site nothing. A
 module missing one of those exports is a compile error naming it, not a quiet
 degrade: pass it whole, or do not pass it.
 
-The four fields it replaces (`schemaVersion`, `selections`,
+The fields it replaces (`surfaceVersion`, `surfaceHashes`, `selections`,
 `namespaceSelections`, `selectionUnions`) still work and still win where both
-are given, so an existing client keeps compiling and behaving exactly as it did.
+are given.
+
+**Drift is keyed on the surface.** The module records the `surfaceVersion` it
+was generated from: a hash over exactly what `foir types` reads, which moves only
+when regenerating would write a different file. Pushing an operation, a role or
+a key moves the server's invalidation counter and not the surface, so it is not
+drift. Publishing a field on a model the types include is, and the client
+refuses the next typed call with a message naming the model. The remedy is
+`foir types`; `strictSchemaDrift: false` never is.
 
 **Scalars are always complete**, so `post.title` is typed present and *is*
 present — there is no partial-`select` footgun. `include` adds a relation key,