@oxyhq/core 19.1.2 → 20.0.0

package/src/i18n/__tests__/reputationCategoryLabels.test.ts

@@ -0,0 +1,56 @@
+import { REPUTATION_CATEGORIES } from '@oxyhq/contracts';
+import {
+  EN_REPUTATION_CATEGORY_LABELS,
+  reputationCategoryLabel,
+} from '../reputationCategoryLabels';
+
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('reputationCategoryLabel', () => {
+  it('covers the whole vocabulary', () => {
+    expect(REPUTATION_CATEGORIES.length).toBeGreaterThanOrEqual(7);
+    expect(Object.keys(EN_REPUTATION_CATEGORY_LABELS)).toHaveLength(
+      REPUTATION_CATEGORIES.length,
+    );
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every category in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const id of REPUTATION_CATEGORIES) {
+        const label = reputationCategoryLabel(locale, id);
+        expect(label).not.toBe('');
+        expect(label).not.toBe(`trust.rules.categories.${id}`);
+      }
+    },
+  );
+
+  it('falls back to English for a language with no category translations', () => {
+    expect(reputationCategoryLabel('de-DE', 'physical')).toBe(
+      EN_REPUTATION_CATEGORY_LABELS.physical,
+    );
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(reputationCategoryLabel('es-MX', 'content')).toBe(
+      reputationCategoryLabel('es-ES', 'content'),
+    );
+    expect(reputationCategoryLabel('es-MX', 'content')).not.toBe(
+      EN_REPUTATION_CATEGORY_LABELS.content,
+    );
+  });
+});

package/src/i18n/__tests__/trustTierLabels.test.ts

@@ -0,0 +1,47 @@
+import { TRUST_TIERS } from '@oxyhq/contracts';
+import { EN_TRUST_TIER_LABELS, trustTierLabel } from '../trustTierLabels';
+
+const SHIPPED_LOCALES = [
+  'en-US',
+  'es-ES',
+  'ca-ES',
+  'fr-FR',
+  'de-DE',
+  'it-IT',
+  'pt-PT',
+  'ja-JP',
+  'ko-KR',
+  'zh-CN',
+  'ar-SA',
+] as const;
+const REGION_VARIANT = 'es-MX';
+const UNSHIPPED_LOCALE = 'nl-NL';
+
+describe('trustTierLabel', () => {
+  it('covers the whole vocabulary', () => {
+    expect(TRUST_TIERS.length).toBe(5);
+    expect(Object.keys(EN_TRUST_TIER_LABELS)).toHaveLength(TRUST_TIERS.length);
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every tier in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const tier of TRUST_TIERS) {
+        const label = trustTierLabel(locale, tier);
+        expect(label).not.toBe('');
+        expect(label).not.toBe(`trust.tiers.${tier}`);
+      }
+    },
+  );
+
+  it('falls back to English for a language with no tier translations', () => {
+    expect(trustTierLabel('de-DE', 'high_trust')).toBe(
+      EN_TRUST_TIER_LABELS.high_trust,
+    );
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(trustTierLabel('es-MX', 'verified')).toBe(trustTierLabel('es-ES', 'verified'));
+    expect(trustTierLabel('es-MX', 'verified')).not.toBe(EN_TRUST_TIER_LABELS.verified);
+  });
+});

package/src/i18n/accountCategoryLabels.ts

