@vertesia/client 0.24.0-dev.202601221707

package/src/store/CollectionsApi.ts

@@ -0,0 +1,166 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { Collection, ComplexCollectionSearchQuery, ComplexSearchPayload, ComputeCollectionFacetPayload, ComputeObjectFacetPayload, ContentObjectItem, ContentObjectStatus, CreateCollectionPayload, DynamicCollection } from "@vertesia/common";
+import { ComputeFacetsResponse, SearchResponse } from "./ObjectsApi.js";
+
+
+export class CollectionsApi extends ApiTopic {
+
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/collections");
+    }
+
+    /**
+     * List collections
+     * @param payload: CollectionSearchPayload
+     * @returns Collection[] list of collections
+    **/
+    search(payload: ComplexCollectionSearchQuery): Promise<Collection[]> {
+        return this.post("/search", { payload });
+    }
+
+    /**
+     * Compute facets for List collections
+     * @param query: ComputeCollectionFacetPayload
+     * @returns ComputeFacetsResponse list of facets
+    **/
+    computeListFacets(query: ComputeCollectionFacetPayload): Promise<ComputeFacetsResponse> {
+        return this.post("/facets", {
+            payload: query
+        });
+    }
+
+    /**
+     * Get the collection data without members
+     * @param collectionId
+     * @returns
+     */
+    retrieve(collectionId: string): Promise<Collection | DynamicCollection> {
+        return this.get(`/${collectionId}`);
+    }
+
+    create(payload: CreateCollectionPayload): Promise<Collection> {
+        return this.post(`/`, {
+            payload
+        });
+    }
+
+    update(collectionId: string, payload: Partial<CreateCollectionPayload>): Promise<{ id: string }> {
+        return this.put(`/${collectionId}`, {
+            payload
+        });
+    }
+
+    addMembers(collectionId: string, members: string[]): Promise<{ id: string }> {
+        return this.post(`/${collectionId}/members`, {
+            payload: {
+                action: 'add',
+                members
+            }
+        });
+    }
+
+    listMembers(collectionId: string, payload: {
+        limit?: number,
+        offset?: number,
+        status?: ContentObjectStatus,
+        type?: string,
+    }): Promise<ContentObjectItem[]> {
+        return this.get(`/${collectionId}/members`, {
+            query: {
+                ...payload
+            }
+        });
+    }
+
+    computeFacets(collectionId: string, query: ComputeObjectFacetPayload): Promise<ComputeFacetsResponse> {
+        return this.post(`/${collectionId}/facets`, {
+            payload: query
+        });
+    }
+
+    searchMembers(collectionId: string, payload: ComplexSearchPayload): Promise<SearchResponse> {
+        return this.post(`/${collectionId}/search`, { payload });
+    }
+
+    deleteMembers(collectionId: string, members: string[]): Promise<{ id: string }> {
+        return this.post(`/${collectionId}/members`, {
+            payload: {
+                action: 'delete',
+                members
+            }
+        });
+    }
+
+    addChildren(collectionId: string, children: string[]): Promise<{ count: number }> {
+        return this.post(`/${collectionId}/children`, {
+            payload: {
+                action: 'add',
+                children
+            }
+        });
+    }
+
+    deleteChildren(collectionId: string, children: string[]): Promise<{ count: number }> {
+        return this.post(`/${collectionId}/children`, {
+            payload: {
+                action: 'delete',
+                children
+            }
+        });
+    }
+
+    searchChildren(collectionId: string, query: ComplexCollectionSearchQuery = {}): Promise<Collection[]> {
+        return this.post(`/${collectionId}/children/search`, {
+            payload: query
+        });
+    }
+
+    delete(id: string) {
+        return this.del(`/${id}`);
+    }
+
+    /**
+     * Update collection permissions and propagate to member objects
+     * @param collectionId - The collection ID
+     * @param permissions - Map of permission types to principal arrays
+     * @returns Object with collection id, updated security, and number of objects updated
+     */
+    updatePermissions(collectionId: string, permissions: Record<string, string[]>): Promise<{
+        id: string;
+        security: Record<string, string[]>;
+    }> {
+        return this.put(`/${collectionId}/permissions`, {
+            payload: permissions
+        });
+    }
+
+    /**
+     * Manually trigger permission propagation from collection to member objects
+     * Useful for debugging and fixing permission issues
+     * @param collectionId - The collection ID
+     * @returns Object with collection id, message, and number of objects updated
+     */
+    propagatePermissions(collectionId: string): Promise<{
+        id: string;
+        message: string;
+        security?: Record<string, string[]>;
+    }> {
+        return this.post(`/${collectionId}/propagate-permissions`);
+    }
+
+    /**
+     * Manually trigger shared properties propagation from collection to member objects
+     * Useful for debugging and fixing shared properties issues
+     * @param collectionId - The collection ID
+     * @returns Object with collection id, message, and number of objects updated
+     */
+    propagateSharedProperties(collectionId: string): Promise<{
+        id: string;
+        message: string;
+        shared_properties: string[]
+    }> {
+        return this.post(`/${collectionId}/propagate-shared-props`);
+    }
+
+
+}

