@foir/sdk 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -108,6 +108,371 @@ 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.
 
+### Added
+
+- **An operation provisions an organization** (`@foir/sdk/app`).
+  `organizations.provision({ provisionId, name, parentId?, settings?, firstMember? })`
+  makes an organization with a customer as its first member, in the role the
+  project names for a founder, and answers `{ organizationId }`. It needs
+  `organizations:create`. With `settings: { modelKey, data }` it writes the
+  organization's settings record too and answers `settingsRecordId`; that
+  takes `records:write:<modelKey>`. Sending the same `provisionId` again with
+  the same request answers the same organization. New type:
+  `AppOrganizationProvision`. It needs the platform release that carries
+  `provisionOrganization`.
+- **An operation schedules the deletion of the organization it runs in**
+  (`@foir/sdk/app`). `organizations.scheduleDeletion()` takes nothing and
+  answers `{ organizationId, deletionScheduledAt, organizations }`. It needs
+  `organizations:delete`, reaches only the organization the run acts in, and
+  needs the platform release that carries `scheduleOrganizationDeletion`.
+- **`FoirWriteNoteArgs`** (`@foir/sdk/data`): the arguments of
+  `foir.ns.notes.writeNote`, the one field that writes a note for a signed-in
+  customer and for a visitor. It asks `notes:create` and needs the platform
+  release that carries `writeNote`. `foir.ns.notes` answers any field the
+  platform serves, so the call itself needs no new SDK.
+
+### Changed
+
+- **`FOIR_EVENTS_SCOPE` is `events:read`** (`@foir/sdk/server`). It was
+  `events:list.project`, the name the event log's permission had when a key
+  was written with scopes. A key is made with the permission catalogue's
+  names, where it is `events:read`, and that is what a refusal names. A key
+  minted under the older name holds `events:read` and needs no change.
+
+### Deprecated
+
+- **`FoirCreateMyNoteArgs`, `FoirSubmitAnonymousNoteArgs` and
+  `FoirAnonymousNoteReceipt`** (`@foir/sdk/data`). `createMyNote` and
+  `submitAnonymousNote` are the older names of `writeNote`. They still answer.
+  `<FoirFeedback>` writes through `createMyNote` in this release, and reads
+  whichever permission a refusal names, so it explains a role that is short
+  `notes:create` as it explained one short `notes:write`.
+
+## [0.20.0] — 2026-10-08
+
+An operation, and the token it is called with, say what they may do as
+`grants`, in the permission catalogue's names. Everything marked "with the
+platform release that carries it" needs the next promotion, and `latest` moves
+to this version then.
+
+### Added
+
+- **A token says what it carries as grants** (`@foir/sdk/server`).
+  `ScopedTokenClaims.grants` is the whole of what a verified token may do:
+  `records:read:<model>`, `records:write:<model>`, `records:create:<model>`,
+  `users:create` and the rest, as the
+  [operation permissions](https://docs.foir.dev/api/operation-permissions) page
+  lists them. It is always set. A token minted before the platform release
+  that says grants carries only the older claims, and `verifyScopedToken`
+  reads it as what those were worth, exactly as the platform does.
+
+  A record grant reaches the operation's own records: the project's, or those
+  of the customer a run acts for. `records:read.all:<model>`, and the write,
+  delete and publish forms like it, reach every owner's records of the model.
+  An older token's write of a model was every owner's, so it is read as
+  `records:write.all:<model>` and `records:create:<model>`, and takes that
+  model's read, delete and publish to `.all` with it.
+
+  `recordsCreateModels(claims)` is the models a token may make records of.
+
+- **The grants a manifest may declare** (`@foir/sdk/app`). `APP_GRANTS` and
+  `AppGrant` are the grants an operation declares as written, and
+  `APP_RECORD_GRANT_PREFIXES` and `AppRecordGrantPrefix` the ones it declares
+  once per model, the every-owner forms (`records:read.all:` and the like)
+  among them.
+
+- **An embedded page reads what its token carries as grants**
+  (`@foir/sdk/placement`). `session.grant.grants` is what the token carries, in
+  the permission catalogue's names, and `session.grant.withheldGrants` is each
+  grant the placement declares that it does not carry whole, with why. Both
+  are always set: a console of the release before sends the two older lists
+  alone, and the session reads `grants` from those.
+
+- **A feature can say which notification category it sends under**
+  (`@foir/sdk/app/contract`). `Feature.notificationCategory` names the string
+  setting that holds the category's key, and the category the app proposes
+  (`key`, `name`, `description`, `optIn`). The setup then offers the project's
+  categories, or makes the app's own, in place of a key typed by hand, and the
+  platform holds a running install's setting to a category the project has.
+
+- **An app can say what connecting changes** (`@foir/sdk/app/contract`).
+  `Credentials.connectNotice` is the app's own words, shown to the operator
+  beside the step that connects their account and, for an install the vendor
+  started, before the install is confirmed. A vendor that keeps one live
+  connection per account (Shopify, per store) says here that connecting moves
+  it from any other project. Empty when there is nothing to say.
+
+- **The roles a signed-in customer holds, and what they may do**
+  (`@foir/sdk/auth`, `@foir/sdk/react`). A storefront can now ask which customer
+  roles the signed-in customer holds and show the page to match, where before
+  it had to treat one of a role's permissions as a stand-in for the role.
+
+  - `getSessionAccess(adapter, env)` and `customerAccess(env, { bearerToken })`
+    return a `FoirAccess`: the customer's id, the keys of the roles they hold
+    (`roles`), and everything they may do through the key (`scopes`). Plain
+    data, so a loader can return it. `null` when nobody is signed in.
+  - `hasRole(access, key)` and `hasScope(access, scope)` read it. `hasScope`
+    applies the platform's own rule: `records:write` covers
+    `records:write:post`, `records:read.all` covers `records:read`, and never
+    the reverse.
+  - `requireRole(adapter, env, key)` and `requireScope(adapter, env, scope)`
+    guard a server route. They return the access, or throw
+    `FoirAccessDeniedError` with a `reason` of `signed_out`, `role_not_held`,
+    `roles_unknown` or `scope_not_held`.
+  - `useFoirAccess()` gives a component `hasRole(key)`, `hasScope(scope)`, a
+    `status` and `reload()`. It asks once however many components use it, and
+    again when the session refreshes.
+
+  The platform resolves the roles on every request, so nothing is cached here
+  and a role taken away is gone the next time it is asked.
+
+  `roles` is `null`, not an empty list, when the platform did not say which
+  roles the customer holds. `hasRole` answers false for it and `requireRole`
+  refuses with `roles_unknown`, so an outage is never read as "not staff". A
+  platform that does not serve the field yet reads the same way: the role
+  helpers need the platform release that carries it.
+
+  These decide what a page shows. They protect nothing: the platform checks
+  every request whatever the page offers.
+
+  `AUTH_OPS` gains `whoami`, and `FoirContextValue` gains `access`,
+  `accessStatus`, `loadAccess` and `ensureAccess`.
+
+- **A save says when it made a record the operation may not read**
+  (`@foir/sdk/app`). `records.upsert` and `records.customer.save` answer
+  `fieldsWithheld`. It is true when the operation declared the create of a
+  model and not the read: the save made the record, and `record` carries its
+  `id` and `modelKey` and nothing else. The record is not empty.
+
+### Changed
+
+- **Breaking, with the platform release that carries it: an operation is
+  called with what it declares and nothing else** (`@foir/sdk/app`). The token
+  used to carry the read of its owner's secrets whatever the operation
+  declared. An operation whose handler reads the app's credentials
+  (`install.credentials()`) declares `appsecrets:read`, and a project's own
+  operation that reads a project secret declares `secrets:read`. An installed
+  app's operations are given the one they could use, so an installed app keeps
+  running; a manifest served from then on says it.
+
+- **Breaking, with the platform release that carries it: erasing a customer
+  takes `identities:delete`** (`@foir/sdk/app`). `records.customer.erase` needed
+  `users:create` beside the delete and the read of the model, and now needs
+  `identities:delete` there. `APP_GRANTS` carries it, with `files:delete`,
+  `notifications:read` and every owner's files (`files:read.all`,
+  `files:write.all`, `files:delete.all`), which a manifest may now declare.
+  `verifyScopedToken` reads a token minted before, that carried the customer
+  create beside the delete of a model, as holding `identities:delete`, as the
+  platform does.
+
+- **Breaking, with the platform release that carries it: an operation declares
+  `grants`** (`@foir/sdk/app`, `@foir/sdk/app/contract`). A manifest's
+  operation says what it may do as `grants`, in the permission catalogue's
+  names, and the platform refuses one that still declares `capabilities`,
+  saying what to declare. An installed app keeps running on what it was
+  installed with; it is installing and updating that need the new manifest.
+
+  Most names are written as they were. These changed:
+
+  | Before | Now |
+  |---|---|
+  | `config:read` | `appconfig:read` |
+  | `secrets:read.app`, `secrets:put.app`, `secrets:list.app`, `secrets:delete.app` | `appsecrets:read`, `appsecrets:put`, `appsecrets:list`, `appsecrets:delete` |
+  | `files:list` | `files:read` |
+  | `customers:write` | `users:create` |
+  | `customers:read` | `users:read.all` |
+  | `customers:read:named` | `users:read.named` |
+  | `customers:read:identity` | `identities:read` |
+  | `notifications:write` | `notifications:write.named` |
+  | `records:write:<model>` | `records:write:<model>` and `records:create:<model>` |
+
+  The last row is a change in what the name means. `records:write:<model>`
+  changes a record that is there, and making one is `records:create:<model>`.
+  An operation that does both declares both. `records.upsert` and
+  `records.customer.save` are let through on either, and the platform asks for
+  the one the save turns out to need.
+
+- **Breaking, with the platform release that carries it: a full-page placement
+  declares `grants`** (`@foir/sdk/app/contract`, `@foir/sdk/placement`). A
+  placement in a manifest says what its page acts with as `grants`, and the
+  platform refuses one that still declares `scopes`, saying what to declare.
+  An installed app's page keeps working on what it was installed with.
+
+  The names are the ones a team member's role is composed from, so three
+  things change in what a placement writes:
+
+  - **Every owner's records are written `.all`.** `records:read:order` was
+    every order and is now the operator's own. Declare
+    `records:read.all:order`.
+  - **A write no longer includes its read.** `records:write:order` also read
+    and created, and `apps:write` also read apps. Declare each one the page
+    uses: `records:write.all:order`, `records:read.all:order`,
+    `records:create:order`.
+  - **A wildcard and a permission that gives others are refused**, as `*`
+    always was.
+
+  The token then carries what the placement declares and the operator holds,
+  permission by permission. An operator who holds part of a declared grant is
+  given that part, where before the whole name was withheld.
+
+- **`session.can` answers by what the token covers** (`@foir/sdk/placement`).
+  It was an exact match on the spelling. `can('records:read.all:order')` is
+  now true for a token that carries `records:read.all`, as Foir's API would
+  answer. A name the token carries as it is written is still held.
+
+- **`PlacementGrant.grantedScopes` and `PlacementGrant.withheld` are
+  deprecated** (`@foir/sdk/placement`). They are still set, and say what
+  `grants` and `withheldGrants` say.
+
+- **Breaking, with the platform release that carries it: `whoami` answers
+  `grants`** (`@foir/sdk/app`). `AppWhoami.capabilities` is gone and
+  `AppWhoami.grants` takes its place, and `AppWhoami.models` gains `create`.
+
+- **Breaking: the older claims on `ScopedTokenClaims` are optional**
+  (`@foir/sdk/server`). `cap`, `rrm` and `rwm` are still on a token the
+  platform mints, in the older names, and are marked deprecated: they never
+  say more than `grants` and can say less. `recordsReadModels` and
+  `recordsWriteModels` now read `grants`, so `recordsWriteModels` is the models
+  a token may change records of, and no longer the ones it may make them in.
+  Code that builds a `ScopedTokenClaims` by hand sets `grants`.
+
+- **Breaking: `AppUpsertResult` has a new required field, `fieldsWithheld`.**
+  Code that builds one by hand, a test double for `records.upsert` for
+  instance, has to set it.
+
+- **Breaking, with the platform release that carries it: only making a record
+  takes no read.** A write that finds a record already there is charged the
+  read of it as well. This is the platform's rule and reaches every caller,
+  whatever version of this package they run.
+
+  - `create` and `submit` (`@foir/sdk/data`) ask for the whole record by
+    default. A credential that may create records of a model and may not read
+    them is refused that, before anything is written, and told the read it
+    lacks. Pass `pick: ['_id']` to make the record and be answered with its id.
+  - `update`, `rename`, `delete`, `publish` and `unpublish` need
+    `records:read` for the model beside their own permission.
+  - An operation that declares the create of a model and not the read
+    (`@foir/sdk/app`) still makes its records. `records.upsert` landing on a
+    record already there, `records.customer.save` likewise, `records.delete`,
+    `records.refresh`, `records.rename` and `records.updateMany` are refused
+    until it declares the read too.
+
+- **Breaking, with the platform release that carries it: `records.customer.erase`
+  needs the delete of the model** (`@foir/sdk/app`). An erase removes a record,
+  so the operation declares `records:delete` and `records:read` for the model,
+  and `users:create`. Until now the grant to save the record was enough. An
+  operation that erased on its write lane is refused until it declares the
+  delete. Nothing is taken from holding a write.
+
+- **Breaking, with the platform release that carries it: a role in
+  `myOrganizations` carries `grants`** (`@foir/sdk/auth`).
+  `MyOrganizationRole.permissions` is gone and `MyOrganizationRole.grants`
+  takes its place: what the role gives, in the permission catalogue's names. A
+  grant stands for itself, so changing a record and creating one are two
+  names (`records:write`, `records:create`), reading every customer's records
+  is `records:read.all`, and staffing an organization is `members:read` and
+  `members:write`. Code that looked for `organizations:staff` or
+  `records:list.all` in a role's list looks for the new names.
+
+- **Breaking, with the platform release that carries it: `customers.byIdentity`
+  and `customers.identities` need `identities:read`, declared by name**
+  (`@foir/sdk/app`). The read of every customer, `users:read.all`, no longer
+  includes them.
+
+### Removed
+
+- **Breaking: `APP_CAPABILITIES`, `APP_RECORD_CAPABILITY_PREFIXES`,
+  `AppCapability` and `AppRecordCapabilityPrefix`** (`@foir/sdk/app`). They
+  listed the names an operation was declared with before, which the platform
+  now refuses. `APP_GRANTS`, `APP_RECORD_GRANT_PREFIXES`, `AppGrant` and
+  `AppRecordGrantPrefix` list what it declares now.
+
+## [0.19.0] — 2026-10-02
+
+Published under npm's `next` tag from `dev`. The data client's change needs no
+platform release. `setConsent` by email calls a field the platform serves from
+the next promotion; `latest` moves to this version then.
+
+### Changed
+
+- **Breaking: schema drift by itself no longer refuses a typed call**
+  (`@foir/sdk/data`). What `strictSchemaDrift` refuses has changed; its name
+  and its default have not.
+
+  Before, a client built with a generated module refused every typed call,
+  with `FoirSchemaDriftError`, from the moment it saw the server serving another
+  surface version. That version is a hash over everything `foir types` reads,
+  so it moves whenever the surface grows. A field published on a model, or an
+  op the platform added to every model, made every deployed client refuse its
+  second typed call, though nothing it prints had changed.
+
+  Now the drift is reported once, exactly as before (`onSchemaDrift`, or the
+  `console.warn`), and it refuses nothing by itself. When the manifest arrives
+  the client compares its generated trees with the served ones, and refuses a
+  typed call only when something that call depends on is no longer served the
+  way the module describes it:
+
+  - its op is gone, or the op's root field or result kind changed;
+  - an argument the module declares is gone, or has a type the generated one no
+    longer fits, or the op now requires an argument the module does not know;
+  - a field its selection names is gone or changed shape, in the model the op
+    returns or in a union that model embeds;
+  - a relation the call includes changed target, became a list or a
+    connection, or its target model lost a field.
+
+  Anything added refuses nothing: a model, a namespace, an op, an optional
+  argument, a field, a relation, a union member, a subscription. An argument
+  that went from required to optional refuses nothing either.
+
+  `FoirSchemaDriftError`'s message now names what the refused call depends on
+  (`models.order.selection.status (no longer served)`), and still names
+  `foir types` as the remedy. The warning for a drift that broke nothing says
+  the surface has grown and that every typed call keeps working.
+
+  Unchanged: `strictSchemaDrift: false` turns refusal off entirely, the first
+  call on a client is never blocked on the manifest, `raw()` is never refused,
+  and `checkSchemaDrift: false` skips the fetch. `createFoirDriftHandler` in
+  `@foir/sdk/live` still resyncs on every drift, whether or not anything is
+  incompatible.
+
+  A client wired by hand with `surfaceVersion` and no `selections` prints from
+  the served manifest, so it has nothing older to compare and is no longer
+  refused on drift.
+
+  Migration: none for an app that only catches `FoirSchemaDriftError`. An app
+  that used the refusal to learn that its module was stale in ANY way should
+  read `onSchemaDrift`, which still fires for every drift, or gate on
+  `foir types --check` in CI.
+- **Breaking: `FoirSchemaDrift` has a new required field, `incompatible`**
+  (`@foir/sdk/data`). Code that reads a drift is unaffected. Code that builds
+  one by hand, for example to test a handler given to `onSchemaDrift` or made by
+  `createFoirDriftHandler`, must add `incompatible: []`.
+- **Breaking (types): `AppConsentChange` names its customer one way**
+  (`@foir/sdk/app`). It was an interface with a required `customerId`. It is
+  now a type that holds a `customerId` or an `email`, never both. A change
+  written as `{ customerId, ... }` is unaffected. An interface that extended
+  `AppConsentChange` no longer compiles: intersect with it instead.
+
+### Added
+
+- `notifications.setConsent` takes `email` in place of `customerId`
+  (`@foir/sdk/app`), for an opt-in from somebody who may have no customer yet,
+  such as a sign-up form. The platform finds the customer holding the address
+  at the install's level, or makes one, together with the change, so a change
+  it refuses (a category the project does not have, a confirmation email the
+  project cannot send) leaves no customer behind. Finding or making the
+  customer first with `customers.ensure` did. The operation must declare
+  `customers:write` as well as `notifications:consent`. `AppConsentSubject` is
+  exported.
+
+- `FoirSchemaDrift.incompatible`: what the generated module describes that the
+  server no longer serves that way, as sorted paths into the manifest
+  (`models.order.selection.status`, `models.order.ops.update`,
+  `namespaces.search.ops.searchRecords.args.query`,
+  `models.order.relations.customer`, `selectionUnions.Block.HeroBlock.title`).
+  Empty when the surface has only grown. `changed` keeps its meaning: what
+  moved, not what broke.
+
 ## [0.18.0] — 2026-10-02
 
 Published under npm's `next` tag from `dev`, because it calls fields the

