@oxyhq/core 15.0.1 → 16.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "15.0.1",
+  "version": "16.1.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -131,7 +131,7 @@
     "expo-crypto": "*",
     "expo-secure-store": "*",
     "express": "^4.0.0",
-    "express-rate-limit": "^7.0.0",
+    "express-rate-limit": "^8.0.0",
     "helmet": "^8.0.0"
   },
   "peerDependenciesMeta": {

package/src/OxyServices.errors.ts

@@ -64,6 +64,51 @@ export class AssetUrlResolutionError extends Error {
   }
 }
 
+/**
+ * Thrown when one or more chunks of `getServiceAssetMetadataByIds` could not be
+ * resolved.
+ *
+ * Exists because for this endpoint a FAILED request and an ABSENT asset produce
+ * the same observable result. The server legitimately omits unknown/deleted ids,
+ * so callers are documented to map the response by `id` and treat a missing
+ * entry as "no such asset" — which means a chunk that 429s, times out or 5xxs
+ * reads as authoritative absence unless it is raised.
+ *
+ * That was not hypothetical: a metadata backfill counted every throttled asset
+ * as needing no update and exited 0, and the MTN signed-record builder embedded
+ * media with no content hash into records that are immutable once signed. Both
+ * paths reported success and wrote nothing.
+ *
+ * `unresolvedIds` carries every id in a failed chunk — not the subset the server
+ * would have omitted anyway, which is unknowable when the request never landed.
+ * A caller that wants best-effort passes `{ partial: true }` and never sees this.
+ */
+export class ServiceAssetMetadataError extends Error {
+  public readonly code = 'SERVICE_ASSET_METADATA_UNRESOLVED';
+  /** Every id belonging to a chunk whose request failed. */
+  public readonly unresolvedIds: string[];
+  /** HTTP statuses observed across the failed chunks (deduped, ascending). */
+  public readonly statuses: number[];
+  /**
+   * The first underlying transport/API failure. Declared on the class rather
+   * than relying on `Error.cause` because this package targets ES2020, where
+   * `cause` is not part of the `Error` type.
+   */
+  public readonly cause?: unknown;
+
+  constructor(unresolvedIds: string[], statuses: number[], cause?: unknown) {
+    const uniqueStatuses = Array.from(new Set(statuses)).sort((a, b) => a - b);
+    const statusSuffix = uniqueStatuses.length > 0 ? ` — status ${uniqueStatuses.join(', ')}` : '';
+    super(
+      `Could not resolve asset metadata for ${unresolvedIds.length} id(s)${statusSuffix}. Treat this as unknown, not as absent; pass { partial: true } for best-effort.`,
+    );
+    this.name = 'ServiceAssetMetadataError';
+    this.unresolvedIds = unresolvedIds;
+    this.statuses = uniqueStatuses;
+    this.cause = cause;
+  }
+}
+
 export class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
   constructor(operationName: string, timeoutMs: number) {
     super(

package/src/OxyServices.ts

@@ -57,7 +57,7 @@
  * See method JSDoc for more details and options.
  */
 import { OxyServicesBase, type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
-import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
+import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors';
 
 // Import mixin composition helper
 import { composeOxyServices } from './mixins';
@@ -151,7 +151,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
 }
 
 // Re-export error classes for convenience
-export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError };
+export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError };
 
 /**
  * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.

package/src/index.ts

@@ -23,7 +23,7 @@ import './crypto/polyfill';
 // ---------------------------------------------------------------------------
 // API client
 // ---------------------------------------------------------------------------
-export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
+export { OxyServices, AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
 // Auth-refresh handler surface — consumed by `@oxyhq/services`'s OxyContext to
@@ -479,6 +479,7 @@ export {
     EMAIL_REGEX,
     USERNAME_REGEX,
     PASSWORD_REGEX,
+    MAX_DISPLAY_NAME_LENGTH,
     isValidEmail,
     isValidUsername,
     isValidPassword,
@@ -486,6 +487,7 @@ export {
     DISPLAY_NAME_ALLOWED_SCRIPTS,
     DISPLAY_NAME_DISALLOWED_SOURCE,
     DISPLAY_NAME_ORPHANED_MARK_SOURCE,
+    DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE,
     isRequiredString,
     isRequiredNumber,
     isRequiredBoolean,

package/src/mixins/OxyServices.assets.ts

@@ -2,7 +2,7 @@ import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, A
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '@oxyhq/protocol';
 import { logger } from '../logger';
-import { AssetUrlResolutionError } from '../OxyServices.errors';
+import { AssetUrlResolutionError, ServiceAssetMetadataError } from '../OxyServices.errors';
 import { extractErrorStatus } from '../utils/errorUtils';
 import { redactUrlQuery } from '../utils/redactUrl';
 
@@ -353,15 +353,28 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
      * throws because no credentials are available. A plain user-session request
      * is rejected by the route's service-auth guard.
      *
-     * Resilience: chunks are independent. A failed chunk is logged and skipped —
-     * the method returns every entry that resolved successfully rather than
-     * discarding the whole call on one chunk's failure. An empty/whitespace-only
-     * input resolves immediately with `[]` and performs no network call.
+     * FAILURE IS NOT ABSENCE. The server legitimately omits unknown/deleted ids,
+     * so a short result is normal — which means a chunk that FAILED (a 429, a
+     * timeout, a 5xx) is indistinguishable from "those assets don't exist" if it
+     * simply contributes nothing. This method used to swallow a failed chunk and
+     * return the rest, so every caller silently read a throttled request as "no
+     * metadata": a backfill counted the asset as needing no update, and the
+     * signed-record builder embedded a media item with no hash. Both reported
+     * success while writing nothing, and the MTN chain's records are immutable.
+     *
+     * So a failed chunk THROWS {@link ServiceAssetMetadataError} by default,
+     * carrying the ids it could not resolve. A caller that genuinely wants
+     * best-effort opts in with `{ partial: true }` and gets the old behaviour
+     * explicitly. An empty/whitespace-only input resolves immediately with `[]`
+     * and performs no network call.
      *
      * Not cached at the SDK layer: it's a POST keyed on a multi-id body (low hit
      * rate), mirroring the sibling service/POST methods which never cache.
      */
