@oxy.so/core 1.18.0 → 3.0.0

package/dist/esm/mixins/OxyServices.accounts.js

@@ -1,543 +0,0 @@
-import { normalizeUserIdentity } from '../utils/userIdentity.js';
-import { evictOxyIdentityCache } from '../utils/identityCacheSweep.js';
-import { evictOxyAccountForestCache, oxyAccountDetailCacheKey, OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX } from '../utils/accountCacheSweep.js';
-import { CACHE_TIMES } from './mixinHelpers.js';
-export { ACCOUNT_CATEGORY_IDS, ACCOUNT_KINDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from '@oxy.so/contracts';
-export function OxyServicesAccountsMixin(Base) {
-    return class extends Base {
-        constructor(...args) {
-            super(...args);
-        }
-        // =========================================================================
-        // 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) {
-            try {
-                const path = opts?.tree ? '/accounts?tree=true' : '/accounts';
-                const res = await this.makeRequest('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) {
-            try {
-                const res = await this.makeRequest('GET', `/accounts/${encodeURIComponent(accountId)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.LONG });
-                return res.account;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Switch the active session INTO a managed account.
-         *
-         * Calls `POST /accounts/:id/switch` with the signed-in operator's bearer.
-         * The server authorises the operator (must hold `account:act_as` over the
-         * target, directly or inherited — else 403; 404 if missing/archived; 403 if
-         * the target is a personal account), then mints a REAL session for the
-         * target account and returns it in the canonical login / `claimSessionByToken`
-         * shape (`{ sessionId, deviceId, expiresAt, accessToken, user }`).
-         *
-         * Unlike the removed `X-Acting-As` delegation header, the returned session
-         * IS the new identity: this plants `accessToken` as the active token —
-         * exactly like `claimSessionByToken` / `verifyChallenge` — so every
-         * subsequent request authenticates as the target account.
-         *
-         * A single call is all that's needed: the server registers the switched
-         * session into the operator's `DeviceSession` set directly, inheriting the
-         * operator's central `deviceId` so the switch survives a reload and syncs
-         * cross-domain via the same device-first session model as a normal login —
-         * there is no separate client-side cookie/slot step to make it stick.
-         *
-         * After planting, the SDK's identity-scoped GET cache is fully cleared so
-         * every cached read re-fetches as the new account. (The consuming
-         * `OxyContext` additionally invalidates its React Query cache and updates
-         * session state from the returned `user`; this clears the SDK's own HTTP
-         * cache at the source — `setTokens` deliberately preserves the warm cache for
-         * same-user silent refreshes, so the sweep here is explicit.)
-         *
-         * @param accountId - The target account's Mongo `_id`.
-         * @returns The minted session, already planted as the active session.
-         */
-        async switchToAccount(accountId) {
-            try {
-                const res = await this.makeRequest('POST', `/accounts/${encodeURIComponent(accountId)}/switch`, undefined, { cache: false });
-                // Plant the freshly minted session as the ACTIVE session, mirroring
-                // `claimSessionByToken` / `verifyChallenge`: the response body carries
-                // the first access token.
-                if (res?.accessToken) {
-                    this.setTokens(res.accessToken);
-                }
-                // The switch route now registers the switched session in the device's
-                // server-side DeviceSession set directly (device-first), so there is no
-                // client-side refresh-cookie slot to establish — the `authuser` comes
-                // from the switch response (optional-chained to match `res?.accessToken`).
-                const authuser = res?.authuser;
-                // Identity changed → drop the entire GET response cache so no entry
-                // personalised for the previous identity is reused. Cache keys are
-                // identity-scoped, so a different identity could not READ the old
-                // entries anyway, but clearing guarantees a clean refetch as the new
-                // account and frees the prior identity's resident data.
-                this.clearCache();
-                return {
-                    ...res,
-                    ...(typeof authuser === 'number' ? { authuser } : {}),
-                    user: normalizeUserIdentity(res.user),
-                };
-            }
-            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) {
-            try {
-                const res = await this.makeRequest('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.
-                evictOxyAccountForestCache(this);
-                return res.account;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Mint a `channel` account under `ownerUserId` via service auth
-         * (`accounts:provision` scope). Requires `configureServiceAuth` first.
-         */
-        async provisionChannelAccount(data) {
-            try {
-                return await this.makeServiceRequest('POST', '/accounts/service/channels', data);
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Grant membership on a channel account via service auth
-         * (`accounts:provision` scope).
-         */
-        async provisionChannelMember(channelAccountId, data) {
-            try {
-                return await this.makeServiceRequest('POST', `/accounts/service/channels/${encodeURIComponent(channelAccountId)}/members`, data);
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Revoke membership on a channel account via service auth
-         * (`accounts:provision` scope).
-         */
-        async revokeChannelMember(channelAccountId, memberUserId) {
-            try {
-                return await this.makeServiceRequest('DELETE', `/accounts/service/channels/${encodeURIComponent(channelAccountId)}/members/${encodeURIComponent(memberUserId)}`);
-            }
-            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.
-         *
-         * An account IS a user, so this write changes identity — and a profile
-         * screen never reads `/accounts/<id>`. It reads `GET /users/<id>` and
-         * `GET /profiles/username/<handle>`, both cached for 5 minutes in the
-         * CALLER'S OWN process, so busting only the account-graph keys left every
-         * profile surface serving the pre-edit avatar and name for the full TTL
-         * with a perfectly healthy server (the cross-service `oxy:user:invalidate`
-         * signal does not help: it evicts BACKEND caches, and cannot reach a cache
-         * living in a browser tab). {@link evictOxyIdentityCache} owns that key
-         * list — see its docs for why the handle-keyed entries are prefix-swept
-         * (a RENAME leaves the old handle's entry unreachable by any targeted key).
-         *
-         * @param accountId - The account's Mongo `_id`.
-         * @param data - Subset of updatable profile fields.
-         */
-        async updateAccount(accountId, data) {
-            try {
-                const res = await this.makeRequest('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.
-                evictOxyAccountForestCache(this, accountId);
-                // The parent's children list embeds this account's profile and is keyed
-                // by the PARENT id, so it is reachable only from the response node.
-                const parentAccountId = res.account?.parentAccountId;
-                if (parentAccountId) {
-                    this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(parentAccountId)}/children`);
-                }
-                // Every identity read of this account, whichever key it lands under.
-                evictOxyIdentityCache(this, accountId);
-                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) {
-            try {
-                const result = await this.makeRequest('DELETE', `/accounts/${encodeURIComponent(accountId)}`, undefined, { cache: false });
-                // Bust every cached representation of the archived account.
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/members`);
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-                evictOxyAccountForestCache(this, accountId);
-                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) {
-            try {
-                const res = await this.makeRequest('GET', `/accounts/${encodeURIComponent(accountId)}/children`, undefined, { cache: true, cacheTTL: CACHE_TIMES.MEDIUM });
-                return res.accounts ?? [];
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        // =========================================================================
-        // Account members
-        // =========================================================================
-        /**
-         * List the members of an account: the membership rows ON it, plus the rows
-         * on its ancestors that cascade into it. Each entry carries `source`
-         * (`direct` | `inherited`) saying which it is.
-         *
-         * Inherited entries are members in every sense the server enforces — an
-         * ancestor row with `inherit: true` resolves through
-         * `resolveEffectiveAccess` and confers every account permission on the
-         * descendant, `account:act_as` included — so a roster that omitted them
-         * answered `[]` for accounts several people could act on.
-         *
-         * Two things follow for a caller. An entry's `accountId` is the account its
-         * ROW lives on, so an inherited entry names an ancestor rather than the
-         * account you asked about; and the member-mutation endpoints only accept
-         * rows on the account in the path, so gate any edit/remove/transfer
-         * affordance on `source === 'direct'`.
-         *
-         * Asking what the CALLER holds over an account is a different question, and
-         * scanning this list for yourself is the wrong way to answer it — use
-         * {@link OxyServicesAccountsMixin.getAccount}, whose `callerMembership` is
-         * the server's own resolution.
-         *
-         * @param accountId - The account's Mongo `_id`.
-         */
-        async listAccountMembers(accountId) {
-            try {
-                const res = await this.makeRequest('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, data) {
-            try {
-                const res = await this.makeRequest('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, memberId, data) {
-            try {
-                const res = await this.makeRequest('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, memberId) {
-            try {
-                const result = await this.makeRequest('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, data) {
-            try {
-                const result = await this.makeRequest('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);
-                evictOxyAccountForestCache(this);
-                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) {
-            try {
-                const res = await this.makeRequest('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) {
-            try {
-                const res = await this.makeRequest('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) {
-            try {
-                const res = await this.makeRequest('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, data) {
-            try {
-                const res = await this.makeRequest('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) {
-            try {
-                const result = await this.makeRequest('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) {
-            try {
-                const res = await this.makeRequest('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, data) {
-            try {
-                const result = await this.makeRequest('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`.
-         * @param options - `graceSeconds` keeps a superseded `machine` token working
-         *   for that long. Omitted, the previous token dies the moment the
-         *   replacement is minted.
-         */
-        async rotateAppCredential(applicationId, credentialId, options) {
-            try {
-                const result = await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/credentials/${encodeURIComponent(credentialId)}/rotate`, options, { 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, credentialId) {
-            try {
-                const result = await this.makeRequest('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, period) {
-            try {
-                return await this.makeRequest('GET', `/applications/${encodeURIComponent(applicationId)}/usage`, period ? { period } : undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        // =========================================================================
-        // Cache-invalidation helpers
-        // =========================================================================
-        /**
-         * 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); 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).
-         *
-         * The forest keys themselves are NOT owned here — see
-         * `utils/accountCacheSweep`, which the user mixin has to reach as well.
-         */
-        _invalidateAccountMembership(accountId) {
-            this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/members`);
-            this.clearCacheEntry(oxyAccountDetailCacheKey(accountId));
-            // Inherited rows on descendant rosters are derived from this account's
-            // membership table — a targeted clear of only the mutated account's keys
-            // leaves every other cached `…/members` list serving stale inherited
-            // roles until MEDIUM TTL. Sweep all per-account sub-resource keys instead;
-            // the forest list keys (`GET:/accounts`, `GET:/accounts?…`) are excluded
-            // by the trailing slash on the prefix (see accountCacheSweep).
-            this.clearCacheByPrefix(OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX);
-        }
-        /**
-         * 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 `_invalidateAccountMembership`
-         * for why this is public rather than `private`.
-         */
-        _invalidateAppLists() {
-            this.clearCacheEntry('GET:/applications');
-            this.clearCacheByPrefix('GET:/applications?');
-        }
-    };
-}