@oxyhq/core 19.0.0 → 19.1.1

package/dist/types/index.d.ts

@@ -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

@@ -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;
@@ -246,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 {
@@ -609,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[]>;
@@ -734,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;
         /**
@@ -767,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,210 @@
+/**
+ * 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;
+        }>;
+        /**
+         * 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" | "watch";
+                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

@@ -259,10 +259,11 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * 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`). Without the sweep a follow-up
-         * `getUserBySession` inside the cache window returns the pre-update user —
-         * most visibly during onboarding, where the username step flickers back as
-         * if nothing was saved.
+         * `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/session/accountProjection.d.ts

@@ -91,6 +91,36 @@ export interface SwitchableAccount {
     /** The underlying per-account user payload. */
     user: SwitchableAccountUser;
 }
+/**
+ * Whether the caller can BECOME this account — the one question every account
+ * switcher asks, answered here so no surface has to re-derive it.
+ *
+ * Two independent grounds, either of which suffices:
+ *
+ *  - **It is already the caller's own identity** (`relationship: 'self'`).
+ *    `GET /accounts` resolves its caller through `resolveOperatorId`, so `self`
+ *    is the HUMAN operator's personal account even while they are operating an
+ *    org — never the operated account. Kind is irrelevant on this ground: the
+ *    caller IS that account, so returning to it asks the server for nothing.
+ *  - **The server will mint a session for it** — `isActAsEligibleKind(kind)` is
+ *    the exact predicate `POST /accounts/:id/switch` enforces, so a row offered
+ *    on this ground is never a dead button.
+ *
+ * `isActAsEligibleKind` ALONE is not this question, and reaching for it
+ * directly is the mistake this function exists to prevent: it is false for
+ * `personal` as well as `channel`, so a switcher gated on it alone renders an
+ * empty list rather than a filtered one. Equally, `kind !== 'channel'` is not
+ * this question either — it silently admits every kind invented after it was
+ * written, which is the same trap `isActAsEligibleKind` was introduced to close
+ * on the server.
+ *
+ * Takes a structural subset rather than a whole {@link AccountNode} so a caller
+ * holding a projected {@link SwitchableAccount} can ask it too.
+ */
+export declare function isSwitchTargetAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+}): boolean;
 /** Input to {@link projectSwitchableAccounts}. */
 export interface ProjectSwitchableAccountsInput {
     /**
@@ -131,8 +161,9 @@ export interface ProjectSwitchableAccountsInput {
  * and a graph node is deduped into ONE device row enriched with the graph
  * metadata (relationship / kind / parent / membership).
  *
- * Graph nodes of a kind nobody may act as (`channel`) are omitted — see the
- * filter below.
+ * Graph nodes that are not switch targets — a `channel`, which nobody may act
+ * as — are omitted. {@link isSwitchTargetAccount} is the rule; see the filter
+ * below.
  */
 export declare function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput): SwitchableAccount[];
 /**
@@ -142,7 +173,10 @@ export declare function projectSwitchableAccounts(input: ProjectSwitchableAccoun
  * document, but including their ids lets the caller pass one id set and lets the
  * projection prefer freshly-fetched profiles uniformly.
  *
- * Applies the SAME act-as filter as {@link projectSwitchableAccounts} to graph
- * nodes, so this never fetches a profile for a row the projection will drop.
+ * Applies the SAME {@link isSwitchTargetAccount} filter as
+ * {@link projectSwitchableAccounts} to graph nodes, so this never fetches a
+ * profile for a row the projection will drop — and, just as importantly, never
+ * SKIPS one the projection will keep, which would leave that row unrendered
+ * until some later fetch happened to resolve it.
  */
 export declare function switchableAccountIds(state: DeviceSessionState | null, graph: AccountNode[]): string[];

package/dist/types/utils/accountCacheSweep.d.ts