-    async getServiceAssetMetadataByIds(ids: string[]): Promise<ServiceAssetMetadata[]> {
+    async getServiceAssetMetadataByIds(
+      ids: string[],
+      options: { partial?: boolean } = {},
+    ): Promise<ServiceAssetMetadata[]> {
       const uniqueIds = Array.from(
         new Set(ids.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)),
       );
@@ -374,7 +387,12 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
         chunks.push(uniqueIds.slice(i, i + SERVICE_ASSET_METADATA_CHUNK_SIZE));
       }
 
-      // Run chunks concurrently; a single chunk failure must not sink the rest.
+      // Chunks stay independent so one failure never cancels work already in
+      // flight; the failures are collected and re-raised together below.
+      const unresolvedIds: string[] = [];
+      const statuses: number[] = [];
+      let firstError: unknown;
+
       const settled = await Promise.all(
         chunks.map(async (chunk): Promise<ServiceAssetMetadata[]> => {
           try {
@@ -385,17 +403,26 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
             );
             return Array.isArray(entries) ? entries : [];
           } catch (error: unknown) {
-            logger.warn('getServiceAssetMetadataByIds: chunk failed, continuing with remaining chunks', {
+            const status = extractErrorStatus(error);
+            logger.warn('getServiceAssetMetadataByIds: chunk failed', {
               method: 'getServiceAssetMetadataByIds',
               chunkSize: chunk.length,
-              status: extractErrorStatus(error),
+              status,
+              partial: options.partial === true,
               error: error instanceof Error ? error.message : String(error),
             });
+            unresolvedIds.push(...chunk);
+            if (typeof status === 'number') statuses.push(status);
+            firstError ??= error;
             return [];
           }
         }),
       );
 
+      if (unresolvedIds.length > 0 && options.partial !== true) {
+        throw new ServiceAssetMetadataError(unresolvedIds, statuses, firstError);
+      }
+
       return settled.flat();
     }
 

