@sparkvault/sdk-mobile 1.0.5 → 3.0.0

package/dist/sparks.d.ts

@@ -1,4 +1,5 @@
 import type { MobileHttpClient } from './http.js';
+import type { ShareSparkResponse, SparkShareStatus, UnshareSparkResponse } from './types.js';
 export interface Spark {
     spark_id: string;
     status: string;
@@ -30,10 +31,30 @@ export interface CreateSparkOptions {
 export interface CreateSparkResponse {
     spark_id: string;
 }
+export interface ShareSparkOptions {
+    /** Link visibility. Defaults to public server-side. */
+    visibility?: 'public' | 'authenticated' | 'invite_only';
+    /** For invite_only visibility: identities granted access (server allows max 1). */
+    invites?: string[];
+    /** Link expiration TTL in seconds (server minimum 60, capped at the spark's own expiry). */
+    expiresInSeconds?: number;
+}
 export declare class MobileSparksClient {
     private readonly http;
     constructor(http: MobileHttpClient);
     list(options?: ListSparksOptions): Promise<ListSparksResponse>;
     get(sparkId: string): Promise<SparkResponse>;
     create(options: CreateSparkOptions): Promise<CreateSparkResponse>;
+    /** Burn a spark before its natural expiry. An already-burned spark resolves (the server returns 204); a missing spark rejects with a 404. */
+    delete(sparkId: string): Promise<void>;
+    /**
+     * Create (or return the existing) public SparkLink for a spark, yielding a
+     * shareable `https://x.sv/...` URL. Only active, non-expired sparks can be
+     * shared.
+     */
+    share(sparkId: string, options?: ShareSparkOptions): Promise<ShareSparkResponse>;
+    /** Current sharing status for a spark. `shared` is false when no SparkLink exists. */
+    getShare(sparkId: string): Promise<SparkShareStatus>;
+    /** Revoke a spark's SparkLink. Resolves whether or not a link existed. */
+    unshare(sparkId: string): Promise<UnshareSparkResponse>;
 }

package/dist/sparks.js

@@ -28,5 +28,35 @@ export class MobileSparksClient {
         });
         return response.data;
     }
+    /** Burn a spark before its natural expiry. An already-burned spark resolves (the server returns 204); a missing spark rejects with a 404. */
+    async delete(sparkId) {
+        await this.http.delete(`/sparks/${encodeURIComponent(sparkId)}`);
+    }
+    /**
+     * Create (or return the existing) public SparkLink for a spark, yielding a
+     * shareable `https://x.sv/...` URL. Only active, non-expired sparks can be
+     * shared.
+     */
+    async share(sparkId, options = {}) {
+        const body = {};
+        if (options.visibility)
+            body.visibility = options.visibility;
+        if (options.invites)
+            body.invites = options.invites;
+        if (options.expiresInSeconds !== undefined)
+            body.expires_in_seconds = options.expiresInSeconds;
+        const response = await this.http.patch(`/sparks/${encodeURIComponent(sparkId)}/share`, body);
+        return response.data;
+    }
+    /** Current sharing status for a spark. `shared` is false when no SparkLink exists. */
+    async getShare(sparkId) {
+        const response = await this.http.get(`/sparks/${encodeURIComponent(sparkId)}/share`);
+        return response.data;
+    }
+    /** Revoke a spark's SparkLink. Resolves whether or not a link existed. */
+    async unshare(sparkId) {
+        const response = await this.http.delete(`/sparks/${encodeURIComponent(sparkId)}/share`);
+        return response.data;
+    }
 }
 //# sourceMappingURL=sparks.js.map

package/dist/sparks.js.map

