@sparkvault/sdk-mobile 1.0.2 → 1.0.4

package/src/index.ts

@@ -65,7 +65,7 @@ export {
   MobileBillingClient,
 } from './billing.js';
 export type {
-  BillingBalance,
+  PortalSession,
 } from './billing.js';
 export {
   MobileTusUploader,
@@ -85,6 +85,9 @@ export {
   utf8ToBytes,
 } from './encoding.js';
 export {
+  gateErrorFromBody,
+  PlanRequiredError,
+  QuotaExceededError,
   SparkVaultAuthenticationError,
   SparkVaultAuthorizationError,
   SparkVaultMobileError,

package/src/tus.ts

@@ -1,7 +1,12 @@
 import type { ResolvedMobileConfig } from './config.js';
 import { base64EncodeUtf8, base64ToBytes } from './encoding.js';
-import { SparkVaultValidationError, TusUploadError } from './errors.js';
-import type { DebugLogger, MobileFileReader, UploadProgressCallback } from './types.js';
+import {
+  gateErrorFromBody,
+  SparkVaultMobileError,
+  SparkVaultValidationError,
+  TusUploadError,
+} from './errors.js';
+import type { ApiErrorBody, DebugLogger, MobileFileReader, UploadProgressCallback } from './types.js';
 
 export interface ParsedForgeUrl {
   baseUrl: string;
@@ -47,6 +52,21 @@ export function parseForgeUrl(forgeUrl: string): ParsedForgeUrl {
   };
 }
 
+/**
+ * Parse a Forge error response body (JSON text) into the shared ApiErrorBody
+ * shape so gate mapping can read its `error.code` / `error.details.resource`.
+ * Returns an empty body on non-JSON text, which simply matches no gate.
+ */
+function parseErrorBody(text: string): ApiErrorBody {
+  if (!text) return {};
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return parsed && typeof parsed === 'object' ? (parsed as ApiErrorBody) : {};
+  } catch {
+    return {};
+  }
+}
+
 function getErrorName(err: unknown): string {
   return err instanceof Error ? err.name : 'UnknownError';
 }
@@ -119,6 +139,15 @@ async function createTusUpload(
 
   if (!response.ok) {
     const errorText = await response.text().catch(() => '');
+
+    // A 402 here is a billable gate hit mid-create (e.g. storage/bandwidth pool
+    // exhausted). Route it through the same typed-gate mapping as the JSON HTTP
+    // path so callers handle subscribe / add-on UX off one set of error types.
+    const gateError = gateErrorFromBody(response.status, parseErrorBody(errorText));
+    if (gateError) {
+      throw gateError;
+    }
+
     throw new TusUploadError(`TUS create failed: ${response.status} - ${errorText}`, {
       httpStatus: response.status,
       filename,
@@ -191,6 +220,11 @@ function uploadChunk(
         const newOffset = offsetHeader ? parseInt(offsetHeader, 10) : offset + chunkSize;
         finish(() => resolve(newOffset));
       } else {
+        const gateError = gateErrorFromBody(xhr.status, parseErrorBody(xhr.responseText));
+        if (gateError) {
+          finish(() => reject(gateError));
+          return;
+        }
         finish(() => reject(new TusUploadError(`Chunk upload failed: ${xhr.status} - ${xhr.responseText.substring(0, 200)}`, {
           httpStatus: xhr.status,
           phase: 'upload',
@@ -287,6 +321,10 @@ export class MobileTusUploader {
       }
 
       if (err instanceof TusUploadError) throw err;
+      // Typed gate errors (PlanRequiredError / QuotaExceededError) must reach
+      // the caller intact so the subscribe / add-on UX fires; never bury them
+      // in a generic TusUploadError.
+      if (err instanceof SparkVaultMobileError) throw err;
       throw TusUploadError.fromError(error, {
         filename: options.filename,
         fileSize: options.fileSize,

package/src/types.ts

@@ -1,9 +1,31 @@
+/** Utilization state shared by storage, bandwidth, and Identity pools. */
+export type PoolState = 'ok' | 'notice' | 'warning' | 'exhausted';
+
+/** Live usage for a single capacity pool. `limit_gb` is null on unlimited plans. */
+export interface PoolStatus {
+  used_gb: number;
+  limit_gb: number | null;
+  pct: number;
+  state: PoolState;
+}
+
+/** Bandwidth pool additionally reports when the metered cycle resets. */
+export interface BandwidthPoolStatus extends PoolStatus {
+  cycle_resets_at: number | null;
+}
+
+/** Storage + bandwidth pool snapshot; rides responses on `meta.pools`. */
+export interface SubscriptionPools {
+  storage: PoolStatus;
+  bandwidth: BandwidthPoolStatus;
+}
+
 export interface ApiMeta {
   request_id: string;
   response_ms: number;
   timestamp: number;
   api_version: string;
-  balance?: string;
+  pools?: SubscriptionPools;
   quota?: {
     limit: number;
     used: number;
@@ -48,12 +70,49 @@ export interface SparkVaultAccount {
   organization_name: string;
   email: string;
   status: 'active' | 'suspended';
-  balance: string;
   logo_url?: string;
   logo_dark_url?: string;
   created_at: number;
 }
 
+/** Identity attempts usage against the purchased tier cap. */
+export interface SubscriptionIdentityStatus {
+  attempts_cap: number | null;
+  attempts_used: number;
+  soft_cap: number | null;
+  state: PoolState;
+}
+
+/**
+ * GET /v1/billing/subscription — the account's current plan, licensed vs. used
+ * seats, capacity blocks, live pool usage, and Identity attempts. Drives the
+ * subscription / usage view. `renewal_amount_usd` is a formatted dollars string;
+ * `renewal_date` is an epoch (seconds) or null when there is no active plan.
+ */
+export interface SparkVaultSubscription {
+  plan: 'subscription' | 'internal' | 'unsubscribed';
+  unlimited: boolean;
+  subscription_status: string | null;
+  past_due: boolean;
+  renewal_date: number | null;
+  renewal_amount_usd: string;
+  seats: {
+    full: number;
+    viewer: number;
+    licensed: number;
+    used: number;
+  };
+  blocks: {
+    storage: number;
+    bandwidth: number;
+  };
+  pools: SubscriptionPools;
+  identity: SubscriptionIdentityStatus;
+}
+
+/** Native in-app purchase store channel for receipt validation. */
+export type IapPlatform = 'ios' | 'android';
+
 export type IdentityType = 'email' | 'phone';
 export type VerifiedIdentityType = IdentityType | 'social';
 
@@ -118,6 +177,17 @@ export interface IdentityTokenClaims {
   method: string;
 }
 
+/**
+ * A server-decided post-login nudge. Computed once per login (default mode);
+ * clients act on the steps they support, in order.
+ */
+export type Recommendation =
+  | { type: 'passkey' }
+  | { type: 'backup_identifier'; missingType: 'email' | 'phone' };
+
+/** Canonical dismiss key for a recommendation (suppresses it server-side 30d). */
+export type RecommendationKey = 'passkey' | 'backup_email' | 'backup_phone';
+
 export interface IdentityVerifyResult {
   token: string;
   identity: string;
@@ -126,6 +196,27 @@ export interface IdentityVerifyResult {
   redirect?: string;
   jwksUri: string;
   jwks?: IdentityJwks;
+  /** Ordered post-login nudges (default-mode logins only). */
+  recommendations?: Recommendation[];
+}
+
+/** Response to POST /backup-verification/send. */
+export interface BackupSendResponse {
+  /** Opaque pending-attach session id (present when a code was sent). */
+  session_id?: string;
+  /** Delivery channel actually used. */
+  method?: 'email' | 'sms' | 'voice';
+  /** Code expiry (Unix seconds). */
+  expires_at?: number;
+  /** True when the identifier is already on the identity — no code was sent. */
+  already_verified?: boolean;
+}
+
+/** Response to POST /backup-verification/verify. */
+export interface BackupVerifyResponse {
+  verified: boolean;
+  type: 'email' | 'phone';
+  value: string;
 }
 
 export interface SendTotpRequest {