@oxyhq/core 19.1.2 → 20.1.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.chains.js

@@ -0,0 +1,70 @@
+/**
+ * Chains — the shared record log every Oxy app reads and writes.
+ *
+ * A person has ONE chain. An app appends its own records to it and projects its
+ * feeds from what it reads back, instead of keeping a private copy of the same
+ * person's activity. This mixin is the client half of `/chains` in oxy-api, and
+ * it exists so that adopting the chain costs an app no HTTP of its own — the
+ * whole point of the shared substrate is that the second app writes less code
+ * than the first, not the same amount in a different file.
+ *
+ * ## Both calls are SERVICE-authenticated
+ *
+ * They go through `makeServiceRequest`, so they only work on a backend that has
+ * called `configureServiceAuth()`. That is not an accident of implementation: an
+ * append writes to someone else's chain and a read spans many subjects, so
+ * neither belongs in a browser holding a user session. A frontend that needs
+ * this asks its own backend.
+ *
+ * The authority is checked server-side and cannot be talked out of from here:
+ * `chains:write` plus the application's own `chainNamespaces` for an append,
+ * `chains:read` plus the public-collection policy for a read. A call that
+ * violates either gets a 403 or an empty page — this client adds no
+ * pre-validation that could drift from the server's answer.
+ */
+export function OxyServicesChainsMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * Append a record to `oxyUserId`'s chain under `collection`/`rkey`.
+         *
+         * Oxy issues and signs it; the calling app never holds a chain signing key.
+         * `rkey` is the app's own id for the thing — reusing it later supersedes the
+         * earlier record for that key, which is how an edit works.
+         *
+         * Requires the `chains:write` scope AND `collection` falling under one of
+         * this application's granted `chainNamespaces`. Both are enforced by the
+         * server; a violation throws with a 403.
+         */
+        async appendChainRecord(params) {
+            return this.makeServiceRequest('POST', '/chains/records', params);
+        }
+        /**
+         * Records published by any of `oxyUserIds` under any of `collections`,
+         * oldest first — the read a cross-app feed is projected from.
+         *
+         * Only collections Oxy declares PUBLIC come back, whatever is asked for; a
+         * private one yields nothing rather than an error.
+         *
+         * **Re-poll from slightly BEFORE your last cursor and dedupe by
+         * `recordId`.** The chain's pagination axis is a transaction-start
+         * timestamp, so a record can commit behind a cursor that already passed it.
+         * Re-delivering one costs bytes; skipping one costs a record that never
+         * appears. Projections are expected to be idempotent for exactly this
+         * reason.
+         */
+        async readChainRecords(params) {
+            const query = new URLSearchParams({
+                authors: params.oxyUserIds.join(','),
+                collections: params.collections.join(','),
+            });
+            if (params.since)
+                query.set('since', params.since);
+            if (params.limit !== undefined)
+                query.set('limit', String(params.limit));
+            return this.makeServiceRequest('GET', `/chains/records?${query.toString()}`);
+        }
+    };
+}

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/mixins/OxyServices.store.js