package/README.md

@@ -88,7 +88,14 @@ was generated from: a hash over exactly what `foir types` reads, which moves onl
 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
+reports it once, naming the model.
+
+**Drift does not stop a call.** A surface that has grown still answers every
+document the module prints. A typed call is refused, with `FoirSchemaDriftError`,
+only when something it depends on is no longer served as generated: a field its
+selection names, its op, one of its arguments, or the target of a relation it
+includes. The message names that part, and `drift.incompatible` lists every
+such part as a path (`models.order.selection.status`). The remedy is
 `foir types`; `strictSchemaDrift: false` never is.
 
 **Scalars are always complete**, so `post.title` is typed present and *is*

package/dist/app/client.d.ts

@@ -144,11 +144,22 @@ export interface AppRecord {
     unreadable: string[];
 }
 export interface AppUpsertResult {
-    /** The record as the platform holds it now. */
+    /**
+     * The record as the platform holds it now. When `fieldsWithheld` is true it
+     * is only which record it is, its `id` and `modelKey`: see there.
+     */
     record: Record<string, unknown>;
     /** The platform's own id for it, when the answer carried one. */
     id: string | null;
     created: boolean;
+    /**
+     * True when the save made a record the operation may not read: it declared
+     * the write for the model and not the read. Making a record takes no read, so
+     * the save worked, and its answer carries which record it made and nothing of
+     * it. The record is not empty. A save that lands on a record already there
+     * takes the read as well, and is refused without it.
+     */
+    fieldsWithheld: boolean;
     /** True when nothing was written because Foir already holds a newer copy (`sourceModifiedAt`). */
     stale: boolean;
 }
