@oxyhq/core 3.18.1 → 4.0.0

package/src/mixins/OxyServices.accounts.ts

@@ -0,0 +1,1079 @@
+/**
+ * Accounts Methods Mixin
+ *
+ * The single client surface for the unified Oxy **account graph** (`/accounts`)
+ * and the **applications** owned within it (`/applications`).
+ *
+ * An account is a relational, tree-structured principal (the `User` document
+ * generalised): a `personal` account is a human login at the root of its tree;
+ * `organization` / `project` / `bot` accounts are non-login principals operated
+ * through membership. Accounts form a tree (`parentAccountId`), own
+ * applications/bots, and expose a single membership model (`AccountMember`) with
+ * a unified role set and an explicit-but-inheritable cascade down the subtree.
+ *
+ * This mixin is the clean-cut replacement for the former `managedAccounts`,
+ * `workspaces`, and `applications` (account-management) mixins. Applications are
+ * now owned by an account (`Application.ownerAccountId`) and their access derives
+ * from the caller's `AccountMember` on that owning account — there is no separate
+ * application-membership surface. The OAuth-consent surface a user sees for
+ * THIRD-PARTY apps they authorized (`getPublicApplication`, `listConnectedApps`,
+ * `revokeAppGrant`) is unrelated to account ownership and lives in
+ * `OxyServices.connectedApps.ts`.
+ *
+ * Reference accounts by their Mongo `_id` (`accountId`, the underlying
+ * `User._id`), applications by their `_id` (`applicationId`), members by their
+ * member `_id`, and credentials by their `credentialId`. Never by name, slug, or
+ * handle.
+ *
+ * NOTE: acting-as (delegated identity) is NOT part of this mixin — `setActingAs`
+ * / `getActingAs` live on `OxyServices.base` and `verifyActingAs` on the utility
+ * mixin (it verifies against `GET /accounts/verify-acting-as`).
+ */
+import type { User } from '../models/interfaces';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { CACHE_TIMES } from './mixinHelpers';
+
+// ---------------------------------------------------------------------------
+// Account graph types
+// ---------------------------------------------------------------------------
+
+/**
+ * Account classification, orthogonal to the federation `type`
+ * (`local|federated|agent|automated`). `personal` accounts have a direct login;
+ * `organization` / `project` / `bot` accounts are operated via `AccountMember`
+ * and have no direct login.
+ */
+export type AccountKind = 'personal' | 'organization' | 'project' | 'bot';
+
+/**
+ * The calling user's relationship to an account node, as resolved by the API:
+ * - `self` — the caller's own personal (root) account.
+ * - `owner` — an account the caller owns (e.g. an org/project/bot they created).
+ * - `member` — an account shared with the caller via membership (including
+ *   external organisations).
+ */
+export type AccountRelationship = 'self' | 'owner' | 'member';
+
+/** Role a member holds within an account. The unified account role set. */
+export type AccountRole = 'owner' | 'admin' | 'editor' | 'developer' | 'billing' | 'viewer';
+
+/** Membership lifecycle status. */
+export type AccountMemberStatus = 'active' | 'invited' | 'removed';
+
+/**
+ * Origin of a resolved membership. `direct` is a membership row on the account
+ * itself; `inherited` is resolved from the nearest ancestor account whose
+ * membership row has `inherit: true` (role inheritance cascades down the tree).
+ */
+export type AccountMemberSource = 'direct' | 'inherited';
+
+/**
+ * Client-facing AccountMember shape. `permissions` is derived from `role` on the
+ * server at write time.
+ */
+export interface AccountMember {
+  _id: string;
+  /** The account this membership grants access to (account `_id`). */
+  accountId: string;
+  /** The member's personal-account `User._id`. */
+  memberUserId: string;
+  role: AccountRole;
+  permissions: string[];
+  /**
+   * Whether this membership cascades to the account's subtree. `true` (default)
+   * lets descendants inherit this role unless a nearer row overrides it; `false`
+   * opts this row out of inheritance (it applies to this account only).
+   */
+  inherit: boolean;
+  status: AccountMemberStatus;
+  /**
+   * Origin of the membership when the API resolves an effective role. Present on
+   * a resolved `callerMembership` to indicate whether the caller's access is
+   * `direct` on the account or `inherited` from an ancestor. Absent on plain
+   * member-list rows (which are always direct rows on the account).
+   */
+  source?: AccountMemberSource;
+  invitedByUserId?: string | null;
+  joinedAt?: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * A node in the account graph as returned by the `/accounts` API. `account` is
+ * the underlying generalised `User` document; `relationship` and
+ * `callerMembership` describe the caller's access. On a flat list every node
+ * carries `parentAccountId`; with `tree:true`, `children` is populated and
+ * `childCount` reflects the number of direct children.
+ */
+export interface AccountNode {
+  /** The account's Mongo `_id` (the underlying `User._id`). */
+  accountId: string;
+  kind: AccountKind;
+  /** Parent account `_id`, or `null` for a root (personal) account. */
+  parentAccountId: string | null;
+  /** The generalised `User` document backing this account. */
+  account: User;
+  relationship: AccountRelationship;
+  /**
+   * The caller's effective membership in this account (direct or inherited), or
+   * `null` when the caller has no membership (e.g. their own `self` root, where
+   * ownership is implicit). Use `callerMembership.permissions` to gate UI.
+   */
+  callerMembership: AccountMember | null;
+  /** Number of direct child accounts (present when the API computes it). */
+  childCount?: number;
+  /** Direct children, populated when the list is requested with `tree:true`. */
+  children?: AccountNode[];
+}
+
+/** Options accepted by `listAccounts`. */
+export interface ListAccountsOptions {
+  /**
+   * When `true`, request the nested tree representation: each returned node has
+   * its `children` populated instead of a flat list keyed by `parentAccountId`.
+   */
+  tree?: boolean;
+}
+
+/** Input accepted by `createAccount`. */
+export interface CreateAccountInput {
+  /** Classification of the new account. `personal` accounts are not created here. */
+  kind: AccountKind;
+  /**
+   * Parent account `_id` to nest the new account under. Omitted → the API roots
+   * it under the caller's personal account.
+   */
+  parentAccountId?: string;
+  /** Unique handle for the account (shares the `User.username` unique index). */
+  username: string;
+  name?: { first?: string; last?: string };
+  bio?: string;
+  avatar?: string;
+}
+
+/** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
+export interface UpdateAccountInput {
+  username?: string;
+  name?: { first?: string; last?: string };
+  bio?: string | null;
+  avatar?: string | null;
+}
+
+/** Input accepted by `inviteAccountMember`. The owner role cannot be invited. */
+export interface InviteAccountMemberInput {
+  /**
+   * The username or email of the user to invite. Resolved to a personal account
+   * server-side; an unknown value yields a 404 "User not found".
+   */
+  usernameOrEmail: string;
+  role: Exclude<AccountRole, 'owner'>;
+}
+
+/** Input accepted by `updateAccountMember`. The owner role cannot be assigned. */
+export interface UpdateAccountMemberInput {
+  role: Exclude<AccountRole, 'owner'>;
+}
+
+/** Input accepted by `transferAccountOwnership`. */
+export interface TransferAccountOwnershipInput {
+  userId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Bot (account) service-credential types
+// ---------------------------------------------------------------------------
+
+/** Credential kind. Account (bot) credentials are always `service` tokens. */
+export type AccountCredentialType = 'service';
+
+/** Deployment environment a bot credential is scoped to. */
+export type AccountCredentialEnvironment = 'development' | 'staging' | 'production';
+
+/** Bot credential lifecycle status. */
+export type AccountCredentialStatus = 'active' | 'deprecated' | 'revoked';
+
+/** Input accepted by `createAccountCredential`. Credential `type` is always `service`. */
+export interface CreateAccountCredentialInput {
+  name: string;
+  environment: AccountCredentialEnvironment;
+  scopes?: string[];
+}
+
+/**
+ * Client-facing AccountCredential shape (a bot account's service token). The raw
+ * secret is NEVER part of this shape — it is returned exactly once, separately,
+ * at creation/rotation.
+ */
+export interface AccountCredential {
+  _id: string;
+  /** The bot account this credential authenticates as (account `_id`). */
+  accountId: string;
+  name: string;
+  publicKey: string;
+  type: AccountCredentialType;
+  environment: AccountCredentialEnvironment;
+  scopes: string[];
+  status: AccountCredentialStatus;
+  lastUsedAt?: string;
+  expiresAt?: string;
+  /**
+   * Audit link to the credential this one was rotated FROM. Populated on
+   * credentials created via rotation; absent on original credentials.
+   */
+  rotatedFromCredentialId?: string;
+  createdByUserId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Result of creating a bot credential — `secret` is returned ONCE. */
+export interface AccountCredentialWithSecret {
+  credential: AccountCredential;
+  secret: string;
+}
+
+/**
+ * Result of rotating a bot credential. Extends the create result with audit
+ * fields: the new plaintext `secret` is returned ONCE, plus `rotatedFrom` (the
+ * previous credential's `credentialId`) and `graceExpiresAt` (ISO string marking
+ * when the old credential stops being honoured during the rotation grace window).
+ */
+export interface RotateAccountCredentialResult extends AccountCredentialWithSecret {
+  /** The previous credential's `credentialId` that this rotation supersedes. */
+  rotatedFrom: string;
+  /** ISO timestamp at which the rotated-from credential's grace window ends. */
+  graceExpiresAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Application (owned by an account) types
+// ---------------------------------------------------------------------------
+
+/**
+ * Application classification. Set only by Oxy platform staff — never editable
+ * through the normal member-facing update path.
+ */
+export type ApplicationType = 'first_party' | 'third_party' | 'internal' | 'system';
+
+/** Lifecycle status of an application. */
+export type ApplicationStatus = 'active' | 'suspended' | 'deleted' | 'pending_review';
+
+/** OAuth credential kind. `service` credentials mint service tokens. */
+export type ApplicationCredentialType = 'public' | 'confidential' | 'service';
+
+/** Deployment environment an application credential is scoped to. */
+export type ApplicationEnvironment = 'development' | 'staging' | 'production';
+
+/** Application credential lifecycle status. */
+export type ApplicationCredentialStatus = 'active' | 'deprecated' | 'revoked';
+
+/**
+ * Client-facing Application shape returned by the `/applications` API. An
+ * application is the OAuth client; it is OWNED by an account
+ * (`ownerAccountId`), and the caller's access derives from their `AccountMember`
+ * on that owning account (with inheritance).
+ */
+export interface Application {
+  _id: string;
+  name: string;
+  description?: string;
+  websiteUrl?: string;
+  icon?: string;
+  type: ApplicationType;
+  status: ApplicationStatus;
+  isOfficial: boolean;
+  isInternal: boolean;
+  capabilities: string[];
+  redirectUris: string[];
+  scopes: string[];
+  webhookUrl?: string;
+  devWebhookUrl?: string;
+  createdByUserId: string;
+  /**
+   * The account that owns this application (account `_id`). Access to the
+   * application derives from the caller's `AccountMember` on this account, with
+   * inheritance up the account tree.
+   */
+  ownerAccountId: string;
+  createdAt: string;
+  updatedAt: string;
+  /**
+   * The caller's effective membership in the OWNING account (direct or
+   * inherited), embedded by the API on list/detail responses, or `null` when the
+   * caller has no membership. Use `callerMembership.permissions` to gate UI.
+   */
+  callerMembership?: AccountMember | null;
+}
+
+/**
+ * Client-facing ApplicationCredential shape (an application's OAuth client
+ * credentials). The raw secret is NEVER part of this shape — it is returned
+ * exactly once, separately, at creation/rotation.
+ */
+export interface ApplicationCredential {
+  _id: string;
+  applicationId: string;
+  name: string;
+  publicKey: string;
+  type: ApplicationCredentialType;
+  environment: ApplicationEnvironment;
+  scopes: string[];
+  status: ApplicationCredentialStatus;
+  lastUsedAt?: string;
+  expiresAt?: string;
+  /**
+   * Audit link to the credential this one was rotated FROM. Populated on
+   * credentials created via rotation; absent on original credentials.
+   */
+  rotatedFromCredentialId?: string;
+  createdByUserId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Input accepted by `createApp`. Staff-only fields are not settable here. */
+export interface CreateApplicationInput {
+  name: string;
+  description?: string;
+  websiteUrl?: string;
+  icon?: string;
+  redirectUris?: string[];
+  scopes?: string[];
+  /**
+   * Owning account `_id`. Omitted → the API defaults to the caller's personal
+   * account.
+   */
+  ownerAccountId?: string;
+}
+
+/** Input accepted by `updateApp`. Staff-only fields are not settable here. */
+export interface UpdateApplicationInput {
+  name?: string;
+  description?: string;
+  websiteUrl?: string;
+  icon?: string;
+  redirectUris?: string[];
+  scopes?: string[];
+  webhookUrl?: string;
+  devWebhookUrl?: string;
+  status?: ApplicationStatus;
+}
+
+/** Input accepted by `createAppCredential`. */
+export interface CreateApplicationCredentialInput {
+  name: string;
+  type: ApplicationCredentialType;
+  environment: ApplicationEnvironment;
+  scopes?: string[];
+}
+
+/** Result of creating an application credential — `secret` is returned ONCE. */
+export interface ApplicationCredentialWithSecret {
+  credential: ApplicationCredential;
+  secret: string;
+}
+
+/**
+ * Result of rotating an application credential. Extends the create result with
+ * audit fields: the new plaintext `secret` is returned ONCE, plus `rotatedFrom`
+ * (the previous credential's `credentialId`) and `graceExpiresAt` (ISO string
+ * marking when the old credential stops being honoured during the grace window).
+ */
+export interface RotateApplicationCredentialResult extends ApplicationCredentialWithSecret {
+  /** The previous credential's `credentialId` that this rotation supersedes. */
+  rotatedFrom: string;
+  /** ISO timestamp at which the rotated-from credential's grace window ends. */
+  graceExpiresAt: string;
+}
+
+/** Time window for application usage statistics. */
+export type ApplicationUsagePeriod = '24h' | '7d' | '30d' | '90d';
+
+/** Aggregate totals for an application over the requested period. */
+export interface ApplicationUsageSummary {
+  totalRequests: number;
+  totalTokens: number;
+  totalCredits: number;
+  avgResponseTime: number;
+  successfulRequests: number;
+  errorRequests: number;
+}
+
+/** Per-day usage bucket. `_id` is the day key (e.g. `YYYY-MM-DD`). */
+export interface ApplicationUsageByDay {
+  _id: string;
+  requests: number;
+  tokens: number;
+  credits: number;
+}
+
+/** Per-endpoint usage bucket. `_id` is the endpoint identifier. */
+export interface ApplicationUsageByEndpoint {
+  _id: string;
+  requests: number;
+  tokens: number;
+}
+
+/** Usage statistics for an application over a period. */
+export interface ApplicationUsageStats {
+  summary: ApplicationUsageSummary;
+  byDay: ApplicationUsageByDay[];
+  byEndpoint: ApplicationUsageByEndpoint[];
+}
+
+/** Result of an archive/remove/revoke/transfer/delete operation. */
+export interface AccountSuccessResult {
+  success: boolean;
+}
+
+export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    // =========================================================================
+    // Accounts
+    // =========================================================================
+
+    /**
+     * List the accounts the caller can access: their own personal (root)
+     * account, accounts they own, and accounts shared with them (including
+     * external organisations), plus the reachable subtree of each.
+     *
+     * @param opts - `{ tree: true }` requests the nested tree representation
+     *   (`children` populated) instead of a flat list. The flag is appended to
+     *   the path as `?tree=true`, so the response cache keys on it automatically —
+     *   the flat and tree variants never collide.
+     */
+    async listAccounts(opts?: ListAccountsOptions): Promise<AccountNode[]> {
+      try {
+        const path = opts?.tree ? '/accounts?tree=true' : '/accounts';
+        const res = await this.makeRequest<{ accounts?: AccountNode[] }>(
+          'GET',
+          path,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.accounts ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Fetch a single account node by id.
+     * @param accountId - The account's Mongo `_id`.
+     */
+    async getAccount(accountId: string): Promise<AccountNode> {
+      try {
+        const res = await this.makeRequest<{ account: AccountNode }>(
+          'GET',
+          `/accounts/${encodeURIComponent(accountId)}`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.LONG },
+        );
+        return res.account;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Create a new (non-personal) account. The caller becomes its `owner`.
+     * @param data - Account configuration: kind, optional parent, and profile.
+     */
+    async createAccount(data: CreateAccountInput): Promise<AccountNode> {
+      try {
+        const res = await this.makeRequest<{ account: AccountNode }>(
+          'POST',
+          '/accounts',
+          data,
+          { cache: false },
+        );
+        // A new account changes the accessible forest — bust every cached list
+        // (flat + tree) so it appears on the next `listAccounts()` read.
+        this._invalidateAccountLists();
+        return res.account;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Update an account's mutable profile fields. Tree placement changes
+     * (reparenting) go through the dedicated move endpoint, not here.
+     * @param accountId - The account's Mongo `_id`.
+     * @param data - Subset of updatable profile fields.
+     */
+    async updateAccount(
+      accountId: string,
+      data: UpdateAccountInput,
+    ): Promise<AccountNode> {
+      try {
+        const res = await this.makeRequest<{ account: AccountNode }>(
+          'PATCH',
+          `/accounts/${encodeURIComponent(accountId)}`,
+          data,
+          { cache: false },
+        );
+        // Bust the cached detail and every list (which embeds account profile
+        // data) so neither serves the pre-update snapshot.
+        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
+        this._invalidateAccountLists();
+        return res.account;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Archive an account (soft delete). Named `archiveAccount` — NOT
+     * `deleteAccount`, which is reserved for the GDPR self-deletion flow on the
+     * user mixin (`OxyServices.user.ts`).
+     * @param accountId - The account's Mongo `_id`.
+     */
+    async archiveAccount(accountId: string): Promise<AccountSuccessResult> {
+      try {
+        const result = await this.makeRequest<AccountSuccessResult>(
+          'DELETE',
+          `/accounts/${encodeURIComponent(accountId)}`,
+          undefined,
+          { cache: false },
+        );
+        // Bust every cached representation of the archived account.
+        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
+        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/members`);
+        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
+        this._invalidateAccountLists();
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * List the direct child accounts of an account.
+     * @param accountId - The parent account's Mongo `_id`.
+     */
+    async listChildAccounts(accountId: string): Promise<AccountNode[]> {
+      try {
+        const res = await this.makeRequest<{ accounts?: AccountNode[] }>(
+          'GET',
+          `/accounts/${encodeURIComponent(accountId)}/children`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.accounts ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    // =========================================================================
+    // Account members
+    // =========================================================================
+
+    /**
+     * List members of an account (direct membership rows on the account).
+     * @param accountId - The account's Mongo `_id`.
+     */
+    async listAccountMembers(accountId: string): Promise<AccountMember[]> {
+      try {
+        const res = await this.makeRequest<{ members?: AccountMember[] }>(
+          'GET',
+          `/accounts/${encodeURIComponent(accountId)}/members`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.members ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Add a member to an account.
+     * @param accountId - The account's Mongo `_id`.
+     * @param data - Target user's username or email and role (never `owner`).
+     *   The server resolves `usernameOrEmail` to a personal account; an unknown
+     *   value yields a 404 "User not found".
+     */
+    async inviteAccountMember(
+      accountId: string,
+      data: InviteAccountMemberInput,
+    ): Promise<AccountMember> {
+      try {
+        const res = await this.makeRequest<{ member: AccountMember }>(
+          'POST',
+          `/accounts/${encodeURIComponent(accountId)}/members`,
+          data,
+          { cache: false },
+        );
+        this._invalidateAccountMembership(accountId);
+        return res.member;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Change a member's role.
+     * @param accountId - The account's Mongo `_id`.
+     * @param memberId - The member's Mongo `_id`.
+     * @param data - New role (never `owner`).
+     */
+    async updateAccountMember(
+      accountId: string,
+      memberId: string,
+      data: UpdateAccountMemberInput,
+    ): Promise<AccountMember> {
+      try {
+        const res = await this.makeRequest<{ member: AccountMember }>(
+          'PATCH',
+          `/accounts/${encodeURIComponent(accountId)}/members/${encodeURIComponent(memberId)}`,
+          data,
+          { cache: false },
+        );
+        this._invalidateAccountMembership(accountId);
+        return res.member;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Remove a member from an account.
+     * @param accountId - The account's Mongo `_id`.
+     * @param memberId - The member's Mongo `_id`.
+     */
+    async removeAccountMember(
+      accountId: string,
+      memberId: string,
+    ): Promise<AccountSuccessResult> {
+      try {
+        const result = await this.makeRequest<AccountSuccessResult>(
+          'DELETE',
+          `/accounts/${encodeURIComponent(accountId)}/members/${encodeURIComponent(memberId)}`,
+          undefined,
+          { cache: false },
+        );
+        this._invalidateAccountMembership(accountId);
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Transfer ownership of an account to another member (owner only).
+     * @param accountId - The account's Mongo `_id`.
+     * @param data - Target user id.
+     */
+    async transferAccountOwnership(
+      accountId: string,
+      data: TransferAccountOwnershipInput,
+    ): Promise<AccountSuccessResult> {
+      try {
+        const result = await this.makeRequest<AccountSuccessResult>(
+          'POST',
+          `/accounts/${encodeURIComponent(accountId)}/transfer-ownership`,
+          data,
+          { cache: false },
+        );
+        // Ownership change alters roles in the member list AND the detail, and
+        // can change which accounts the caller "owns" in the list view.
+        this._invalidateAccountMembership(accountId);
+        this._invalidateAccountLists();
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    // =========================================================================
+    // Bot (account) service credentials  —  /accounts/:id/credentials
+    // =========================================================================
+
+    /**
+     * List a bot account's service credentials. The response NEVER includes
+     * secrets.
+     * @param accountId - The account's Mongo `_id`.
+     */
+    async listAccountCredentials(accountId: string): Promise<AccountCredential[]> {
+      try {
+        const res = await this.makeRequest<{ credentials?: AccountCredential[] }>(
+          'GET',
+          `/accounts/${encodeURIComponent(accountId)}/credentials`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.credentials ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Create a service credential for a bot account. The plaintext `secret` is
+     * returned exactly ONCE; the server stores only a hash and will never return
+     * it again.
+     * @param accountId - The account's Mongo `_id`.
+     * @param data - Credential configuration (`type` is always `service`).
+     */
+    async createAccountCredential(
+      accountId: string,
+      data: CreateAccountCredentialInput,
+    ): Promise<AccountCredentialWithSecret> {
+      try {
+        const result = await this.makeRequest<AccountCredentialWithSecret>(
+          'POST',
+          `/accounts/${encodeURIComponent(accountId)}/credentials`,
+          data,
+          { cache: false },
+        );
+        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Rotate a bot credential's secret. The new plaintext `secret` is returned
+     * exactly ONCE, along with audit fields: `rotatedFrom` (the previous
+     * credentialId) and `graceExpiresAt` (ISO string for the grace window during
+     * which the old credential is still honoured).
+     * @param accountId - The account's Mongo `_id`.
+     * @param credentialId - The credential's Mongo `_id`.
+     */
+    async rotateAccountCredential(
+      accountId: string,
+      credentialId: string,
+    ): Promise<RotateAccountCredentialResult> {
+      try {
+        const result = await this.makeRequest<RotateAccountCredentialResult>(
+          'POST',
+          `/accounts/${encodeURIComponent(accountId)}/credentials/${encodeURIComponent(credentialId)}/rotate`,
+          undefined,
+          { cache: false },
+        );
+        // Rotation changes credential status/audit fields surfaced by the list.
+        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Revoke a bot credential (`status='revoked'`). Revoked credentials can no
+     * longer authenticate.
+     * @param accountId - The account's Mongo `_id`.
+     * @param credentialId - The credential's Mongo `_id`.
+     */
+    async revokeAccountCredential(
+      accountId: string,
+      credentialId: string,
+    ): Promise<AccountSuccessResult> {
+      try {
+        const result = await this.makeRequest<AccountSuccessResult>(
+          'DELETE',
+          `/accounts/${encodeURIComponent(accountId)}/credentials/${encodeURIComponent(credentialId)}`,
+          undefined,
+          { cache: false },
+        );
+        // Revocation flips the credential's status in the cached list.
+        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    // =========================================================================
+    // Applications owned by an account  —  /applications
+    // =========================================================================
+
+    /**
+     * List the applications owned by an account. Backed by
+     * `GET /applications?ownerAccountId=<id>`.
+     * @param accountId - The owning account's Mongo `_id`.
+     */
+    async listAccountApps(accountId: string): Promise<Application[]> {
+      try {
+        const res = await this.makeRequest<{ applications?: Application[] }>(
+          'GET',
+          `/applications?ownerAccountId=${encodeURIComponent(accountId)}`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.applications ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Create a new application owned by an account.
+     * @param data - Application configuration. `ownerAccountId` defaults to the
+     *   caller's personal account when omitted. Staff-only fields are ignored.
+     */
+    async createApp(data: CreateApplicationInput): Promise<Application> {
+      try {
+        const res = await this.makeRequest<{ application: Application }>(
+          'POST',
+          '/applications',
+          data,
+          { cache: false },
+        );
+        // Bust every cached application list (per owning account) so the new app
+        // appears on the next `listAccountApps()` read.
+        this._invalidateAppLists();
+        return res.application;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Fetch a single application by id.
+     * @param applicationId - The application's Mongo `_id`.
+     */
+    async getApp(applicationId: string): Promise<Application> {
+      try {
+        const res = await this.makeRequest<{ application: Application }>(
+          'GET',
+          `/applications/${encodeURIComponent(applicationId)}`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.LONG },
+        );
+        return res.application;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Update an application's mutable fields.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param data - Subset of updatable fields. Staff-only fields are ignored.
+     */
+    async updateApp(
+      applicationId: string,
+      data: UpdateApplicationInput,
+    ): Promise<Application> {
+      try {
+        const res = await this.makeRequest<{ application: Application }>(
+          'PATCH',
+          `/applications/${encodeURIComponent(applicationId)}`,
+          data,
+          { cache: false },
+        );
+        // Bust the cached detail and every list (which embeds application fields).
+        this.clearCacheEntry(`GET:/applications/${encodeURIComponent(applicationId)}`);
+        this._invalidateAppLists();
+        return res.application;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Soft-delete an application.
+     * @param applicationId - The application's Mongo `_id`.
+     */
+    async deleteApp(applicationId: string): Promise<AccountSuccessResult> {
+      try {
+        const result = await this.makeRequest<AccountSuccessResult>(
+          'DELETE',
+          `/applications/${encodeURIComponent(applicationId)}`,
+          undefined,
+          { cache: false },
+        );
+        // Bust every cached representation of the deleted application.
+        this.clearCacheEntry(`GET:/applications/${encodeURIComponent(applicationId)}`);
+        this.clearCacheEntry(`GET:/applications/${encodeURIComponent(applicationId)}/credentials`);
+        this._invalidateAppLists();
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    // =========================================================================
+    // Application OAuth credentials  —  /applications/:appId/credentials
+    // =========================================================================
+
+    /**
+     * List an application's OAuth credentials. The response NEVER includes
+     * secrets.
+     * @param applicationId - The application's Mongo `_id`.
+     */
+    async listAppCredentials(applicationId: string): Promise<ApplicationCredential[]> {
+      try {
+        const res = await this.makeRequest<{ credentials?: ApplicationCredential[] }>(
+          'GET',
+          `/applications/${encodeURIComponent(applicationId)}/credentials`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.credentials ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Create an application credential. The plaintext `secret` is returned
+     * exactly ONCE; the server stores only a hash and will never return it again.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param data - Credential configuration.
+     */
+    async createAppCredential(
+      applicationId: string,
+      data: CreateApplicationCredentialInput,
+    ): Promise<ApplicationCredentialWithSecret> {
+      try {
+        const result = await this.makeRequest<ApplicationCredentialWithSecret>(
+          'POST',
+          `/applications/${encodeURIComponent(applicationId)}/credentials`,
+          data,
+          { cache: false },
+        );
+        this.clearCacheEntry(`GET:/applications/${encodeURIComponent(applicationId)}/credentials`);
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Rotate an application credential's secret. The new plaintext `secret` is
+     * returned exactly ONCE, along with audit fields: `rotatedFrom` (the previous
+     * credentialId) and `graceExpiresAt` (ISO string for the grace window during
+     * which the old credential is still honoured).
+     * @param applicationId - The application's Mongo `_id`.
+     * @param credentialId - The credential's Mongo `_id`.
+     */
+    async rotateAppCredential(
+      applicationId: string,
+      credentialId: string,
+    ): Promise<RotateApplicationCredentialResult> {
+      try {
+        const result = await this.makeRequest<RotateApplicationCredentialResult>(
+          'POST',
+          `/applications/${encodeURIComponent(applicationId)}/credentials/${encodeURIComponent(credentialId)}/rotate`,
+          undefined,
+          { cache: false },
+        );
+        // Rotation changes credential status/audit fields surfaced by the list.
+        this.clearCacheEntry(`GET:/applications/${encodeURIComponent(applicationId)}/credentials`);
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Revoke an application credential (`status='revoked'`). Revoked credentials
+     * can no longer authenticate.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param credentialId - The credential's Mongo `_id`.
+     */
+    async revokeAppCredential(
+      applicationId: string,
+      credentialId: string,
+    ): Promise<AccountSuccessResult> {
+      try {
+        const result = await this.makeRequest<AccountSuccessResult>(
+          'DELETE',
+          `/applications/${encodeURIComponent(applicationId)}/credentials/${encodeURIComponent(credentialId)}`,
+          undefined,
+          { cache: false },
+        );
+        // Revocation flips the credential's status in the cached list.
+        this.clearCacheEntry(`GET:/applications/${encodeURIComponent(applicationId)}/credentials`);
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Fetch usage statistics for an application.
+     * @param applicationId - The application's Mongo `_id`.
+     * @param period - Time window (defaults to the server default).
+     */
+    async getAppUsage(
+      applicationId: string,
+      period?: ApplicationUsagePeriod,
+    ): Promise<ApplicationUsageStats> {
+      try {
+        return await this.makeRequest<ApplicationUsageStats>(
+          'GET',
+          `/applications/${encodeURIComponent(applicationId)}/usage`,
+          period ? { period } : undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    // =========================================================================
+    // Cache-invalidation helpers
+    // =========================================================================
+
+    /**
+     * Bust every cached account list. `listAccounts({tree?})` keys the flat list
+     * as `GET:/accounts` and the tree variant as `GET:/accounts?tree=true` (the
+     * query string is part of the URL path). A change to the accessible forest
+     * (create/archive/ownership transfer) invalidates both, so we clear the
+     * unscoped entry plus every `?`-query variant via a prefix sweep. The prefix
+     * `GET:/accounts?` matches only the query-string list variants, never the
+     * `GET:/accounts/<id>…` detail/sub-resource keys.
+     *
+     * Internal helper (leading underscore); not part of the supported public
+     * surface. Public rather than `private` because mixins compose into an
+     * exported anonymous class, where TypeScript cannot represent a private
+     * member in the emitted declaration file (TS4094).
+     */
+    _invalidateAccountLists(): void {
+      this.clearCacheEntry('GET:/accounts');
+      this.clearCacheByPrefix('GET:/accounts?');
+    }
+
+    /**
+     * Bust the cached member list and detail for an account after a membership
+     * mutation. The member list (`listAccountMembers`) and the detail
+     * (`getAccount`, which can embed the caller's membership) both go stale when
+     * the member set or a member's role changes.
+     *
+     * Internal helper (leading underscore); see `_invalidateAccountLists` for why
+     * this is public rather than `private`.
+     */
+    _invalidateAccountMembership(accountId: string): void {
+      this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/members`);
+      this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
+    }
+
+    /**
+     * Bust every cached application list. `listAccountApps(accountId)` keys each
+     * owner-scoped list as `GET:/applications?ownerAccountId=<id>` (the query
+     * string is part of the URL path). A change to any list (create/delete)
+     * invalidates them all, so we clear the unscoped entry plus every `?`-query
+     * variant via a prefix sweep. The prefix `GET:/applications?` matches only the
+     * query-string list variants, never the `GET:/applications/<id>…`
+     * detail/sub-resource keys.
+     *
+     * Internal helper (leading underscore); see `_invalidateAccountLists` for why
+     * this is public rather than `private`.
+     */
+    _invalidateAppLists(): void {
+      this.clearCacheEntry('GET:/applications');
+      this.clearCacheByPrefix('GET:/applications?');
+    }
+  };
+}