@@ -0,0 +1,44 @@
+import type { AccountCategoryId } from '@oxyhq/contracts';
+import enUS from './locales/en-US.json';
+import { translate } from './index';
+
+/**
+ * Every account category's English name, keyed by its stable id.
+ *
+ * **The annotation is the point.** The vocabulary lives in `@oxyhq/contracts`
+ * and the names live in `locales/en-US.json`, so they are two lists that must
+ * agree and nothing but a type can make them. Declaring the JSON node as a
+ * TOTAL `Record<AccountCategoryId, string>` turns "somebody added a category at
+ * Oxy and nobody wrote its English" into a `TS2741` naming the missing id, at
+ * build time, instead of a picker row that paints `accounts.accountCategory.<id>`
+ * at a user trying to choose one.
+ *
+ * That failure is not hypothetical. The screen previously wrote `t(key) || id`,
+ * whose author believed an unnamed id would degrade to its raw slug. It cannot:
+ * {@link translate} echoes the KEY when it resolves nothing, and a non-empty
+ * string is never falsy, so the `|| id` arm was unreachable and the output was
+ * the dotted key. A runtime fallback that cannot run is worse than none,
+ * because it reads as protection.
+ *
+ * Totality is over `ACCOUNT_CATEGORY_IDS`, which RETAINS withdrawn ids, so an
+ * account still carrying a retired category keeps rendering its name while no
+ * picker offers it again. Retired and unknown are different cases: only an id
+ * outside the union is unnameable, which is why this is keyed by
+ * `AccountCategoryId` and not by `string`.
+ */
+/**
+ * Module-scoped, NOT re-exported from the package index: the annotation is the
+ * whole job, and it does that job without being public API. It carries no
+ * `Object.freeze` and no `Readonly<>` for the same reason — those existed only
+ * to make an exported reference safe from a consumer's stray write, and there
+ * is no such consumer. Exported from the MODULE so its own test can name it.
+ */
+export const EN_ACCOUNT_CATEGORY_LABELS: Record<AccountCategoryId, string> =
+  enUS.accounts.accountCategory;
+
+export function accountCategoryLabel(
+  locale: string | undefined,
+  id: AccountCategoryId,
+): string {
+  return translate(locale, `accounts.accountCategory.${id}`);
+}

package/src/i18n/accountRoleLabels.ts

@@ -0,0 +1,26 @@
+import type { AccountRole } from '../mixins/OxyServices.accounts';
+import enUS from './locales/en-US.json';
+import { translate } from './index';
+
+/**
+ * Every account member role's English name, keyed by its stable id.
+ *
+ * Totality is over the closed `AccountRole` union so a new role without an
+ * English label is a build error, not a members row that paints
+ * `accounts.roles.<role>.label`.
+ */
+export const EN_ACCOUNT_ROLE_LABELS: Record<AccountRole, string> = {
+  owner: enUS.accounts.roles.owner.label,
+  admin: enUS.accounts.roles.admin.label,
+  editor: enUS.accounts.roles.editor.label,
+  developer: enUS.accounts.roles.developer.label,
+  billing: enUS.accounts.roles.billing.label,
+  viewer: enUS.accounts.roles.viewer.label,
+};
+
+export function accountRoleLabel(
+  locale: string | undefined,
+  role: AccountRole,
+): string {
+  return translate(locale, `accounts.roles.${role}.label`);
+}

package/src/i18n/reputationCategoryLabels.ts

@@ -0,0 +1,20 @@
+import type { ReputationCategory } from '@oxyhq/contracts';
+import enUS from './locales/en-US.json';
+import { translate } from './index';
+
+/**
+ * Every reputation rule category's English name, keyed by its stable id.
+ *
+ * Totality is over `REPUTATION_CATEGORIES` from `@oxyhq/contracts` so a new
+ * category added server-side without an English label is a build error, not a
+ * Trust Rules section title that paints `trust.rules.categories.<id>`.
+ */
+export const EN_REPUTATION_CATEGORY_LABELS: Record<ReputationCategory, string> =
+  enUS.trust.rules.categories;
+
+export function reputationCategoryLabel(
+  locale: string | undefined,
+  id: ReputationCategory,
+): string {
+  return translate(locale, `trust.rules.categories.${id}`);
+}

package/src/i18n/trustTierLabels.ts

@@ -0,0 +1,18 @@
+import type { TrustTier } from '@oxyhq/contracts';
+import enUS from './locales/en-US.json';
+import { translate } from './index';
+
+/**
+ * Every trust tier's English name, keyed by its stable id.
+ *
+ * Totality is over `TRUST_TIERS` from `@oxyhq/contracts` so a new tier without
+ * an English label is a build error, not a chip that paints `trust.tiers.<id>`.
+ */
+export const EN_TRUST_TIER_LABELS: Record<TrustTier, string> = enUS.trust.tiers;
+
+export function trustTierLabel(
+  locale: string | undefined,
+  tier: TrustTier,
+): string {
+  return translate(locale, `trust.tiers.${tier}`);
+}