@@ -186,8 +197,56 @@ export interface AppNotification {
     /** Makes the send safe to repeat: the same key from the same operation tells the customer once. */
     idempotencyKey?: string;
 }
-export interface AppConsentChange {
+/** An organisation an operation makes for one of its customers. */
+export interface AppOrganizationProvision {
+    /**
+     * Yours to choose and to keep. Sending the same one again with the same
+     * request answers the same organisation and makes no second, so a run that
+     * stopped half way is finished by running it again. A different request
+     * under an id already used is refused.
+     */
+    provisionId: string;
+    name: string;
+    /** The organisation this one is made beneath. Left out, it is made at the top of the project. */
+    parentId?: string;
+    /**
+     * The organisation's settings record, written with it: a record of the
+     * model the project keeps an organisation's settings in (a singleton on the
+     * organisation owner plane). The operation declares that model's write,
+     * `records:write:<modelKey>`, beside `organizations:create`. It is the one
+     * record of an organisation an operation writes without running in it.
+     */
+    settings?: {
+        modelKey: string;
+        data: Record<string, unknown>;
+    };
+    /**
+     * The customer who becomes its first member. They are given the role the
+     * project names for an organisation's founder, in its settings: the
+     * operation chooses who, and the project decides what they hold.
+     */
+    firstMember?: {
+        customerId: string;
+    };
+}
+/**
+ * Who a consent change is for: a customer whose id the app holds, or an
+ * address.
+ *
+ * By `email`, the customer holding the address at the operation's level is
+ * found, or made, together with the change, so a change the platform refuses
+ * leaves no customer behind. It is for an opt-in from somebody who may have no
+ * customer yet (a sign-up form), and the operation must declare
+ * `users:create` as well as `notifications:consent`.
+ */
+export type AppConsentSubject = {
     customerId: string;
+    email?: undefined;
+} | {
+    email: string;
+    customerId?: undefined;
+};
+export type AppConsentChange = AppConsentSubject & {
     /** 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`). */
@@ -215,17 +274,18 @@ export interface AppConsentChange {
      * email is written in it when the customer has stated none of their own.
      */
     locale?: 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. */
+    /** What the token carries, as grants in the permission catalogue's names. */
+    grants: string[];
+    /** The models its record grants name, by permission. Changing a record and making one are two. */
     models: {
         read: string[];
         write: string[];
+        create: string[];
         delete: string[];
         publish: string[];
     };
@@ -248,17 +308,17 @@ export interface AppClient {
     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`. */
+        /** The operator's settings and mappings. Needs `appconfig:read`. */
         config(): Promise<AppInstallConfig>;
         /**
          * The install's credential, by the manifest's credential field names.
-         * Values are always strings. Needs `secrets:read.app`.
+         * Values are always strings. Needs `appsecrets:read`.
          */
         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`.
+         * `appsecrets:put`.
          */
         writeCredentials(values: Record<string, string>): Promise<void>;
         /** Report the install's health. Needs `status:write`. See {@link AppStatusReport}. */
@@ -268,7 +328,9 @@ export interface AppClient {
     records: {
         /**
          * Write the record at a natural key, making it when there is none.
-         * `ownerId` names the customer it belongs to (needs
+         * Changing the record there needs `records:write:<model>` and making one
+         * needs `records:create:<model>`, so an operation that does both declares
+         * both. `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.
@@ -383,7 +445,9 @@ export interface AppClient {
             /**
              * 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.
+             * else is attached to them. It removes a record, so it needs
+             * `records:delete` and `records:read` for the model, and
+             * `identities:delete`. The grant to save the record is not enough.
              */
             erase(model: string, identity: string): Promise<AppCustomerEraseResult>;
         };
@@ -392,7 +456,7 @@ export interface AppClient {
         /**
          * 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`.
+         * `users:create`.
          *
          * `verified` says whether that address is one the customer has proved is
          * theirs. A customer this call makes has not, and neither has one an
@@ -407,14 +471,14 @@ export interface AppClient {
         }>;
         /**
          * One customer by id, or null when there is none at the install's level.
-         * Needs `customers:read:named`, or `customers:read`.
+         * Needs `users:read.named`, or `users:read.all`.
          */
         get(id: string): Promise<AppCustomer | null>;
         /**
          * The customer who has this email at the install's level, or null. The
          * exact address, as `ensure` matches it, and nothing wider: it finds one
-         * customer and never searches. Needs `customers:read:named`, or
-         * `customers:read`.
+         * customer and never searches. Needs `users:read.named`, or
+         * `users:read.all`.
          */
         byEmail(email: string): Promise<AppCustomer | null>;
         /**
@@ -423,7 +487,8 @@ export interface AppClient {
          * of its customers. The identity is the subject of the customer's sign-in
          * with that system, and it is resolved through the customer sign-in the
          * install pairs (`install.config().customerSignIn`) and no other. Never
-         * matched by email. Needs `customers:read:identity`, or `customers:read`.
+         * matched by email. Needs `identities:read`, declared by name:
+         * `users:read.all` does not include it.
          */
         byIdentity(identity: string): Promise<string | null>;
         /**
@@ -431,13 +496,13 @@ export interface AppClient {
          * holds at the app's own system, most recently seen first, through the
          * same pairing. Empty when they have never signed in that way. For an app
          * acting on an event that names the Foir customer. Needs
-         * `customers:read:identity`, or `customers:read`.
+         * `identities:read`, declared by name.
          */
         identities(customerId: string): Promise<string[]>;
         /**
          * The customers at the install's level, a page at a time, newest first.
-         * Needs `customers:read`: an operation declaring only
-         * `customers:read:named` reads the customers it names and is refused the
+         * Needs `users:read.all`: an operation declaring only
+         * `users:read.named` reads the customers it names and is refused the
          * list.
          */
         list(query?: AppCustomerList): Promise<{
@@ -446,8 +511,47 @@ export interface AppClient {
             endCursor: string | null;
         }>;
     };
+    organizations: {
+        /**
+         * Make an organisation, with its settings record and a customer as its
+         * first member. Needs `organizations:create`, and for `settings` the write
+         * of the settings model. Sign-up is the use: one operation creates the
+         * customer (`customers.ensure`) and then the organisation that is theirs.
+         *
+         * The first member is given the role the project names for an
+         * organisation's founder. A project that names none refuses it, saying
+         * which setting to fill in.
+         *
+         * Safe to run again: the same `provisionId` with the same request answers
+         * the same organisation and the same settings record.
+         */
+        provision(organization: AppOrganizationProvision): Promise<{
+            organizationId: string;
+            settingsRecordId?: string;
+        }>;
+        /**
+         * Schedule the deletion of the organisation this run acts in, with every
+         * organisation beneath it. Needs `organizations:delete`. It takes no
+         * organisation: the one whoever triggered the run stands in is the only
+         * one it reaches, and a run that acts in none is refused. So is a run
+         * that acts for nobody who is a member of that organisation.
+         *
+         * The organisation stops being active at once, so nothing that stands in
+         * it is served after this answers. Nothing is removed until
+         * `deletionScheduledAt`, and the project can resume it until then. This
+         * call cannot.
+         */
+        scheduleDeletion(): Promise<{
+            organizationId: string;
+            deletionScheduledAt: string | null;
+            organizations: {
+                id: string;
+                name: string;
+            }[];
+        }>;
+    };
     notifications: {
-        /** Tell a customer something. Needs `notifications:write`. */
+        /** Tell a customer something. Needs `notifications:write.named`. */
         send(notification: AppNotification): Promise<void>;
         /**
          * Set a named customer's consent in an opt-in category. Needs
@@ -458,6 +562,10 @@ export interface AppClient {
          * been sent a link, or was sent one recently, and the preference turns on
          * when they follow it. The answer is the same whether or not the address
          * already had a customer.
+         *
+         * Name the customer by `customerId`, or by `email` for somebody who may
+         * have no customer yet: the platform finds or makes them with the change,
+         * and that also needs `users:create`.
          */
         setConsent(change: AppConsentChange): Promise<{
             stale: boolean;
@@ -477,7 +585,7 @@ export interface AppClient {
          *
          * 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.
+         * carries that operation's grants and no other's.
          */
         start(operationKey: string, options?: AppOperationStart): Promise<AppStartedOperation>;
     };