@sparkvault/sdk-mobile 6.0.2 → 7.0.1

package/dist/identity-input.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Identity entry rules: what a typed identity is, its normalized form, and the
+ * keyboard its field needs. The sign-in dialog and every public identity method
+ * read identities through these rules, so a number or address resolves to the
+ * same identity whichever path it arrives by. A rule that misreads an identity
+ * locks that person out.
+ *
+ * What reads as a phone number and its E.164 form, and what is an email address
+ * and its canonical form, are the platform's one rules, mirrored from
+ * `@sparkvault/app-sdk/phone` and `@sparkvault/app-sdk/email-address` into
+ * `./app-sdk/`: the rules the Identity Product and the web SDK's identity field
+ * apply, so the dialog refuses exactly what the server would.
+ */
+import { inferIdentityType } from './app-sdk/phone.js';
+import type { IdentityType } from './types.js';
+export { inferIdentityType };
+/**
+ * An identity in the form the Identity Product keys it by, read as the given
+ * type: the canonical email address (trimmed, lowercased), or a phone number in
+ * E.164. Null when the value is not a valid identity of that type.
+ */
+export declare function normalizeIdentifier(value: string, identityType: IdentityType): string | null;
+export type ParsedIdentity = {
+    ok: true;
+    identity: string;
+    identityType: IdentityType;
+} | {
+    ok: false;
+    error: string;
+};
+/** Classify and normalize a submitted identity (the canonical email address, or E.164 phone via `parsePhone`). */
+export declare function parseIdentity(value: string, allowedTypes: IdentityType[]): ParsedIdentity;
+/**
+ * The identity field's keyboard. A field that takes an email keeps a keyboard
+ * that can type one even while the input still reads as a phone number: the
+ * first characters of "2024user@gmail.com" do, and the phone pad has no
+ * letters or '@' to finish it with.
+ */
+export declare function identityKeyboardType(allowedTypes: IdentityType[]): 'email-address' | 'phone-pad';

package/dist/identity-input.js

@@ -0,0 +1,59 @@
+/**
+ * Identity entry rules: what a typed identity is, its normalized form, and the
+ * keyboard its field needs. The sign-in dialog and every public identity method
+ * read identities through these rules, so a number or address resolves to the
+ * same identity whichever path it arrives by. A rule that misreads an identity
+ * locks that person out.
+ *
+ * What reads as a phone number and its E.164 form, and what is an email address
+ * and its canonical form, are the platform's one rules, mirrored from
+ * `@sparkvault/app-sdk/phone` and `@sparkvault/app-sdk/email-address` into
+ * `./app-sdk/`: the rules the Identity Product and the web SDK's identity field
+ * apply, so the dialog refuses exactly what the server would.
+ */
+import { canonicalEmailAddress, isValidEmailAddress } from './app-sdk/email-address.js';
+import { inferIdentityType, parsePhone } from './app-sdk/phone.js';
+export { inferIdentityType };
+/**
+ * An identity in the form the Identity Product keys it by, read as the given
+ * type: the canonical email address (trimmed, lowercased), or a phone number in
+ * E.164. Null when the value is not a valid identity of that type.
+ */
+export function normalizeIdentifier(value, identityType) {
+    if (identityType === 'phone') {
+        return parsePhone(value);
+    }
+    return isValidEmailAddress(value) ? canonicalEmailAddress(value) : null;
+}
+/** Classify and normalize a submitted identity (the canonical email address, or E.164 phone via `parsePhone`). */
+export function parseIdentity(value, allowedTypes) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return { ok: false, error: 'Enter an identity to continue.' };
+    }
+    const inferredType = inferIdentityType(trimmed);
+    if (!allowedTypes.includes(inferredType)) {
+        return {
+            ok: false,
+            error: inferredType === 'phone' ? 'Phone sign-in is not enabled for this app.' : 'Email sign-in is not enabled for this app.',
+        };
+    }
+    const identity = normalizeIdentifier(trimmed, inferredType);
+    if (!identity) {
+        return {
+            ok: false,
+            error: inferredType === 'email' ? 'Enter a valid email address.' : 'Enter a valid phone number in international format.',
+        };
+    }
+    return { ok: true, identity, identityType: inferredType };
+}
+/**
+ * The identity field's keyboard. A field that takes an email keeps a keyboard
+ * that can type one even while the input still reads as a phone number: the
+ * first characters of "2024user@gmail.com" do, and the phone pad has no
+ * letters or '@' to finish it with.
+ */
+export function identityKeyboardType(allowedTypes) {
+    return allowedTypes.includes('email') ? 'email-address' : 'phone-pad';
+}
+//# sourceMappingURL=identity-input.js.map