package/src/mixins/OxyServices.deviceBoot.ts

@@ -169,11 +169,11 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
      *
      * That paragraph is LOAD-BEARING, not belt-and-braces: the route sits above
      * oxy-api's router-wide origin guard (deliberately, so a native client with
-     * no `Origin` is not rejected), so as of this writing NOTHING server-side
-     * refuses a browser caller that presents a valid bearer. Until a server-side
-     * check lands, caller discipline is the only control — which is also why a
-     * doc note cannot be the whole answer to browser XSS minting a long-lived
-     * credential with the victim's bearer.
+     * no `Origin` is not rejected). oxy-api additionally refuses callers that
+     * carry browser context signals (`Origin` or `Sec-Fetch-Site`) with
+     * `403 browser_not_allowed` — native HTTP clients send neither. Gate the
+     * caller by platform on the client as well; do not widen the 404 degrade to
+     * 403, which would also swallow a genuine origin misconfiguration.
      *
      * @returns the provisioned credential, or `null` when the endpoint is absent
      * (404). The API deploy leads the SDK release, so a client on a newer SDK

package/src/mixins/__tests__/OxyServices.serviceAssetMetadata.test.ts

@@ -10,11 +10,14 @@
  *  - the `{ data }` envelope is unwrapped to a bare `ServiceAssetMetadata[]`
  *    (mirroring how `makeServiceRequest<T[]>` returns the inner array);
  *  - inputs > 100 ids are chunked at 100/request and merged;
- *  - a failed chunk is logged and skipped — successful chunks still return.
+ *  - a failed chunk THROWS `ServiceAssetMetadataError` naming its ids, so a
+ *    throttled request can never be read as "those assets do not exist";
+ *  - `{ partial: true }` opts back into best-effort explicitly.
  */
 
 import type { ServiceAssetMetadata } from '../../models/interfaces';
 import { OxyServices } from '../../OxyServices';
