@sparkvault/sdk-mobile 6.0.2 → 7.0.0

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,6 +142,41 @@ 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;
@@ -259,8 +296,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 +307,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 +367,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 });
   }
 }