@almadar/server 1.0.13 → 1.0.14

package/dist/stores/index.d.ts

@@ -0,0 +1,167 @@
+import { OrbitalSchema, SnapshotDocument, SaveOptions, SaveResult, AppSummary, StatsView, ChangeSetDocument, ValidationResults, CategorizedRemovals, PageContentReduction } from '@almadar/core';
+
+/**
+ * Firestore Serialization Utilities
+ *
+ * Handles the Firestore 20-level depth limit by serializing deeply nested
+ * OrbitalSchema fields (orbitals, traits, services) to JSON strings.
+ */
+
+/**
+ * Convert OrbitalSchema to Firestore-safe format.
+ *
+ * Serializes orbitals, traits, and services to JSON strings to avoid
+ * Firestore's 20-level nesting limit.
+ */
+declare function toFirestoreFormat(schema: OrbitalSchema): Record<string, unknown>;
+/**
+ * Convert Firestore document back to OrbitalSchema.
+ *
+ * Deserializes JSON strings back to arrays.
+ */
+declare function fromFirestoreFormat(data: Record<string, unknown>): OrbitalSchema;
+
+/**
+ * SnapshotStore - Firestore CRUD for schema snapshots
+ *
+ * Snapshots are full copies of the schema at a point in time,
+ * stored in subcollection: users/{uid}/apps/{appId}/snapshots/{snapshotId}
+ */
+
+declare class SnapshotStore {
+    private appsCollection;
+    constructor(appsCollection?: string);
+    private getCollectionPath;
+    private getAppDocPath;
+    /** Create a snapshot of the current schema */
+    create(uid: string, appId: string, schema: OrbitalSchema, reason: string): Promise<string>;
+    /** Get all snapshots for an app (ordered by timestamp desc) */
+    getAll(uid: string, appId: string): Promise<SnapshotDocument[]>;
+    /** Get a specific snapshot by ID */
+    get(uid: string, appId: string, snapshotId: string): Promise<SnapshotDocument | null>;
+    /** Delete a snapshot */
+    delete(uid: string, appId: string, snapshotId: string): Promise<boolean>;
+    /** Get schema snapshot at a specific version */
+    getByVersion(uid: string, appId: string, version: number): Promise<OrbitalSchema | null>;
+    /** Get the schema from a snapshot (deserialized) */
+    getSchemaFromSnapshot(snapshot: SnapshotDocument): OrbitalSchema;
+}
+
+/**
+ * SchemaStore - Firestore CRUD for OrbitalSchema documents
+ *
+ * Handles schema get/save/create/delete/list with caching
+ * and Firestore serialization.
+ */
+
+declare class SchemaStore {
+    private appsCollection;
+    private schemaCache;
+    private listCache;
+    private protectionService;
+    private snapshotStore;
+    constructor(appsCollection?: string);
+    /** Set snapshot store for auto-snapshot on destructive saves */
+    setSnapshotStore(store: SnapshotStore): void;
+    /** Get a schema by app ID */
+    get(uid: string, appId: string): Promise<OrbitalSchema | null>;
+    /**
+     * Save a schema (create or full replace).
+     *
+     * Features:
+     * - Detects destructive changes (removals)
+     * - Requires confirmation for critical removals
+     * - Auto-creates snapshots before destructive changes (if SnapshotStore attached)
+     */
+    save(uid: string, appId: string, schema: OrbitalSchema, options?: SaveOptions): Promise<SaveResult>;
+    /** Create a new app with initial schema */
+    create(uid: string, metadata: {
+        name: string;
+        description?: string;
+    }): Promise<{
+        appId: string;
+        schema: OrbitalSchema;
+    }>;
+    /** Delete an app */
+    delete(uid: string, appId: string): Promise<boolean>;
+    /** List all apps for a user */
+    list(uid: string): Promise<AppSummary[]>;
+    /** Compute stats from OrbitalSchema */
+    computeStats(schema: OrbitalSchema): StatsView;
+    /** Invalidate caches for a specific app */
+    invalidateCache(uid: string, appId: string): void;
+    /** Clear all caches */
+    clearCaches(): void;
+    /** Get the collection path for an app */
+    getAppDocPath(uid: string, appId: string): string;
+    /** Expose apps collection name for subcollection stores */
+    getAppsCollection(): string;
+}
+
+/**
+ * ChangeSetStore - Firestore CRUD for schema changesets
+ *
+ * Changesets track changes made to the schema over time,
+ * stored in subcollection: users/{uid}/apps/{appId}/changesets/{changeSetId}
+ */
+
+declare class ChangeSetStore {
+    private appsCollection;
+    constructor(appsCollection?: string);
+    private getCollectionPath;
+    private getAppDocPath;
+    /** Append a changeset to history */
+    append(uid: string, appId: string, changeSet: ChangeSetDocument): Promise<void>;
+    /** Get change history for an app (ordered by version desc) */
+    getHistory(uid: string, appId: string): Promise<ChangeSetDocument[]>;
+    /** Get a specific changeset by ID */
+    get(uid: string, appId: string, changeSetId: string): Promise<ChangeSetDocument | null>;
+    /** Update a changeset's status */
+    updateStatus(uid: string, appId: string, changeSetId: string, status: 'applied' | 'reverted' | 'pending'): Promise<void>;
+    /** Delete a changeset */
+    delete(uid: string, appId: string, changeSetId: string): Promise<boolean>;
+}
+
+/**
+ * ValidationStore - Firestore CRUD for validation results
+ *
+ * Validation results stored at: users/{uid}/apps/{appId}/validation/current
+ */
+
+declare class ValidationStore {
+    private appsCollection;
+    constructor(appsCollection?: string);
+    private getDocPath;
+    private getAppDocPath;
+    /** Save validation results */
+    save(uid: string, appId: string, results: ValidationResults): Promise<void>;
+    /** Get validation results */
+    get(uid: string, appId: string): Promise<ValidationResults | null>;
+    /** Clear validation results */
+    clear(uid: string, appId: string): Promise<void>;
+}
+
+/**
+ * SchemaProtectionService - Detects destructive schema changes
+ *
+ * Uses real diff functions from @almadar/core to detect and categorize
+ * removals, page content reductions, and other destructive changes.
+ */
+
+declare class SchemaProtectionService {
+    /**
+     * Compare two schemas and detect destructive changes.
+     *
+     * Returns categorized removals including page content reductions.
+     */
+    compareSchemas(before: OrbitalSchema, after: OrbitalSchema): {
+        isDestructive: boolean;
+        removals: CategorizedRemovals;
+    };
+    /** Check if critical removals require confirmation */
+    requiresConfirmation(removals: CategorizedRemovals): boolean;
+    /** Check for significant page content reductions */
+    hasSignificantContentReduction(reductions: PageContentReduction[]): boolean;
+}
+
+export { ChangeSetStore, SchemaProtectionService, SchemaStore, SnapshotStore, ValidationStore, fromFirestoreFormat, toFirestoreFormat };