@sparkvault/sdk-mobile 6.0.2 → 7.0.1

package/src/entropy.ts

@@ -1,18 +1,34 @@
-import { base64ToBytes } from './encoding.js';
+import { base64ToBytes } from './app-sdk/encoding.js';
+import { ENTROPY_FORMATS, MAX_DRAW_BYTES, isEntropyFormat, maxBytesFor } from './app-sdk/entropy-contract.js';
 import { SparkVaultMobileError, SparkVaultValidationError } from './errors.js';
 import type { MobileHttpClient } from './http.js';
+import { apiPath } from './request-path.js';
 
-export type EntropyFormat = 'hex' | 'base64' | 'bytes' | 'uuid';
+/** An output format the entropy endpoint serves (the platform's entropy contract). */
+export type EntropyFormat =
+  | 'hex'
+  | 'base64'
+  | 'base64url'
+  | 'alphanumeric'
+  | 'alphanumeric-mixed'
+  | 'password'
+  | 'numeric'
+  | 'uuid'
+  | 'bytes';
 
 export interface GenerateEntropyOptions {
+  /** Number of random bytes: 1–1024, or 1–512 for alphanumeric, alphanumeric-mixed and password. */
   bytes: number;
+  /** Output format. Defaults to base64. */
   format?: EntropyFormat;
 }
 