package/src/store/CommandsApi.ts

@@ -0,0 +1,15 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import { EmbeddingsApi } from "./EmbeddingsApi.js";
+
+/**
+ * @deprecated use EmbeddingsApi instead
+ * @see EmbeddingsApi
+ */
+export class CommandsApi extends ApiTopic {
+
+    constructor(parent: ClientBase) {
+        super(parent, "/api/v1/commands");
+    }
+
+    embeddings = new EmbeddingsApi(this, "/embeddings");
+}

package/src/store/DashboardApi.ts

@@ -0,0 +1,216 @@
+import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
+import {
+    CreateDashboardPayload,
+    CreateDashboardSnapshotPayload,
+    Dashboard,
+    DashboardItem,
+    DashboardStatus,
+    DashboardVersion,
+    DashboardVersionItem,
+    DataStoreApiHeaders,
+    PromoteDashboardVersionPayload,
+    UpdateDashboardPayload,
+} from "@vertesia/common";
+
+/**
+ * Client API for managing Vega-based dashboards linked to data stores.
+ *
+ * Dashboards provide:
+ * - Multi-panel Vega/Vega-Lite visualizations
+ * - SQL-backed data sources via named queries
+ *
+ * Note: Rendering is handled by the tools (data_preview_dashboard, data_render_dashboard).
+ */
+export class DashboardApi extends ApiTopic {
+    private readonly storeId: string;
+
+    constructor(parent: ClientBase, storeId: string) {
+        super(parent, `/api/v1/data/${storeId}/dashboards`);
+        this.storeId = storeId;
+    }
+
+    /**
+     * Create headers with data store ID for Cloud Run session affinity.
+     */
+    private storeHeaders(): Record<string, string> {
+        return { [DataStoreApiHeaders.DATA_STORE_ID]: this.storeId };
+    }
+
+    // ============================================================
+    // Dashboard Operations
+    // ============================================================
+
+    /**
+     * List all dashboards for the data store.
+     *
+     * @param status - Filter by status (default: 'active')
+     * @returns List of dashboards
+     */
+    list(status?: DashboardStatus): Promise<DashboardItem[]> {
+        const query = status ? `?status=${status}` : '';
+        return this.get(`/${query}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Create a new dashboard.
+     *
+     * @param payload - Dashboard configuration with queries and panels
+     * @returns The created dashboard
+     *
+     * @example
+     * ```typescript
+     * const dashboard = await client.data.dashboards(storeId).create({
+     *   name: 'Sales Overview',
+     *   queries: [
+     *     { name: 'revenue', sql: 'SELECT month, SUM(amount) FROM sales GROUP BY month' }
+     *   ],
+     *   panels: [
+     *     {
+     *       title: 'Monthly Revenue',
+     *       dataSources: ['revenue'],
+     *       position: { row: 0, col: 0 },
+     *       spec: {
+     *         mark: 'bar',
+     *         encoding: {
+     *           x: { field: 'month', type: 'ordinal' },
+     *           y: { field: 'sum_amount', type: 'quantitative' }
+     *         }
+     *       }
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    create(payload: CreateDashboardPayload): Promise<Dashboard> {
+        return this.post("/", { payload, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Get a dashboard by ID.
+     *
+     * @param id - Dashboard ID
+     * @returns The dashboard with all details
+     */
+    retrieve(id: string): Promise<Dashboard> {
+        return this.get(`/${id}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Update an existing dashboard.
+     *
+     * @param id - Dashboard ID
+     * @param payload - Fields to update
+     * @returns The updated dashboard
+     */
+    update(id: string, payload: UpdateDashboardPayload): Promise<Dashboard> {
+        return this.put(`/${id}`, { payload, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Archive (soft delete) a dashboard.
+     *
+     * @param id - Dashboard ID
+     * @returns Object with the archived dashboard ID
+     */
+    delete(id: string): Promise<{ id: string; status: DashboardStatus }> {
+        return this.del(`/${id}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Archive (soft delete) multiple dashboards.
+     *
+     * @param ids - Array of dashboard IDs
+     * @returns Object with counts of archived and failed dashboards
+     */
+    bulkArchive(ids: string[]): Promise<{ archived: number; failed: number }> {
+        return this.post('/bulk/archive', { payload: { ids }, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Permanently delete multiple dashboards.
+     *
+     * @param ids - Array of dashboard IDs
+     * @returns Object with counts of deleted and failed dashboards
+     */
+    bulkDelete(ids: string[]): Promise<{ deleted: number; failed: number }> {
+        return this.post('/bulk/delete', { payload: { ids }, headers: this.storeHeaders() });
+    }
+
+    // ============================================================
+    // Version Operations
+    // ============================================================
+
+    /**
+     * List versions for a dashboard.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param options - Filter options
+     * @returns List of version summaries
+     */
+    listVersions(
+        dashboardId: string,
+        options?: { snapshotsOnly?: boolean; limit?: number }
+    ): Promise<DashboardVersionItem[]> {
+        const params = new URLSearchParams();
+        if (options?.snapshotsOnly) params.set('snapshots_only', 'true');
+        if (options?.limit) params.set('limit', String(options.limit));
+        const query = params.toString() ? `?${params}` : '';
+        return this.get(`/${dashboardId}/versions${query}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Get a specific version with full content.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param versionId - Version ID
+     * @returns The version with full content
+     */
+    getVersion(dashboardId: string, versionId: string): Promise<DashboardVersion> {
+        return this.get(`/${dashboardId}/versions/${versionId}`, { headers: this.storeHeaders() });
+    }
+
+    /**
+     * Create a named snapshot from current dashboard state.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param payload - Snapshot name and message
+     * @returns The created snapshot version
+     */
+    createSnapshot(
+        dashboardId: string,
+        payload: CreateDashboardSnapshotPayload
+    ): Promise<DashboardVersionItem> {
+        return this.post(`/${dashboardId}/versions`, { payload, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Promote a version to be the current/active one.
+     * This restores the version's content to the dashboard.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param versionId - Version ID to promote
+     * @param payload - Optional promotion message
+     * @returns The updated dashboard
+     */
+    promoteVersion(
+        dashboardId: string,
+        versionId: string,
+        payload?: PromoteDashboardVersionPayload
+    ): Promise<Dashboard> {
+        return this.post(`/${dashboardId}/versions/${versionId}/promote`, { payload: payload || {}, headers: this.storeHeaders() });
+    }
+
+    /**
+     * Enable or disable versioning for a dashboard.
+     *
+     * @param dashboardId - Dashboard ID
+     * @param enabled - Whether versioning should be enabled
+     * @returns The updated versioning state
+     */
+    setVersioningEnabled(
+        dashboardId: string,
+        enabled: boolean
+    ): Promise<{ versioning_enabled: boolean }> {
+        return this.put(`/${dashboardId}/versioning`, { payload: { enabled }, headers: this.storeHeaders() });
+    }
+}