@oxyhq/core 18.0.0 → 19.1.0

package/dist/types/index.d.ts

@@ -39,8 +39,8 @@ export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHand
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
-export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
-export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
+export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';
 export { parseIdPayload, parseAttestPayload, verifyPublicCardAttestation, } from './mixins/OxyServices.civic';
@@ -104,7 +104,7 @@ export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
 export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState';
-export { projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
+export { isSwitchTargetAccount, projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
 export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
 export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFlowPhase, SignInFlowState, SignInProgress, } from './session/accountDialogController';

package/dist/types/mixins/OxyServices.accounts.d.ts

@@ -33,7 +33,7 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
-import type { AccountKind, OrganizationCategory, ChildAccountKind } from '@oxyhq/contracts';
+import type { AccountCategoryId, AccountKind, ChildAccountKind } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 /**
@@ -45,8 +45,8 @@ import type { OxyServicesBase } from '../OxyServices.base';
  *
  * Single source of truth is `@oxyhq/contracts`.
  */
-export type { AccountKind, OrganizationCategory } from '@oxyhq/contracts';
-export { ACCOUNT_KINDS, ORGANIZATION_CATEGORIES, isActAsEligibleKind } from '@oxyhq/contracts';
+export type { AccountCategoryId, AccountKind } from '@oxyhq/contracts';
+export { ACCOUNT_CATEGORY_IDS, ACCOUNT_KINDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isActAsEligibleKind, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from '@oxyhq/contracts';
 /**
  * The calling user's relationship to an account node, as resolved by the API:
  * - `self` — the caller's own personal (root) account.
@@ -66,8 +66,8 @@ export type AccountMemberStatus = 'active' | 'invited' | 'removed';
  */
 export type AccountMemberSource = 'direct' | 'inherited';
 /**
- * Client-facing AccountMember shape. `permissions` is derived from `role` on the
- * server at write time.
+ * Client-facing AccountMember shape. `permissions` is the effective permission
+ * set (role baseline plus `permissionGrants` minus `permissionRevokes`).
  */
 export interface AccountMember {
     _id: string;
@@ -77,6 +77,10 @@ export interface AccountMember {
     memberUserId: string;
     role: AccountRole;
     permissions: string[];
+    /** Permissions granted beyond the role baseline. */
+    permissionGrants?: string[];
+    /** Permissions revoked from the role baseline. */
+    permissionRevokes?: string[];
     /**
      * Whether this membership cascades to the account's subtree. `true` (default)
      * lets descendants inherit this role unless a nearer row overrides it; `false`
@@ -85,12 +89,20 @@ export interface AccountMember {
     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).
+     * Where this membership COMES FROM relative to the account it is being
+     * reported for: `direct` when the row lives on that account, `inherited` when
+     * it lives on an ancestor whose `inherit` flag cascades it down.
+     *
+     * Present on every membership the API serialises — a resolved
+     * `callerMembership` and every entry of a member list alike. It is not
+     * decoration: an `inherited` entry's `accountId` is the ANCESTOR's, and the
+     * member-mutation endpoints are scoped to rows on the account named in the
+     * path, so `PATCH`/`DELETE .../members/<that row's _id>` against the
+     * descendant 404s. **Branch on `source === 'direct'` before offering to edit,
+     * remove or transfer to a member**, and count owners for a last-owner check
+     * over direct entries only.
      */
-    source?: AccountMemberSource;
+    source: AccountMemberSource;
     invitedByUserId?: string | null;
     joinedAt?: string | null;
     createdAt: string;
@@ -168,8 +180,17 @@ export interface CreateAccountInput {
     };
     bio?: string;
     avatar?: string;
-    /** Meaningful only when `kind` is `organization`. */
-    organizationCategory?: OrganizationCategory;
+    /**
+     * What the account is about. ORDERED — the FIRST element is the primary
+     * category, so a picker must submit them in the order the user arranged them
+     * and must not sort. Stable ids, never labels: render each one through the
+     * `accounts.accountCategory.<id>` translation key.
+     *
+     * Offer `SELECTABLE_ACCOUNT_CATEGORY_IDS`, not `ACCOUNT_CATEGORY_IDS` — the
+     * latter still contains withdrawn ids so that accounts already carrying one
+     * keep working. At most `MAX_ACCOUNT_CATEGORIES`, no duplicates.
+     */
+    accountCategories?: AccountCategoryId[];
 }
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
 export interface UpdateAccountInput {
@@ -187,8 +208,19 @@ export interface UpdateAccountInput {
     };
     bio?: string | null;
     avatar?: string | null;
-    /** Clears the category when `null`; only valid on `kind: 'organization'`. */
-    organizationCategory?: OrganizationCategory | null;
+    /**
+     * Replaces the WHOLE list, in the order given — there is no add/remove verb,
+     * because a partial edit cannot express a re-ordering and the order is what
+     * names the primary category. `[]` clears it.
+     *
+     * Not nullable, unlike `bio` and `avatar`: the empty case already has a
+     * spelling of its own, so a second one could only ever disagree with it.
+     *
+     * Rejected for a `personal` account, and rejected when it ADDS a withdrawn
+     * id the account did not already carry — keeping or re-ordering one it has is
+     * always allowed.
+     */
+    accountCategories?: AccountCategoryId[];
 }
 /** Input accepted by `provisionChannelAccount` (service token + `accounts:provision`). */
 export interface ProvisionChannelInput {
@@ -226,7 +258,10 @@ export interface InviteAccountMemberInput {
 }
 /** Input accepted by `updateAccountMember`. The owner role cannot be assigned. */
 export interface UpdateAccountMemberInput {
-    role: Exclude<AccountRole, 'owner'>;
+    role?: Exclude<AccountRole, 'owner'>;
+    inherit?: boolean;
+    permissionGrants?: string[];
+    permissionRevokes?: string[];
 }
 /** Input accepted by `transferAccountOwnership`. */
 export interface TransferAccountOwnershipInput {
@@ -560,6 +595,18 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
         /**
          * 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.
          */
@@ -577,7 +624,27 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          */
         listChildAccounts(accountId: string): Promise<AccountNode[]>;
         /**
-         * List members of an account (direct membership rows on the account).
+         * 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`.
          */
         listAccountMembers(accountId: string): Promise<AccountMember[]>;
@@ -702,28 +769,18 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          */
         getAppUsage(applicationId: string, period?: ApplicationUsagePeriod): Promise<ApplicationUsageStats>;
         /**
-         * 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.
+         * 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).
-         */
-        _invalidateAccountLists(): void;
-        /**
-         * 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`.
+         * The forest keys themselves are NOT owned here — see
+         * `utils/accountCacheSweep`, which the user mixin has to reach as well.
          */
         _invalidateAccountMembership(accountId: string): void;
         /**
@@ -735,8 +792,8 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * 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`.
+         * Internal helper (leading underscore); see `_invalidateAccountMembership`
+         * for why this is public rather than `private`.
          */
         _invalidateAppLists(): void;
         httpService: import("../HttpService").HttpService;

package/dist/types/mixins/OxyServices.followGraph.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Follow Graph Mixin (`/v2/follows`)
+ *
+ * The user-owned follow graph: one relationship per user and target, shared by
+ * every application, with per-application context on top. This is the SDK half
+ * of #809 and the replacement for the per-app follow endpoints each application
+ * grew for itself.
+ *
+ * ## Why this is not `followUser` with more parameters
+ *
+ * `followUser` answers "does A follow B" and nothing else. This answers "what
+ * does this user follow, anywhere, and which applications act on it" — a
+ * different question with a different owner. The legacy methods stay for the
+ * Mongo-backed social graph they were written for; new kinds (topics, stores,
+ * artists, channels) come here, and users will migrate behind an adapter rather
+ * than through a flag day.
+ *
+ * ## Caching
+ *
+ * Every method is `cache: false`. A follow status is exactly the shape that
+ * must never be served stale: the SDK's GET cache is identity-scoped but
+ * time-based, and a status cached across a write is the "follow reverts after
+ * navigating away and back" bug — which the legacy `followUser` had to fix with
+ * explicit invalidation. Not caching at this layer means an app's own store
+ * (React Query, Zustand) is the single cache authority, which is the rule the
+ * ecosystem already follows for anything written and read in the same session.
+ */
+import type { FollowListPage, FollowMutation, FollowOptions, FollowStatus, UnfollowMutation } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesFollowGraphMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Follow a target. Idempotent — following something already followed
+         * returns the same relationship with `created: false`.
+         *
+         * The follower and the acting application are BOTH derived server-side from
+         * the session. There is deliberately no parameter for either: a client that
+         * could name them could forge a follow on another user's behalf, or record
+         * one as coming from an application it is not.
+         *
+         * @param targetId - The registered target's id, not its URI. Registration is
+         *   a separate operation precisely so following cannot silently create
+         *   targets — a typo would otherwise become a permanent row nobody follows.
+         * @param options.expiresIn - Seconds until the follow lapses on its own. For
+         *   an event, a trial, a topic followed for a week. The server bounds it.
+         */
+        followTarget(targetId: string, options?: FollowOptions): Promise<FollowMutation>;
+        /**
+         * Unfollow everywhere.
+         *
+         * There is no "unfollow here" — that is `setFollowApplicationMode(...,
+         * 'disabled')`, and keeping the two distinct is the point of the design. An
+         * application that quietly turned a global unfollow into a local one would
+         * leave the user believing they had stopped following something they still
+         * follow everywhere else.
+         *
+         * Idempotent: `removed: false` when it was already gone, because the state
+         * the caller asked for is the state that holds.
+         */
+        unfollowTarget(relationshipId: string): Promise<UnfollowMutation>;
+        /**
+         * The three-part status: globally, in this application, and in effect.
+         *
+         * Render `effectiveState` on the button and keep the other two for the
+         * explanation. A UI that collapses them cannot tell the user why a follow
+         * they can see in their list is not showing up in this app's feed.
+         */
+        getFollowTargetStatus(targetId: string): Promise<FollowStatus>;
+        /**
+         * Turn a relationship off, or back on, in ONE application.
+         *
+         * Omit `applicationId` and it applies to the calling application, which is
+         * the only form an ordinary app should ever need. Naming a DIFFERENT
+         * application requires `follows:manage` server-side — acting on another
+         * app's behalf is exactly the cross-application authority this design
+         * otherwise refuses, so it is a distinct permission and not a parameter an
+         * app happens to fill in.
+         */
+        setFollowApplicationMode(relationshipId: string, mode: "enabled" | "disabled", applicationId?: string): Promise<{
+            ok: true;
+            mode: "enabled" | "disabled";
+        }>;
+        /**
+         * Drop the override so this application follows the global relationship
+         * again. Distinct from setting `enabled`: inheriting means a later global
+         * change takes effect here, and an explicit `enabled` means it does not.
+         */
+        restoreFollowInheritance(relationshipId: string, applicationId?: string): Promise<{
+            ok: true;
+        }>;
+        /**
+         * Resolve a target by canonical URI, registering it the first time anyone
+         * asks. The call an application makes on the way into a screen, before it
+         * can render a button.
+         *
+         * Idempotent on the URI, which is what makes two applications describing
+         * the same thing — the same fediverse actor, the same topic — arrive at ONE
+         * row, and therefore at one relationship per user rather than one per app.
+         *
+         * `metadata` is a display snapshot (name, handle, icon) and is refreshed
+         * only for the application that provides the target: a second application
+         * passing its own idea of the name would make the display flip depending on
+         * which app last looked.
+         */
+        ensureFollowTarget(input: {
+            uri: string;
+            kind: string;
+            metadata?: Record<string, unknown>;
+            providerReference?: string;
+            localUserId?: string;
+        }): Promise<{
+            id: string;
+            uri: string;
+            kind: string;
+            created: boolean;
+        }>;
+        /**
+         * Claim a namespace for the calling application. First come, and idempotent
+         * for the holder — an application that registers on every boot must not
+         * fail the second time.
+         */
+        claimFollowNamespace(namespace: string): Promise<{
+            namespace: string;
+            created: boolean;
+        }>;
+        /**
+         * Declare what following a kind of thing MEANS: the verb clients render,
+         * whether reverse lookups are public, whether it federates.
+         *
+         * Declared once by the application that owns the concept, rather than
+         * passed per call site — otherwise two screens of one app can disagree
+         * about whether a store is followed or subscribed to.
+         */
+        registerFollowKind(input: {
+            kind: string;
+            label?: string;
+            capabilities?: {
+                verb?: "follow" | "subscribe" | "join";
+                reverse?: "public" | "private" | "aggregate" | "unavailable";
+                federated?: boolean;
+            };
+        }): Promise<{
+            kind: string;
+            created: boolean;
+        }>;
+        /**
+         * Everything the signed-in user follows, newest first.
+         *
+         * Owner-only by construction server-side — there is no parameter naming a
+         * user, so this cannot be pointed at somebody else's graph.
+         *
+         * Paginate by passing back `nextCursor`, never an offset: the list changes
+         * while it is being read, and an offset silently skips or repeats rows
+         * exactly when it does.
+         */
+        listFollows(params?: {
+            kind?: string;
+            cursor?: string;
+            limit?: number;
+        }): Promise<FollowListPage>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/OxyServices.user.d.ts

@@ -254,13 +254,16 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         /**
          * Update user profile.
          *
-         * Invalidates the SDK-side response cache for every endpoint that
-         * returns the current user (`GET /users/me`, `GET /session/user/*`,
-         * `GET /users/<id>`, `GET /profiles/username/*`) so the next read
-         * doesn't return a stale snapshot. Without this, a follow-up
-         * `getUserBySession` call inside the 2-minute cache window can return
-         * the pre-update user — most visibly during onboarding, where it
-         * causes the username step to flicker back as if nothing was saved.
+         * Invalidates the SDK-side response cache for every endpoint that can
+         * return this user — the list is owned by {@link evictOxyIdentityCache}, so
+         * a new identity read is added in one place instead of to each writer
+         * separately (this method's own hand-written copy had already drifted from
+         * the server-side one, missing `GET /auth/lookup/*` and
+         * `GET /profiles/resolve`). The account forest (`GET /accounts` and the
+         * caller's own detail row) is swept too — a personal account IS this user,
+         * and `AccountNode.account` embeds the whole profile — from the list that
+         * {@link evictOxyAccountForestCache} owns, for the same reason: the accounts
+         * mixin writes those keys as well, and two hand-written copies drift.
          *
          * TanStack Query handles offline queuing automatically.
          */

package/dist/types/mixins/index.d.ts

@@ -29,6 +29,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
+import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
 import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 /**
@@ -40,7 +41,7 @@ import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

package/dist/types/models/interfaces.d.ts

@@ -1,4 +1,4 @@
-import type { AccountKind, OrganizationCategory, UserNameResponse, UserRelationship, ThemePreference } from '@oxyhq/contracts';
+import type { AccountKind, AccountCategoryId, UserNameResponse, UserRelationship, ThemePreference } from '@oxyhq/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
@@ -151,8 +151,16 @@ export interface User {
     };
     isManagedAccount?: boolean;
     managedBy?: string;
-    /** Real-estate taxonomy when this user is a `kind: 'organization'` account. */
-    organizationCategory?: OrganizationCategory;
+    /**
+     * What this account is about, for any NON-personal account. ORDERED — the
+     * first element is the primary category, and nothing may reorder it.
+     *
+     * Stable ids, not labels: render each through the
+     * `accounts.accountCategory.<id>` translation key so the reader sees their own
+     * language rather than the language of whoever chose it. Absent when the
+     * account has none.
+     */
+    accountCategories?: AccountCategoryId[];
     /**
      * The account's languages as full BCP-47 locales (`language-REGION`, e.g.
      * `en-US`, `es-MX`, `pt-BR`), ordered with the PRIMARY (UI) locale first.

package/dist/types/server/index.d.ts

@@ -25,7 +25,9 @@ export type { OxyCorsOptions } from './cors';
 export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders, formatOxyCspPolicy, OXY_CSP_BASELINE, } from './securityHeaders';
 export type { OxyCspDirective, OxyCspExtensions, OxyPagesHeadersOptions, OxySecurityHeadersOptions, } from './securityHeaders';
 export { verifySecret } from './verifySecret';
-export { createOxyUserInvalidationHandler, evictOxyIdentityCache, publishOxyUserInvalidation, } from './userInvalidation';
-export type { OxyIdentityCacheEvictor, OxyInvalidationPublisher, OxyUserInvalidationHandlerOptions, } from './userInvalidation';
+export { createOxyUserInvalidationHandler, publishOxyUserInvalidation, } from './userInvalidation';
+export type { OxyInvalidationPublisher, OxyUserInvalidationHandlerOptions, } from './userInvalidation';
+export { evictOxyIdentityCache, oxyUserByIdCacheKey, OXY_IDENTITY_CACHE_PREFIXES } from '../utils/identityCacheSweep';
+export type { OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
 export { registrableApex } from '../utils/registrableApex';
 export { isOfficialWebOrigin } from '../utils/officialOrigins';

package/dist/types/server/userInvalidation.d.ts

@@ -6,10 +6,10 @@
  * Every Oxy backend caches Oxy identity, and none of them find out when it
  * changes. The `OxyServices` GET response cache holds `GET /users/:id` and
  * `GET /profiles/username/:name` for five minutes; it is swept when THIS process
- * writes the profile (see the `clearCacheEntry` calls in the user mixin) and
- * never when somebody else does — which is the normal case, since profiles are
- * edited in Oxy's own apps. So an avatar or display-name change is invisible to
- * every consuming backend for up to five minutes, per process.
+ * writes the profile (the `evictOxyIdentityCache` calls in the user and accounts
+ * mixins) and never when somebody else does — which is the normal case, since
+ * profiles are edited in Oxy's own apps. So an avatar or display-name change is
+ * invisible to every consuming backend for up to five minutes, per process.
  *
  * oxy-api broadcasts {@link OXY_USER_INVALIDATION_CHANNEL} on the shared Valkey
  * when a user's identity changes. This module is the consumer half: it parses
@@ -51,6 +51,7 @@
  * Node-only; exported solely from `@oxyhq/core/server`.
  */
 import { type OxyUserChangeReason, type OxyUserInvalidationEvent } from '@oxyhq/contracts';
+import { type OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
 /**
  * The publish surface of a Redis client. Both `ioredis` and `node-redis`
  * satisfy this structurally, so neither library is a dependency here.
@@ -58,14 +59,6 @@ import { type OxyUserChangeReason, type OxyUserInvalidationEvent } from '@oxyhq/
 export interface OxyInvalidationPublisher {
     publish(channel: string, message: string): unknown;
 }
-/**
- * The cache-eviction surface of an {@link OxyServices} instance. Declared
- * structurally so this Node-only module does not pull in the client.
- */
-export interface OxyIdentityCacheEvictor {
-    clearCacheEntry(key: string): void;
-    clearCacheByPrefix(prefix: string): number;
-}
 /**
  * Broadcast that an Oxy user's record changed.
  *
@@ -119,15 +112,3 @@ export interface OxyUserInvalidationHandlerOptions {
  * fixes.
  */
 export declare function createOxyUserInvalidationHandler(options?: OxyUserInvalidationHandlerOptions): (raw: string) => void;
-/**
- * Sweep an `OxyServices` GET response cache of everything that could carry the
- * given user's identity.
- *
- * The by-id entry is exact. The by-username and resolve entries are keyed by
- * HANDLE, which cannot be derived from an id without the very lookup we are
- * invalidating, so those are swept by prefix — the same imprecision the SDK
- * already accepts when it sweeps its own cache after a local profile write, and
- * bounded by the fact that over-eviction costs a refetch and can never serve
- * wrong data.
- */
-export declare function evictOxyIdentityCache(oxy: OxyIdentityCacheEvictor, userId: string): void;