@oxyhq/core 19.0.0 → 19.1.0

package/dist/cjs/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/dist/cjs/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/dist/cjs/i18n/locales/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/dist/cjs/i18n/locales/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/dist/cjs/index.js

@@ -21,8 +21,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hkdfSha256 = exports.RecoveryPhraseService = exports.SignatureService = exports.updateIdentityMarker = exports.readIdentityMarker = exports.IdentityUnavailableError = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.verifyPublicCardAttestation = exports.parseAttestPayload = exports.parseIdPayload = exports.buildUserDid = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_CATEGORY_IDS = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.OxyAppDataIdentifierError = exports.commonsDeliveryPlatform = exports.pushTargetsFromDelivery = exports.selectCommonsDelivery = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.ServiceCredentialMismatchError = exports.oxyClient = exports.OXY_CLOUD_URL = exports.ServiceAssetMetadataError = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.AssetUrlResolutionError = exports.OxyServices = void 0;
 exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = void 0;
 exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.isValidDisplayName = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = exports.DISPLAY_NAME_INVALID_MESSAGE = exports.MAX_DISPLAY_NAME_LENGTH = exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.buildQueryParams = exports.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = void 0;
-exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.switchableAccountIds = exports.projectSwitchableAccounts = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.runColdBoot = exports.isOxyRpOrigin = exports.CENTRAL_IDP_APEX = exports.registrableApex = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = void 0;
-exports.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AccountNotOnDeviceError = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = void 0;
+exports.createWebIdentityPinStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.switchableAccountIds = exports.projectSwitchableAccounts = exports.isSwitchTargetAccount = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.runColdBoot = exports.isOxyRpOrigin = exports.CENTRAL_IDP_APEX = exports.registrableApex = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = void 0;
+exports.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AccountNotOnDeviceError = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -370,7 +370,14 @@ Object.defineProperty(exports, "accountIdsOf", { enumerable: true, get: function
 // 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.
+// `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.
 var accountProjection_1 = require("./session/accountProjection");
+Object.defineProperty(exports, "isSwitchTargetAccount", { enumerable: true, get: function () { return accountProjection_1.isSwitchTargetAccount; } });
 Object.defineProperty(exports, "projectSwitchableAccounts", { enumerable: true, get: function () { return accountProjection_1.projectSwitchableAccounts; } });
 Object.defineProperty(exports, "switchableAccountIds", { enumerable: true, get: function () { return accountProjection_1.switchableAccountIds; } });
 // Headless controller for the unified account dialog. Framework-agnostic

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

@@ -4,6 +4,7 @@ exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = e
 exports.OxyServicesAccountsMixin = OxyServicesAccountsMixin;
 const userIdentity_1 = require("../utils/userIdentity");
 const identityCacheSweep_1 = require("../utils/identityCacheSweep");
+const accountCacheSweep_1 = require("../utils/accountCacheSweep");
 const mixinHelpers_1 = require("./mixinHelpers");
 var contracts_1 = require("@oxyhq/contracts");
 Object.defineProperty(exports, "ACCOUNT_CATEGORY_IDS", { enumerable: true, get: function () { return contracts_1.ACCOUNT_CATEGORY_IDS; } });
@@ -124,7 +125,7 @@ function OxyServicesAccountsMixin(Base) {
                 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.
-                this._invalidateAccountLists();
+                (0, accountCacheSweep_1.evictOxyAccountForestCache)(this);
                 return res.account;
             }
             catch (error) {
@@ -190,8 +191,7 @@ function OxyServicesAccountsMixin(Base) {
                 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.
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
-                this._invalidateAccountLists();
+                (0, accountCacheSweep_1.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;
@@ -216,10 +216,9 @@ function OxyServicesAccountsMixin(Base) {
             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)}`);
                 this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/members`);
                 this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-                this._invalidateAccountLists();
+                (0, accountCacheSweep_1.evictOxyAccountForestCache)(this, accountId);
                 return result;
             }
             catch (error) {
@@ -243,7 +242,27 @@ function OxyServicesAccountsMixin(Base) {
         // Account members
         // =========================================================================
         /**
-         * 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`.
          */
         async listAccountMembers(accountId) {
@@ -314,7 +333,7 @@ function OxyServicesAccountsMixin(Base) {
                 // Ownership change alters roles in the member list AND the detail, and
                 // can change which accounts the caller "owns" in the list view.
                 this._invalidateAccountMembership(accountId);
-                this._invalidateAccountLists();
+                (0, accountCacheSweep_1.evictOxyAccountForestCache)(this);
                 return result;
             }
             catch (error) {
@@ -558,35 +577,29 @@ function OxyServicesAccountsMixin(Base) {
         // Cache-invalidation helpers
         // =========================================================================
         /**
-         * Bust every cached account list. `listAccounts({tree?})` keys the flat list
-         * as `GET:/accounts` and the tree variant as `GET:/accounts?tree=true` (the
-         * query string is part of the URL path). A change to the accessible forest
-         * (create/archive/ownership transfer) invalidates both, so we clear the
-         * unscoped entry plus every `?`-query variant via a prefix sweep. The prefix
-         * `GET:/accounts?` matches only the query-string list variants, never the
-         * `GET:/accounts/<id>…` detail/sub-resource keys.
+         * 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() {
-            this.clearCacheEntry('GET:/accounts');
-            this.clearCacheByPrefix('GET:/accounts?');
-        }
-        /**
-         * Bust the cached member list and detail for an account after a membership
-         * mutation. The member list (`listAccountMembers`) and the detail
-         * (`getAccount`, which can embed the caller's membership) both go stale when
-         * the member set or a member's role changes.
          *
-         * Internal helper (leading underscore); see `_invalidateAccountLists` for why
-         * this is public rather than `private`.
+         * 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(`GET:/accounts/${encodeURIComponent(accountId)}`);
+            this.clearCacheEntry((0, accountCacheSweep_1.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(accountCacheSweep_1.OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX);
         }
         /**
          * Bust every cached application list. `listAccountApps(accountId)` keys each
@@ -597,8 +610,8 @@ function OxyServicesAccountsMixin(Base) {
          * 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() {
             this.clearCacheEntry('GET:/applications');

package/dist/cjs/mixins/OxyServices.followGraph.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyServicesFollowGraphMixin = OxyServicesFollowGraphMixin;
+const apiUtils_1 = require("../utils/apiUtils");
+function OxyServicesFollowGraphMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * 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.
+         */
+        async followTarget(targetId, options) {
+            try {
+                return await this.makeRequest('PUT', `/v2/follows/${encodeURIComponent(targetId)}`, options?.expiresIn !== undefined ? { expiresIn: options.expiresIn } : {}, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async unfollowTarget(relationshipId) {
+            try {
+                return await this.makeRequest('DELETE', `/v2/follows/${encodeURIComponent(relationshipId)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async getFollowTargetStatus(targetId) {
+            try {
+                return await this.makeRequest('GET', `/v2/follows/${encodeURIComponent(targetId)}/status`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async setFollowApplicationMode(relationshipId, mode, applicationId) {
+            try {
+                return await this.makeRequest('PUT', `/v2/follows/${encodeURIComponent(relationshipId)}/context`, { mode, ...(applicationId ? { applicationId } : {}) }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async restoreFollowInheritance(relationshipId, applicationId) {
+            try {
+                const path = (0, apiUtils_1.buildUrl)(`/v2/follows/${encodeURIComponent(relationshipId)}/context`, applicationId ? { applicationId } : {});
+                return await this.makeRequest('DELETE', path, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async ensureFollowTarget(input) {
+            try {
+                return await this.makeRequest('POST', '/v2/follow-targets', input, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async claimFollowNamespace(namespace) {
+            try {
+                return await this.makeRequest('POST', '/v2/follow-targets/namespaces', { namespace }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async registerFollowKind(input) {
+            try {
+                return await this.makeRequest('POST', '/v2/follow-targets/kinds', input, {
+                    cache: false,
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * 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.
+         */
+        async listFollows(params) {
+            try {
+                const path = (0, apiUtils_1.buildUrl)('/v2/me/follows', {
+                    ...(params?.kind ? { kind: params.kind } : {}),
+                    ...(params?.cursor ? { cursor: params.cursor } : {}),
+                    ...(params?.limit ? { limit: params.limit } : {}),
+                });
+                return await this.makeRequest('GET', path, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/cjs/mixins/OxyServices.user.js

@@ -7,6 +7,7 @@ const keyManager_1 = require("../crypto/keyManager");
 const signatureService_1 = require("../crypto/signatureService");
 const userIdentity_1 = require("../utils/userIdentity");
 const identityCacheSweep_1 = require("../utils/identityCacheSweep");
+const accountCacheSweep_1 = require("../utils/accountCacheSweep");
 const logger_1 = require("../logger");
 const errorUtils_1 = require("../utils/errorUtils");
 /**
@@ -353,10 +354,11 @@ function OxyServicesUserMixin(Base) {
          * 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.
          */
@@ -364,6 +366,7 @@ function OxyServicesUserMixin(Base) {
             try {
                 const result = (0, userIdentity_1.normalizeUserIdentity)(await this.makeRequest('PUT', '/users/me', updates, { cache: false }));
                 (0, identityCacheSweep_1.evictOxyIdentityCache)(this, result?.id);
+                (0, accountCacheSweep_1.evictOxyAccountForestCache)(this, result?.id);
                 return result;
             }
             catch (error) {

package/dist/cjs/mixins/index.js

@@ -33,6 +33,7 @@ const OxyServices_appData_1 = require("./OxyServices.appData");
 const OxyServices_civic_1 = require("./OxyServices.civic");
 const OxyServices_nodes_1 = require("./OxyServices.nodes");
 const OxyServices_links_1 = require("./OxyServices.links");
+const OxyServices_followGraph_1 = require("./OxyServices.followGraph");
 const OxyServices_deviceBoot_1 = require("./OxyServices.deviceBoot");
 const OxyServices_deviceTransfer_1 = require("./OxyServices.deviceTransfer");
 /**
@@ -89,6 +90,9 @@ const MIXIN_PIPELINE = [
     // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
     // so apps stop scraping link metadata locally.
     OxyServices_links_1.OxyServicesLinksMixin,
+    // The user-owned follow graph (#809). One relationship per user and target,
+    // shared across applications, with per-application context on top.
+    OxyServices_followGraph_1.OxyServicesFollowGraphMixin,
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServices_deviceBoot_1.OxyServicesDeviceBootMixin,

package/dist/cjs/session/accountProjection.js

@@ -18,11 +18,41 @@
  * atomic, so no cross-call current-row reconciliation is needed).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSwitchTargetAccount = isSwitchTargetAccount;
 exports.projectSwitchableAccounts = projectSwitchableAccounts;
 exports.switchableAccountIds = switchableAccountIds;
 const contracts_1 = require("@oxyhq/contracts");
 const accountUtils_1 = require("../utils/accountUtils");
 const userHandle_1 = require("../utils/userHandle");
+/**
+ * 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.
+ */
+function isSwitchTargetAccount(node) {
+    return node.relationship === 'self' || (0, contracts_1.isActAsEligibleKind)(node.kind);
+}
 /**
  * Pure union of device sign-ins and account-graph nodes into the flat
  * {@link SwitchableAccount}[] every switcher renders.
@@ -32,8 +62,9 @@ const userHandle_1 = require("../utils/userHandle");
  * 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.
  */
 function projectSwitchableAccounts(input) {
     const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
@@ -108,10 +139,12 @@ function projectSwitchableAccounts(input) {
         // construction": the graph contributes accounts that have no device session
         // and no credentials at all, which is exactly how an org first becomes
         // switchable. So a kind that must never be switched into has to be filtered
-        // HERE, and `isActAsEligibleKind` is the same predicate the server enforces
-        // on `POST /accounts/:id/switch` — offering a row the server would 403 is a
-        // dead button.
-        if (!(0, contracts_1.isActAsEligibleKind)(node.kind)) {
+        // HERE — offering a row the server would 403 is a dead button.
+        //
+        // An account already on the device skipped this check via the branch above,
+        // and correctly: whatever its kind, the caller is signed into it, so
+        // switching is a local activation that asks the server for nothing.
+        if (!isSwitchTargetAccount(node)) {
             continue;
         }
         remember(toRow(node.account, {
@@ -133,8 +166,11 @@ function projectSwitchableAccounts(input) {
  * 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.
  */
 function switchableAccountIds(state, graph) {
     const ids = new Set();
@@ -144,7 +180,7 @@ function switchableAccountIds(state, graph) {
         }
     }
     for (const node of graph) {
-        if (node.accountId && (0, contracts_1.isActAsEligibleKind)(node.kind)) {
+        if (node.accountId && isSwitchTargetAccount(node)) {
             ids.add(node.accountId);
         }
     }

package/dist/cjs/utils/accountCacheSweep.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX = exports.OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX = exports.OXY_ACCOUNT_LIST_CACHE_KEY = void 0;
+exports.oxyAccountDetailCacheKey = oxyAccountDetailCacheKey;
+exports.evictOxyAccountForestCache = evictOxyAccountForestCache;
+/** The cache key `listAccounts()` reads under with no options. */
+exports.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.
+ */
+exports.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.
+ */
+exports.OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX = 'GET:/accounts/';
+/**
+ * Build the exact cache key `getAccount(accountId)` reads under.
+ */
+function oxyAccountDetailCacheKey(accountId) {
+    return `GET:/accounts/${encodeURIComponent(accountId)}`;
+}
+/**
+ * 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.
+ */
+function evictOxyAccountForestCache(oxy, accountId) {
+    oxy.clearCacheEntry(exports.OXY_ACCOUNT_LIST_CACHE_KEY);
+    oxy.clearCacheByPrefix(exports.OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX);
+    if (accountId) {
+        oxy.clearCacheEntry(oxyAccountDetailCacheKey(accountId));
+    }
+}