@@ -0,0 +1,75 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that serve the ACCOUNT FOREST
+ * — the caller's accessible accounts, as lists and as individual detail rows —
+ * and the one sweep that clears them.
+ *
+ * WHY THIS IS NOT A METHOD ON THE ACCOUNTS MIXIN
+ * ---------------------------------------------
+ * `AccountNode.account` is a whole `User`, so a forest read embeds the very
+ * profile the identity reads serve. That makes an IDENTITY write a writer of
+ * these keys too: `updateProfile` edits the caller's own personal account,
+ * which is a row in `GET /accounts` and is its own `GET /accounts/<id>`. Leave
+ * those cached and the account switcher keeps drawing the pre-edit name and
+ * picture for the full TTL, against a perfectly healthy server.
+ *
+ * The mixins compose into one class at runtime but are typed one at a time, so
+ * the user mixin cannot call a method the accounts mixin owns. The key list
+ * therefore lives here, once, and every writer calls {@link
+ * evictOxyAccountForestCache} — exactly like the identity key list in
+ * `identityCacheSweep`, which the accounts mixin already calls for the
+ * mirror-image case (an account write staling the identity reads). The
+ * alternative — a second hand-written copy of these keys in the other mixin —
+ * is the drift that shipped the two stale-profile bugs `identityCacheSweep`
+ * documents.
+ *
+ * WHY THE LIST NEEDS A PREFIX AND THE DETAIL DOES NOT
+ * --------------------------------------------------
+ * `listAccounts({tree?})` keys the flat list as `GET:/accounts` and every
+ * option variant as `GET:/accounts?<query>` (the query string is part of the
+ * URL, hence of the key), and a writer cannot enumerate which variants a caller
+ * has read. The detail key, by contrast, is derivable from the account id the
+ * writer already holds.
+ *
+ * The `GET:/accounts?` prefix matches ONLY the query-string list variants —
+ * never `GET:/accounts/<id>` or its `…/members`, `…/credentials`, `…/children`
+ * sub-resources, which are the accounts mixin's own business and stay there.
+ */
+import type { OxyIdentityCacheEvictor } from './identityCacheSweep';
+/**
+ * The cache-eviction surface of an `OxyServices` instance. Reused from
+ * `identityCacheSweep` rather than re-declared: it is the SDK's one published
+ * name for these two methods, and a second identical interface would be one
+ * more shape to keep in step.
+ */
+export type OxyAccountCacheEvictor = OxyIdentityCacheEvictor;
+/** The cache key `listAccounts()` reads under with no options. */
+export declare const OXY_ACCOUNT_LIST_CACHE_KEY = "GET:/accounts";
+/**
+ * The prefix covering every option-carrying `listAccounts(opts)` variant
+ * (`?tree=true`, …), none of which a writer can enumerate.
+ */
+export declare const OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX = "GET:/accounts?";
+/**
+ * Prefix covering every per-account sub-resource cache key
+ * (`GET:/accounts/<id>`, `…/members`, `…/credentials`, `…/children`). A
+ * membership mutation on an ancestor must sweep ALL of these, not only the
+ * account named in the path: descendant member rosters embed inherited rows
+ * resolved from that ancestor, and the writer cannot enumerate which descendant
+ * ids a caller has already read. The trailing slash deliberately excludes the
+ * forest list keys (`GET:/accounts`, `GET:/accounts?…`) documented above.
+ */
+export declare const OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX = "GET:/accounts/";
+/**
+ * Build the exact cache key `getAccount(accountId)` reads under.
+ */
+export declare function oxyAccountDetailCacheKey(accountId: string): string;
+/**
+ * Sweep an `OxyServices` GET response cache of the account forest.
+ *
+ * @param oxy       - Anything exposing the SDK's two eviction methods.
+ * @param accountId - The account whose detail row to drop as well. Optional: a
+ *                    writer that changed the SHAPE of the forest rather than one
+ *                    account in it (create, archive, ownership transfer) has no
+ *                    detail row to name, and clears only the lists.
+ */
+export declare function evictOxyAccountForestCache(oxy: OxyAccountCacheEvictor, accountId?: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "19.0.0",
+  "version": "19.1.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,7 +115,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.23.0",
+    "@oxyhq/contracts": "^0.24.0",
     "@oxyhq/protocol": "^0.1.6",
     "@scure/bip39": "^1.6.0",
     "@types/elliptic": "^6.4.18",

package/src/i18n/locales/en-US.json

@@ -1839,6 +1839,7 @@
       "title": "Members",
       "subtitle": "People with access to this account.",
       "empty": "No members yet.",
+      "inherited": "Inherited",
       "actions": {
         "remove": "Remove member",
         "transfer": "Transfer ownership"

package/src/i18n/locales/es-ES.json

@@ -1839,6 +1839,7 @@
       "title": "Miembros",
       "subtitle": "Personas con acceso a esta cuenta.",
       "empty": "Aún no hay miembros.",
+      "inherited": "Heredado",
       "actions": {
         "remove": "Eliminar miembro",
         "transfer": "Transferir propiedad"

package/src/index.ts

@@ -647,7 +647,14 @@ export {
 // chooser: device sign-ins ∪ account graph, deduped by accountId). Pure +
 // I/O-free — the caller hydrates profiles via `getUsersByIds`. Shared by
 // `@oxyhq/services` and auth.oxy.so so the list can't diverge.
-export {
+// `isSwitchTargetAccount` is the switcher's own question ("can I become this
+// account?"), exported so a surface that renders `AccountNode`s rather than the
+// projection — the Console's workspace switcher, the accounts app's
+// managed-accounts rows — asks the SAME question instead of testing a kind
+// literal. It is NOT `isActAsEligibleKind`: that one is false for `personal`
+// too, so gating a switcher on it alone empties the list.
+export {
+    isSwitchTargetAccount,
     projectSwitchableAccounts,
     switchableAccountIds,
 } from './session/accountProjection';