@@ -1 +1 @@
-{"version":3,"file":"sparks.js","sourceRoot":"","sources":["../src/sparks.ts"],"names":[],"mappings":"AAuCA,MAAM,OAAO,kBAAkB;IAG7B,YAAY,IAAsB;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAA6B,EAAE;QACxC,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,QAAQ;YAAE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/D,IAAI,OAAO,CAAC,KAAK;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9D,IAAI,OAAO,CAAC,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAEzD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAqB,KAAK,CAAC,CAAC,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACjG,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,OAAe;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAgB,WAAW,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9F,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAA2B;QACtC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAsB,SAAS,EAAE;YACpE,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,YAAY,EAAE,OAAO,CAAC,WAAW;YACjC,WAAW,EAAE,OAAO,CAAC,UAAU;YAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"sparks.js","sourceRoot":"","sources":["../src/sparks.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -201,12 +201,6 @@ export interface RequestPinResponse {
     retry_after?: number;
     is_signup: boolean;
 }
-export interface PinVerifyRequest {
-    kindling: string;
-    pin: string;
-    recipient: string;
-    organization_name?: string;
-}
 export interface PinVerifyLoginResponse {
     access_token: string;
     refresh_token: string;
@@ -221,9 +215,10 @@ export interface PinVerifySignupPendingResponse {
     expires_at: number;
 }
 /**
- * Returned by verifyPin when the PIN was correct but the account has 2FA
- * enabled: the caller must collect a second factor and call
- * completeSecondFactorPin({ ticket, code }) to finish the login.
+ * Variant of the Core exchange result indicating the account has 2FA enabled:
+ * the caller must collect a second factor via
+ * `products.identity.submitSecondFactor({ ticket, code })` and re-exchange the
+ * resulting Identity token via `account.exchangeIdentityToken`.
  */
 export interface PinVerifySecondFactorPendingResponse {
     verified: false;
@@ -403,7 +398,7 @@ export interface IngotSharingConfig {
 export interface IngotInvite {
     invite_id: string;
     identity: string;
-    identity_type: 'email';
+    identity_type: 'email' | 'phone';
     created_at: number;
 }
 export interface IngotAccessLog {
@@ -510,3 +505,37 @@ export interface DebugLogger {
 export interface UploadProgressCallback {
     (bytesUploaded: number, bytesTotal: number): void;
 }
+/** Result of sharing a spark — the created (or already-existing) SparkLink. */
+export interface ShareSparkResponse {
+    shared: true;
+    /** Public `https://x.sv/{code}` URL for the SparkLink. */
+    share_url: string;
+    link_code: string;
+    visibility: string;
+    invites?: string[];
+    expires_at?: number;
+    created_at?: number;
+    /** True when a SparkLink already existed and was returned as-is. */
+    already_shared?: boolean;
+}
+/** Sharing status for a spark. */
+export type SparkShareStatus = {
+    shared: false;
+    spark_id: string;
+} | {
+    shared: true;
+    spark_id: string;
+    share_url: string;
+    link_code: string;
+    visibility: string;
+    invites: string[];
+    max_uses?: number | null;
+    use_count: number;
+    expires_at?: number;
+    created_at?: number;
+};
+/** Result of unsharing a spark (deleting its SparkLink). */
+export interface UnshareSparkResponse {
+    shared: false;
+    message: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkvault/sdk-mobile",
-  "version": "1.0.5",
+  "version": "3.0.0",
   "description": "Mobile SDK for SparkVault Identity, vault, folder, and ingot workflows",
   "type": "module",
   "main": "./dist/index.js",

package/src/account.ts

@@ -0,0 +1,152 @@
+import type { ResolvedMobileConfig } from './config.js';
+import { SparkVaultValidationError } from './errors.js';
+import type { MobileHttpClient } from './http.js';
+import type {
+  CompleteSignupRequest,
+  CompleteSignupResponse,
+  IdentitySessionResponse,
+  PinVerifyResponse,
+  SparkVaultAccount,
+  SparkVaultUser,
+} from './types.js';
+
+/**
+ * First-party SparkVault Core session, profile, and account client. Exchanges a
+ * verified Identity token for an app session and owns the authenticated
+ * profile/account surface.
+ */
+export class MobileAccountClient {
+  private readonly config: ResolvedMobileConfig;
+  private readonly http: MobileHttpClient;
+
+  constructor(config: ResolvedMobileConfig, http: MobileHttpClient) {
+    this.config = config;
+    this.http = http;
+  }
+
+  async exchangeIdentityToken(identityToken: string): Promise<PinVerifyResponse> {
+    const sessionResponse = await this.http.post<IdentitySessionResponse>(
+      '/auth/identity/verify',
+      { token: identityToken },
+      { skipAuth: true }
+    );
+
+    const session = sessionResponse.data;
+    if (session.user) {
+      await this.storeSession(session);
+      return {
+        access_token: session.access_token,
+        refresh_token: session.refresh_token,
+        token_type: session.token_type ?? 'Bearer',
+        expires_in: session.expires_in ?? 3600,
+        user: session.user,
+      };
+    }
+
+    return {
+      verified: true,
+      needs_signup_info: true,
+      signup_token: session.access_token,
+      expires_at: Math.floor(Date.now() / 1000) + (session.expires_in ?? 3600),
+    };
+  }
+
+  async completeSignup(
+    signupToken: string,
+    request: CompleteSignupRequest
+  ): Promise<CompleteSignupResponse> {
+    const response = await this.http.post<CompleteSignupResponse>(
+      '/auth/complete-signup',
+      request,
+      {
+        skipAuth: true,
+        headers: { Authorization: `Bearer ${signupToken}` },
+      }
+    );
+
+    await this.storeSession(response.data);
+    return response.data;
+  }
+
+  async signup(params: {
+    signup_token: string;
+    organization_name: string;
+    full_name?: string;
+  }): Promise<CompleteSignupResponse> {
+    return this.completeSignup(params.signup_token, {
+      organization_name: params.organization_name,
+      full_name: params.full_name,
+    });
+  }
+
+  async getProfile(): Promise<SparkVaultUser> {
+    const response = await this.http.get<SparkVaultUser>('/profile');
+    if (this.config.tokenStorage.setUser) {
+      await this.config.tokenStorage.setUser(response.data);
+    }
+    return response.data;
+  }
+
+  async updateProfile(updates: { name?: string }): Promise<SparkVaultUser> {
+    const response = await this.http.put<SparkVaultUser>('/profile', updates);
+    if (this.config.tokenStorage.setUser) {
+      await this.config.tokenStorage.setUser(response.data);
+    }
+    return response.data;
+  }
+
+  async getAccount(): Promise<SparkVaultAccount> {
+    const response = await this.http.get<SparkVaultAccount>('/account');
+    if (this.config.tokenStorage.setAccount) {
+      await this.config.tokenStorage.setAccount(response.data);
+    }
+    return response.data;
+  }
+
+  async revokeRefreshToken(refreshToken?: string): Promise<void> {
+    const token = refreshToken ?? await this.config.tokenStorage.getRefreshToken();
+    if (!token) return;
+
+    await this.http.post('/auth/logout', { refresh_token: token }).catch(err => {
+      this.config.logger.warn('Logout API call failed', { error: String(err) });
+    });
+  }
+
+  async logout(options: { revoke?: boolean; clearTokens?: boolean } = {}): Promise<void> {
+    if (options.revoke !== false) {
+      await this.revokeRefreshToken();
+    }
+    if (options.clearTokens !== false) {
+      await this.config.tokenStorage.clearTokens();
+    }
+  }
+
+  private async storeSession(session: {
+    access_token: string;
+    refresh_token: string;
+    user?: SparkVaultUser | null;
+    account?: SparkVaultAccount | null;
+  }): Promise<void> {
+    if (!session.access_token || !session.refresh_token) {
+      throw new SparkVaultValidationError('Invalid session response from SparkVault');
+    }
+
+    if (this.config.tokenStorage.setTokens) {
+      await this.config.tokenStorage.setTokens(session.access_token, session.refresh_token);
+    } else {
+      await Promise.all([
+        this.config.tokenStorage.setAccessToken(session.access_token),
+        this.config.tokenStorage.setRefreshToken(session.refresh_token),
+      ]);
+    }
+
+    const writes: Promise<void>[] = [];
+    if (session.user && this.config.tokenStorage.setUser) {
+      writes.push(this.config.tokenStorage.setUser(session.user));
+    }
+    if (session.account && this.config.tokenStorage.setAccount) {
+      writes.push(this.config.tokenStorage.setAccount(session.account));
+    }
+    await Promise.all(writes);
+  }
+}

package/src/client.ts

@@ -1,4 +1,4 @@
-import { MobileAuthClient } from './auth.js';
+import { MobileAccountClient } from './account.js';
 import { MobileBillingClient } from './billing.js';
 import { resolveMobileConfig, type SparkVaultMobileConfig, type ResolvedMobileConfig } from './config.js';
 import { MobileEntropyClient } from './entropy.js';
@@ -6,13 +6,15 @@ import { MobileFoldersClient } from './folders.js';
 import { MobileHealthClient } from './health.js';
 import { MobileHttpClient, type AuthEventListener } from './http.js';
 import { MobileIngotsClient } from './ingots.js';
+import { MobileProductsClient } from './products/index.js';
 import { MobilePushTokensClient } from './push-tokens.js';
 import { MobileSparksClient } from './sparks.js';
 import { MobileVaultsClient } from './vaults.js';
 
 export class SparkVaultMobile {
   readonly config: ResolvedMobileConfig;
-  readonly auth: MobileAuthClient;
+  readonly products: MobileProductsClient;
+  readonly account: MobileAccountClient;
   readonly vaults: MobileVaultsClient;
   readonly ingots: MobileIngotsClient;
   readonly folders: MobileFoldersClient;
@@ -26,7 +28,8 @@ export class SparkVaultMobile {
   constructor(config: SparkVaultMobileConfig) {
     this.config = resolveMobileConfig(config);
     this.http = new MobileHttpClient(this.config);
-    this.auth = new MobileAuthClient(this.config, this.http);
+    this.products = new MobileProductsClient(this.config);
+    this.account = new MobileAccountClient(this.config, this.http);
     this.vaults = new MobileVaultsClient(this.http);
     this.ingots = new MobileIngotsClient(this.config, this.http);
     this.folders = new MobileFoldersClient(this.http);
@@ -37,7 +40,7 @@ export class SparkVaultMobile {
     this.billing = new MobileBillingClient(this.http);
 
     if (this.config.preloadIdentityConfig) {
-      this.auth.preloadConfig();
+      this.products.identity.preloadConfig();
     }
   }
 

package/src/identity-dialog.tsx

@@ -111,7 +111,7 @@ export function SparkVaultIdentityDialog({
     setIdentity(initialIdentity ?? '');
     setIdentityType(initialIdentityType ?? 'email');
 
-    client.auth.getConfig()
+    client.products.identity.getConfig()
       .then((nextConfig) => {
         if (cancelled || !isActiveSession(sessionRef, sessionId)) return;
         setConfig(nextConfig);
@@ -156,7 +156,7 @@ export function SparkVaultIdentityDialog({
   }, [expiresAt, step]);
 
   const finishWithToken = useCallback(async (result: IdentityVerifyResult, sessionId: number) => {
-    const jwks = await client.auth.getJwks();
+    const jwks = await client.products.identity.getJwks();
     if (!isActiveSession(sessionRef, sessionId)) return;
     await onSuccessRef.current({ ...result, jwks });
   }, [client]);
@@ -186,7 +186,7 @@ export function SparkVaultIdentityDialog({
     setError('');
     setSelectedMethod(method);
     try {
-      const response = await client.auth.sendTotp({
+      const response = await client.products.identity.sendTotp({
         identity: targetIdentity,
         identityType: targetIdentityType,
         method: totpMethod,
@@ -225,7 +225,7 @@ export function SparkVaultIdentityDialog({
       }
       if (!isActiveSession(sessionRef, sessionId)) return;
 
-      const challenge = await client.auth.getPasskeyAuthOptions();
+      const challenge = await client.products.identity.getPasskeyAuthOptions();
       if (!isActiveSession(sessionRef, sessionId)) return;
       const credential = await passkeyProvider.authenticate(challenge.options);
       if (!isActiveSession(sessionRef, sessionId)) return;
@@ -233,7 +233,7 @@ export function SparkVaultIdentityDialog({
         throw new Error('Passkey authentication was cancelled.');
       }
 
-      const result = await client.auth.completePasskeyAuthentication(credential, challenge.session);
+      const result = await client.products.identity.completePasskeyAuthentication(credential, challenge.session);
       await finishWithToken(result, sessionId);
     } catch (err) {
       if (!isActiveSession(sessionRef, sessionId)) return;
@@ -304,7 +304,7 @@ export function SparkVaultIdentityDialog({
     setIsBusy(true);
     setError('');
     try {
-      const result = await client.auth.verifyTotp({
+      const result = await client.products.identity.verifyTotp({
         kindling,
         pin,
         recipient: identity,
@@ -341,7 +341,7 @@ export function SparkVaultIdentityDialog({
     setError('');
     setStep('loading');
 
-    client.auth.getConfig()
+    client.products.identity.getConfig()
       .then((nextConfig) => {
         if (!isActiveSession(sessionRef, sessionId)) return;
         setConfig(nextConfig);

package/src/index.ts

@@ -11,8 +11,12 @@ export type {
   AuthEventListener,
 } from './http.js';
 export {
-  MobileAuthClient,
-} from './auth.js';
+  MobileProductsClient,
+  MobileIdentityClient,
+} from './products/index.js';
+export {
+  MobileAccountClient,
+} from './account.js';
 export {
   MobileVaultsClient,
 } from './vaults.js';
@@ -28,6 +32,10 @@ export type {
   UploadOptions,
   UploadFromUriOptions,
   ReplaceFromUriOptions,
+  CreateUploadOptions,
+  CreateUploadResult,
+  CreateDownloadLinkOptions,
+  CreateDownloadLinkResult,
 } from './ingots.js';
 export {
   MobileHealthClient,
@@ -44,6 +52,7 @@ export type {
   CreateSparkResponse,
   ListSparksOptions,
   ListSparksResponse,
+  ShareSparkOptions,
   Spark,
   SparkResponse,
 } from './sparks.js';

package/src/ingots.ts

@@ -65,6 +65,49 @@ export interface DownloadToFileResult {
   sizeBytes: number;
 }
 
+export interface AddInviteOptions {
+  /** Invite lifetime in seconds. Omit to inherit the link's existing expiry. */
+  expiresInSeconds?: number;
+}
+
+export interface CreateUploadOptions {
+  vaultId: string;
+  vat: string;
+  name: string;
+  contentType: string;
+  sizeBytes: number;
+  /**
+   * Slash-delimited folder path within the vault (e.g. "Accounts/001xx").
+   * Missing path segments are find-or-created. Omitted means the vault root.
+   */
+  folder?: string;
+  /**
+   * Existing folder id to upload into (e.g. "fld_xxx"). Use when the target
+   * folder is already known by id; mutually exclusive with `folder` (path).
+   * Omitted means the vault root.
+   */
+  folderId?: string;
+}
+
+export interface CreateUploadResult {
+  ingotId: string;
+  /** Forge tus endpoint plus upload-session token (ISTK) for the resumable upload. */
+  forgeUrl: string;
+  name?: string;
+  sizeBytes?: number;
+}
+
+export interface CreateDownloadLinkOptions {
+  vaultId: string;
+  ingotId: string;
+  vat: string;
+}
+
+export interface CreateDownloadLinkResult {
+  /** Short-lived signed download URL, validated against the allowed-host policy. */
+  downloadUrl: string;
+}
+
 interface IngotUploadInitResponse {
   ingot_id: string;
   forge_url: string;
@@ -120,7 +163,7 @@ export class MobileIngotsClient {
       throw new SparkVaultMobileError('Upload cancelled', { code: 'upload_cancelled' });
     }
 
-    const init = await this.createIngotUpload({
+    const init = await this.createUpload({
       vaultId: options.vaultId,
       vat: options.vat,
       name: options.name,
@@ -135,22 +178,59 @@ export class MobileIngotsClient {
       fileSize: options.fileSize,
       filename: options.name,
       contentType: options.contentType,
-      forgeUrl: init.forge_url,
+      forgeUrl: init.forgeUrl,
       onProgress: options.onProgress,
       abortSignal: options.abortSignal,
       debug: options.debug,
     });
 
-    await this.verifyIngotActive(options.vaultId, init.ingot_id, options.vat);
+    await this.verifyIngotActive(options.vaultId, init.ingotId, options.vat);
 
     return {
-      ingot_id: init.ingot_id,
+      ingot_id: init.ingotId,
       name: init.name ?? options.name,
-      size_bytes: init.size_bytes ?? options.fileSize,
+      size_bytes: init.sizeBytes ?? options.fileSize,
       storage_location: 's3',
     };
   }
 
+  /**
+   * Initialize an ingot record and obtain the Forge resumable-upload endpoint
+   * (with its upload-session token). The canonical first step of every upload;
+   * `uploadFromUri` calls this before streaming bytes via tus.
+   */
+  async createUpload(options: CreateUploadOptions): Promise<CreateUploadResult> {
+    validateVaultId(options.vaultId);
+    const body: Record<string, unknown> = {
+      name: options.name,
+      content_type: options.contentType,
+      size_bytes: options.sizeBytes,
+    };
+    // folder_path (find-or-create) and folder_id (existing folder) are
+    // mutually exclusive server-side; a path takes precedence when both given.
+    if (options.folder) {
+      body.folder_path = options.folder;
+    } else if (options.folderId) {
+      body.folder_id = options.folderId;
+    }
+    const response = await this.http.post<IngotUploadInitResponse>(
+      `/vaults/${options.vaultId}/ingots`,
+      body,
+      { vat: options.vat }
+    );
+
+    if (!response.data.ingot_id || !response.data.forge_url) {
+      throw new SparkVaultMobileError('Server returned invalid response for ingot creation');
+    }
+
+    return {
+      ingotId: response.data.ingot_id,
+      forgeUrl: response.data.forge_url,
+      name: response.data.name,
+      sizeBytes: response.data.size_bytes,
+    };
+  }
+
   async replaceFromUri(options: ReplaceFromUriOptions): Promise<UploadResult> {
     const { vaultId, ingotId, vat, name, contentType, fileUri, fileSize, onProgress, abortSignal, debug } = options;
     validateVaultId(vaultId);
@@ -289,11 +369,14 @@ export class MobileIngotsClient {
     await this.http.delete(`/vaults/${vaultId}/ingots/${ingotId}`, { vat });
   }
 
-  private async getDownloadUrl(
-    vaultId: string,
-    ingotId: string,
-    vat: string
-  ): Promise<string> {
+  /**
+   * Mint a fresh signed download URL for an ingot, validated against the
+   * allowed-host policy. The canonical first step of every download;
+   * `downloadToFile` calls this once per attempt because signed URLs are
+   * short-lived.
+   */
+  async createDownloadLink(options: CreateDownloadLinkOptions): Promise<CreateDownloadLinkResult> {
+    const { vaultId, ingotId, vat } = options;
     validateVaultId(vaultId);
     validateIngotId(ingotId);
 
@@ -309,7 +392,7 @@ export class MobileIngotsClient {
     }
 
     this.validateDownloadUrl(downloadUrl);
-    return downloadUrl;
+    return { downloadUrl };
   }
 
   async downloadToFile(options: DownloadToFileOptions): Promise<DownloadToFileResult> {
@@ -343,7 +426,7 @@ export class MobileIngotsClient {
       try {
         // Fresh signed URL on every attempt — server URLs are short-lived,
         // and retrying with a stale URL would just fail again.
-        const downloadUrl = await this.getDownloadUrl(vaultId, ingotId, vat);
+        const { downloadUrl } = await this.createDownloadLink({ vaultId, ingotId, vat });
         const result = await fileDownloader.download(downloadUrl, fileUri, {
           timeoutMs: options.timeoutMs ?? this.config.fileTransferTimeoutMs,
           abortSignal,
@@ -424,13 +507,13 @@ export class MobileIngotsClient {
     ingotId: string,
     vat: string,
     identity: string,
-    identityType: 'email' = 'email'
+    options: AddInviteOptions = {}
   ): Promise<IngotInvite> {
     validateVaultId(vaultId);
     validateIngotId(ingotId);
     const response = await this.http.post<IngotInvite>(
       `/vaults/${vaultId}/ingots/${ingotId}/sharing/invite`,
-      { identity, identity_type: identityType },
+      { identity, expires_in_seconds: options.expiresInSeconds },
       { vat }
     );
     return response.data;
@@ -487,40 +570,6 @@ export class MobileIngotsClient {
     );
   }
 
-  private async createIngotUpload(options: {
-    vaultId: string;
-    vat: string;
-    name: string;
-    contentType: string;
-    sizeBytes: number;
-    folder?: string;
-    folderId?: string;
-  }): Promise<IngotUploadInitResponse> {
-    const body: Record<string, unknown> = {
-      name: options.name,
-      content_type: options.contentType,
-      size_bytes: options.sizeBytes,
-    };
-    // folder_path (find-or-create) and folder_id (existing folder) are
-    // mutually exclusive server-side; a path takes precedence when both given.
-    if (options.folder) {
-      body.folder_path = options.folder;
-    } else if (options.folderId) {
-      body.folder_id = options.folderId;
-    }
-    const response = await this.http.post<IngotUploadInitResponse>(
-      `/vaults/${options.vaultId}/ingots`,
-      body,
-      { vat: options.vat }
-    );
-
-    if (!response.data.ingot_id || !response.data.forge_url) {
-      throw new SparkVaultMobileError('Server returned invalid response for ingot creation');
-    }
-
-    return response.data;
-  }
-
   private async verifyIngotActive(vaultId: string, ingotId: string, vat: string): Promise<Ingot> {
     let ingot: Ingot | null = null;