package/dist/identity-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-input.js","sourceRoot":"","sources":["../src/identity-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGnE,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAE7B;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,YAA0B;IAC3E,IAAI,YAAY,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC;AAMD,kHAAkH;AAClH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,YAA4B;IACvE,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,YAAY,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QACzC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC,4CAA4C;SAC9H,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC5D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC,qDAAqD;SACzH,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAA4B;IAC/D,OAAO,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC;AACxE,CAAC"}

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 export { SparkVaultMobile, createSparkVaultMobileClient, } from './client.js';
-export type { SparkVaultMobileConfig, ResolvedMobileConfig, } from './config.js';
+export type { MobileConnectivity, SparkVaultMobileConfig, ResolvedMobileConfig, } from './config.js';
 export type { AuthEvent, AuthEventListener, } from './http.js';
 export { MobileProductsClient, MobileIdentityClient, } from './products/index.js';
 export { MobileAccountClient, } from './account.js';
 export { MobileVaultsClient, } from './vaults.js';
 export { MobileFoldersClient, } from './folders.js';
-export { MobileIngotsClient, } from './ingots.js';
-export type { DownloadToFileOptions, DownloadToFileResult, UploadOptions, UploadFromUriOptions, ReplaceFromUriOptions, ResumeUploadOptions, CreateUploadOptions, CreateUploadResult, CreateDownloadLinkOptions, CreateDownloadLinkResult, } from './ingots.js';
+export { MobileIngotsClient, NAME_CONFLICT_POLICIES, } from './ingots.js';
+export type { NameConflictPolicy, DownloadToFileOptions, DownloadToFileResult, UploadOptions, UploadFromUriOptions, ReplaceFromUriOptions, ResumeUploadOptions, CreateUploadOptions, CreateUploadResult, CreateDownloadLinkOptions, CreateDownloadLinkResult, } from './ingots.js';
 export { MobileHealthClient, } from './health.js';
 export type { HealthCheckOptions, HealthCheckResult, } from './health.js';
 export { MobileSparksClient, } from './sparks.js';
@@ -16,11 +16,12 @@ export type { EntropyFormat, EntropyResponse, GenerateEntropyOptions, } from './
 export { MobileNotifyClient, } from './notify.js';
 export type { NotificationInboxState, NotificationMarkState, NotificationRow, ListNotificationsOptions, ListNotificationsResponse, UnreadCountResponse, MarkNotificationStateOptions, MarkNotificationStateResponse, NotificationBulkMarkState, MarkAllNotificationsStateOptions, MarkAllNotificationsStateResponse, MarkAllReadResult, RegisterDeviceResponse, } from './notify.js';
 export { MobileBillingClient, } from './billing.js';
-export type { PortalSession, } from './billing.js';
 export { MobileUsersClient, } from './users.js';
-export { isSessionGone, MobileTusUploader, parseForgeUrl, } from './tus.js';
+export { isSessionExpired, isSessionGone, MobileTusUploader, parseForgeUrl, } from './tus.js';
 export type { TusUploadFromUriOptions, TusResumeSession, TusSessionProbe, ParsedForgeUrl, } from './tus.js';
