@oxyhq/core 19.1.1 → 20.0.0

package/dist/esm/HttpService.js

@@ -15,7 +15,7 @@
 import { TTLCache, registerCacheForCleanup } from './utils/cache.js';
 import { RequestDeduplicator, RequestQueue, SimpleLogger } from './utils/requestUtils.js';
 import { retryAsync } from './utils/asyncUtils.js';
-import { handleHttpError } from './utils/errorUtils.js';
+import { handleHttpError, parseHttpErrorBody } from './utils/errorUtils.js';
 import { jwtDecode } from 'jwt-decode';
 import { isNative, getPlatformOS } from './utils/platform.js';
 import { isReactNative } from '@oxyhq/protocol';
@@ -447,32 +447,37 @@ export class HttpService {
                             // Failed to parse error body — not a CSRF error
                         }
                     }
-                    // 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;
+                    const errorContentType = response.headers.get('content-type');
+                    if (errorContentType?.includes('application/json')) {
                         try {
-                            const errorData = await response.json();
-                            // 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);
+                    // `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}`);
                     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;
                 }
                 // Handle different response types (optimized - read response once)

package/dist/esm/i18n/accountCategoryLabels.js

@@ -0,0 +1,37 @@
+import enUS from './locales/en-US.json' with { type: "json" };
+import { translate } from './index.js';
+/**
+ * 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 = enUS.accounts.accountCategory;
+export function accountCategoryLabel(locale, id) {
+    return translate(locale, `accounts.accountCategory.${id}`);
+}

package/dist/esm/i18n/accountRoleLabels.js

@@ -0,0 +1,20 @@
+import enUS from './locales/en-US.json' with { type: "json" };
+import { translate } from './index.js';
+/**
+ * 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 = {
+    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, role) {
+    return translate(locale, `accounts.roles.${role}.label`);
+}

package/dist/esm/i18n/reputationCategoryLabels.js

@@ -0,0 +1,13 @@
+import enUS from './locales/en-US.json' with { type: "json" };
+import { translate } from './index.js';
+/**
+ * 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 = enUS.trust.rules.categories;
+export function reputationCategoryLabel(locale, id) {
+    return translate(locale, `trust.rules.categories.${id}`);
+}

package/dist/esm/i18n/trustTierLabels.js

@@ -0,0 +1,12 @@
+import enUS from './locales/en-US.json' with { type: "json" };
+import { translate } from './index.js';
+/**
+ * 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 = enUS.trust.tiers;
+export function trustTierLabel(locale, tier) {
+    return translate(locale, `trust.tiers.${tier}`);
+}

package/dist/esm/index.js

@@ -110,11 +110,15 @@ export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBac
 // i18n
 // ---------------------------------------------------------------------------
 export { translate } from './i18n/index.js';
+export { accountCategoryLabel } from './i18n/accountCategoryLabels.js';
+export { accountRoleLabel } from './i18n/accountRoleLabels.js';
+export { reputationCategoryLabel } from './i18n/reputationCategoryLabels.js';
+export { trustTierLabel } from './i18n/trustTierLabels.js';
 // ---------------------------------------------------------------------------
 // API request / URL helpers
 // ---------------------------------------------------------------------------
 export { buildQueryParams, buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils.js';
-export { ErrorCodes, createApiError, handleHttpError, validateRequiredFields, } from './utils/errorUtils.js';
+export { ErrorCodes, createApiError, handleHttpError, isHttpRequestError, parseHttpErrorBody, validateRequiredFields, } from './utils/errorUtils.js';
 export { retryAsync } from './utils/asyncUtils.js';
 // ---------------------------------------------------------------------------
 // Validation
@@ -173,13 +177,12 @@ export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountId
 // 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.js';
+// `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.js';
 // Headless controller for the unified account dialog. Framework-agnostic
 // state machine + subscribe/getSnapshot store (bind via `useSyncExternalStore`)
 // — sign-in is passkey (WebAuthn) or the Commons QR / shared-keychain handoff;

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

@@ -156,6 +156,23 @@ export function OxyServicesFollowGraphMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * 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) {
+            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/dist/esm/session/accountProjection.js

@@ -48,6 +48,30 @@ import { getNormalizedUserHandle } from '../utils/userHandle.js';
 export function isSwitchTargetAccount(node) {
     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) {
+    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';
+}
 /**
  * Pure union of device sign-ins and account-graph nodes into the flat
  * {@link SwitchableAccount}[] every switcher renders.
@@ -57,9 +81,9 @@ export function isSwitchTargetAccount(node) {
  * 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) {
     const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
@@ -139,7 +163,7 @@ export function projectSwitchableAccounts(input) {
         // 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, {
@@ -161,7 +185,7 @@ export function projectSwitchableAccounts(input) {
  * document, but including their ids lets the caller pass one id set and lets the
  * projection prefer freshly-fetched profiles uniformly.
  *
- * Applies the SAME {@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
@@ -175,7 +199,7 @@ export function switchableAccountIds(state, graph) {
         }
     }
     for (const node of graph) {
-        if (node.accountId && isSwitchTargetAccount(node)) {
+        if (node.accountId && canSwitchIntoAccount(node)) {
             ids.add(node.accountId);
         }
     }

package/dist/esm/utils/errorUtils.js

@@ -28,6 +28,63 @@ export const ErrorCodes = {
     NETWORK_ERROR: 'NETWORK_ERROR',
     CONNECTION_FAILED: 'CONNECTION_FAILED'
 };
+/**
+ * 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) {
+    if (!(value instanceof Error)) {
+        return false;
+    }
+    return typeof value.status === 'number';
+}
+const isPlainRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const nonEmptyString = (value) => 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) {
+    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
  */
@@ -72,7 +129,12 @@ export function handleHttpError(error) {
         const fetchError = error;
         const status = fetchError.response?.status || fetchError.status;
         if (status) {
-            return createApiError(fetchError.message || `HTTP ${status} error`, getErrorCodeFromStatus(status), 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, isPlainRecord(fetchError.details) ? fetchError.details : undefined);
         }
     }
     // Handle standard errors