@@ -0,0 +1,263 @@
+import { CACHE_TIMES } from './mixinHelpers.js';
+/** Read one page out of that envelope. */
+function pageOf(res) {
+    return {
+        items: res.data ?? [],
+        total: res.pagination?.total ?? 0,
+        hasMore: res.pagination?.hasMore ?? false,
+    };
+}
+/**
+ * Build a query string from the options that were actually supplied.
+ *
+ * Generic over the options object rather than taking a `Record`: an interface
+ * has no implicit index signature in TypeScript, so `StoreReviewsOptions` would
+ * not be assignable to one and every call site would need a cast.
+ */
+function queryOf(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const rendered = search.toString();
+    return rendered ? `?${rendered}` : '';
+}
+export function OxyServicesStoreMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        // =========================================================================
+        // The storefront — /store. No authentication: everything served is public.
+        // =========================================================================
+        /** The shelves, in the order the store curates them. */
+        async listStoreCategories() {
+            try {
+                const res = await this.makeRequest('GET', '/store/categories', undefined, { cache: true, cacheTTL: CACHE_TIMES.MEDIUM });
+                return res.data ?? [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Published listings, newest first, optionally one shelf.
+         *
+         * An unknown category slug is an EMPTY shelf, not every app on the store —
+         * so a typo shows nothing rather than showing everything.
+         *
+         * @param options - `category` is a category slug; `limit` defaults to 24.
+         */
+        async listStoreApps(options = {}) {
+            try {
+                const res = await this.makeRequest('GET', `/store/apps${queryOf(options)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return pageOf(res);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * One store page.
+         *
+         * A draft answers 404 exactly as an unknown slug does: whether an
+         * unpublished page exists under a name is not something a visitor learns.
+         *
+         * @param slug - The listing's public slug, not an application id.
+         */
+        async getStoreApp(slug) {
+            try {
+                const res = await this.makeRequest('GET', `/store/apps/${encodeURIComponent(slug)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return res.data;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Visible reviews for a published app, each with the publisher's reply. */
+        async listStoreReviews(slug, options = {}) {
+            try {
+                const res = await this.makeRequest('GET', `/store/apps/${encodeURIComponent(slug)}/reviews${queryOf(options)}`, undefined, { cache: true, cacheTTL: CACHE_TIMES.SHORT });
+                return pageOf(res);
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // =========================================================================
+        // Reviewing — any signed-in Oxy account
+        // =========================================================================
+        /** The caller's own review of an app, or `null` if they have not written one. */
+        async getMyStoreReview(slug) {
+            try {
+                const res = await this.makeRequest('GET', `/store/apps/${encodeURIComponent(slug)}/review`, undefined, { cache: false });
+                return res.data ?? null;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Write the caller's review, or replace what they said before.
+         *
+         * A person has one review per app, so this sets it rather than adding one.
+         * Rewriting does not clear a moderator's decision: a hidden review stays
+         * hidden when its author edits it.
+         */
+        async writeStoreReview(slug, input) {
+            try {
+                const res = await this.makeRequest('PUT', `/store/apps/${encodeURIComponent(slug)}/review`, input, { cache: false });
+                return res.data;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Withdraw the caller's own review. A real delete — the words were theirs. */
+        async deleteMyStoreReview(slug) {
+            try {
+                await this.makeRequest('DELETE', `/store/apps/${encodeURIComponent(slug)}/review`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Answer a review on the publisher's behalf.
+         *
+         * Requires `app:update` over the application's owning account — the same
+         * permission that guards every other write to that application. Addressed
+         * by review id because the reply belongs to the review, and a listing can be
+         * renamed or withdrawn out from under it.
+         */
+        async replyToStoreReview(reviewId, body) {
+            try {
+                const res = await this.makeRequest('PUT', `/store/reviews/${encodeURIComponent(reviewId)}/reply`, { body }, { cache: false });
+                return res.data;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Withdraw the publisher's answer. Same permission that wrote it. */
+        async deleteStoreReviewReply(reviewId) {
+            try {
+                await this.makeRequest('DELETE', `/store/reviews/${encodeURIComponent(reviewId)}/reply`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // =========================================================================
+        // The publisher's listing — /applications/:appId/listing
+        // =========================================================================
+        /** The application's store page in whatever state, or `null` if it has none. */
+        async getAppListing(applicationId) {
+            try {
+                return await this.makeRequest('GET', `/applications/${encodeURIComponent(applicationId)}/listing`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Create the page or replace its content. Never its status.
+         *
+         * Editing does not move a page: correcting a typo on a live listing leaves
+         * it live, and fixing a rejected one does not re-submit it.
+         */
+        async writeAppListing(applicationId, input) {
+            try {
+                return await this.makeRequest('PUT', `/applications/${encodeURIComponent(applicationId)}/listing`, input, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Hand the page to the store for review. From a draft, or a rejected page once fixed. */
+        async submitAppListing(applicationId) {
+            try {
+                return await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/listing/submit`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Take the page down, or withdraw it from the queue.
+         *
+         * Back to a draft, never deleted: the slug, the words and the screenshots
+         * are the publisher's work, and the reviews were never the listing's to take
+         * with them.
+         */
+        async unpublishAppListing(applicationId) {
+            try {
+                return await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/listing/unpublish`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        // =========================================================================
+        // Screenshots
+        // =========================================================================
+        /** Every picture on the listing, in the author's order. */
+        async listAppListingScreenshots(applicationId) {
+            try {
+                return await this.makeRequest('GET', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Attach an already-uploaded image, appended to the end.
+         *
+         * Upload through the assets surface first; the store keeps a reference
+         * rather than a second copy of the asset pipeline. The file must be live, an
+         * image, and one the caller is entitled to.
+         */
+        async addAppListingScreenshot(applicationId, input) {
+            try {
+                return await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots`, input, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Edit a picture's caption or the frame it was taken in. Order is {@link reorderAppListingScreenshots}. */
+        async updateAppListingScreenshot(applicationId, screenshotId, input) {
+            try {
+                return await this.makeRequest('PATCH', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots/${encodeURIComponent(screenshotId)}`, input, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Remove a picture. The uploaded file stays — it may be in use elsewhere. */
+        async deleteAppListingScreenshot(applicationId, screenshotId) {
+            try {
+                await this.makeRequest('DELETE', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots/${encodeURIComponent(screenshotId)}`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Set the order of every picture at once.
+         *
+         * Send EVERY id on the listing, exactly once, in the order they should
+         * appear. A partial list is rejected rather than applied: it would leave the
+         * pictures it omits at their old positions, interleaved with the new ones.
+         */
+        async reorderAppListingScreenshots(applicationId, screenshotIds) {
+            try {
+                return await this.makeRequest('PUT', `/applications/${encodeURIComponent(applicationId)}/listing/screenshots/order`, { screenshotIds }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}