-export { base64EncodeUtf8, base64UrlToBytes, base64UrlToUtf8, bytesToUtf8, base64ToBytes, bytesToBase64, utf8ToBytes, } from './encoding.js';
-export { BackgroundTransferError, gateErrorFromBody, IngotNotReadyError, isAuthError, isIngotNotReadyError, isNetworkError, isRateLimitError, isReadOnlyVaultError, isRetryableDownloadError, isVatExpiredError, PlanRequiredError, QuotaExceededError, SparkVaultAuthenticationError, SparkVaultAuthorizationError, SparkVaultMobileError, SparkVaultNetworkError, SparkVaultTimeoutError, SparkVaultValidationError, TusUploadError, } from './errors.js';
+export { base64EncodeUtf8, base64UrlToBytes, base64UrlToUtf8, bytesToUtf8, base64ToBytes, bytesToBase64, bytesToBase64url, utf8ToBytes, } from './encoding.js';
+export { BackgroundTransferError, gateErrorFromBody, IngotNameHeldError, IngotNotReadyError, isAuthError, isIngotNameHeldError, isIngotNotReadyError, isNetworkError, isNotFoundError, isRateLimitError, isReadOnlyVaultError, isRetryableDownloadError, isVatExpiredError, PlanRequiredError, vatRefusalReason, QuotaExceededError, SparkVaultAuthenticationError, SparkVaultAuthorizationError, SparkVaultMobileError, SparkVaultNetworkError, SparkVaultTimeoutError, SparkVaultValidationError, TusUploadError, } from './errors.js';
+export { VAT_REFUSAL_REASONS, endsVatSession } from './app-sdk/vat-refusal.js';
+export type { IngotNameHolder, } from './errors.js';
 export { isSafeId, sanitizeFilename, validateFolderId, validateIngotId, validateVaultId, } from './validation.js';
 export type * from './types.js';

package/dist/index.js

@@ -3,15 +3,16 @@ export { MobileProductsClient, MobileIdentityClient, } from './products/index.js
 export { MobileAccountClient, } from './account.js';
 export { MobileVaultsClient, } from './vaults.js';
 export { MobileFoldersClient, } from './folders.js';
-export { MobileIngotsClient, } from './ingots.js';
+export { MobileIngotsClient, NAME_CONFLICT_POLICIES, } from './ingots.js';
 export { MobileHealthClient, } from './health.js';
 export { MobileSparksClient, } from './sparks.js';
 export { MobileEntropyClient, } from './entropy.js';
 export { MobileNotifyClient, } from './notify.js';
 export { MobileBillingClient, } from './billing.js';
 export { MobileUsersClient, } from './users.js';
-export { isSessionGone, MobileTusUploader, parseForgeUrl, } from './tus.js';
-export { base64EncodeUtf8, base64UrlToBytes, base64UrlToUtf8, bytesToUtf8, base64ToBytes, bytesToBase64, utf8ToBytes, } from './encoding.js';
-export { BackgroundTransferError, gateErrorFromBody, IngotNotReadyError, isAuthError, isIngotNotReadyError, isNetworkError, isRateLimitError, isReadOnlyVaultError, isRetryableDownloadError, isVatExpiredError, PlanRequiredError, QuotaExceededError, SparkVaultAuthenticationError, SparkVaultAuthorizationError, SparkVaultMobileError, SparkVaultNetworkError, SparkVaultTimeoutError, SparkVaultValidationError, TusUploadError, } from './errors.js';
+export { isSessionExpired, isSessionGone, MobileTusUploader, parseForgeUrl, } from './tus.js';
+export { base64EncodeUtf8, base64UrlToBytes, base64UrlToUtf8, bytesToUtf8, base64ToBytes, bytesToBase64, bytesToBase64url, utf8ToBytes, } from './encoding.js';
+export { BackgroundTransferError, gateErrorFromBody, IngotNameHeldError, IngotNotReadyError, isAuthError, isIngotNameHeldError, isIngotNotReadyError, isNetworkError, isNotFoundError, isRateLimitError, isReadOnlyVaultError, isRetryableDownloadError, isVatExpiredError, PlanRequiredError, vatRefusalReason, QuotaExceededError, SparkVaultAuthenticationError, SparkVaultAuthorizationError, SparkVaultMobileError, SparkVaultNetworkError, SparkVaultTimeoutError, SparkVaultValidationError, TusUploadError, } from './errors.js';
+export { VAT_REFUSAL_REASONS, endsVatSession } from './app-sdk/vat-refusal.js';
 export { isSafeId, sanitizeFilename, validateFolderId, validateIngotId, validateVaultId, } from './validation.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AASrB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAarB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAKrB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAUrB,OAAO,EACL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAMtB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAgBrB,OAAO,EACL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAItB,OAAO,EACL,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,aAAa,GACd,MAAM,UAAU,CAAC;AAOlB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,6BAA6B,EAC7B,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AAUrB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAcrB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAKrB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAUrB,OAAO,EACL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAMtB,OAAO,EACL,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAgBrB,OAAO,EACL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,aAAa,GACd,MAAM,UAAU,CAAC;AAOlB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,6BAA6B,EAC7B,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/E,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/ingots.d.ts