+import { ServiceAssetMetadataError } from '../../OxyServices.errors';
 
 const sampleEntry: ServiceAssetMetadata = {
   id: 'asset-1',
@@ -101,16 +104,62 @@ describe('OxyServices.assets — getServiceAssetMetadataByIds', () => {
     expect(result[249]?.id).toBe('asset-249');
   });
 
-  it('skips a failed chunk and returns the entries that resolved', async () => {
+  it('THROWS when a chunk fails, so a failed request is never read as absence', async () => {
+    // The load-bearing assertion. The server legitimately omits unknown/deleted
+    // ids, so a short result is normal — which is exactly why a chunk that 429s
+    // must not just contribute nothing. Swallowing it made a throttled request
+    // indistinguishable from "those assets do not exist".
     const ids = Array.from({ length: 150 }, (_, i) => `asset-${i}`);
 
     makeServiceRequestSpy
       .mockResolvedValueOnce([sampleEntry]) // first chunk (100 ids) succeeds
       .mockRejectedValueOnce(new Error('chunk failed')); // second chunk (50 ids) fails
 
-    const result = await oxy.getServiceAssetMetadataByIds(ids);
+    await expect(oxy.getServiceAssetMetadataByIds(ids)).rejects.toThrow(ServiceAssetMetadataError);
+    expect(makeServiceRequestSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('names every id of the failed chunk on the error', async () => {
+    const ids = Array.from({ length: 150 }, (_, i) => `asset-${i}`);
+
+    makeServiceRequestSpy
+      .mockResolvedValueOnce([sampleEntry])
+      .mockRejectedValueOnce(Object.assign(new Error('rate limited'), {
+        response: { status: 429 },
+      }));
+
+    const error = await oxy.getServiceAssetMetadataByIds(ids).catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(ServiceAssetMetadataError);
+    const typed = error as ServiceAssetMetadataError;
+    // The whole chunk is unresolved: which of those ids the server would have
+    // omitted anyway is unknowable when the request never landed.
+    expect(typed.unresolvedIds).toHaveLength(50);
+    expect(typed.unresolvedIds).toContain('asset-100');
+    expect(typed.unresolvedIds).not.toContain('asset-0');
+    expect(typed.statuses).toEqual([429]);
+    expect(typed.code).toBe('SERVICE_ASSET_METADATA_UNRESOLVED');
+  });
+
+  it('returns the resolved entries when the caller opts into { partial: true }', async () => {
+    const ids = Array.from({ length: 150 }, (_, i) => `asset-${i}`);
+
+    makeServiceRequestSpy
+      .mockResolvedValueOnce([sampleEntry])
+      .mockRejectedValueOnce(new Error('chunk failed'));
+
+    const result = await oxy.getServiceAssetMetadataByIds(ids, { partial: true });
 
     expect(makeServiceRequestSpy).toHaveBeenCalledTimes(2);
     expect(result).toEqual([sampleEntry]);
   });
+
+  it('does not throw when every chunk succeeds, with or without partial', async () => {
+    makeServiceRequestSpy.mockResolvedValue([sampleEntry]);
+
+    await expect(oxy.getServiceAssetMetadataByIds(['asset-1'])).resolves.toEqual([sampleEntry]);
+    await expect(
+      oxy.getServiceAssetMetadataByIds(['asset-1'], { partial: true }),
+    ).resolves.toEqual([sampleEntry]);
+  });
 });

package/src/utils/__tests__/accountUtils.test.ts

@@ -1,4 +1,5 @@
 import {
+    createQuickAccount,
     getAccountDisplayName,
     getAccountFallbackHandle,
     formatPublicKeyHandle,
@@ -116,6 +117,27 @@ describe('getAccountFallbackHandle', () => {
     });
 });
 
+describe('createQuickAccount', () => {
+    it('prefers API name.displayName over composed first/last', () => {
+        const account = createQuickAccount('sess-1', {
+            name: { first: 'Nate', last: 'Isern', displayName: 'Nate Isern' },
+            username: 'nateus',
+            id: 'user-1',
+        });
+        expect(account.displayName).toBe('Nate Isern');
+    });
+
+    it('falls back to the normalized handle when displayName is absent', () => {
+        const account = createQuickAccount('sess-1', {
+            name: { first: 'Nate', last: 'Isern' },
+            username: 'nateus',
+            id: 'user-1',
+        });
+        expect(account.displayName).toBe('nateus');
+        expect(account.displayName).not.toBe('Nate Isern');
+    });
+});
+
 describe('formatPublicKeyHandle', () => {
     it('truncates a long key and strips the 0x prefix before re-adding it', () => {
         expect(formatPublicKeyHandle('0x1234567890abcdef')).toBe('0x12345678…');

package/src/utils/__tests__/coldBoot.test.ts

@@ -241,13 +241,17 @@ describe('runColdBoot', () => {
     it('hangs forever when a step never settles and no deadline is set', async () => {
       const terminalRan = jest.fn();
       let settled = false;
+      let releaseHang: (() => void) | undefined;
 
       const outcomePromise = runColdBoot<TestSession>({
         steps: [
           {
             id: 'never-settles',
-            // Never resolves or rejects — models a hung async call.
-            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+            // Never resolves or rejects until the test tears down — models a hung async call.
+            run: () =>
+              new Promise<ColdBootStepResult<TestSession>>((resolve) => {
+                releaseHang = () => resolve({ kind: 'skip' });
+              }),
           },
           {
             id: 'terminal',
@@ -268,8 +272,9 @@ describe('runColdBoot', () => {
       expect(settled).toBe(false);
       expect(terminalRan).not.toHaveBeenCalled();
 
-      // Avoid a dangling unhandled promise in the test runner.
-      void outcomePromise;
+      // Tear down the intentional hang so Jest workers can exit cleanly.
+      releaseHang?.();
+      await outcomePromise;
     });
 
     /**