@sparkvault/sdk-mobile 6.0.2 → 7.0.1

package/src/types.ts

@@ -5,7 +5,9 @@ export type PoolState = 'ok' | 'notice' | 'warning' | 'exhausted';
 export interface PoolStatus {
   used_gb: number;
   limit_gb: number | null;
+  /** Used fraction of the pool: 0.85 is 85% full, 1 is full (above 1 when over). */
   pct: number;
+  /** The server's severity for the pool, from the canonical thresholds; display keys off it. */
   state: PoolState;
 }
 
@@ -137,6 +139,12 @@ export interface RemoveMemberResponse {
   user_id: string;
   removed_at: number;
   dvaks_revoked: number;
+  /**
+   * True when this removal ends the subscription: the member renewed the last
+   * license it renews, and it was not already set to end. It ends at the
+   * period end.
+   */
+  wind_down: boolean;
 }
 
 export interface ResendInviteResponse {
@@ -177,7 +185,7 @@ export interface SparkVaultSubscription {
   renewal_date: number | null;
   renewal_amount_usd: string;
   seats: {
-    /** Cycle-unique billed counts (flex billing: what the renewal invoices). */
+    /** Licenses the subscription renews with — what the next renewal bills. */
     full: number;
     viewer: number;
     licensed: number;
@@ -187,6 +195,18 @@ export interface SparkVaultSubscription {
     assigned_viewer: number;
     /** Roster members with no license (no access until licensed; free). */
     unlicensed_members: number;
+    /** Licenses paid for the current billing period (a removed license stays
+     *  paid until the renewal). */
+    paid: { full: number; viewer: number };
+    /** Paid licenses nobody holds — assignable at no charge until the renewal. */
+    available: { full: number; viewer: number };
+    /**
+     * Licenses are prepaid per period on a web subscription: a removed one
+     * stays paid until the renewal, free to give to someone else until then.
+     * False on a store subscription (its one license lands on a member by
+     * itself) and on an account with no web subscription.
+     */
+    prepaid: boolean;
   };
   blocks: {
     /** Effective capacity blocks (this subscription plus any add-on rail). */
@@ -204,6 +224,21 @@ export interface SparkVaultSubscription {
 /** Native in-app purchase store channel for receipt validation. */
 export type IapPlatform = 'ios' | 'android';
 
+/** The store rail a validated purchase is billed on. */
+export type IapChannel = 'appstore' | 'play';
+
+/**
+ * POST /v1/billing/iap/validate — whether Core provisioned the purchase: a
+ * provisioning status, not a subscription (read the subscription again with
+ * `billing.getSubscription()` to show what changed). A purchase the store
+ * reports as not entitling (expired, refunded, revoked or not yet paid) is
+ * answered, not refused, and provisions nothing; every other refusal is an
+ * error. `addon` marks a capacity add-on stacked on the license.
+ */
+export type IapValidation =
+  | { provisioned: true; channel: IapChannel; addon?: true }
+  | { provisioned: false; reason: 'not_entitling' };
+
 export type IdentityType = 'email' | 'phone';
 export type VerifiedIdentityType = IdentityType | 'social';
 
@@ -542,9 +577,104 @@ export interface UnsealVaultResponse {
   ttl_seconds: number;
 }
 
+/** One page of GET /v1/vaults. */
 export interface ListVaultsResponse {
   vaults: Vault[];
-  total: number;
+  count: number;
+  has_more: boolean;
+  next_cursor?: string;
+}
+
+/** A vault's public sharing policy (GET /v1/vaults/{id}/sharing). */
+export interface VaultSharingConfig {
+  vault_id: string;
+  public_sharing_enabled: boolean;
+  all_ingots_public: boolean;
+  session_length_seconds: number | null;
+  enabled_at: number | null;
+}
+
+/** The sharing policy a caller sets when enabling or updating vault sharing. */
+export interface VaultSharingOptions {
+  all_ingots_public?: boolean;
+  session_length_seconds?: number;
+}
+
+export interface EnableVaultSharingResponse {
+  vault_id: string;
+  public_sharing_enabled: boolean;
+  all_ingots_public: boolean;
+  session_length_seconds: number;
+  enabled_at: number;
+}
+
+export interface DisableVaultSharingResponse {
+  vault_id: string;
+  public_sharing_enabled: false;
+  disabled_at: number;
+  shares_revoked: number;
+}
+
+export interface UpdateVaultSharingResponse {
+  vault_id: string;
+  public_sharing_enabled: boolean;
+  all_ingots_public: boolean;
+  session_length_seconds: number;
+  updated_at: number;
+}
+
+/** How long a vault keeps its access log (GET /v1/vaults/{id}/access-log-retention). */
+export interface AccessLogRetention {
+  vault_id: string;
+  access_log_retention_seconds: number;
+}
+
+export interface UpdateAccessLogRetentionResponse extends AccessLogRetention {
+  updated_at: number;
+}
+
+/** A vault's upload portal and widget settings (GET /v1/vaults/{id}/upload). */
+export interface UploadConfig {
+  vault_id: string;
+  upload_portal_enabled: boolean;
+  upload_portal_enabled_at: number | null;
+  upload_widget_enabled: boolean;
+  upload_widget_enabled_at: number | null;
+  max_size_bytes: number | null;
+  notification_email: string | null;
+  portal_url?: string;
+}
+
+export interface UploadPortalEnabled {
+  vault_id: string;
+  upload_portal_enabled: true;
+  enabled_at: number;
+  portal_url: string;
+}
+
+export interface UploadWidgetEnabled {
+  vault_id: string;
+  upload_widget_enabled: true;
+  enabled_at: number;
+}
+
+export interface UploadPortalDisabled {
+  vault_id: string;
+  upload_portal_enabled: false;
+  disabled_at: number;
+}
+
+export interface UploadWidgetDisabled {
+  vault_id: string;
+  upload_widget_enabled: false;
+  disabled_at: number;
+}
+
+export interface UploadConfigUpdate {
+  vault_id: string;
+  max_size_bytes: number;
+  notification_email: string | null;
+  updated_at: number;
 }
 
 export interface Ingot {
@@ -553,7 +683,8 @@ export interface Ingot {
   content_type: string;
   size_bytes: number;
   storage_location: 'dynamodb' | 's3';
-  status?: 'uploading' | 'encrypting' | 'active' | 'failed';
+  /** `uploading` until Forge activates the upload, then `active`. */
+  status?: 'uploading' | 'active';
   folder_id?: string | null;
   created_at: number;
   accessed_at?: number;
@@ -586,24 +717,36 @@ export interface ListIngotsResponse {
   next_cursor?: string;
 }
 
+/**
+ * GET /vaults/:id/contents: one folder whole, in one response — the folder
+ * (null at the vault root), the trail from the root to it, its direct
+ * subfolders (pinned first) and every ingot directly in it.
+ */
+export interface FolderContentsResponse {
+  folder: { folder_id: string; name: string; parent_id: string | null } | null;
+  breadcrumb: Array<{ folder_id: string | null; name: string }>;
+  folders: Folder[];
+  ingots: Ingot[];
+}
+
 export interface UploadResult {
   ingot_id: string;
   name: string;
   size_bytes: number;
   storage_location: 's3';
   /**
-   * Whether this upload minted the ingot (true) or was handed an existing row
-   * by the server's same-name upsert / a resumed session (false). A caller
-   * that discards its ingot on a failure path needs this to tell "mine to
-   * discard" from "someone else's live row".
+   * Whether this upload minted the ingot (true) or went into an existing row
+   * (false): the one holding the name, as the create's name-conflict policy
+   * allowed, a replace, or a resumed session. A caller that discards its
+   * ingot on a failure path needs this to tell "mine to discard" from
+   * "someone else's live row".
    */
   created?: boolean;
   /**
-   * The ingot status the upload last observed: `active` when the server
-   * confirmed activation. Anything else means the transfer completed but the
-   * activation poll budget ran out first - the ingot usually activates
-   * moments later, but a caller recording "backed up" must not take that on
-   * faith (resume the session later; Forge re-confirms finalization).
+   * The ingot status the upload confirmed: `active`, the server's read of
+   * the published ingot. An upload whose activation the poll budget could
+   * not confirm never resolves: it rejects with a `TusUploadError` whose
+   * `retryLater` is set.
    */
   status?: Ingot['status'];
 }
@@ -623,9 +766,19 @@ export interface IngotInvite {
   created_at: number;
 }
 
+/**
+ * An ingot access-log entry: a download that delivered the file, a SparkLink
+ * open of it included. The server records an access as the download that
+ * delivered it, so `download` is the one action.
+ */
 export interface IngotAccessLog {
+  /**
+   * The entry's time (Unix seconds) as a string. The server issues no entry id,
+   * so entries in the same second share it.
+   */
   log_id: string;
-  action: 'download' | 'view';
+  action: 'download';
+  /** Who accessed: a member's email, an API key's name, or a SparkLink visitor's identity */
   identity: string;
   ip_address: string;
   user_agent: string;
@@ -638,18 +791,14 @@ export interface IngotAccessStats {
   last_accessed_at?: number;
 }
 
+/** A folder as every folder route answers it (Core's FolderRepository.toPublicFormat). */
 export interface Folder {
   folder_id: string;
-  vault_id: string;
   name: string;
   parent_id: string | null;
-  is_system: boolean;
   pinned: boolean;
   created_at: number;
   updated_at?: number;
-  path?: string;
-  depth?: number;
-  ingot_count?: number;
 }
 
 export interface CreateFolderRequest {
@@ -663,9 +812,9 @@ export interface UpdateFolderRequest {
   pinned?: boolean;
 }
 
+/** GET /v1/vaults/{id}/folders: the vault's whole folder list. */
 export interface ListFoldersResponse {
   folders: Folder[];
-  total: number;
 }
 
 export interface FolderBreadcrumbItem {
@@ -716,14 +865,23 @@ export interface MobileFileReader {
 
 /**
  * A tus upload session as Forge created it: the session URL, the per-upload
- * token every request on it must carry, and the chunk geometry Forge fixed
- * for it. Persist it to resume the upload after a failed attempt or a
- * relaunch (`ingots.resumeUpload`) instead of re-sending bytes Forge holds.
+ * token every request on it must carry, the chunk geometry Forge fixed for
+ * it, and when it lapses. Persist it to resume the upload after a failed
+ * attempt or a relaunch (`ingots.resumeUpload`) instead of re-sending bytes
+ * Forge holds.
  */
 export interface TusSessionInfo {
   uploadUrl: string;
   istk: string;
   chunkSize: number;
+  /**
+   * When the session lapses (epoch ms, Forge's `Upload-Expires`), or null
+   * when Forge named no expiry. Forge slides it forward on every committed
+   * chunk, so a caller that persists the session keeps this current through
+   * the upload's `onSessionExpiry`; past it, Forge refuses every request to
+   * the session (`isSessionExpired`).
+   */
+  expiresAt: number | null;
 }
 
 /**
@@ -919,7 +1077,7 @@ export type SparkShareStatus =
       link_code: string;
       visibility: string;
       invites: string[];
-      /** Single-use lifecycle: 'active' → 'consumed' (opened once) | 'revoked'. */
+      /** Single-use lifecycle: 'active' → 'consumed' (opened once). */
       status: string;
       expires_at?: number;
       created_at?: number;

package/src/users.ts

@@ -7,15 +7,17 @@ import type {
   RemoveMemberResponse,
   ResendInviteResponse,
 } from './types.js';
+import { apiPath } from './request-path.js';
+import { validateResourceId } from './validation.js';
 
 /**
  * Organization team client (member admins only — the API gates these on the
  * admin role and returns 403 otherwise).
  *
- * Licensing is a billing action (flex: nothing charges mid-cycle — the renewal
- * bills each cycle's unique license holders), so the only seat-affecting
- * operation exposed here is `invite`, which defaults new members to
- * `unlicensed` and never charges. Assigning or changing a paid license is
+ * Licensing is a billing action (licenses are prepaid: assigning or upgrading
+ * one charges the rest of the current billing period at once), so the only
+ * seat-affecting operation exposed here is `invite`, which defaults new members
+ * to `unlicensed` and never charges. Assigning or changing a paid license is
  * intentionally absent — clients route that to the web dashboard so native
  * apps never initiate an out-of-band purchase.
  */
@@ -28,33 +30,41 @@ export class MobileUsersClient {
 
   /** List organization members (active and invited), with optional search/filter. */
   async list(options: ListMembersOptions = {}): Promise<ListMembersResponse> {
-    const params = new URLSearchParams();
-    if (options.search) params.set('search', options.search);
-    if (options.status) params.set('status', options.status);
-    if (typeof options.limit === 'number') params.set('limit', String(options.limit));
-    if (options.cursor) params.set('cursor', options.cursor);
-    const query = params.toString();
-    const response = await this.http.get<ListMembersResponse>(
-      query ? `/users?${query}` : '/users'
-    );
+    const response = await this.http.get<ListMembersResponse>(apiPath`/users`, {
+      query: {
+        search: options.search,
+        status: options.status,
+        limit: typeof options.limit === 'number' ? options.limit : undefined,
+        cursor: options.cursor,
+      },
+    });
     return response.data;
   }
 
   /** Invite a coworker by email. Defaults to an unlicensed seat (no charge). */
   async invite(request: InviteMemberRequest): Promise<InviteMemberResponse> {
-    const response = await this.http.post<InviteMemberResponse>('/users/invite', request);
+    const response = await this.http.post<InviteMemberResponse>(apiPath`/users/invite`, request);
     return response.data;
   }
 
-  /** Remove a member and revoke their DVAKs. Access ends immediately; the current cycle still bills them, and they stop counting next cycle. */
+  /**
+   * Remove a member and revoke their DVAKs. Access ends immediately. A license
+   * they held stays paid until the end of the billing period — nothing is
+   * refunded — and is not renewed; until then it can be given to someone else
+   * at no charge. `wind_down` is true when this removal ends the
+   * subscription — theirs was the last license it renews, and it was not
+   * already set to end: it ends at the period end.
+   */
   async remove(userId: string): Promise<RemoveMemberResponse> {
-    const response = await this.http.delete<RemoveMemberResponse>(`/users/${userId}`);
+    validateResourceId(userId, 'user ID', 'userId');
+    const response = await this.http.delete<RemoveMemberResponse>(apiPath`/users/${userId}`);
     return response.data;
   }
 
   /** Resend a pending invitation email (resets the 7-day expiry). */
   async resendInvite(userId: string): Promise<ResendInviteResponse> {
-    const response = await this.http.post<ResendInviteResponse>(`/users/${userId}/resend-invite`);
+    validateResourceId(userId, 'user ID', 'userId');
+    const response = await this.http.post<ResendInviteResponse>(apiPath`/users/${userId}/resend-invite`);
     return response.data;
   }
 }

package/src/validation.ts

@@ -1,28 +1,32 @@
+import { isResourceId } from './app-sdk/ids.js';
 import { SparkVaultValidationError } from './errors.js';
+import { SAVED_FILENAME_FALLBACK, toStorableFilename } from './app-sdk/filename.js';
 
-export function isSafeId(id: string): boolean {
-  if (!id || typeof id !== 'string') return false;
-  if (id.includes('/') || id.includes('\\') || id.includes('..') || id.includes('\0')) return false;
-  if (id.length < 8 || id.length > 128) return false;
-  return /^[a-zA-Z0-9_-]+$/.test(id);
+/** Whether a value is a well-formed SparkVault resource id (the platform's one rule). */
+export { isResourceId as isSafeId };
+
+/**
+ * Refuse a value that is not a SparkVault resource id before it names a route.
+ *
+ * @param label - How the message names the id, e.g. 'spark ID'.
+ * @param field - The argument's name, reported in the error details.
+ */
+export function validateResourceId(value: unknown, label: string, field: string): void {
+  if (!isResourceId(value)) {
+    throw new SparkVaultValidationError(`Invalid ${label} format`, { [field]: value });
+  }
 }
 
 export function validateVaultId(vaultId: string): void {
-  if (!isSafeId(vaultId)) {
-    throw new SparkVaultValidationError('Invalid vault ID format', { vaultId });
-  }
+  validateResourceId(vaultId, 'vault ID', 'vaultId');
 }
 
 export function validateIngotId(ingotId: string): void {
-  if (!isSafeId(ingotId)) {
-    throw new SparkVaultValidationError('Invalid ingot ID format', { ingotId });
-  }
+  validateResourceId(ingotId, 'ingot ID', 'ingotId');
 }
 
 export function validateFolderId(folderId: string): void {
-  if (!folderId || typeof folderId !== 'string' || !folderId.startsWith('fld_') || !isSafeId(folderId)) {
-    throw new SparkVaultValidationError('Invalid folder ID format', { folderId });
-  }
+  validateResourceId(folderId, 'folder ID', 'folderId');
 }
 
 /** Windows reserved filenames that cannot be used. */
@@ -33,17 +37,19 @@ const WINDOWS_RESERVED_NAMES = new Set([
 ]);
 
 /**
- * Sanitize a filename to prevent path traversal and other security issues:
- * removes null bytes and control characters, strips path traversal sequences,
- * replaces directory separators, strips leading dots (hidden files), and
- * prefixes Windows reserved names. Falls back to 'file' when nothing remains.
+ * The file name to store or save text under, by the platform's one file-name
+ * rule (@sparkvault/app-sdk/filename, mirrored into ./app-sdk/filename.js):
+ * path separators, control characters and the bidi controls that disguise an
+ * extension (`invoice<U+202E>fdp.exe` shows as `invoiceexe.pdf`) become `_`,
+ * and so do the characters SparkVault refuses in a name (: * ? " < > |), so a
+ * name derived from a note's title uploads. With every separator gone no name
+ * can climb a directory, so a `..` inside a name is kept. On top of the rule,
+ * for the device's file system: leading dots are stripped (a hidden file) and
+ * Windows reserved names are prefixed. Falls back to the platform's one
+ * fallback name (SAVED_FILENAME_FALLBACK) when nothing remains.
  */
 export function sanitizeFilename(filename: string): string {
-  let sanitized = filename
-    .replace(/\0/g, '')
-    .replace(/[\x00-\x1f\x7f]/g, '')
-    .replace(/\.\./g, '')
-    .replace(/[\/\\]/g, '_')
+  let sanitized = toStorableFilename(filename)
     .replace(/^\.+/, '')
     .trim();
 
@@ -52,5 +58,5 @@ export function sanitizeFilename(filename: string): string {
     sanitized = `_${sanitized}`;
   }
 
-  return sanitized || 'file';
+  return sanitized || SAVED_FILENAME_FALLBACK;
 }

package/src/vaults.test-d.ts

@@ -0,0 +1,29 @@
+/**
+ * Vault and folder wire-contract assertions — COMPILE-TIME ONLY.
+ *
+ * These types have no runtime, so a unit test can never catch them drifting from
+ * the server: the transpiler strips them and every assertion passes. `tsc
+ * --noEmit` (`pnpm typecheck`) is the gate instead. It is deliberately NOT a
+ * `*.test.ts`, which tsconfig excludes.
+ *
+ * Mirrored server sources: apps/api/src/folders/list.js (listFolders answers
+ * `{ folders }`, the whole list and nothing else) and apps/api/src/vaults/list.js
+ * (one page: `{ vaults, count, has_more, next_cursor? }`).
+ */
+
+import type { ListFoldersResponse, ListVaultsResponse } from './types.js';
+
+/** Fails to compile unless `T` resolves to exactly `true`. */
+type Assert<T extends true> = T;
+
+/** Invariant type equality: the SAME type, not merely mutually assignable. */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+  ? true
+  : false;
+
+export type VaultsWireContract = [
+  // A folder listing carries the folders and nothing else: a `total` the server
+  // never sends would read as undefined wherever a caller trusted it.
+  Assert<Equals<keyof ListFoldersResponse, 'folders'>>,
+  Assert<Equals<keyof ListVaultsResponse, 'vaults' | 'count' | 'has_more' | 'next_cursor'>>,
+];