@@ -1,6 +1,23 @@
 import type { ResolvedMobileConfig } from './config.js';
 import type { MobileHttpClient } from './http.js';
-import type { DebugLogger, HashCheckResponse, Ingot, IngotAccessLog, IngotAccessStats, IngotInvite, IngotSharingConfig, ListIngotsResponse, IngotUploadSession, UploadAbortBehavior, UploadProgressCallback, UploadResult, UploadTransferPolicy, UploadTransport } from './types.js';
+import { type TusSessionProbe } from './tus.js';
+import type { DebugLogger, HashCheckResponse, Ingot, IngotAccessLog, IngotAccessStats, IngotInvite, IngotSharingConfig, ListIngotsResponse, FolderContentsResponse, IngotUploadSession, UploadAbortBehavior, UploadProgressCallback, UploadResult, UploadTransferPolicy, UploadTransport } from './types.js';
+/**
+ * What the server does when a create's name is already held in the target
+ * folder (case-insensitive). The server decides on the holder it read before
+ * writing anything, so a caller that must not replace content says so here:
+ * - `upsert` (the server default): the upload replaces the holder's content.
+ * - `complete_pending`: a holder whose own upload never finalized is completed
+ *   (`created: false`); a published holder is refused with
+ *   `IngotNameHeldError`, untouched.
+ * - `refuse`: any holder, its upload finished or not, is refused with
+ *   `IngotNameHeldError`, untouched; the create only ever mints.
+ * - `new_name`: the holder is never touched; the ingot is minted under the
+ *   first free numbered name the server picks ("report (2).pdf"), returned
+ *   as the result's `name`.
+ */
+export declare const NAME_CONFLICT_POLICIES: readonly ["upsert", "complete_pending", "refuse", "new_name"];
+export type NameConflictPolicy = (typeof NAME_CONFLICT_POLICIES)[number];
 export interface UploadOptions {
     vaultId: string;
     vat: string;
@@ -29,16 +46,22 @@ export interface UploadOptions {
 export interface UploadFromUriOptions extends UploadOptions {
     fileUri: string;
     fileSize: number;
+    /** What a name already held in the target folder does; omitted means the server's `upsert`. */
+    onNameConflict?: NameConflictPolicy;
     /**
-     * Invoked once the API has minted (or, via its same-name upsert, handed
-     * back) the ingot and before any Forge session exists. `created: false`
-     * means the bytes about to be sent will REPLACE an existing ingot's content
-     * once they finalize; a caller that must never overwrite throws here, and
-     * the throw propagates as-is with nothing sent and no session to clean up.
+     * Invoked once the server has placed the upload and before any Forge
+     * session exists: `created` is true when it minted the ingot and false when
+     * it staged the upload onto the row holding the name (as `onNameConflict`
+     * allowed), and `name` is the name the ingot is stored under (the server's
+     * numbered name under `new_name`). The placement has already been written
+     * by then, so this hook observes; a caller that must not replace content
+     * says so through `onNameConflict`. A throw here still stops the upload
+     * before a byte moves and propagates as-is.
      */
     onIngotCreated?: (ingot: {
         ingotId: string;
         created: boolean;
+        name: string;
     }) => void;
     /**
      * Invoked once the Forge tus session exists and before the first byte is
@@ -46,6 +69,12 @@ export interface UploadFromUriOptions extends UploadOptions {
      * attempt or a relaunch instead of re-sending bytes Forge already holds.
      */
     onSessionCreated?: (session: IngotUploadSession) => void;
+    /**
+     * Invoked whenever the session's expiry changes (see
+     * `TusUploadFromUriOptions.onSessionExpiry`): a caller that persists the
+     * session keeps its `expiresAt` current with it.
+     */
+    onSessionExpiry?: (expiresAt: number | null) => void;
     /** See `UploadTransport`; default `foreground`. */
     transport?: UploadTransport;
     /** Network policy for the OS transfer engine; see `UploadTransferPolicy`. Default: both allowed. */
@@ -62,7 +91,8 @@ export interface UploadFromUriOptions extends UploadOptions {
     abortBehavior?: UploadAbortBehavior;
     debug?: DebugLogger;
 }
-export interface ReplaceFromUriOptions extends UploadFromUriOptions {
+/** A replace addresses its ingot by id: no name is placed, so the create-only hooks do not apply. */
+export interface ReplaceFromUriOptions extends Omit<UploadFromUriOptions, 'onNameConflict' | 'onIngotCreated'> {
     ingotId: string;
 }
 export interface ResumeUploadOptions {
@@ -73,12 +103,18 @@ export interface ResumeUploadOptions {
     fileUri: string;
     fileSize: number;
     name: string;
-    contentType: string;
-    /** The persisted tus session handed to `onSessionCreated`. */
+    /**
+     * The persisted tus session handed to `onSessionCreated`, with the expiry
+     * the caller keeps for it (`onSessionExpiry`): a session past it is
+     * refused as `sessionLost` before any request.
+     */
     session: {
         uploadUrl: string;
         istk: string;
+        expiresAt?: number | null;
     };
+    /** See `UploadFromUriOptions.onSessionExpiry`. */
+    onSessionExpiry?: (expiresAt: number | null) => void;
     /** See `UploadTransport`; default `foreground`. */
     transport?: UploadTransport;
     /** Network policy for the OS transfer engine; see `UploadTransferPolicy`. Default: both allowed. */
@@ -135,16 +171,19 @@ export interface CreateUploadOptions {
     folderId?: string;
     /** Vault-keyed plaintext HMAC (43-char base64url); see UploadOptions.contentHmac. */
     contentHmac?: string;
+    /** What a name already held in the target folder does; omitted means the server's `upsert`. */
+    onNameConflict?: NameConflictPolicy;
 }
 export interface CreateUploadResult {
     ingotId: string;
     /** Forge tus endpoint plus upload-session token (ISTK) for the resumable upload. */
     forgeUrl: string;
+    /** The name the ingot is stored under: the server's numbered name under `new_name`. */
     name?: string;
     sizeBytes?: number;
     /**
-     * Whether the server minted this ingot (true) or handed back an existing
-     * row via its same-name upsert (false). Absent when the server did not say.
+     * Whether the server minted this ingot (true) or staged the upload onto
+     * the row already holding the name (false). Absent when the server did not say.
      */
     created?: boolean;
 }
@@ -177,8 +216,10 @@ export declare class MobileIngotsClient {
      * sent, then the ingot is verified active exactly as a fresh upload is.
      *
      * A `TusUploadError` with `sessionLost` means Forge no longer has the
-     * session (expired or terminated); the caller drops it and starts over
-     * with `uploadFromUri`.
+     * session (its expiry passed, or it was terminated); the caller drops it
+     * and starts over with `uploadFromUri`. A session `uploadUrl` that is not
+     * an upload session on an allowed transfer host is refused
+     * (SparkVaultValidationError) before the ISTK or a byte is sent anywhere.
      */
     resumeUpload(options: ResumeUploadOptions): Promise<UploadResult>;
     /**
@@ -186,21 +227,21 @@ export declare class MobileIngotsClient {
      * longer has it. Lets a caller reconcile sessions on relaunch — a session
      * at `offset === length` only needs its ingot verified, a lost one needs a
      * fresh `uploadFromUri` — without spending an upload slot to find out.
+     * An `uploadUrl` that is not an upload session on an allowed transfer host
+     * is refused (SparkVaultValidationError) before the ISTK is sent anywhere.
      */
     probeUploadSession(session: {
         uploadUrl: string;
         istk: string;
-    }): Promise<{
-        offset: number;
-        length: number;
-        chunkSize: number;
-    } | null>;
+    }): Promise<TusSessionProbe | null>;
     /**
      * Release a tus session the caller kept on Forge (`abortBehavior: 'keep'`)
      * and has since abandoned, so Forge drops the chunks it holds and settles
      * the partial transfer's billing instead of waiting for expiry. Resolves
      * once the session is gone, including when Forge no longer had it
      * (404/410); any other failure rejects so the caller can retry later.
+     * An `uploadUrl` that is not an upload session on an allowed transfer host
+     * is refused (SparkVaultValidationError) before the ISTK is sent anywhere.
      */
     terminateUploadSession(session: {
         uploadUrl: string;
@@ -224,14 +265,17 @@ export declare class MobileIngotsClient {
         limit?: number;
         cursor?: string;
     }): Promise<ListIngotsResponse>;
+    /**
+     * List a folder, or the vault root, whole: the folder, its breadcrumb, its
+     * direct subfolders and every ingot directly in it, in one response.
+     */
     listContents(vaultId: string, vat: string, options?: {
         folder_id?: string | null;
-        cursor?: string;
-        limit?: number;
+        /** Ingot sort field (name | size | content_type | created | access_count | bandwidth); `created` by default */
         sort_by?: string;
+        /** `desc` by default */
         sort_order?: 'asc' | 'desc';
-        type?: string;
-    }): Promise<ListIngotsResponse>;
+    }): Promise<FolderContentsResponse>;
     search(vaultId: string, vat: string, options?: {
         q?: string;
         file_type?: string;
@@ -271,19 +315,19 @@ export declare class MobileIngotsClient {
     getAccessStats(vaultId: string, ingotId: string, vat: string): Promise<IngotAccessStats>;
     purgeAccessLogs(vaultId: string, ingotId: string, vat: string): Promise<void>;
     /**
-     * Wait for a just-uploaded ingot to finish server-side finalization.
+     * Read a just-uploaded ingot until the server reports it `active`.
      *
-     * The bytes are already fully uploaded and the ingot record exists before
-     * this runs, so this NEVER re-creates or re-uploads anything - it only polls
-     * status. A `failed` status throws (a genuine server encryption error the
-     * caller should surface). A still-`processing` ingot after the poll budget
-     * is returned as success, not thrown: the transport completed and the ingot
-     * exists, so treating it as a failure would make the caller re-run the whole
-     * upload and mint a DUPLICATE ingot (re-streaming the entire file and
-     * double-billing storage). Finalization completes asynchronously server-side.
+     * The upload resolved on Forge's receipt (a 2xx to the PATCH at the final
+     * offset, which Forge answers only once the ingot is published), so a read
+     * that is not `active` yet is a read lagging that publication, which the
+     * poll waits out. It never re-creates or re-uploads anything. A row still
+     * not `active` past the poll budget is never reported as a success: it
+     * throws a `TusUploadError` whose `retryLater` is set (every byte is
+     * received, publication is unconfirmed), so the caller resumes the session
+     * it persisted later, which asks Forge for the receipt again and sends no
+     * bytes, rather than recording a backup the vault may not hold.
      */
     private verifyIngotActive;
-    private toAccessLog;
     private verifyDownloadedFile;
     private deleteFileIfPresent;
     private ensureNotAborted;
@@ -295,5 +339,6 @@ export declare class MobileIngotsClient {
      */
     private isAbortError;
     private delay;
+    /** Refuse a download link that is not a Forge decrypt URL on a trusted host (forge-url's rule). */
     private validateDownloadUrl;
 }