package/src/index.ts

@@ -453,6 +453,10 @@ export type { CircuitBreakerState, CircuitBreakerConfig } from './shared/utils/n
 // i18n
 // ---------------------------------------------------------------------------
 export { translate } from './i18n';
+export { accountCategoryLabel } from './i18n/accountCategoryLabels';
+export { accountRoleLabel } from './i18n/accountRoleLabels';
+export { reputationCategoryLabel } from './i18n/reputationCategoryLabels';
+export { trustTierLabel } from './i18n/trustTierLabels';
 
 // ---------------------------------------------------------------------------
 // API request / URL helpers
@@ -476,8 +480,11 @@ export {
     ErrorCodes,
     createApiError,
     handleHttpError,
+    isHttpRequestError,
+    parseHttpErrorBody,
     validateRequiredFields,
 } from './utils/errorUtils';
+export type { HttpRequestError, ParsedHttpErrorBody } from './utils/errorUtils';
 
 export { retryAsync } from './utils/asyncUtils';
 
@@ -647,14 +654,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.
+// `isSwitchTargetAccount` is the structural half ("is this kind switchable at
+// all?"); `canSwitchIntoAccount` adds the caller's `account:act_as` permission.
+// Both are exported so surfaces that render `AccountNode`s rather than the
+// projection — the Console workspace switcher, managed-accounts rows — ask the
+// SAME questions instead of testing a kind literal.
 export {
     isSwitchTargetAccount,
+    canSwitchIntoAccount,
     projectSwitchableAccounts,
     switchableAccountIds,
 } from './session/accountProjection';

package/src/mixins/OxyServices.followGraph.ts

@@ -210,6 +210,30 @@ export function OxyServicesFollowGraphMixin<T extends typeof OxyServicesBase>(Ba
       }
     }
 
