@kubun/store-graph 0.10.2 → 0.12.0

package/lib/api.d.ts

@@ -12,8 +12,36 @@ export type StoredAccessRule = {
     allowedCircles: Array<string> | null;
     allowedGroups: Array<string> | null;
 };
+/**
+ * A single stored access-default row, tagged with the model and permission
+ * type it belongs to. Returned by `listUserModelAccessDefaults`, which -
+ * unlike `getUserModelAccessDefault` - is not scoped to one (model,
+ * permissionType) pair.
+ */
+export type StoredAccessDefaultRow = StoredAccessRule & {
+    modelID: string;
+    permissionType: 'read' | 'write';
+    /**
+     * The row's LWW anchor, or null when written without a stamp. Carried here so
+     * a caller needing rule + anchor for several models reads one list rather than
+     * a `getUserModelAccessDefault` / `getUserModelAccessDefaultHLC` pair each.
+     */
+    hlc: string | null;
+};
 export type GraphStoreAPI = {
     getDocument(id: DocumentID | string): Promise<DocumentNode | null>;
+    /**
+     * Batch fetch documents, returning a Map keyed by the document ID string. A
+     * missing id is absent from the map, exactly as `getDocument` returning `null`.
+     *
+     * Documents live in a per-model table, so the reads are grouped by model and
+     * cost one query per DISTINCT model rather than one per id. A model with no
+     * table contributes nothing, matching `getDocument`'s behaviour for an id whose
+     * model was never deployed. Empty input short-circuits with no SQL.
+     *
+     * Caller is responsible for deduplicating ids.
+     */
+    getDocuments(ids: Array<DocumentID | string>): Promise<Map<string, DocumentNode>>;
     getDocumentModel(id: DocumentModelID | string): Promise<DocumentModel>;
     /**
      * Return the interface model IDs declared by `modelID` from the
@@ -45,7 +73,8 @@ export type GraphStoreAPI = {
      */
     getMaxMutationHLC(): Promise<string | null>;
     getFieldHLCs(documentID: string): Promise<Record<string, string> | null>;
-    updateFieldHLCs(docID: DocumentID, fieldHLCs: Record<string, string>): Promise<void>;
+    getFieldValues(documentID: string): Promise<Record<string, unknown> | null>;
+    updateFieldHLCs(docID: DocumentID, fieldHLCs: Record<string, string>, fieldValues: Record<string, unknown>): Promise<void>;
     listGraphs(): Promise<Array<GraphModel>>;
     createGraph(params: CreateGraphParams): Promise<string>;
     getGraph(id: string): Promise<GraphModelWithRecord | null>;
@@ -60,7 +89,30 @@ export type GraphStoreAPI = {
     updateSearchEntry(modelID: string, documentID: string, data: Record<string, unknown>, fields: Array<string>): Promise<void>;
     removeSearchEntry(modelID: string, documentID: string): Promise<void>;
     searchDocuments(params: SearchDocumentsParams): Promise<Array<SearchDocumentResult>>;
+    /** Create an own catalog: stored active (scopes sync) with null provenance. */
     createCatalog(catalog: InsertCatalog): Promise<void>;
+    /**
+     * Insert a discovered catalog as known (not active) with first-discovery
+     * provenance. Idempotent on the id: an already-stored catalog is left
+     * untouched, so its local `active` flag and first-discovery source columns
+     * are never overwritten by a later re-discovery.
+     */
+    upsertDiscoveredCatalog(params: {
+        catalog: InsertCatalog;
+        sourceGroupID: string | null;
+        sourceCircleID: string | null;
+    }): Promise<void>;
+    /** Toggle a catalog's local sync activation. */
+    setCatalogActive(id: string, active: boolean): Promise<void>;
+    /** Flip several catalogs together — one statement, not one per id. */
+    setCatalogsActive(ids: Array<string>, active: boolean): Promise<void>;
+    /**
+     * All locally-stored catalog rows regardless of owner, optionally filtered by
+     * activation state. Backs the viewer's known-catalogs surface.
+     */
+    listStoredCatalogs(filter?: {
+        active?: boolean;
+    }): Promise<Array<Catalog>>;
     getCatalog(id: string): Promise<Catalog | undefined>;
     /**
      * Batch fetch catalogs by ID. Returns a Map keyed by ID; missing IDs are
@@ -70,7 +122,7 @@ export type GraphStoreAPI = {
      * Caller is responsible for deduplicating IDs (e.g. via `Array.from(new Set(...))`).
      */
     getCatalogs(ids: Array<string>): Promise<Map<string, Catalog>>;
-    updateCatalog(id: string, update: Partial<Pick<InsertCatalog, 'name' | 'description' | 'filter_criteria' | 'hlc'>>): Promise<void>;
+    updateCatalog(id: string, update: Partial<Pick<InsertCatalog, 'name' | 'description' | 'filter_criteria' | 'hlc' | 'signed_token'>>): Promise<void>;
     deleteCatalog(id: string): Promise<void>;
     listCatalogs(ownerDID: string): Promise<Array<Catalog>>;
     resolveCatalogScope(catalogID: string): Promise<{
@@ -78,7 +130,22 @@ export type GraphStoreAPI = {
         owners: Array<string> | undefined;
     }>;
     registerClusterModels(clusterID: string, entries: Array<InsertClusterModel>): Promise<void>;
+    /** A tombstoned (removed) rule reads as absent. */
     getUserModelAccessDefault(ownerDID: string, modelID: string, permissionType: 'read' | 'write'): Promise<StoredAccessRule | null>;
+    /**
+     * All active stored access-default rows for `ownerDID`, across every model and
+     * permission type. Tombstoned (removed) rows are excluded. Bounded by the
+     * owner's model count, no pagination.
+     */
+    listUserModelAccessDefaults(ownerDID: string): Promise<Array<StoredAccessDefaultRow>>;
+    /**
+     * The LWW anchor (`hlc`) stamped on a stored rule, or null when the rule is
+     * absent or was written without a stamp (a legacy or unsynced local policy).
+     * A caller applying a replicated rule reads this to reject an older write.
+     * A tombstoned row keeps its anchor: this returns the removal's `hlc` so a
+     * stale set arriving after the remove is still rejected.
+     */
+    getUserModelAccessDefaultHLC(ownerDID: string, modelID: string, permissionType: 'read' | 'write'): Promise<string | null>;
     setUserModelAccessDefault(params: {
         ownerDID: string;
         modelID: string;
@@ -87,8 +154,21 @@ export type GraphStoreAPI = {
         allowedDIDs: Array<string> | null;
         allowedCircles: Array<string> | null;
         allowedGroups: Array<string> | null;
+        /** LWW anchor. Omitted by callers that do not participate in replication. */
+        hlc?: string;
     }): Promise<void>;
-    removeUserModelAccessDefaults(ownerDID: string, modelID: string, permissionTypes: Array<string>): Promise<void>;
+    /**
+     * Tombstone the given permission types: retain each row with its rule fields
+     * nulled, `removed` set, and `hlc` stamped as the LWW anchor. The row is kept
+     * (not deleted) so a stale set arriving after the removal is rejected by HLC.
+     * A type with no existing row is skipped (nothing to tombstone).
+     */
+    removeUserModelAccessDefaults(ownerDID: string, modelID: string, permissionTypes: Array<string>, hlc: string): Promise<void>;
+    /**
+     * Document IDs across every scope, one query per distinct model. Repeating a
+     * (model, owner) pair yields its documents once — the result is a set, and the
+     * caller builds a Merkle tree from it, where a duplicate would be a defect.
+     */
     getDocumentIDsForScope(scopes: Array<{
         modelID: string;
         ownerDID: string;