@foir/sdk 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -108,6 +108,336 @@ 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.
+
+- **A server says where its visitor is** (`@foir/sdk/data`). `visitor` takes
+  an object as well as an address: `{ address, country, latitude, longitude }`,
+  or a function that yields one for each request. The address is sent as
+  `X-Foir-Visitor-IP`, as before. The country and the coordinates are attached
+  to every read, in its `contexts`, so location targeting is decided by where
+  the visitor is and not by where your server is. Coordinates are sent at two
+  decimal places, and latitude and longitude go together or not at all. The
+  visitor is resolved once for a request, so the header and the read name the
+  same one. A string is still the address alone. New type: `FoirVisitor`, and
+  `country` and `location` on `FoirResolveContext`. It needs a key holding
+  `visitors:forward`, and the platform release that takes `contexts.country`
+  and `contexts.location`: an earlier platform refuses a read that names them.
+
+### Changed
+
+- **Breaking: an app client refuses an admin key** (`@foir/sdk/data`).
+  `createFoirClient` given a key that begins `foir_adm_` throws before any
+  request. An admin key is a machine's own: nobody signs in through it, and an
+  app never holds one. Build the client from a publishable key, or from a
+  server key on the server that renders your pages. A machine that acts for
+  itself uses `createServerClient` from `@foir/sdk/server`. A key minted
+  before a key had a kind (`sk_`) is not refused here.
+- **A key's kind is read from its prefix in one place.** A key is publishable
+  (`foir_pub_`), server (`foir_srv_`) or admin (`foir_adm_`), and a key minted
+  earlier is `pk_`, `sk_` or `tc_`. Only a publishable key, in either format,
+  is named in a URL and takes the shared cache lane. Earlier versions looked
+  for the letters `pk_` alone, so a `foir_pub_` key was sent to the origin and
+  missed the shared cache.
+- **`visitor` takes a server key** (`@foir/sdk/data`). A client that names the
+  visitor it calls for is built from a server key (`foir_srv_`), or from a
+  secret key minted before a key had a kind. Earlier versions looked for the
+  letters `sk_` alone and refused a server key. A publishable key is still
+  refused `visitor`, in either format.
+- **The events client takes an admin key** (`@foir/sdk/server`).
+  `createEventsClient` refuses a publishable key and a server key by name, and
+  takes an admin key (`foir_adm_`) or a secret key minted earlier.
+- **`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.
+
+### Removed
+
+- **Breaking: `ScopedTokenClaims` has no `cap`, `rrm` or `rwm`**
+  (`@foir/sdk/server`). The platform no longer writes the claims a token
+  carried before it said its grants. Read `grants`, or `recordsReadModels`,
+  `recordsWriteModels` and `recordsCreateModels`.
+- **Breaking: `PlacementGrant` has no `grantedScopes` or `withheld`**
+  (`@foir/sdk/placement`). A console sends what a page's token carries as
+  `grants` and what it was refused as `withheldGrants`, and no longer sends
+  the same two lists under their older names. Read `session.grant.grants`, or
+  ask `session.can`.
+- **Breaking: `verifyScopedToken` refuses a token that does not say its
+  grants** (`@foir/sdk/server`), with `the token says no grants`, as the
+  platform refuses it. It used to read such a token as what its older claims
+  were worth. `requireScopedToken` answers it 401 like any token that does not
+  verify.
+
+### 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

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,6 +197,38 @@ export interface AppNotification {
     /** Makes the send safe to repeat: the same key from the same operation tells the customer once. */
     idempotencyKey?: string;
 }
+/** 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.
@@ -194,7 +237,7 @@ export interface AppNotification {
  * 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
- * `customers:write` as well as `notifications:consent`.
+ * `users:create` as well as `notifications:consent`.
  */
 export type AppConsentSubject = {
     customerId: string;
@@ -236,12 +279,13 @@ export type AppConsentChange = AppConsentSubject & {
 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[];
     };
@@ -264,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}. */
@@ -284,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.
@@ -399,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>;
         };
@@ -408,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
@@ -423,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>;
         /**
@@ -439,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>;
         /**
@@ -447,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<{
@@ -462,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
@@ -477,7 +565,7 @@ export interface AppClient {
          *
          * 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 `customers:write`.
+         * and that also needs `users:create`.
          */
         setConsent(change: AppConsentChange): Promise<{
             stale: boolean;
@@ -497,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>;
     };