@oxyhq/core 18.0.0 → 19.1.0

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/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.1.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.24.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",
@@ -1796,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

@@ -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",
@@ -1796,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

@@ -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).
@@ -641,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.
+// `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';