@oxyhq/core 19.1.2 → 20.1.0

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

@@ -116,6 +116,29 @@ export type {
     ConnectedApp,
 } from './mixins/OxyServices.connectedApps';
 
+// ---------------------------------------------------------------------------
+// App store (public storefront + reviews + the listing a publisher edits)
+// ---------------------------------------------------------------------------
+export type {
+    StoreCategory,
+    StoreRating,
+    StoreListingSummary,
+    StoreListingDetail,
+    StoreScreenshot,
+    StoreScreenshotPlatform,
+    StoreReview,
+    StoreOwnReview,
+    WriteStoreReviewInput,
+    StoreListingStatus,
+    PublisherListing,
+    WriteListingInput,
+    AddScreenshotInput,
+    UpdateScreenshotInput,
+    StorePage,
+    StorePageOptions,
+    StoreReviewsOptions,
+} from './mixins/OxyServices.store';
+
 // ---------------------------------------------------------------------------
 // Accounts (unified account graph: tree, membership, roles, bot credentials)
 // plus the applications owned within it (Application = OAuth client).
@@ -230,6 +253,13 @@ export type {
 } from './mixins/OxyServices.civic';
 export type { UserNodeStatus, UserNodeMode, UserNodeController, UserNodeLivenessStatus, RegisterNodeInput, RemoveNodeResult } from './mixins/OxyServices.nodes';
 
+/**
+ * Chains — the shared per-person record log. `ChainRecord` is generic over the
+ * app's own lexicon payload, so a consumer types its records without Oxy
+ * knowing any app's schema.
+ */
+export type { ChainRecord, ChainRecordPage, AppendedChainRecord } from './mixins/OxyServices.chains';
+
 // ---------------------------------------------------------------------------
 // Auth helpers (token refresh, error normalisation, retry policies)
 // ---------------------------------------------------------------------------
@@ -453,6 +483,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 +510,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 +684,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.chains.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+
+import type { OxyServicesBase } from '../OxyServices.base';
+
+/** A signed record as it comes back from a read. */
+export interface ChainRecord<TRecord = Record<string, unknown>> {
+  recordId: string;
+  /** The subject whose chain it is — the person the record is about. */
+  oxyUserId: string;
+  /** The lexicon NSID, e.g. `app.mention.feed.post`. */
+  collection: string;
+  envelope: {
+    version: number;
+    type: string;
+    subject: string;
+    issuer: string;
+    record: TRecord;
+    issuedAt: number;
+    seq?: number;
+    prev?: string | null;
+    collection?: string;
+    rkey?: string;
+    publicKey: string;
+    alg: string;
+    signature: string;
+  };
+}
+
+/** One page of a multi-subject read. */
+export interface ChainRecordPage<TRecord = Record<string, unknown>> {
+  records: ChainRecord<TRecord>[];
+  /**
+   * Opaque. Hand it back as `since` to continue; `null` at the end of the
+   * stream as of this snapshot. Never construct one.
+   */
+  nextCursor: string | null;
+}
+
+/** What an append returns once the record is on the chain. */
+export interface AppendedChainRecord {
+  recordId: string;
+  seq: number;
+  envelope: ChainRecord['envelope'];
+  verified: boolean;
+}
+
+export function OxyServicesChainsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /** Service-token request, implemented by the auth mixin earlier in the pipeline. */
+    declare makeServiceRequest: <R = unknown>(
+      method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+      url: string,
+      data?: unknown,
+      userId?: string,
+    ) => Promise<R>;
+
+    /**
+     * 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: {
+      oxyUserId: string;
+      collection: string;
+      rkey: string;
+      record: Record<string, unknown>;
+    }): Promise<AppendedChainRecord> {
+      return this.makeServiceRequest<AppendedChainRecord>('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<TRecord = Record<string, unknown>>(params: {
+      oxyUserIds: readonly string[];
+      collections: readonly string[];
+      since?: string | null;
+      limit?: number;
+    }): Promise<ChainRecordPage<TRecord>> {
+      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<ChainRecordPage<TRecord>>('GET', `/chains/records?${query.toString()}`);
+    }
+  };
+}

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.