+    /**
+     * Release a namespace the calling application holds, when nothing is
+     registered inside it yet.
+     *
+     * Idempotent when the namespace is already unowned (`released: false`).
+     * Exists because claims are first-come and registration runs on boot — a
+     * development build with the wrong client id can bind a name permanently
+     * unless the holder can give it back.
+     */
+    async releaseFollowNamespace(
+      namespace: string,
+    ): Promise<{ namespace: string; released: boolean }> {
+      try {
+        return await this.makeRequest(
+          'DELETE',
+          `/v2/follow-targets/namespaces/${encodeURIComponent(namespace)}`,
+          undefined,
+          { 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.

package/src/mixins/__tests__/followGraph.test.ts

@@ -105,6 +105,23 @@ describe('OxyServices.followGraph', () => {
       await oxy.followTarget('../../admin');
       expect(makeRequest.mock.calls[0][1]).toBe('/v2/follows/..%2F..%2Fadmin');
     });
+
+    it('claims a namespace with POST', async () => {
+      await oxy.claimFollowNamespace('mention');
+      expect(makeRequest.mock.calls[0].slice(0, 3)).toEqual([
+        'POST',
+        '/v2/follow-targets/namespaces',
+        { namespace: 'mention' },
+      ]);
+    });
+
+    it('releases a namespace with DELETE and encodes the segment', async () => {
+      await oxy.releaseFollowNamespace('mention.dev');
+      expect(makeRequest.mock.calls[0].slice(0, 2)).toEqual([
+        'DELETE',
+        '/v2/follow-targets/namespaces/mention.dev',
+      ]);
+    });
   });
 
   describe('caching', () => {
@@ -115,6 +132,8 @@ describe('OxyServices.followGraph', () => {
       await oxy.unfollowTarget('r');
       await oxy.setFollowApplicationMode('r', 'disabled');
       await oxy.restoreFollowInheritance('r');
+      await oxy.claimFollowNamespace('ns');
+      await oxy.releaseFollowNamespace('ns');
 
       // A status cached across a write is the "follow reverts after navigating
       // away and back" bug the legacy path had to fix with explicit

package/src/session/__tests__/accountProjection.test.ts

@@ -3,6 +3,7 @@ import { ACCOUNT_KINDS } from '@oxyhq/contracts';
 import type { User } from '../../models/interfaces';
 import type { AccountNode } from '../../mixins/OxyServices.accounts';
 import {
+  canSwitchIntoAccount,
   isSwitchTargetAccount,
   projectSwitchableAccounts,
   switchableAccountIds,
@@ -102,6 +103,71 @@ describe('isSwitchTargetAccount', () => {
   });
 });
 
+describe('canSwitchIntoAccount', () => {
+  it('admits self without membership permissions', () => {
+    expect(canSwitchIntoAccount({ kind: 'personal', relationship: 'self' })).toBe(true);
+  });
+
+  it('admits an owned switch target when membership is absent (owner baseline)', () => {
+    expect(canSwitchIntoAccount({ kind: 'organization', relationship: 'owner' })).toBe(true);
+  });
+
+  it('requires account:act_as for member relationships', () => {
+    expect(
+      canSwitchIntoAccount({
+        kind: 'organization',
+        relationship: 'member',
+        callerMembership: {
+          _id: 'm1',
+          accountId: 'org1',
+          memberUserId: 'u1',
+          role: 'billing',
+          status: 'active',
+          permissions: ['account:read', 'billing:manage'],
+          inherit: true,
+          source: 'direct',
+        },
+      }),
+    ).toBe(false);
+
+    expect(
+      canSwitchIntoAccount({
+        kind: 'organization',
+        relationship: 'member',
+        callerMembership: {
+          _id: 'm2',
+          accountId: 'org1',
+          memberUserId: 'u1',
+          role: 'admin',
+          status: 'active',
+          permissions: ['account:act_as', 'account:read'],
+          inherit: true,
+          source: 'direct',
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it('refuses channels even with act_as permission', () => {
+    expect(
+      canSwitchIntoAccount({
+        kind: 'channel',
+        relationship: 'owner',
+        callerMembership: {
+          _id: 'm3',
+          accountId: 'chan1',
+          memberUserId: 'u1',
+          role: 'owner',
+          status: 'active',
+          permissions: ['account:act_as'],
+          inherit: true,
+          source: 'direct',
+        },
+      }),
+    ).toBe(false);
+  });
+});
+
 describe('projectSwitchableAccounts', () => {
   it('returns [] for null state and empty graph', () => {
     expect(
@@ -235,6 +301,38 @@ describe('projectSwitchableAccounts', () => {
     ]);
   });
 
+  it('omits a graph-only member without account:act_as', () => {
+    const rows = projectSwitchableAccounts({
+      state: state([{ accountId: 'a1', sessionId: 's1' }], 'a1'),
+      graph: [
+        graphNode('org1', { kind: 'organization', relationship: 'member', callerMembership: {
+          _id: 'm1',
+          accountId: 'org1',
+          memberUserId: 'a1',
+          role: 'billing',
+          status: 'active',
+          permissions: ['account:read', 'billing:manage'],
+          inherit: true,
+          source: 'direct',
+        } }),
+        graphNode('org2', { kind: 'organization', relationship: 'member', callerMembership: {
+          _id: 'm2',
+          accountId: 'org2',
+          memberUserId: 'a1',
+          role: 'admin',
+          status: 'active',
+          permissions: ['account:act_as', 'account:read'],
+          inherit: true,
+          source: 'direct',
+        } }),
+      ],
+      profilesById: mapOf(user('a1'), user('org1'), user('org2')),
+      resolveAvatarUrl: noAvatar,
+    });
+
+    expect(rows.map((r) => r.accountId)).toEqual(['a1', 'org2']);
+  });
+
   it('dedups an account present as BOTH device session and graph node into ONE enriched row', () => {
     const rows = projectSwitchableAccounts({
       state: state([{ accountId: 'a1', sessionId: 's1', authuser: 0 }], 'a1'),

package/src/session/accountProjection.ts

@@ -135,6 +135,37 @@ export function isSwitchTargetAccount(
   return node.relationship === 'self' || isActAsEligibleKind(node.kind);
 }
 
+/**
+ * Whether the caller may switch INTO this account — the server-side
+ * `account:act_as` gate plus the structural {@link isSwitchTargetAccount} rule.
+ *
+ * `relationship: 'self'` always passes (returning to the caller's own personal
+ * account). Every other ground requires a switch-eligible kind AND
+ * `account:act_as` in the resolved membership permissions. When permissions are
+ * absent but the relationship is `owner`, the owner baseline is assumed — the
+ * API always resolves effective permissions for owned accounts, but test
+ * fixtures and stale rows may omit the membership blob.
+ */
+export function canSwitchIntoAccount(
+  node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+    callerMembership?: AccountMember | null;
+  },
+): boolean {
+  if (node.relationship === 'self') {
+    return true;
+  }
+  if (!isSwitchTargetAccount(node)) {
+    return false;
+  }
+  const permissions = node.callerMembership?.permissions;
+  if (permissions) {
+    return permissions.includes('account:act_as');
+  }
+  return node.relationship === 'owner';
+}
+
 /** Input to {@link projectSwitchableAccounts}. */
 export interface ProjectSwitchableAccountsInput {
   /**
@@ -176,9 +207,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 that are not switch targets — a `channel`, which nobody may act
- * as — are omitted. {@link isSwitchTargetAccount} is the rule; see the filter
- * below.
+ * Graph nodes the caller cannot switch into — a `channel`, or a managed account
+ * whose membership lacks `account:act_as` — are omitted.
+ * {@link canSwitchIntoAccount} is the rule; see the filter below.
  */
 export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput): SwitchableAccount[] {
   const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
@@ -274,7 +305,7 @@ export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput)
     // 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)) {
+    if (!canSwitchIntoAccount(node)) {
       continue;
     }
     remember(toRow(node.account, {
@@ -298,7 +329,7 @@ export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput)
  * document, but including their ids lets the caller pass one id set and lets the
  * projection prefer freshly-fetched profiles uniformly.
  *
- * Applies the SAME {@link isSwitchTargetAccount} filter as
+ * Applies the SAME {@link canSwitchIntoAccount} 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
@@ -315,7 +346,7 @@ export function switchableAccountIds(
     }
   }
   for (const node of graph) {
-    if (node.accountId && isSwitchTargetAccount(node)) {
+    if (node.accountId && canSwitchIntoAccount(node)) {
       ids.add(node.accountId);
     }
   }

package/src/utils/errorUtils.ts

@@ -36,6 +36,110 @@ export const ErrorCodes = {
   CONNECTION_FAILED: 'CONNECTION_FAILED'
 } as const;
 
+/**
+ * The `Error` shape the SDK rejects with when an HTTP request fails.
+ *
+ * `HttpService` throws this for every non-2xx response, and
+ * `OxyServices.handleError` (the wrapper the mixin methods rethrow through)
+ * preserves `message`, `status`, `code` and `details`. `response` only survives
+ * on the raw `HttpService`/`makeRequest` path, so treat it as optional.
+ *
+ * Narrow a caught value with {@link isHttpRequestError} instead of asserting.
+ */
+export interface HttpRequestError extends Error {
+    /** HTTP status of the failed response. */
+    status: number;
+    /** Machine-readable code the server sent, when it sent one. */
+    code?: string;
+    /** Structured error detail the server sent, when it sent an object. */
+    details?: Record<string, unknown>;
+    /**
+     * Present on errors thrown directly by `HttpService`. `data` is the parsed
+     * JSON error body verbatim — the escape hatch for any server field the SDK
+     * does not lift onto `code`/`details`.
+     */
+    response?: {
+        status: number;
+        statusText: string;
+        data?: unknown;
+    };
+}
+
+/**
+ * Narrow a caught value to {@link HttpRequestError}.
+ *
+ * Returns `false` for a plain {@link ApiError} object (those are objects, not
+ * `Error`s) — run an arbitrary thrown value through {@link handleHttpError}
+ * first if you need one normalized.
+ */
+export function isHttpRequestError(value: unknown): value is HttpRequestError {
+    if (!(value instanceof Error)) {
+        return false;
+    }
+    return typeof (value as Partial<HttpRequestError>).status === 'number';
+}
+
+/**
+ * The fields {@link parseHttpErrorBody} lifts off a parsed error response body.
+ */
+export interface ParsedHttpErrorBody {
+    message?: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+
+const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const nonEmptyString = (value: unknown): string | undefined =>
+    typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+
+/**
+ * Extract `message` / `code` / `details` from a parsed HTTP error response body.
+ *
+ * Handles every error envelope in use across the Oxy ecosystem:
+ *
+ * - `{ error: { code, message, details? } }` — nested envelope (CrowdSource and
+ *   other Oxy services). Never stringify the nested object: `new Error(obj)`
+ *   yields the literal message `"[object Object]"`.
+ * - `{ error: '<CODE>', message, details? }` — oxy-api's canonical shape
+ *   (`ApiError.toJSON`), where the top-level `error` field IS the code.
+ * - `{ error: '<CODE>', error_description }` — RFC 6749 §5.2 / RFC 6750 §3, the
+ *   OAuth token and userinfo endpoints. `error_description` is the human text
+ *   and `error` is the machine code, so both survive.
+ * - `{ message, code }` — e.g. the API's CSRF rejections.
+ * - `{ error: '<human message>' }` — legacy hand-rolled routes. With no sibling
+ *   `message`/`error_description` the string is the message, not a code: a bare
+ *   `error` string is not machine-readable enough to promote to `code`.
+ *
+ * Anything else — a non-object body (`null`, `[]`, `"str"`, `42`), or an object
+ * carrying none of these fields — yields an empty result, leaving the caller on
+ * its status-based fallback message. Total function: never throws.
+ */
+export function parseHttpErrorBody(body: unknown): ParsedHttpErrorBody {
+    if (!isPlainRecord(body)) {
+        return {};
+    }
+
+    const nested = isPlainRecord(body.error) ? body.error : undefined;
+    const errorString = nonEmptyString(body.error);
+    // A sibling that proves the top-level `error` is a CODE rather than prose.
+    const siblingMessage = nonEmptyString(body.message) ?? nonEmptyString(body.error_description);
+
+    return {
+        message: siblingMessage ?? (nested ? nonEmptyString(nested.message) : errorString),
+        code:
+            (nested ? nonEmptyString(nested.code) : undefined) ??
+            nonEmptyString(body.code) ??
+            (siblingMessage ? errorString : undefined),
+        details: isPlainRecord(body.details)
+            ? body.details
+            : nested && isPlainRecord(nested.details)
+                ? nested.details
+                : undefined,
+    };
+}
+
 /**
  * Create a standardized API error
  */
@@ -98,21 +202,28 @@ export function handleHttpError(error: unknown): ApiError {
 
   // Handle fetch Response errors - check if it has response property with status
   if (error && typeof error === 'object' && 'response' in error) {
-    const fetchError = error as { 
-      response?: { 
-        status: number; 
+    const fetchError = error as {
+      response?: {
+        status: number;
         statusText?: string;
       };
       status?: number;
       message?: string;
+      details?: unknown;
     };
-    
+
     const status = fetchError.response?.status || fetchError.status;
     if (status) {
+      // `details` is carried through when present: a body may ship structured
+      // detail without a machine-readable `code` (which is what routes the
+      // error to the already-an-ApiError branch above), and dropping it here
+      // would make it unreachable to every caller that rethrows via
+      // `OxyServices.handleError`.
       return createApiError(
         fetchError.message || `HTTP ${status} error`,
         getErrorCodeFromStatus(status),
-        status
+        status,
+        isPlainRecord(fetchError.details) ? fetchError.details : undefined
       );
     }
   }