@calimero-network/mero-js 26.11.0 → 27.0.1

package/dist/cloud-v2/client.js

@@ -0,0 +1,646 @@
+/**
+ * Client for Calimero 1.0, the confidential cloud: one app = one replicated log on
+ * attested nodes; this client verifies the node, seals every request to it,
+ * signs people in with passkeys and machines with API keys.
+ *
+ * ```ts
+ * const cloud = new CalimeroClient({ baseUrl, policy: { release: { minReleaseVersion: '2.3.109' } } });
+ * await cloud.signIn(browserPasskey());
+ * const { result } = await cloud.call(appId, 'set', { key: 'a', value: '1' });
+ * ```
+ */
+import { SealedTransportError, createSealedFetch } from '../sealed/sealed.js';
+import { fetchAttestedKey } from './attestation.js';
+import { CalimeroError, ConfirmCancelled, ConfirmRequired, UnavailableError, errorFrom } from './errors.js';
+import { b64url, fromB64url } from './passkey.js';
+export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, NotFound, TrapError, UnavailableError, errorFrom, } from './errors.js';
+/** One URL path segment, so an id cannot reach another route. */
+function seg(value) {
+    return encodeURIComponent(value);
+}
+/**
+ * The node refuses an envelope past its 64 MiB sealed cap with `413` in the
+ * clear, before opening it, so the refusal arrives as the transport's. To the
+ * caller it is the API's `TOO_LARGE`, as the Rust client reports it.
+ */
+function sealedError(error) {
+    if (error instanceof SealedTransportError && error.status === 413) {
+        return errorFrom(413, {
+            error: 'TOO_LARGE',
+            message: error.message.replace(/^Sealed request refused: /, ''),
+        });
+    }
+    return error;
+}
+/** Read a refused response's body and map it ({@link errorFrom}). */
+async function refusal(response) {
+    const text = await response.text().catch(() => '');
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        body = { message: text };
+    }
+    return errorFrom(response.status, body, response.headers.get('retry-after'));
+}
+/** Server-sent event frames from a response body: `{ id, kind, data }` each, `data` parsed as JSON when it is. */
+async function* sseFrames(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            return;
+        buffer += decoder.decode(value, { stream: true });
+        let cut;
+        while ((cut = buffer.indexOf('\n\n')) >= 0) {
+            const frame = buffer.slice(0, cut);
+            buffer = buffer.slice(cut + 2);
+            let id = '';
+            let kind = '';
+            let data = '';
+            for (const line of frame.split('\n')) {
+                if (line.startsWith('id:'))
+                    id = line.slice(3).trim();
+                else if (line.startsWith('event:'))
+                    kind = line.slice(6).trim();
+                else if (line.startsWith('data:'))
+                    data += line.slice(5).trim();
+            }
+            if (!kind && !data)
+                continue;
+            let parsed = data;
+            try {
+                parsed = JSON.parse(data);
+            }
+            catch {
+                /* plain text */
+            }
+            yield { id, kind, data: parsed };
+        }
+    }
+}
+/** Bytes as lower-case hex. */
+function toHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * A key for a call the caller gave none, made once so every retry shares it:
+ * `node:c-` and 16 random bytes in base64url without padding, as the Rust
+ * client mints it. It only has to outlive this client's own retries, so it
+ * takes the node's short-lived class: a key starting `node:` is kept 10
+ * minutes, a caller's own key 24 hours.
+ * `getRandomValues`, not `randomUUID`, which a page outside a secure context lacks.
+ */
+function newIdempotencyKey() {
+    return `node:c-${b64url(crypto.getRandomValues(new Uint8Array(16)))}`;
+}
+export const DEFAULT_RETRY = { retries: 6, baseDelayMs: 200, maxDelayMs: 2000 };
+/** The backoff before retry `retry` (0 for the first): `baseDelayMs` doubling, at most `maxDelayMs`. */
+export function retryDelayMs(retry, options) {
+    return Math.min(options.baseDelayMs * 2 ** retry, options.maxDelayMs);
+}
+export class CalimeroClient {
+    constructor(options) {
+        /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
+        this.networkFailures = new WeakSet();
+        this.base = options.baseUrl.replace(/\/+$/, '');
+        this.retry = { ...DEFAULT_RETRY, ...options.retry };
+        const given = options.fetch ?? ((input, init) => fetch(input, init));
+        // `fetch` rejects with a `TypeError` when it gets no answer: the connection
+        // was refused, reset or dropped before the response. The sealed fetch passes
+        // that rejection on unchanged, so it is recognised here, at its source, and
+        // not by its type alone (a bad URL is a `TypeError` too, and is not retried).
+        const raw = async (input, init) => {
+            try {
+                return await given(input, init);
+            }
+            catch (error) {
+                if (error instanceof TypeError)
+                    this.networkFailures.add(error);
+                throw error;
+            }
+        };
+        this.raw = raw;
+        this.sealed = createSealedFetch({
+            baseUrl: this.base,
+            transportPublicKey: () => fetchAttestedKey(this.base, options.policy, raw),
+            fetch: raw,
+        });
+    }
+    /** Authenticate every request with an API key. */
+    useApiKey(key) {
+        this.auth = key;
+        this.current = undefined;
+    }
+    useSession(session) {
+        this.auth = session.sessionToken;
+        this.current = session;
+    }
+    get session() {
+        return this.current;
+    }
+    async request(method, path, body, raw, contentType = 'application/wasm') {
+        const headers = {};
+        if (this.auth)
+            headers.authorization = `Bearer ${this.auth}`;
+        let payload;
+        if (raw) {
+            headers['content-type'] = contentType;
+            payload = raw;
+        }
+        else if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+            payload = JSON.stringify(body);
+        }
+        try {
+            return await this.sealed(`${this.base}/${path}`, { method, headers, body: payload });
+        }
+        catch (error) {
+            throw sealedError(error);
+        }
+    }
+    async json(method, path, body, raw, contentType) {
+        const response = await this.request(method, path, body, raw, contentType);
+        if (!response.ok)
+            throw await refusal(response);
+        const text = await response.text();
+        return (text ? JSON.parse(text) : {});
+    }
+    /**
+     * {@link json} for a call or a view (D70): while the node answers 503 or
+     * cannot be reached, the same request, with the same idempotency key, is sent
+     * again after {@link retryDelayMs} (or the pause the node asked for, if
+     * longer), at most `retries` times. Every other answer is final. The last
+     * failure surfaces as {@link UnavailableError}: the node's 503, or reason
+     * `network` for a connection that failed, whose `committed` is `'unknown'`.
+     * `retries` 0 sends the request exactly once.
+     */
+    async retried(method, path, body, retries = this.retry.retries) {
+        for (let attempt = 0;; attempt++) {
+            let unavailable;
+            try {
+                return await this.json(method, path, body);
+            }
+            catch (error) {
+                if (error instanceof UnavailableError)
+                    unavailable = error;
+                else if (error instanceof TypeError && this.networkFailures.has(error)) {
+                    unavailable = new UnavailableError('NETWORK', `the node could not be reached: ${error.message}`, {}, undefined, error);
+                }
+                else
+                    throw error;
+            }
+            if (attempt >= retries)
+                throw unavailable;
+            const backoff = retryDelayMs(attempt, this.retry);
+            await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, (unavailable.retryAfter ?? 0) * 1000)));
+        }
+    }
+    post(path, body = {}) {
+        return this.json('POST', path, body);
+    }
+    get(path) {
+        return this.json('GET', path);
+    }
+    put(path, body = {}) {
+        return this.json('PUT', path, body);
+    }
+    delete(path, body) {
+        return this.json('DELETE', path, body);
+    }
+    // ---------------------------------------------------------------- identity
+    /** Create an account with a new passkey, and sign in. */
+    async signUp(passkey, name) {
+        const begin = await this.post('auth/passkey/register/begin', { name });
+        const registration = await passkey.create(begin.options);
+        const session = await this.post('auth/passkey/register/finish', {
+            challengeId: begin.challengeId,
+            registration,
+        });
+        this.useSession(session);
+        return session;
+    }
+    /** Sign in with an existing passkey. */
+    async signIn(passkey) {
+        const begin = await this.post('auth/passkey/login/begin');
+        const assertion = await passkey.get(fromB64url(begin.options.challenge), begin.options.rpId);
+        const session = await this.post('auth/passkey/login/finish', {
+            challengeId: begin.challengeId,
+            assertion,
+        });
+        this.useSession(session);
+        return session;
+    }
+    /** Swap the refresh token for a new session. */
+    async refresh() {
+        if (!this.current)
+            throw new Error('no session to refresh');
+        const session = await this.post('auth/refresh', { refreshToken: this.current.refreshToken });
+        this.useSession(session);
+        return session;
+    }
+    async signOut() {
+        await this.post('auth/logout');
+        this.auth = undefined;
+        this.current = undefined;
+    }
+    /** End every session of the signed-in account, on every device, this one too. */
+    async signOutEverywhere() {
+        await this.post('auth/logout-all');
+        this.auth = undefined;
+        this.current = undefined;
+    }
+    me() {
+        return this.get('auth/me');
+    }
+    /** Add another passkey (another device) to the signed-in account; answers its credential id. */
+    async addPasskey(passkey) {
+        const begin = await this.post('auth/passkeys/add/begin');
+        const registration = await passkey.create(begin.options);
+        const { credentialId } = await this.post('auth/passkeys/add/finish', {
+            challengeId: begin.challengeId,
+            registration,
+        });
+        return credentialId;
+    }
+    /** Remove one of the account's passkeys (not the last). */
+    async removePasskey(credentialId) {
+        await this.delete(`auth/passkeys/${seg(credentialId)}`);
+    }
+    /** Name one of the account's passkeys (a device label); `''` clears the name. */
+    async labelPasskey(credentialId, label) {
+        await this.post(`auth/passkeys/${seg(credentialId)}`, { label });
+    }
+    /** What this account uses (apps, bundle bytes, API keys, owned orgs), with the cluster's quotas. */
+    usage() {
+        return this.get('auth/usage');
+    }
+    /**
+     * The node's attestation document, unverified: for display only. Every
+     * request this client sends is sealed to a key it verified itself first.
+     */
+    async attestation() {
+        const nonce = toHex(crypto.getRandomValues(new Uint8Array(32)));
+        const response = await this.raw(`${this.base}/attestation?nonce=${nonce}`);
+        if (!response.ok)
+            throw await refusal(response);
+        return (await response.json());
+    }
+    /** The account's API keys (never the keys themselves). */
+    async listApiKeys() {
+        const { keys } = await this.get('auth/apikeys');
+        return keys;
+    }
+    async revokeApiKey(keyId) {
+        await this.delete(`auth/apikeys/${seg(keyId)}`);
+    }
+    /** Create an API key for an agent or server. The key is returned once. */
+    createApiKey(options) {
+        return this.post('auth/apikeys', options);
+    }
+    // ---------------------------------------------------------------- apps
+    /** Upload a raw WASM bundle (development clusters only); answers its hash. */
+    async uploadBundle(wasm) {
+        const { hash } = await this.json('POST', 'bundles', undefined, wasm);
+        return hash;
+    }
+    /** Upload a blob for `app`: `blobId` is base58 (what apps print), `id` hex. */
+    uploadBlob(app, data) {
+        return this.json('POST', `apps/${seg(app)}/blobs`, undefined, data);
+    }
+    /** One of `app`'s blobs, by id (base58 or hex). */
+    async downloadBlob(app, id) {
+        const response = await this.request('GET', `apps/${seg(app)}/blobs/${seg(id)}`);
+        if (!response.ok)
+            throw await refusal(response);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    /** `app`'s blobs. */
+    async listBlobs(app) {
+        const { blobs } = await this.get(`apps/${seg(app)}/blobs`);
+        return blobs;
+    }
+    /** One of `app`'s blobs' id and size; `NotFound` if the app has no such blob. */
+    blobInfo(app, id) {
+        return this.get(`apps/${seg(app)}/blobs/${seg(id)}/info`);
+    }
+    /** Delete one of `app`'s blobs (its owner, or an admin of its organization). */
+    async deleteBlob(app, id) {
+        await this.delete(`apps/${seg(app)}/blobs/${seg(id)}`);
+    }
+    // ---------------------------------------------------------------- packages
+    /** Install a signed `.mpk` package file. */
+    uploadPackage(mpk) {
+        return this.json('POST', 'packages', undefined, mpk, 'application/octet-stream');
+    }
+    /** Install `package@version` from the cluster's registry; every node that runs it verifies it. */
+    installPackage(pkg, version) {
+        return this.post('packages/install', { package: pkg, version });
+    }
+    /** Installed packages and their versions. */
+    async packages() {
+        const { packages } = await this.get('packages');
+        return packages;
+    }
+    /** One installed package and its versions. */
+    package(pkg) {
+        return this.get(`packages/${seg(pkg)}`);
+    }
+    /** Uninstall one version, or the whole package. Refused while an app runs it. */
+    uninstallPackage(pkg, version) {
+        return this.delete(version === undefined ? `packages/${seg(pkg)}` : `packages/${seg(pkg)}/${seg(version)}`);
+    }
+    // ---------------------------------------------------------------- app instances
+    /** Apps this caller reaches, optionally only those of one package or bundle. */
+    async listApps(filter = {}) {
+        const q = new URLSearchParams();
+        if (filter.package)
+            q.set('package', filter.package);
+        if (filter.bundle)
+            q.set('bundle', filter.bundle);
+        const query = q.toString();
+        const { apps } = await this.get(query ? `apps?${query}` : 'apps');
+        return apps;
+    }
+    getApp(app) {
+        return this.get(`apps/${seg(app)}`);
+    }
+    /** Delete an app instance (its owner, or an admin of its organization). */
+    async deleteApp(app) {
+        await this.delete(`apps/${seg(app)}`);
+    }
+    /** Who may reach the app: `{ kind: 'owner' | 'org' | 'public' | 'accounts' | 'team', ... }`. */
+    async setAccess(app, access) {
+        await this.post(`apps/${seg(app)}/access`, { access });
+    }
+    /** Set the app instance's metadata (its owner, or an admin of its organization); at most 16 KiB. */
+    async setAppMetadata(app, metadata) {
+        await this.post(`apps/${seg(app)}/metadata`, { metadata });
+    }
+    /** What the app's storage holds: `{ keys, bytes, blobs, blobBytes }`. */
+    appStorage(app) {
+        return this.get(`apps/${seg(app)}/storage`);
+    }
+    /** The ABI the app's bundle embeds: `{ bundle, abi }`. */
+    appAbi(app) {
+        return this.get(`apps/${seg(app)}/abi`);
+    }
+    /**
+     * Hand the app to another account (an organization's app only to one of its
+     * members). The owner approves with `passkey`.
+     */
+    async transferApp(app, to, passkey) {
+        await this.postConfirmed(`apps/${seg(app)}/transfer`, { to }, passkey);
+    }
+    /**
+     * Move an app to another release of its package (`{ version }`), another
+     * package, or a bundle hash, running its migration. Answers the upgrade's
+     * entry; a failed migration rejects with code `UPGRADE_FAILED` (422).
+     * Where the owner holds app upgrades, the node asks for the owner's approval
+     * (`412 CONFIRM_REQUIRED`), which `passkey` gives.
+     */
+    upgradeApp(app, target, passkey) {
+        const path = `apps/${seg(app)}/upgrade`;
+        return passkey ? this.postConfirmed(path, target, passkey) : this.post(path, target);
+    }
+    /**
+     * POST `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
+     * assertion over the node's challenge (deleting an org, approving a release, ...).
+     */
+    postConfirmed(path, body, passkey) {
+        return this.confirmed('POST', path, body, passkey);
+    }
+    /** {@link postConfirmed} for a DELETE (deleting an organization). */
+    deleteConfirmed(path, passkey, body = {}) {
+        return this.confirmed('DELETE', path, body, passkey);
+    }
+    async confirmed(method, path, body, passkey, send = (b) => this.json(method, path, b)) {
+        try {
+            return await send(body);
+        }
+        catch (error) {
+            if (!(error instanceof ConfirmRequired))
+                throw error;
+            const d = error.details;
+            let assertion;
+            try {
+                assertion = await passkey.get(fromB64url(d.challenge), d.rpId, d.allowCredentials);
+            }
+            catch (declined) {
+                // WebAuthn rejects a prompt the user dismissed with `NotAllowedError`
+                // (`AbortError` when it was aborted); anything else is a real failure.
+                const name = declined?.name;
+                if (name === 'NotAllowedError' || name === 'AbortError')
+                    throw new ConfirmCancelled(declined);
+                throw declined;
+            }
+            return send({ ...body, confirm: { challengeId: d.challengeId, assertion } });
+        }
+    }
+    /**
+     * Create an app instance from a bundle hash, or from a package release
+     * (`{ package, version?, service? }`, installed from the registry first if
+     * the cluster lacks it).
+     */
+    async createApp(name, bundle, options = {}) {
+        const target = typeof bundle === 'string' ? { bundle } : bundle;
+        const { appId } = await this.post('apps', { name, ...target, ...options });
+        return appId;
+    }
+    /**
+     * Call a method. A retry with the same `idempotencyKey` is answered once.
+     * Without one, the client makes one, so its own retries of a 503 share it.
+     */
+    call(app, method, args = {}, idempotencyKey) {
+        const key = idempotencyKey ?? newIdempotencyKey();
+        return this.retried('POST', `apps/${seg(app)}/intents`, { method, args, idempotencyKey: key });
+    }
+    /**
+     * Call a method that needs the account holder's approval: the node returns a
+     * challenge over this exact call, which `passkey` signs. A declined prompt
+     * rejects with {@link ConfirmCancelled}.
+     */
+    async callConfirmed(app, method, args, passkey, idempotencyKey) {
+        const path = `apps/${seg(app)}/intents`;
+        const key = idempotencyKey ?? newIdempotencyKey();
+        // The confirmed attempt goes out exactly once: its challenge is single-use,
+        // so a resend would be refused on the challenge, not answered from the key.
+        return this.confirmed('POST', path, { method, args, idempotencyKey: key }, passkey, (body) => this.retried('POST', path, body, body.confirm === undefined ? this.retry.retries : 0));
+    }
+    /** Run a read-only method: strong by default, or stale from any replica. */
+    view(app, method, args = {}, options = {}) {
+        return this.retried('POST', `apps/${seg(app)}/views`, {
+            method,
+            args,
+            consistency: options.stale ? 'stale' : 'strong',
+            minIndex: options.minIndex ?? 0,
+        });
+    }
+    /** Committed events from index `from`, then live, until `signal` aborts. */
+    events(app, from = 0, signal) {
+        return this.stream(`apps/${seg(app)}/events?from=${from}`, signal);
+    }
+    /** A server-sent event stream on `path`, sealed like every other answer. */
+    async *stream(path, signal) {
+        const headers = {};
+        if (this.auth)
+            headers.authorization = `Bearer ${this.auth}`;
+        const response = await this.sealed(`${this.base}/${path}`, { headers, signal });
+        if (!response.ok)
+            throw await refusal(response);
+        if (!response.body)
+            throw new CalimeroError(response.status, 'EVENTS', 'the event stream has no body');
+        yield* sseFrames(response.body);
+    }
+    // ---------------------------------------------------------------- presence
+    /**
+     * Publish this device's presence in `app`: `state` (at most 4 KiB) or `null`
+     * to retract it. The newest `seq` wins; send the same `seq` and state again
+     * as a heartbeat, since an entry not refreshed within 7 s is gone.
+     */
+    async publishPresence(app, seq, state) {
+        await this.post(`apps/${seg(app)}/presence`, { seq, state: state === null ? null : toHex(state) });
+    }
+    /** Who is present in `app` now. */
+    async presence(app) {
+        const { present } = await this.get(`apps/${seg(app)}/presence`);
+        return present;
+    }
+    /**
+     * Presence as a stream until `signal` aborts: a `snapshot` event (`data` the
+     * entries present), then a `presence` event (`data` one entry) per change.
+     */
+    presenceStream(app, signal) {
+        return this.stream(`apps/${seg(app)}/presence/stream`, signal);
+    }
+    // ---------------------------------------------------------------- aliases
+    /** Name an app (its id or context id) for this account. */
+    async setAlias(alias, app) {
+        await this.put(`auth/aliases/${seg(alias)}`, { app });
+    }
+    /** This account's aliases, alias → app id. */
+    async aliases() {
+        const { aliases } = await this.get('auth/aliases');
+        return aliases;
+    }
+    /** The app an alias names. */
+    async alias(alias) {
+        const { appId } = await this.get(`auth/aliases/${seg(alias)}`);
+        return appId;
+    }
+    async deleteAlias(alias) {
+        await this.delete(`auth/aliases/${seg(alias)}`);
+    }
+    // ---------------------------------------------------------------- organizations
+    async createOrg(name) {
+        const { orgId } = await this.post('orgs', { name });
+        return orgId;
+    }
+    /** The organization, with the teams this caller reaches or manages. */
+    getOrg(org) {
+        return this.get(`orgs/${seg(org)}`);
+    }
+    /**
+     * Delete an organization with its teams, invites and apps (its owner only).
+     * The node asks for the owner's passkey (`412 CONFIRM_REQUIRED`), which `passkey` gives.
+     */
+    async deleteOrg(org, passkey) {
+        await this.deleteConfirmed(`orgs/${seg(org)}`, passkey);
+    }
+    /** Set the organization's metadata (an admin, or a holder of `MANAGE_METADATA`); at most 16 KiB. */
+    async setOrgMetadata(org, metadata) {
+        await this.post(`orgs/${seg(org)}/metadata`, { metadata });
+    }
+    /** Set a member's metadata (theirs, or an admin's); `null` clears it. */
+    async setMemberMetadata(org, account, metadata) {
+        await this.post(`orgs/${seg(org)}/members/${seg(account)}/metadata`, { metadata });
+    }
+    /**
+     * Upgrade every app of `org` that runs `target.package` to `target.version`
+     * (optionally one team's, with `cascade` the teams below it). The org's owner,
+     * or a holder of `MANAGE_APPLICATION`, approves the whole run with `passkey`.
+     * Answers the run; {@link upgradeRun} follows it.
+     */
+    upgradeOrg(org, target, passkey) {
+        return this.postConfirmed(`orgs/${seg(org)}/upgrade`, { ...target }, passkey);
+    }
+    /** An organization-wide upgrade run: its apps, those done and those that failed. */
+    upgradeRun(org, run) {
+        return this.get(`orgs/${seg(org)}/upgrades/${seg(run)}`);
+    }
+    /** Run the apps that failed in `run` again, as a new run, approved with `passkey`. */
+    retryUpgradeRun(org, run, passkey) {
+        return this.postConfirmed(`orgs/${seg(org)}/upgrades/${seg(run)}/retry`, {}, passkey);
+    }
+    /**
+     * Approve a mero-tee release to hold the apps of `org`, or of this account
+     * outside any organization (`org` `null`); `approved: false` withdraws it.
+     * Until then, nodes on that release get none of those apps' data. The owner
+     * approves with `passkey`.
+     */
+    async approveRelease(org, version, passkey, approved = true) {
+        const path = org === null ? 'auth/releases' : `orgs/${seg(org)}/releases`;
+        return this.postConfirmed(path, { version, approved }, passkey);
+    }
+    /**
+     * Approve the URL prefixes apps from `pkg`'s publisher may call out to, for
+     * `org`'s apps or this account's own (`org` `null`). `prefixes` `'manifest'`
+     * (the default) approves every prefix the package's latest release declares;
+     * `replace` sets exactly `prefixes`, which is how one is revoked. Approved
+     * with `passkey`.
+     */
+    async approveOutbound(org, pkg, passkey, options = {}) {
+        const path = org === null ? 'auth/outbound' : `orgs/${seg(org)}/outbound`;
+        return this.postConfirmed(path, { package: pkg, prefixes: options.prefixes ?? 'manifest', replace: options.replace ?? false }, passkey);
+    }
+    /** Add a member, or change their role. */
+    async setMember(org, account, role) {
+        await this.post(`orgs/${seg(org)}/members`, { account, role });
+    }
+    removeMember(org, account) {
+        return this.delete(`orgs/${seg(org)}/members/${seg(account)}`);
+    }
+    /**
+     * Set capability bits ({@link ORG_CAPABILITIES}): for a member (`account`),
+     * for a member of one team (`account` and `team`), or the organization's
+     * default (neither).
+     */
+    async setCapabilities(org, capabilities, at = {}) {
+        await this.post(`orgs/${seg(org)}/capabilities`, { capabilities, ...at });
+    }
+    async createTeam(org, name, join, parent) {
+        const { teamId } = await this.post(`orgs/${seg(org)}/teams`, { name, join, parent });
+        return teamId;
+    }
+    getTeam(org, team) {
+        return this.get(`orgs/${seg(org)}/teams/${seg(team)}`);
+    }
+    /**
+     * Rename, change who may join, set the app's metadata, or move the team:
+     * `parent: null` moves it to the top, an absent `parent` leaves it.
+     */
+    async updateTeam(org, team, update) {
+        await this.post(`orgs/${seg(org)}/teams/${seg(team)}`, update);
+    }
+    /** Delete a team, the teams below it and their apps. */
+    async deleteTeam(org, team) {
+        await this.delete(`orgs/${seg(org)}/teams/${seg(team)}`);
+    }
+    /** Add a member to a team, or change their row: role, lead, capability bits. */
+    async setTeamMember(org, team, account, row = {}) {
+        await this.post(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row });
+    }
+    async removeTeamMember(org, team, account) {
+        await this.delete(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`);
+    }
+    async invite(org, role, teams = [], options = {}) {
+        const { token } = await this.post(`orgs/${seg(org)}/invites`, { role, teams, ...options });
+        return token;
+    }
+    redeemInvite(token) {
+        return this.post(`invites/${seg(token)}/redeem`);
+    }
+}