-export interface EntropyResponse {
-  value: string;
+/** The endpoint's answer: `value` is a number array for the `bytes` format and a string for every other. */
+export interface EntropyResponse<Value extends string | number[] = string | number[]> {
+  value: Value;
   num_bytes: number;
   format?: EntropyFormat;
+  reference_id?: string;
 }
 
 export class MobileEntropyClient {
@@ -22,35 +38,85 @@ export class MobileEntropyClient {
     this.http = http;
   }
 
+  generate(options: GenerateEntropyOptions & { format: 'bytes' }): Promise<EntropyResponse<number[]>>;
+  generate(options: GenerateEntropyOptions & { format?: Exclude<EntropyFormat, 'bytes'> }): Promise<EntropyResponse<string>>;
+  generate(options: GenerateEntropyOptions): Promise<EntropyResponse>;
   async generate(options: GenerateEntropyOptions): Promise<EntropyResponse> {
-    this.validateByteCount(options.bytes);
-    const response = await this.http.post<EntropyResponse>('/entropy/generate', {
+    const format = options.format ?? 'base64';
+    validateEntropyRequest(options.bytes, format);
+    const response = await this.http.post<EntropyResponse>(apiPath`/entropy/generate`, {
       num_bytes: options.bytes,
-      format: options.format ?? 'base64',
+      format,
     });
     return response.data;
   }
 
   async generateBytes(bytes: number): Promise<Uint8Array> {
     const response = await this.generate({ bytes, format: 'base64' });
-    if (typeof response.value !== 'string' || response.value.length === 0) {
-      throw new SparkVaultMobileError('Entropy endpoint returned no value');
-    }
-
-    const entropy = base64ToBytes(response.value);
-    if (entropy.length !== bytes) {
-      throw new SparkVaultMobileError(`Entropy length mismatch: expected ${bytes}, got ${entropy.length}`);
-    }
-
-    return entropy;
+    return drawnBytes(response.value, bytes);
   }
 
-  private validateByteCount(bytes: number): void {
-    if (!Number.isInteger(bytes) || bytes < 1 || bytes > 1024) {
-      throw new SparkVaultValidationError('Entropy byte count must be an integer from 1 to 1024', {
+  /**
+   * Random bytes for the signed-in client's own working values (a key's id, a
+   * secret's server share), from POST /v1/entropy/first-party: answered to an
+   * interactive SparkVault session only, never plan- or bandwidth-gated and
+   * never recorded as the account's usage. Values an integration asks for come
+   * from `generate` / `generateBytes`.
+   *
+   * @param bytes - 1 to the entropy contract's ceiling (MAX_DRAW_BYTES)
+   * @returns exactly `bytes` bytes
+   */
+  async drawFirstParty(bytes: number): Promise<Uint8Array> {
+    if (!Number.isInteger(bytes) || bytes < 1 || bytes > MAX_DRAW_BYTES) {
+      throw new SparkVaultValidationError(`Entropy byte count must be an integer from 1 to ${MAX_DRAW_BYTES}`, {
         field: 'bytes',
         received: bytes,
       });
     }
+    const response = await this.http.post<{ value: unknown; num_bytes: number }>(apiPath`/entropy/first-party`, {
+      num_bytes: bytes,
+    });
+    return drawnBytes(response.data.value, bytes);
+  }
+}
+
+/**
+ * The bytes a draw answered as base64, refused unless they are exactly the
+ * bytes asked for, so a malformed answer fails the operation that asked for it.
+ */
+function drawnBytes(value: unknown, bytes: number): Uint8Array {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new SparkVaultMobileError('Entropy endpoint returned no value');
+  }
+
+  const entropy = base64ToBytes(value);
+  if (entropy === null) {
+    throw new SparkVaultMobileError('Entropy endpoint returned a value that is not base64');
+  }
+  if (entropy.length !== bytes) {
+    throw new SparkVaultMobileError(`Entropy length mismatch: expected ${bytes}, got ${entropy.length}`);
+  }
+
+  return entropy;
+}
+
+/**
+ * Refuse a request the endpoint would refuse, before it is sent: the format must
+ * be one the endpoint serves, and the byte count an integer from 1 to that
+ * format's ceiling.
+ */
+function validateEntropyRequest(bytes: number, format: EntropyFormat): void {
+  if (!isEntropyFormat(format)) {
+    throw new SparkVaultValidationError(`Entropy format must be one of: ${ENTROPY_FORMATS.join(', ')}`, {
+      field: 'format',
+      received: format,
+    });
+  }
+  const max = maxBytesFor(format);
+  if (!Number.isInteger(bytes) || bytes < 1 || bytes > max) {
+    throw new SparkVaultValidationError(`Entropy byte count must be an integer from 1 to ${max} for the ${format} format`, {
+      field: 'bytes',
+      received: bytes,
+    });
   }
 }

package/src/errors.ts

@@ -1,7 +1,9 @@
 import type { ApiErrorBody, ApiMeta, BackgroundTransferFailureKind } from './types.js';
+import { isTransientHttpStatus } from './app-sdk/transient.js';
+import { VAT_REFUSAL_REASONS, vatRefusalReason as readVatRefusalReason } from './app-sdk/vat-refusal.js';
 
-// Only the byte pools hard-gate: flex licensing has no seat limit, and
-// Identity soft-gates through its own path.
+// Only the byte pools hard-gate: licenses are assigned per member, never
+// drawn from a pool, and Identity soft-gates through its own path.
 type QuotaResource = 'storage' | 'bandwidth';
 
 function isQuotaResource(value: unknown): value is QuotaResource {
@@ -115,10 +117,10 @@ export class SparkVaultTimeoutError extends SparkVaultMobileError {
 }
 
 /**
- * Thrown when a download is requested against an ingot that is still being
- * processed server-side (status `uploading`/`encrypting`). Transient by
- * nature, but retrying immediately will not help — callers should back off
- * until the ingot becomes active.
+ * Thrown when a download is requested against an ingot whose upload Forge has
+ * not activated yet (status `uploading`). Transient by nature, but retrying
+ * immediately will not help — callers should back off until the ingot becomes
+ * active.
  */
 export class IngotNotReadyError extends SparkVaultMobileError {
   /** Server-reported ingot status at the time of the request, when known. */
@@ -140,32 +142,101 @@ export class IngotNotReadyError extends SparkVaultMobileError {
   }
 }
 
+/** The ingot a create was refused over, as the server read it. */
+export interface IngotNameHolder {
+  ingotId: string;
+  /**
+   * Lifecycle status of the holder: `active` when its upload finished,
+   * `uploading` when it has not (only a `refuse` create is refused over an
+   * unfinished holder; `complete_pending` completes one).
+   */
+  status: string;
+  sizeBytes: number;
+}
+
+/**
+ * Thrown when a create is refused because an ingot already holds the name in
+ * the target folder (409 `details.reason === 'NAME_HELD'`): with
+ * `onNameConflict: 'complete_pending'` a published holder, with `'refuse'` any
+ * holder. The server decided before writing anything, so the holder is
+ * untouched; `holder` is the row it read, which lets the caller act on it
+ * (send its bytes into its own row by id, adopt it, or try another name)
+ * without a second read.
+ */
+export class IngotNameHeldError extends SparkVaultMobileError {
+  readonly holder: IngotNameHolder;
+
+  constructor(
+    message: string,
+    options: { holder: IngotNameHolder; details?: Record<string, unknown>; meta?: ApiMeta }
+  ) {
+    super(message, { code: 'CONFLICT', statusCode: 409, details: options.details, meta: options.meta });
+    this.name = 'IngotNameHeldError';
+    this.holder = options.holder;
+    Object.setPrototypeOf(this, IngotNameHeldError.prototype);
+  }
+}
+
 export class TusUploadError extends SparkVaultMobileError {
   readonly cause: Error | null;
   readonly filename: string | null;
   readonly fileSize: number | null;
-  readonly phase: 'create' | 'upload' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
+  /**
+   * Where the upload stopped: `finalize` is after the transfer, when every
+   * byte was on Forge but the ingot was not confirmed published.
+   */
+  readonly phase: 'create' | 'upload' | 'finalize' | 'network' | 'timeout' | 'cancelled' | 'stalled' | 'unknown';
   /**
    * True when Forge no longer has the session (it answered a status
-   * `isSessionGone` recognises: expired or terminated), or the session
-   * cannot carry this file. The persisted session is worthless, so the
-   * caller starts a fresh upload instead of retrying it.
+   * `isSessionGone` recognises, or the expiry it named has passed), or the
+   * session cannot carry this file. The persisted session is worthless, so
+   * the caller starts a fresh upload instead of retrying it.
    */
   readonly sessionLost: boolean;
+  /**
+   * The `Retry-After` of the answer that ended the upload, in ms: the
+   * earliest a next attempt can expect another answer. Null when that answer
+   * named none, or no answer arrived.
+   */
+  readonly retryAfterMs: number | null;
+  /**
+   * True when every byte is on Forge and the session is intact but the ingot
+   * was not confirmed published: the vault did not read it `active` within
+   * the activation poll budget, or Forge was still saving the file at the
+   * upload's idle limit (code `upload_received_publishing`; it finishes
+   * without this device). The caller retries later by resuming the session
+   * it persisted, which asks Forge for the receipt again and sends no bytes.
+   */
+  readonly retryLater: boolean;
+  /**
+   * The code Core ended this upload with, as Forge named it. With code
+   * `upload_refused` a final refusal (`UPLOAD_POOL_FULL`: the account's
+   * storage pool cannot take it; `UPLOAD_SUPERSEDED`: a later upload replaced
+   * it), whose message is Core's own sentence and which no new upload of the
+   * same file remedies; with `sessionLost` any other code (`NOT_FOUND`: the
+   * file the upload was for is gone; `UPLOAD_PROTOCOL_RETIRED`; a 412's),
+   * which a fresh upload starts over from. Null when the answer named none.
+   */
+  readonly coreCode: string | null;
 
   constructor(
     message: string,
     options: {
       cause?: Error | null;
       httpStatus?: number | null;
+      /** The error's code when it names an outcome of its own; otherwise the HTTP status, or `tus_upload_error`. */
+      code?: string;
       filename?: string | null;
       fileSize?: number | null;
       phase?: TusUploadError['phase'];
       sessionLost?: boolean;
+      retryAfterMs?: number | null;
+      retryLater?: boolean;
+      coreCode?: string | null;
     } = {}
   ) {
     super(message, {
-      code: options.httpStatus ?? 'tus_upload_error',
+      code: options.code ?? options.httpStatus ?? 'tus_upload_error',
       statusCode: options.httpStatus ?? undefined,
     });
     this.name = 'TusUploadError';
@@ -174,6 +245,9 @@ export class TusUploadError extends SparkVaultMobileError {
     this.fileSize = options.fileSize ?? null;
     this.phase = options.phase ?? 'unknown';
     this.sessionLost = options.sessionLost ?? false;
+    this.retryAfterMs = options.retryAfterMs ?? null;
+    this.retryLater = options.retryLater ?? false;
+    this.coreCode = options.coreCode ?? null;
     Object.setPrototypeOf(this, TusUploadError.prototype);
   }
 
@@ -259,8 +333,7 @@ export function isNetworkError(err: unknown): boolean {
  * per-upload token minted with the ingot (expired, consumed, or bound to a
  * different session) — not the vault session. Re-unsealing the vault cannot
  * fix it; the caller creates a new upload session (`POST /ingots`) instead.
- * Use `isVatExpiredError` / `isReadOnlyVaultError` to tell the API's VAT
- * rejections apart.
+ * Use `vatRefusalReason` to tell the API's VAT refusals apart.
  */
 export function isAuthError(err: unknown): boolean {
   return (
@@ -271,31 +344,51 @@ export function isAuthError(err: unknown): boolean {
 }
 
 /**
- * True when the API rejected the vault access token because it has expired
- * (`details.reason === 'VAT_EXPIRED'` on a 401 or 403 — an expired VAT
- * answers 403 for its first hour, then 401). Re-unsealing the vault mints a
- * fresh VAT and the same request can be retried as-is.
+ * The reason the API refused the vault access token, or null when the error
+ * is not a VAT refusal:
+ *   - `VAT_INVALID` (401): no, a malformed, unknown or swept token, or one a
+ *     since-revoked DVAK minted — unseal again. Never the login.
+ *   - `VAT_EXPIRED` (403): the token outlived its TTL — unseal again and
+ *     retry the same request as-is.
+ *   - `VAT_READ_ONLY` (403): a View Only token on a write — no unseal fixes it.
+ * A 403 with no reason is a token for another vault or account; a 401 with no
+ * reason is the login itself.
+ */
+export function vatRefusalReason(err: unknown): string | null {
+  if (!(err instanceof SparkVaultMobileError) || err instanceof TusUploadError) {
+    return null;
+  }
+  return readVatRefusalReason(err);
+}
+
+/**
+ * True when the API refused the vault access token because it has expired
+ * (403 `VAT_EXPIRED`). Re-unsealing the vault mints a fresh VAT and the same
+ * request can be retried as-is.
  */
 export function isVatExpiredError(err: unknown): err is SparkVaultMobileError {
-  return (
-    err instanceof SparkVaultMobileError &&
-    (err.statusCode === 401 || err.statusCode === 403) &&
-    err.details?.reason === 'VAT_EXPIRED'
-  );
+  return vatRefusalReason(err) === VAT_REFUSAL_REASONS.EXPIRED;
 }
 
 /**
- * True when the vault access token is valid but read-only
- * (`details.reason === 'VAT_READ_ONLY'` on a 403): the session was unsealed
- * with a read-only access level, so a write cannot succeed by retrying or by
- * re-unsealing the same way — the caller needs write access to the vault.
+ * True when the vault access token is valid but read-only (403
+ * `VAT_READ_ONLY`): the session was unsealed with a read-only access level, so
+ * a write cannot succeed by retrying or by re-unsealing the same way — the
+ * caller needs write access to the vault.
  */
 export function isReadOnlyVaultError(err: unknown): err is SparkVaultMobileError {
-  return (
-    err instanceof SparkVaultMobileError &&
-    err.statusCode === 403 &&
-    err.details?.reason === 'VAT_READ_ONLY'
-  );
+  return vatRefusalReason(err) === VAT_REFUSAL_REASONS.READ_ONLY;
+}
+
+/**
+ * True for the API's 404 not-found answer: the resource it names does not
+ * exist (or is not this caller's to see). The only answer that says a vault,
+ * an ingot or a key's vault is missing; a rate limit, an outage or a refused
+ * session says nothing about it. Never true for a `TusUploadError`: Forge's
+ * 404 is an upload session that is gone, not a missing resource.
+ */
+export function isNotFoundError(err: unknown): err is SparkVaultMobileError {
+  return err instanceof SparkVaultMobileError && !(err instanceof TusUploadError) && err.statusCode === 404;
 }
 
 /** True for a 429 rate-limit response — retry after a cooldown, never immediately. */
@@ -311,18 +404,22 @@ export function isIngotNotReadyError(err: unknown): err is IngotNotReadyError {
   return err instanceof IngotNotReadyError;
 }
 
+/** Type guard for a create refused over the same-name ingot holding its name. */
+export function isIngotNameHeldError(err: unknown): err is IngotNameHeldError {
+  return err instanceof IngotNameHeldError;
+}
+
 /**
- * True when retrying a failed download can succeed. Validation failures and
- * deterministic 4xx responses always fail the same way again; everything else
- * (connectivity, 5xx, 408, 429) is worth another attempt.
+ * True when retrying a failed download can succeed. A validation failure always
+ * fails the same way again, and an HTTP refusal is retried only when the
+ * platform's retry rule (`isTransientHttpStatus`, mirrored from
+ * `@sparkvault/app-sdk/transient`) calls it transient; every other failure
+ * (connectivity, an answer that could not be read) is worth another attempt.
  */
 export function isRetryableDownloadError(err: unknown): boolean {
   if (err instanceof SparkVaultValidationError) return false;
   const status = err instanceof SparkVaultMobileError ? err.statusCode : undefined;
-  if (typeof status === 'number' && status >= 400 && status < 500 && status !== 408 && status !== 429) {
-    return false;
-  }
-  return true;
+  return typeof status !== 'number' || status < 400 || isTransientHttpStatus(status);
 }
 
 /**

package/src/folders.ts

@@ -7,6 +7,7 @@ import type {
   UpdateFolderRequest,
 } from './types.js';
 import { validateFolderId, validateIngotId, validateVaultId } from './validation.js';
+import { apiPath } from './request-path.js';
 
 export class MobileFoldersClient {
   private readonly http: MobileHttpClient;
@@ -17,14 +18,14 @@ export class MobileFoldersClient {
 
   async list(vaultId: string, vat: string): Promise<ListFoldersResponse> {
     validateVaultId(vaultId);
-    const response = await this.http.get<ListFoldersResponse>(`/vaults/${vaultId}/folders`, { vat });
+    const response = await this.http.get<ListFoldersResponse>(apiPath`/vaults/${vaultId}/folders`, { vat });
     return response.data;
   }
 
   async get(vaultId: string, folderId: string, vat: string): Promise<Folder> {
     validateVaultId(vaultId);
     validateFolderId(folderId);
-    const response = await this.http.get<Folder>(`/vaults/${vaultId}/folders/${folderId}`, { vat });
+    const response = await this.http.get<Folder>(apiPath`/vaults/${vaultId}/folders/${folderId}`, { vat });
     return response.data;
   }
 
@@ -32,7 +33,7 @@ export class MobileFoldersClient {
     validateVaultId(vaultId);
     validateFolderId(folderId);
     const response = await this.http.get<Folder & { breadcrumb?: FolderBreadcrumbItem[] }>(
-      `/vaults/${vaultId}/folders/${folderId}`,
+      apiPath`/vaults/${vaultId}/folders/${folderId}`,
       { vat }
     );
     return response.data.breadcrumb ?? [];
@@ -40,14 +41,14 @@ export class MobileFoldersClient {
 
   async create(vaultId: string, vat: string, data: CreateFolderRequest): Promise<Folder> {
     validateVaultId(vaultId);
-    const response = await this.http.post<Folder>(`/vaults/${vaultId}/folders`, data, { vat });
+    const response = await this.http.post<Folder>(apiPath`/vaults/${vaultId}/folders`, data, { vat });
     return response.data;
   }
 
   async update(vaultId: string, folderId: string, vat: string, data: UpdateFolderRequest): Promise<Folder> {
     validateVaultId(vaultId);
     validateFolderId(folderId);
-    const response = await this.http.put<Folder>(`/vaults/${vaultId}/folders/${folderId}`, data, { vat });
+    const response = await this.http.put<Folder>(apiPath`/vaults/${vaultId}/folders/${folderId}`, data, { vat });
     return response.data;
   }
 
@@ -62,7 +63,7 @@ export class MobileFoldersClient {
   async delete(vaultId: string, folderId: string, vat: string): Promise<void> {
     validateVaultId(vaultId);
     validateFolderId(folderId);
-    await this.http.delete(`/vaults/${vaultId}/folders/${folderId}`, { vat });
+    await this.http.delete(apiPath`/vaults/${vaultId}/folders/${folderId}`, { vat });
   }
 
   async moveIngot(vaultId: string, ingotId: string, vat: string, folderId: string | null): Promise<void> {
@@ -71,6 +72,6 @@ export class MobileFoldersClient {
     if (folderId !== null) {
       validateFolderId(folderId);
     }
-    await this.http.patch(`/vaults/${vaultId}/ingots/${ingotId}`, { folder_id: folderId }, { vat });
+    await this.http.patch(apiPath`/vaults/${vaultId}/ingots/${ingotId}`, { folder_id: folderId }, { vat });
   }
 }