@oxyhq/core 18.0.0 → 19.0.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';

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.
@@ -168,8 +168,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 +196,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 {
@@ -560,6 +580,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.
          */

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

@@ -254,13 +254,15 @@ 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`). 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.
          *
          * TanStack Query handles offline queuing automatically.
          */

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;

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

@@ -0,0 +1,80 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that can carry a single
+ * account's identity, and the one sweep that clears them.
+ *
+ * WHY THIS IS ONE LIST
+ * --------------------
+ * An Oxy account is readable under SEVERAL cache keys, and a write that only
+ * busts the key it happens to know about leaves every other one serving the
+ * pre-write snapshot for up to its TTL — from the caller's OWN in-memory cache,
+ * with a perfectly healthy server. That failure has already shipped twice with
+ * two different sets of keys:
+ *
+ *   - `updateAccount` busted `GET:/accounts/<id>` and the account lists, but a
+ *     profile screen reads `GET:/profiles/username/<name>` and
+ *     `GET:/users/<id>`, so a channel's new picture stayed invisible for the
+ *     full 5-minute profile TTL.
+ *   - `updateProfile` busted four of the six keys below, missing
+ *     `GET:/auth/lookup/` (the login-flow avatar/display-name lookup) and
+ *     `GET:/profiles/resolve` (handle resolution) — two independently-drifted
+ *     copies of a list that has to agree.
+ *
+ * So the list lives here, once, and every writer calls
+ * {@link evictOxyIdentityCache}. Adding a new identity read means adding its key
+ * HERE and every writer inherits it.
+ *
+ * WHERE THE LINE IS DRAWN
+ * -----------------------
+ * These are the SINGLE-PROFILE reads — the account is the subject of the
+ * response and is addressable by id, handle, or session. Reads that merely
+ * CONTAIN an account among many (`GET:/profiles/search`,
+ * `GET:/users/<other>/followers`, `GET:/profiles/<other>/similar`) are
+ * deliberately NOT swept: an account cannot be located in them without the very
+ * lookup being invalidated, so sweeping them means sweeping the whole namespace
+ * on every identity change — a real cost on a backend consuming the
+ * cross-service invalidation signal, for a surface where a stale thumbnail
+ * expires on its own in ~2 minutes.
+ *
+ * WHY PREFIXES RATHER THAN EXACT KEYS
+ * -----------------------------------
+ * Only the by-id key can be built from a user id. The handle-keyed and
+ * session-keyed entries cannot — deriving a handle from an id needs the lookup
+ * we are invalidating, and the SDK never tracks active session ids centrally.
+ * Prefix sweeping is also what makes a USERNAME CHANGE correct: the entry under
+ * the OLD handle is unreachable by construction (nothing in the write response
+ * carries it), and a sweep targeted at the new handle alone would leave the old
+ * one serving the pre-rename profile until its TTL. Over-eviction costs a
+ * refetch; under-eviction serves wrong data.
+ *
+ * Platform-neutral by construction (no imports, no `OxyServices` reference) so
+ * the client mixins and the Node-only `@oxyhq/core/server` invalidation
+ * subscriber can share it without either pulling in the other.
+ */
+/**
+ * The cache-eviction surface of an `OxyServices` instance. Declared
+ * structurally so this module stays free of any client import.
+ */
+export interface OxyIdentityCacheEvictor {
+    clearCacheEntry(key: string): void;
+    clearCacheByPrefix(prefix: string): number;
+}
+/**
+ * Cache-key PREFIXES under which an account's identity can be served, for the
+ * reads whose key cannot be derived from a user id. Swept wholesale.
+ */
+export declare const OXY_IDENTITY_CACHE_PREFIXES: readonly string[];
+/**
+ * Build the exact cache key `getUserById` reads under. The only identity key
+ * derivable from a user id, so the only one that does not need a prefix sweep.
+ */
+export declare function oxyUserByIdCacheKey(userId: string): string;
+/**
+ * Sweep an `OxyServices` GET response cache of everything that could carry the
+ * given account's identity.
+ *
+ * @param oxy    - Anything exposing the SDK's two eviction methods.
+ * @param userId - The account whose by-id entry to drop. Optional: a caller
+ *                 that does not know the id still clears every handle-, session-
+ *                 and self-keyed entry, which is the majority of the surface.
+ */
+export declare function evictOxyIdentityCache(oxy: OxyIdentityCacheEvictor, userId?: string): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "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.22.0",
+    "@oxyhq/contracts": "^0.23.0",
     "@oxyhq/protocol": "^0.1.6",
     "@scure/bip39": "^1.6.0",
     "@types/elliptic": "^6.4.18",

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

@@ -1748,11 +1748,53 @@
         "description": "A programmatic account with service credentials"
       }
     },
-    "organizationCategory": {
+    "accountCategory": {
+      "news": "News",
+      "politics": "Politics & policy",
+      "business": "Business",
+      "startup": "Startups & entrepreneurship",
+      "finance": "Finance & investing",
+      "crypto": "Crypto & web3",
+      "marketplace": "Marketplace & classifieds",
+      "retail": "Retail & ecommerce",
+      "real_estate": "Real estate",
       "agency": "Real estate agency",
+      "landlord": "Landlord & property management",
       "cooperative": "Housing cooperative",
-      "landlord": "Landlord / property manager",
-      "other": "Other organization"
+      "architecture": "Architecture & construction",
+      "technology": "Technology",
+      "software": "Software & development",
+      "ai": "AI & machine learning",
+      "security": "Security & privacy",
+      "automation": "Automation & tools",
+      "science": "Science & research",
+      "education": "Education & training",
+      "books": "Books & writing",
+      "health": "Health & medicine",
+      "fitness": "Fitness & wellbeing",
+      "sports": "Sports",
+      "gaming": "Gaming & esports",
+      "music": "Music",
+      "film": "Film & TV",
+      "podcast": "Podcasts & audio",
+      "art": "Art & design",
+      "photography": "Photography",
+      "comedy": "Comedy",
+      "food": "Food & drink",
+      "travel": "Travel & places",
+      "fashion": "Fashion & beauty",
+      "home_garden": "Home & garden",
+      "diy": "DIY & making",
+      "automotive": "Cars & motoring",
+      "animals": "Animals & pets",
+      "family": "Family & parenting",
+      "nonprofit": "Non-profit & charity",
+      "government": "Government & public sector",
+      "community": "Local community",
+      "activism": "Activism & advocacy",
+      "environment": "Environment & sustainability",
+      "religion": "Religion & spirituality",
+      "other": "Other"
     },
     "create": {
       "title": "Create account",
@@ -1772,8 +1814,9 @@
         "invalidChars": "Only letters, numbers, hyphens, and underscores",
         "checkFailed": "Could not check availability"
       },
-      "organizationCategory": {
-        "label": "Organization type"
+      "accountCategory": {
+        "label": "Categories",
+        "hint": "Pick up to {{max}}. The first one is your main category."
       },
       "toasts": {
         "success": "Account created",

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

@@ -1748,11 +1748,53 @@
         "description": "Una cuenta programática con credenciales de servicio"
       }
     },
-    "organizationCategory": {
+    "accountCategory": {
+      "news": "Noticias",
+      "politics": "Política",
+      "business": "Negocios",
+      "startup": "Startups y emprendimiento",
+      "finance": "Finanzas e inversión",
+      "crypto": "Cripto y web3",
+      "marketplace": "Marketplace y anuncios",
+      "retail": "Comercio y ecommerce",
+      "real_estate": "Inmobiliaria",
       "agency": "Agencia inmobiliaria",
+      "landlord": "Casero y gestión de fincas",
       "cooperative": "Cooperativa de vivienda",
-      "landlord": "Propietario / administrador de fincas",
-      "other": "Otra organización"
+      "architecture": "Arquitectura y construcción",
+      "technology": "Tecnología",
+      "software": "Software y desarrollo",
+      "ai": "IA y aprendizaje automático",
+      "security": "Seguridad y privacidad",
+      "automation": "Automatización y herramientas",
+      "science": "Ciencia e investigación",
+      "education": "Educación y formación",
+      "books": "Libros y escritura",
+      "health": "Salud y medicina",
+      "fitness": "Deporte y bienestar",
+      "sports": "Deportes",
+      "gaming": "Videojuegos y esports",
+      "music": "Música",
+      "film": "Cine y TV",
+      "podcast": "Pódcast y audio",
+      "art": "Arte y diseño",
+      "photography": "Fotografía",
+      "comedy": "Comedia",
+      "food": "Comida y bebida",
+      "travel": "Viajes y lugares",
+      "fashion": "Moda y belleza",
+      "home_garden": "Hogar y jardín",
+      "diy": "Bricolaje y manualidades",
+      "automotive": "Coches y motor",
+      "animals": "Animales y mascotas",
+      "family": "Familia y crianza",
+      "nonprofit": "ONG y benéficas",
+      "government": "Gobierno y sector público",
+      "community": "Comunidad local",
+      "activism": "Activismo y defensa",
+      "environment": "Medio ambiente y sostenibilidad",
+      "religion": "Religión y espiritualidad",
+      "other": "Otra"
     },
     "create": {
       "title": "Crear cuenta",
@@ -1772,8 +1814,9 @@
         "invalidChars": "Solo letras, números, guiones y guiones bajos",
         "checkFailed": "No se pudo comprobar la disponibilidad"
       },
-      "organizationCategory": {
-        "label": "Tipo de organización"
+      "accountCategory": {
+        "label": "Categorías",
+        "hint": "Elige hasta {{max}}. La primera es tu categoría principal."
       },
       "toasts": {
         "success": "Cuenta creada",

package/src/index.ts

@@ -122,7 +122,7 @@ export type {
 // ---------------------------------------------------------------------------
 export type {
     AccountKind,
-    OrganizationCategory,
+    AccountCategoryId,
     AccountRelationship,
     AccountRole,
     AccountMemberStatus,
@@ -167,7 +167,13 @@ export type {
     ApplicationUsageStats,
 } from './mixins/OxyServices.accounts';
 
-export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
+export {
+    ACCOUNT_CATEGORY_IDS,
+    MAX_ACCOUNT_CATEGORIES,
+    SELECTABLE_ACCOUNT_CATEGORY_IDS,
+    isSelectableAccountCategoryId,
+    kindAcceptsAccountCategories,
+} from './mixins/OxyServices.accounts';
 
 // ---------------------------------------------------------------------------
 // Reputation (Oxy Trust: ledger, balances, disputes, rules, influence).

package/src/mixins/OxyServices.accounts.ts

@@ -33,10 +33,11 @@
  * 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';
 import { normalizeUserIdentity } from '../utils/userIdentity';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
 import { CACHE_TIMES } from './mixinHelpers';
 
 // ---------------------------------------------------------------------------
@@ -52,8 +53,16 @@ import { CACHE_TIMES } from './mixinHelpers';
  *
  * 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:
@@ -179,8 +188,17 @@ export interface CreateAccountInput {
   name?: { first?: string; last?: string; displayName?: string };
   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`. */
@@ -195,8 +213,19 @@ export interface UpdateAccountInput {
   name?: { first?: string; last?: string; displayName?: string };
   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`). */
@@ -736,6 +765,18 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
     /**
      * 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.
      */
@@ -754,6 +795,16 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
         // data) so neither serves the pre-update snapshot.
         this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
         this._invalidateAccountLists();
+        // The parent's children list embeds this account's profile and is keyed
+        // by the PARENT id, so it is reachable only from the response node.
+        const parentAccountId = res.account?.parentAccountId;
+        if (parentAccountId) {
+          this.clearCacheEntry(
+            `GET:/accounts/${encodeURIComponent(parentAccountId)}/children`,
+          );
+        }
+        // Every identity read of this account, whichever key it lands under.
+        evictOxyIdentityCache(this, accountId);
         return res.account;
       } catch (error) {
         throw this.handleError(error);

package/src/mixins/OxyServices.user.ts

@@ -28,6 +28,7 @@ import {
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
 import { logger } from '../logger';
 import { extractErrorStatus } from '../utils/errorUtils';
 
@@ -534,13 +535,15 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     /**
      * 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`). 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.
      *
      * TanStack Query handles offline queuing automatically.
      */
@@ -550,15 +553,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false }),
         );
 
-        // Bust every cached representation of the current user. We use a
-        // prefix sweep rather than an enumeration because the SDK never
-        // tracks the set of active session IDs centrally.
-        this.clearCacheByPrefix('GET:/session/user/');
-        this.clearCacheByPrefix('GET:/users/me');
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        if (result?.id) {
-          this.clearCacheEntry(`GET:/users/${result.id}`);
-        }
+        evictOxyIdentityCache(this, result?.id);
 
         return result;
       } catch (error) {
@@ -615,10 +610,9 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         const result = await this.makeRequest<PrivacySettings>('PATCH', `/privacy/${id}/privacy`, settings, {
           cache: false,
         });
-        this.clearCacheByPrefix('GET:/session/user/');
-        this.clearCacheByPrefix('GET:/users/me');
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        this.clearCacheEntry(`GET:/users/${id}`);
+        // Privacy settings ride the user DTO, so every identity read goes stale
+        // too — same key list as any other profile write.
+        evictOxyIdentityCache(this, id);
         this.clearCacheEntry(`GET:/privacy/${id}/privacy`);
         return result;
       } catch (error) {