native-update 1.3.0 → 1.3.2

package/dist/esm/firestore/schema.d.ts

@@ -0,0 +1,504 @@
+/**
+ * Firestore Schema Types
+ *
+ * These interfaces define the structure of all Firestore documents
+ * used by the native-update plugin for the free backend architecture.
+ *
+ * Collections:
+ * - manifests/{appId}_{channel} - Update manifests (1 read per update check)
+ * - apps/{appId} - App registry (admin only)
+ * - builds/{buildId} - Build archive (admin only)
+ * - deltas/{appId}_{fromVersion}_{toVersion} - Delta patch registry
+ * - analytics_batch/{batchId} - Batched analytics
+ */
+/**
+ * Firestore Timestamp type (compatible with Firebase SDK)
+ */
+export interface FirestoreTimestamp {
+    seconds: number;
+    nanoseconds: number;
+}
+/**
+ * Convert FirestoreTimestamp to JavaScript Date
+ */
+export declare function timestampToDate(timestamp: FirestoreTimestamp): Date;
+/**
+ * Convert JavaScript Date to FirestoreTimestamp
+ */
+export declare function dateToTimestamp(date: Date): FirestoreTimestamp;
+/**
+ * Manifest Document - The ONLY document clients read for update checks
+ *
+ * Collection: manifests/{appId}_{channel}
+ * Example ID: "com.myapp.app_production"
+ *
+ * Design: Single document per app+channel to minimize Firestore reads
+ */
+export interface ManifestDocument {
+    /** App identifier (e.g., "com.myapp.app") */
+    appId: string;
+    /** Update channel */
+    channel: 'production' | 'staging' | 'development';
+    /** Current version information */
+    current: ManifestCurrentVersion;
+    /** Available delta patches from previous versions */
+    deltas: Record<string, ManifestDelta>;
+    /** Staged rollout configuration */
+    rollout: RolloutConfig;
+    /** Previous versions for rollback */
+    previousVersions: ManifestPreviousVersion[];
+    /** Last update timestamp */
+    updatedAt: FirestoreTimestamp;
+    /** User who last updated */
+    updatedBy: string;
+}
+/**
+ * Current version info in manifest
+ */
+export interface ManifestCurrentVersion {
+    /** Semantic version (e.g., "1.2.0") */
+    version: string;
+    /** Unique bundle identifier */
+    bundleId: string;
+    /** Google Drive direct download URL */
+    bundleUrl: string;
+    /** Google Drive URL for file manifest JSON */
+    manifestUrl: string;
+    /** SHA-256 checksum of the full bundle */
+    checksum: string;
+    /** Optional RSA-PSS signature (base64) */
+    signature?: string;
+    /** Bundle size in bytes */
+    size: number;
+    /** Release notes for this version */
+    releaseNotes: string;
+    /** Release date */
+    releaseDate: FirestoreTimestamp;
+    /** Force all users to update */
+    mandatory: boolean;
+    /** Minimum native app version required */
+    minNativeVersion: string;
+}
+/**
+ * Delta patch info for a specific source version
+ */
+export interface ManifestDelta {
+    /** Google Drive URL for delta patch file */
+    patchUrl: string;
+    /** Size of the patch file in bytes */
+    patchSize: number;
+    /** SHA-256 checksum of the patch file */
+    patchChecksum: string;
+    /** SHA-256 checksum of the result after applying patch */
+    targetChecksum: string;
+}
+/**
+ * Previous version info for rollback
+ */
+export interface ManifestPreviousVersion {
+    /** Version string */
+    version: string;
+    /** Google Drive download URL */
+    bundleUrl: string;
+    /** SHA-256 checksum */
+    checksum: string;
+    /** Bundle size in bytes */
+    size: number;
+}
+/**
+ * Staged rollout configuration
+ */
+export interface RolloutConfig {
+    /** Whether rollout is enabled */
+    enabled: boolean;
+    /** Current rollout percentage (0-100) */
+    percentage: number;
+    /** When the rollout started */
+    startTime: FirestoreTimestamp;
+    /** When the rollout ends (null = indefinite) */
+    endTime: FirestoreTimestamp | null;
+    /** Target user segments */
+    targetSegments?: RolloutTargetSegments;
+    /** Rollout schedule configuration */
+    schedule?: RolloutSchedule;
+}
+/**
+ * Target segments for rollout
+ */
+export interface RolloutTargetSegments {
+    /** Target platforms */
+    platforms?: ('ios' | 'android' | 'web')[];
+    /** Minimum app version to receive update */
+    minAppVersion?: string;
+    /** Maximum app version to receive update */
+    maxAppVersion?: string;
+    /** Specific device IDs to target */
+    deviceIds?: string[];
+    /** ISO country codes to target */
+    regions?: string[];
+}
+/**
+ * Rollout schedule configuration
+ */
+export interface RolloutSchedule {
+    /** Schedule type */
+    type: 'immediate' | 'gradual' | 'scheduled';
+    /** Percentage steps for gradual rollout (e.g., [10, 25, 50, 100]) */
+    gradualSteps?: number[];
+    /** Hours between gradual steps */
+    gradualInterval?: number;
+    /** Scheduled start time (for scheduled type) */
+    scheduledTime?: FirestoreTimestamp;
+}
+/**
+ * App Document - App registry for admin dashboard
+ *
+ * Collection: apps/{appId}
+ */
+export interface AppDocument {
+    /** App ID (document ID) */
+    id: string;
+    /** Owner user ID */
+    userId: string;
+    /** App display name */
+    name: string;
+    /** Package identifier (e.g., "com.example.app") */
+    packageId: string;
+    /** App icon URL (Google Drive or data URL) */
+    icon: string | null;
+    /** App description */
+    description: string;
+    /** Supported platforms */
+    platforms: ('ios' | 'android' | 'web')[];
+    /** Channel configurations */
+    channels: {
+        production: ChannelConfig;
+        staging: ChannelConfig;
+        development: ChannelConfig;
+    };
+    /** Google Drive folder structure */
+    driveFolders: {
+        rootFolderId: string;
+        productionFolderId: string;
+        stagingFolderId: string;
+        developmentFolderId: string;
+    };
+    /** Aggregated statistics */
+    stats: {
+        totalBuilds: number;
+        activeUsers: number;
+        downloadsThisMonth: number;
+        lastBuildDate: FirestoreTimestamp | null;
+    };
+    /** Public key for bundle verification (base64) */
+    publicKey?: string;
+    /** Creation timestamp */
+    createdAt: FirestoreTimestamp;
+    /** Last update timestamp */
+    updatedAt: FirestoreTimestamp;
+}
+/**
+ * Channel configuration
+ */
+export interface ChannelConfig {
+    /** Whether channel is enabled */
+    enabled: boolean;
+    /** Enable automatic updates */
+    autoUpdate: boolean;
+    /** Update strategy */
+    updateStrategy: 'immediate' | 'background' | 'manual';
+    /** Require user consent before update */
+    requireUserConsent: boolean;
+    /** Minimum native version for this channel */
+    minNativeVersion: string | null;
+    /** Enable automatic rollback on errors */
+    autoRollbackEnabled: boolean;
+    /** Error percentage threshold to trigger rollback */
+    rollbackThreshold: number;
+}
+/**
+ * Build Document - Complete build history
+ *
+ * Collection: builds/{buildId}
+ */
+export interface BuildDocument {
+    /** Build ID (document ID) */
+    id: string;
+    /** Owner user ID */
+    userId: string;
+    /** App ID this build belongs to */
+    appId: string;
+    /** Semantic version */
+    version: string;
+    /** Build number (auto-incremented) */
+    buildNumber: number;
+    /** Update channel */
+    channel: 'production' | 'staging' | 'development';
+    /** Target platform */
+    platform: 'ios' | 'android' | 'web' | 'universal';
+    /** Original file name */
+    fileName: string;
+    /** File size in bytes */
+    fileSize: number;
+    /** MIME type */
+    mimeType: string;
+    /** SHA-256 checksum */
+    checksum: string;
+    /** RSA-PSS signature (base64) */
+    signature: string | null;
+    /** Google Drive file ID */
+    driveFileId: string;
+    /** Google Drive direct download URL */
+    driveFileUrl: string;
+    /** Google Drive folder ID */
+    driveFolderId: string;
+    /** File manifest for delta calculation */
+    fileManifest: FileManifestEntry[];
+    /** Google Drive ID of manifest JSON file */
+    manifestDriveId: string;
+    /** Release notes */
+    releaseNotes: string;
+    /** Release type */
+    releaseType: 'major' | 'minor' | 'patch' | 'hotfix';
+    /** Pre-release flag */
+    isPreRelease: boolean;
+    /** Minimum native app version */
+    minNativeVersion: string;
+    /** Upload timestamp */
+    uploadedAt: FirestoreTimestamp;
+    /** User who uploaded */
+    uploadedBy: string;
+    /** Upload duration in milliseconds */
+    uploadDuration: number;
+    /** Build status */
+    status: 'uploading' | 'processing' | 'active' | 'archived' | 'failed';
+    /** Processing steps status */
+    processingSteps: {
+        uploaded: boolean;
+        manifestGenerated: boolean;
+        deltasGenerated: boolean;
+        published: boolean;
+    };
+    /** Analytics (updated periodically) */
+    analytics: {
+        downloads: number;
+        installs: number;
+        rollbacks: number;
+        errors: number;
+        lastDownload: FirestoreTimestamp | null;
+    };
+    /** Last update timestamp */
+    updatedAt: FirestoreTimestamp;
+}
+/**
+ * File manifest entry for delta calculation
+ */
+export interface FileManifestEntry {
+    /** Relative path within bundle */
+    path: string;
+    /** SHA-256 checksum of file content */
+    checksum: string;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * Delta Document - Pre-computed delta patches
+ *
+ * Collection: deltas/{appId}_{fromVersion}_{toVersion}
+ * Example ID: "com.myapp.app_1.0.0_1.1.0"
+ */
+export interface DeltaDocument {
+    /** App ID */
+    appId: string;
+    /** Source version */
+    fromVersion: string;
+    /** Target version */
+    toVersion: string;
+    /** Channel */
+    channel: 'production' | 'staging' | 'development';
+    /** Google Drive file ID for patch */
+    patchDriveId: string;
+    /** Google Drive download URL */
+    patchUrl: string;
+    /** Patch file size in bytes */
+    patchSize: number;
+    /** SHA-256 checksum of patch file */
+    patchChecksum: string;
+    /** SHA-256 checksum of source bundle */
+    sourceChecksum: string;
+    /** SHA-256 checksum after applying patch */
+    targetChecksum: string;
+    /** Generation timestamp */
+    generatedAt: FirestoreTimestamp;
+    /** Generation duration in milliseconds */
+    generationDuration: number;
+    /** Diff algorithm used */
+    algorithm: 'bsdiff' | 'vcdiff';
+    /** Compression ratio (patchSize / fullSize) */
+    compressionRatio: number;
+    /** Delta status */
+    status: 'generating' | 'ready' | 'failed';
+}
+/**
+ * Analytics Batch Document - Batched analytics events
+ *
+ * Collection: analytics_batch/{batchId}
+ *
+ * Design: Clients batch events locally and write in bulk
+ * to minimize Firestore write operations
+ */
+export interface AnalyticsBatchDocument {
+    /** App ID */
+    appId: string;
+    /** Channel */
+    channel: 'production' | 'staging' | 'development';
+    /** Batch window start */
+    windowStart: FirestoreTimestamp;
+    /** Batch window end */
+    windowEnd: FirestoreTimestamp;
+    /** Aggregated event counts */
+    events: {
+        updateChecks: number;
+        downloads: number;
+        installs: number;
+        rollbacks: number;
+        errors: number;
+    };
+    /** Per-version statistics */
+    versionStats: Record<string, {
+        downloads: number;
+        installs: number;
+        errors: number;
+    }>;
+    /** Per-platform statistics */
+    platformStats: {
+        ios: {
+            downloads: number;
+            installs: number;
+        };
+        android: {
+            downloads: number;
+            installs: number;
+        };
+        web: {
+            downloads: number;
+            installs: number;
+        };
+    };
+    /** Sampled error details */
+    errorSamples: ErrorSample[];
+    /** Creation timestamp */
+    createdAt: FirestoreTimestamp;
+}
+/**
+ * Sampled error for analytics
+ */
+export interface ErrorSample {
+    /** Error code */
+    code: string;
+    /** Error message */
+    message: string;
+    /** Occurrence count */
+    count: number;
+    /** Last occurrence time */
+    lastOccurrence: FirestoreTimestamp;
+}
+/**
+ * Device information used for rollout eligibility checks
+ */
+export interface DeviceInfo {
+    /** Unique device identifier */
+    deviceId: string;
+    /** Device platform */
+    platform: 'ios' | 'android' | 'web';
+    /** Native app version */
+    appVersion: string;
+    /** Current bundle version */
+    bundleVersion: string;
+    /** OS version */
+    osVersion: string;
+    /** ISO region/country code */
+    region?: string;
+    /** Device locale */
+    locale: string;
+}
+/**
+ * Response from update check (parsed from ManifestDocument)
+ */
+export interface UpdateCheckResponse {
+    /** Whether an update is available */
+    updateAvailable: boolean;
+    /** Latest version info */
+    version?: string;
+    /** Bundle download URL */
+    bundleUrl?: string;
+    /** Minimum native app version required */
+    minNativeVersion?: string;
+    /** Release notes */
+    releaseNotes?: string;
+    /** Bundle signature */
+    signature?: string;
+    /** Bundle checksum */
+    checksum?: string;
+    /** Whether update is mandatory */
+    mandatory?: boolean;
+    /** Bundle size in bytes */
+    size?: number;
+    /** Delta patch info if available */
+    delta?: {
+        available: boolean;
+        patchUrl?: string;
+        patchSize?: number;
+        patchChecksum?: string;
+        targetChecksum?: string;
+    };
+    /** Rollout eligibility */
+    rolloutEligible?: boolean;
+    /** Reason if not eligible */
+    rolloutReason?: string;
+}
+/**
+ * Firestore configuration for the plugin
+ */
+export interface FirestoreConfig {
+    /** Firebase project ID */
+    projectId: string;
+    /** Firestore database ID (default: "(default)") */
+    databaseId?: string;
+    /** App ID for update checks */
+    appId: string;
+    /** Update channel */
+    channel: 'production' | 'staging' | 'development';
+    /** Cache duration for manifests in milliseconds (default: 5 minutes) */
+    cacheDuration?: number;
+    /** Enable offline persistence */
+    enableOffline?: boolean;
+}
+/**
+ * Firestore collection paths
+ */
+export declare const COLLECTIONS: {
+    readonly MANIFESTS: "manifests";
+    readonly APPS: "apps";
+    readonly BUILDS: "builds";
+    readonly DELTAS: "deltas";
+    readonly ANALYTICS_BATCH: "analytics_batch";
+    readonly DRIVE_TOKENS: "drive_tokens";
+    readonly USERS: "users";
+};
+/**
+ * Generate manifest document ID
+ */
+export declare function getManifestId(appId: string, channel: string): string;
+/**
+ * Generate delta document ID
+ */
+export declare function getDeltaId(appId: string, fromVersion: string, toVersion: string): string;
+/**
+ * Validate semantic version format
+ */
+export declare function isValidVersion(version: string): boolean;
+/**
+ * Validate SHA-256 checksum format
+ */
+export declare function isValidChecksum(checksum: string): boolean;

package/dist/esm/firestore/schema.js

@@ -0,0 +1,69 @@
+/**
+ * Firestore Schema Types
+ *
+ * These interfaces define the structure of all Firestore documents
+ * used by the native-update plugin for the free backend architecture.
+ *
+ * Collections:
+ * - manifests/{appId}_{channel} - Update manifests (1 read per update check)
+ * - apps/{appId} - App registry (admin only)
+ * - builds/{buildId} - Build archive (admin only)
+ * - deltas/{appId}_{fromVersion}_{toVersion} - Delta patch registry
+ * - analytics_batch/{batchId} - Batched analytics
+ */
+/**
+ * Convert FirestoreTimestamp to JavaScript Date
+ */
+export function timestampToDate(timestamp) {
+    return new Date(timestamp.seconds * 1000 + timestamp.nanoseconds / 1000000);
+}
+/**
+ * Convert JavaScript Date to FirestoreTimestamp
+ */
+export function dateToTimestamp(date) {
+    const ms = date.getTime();
+    return {
+        seconds: Math.floor(ms / 1000),
+        nanoseconds: (ms % 1000) * 1000000,
+    };
+}
+// ============================================
+// COLLECTION HELPERS
+// ============================================
+/**
+ * Firestore collection paths
+ */
+export const COLLECTIONS = {
+    MANIFESTS: 'manifests',
+    APPS: 'apps',
+    BUILDS: 'builds',
+    DELTAS: 'deltas',
+    ANALYTICS_BATCH: 'analytics_batch',
+    DRIVE_TOKENS: 'drive_tokens',
+    USERS: 'users',
+};
+/**
+ * Generate manifest document ID
+ */
+export function getManifestId(appId, channel) {
+    return `${appId}_${channel}`;
+}
+/**
+ * Generate delta document ID
+ */
+export function getDeltaId(appId, fromVersion, toVersion) {
+    return `${appId}_${fromVersion}_${toVersion}`;
+}
+/**
+ * Validate semantic version format
+ */
+export function isValidVersion(version) {
+    return /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?$/.test(version);
+}
+/**
+ * Validate SHA-256 checksum format
+ */
+export function isValidChecksum(checksum) {
+    return /^[a-f0-9]{64}$/i.test(checksum);
+}
+//# sourceMappingURL=schema.js.map

package/dist/esm/firestore/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/firestore/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,SAA6B;IAC3D,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,WAAW,GAAG,OAAO,CAAC,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAU;IACxC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAC1B,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC;QAC9B,WAAW,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO;KACnC,CAAC;AACJ,CAAC;AAknBD,+CAA+C;AAC/C,qBAAqB;AACrB,+CAA+C;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,eAAe,EAAE,iBAAiB;IAClC,YAAY,EAAE,cAAc;IAC5B,KAAK,EAAE,OAAO;CACN,CAAC;AAEX;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,OAAe;IAEf,OAAO,GAAG,KAAK,IAAI,OAAO,EAAE,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,KAAa,EACb,WAAmB,EACnB,SAAiB;IAEjB,OAAO,GAAG,KAAK,IAAI,WAAW,IAAI,SAAS,EAAE,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,kCAAkC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC1C,CAAC"}

package/dist/esm/live-update/delta-processor.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Delta Processor
+ *
+ * Handles delta/patch-based updates for reduced download sizes.
+ * Uses a simple file-level patching strategy that works in JavaScript.
+ *
+ * For production, a WASM-based bsdiff/bspatch implementation can be added
+ * for better performance on binary files.
+ */
+import type { UpdateCheckResponse } from '../firestore/schema';
+/**
+ * Delta patch information
+ */
+export interface DeltaPatchInfo {
+    /** Whether delta is available for current version */
+    available: boolean;
+    /** Patch download URL */
+    patchUrl?: string;
+    /** Patch size in bytes */
+    patchSize?: number;
+    /** Checksum of the patch file */
+    patchChecksum?: string;
+    /** Expected checksum after applying patch */
+    targetChecksum?: string;
+}
+/**
+ * Delta download result
+ */
+export interface DeltaDownloadResult {
+    /** Whether delta was used */
+    usedDelta: boolean;
+    /** The final bundle data */
+    bundleData: ArrayBuffer;
+    /** Checksum of the bundle */
+    checksum: string;
+    /** Download size (delta or full) */
+    downloadSize: number;
+    /** Time taken in milliseconds */
+    duration: number;
+}
+/**
+ * Delta processor for applying patch updates
+ */
+export declare class DeltaProcessor {
+    private readonly logger;
+    private readonly configManager;
+    constructor();
+    /**
+     * Download update with delta support
+     * Falls back to full download if delta fails
+     */
+    downloadWithDelta(updateInfo: UpdateCheckResponse, currentBundleData: ArrayBuffer | null, onProgress?: (percent: number) => void): Promise<DeltaDownloadResult>;
+    /**
+     * Download a delta patch file
+     */
+    private downloadPatch;
+    /**
+     * Download full bundle
+     */
+    private downloadFull;
+    /**
+     * Apply a delta patch to create new bundle
+     *
+     * This is a simplified patch format using JSON metadata + file-level changes.
+     * For production binary patching, a WASM bspatch implementation would be used.
+     */
+    private applyPatch;
+    /**
+     * Apply file-level patch (JSON format)
+     */
+    private applyFileLevelPatch;
+    /**
+     * Apply binary patch (bsdiff format)
+     *
+     * NOTE: This is a placeholder. For production, use WASM-compiled bspatch.
+     */
+    private applyBinaryPatch;
+    /**
+     * Calculate SHA-256 checksum
+     */
+    calculateChecksum(data: ArrayBuffer): Promise<string>;
+    /**
+     * Verify checksum matches
+     */
+    verifyChecksum(data: ArrayBuffer, expectedChecksum: string): Promise<boolean>;
+    /**
+     * Check if delta updates are enabled
+     */
+    isDeltaEnabled(): boolean;
+}
+/**
+ * Create delta processor instance
+ */
+export declare function createDeltaProcessor(): DeltaProcessor;