@oxyhq/core 19.1.2 → 20.0.0

package/dist/types/i18n/accountCategoryLabels.d.ts

@@ -0,0 +1,34 @@
+import type { AccountCategoryId } from '@oxyhq/contracts';
+/**
+ * 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 declare const EN_ACCOUNT_CATEGORY_LABELS: Record<AccountCategoryId, string>;
+export declare function accountCategoryLabel(locale: string | undefined, id: AccountCategoryId): string;

package/dist/types/i18n/accountRoleLabels.d.ts

@@ -0,0 +1,10 @@
+import type { AccountRole } from '../mixins/OxyServices.accounts';
+/**
+ * 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 declare const EN_ACCOUNT_ROLE_LABELS: Record<AccountRole, string>;
+export declare function accountRoleLabel(locale: string | undefined, role: AccountRole): string;

package/dist/types/i18n/reputationCategoryLabels.d.ts

@@ -0,0 +1,10 @@
+import type { ReputationCategory } from '@oxyhq/contracts';
+/**
+ * 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 declare const EN_REPUTATION_CATEGORY_LABELS: Record<ReputationCategory, string>;
+export declare function reputationCategoryLabel(locale: string | undefined, id: ReputationCategory): string;

package/dist/types/i18n/trustTierLabels.d.ts

@@ -0,0 +1,9 @@
+import type { TrustTier } from '@oxyhq/contracts';
+/**
+ * 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 declare const EN_TRUST_TIER_LABELS: Record<TrustTier, string>;
+export declare function trustTierLabel(locale: string | undefined, tier: TrustTier): string;

package/dist/types/index.d.ts

@@ -79,9 +79,14 @@ export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError,
 export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './shared/utils/networkUtils';
 export type { CircuitBreakerState, CircuitBreakerConfig } from './shared/utils/networkUtils';
 export { translate } from './i18n';
+export { accountCategoryLabel } from './i18n/accountCategoryLabels';
+export { accountRoleLabel } from './i18n/accountRoleLabels';
+export { reputationCategoryLabel } from './i18n/reputationCategoryLabels';
+export { trustTierLabel } from './i18n/trustTierLabels';
 export { buildQueryParams, buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils';
 export type { PaginationParams, FollowGraphParams, FollowGraphSort, ApiResponse, ErrorResponse, } from './utils/apiUtils';
-export { ErrorCodes, createApiError, handleHttpError, validateRequiredFields, } from './utils/errorUtils';
+export { ErrorCodes, createApiError, handleHttpError, isHttpRequestError, parseHttpErrorBody, validateRequiredFields, } from './utils/errorUtils';
+export type { HttpRequestError, ParsedHttpErrorBody } from './utils/errorUtils';
 export { retryAsync } from './utils/asyncUtils';
 export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, MAX_DISPLAY_NAME_LENGTH, DISPLAY_NAME_INVALID_MESSAGE, isValidEmail, isValidUsername, isValidPassword, isValidDisplayName, DISPLAY_NAME_ALLOWED_SCRIPTS, DISPLAY_NAME_DISALLOWED_SOURCE, DISPLAY_NAME_ORPHANED_MARK_SOURCE, DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils';
 export { normalizeInlineText, normalizeMultilineText, } from './utils/textNormalization';
@@ -104,7 +109,7 @@ export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
 export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState';
-export { isSwitchTargetAccount, projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
+export { isSwitchTargetAccount, canSwitchIntoAccount, projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
 export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
 export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFlowPhase, SignInFlowState, SignInProgress, } from './session/accountDialogController';

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

@@ -122,6 +122,19 @@ export declare function OxyServicesFollowGraphMixin<T extends typeof OxyServices
             namespace: string;
             created: boolean;
         }>;
+        /**
+         * 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.
+         */
+        releaseFollowNamespace(namespace: string): Promise<{
+            namespace: string;
+            released: boolean;
+        }>;
         /**
          * Declare what following a kind of thing MEANS: the verb clients render,
          * whether reverse lookups are public, whether it federates.

package/dist/types/session/accountProjection.d.ts

@@ -121,6 +121,22 @@ export declare function isSwitchTargetAccount(node: {
     kind?: AccountKind | null;
     relationship?: AccountRelationship;
 }): boolean;
+/**
+ * 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 declare function canSwitchIntoAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+    callerMembership?: AccountMember | null;
+}): boolean;
 /** Input to {@link projectSwitchableAccounts}. */
 export interface ProjectSwitchableAccountsInput {
     /**
@@ -161,9 +177,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 declare function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput): SwitchableAccount[];
 /**
@@ -173,7 +189,7 @@ 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 {@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

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

@@ -23,6 +23,73 @@ export declare const ErrorCodes: {
     readonly NETWORK_ERROR: "NETWORK_ERROR";
     readonly CONNECTION_FAILED: "CONNECTION_FAILED";
 };
+/**
+ * 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 declare function isHttpRequestError(value: unknown): value is HttpRequestError;
+/**
+ * The fields {@link parseHttpErrorBody} lifts off a parsed error response body.
+ */
+export interface ParsedHttpErrorBody {
+    message?: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * 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 declare function parseHttpErrorBody(body: unknown): ParsedHttpErrorBody;
 /**
  * Create a standardized API error
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "19.1.2",
+  "version": "20.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -62,6 +62,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "NOTICE",
     "dist",
     "src"
   ],
@@ -79,7 +80,7 @@
     "directory": "packages/core"
   },
   "author": "OxyHQ",
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "homepage": "https://oxy.so",
   "engines": {
     "node": ">=18.0.0"
@@ -115,12 +116,13 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.24.0",
-    "@oxyhq/protocol": "^0.1.6",
+    "@oxyhq/contracts": "^0.25.0",
+    "@oxyhq/protocol": "^0.2.0",
     "@scure/bip39": "^1.6.0",
     "@types/elliptic": "^6.4.18",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",
+    "express-rate-limit": "^8.6.0",
     "helmet": "^8.0.0",
     "invariant": "^2.2.4",
     "jwt-decode": "^4.0.0",
@@ -132,8 +134,7 @@
     "@react-native-async-storage/async-storage": "*",
     "expo-crypto": "*",
     "expo-secure-store": "*",
-    "express": "^4.0.0",
-    "express-rate-limit": "^8.0.0"
+    "express": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@react-native-async-storage/async-storage": {

package/src/HttpService.ts

@@ -16,7 +16,7 @@
 import { TTLCache, registerCacheForCleanup } from './utils/cache';
 import { RequestDeduplicator, RequestQueue, SimpleLogger } from './utils/requestUtils';
 import { retryAsync } from './utils/asyncUtils';
-import { handleHttpError } from './utils/errorUtils';
+import { handleHttpError, parseHttpErrorBody } from './utils/errorUtils';
 import { jwtDecode } from 'jwt-decode';
 import { isNative, getPlatformOS } from './utils/platform';
 import { isReactNative } from '@oxyhq/protocol';
@@ -632,37 +632,44 @@ export class HttpService {
             }
           }
 
-          // Try to parse error response (handle empty/malformed JSON)
-          let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
-          const contentType = response.headers.get('content-type');
-          if (contentType && contentType.includes('application/json')) {
+          // Read the error body (may be absent, non-JSON, empty or malformed).
+          // Anything unreadable leaves `errorBody` undefined and degrades to the
+          // status-based message — an error path that throws its own error is
+          // worse than the error it was reporting.
+          let errorBody: unknown;
+          const errorContentType = response.headers.get('content-type');
+          if (errorContentType?.includes('application/json')) {
             try {
-              const errorData = await response.json() as {
-                message?: string;
-                error?: string;
-                error_description?: string;
-              } | null;
-              // Accept either structured error field from API responses.
-              if (errorData?.message) {
-                errorMessage = errorData.message;
-              } else if (errorData?.error_description) {
-                // RFC 6749 §5.2 / RFC 6750 §3 — OAuth endpoints surface human text here.
-                errorMessage = errorData.error_description;
-              } else if (errorData?.error) {
-                errorMessage = errorData.error;
-              }
+              errorBody = await response.json();
             } catch (parseError) {
               // Malformed JSON or empty response - use status text
               this.logger.warn('Failed to parse error response JSON:', parseError);
             }
           }
 
-          const error = new Error(errorMessage) as Error & {
+          // `parseHttpErrorBody` handles every envelope in use, including the
+          // nested `{ error: { code, message } }` shape — assigning that nested
+          // OBJECT as the message is what produced `"[object Object]"`.
+          const parsed = parseHttpErrorBody(errorBody);
+          const error = new Error(
+            parsed.message ?? `HTTP ${response.status}: ${response.statusText}`,
+          ) as Error & {
             status?: number;
-            response?: { status: number; statusText: string }
+            code?: string;
+            details?: Record<string, unknown>;
+            response?: { status: number; statusText: string; data?: unknown };
           };
           error.status = response.status;
-          error.response = { status: response.status, statusText: response.statusText };
+          error.response = { status: response.status, statusText: response.statusText, data: errorBody };
+          // Only set `code`/`details` when the server actually sent them.
+          // Assigning `undefined` would still create the property, which changes
+          // how `handleHttpError` classifies the error downstream.
+          if (parsed.code !== undefined) {
+            error.code = parsed.code;
+          }
+          if (parsed.details !== undefined) {
+            error.details = parsed.details;
+          }
           throw error;
         }
 

package/src/__tests__/parseHttpErrorBody.test.ts

@@ -0,0 +1,116 @@
+import { isHttpRequestError, parseHttpErrorBody } from '../utils/errorUtils';
+
+/**
+ * `parseHttpErrorBody` is the ONE place the SDK decides what a failed request's
+ * message, code and details are, across every error envelope the Oxy ecosystem
+ * emits. The bug it exists to prevent is silent: a nested
+ * `{ error: { code, message } }` assigned straight to `new Error(...)` yields
+ * the literal string `"[object Object]"`, which reads as a rendering bug in
+ * whichever app surfaces it, arbitrarily far from here.
+ *
+ * Each case below pins one envelope AND the discrimination it depends on — in
+ * particular, whether the top-level `error` string is a machine CODE or human
+ * prose is decided solely by whether a sibling human field is present, so both
+ * sides of that fork need a fixture or the rule is untested.
+ */
+describe('parseHttpErrorBody', () => {
+    it('reads the nested { error: { code, message, details } } envelope', () => {
+        expect(
+            parseHttpErrorBody({
+                error: { code: 'case_conflict', message: 'A case already exists', details: { caseId: 'c_1' } },
+            }),
+        ).toEqual({
+            message: 'A case already exists',
+            code: 'case_conflict',
+            details: { caseId: 'c_1' },
+        });
+    });
+
+    it("reads oxy-api's { error: '<CODE>', message } shape — error IS the code", () => {
+        expect(parseHttpErrorBody({ error: 'VALIDATION_ERROR', message: 'username is taken' })).toEqual({
+            message: 'username is taken',
+            code: 'VALIDATION_ERROR',
+            details: undefined,
+        });
+    });
+
+    it("reads RFC 6749 { error: '<CODE>', error_description } from the OAuth endpoints", () => {
+        // The OAuth token/userinfo endpoints are the one part of the API that
+        // does not use the `{ error, message }` envelope. Without this arm the
+        // human text is dropped and the raw code is shown to the user.
+        expect(
+            parseHttpErrorBody({ error: 'invalid_grant', error_description: 'Authorization code expired' }),
+        ).toEqual({
+            message: 'Authorization code expired',
+            code: 'invalid_grant',
+            details: undefined,
+        });
+    });
+
+    it("treats a LONE { error: '<text>' } as the message, never as a code", () => {
+        // The discriminator is the ABSENCE of a sibling human field. Promoting a
+        // bare string to `code` would put prose where callers switch on codes,
+        // so this case and the two above have to disagree.
+        expect(parseHttpErrorBody({ error: 'Something went wrong' })).toEqual({
+            message: 'Something went wrong',
+            code: undefined,
+            details: undefined,
+        });
+    });
+
+    it('reads the flat { message, code } shape (CSRF rejections)', () => {
+        expect(parseHttpErrorBody({ message: 'Invalid CSRF token', code: 'CSRF_TOKEN_INVALID' })).toEqual({
+            message: 'Invalid CSRF token',
+            code: 'CSRF_TOKEN_INVALID',
+            details: undefined,
+        });
+    });
+
+    it('ignores whitespace-only strings rather than reporting them as a message', () => {
+        // A blank message is worse than none: it replaces the status fallback
+        // with an empty error surface the user cannot act on.
+        expect(parseHttpErrorBody({ message: '   ', error: '' })).toEqual({
+            message: undefined,
+            code: undefined,
+            details: undefined,
+        });
+    });
+
+    it('ignores a non-object `details` instead of passing it through', () => {
+        expect(parseHttpErrorBody({ message: 'nope', details: 'not-an-object' }).details).toBeUndefined();
+        expect(parseHttpErrorBody({ message: 'nope', details: ['a'] }).details).toBeUndefined();
+    });
+
+    it.each([null, undefined, [], 'a string', 42, true])('returns {} for the non-object body %p', (body) => {
+        expect(parseHttpErrorBody(body)).toEqual({});
+    });
+
+    it('returns {} for an object carrying none of the known fields', () => {
+        expect(parseHttpErrorBody({ unrelated: 'field' })).toEqual({
+            message: undefined,
+            code: undefined,
+            details: undefined,
+        });
+    });
+});
+
+describe('isHttpRequestError', () => {
+    it('accepts an Error carrying a numeric status', () => {
+        const error = Object.assign(new Error('boom'), { status: 409 });
+        expect(isHttpRequestError(error)).toBe(true);
+    });
+
+    it('rejects a plain ApiError object — those are objects, not Errors', () => {
+        // The distinction is load-bearing: an ApiError has to go through
+        // `handleHttpError` first, and a truthy answer here would let a caller
+        // read `.stack`/`.name` off something that has neither.
+        expect(isHttpRequestError({ message: 'boom', status: 409, code: 'CONFLICT' })).toBe(false);
+    });
+
+    it('rejects an Error whose status is a non-number', () => {
+        // `'409'` is the shape a hand-built error most plausibly carries, and
+        // the narrowing promises callers a number they can compare.
+        expect(isHttpRequestError(Object.assign(new Error('boom'), { status: '409' }))).toBe(false);
+        expect(isHttpRequestError(new Error('boom'))).toBe(false);
+    });
+});

package/src/__tests__/serverValueImportsDeclared.test.ts

@@ -103,6 +103,13 @@ describe('@oxyhq/core/server value imports are installable', () => {
     expect(manifest.peerDependenciesMeta?.helmet?.optional).toBeUndefined();
   });
 
+  it('keeps express-rate-limit installable rather than a peer', () => {
+    // Same class as helmet: `rateLimit.ts` value-imports it and the server
+    // barrel re-exports that module, so a missing install crashes at boot.
+    expect(dependencies.has('express-rate-limit')).toBe(true);
+    expect(manifest.peerDependencies?.['express-rate-limit']).toBeUndefined();
+  });
+
   it('leaves express as an optional peer, because it is type-only here', () => {
     // The counter-example that stops this test from being read as "declare
     // everything": type imports vanish at build time, so an optional peer is a

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

@@ -0,0 +1,62 @@
+import { ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS } from '@oxyhq/contracts';
+import { accountCategoryLabel, EN_ACCOUNT_CATEGORY_LABELS } from '../accountCategoryLabels';
+
+/**
+ * Every locale the SDK ships a dictionary for, plus a region variant and an
+ * untranslated language, because the three take different paths through
+ * `translate`: exact dictionary, base-subtag dictionary, and English fallback.
+ */
+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('accountCategoryLabel', () => {
+  // Vacuity floor: a traversal bug that yielded an empty id list would make
+  // every assertion below pass over nothing.
+  it('covers the whole vocabulary', () => {
+    expect(ACCOUNT_CATEGORY_IDS.length).toBeGreaterThanOrEqual(46);
+    expect(Object.keys(EN_ACCOUNT_CATEGORY_LABELS)).toHaveLength(ACCOUNT_CATEGORY_IDS.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 ACCOUNT_CATEGORY_IDS) {
+        const label = accountCategoryLabel(locale, id);
+        expect(label).not.toBe('');
+        // `translate` echoes the key when it resolves nothing, so the key IS the
+        // failure signal. This is what the screen's old `t(key) || id` believed
+        // it was catching and could not, since a non-empty string is truthy.
+        expect(label).not.toBe(`accounts.accountCategory.${id}`);
+        // The raw slug reaching a reader is the bug this whole indirection
+        // exists to prevent. `ai` is excluded: its English label legitimately
+        // equals its id.
+      }
+    },
+  );
+
+  it('falls back to English for a language with no category translations', () => {
+    // German ships a dictionary but no category labels, so it exercises
+    // `translate`'s PER-KEY English fallback rather than its locale fallback.
+    expect(accountCategoryLabel('de-DE', 'cooperative')).toBe(
+      EN_ACCOUNT_CATEGORY_LABELS.cooperative,
+    );
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(accountCategoryLabel('es-MX', 'news')).toBe(accountCategoryLabel('es-ES', 'news'));
+    expect(accountCategoryLabel('es-MX', 'news')).not.toBe(EN_ACCOUNT_CATEGORY_LABELS.news);
+  });
+});

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

@@ -0,0 +1,54 @@
+import type { AccountRole } from '../../mixins/OxyServices.accounts';
+import { EN_ACCOUNT_ROLE_LABELS, accountRoleLabel } from '../accountRoleLabels';
+
+const ACCOUNT_ROLES: AccountRole[] = [
+  'owner',
+  'admin',
+  'editor',
+  'developer',
+  'billing',
+  'viewer',
+];
+
+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('accountRoleLabel', () => {
+  it('covers the whole vocabulary', () => {
+    expect(ACCOUNT_ROLES.length).toBe(6);
+    expect(Object.keys(EN_ACCOUNT_ROLE_LABELS)).toHaveLength(ACCOUNT_ROLES.length);
+  });
+
+  it.each([...SHIPPED_LOCALES, REGION_VARIANT, UNSHIPPED_LOCALE])(
+    'names every role in %s — never a key, never a slug, never empty',
+    (locale) => {
+      for (const role of ACCOUNT_ROLES) {
+        const label = accountRoleLabel(locale, role);
+        expect(label).not.toBe('');
+        expect(label).not.toBe(`accounts.roles.${role}.label`);
+      }
+    },
+  );
+
+  it('falls back to English for a language with no role translations', () => {
+    expect(accountRoleLabel('de-DE', 'developer')).toBe(EN_ACCOUNT_ROLE_LABELS.developer);
+  });
+
+  it('resolves a region variant through its base language', () => {
+    expect(accountRoleLabel('es-MX', 'admin')).toBe(accountRoleLabel('es-ES', 'admin'));
+    expect(accountRoleLabel('es-MX', 'admin')).not.toBe(EN_ACCOUNT_ROLE_LABELS.admin);
+  });
+});