@bardioc/app-sdk 1.0.1 → 1.0.3

package/dist/transports/graph-transport.js

@@ -0,0 +1,616 @@
+import { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from '../errors.js';
+const GRAPH_BASE = '/bardioc/api/graph/7.4';
+function buildQueryString(params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== '') {
+            searchParams.set(key, String(value));
+        }
+    }
+    const qs = searchParams.toString();
+    return qs ? `?${qs}` : '';
+}
+// Maps backend errors to typed SDK errors
+function parseError(error, operation, context) {
+    let statusCode;
+    let errorMessage = 'Unknown error';
+    // Check for direct message on error object (e.g. from fetch/network errors)
+    if (error.message && typeof error.message === 'string') {
+        errorMessage = error.message;
+    }
+    // Backend may return status in responsePayload
+    if (error.responsePayload && typeof error.responsePayload === 'object') {
+        statusCode = error.responsePayload.status || error.responsePayload.statusCode;
+        if (error.responsePayload.message) {
+            errorMessage = error.responsePayload.message;
+        }
+    }
+    // Check for timeout errors
+    if (errorMessage.includes('timed out') || errorMessage.includes('timeout')) {
+        return new TimeoutError(operation, 10000);
+    }
+    // Map by status code
+    if (statusCode) {
+        const fullContext = {
+            ...context,
+            operation,
+            timestamp: Date.now(),
+            statusCode,
+        };
+        switch (statusCode) {
+            case 404:
+                return new EntityNotFoundError(context?.id || context?.xid || 'unknown');
+            case 400:
+                return new ValidationError(errorMessage, context?.field);
+            case 403:
+                return new PermissionError(errorMessage);
+            case 408:
+                return new TimeoutError(operation, 10000);
+            case 500:
+            case 502:
+            case 503:
+                return new NetworkError(errorMessage, statusCode);
+            default:
+                if (statusCode >= 400) {
+                    return new NetworkError(errorMessage, statusCode);
+                }
+        }
+    }
+    // Default to generic SDK error
+    return new SdkError(errorMessage, 'UNKNOWN_ERROR', statusCode, {
+        ...context,
+        operation,
+        timestamp: Date.now(),
+    });
+}
+/** Graph transport class providing graph database operations */
+export class GraphTransport {
+    _request;
+    _debug;
+    constructor(_request, options) {
+        this._request = _request;
+        this._debug = options?.debug ?? false;
+    }
+    log(...args) {
+        if (this._debug)
+            console.log('[graph-transport]', ...args);
+    }
+    withScope(payload, options) {
+        if (!options?.scopeId) {
+            return payload;
+        }
+        return {
+            ...payload,
+            scopeId: options.scopeId,
+            scopePolicy: 'required',
+        };
+    }
+    /**
+     * Get single node by ID
+     * Returns raw backend format (ogit/* fields)
+     *
+     * @throws {EntityNotFoundError} if node doesn't exist
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async get(id, options) {
+        try {
+            const qs = buildQueryString({
+                fields: options?.fields,
+                includeDeleted: options?.includeDeleted,
+                listMeta: options?.listMeta,
+                vid: options?.vid,
+            });
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/${encodeURIComponent(id)}${qs}`,
+                method: 'GET',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.get', { id, ...options });
+        }
+    }
+    /**
+     * Get multiple nodes by IDs (batched request)
+     * Uses /query/ids endpoint
+     *
+     * @returns Array in same order as input IDs (missing nodes = undefined)
+     * @throws {ValidationError} if ids array is empty or invalid
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async getMany(ids, options) {
+        try {
+            const qs = buildQueryString({
+                query: ids.join(','),
+                fields: options?.fields,
+                includeDeleted: options?.includeDeleted,
+                listMeta: options?.listMeta,
+            });
+            this.log('getMany', { path: `${GRAPH_BASE}/query/ids${qs}`, count: ids.length });
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/query/ids${qs}`,
+                method: 'GET',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.getMany', { ids: ids.length, ...options });
+        }
+    }
+    /**
+     * Get node by external ID
+     *
+     * @throws {EntityNotFoundError} if XID doesn't exist
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async getByXid(xid, options) {
+        try {
+            const qs = buildQueryString({
+                fields: options?.fields,
+                includeDeleted: options?.includeDeleted,
+                listMeta: options?.listMeta,
+            });
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/xid/${encodeURIComponent(xid)}${qs}`,
+                method: 'GET',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.getByXid', { xid, ...options });
+        }
+    }
+    /**
+     * Query nodes using Lucene syntax
+     * Returns raw backend format (ogit/* fields)
+     *
+     * @example
+     * const people = await graph.query<GraphNodeRaw>(
+     *   'ogit/_type:ogit/Person',
+     *   { limit: 50, offset: 0 }
+     * );
+     *
+     * @throws {ValidationError} if query syntax is invalid
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async query(lucene, options) {
+        try {
+            const qs = buildQueryString({
+                query: lucene,
+                limit: options?.limit,
+                offset: options?.offset,
+                fields: options?.fields,
+                includeDeleted: options?.includeDeleted,
+                listMeta: options?.listMeta,
+                order: options?.order,
+            });
+            this.log('query', {
+                path: `${GRAPH_BASE}/query/vertices${qs}`,
+                lucene,
+                limit: options?.limit,
+                offset: options?.offset,
+            });
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/query/vertices${qs}`,
+                method: 'GET',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.query', { lucene, ...options });
+        }
+    }
+    /**
+     * Execute Gremlin traversal query
+     * Returns raw results (structure varies by query)
+     *
+     * @example
+     * const edges = await graph.gremlin(rootId, "outE('ogit/relates')");
+     *
+     * @throws {EntityNotFoundError} if root node doesn't exist
+     * @throws {ValidationError} if query syntax is invalid
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async gremlin(rootId, query, options) {
+        try {
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/query/gremlin`,
+                method: 'POST',
+                body: {
+                    root: rootId,
+                    query,
+                    fields: options?.fields,
+                    includeDeleted: options?.includeDeleted,
+                    listMeta: options?.listMeta,
+                },
+                contentType: 'application/json',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.gremlin', { rootId, query, ...options });
+        }
+    }
+    /**
+     * Execute combined query: Elasticsearch selects the start vertices, the Gremlin traversal
+     * runs from their IDs. Returns raw results (structure varies by the traversal).
+     *
+     * The result is one flat set for all start vertices — it carries no marker for which start
+     * vertex a row came from. Label and select in the traversal when attribution is needed.
+     *
+     * @example
+     * const speeches = await graph.combined(
+     *   '+(ogit\\/_type: "ogit/Politics/AgendaItem")',
+     *   "inE().outV().has('ogit/_type', 'ogit/Politics/Discussion')",
+     *   { limit: 1000 }
+     * );
+     *
+     * @throws {ValidationError} if either query is invalid
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async combined(elasticsearchQuery, gremlinQuery, options) {
+        try {
+            const path = `${GRAPH_BASE}/query/combined`;
+            this.log('combined', { path, elasticsearchQuery, gremlinQuery, limit: options?.limit });
+            return await this._request(this.withScope({
+                path,
+                method: 'POST',
+                body: {
+                    elasticsearch_query: elasticsearchQuery,
+                    gremlin_query: gremlinQuery,
+                    ...(options?.limit === undefined ? {} : { limit: options.limit }),
+                },
+                contentType: 'application/json',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.combined', { elasticsearchQuery, gremlinQuery, ...options });
+        }
+    }
+    /**
+     * Create new graph node
+     *
+     * @param type - OGIT type (e.g., 'ogit/Person')
+     * @param data - Node attributes (ogit/* format)
+     * @returns Created node (raw backend format)
+     *
+     * @throws {ValidationError} if data is invalid or missing required fields
+     * @throws {PermissionError} if user lacks permission to create this type
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async create(type, data, options) {
+        try {
+            const qs = buildQueryString({
+                fullResponse: options?.fullResponse,
+                listMeta: options?.listMeta,
+            });
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/new/${encodeURIComponent(type)}${qs}`,
+                method: 'POST',
+                body: data,
+                contentType: 'application/json',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.create', { type, ...options });
+        }
+    }
+    /**
+     * Update existing node
+     *
+     * @param id - Node ID
+     * @param data - Fields to update (ogit/* format)
+     * @returns Updated node (raw backend format)
+     *
+     * @throws {EntityNotFoundError} if node doesn't exist
+     * @throws {ValidationError} if data is invalid
+     * @throws {PermissionError} if user lacks permission to update this node
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async update(id, data, options) {
+        try {
+            const qs = buildQueryString({
+                fullResponse: options?.fullResponse,
+                listMeta: options?.listMeta,
+            });
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/${encodeURIComponent(id)}${qs}`,
+                method: 'POST',
+                body: data,
+                contentType: 'application/json',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.update', { id, ...options });
+        }
+    }
+    /**
+     * Delete node (soft delete by default)
+     *
+     * @throws {EntityNotFoundError} if node doesn't exist
+     * @throws {PermissionError} if user lacks permission to delete this node
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async delete(id, options) {
+        try {
+            const qs = buildQueryString({
+                hard: options?.hard,
+            });
+            await this._request(this.withScope({
+                path: `${GRAPH_BASE}/${encodeURIComponent(id)}${qs}`,
+                method: 'DELETE',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.delete', { id, ...options });
+        }
+    }
+    /**
+     * Create edge between two nodes
+     *
+     * @param from - Source node ID
+     * @param to - Target node ID
+     * @param type - Edge type (e.g., 'ogit/relates')
+     * @returns Created edge (raw backend format)
+     *
+     * @throws {EntityNotFoundError} if either node doesn't exist
+     * @throws {ValidationError} if edge type is invalid or not allowed
+     * @throws {PermissionError} if user lacks permission to create this edge
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async connect(from, to, type, options) {
+        try {
+            const qs = buildQueryString({
+                fullResponse: options?.fullResponse,
+                listMeta: options?.listMeta,
+            });
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/connect${qs}`,
+                method: 'POST',
+                body: { fromId: from, toId: to, edgeType: type },
+                contentType: 'application/json',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.connect', { from, to, type, ...options });
+        }
+    }
+    /**
+     * Get node history
+     *
+     * @param nodeId - Node ID
+     * @param options - Time range, limit, etc.
+     * @returns Array of historical versions
+     *
+     * @throws {EntityNotFoundError} if node doesn't exist
+     * @throws {NetworkError} on HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async history(nodeId, options) {
+        try {
+            const qs = buildQueryString({
+                from: options?.from,
+                to: options?.to,
+                limit: options?.limit,
+                offset: options?.offset,
+                includeDeleted: options?.includeDeleted,
+            });
+            return await this._request(this.withScope({
+                path: `${GRAPH_BASE}/${encodeURIComponent(nodeId)}/history${qs}`,
+                method: 'GET',
+            }, options));
+        }
+        catch (error) {
+            throw parseError(error, 'graph.history', { nodeId, ...options });
+        }
+    }
+    /**
+     * Batch operations
+     */
+    batch = {
+        /**
+         * Delete multiple nodes in parallel
+         * Continues deleting even if some fail
+         *
+         * @param ids - Array of node IDs to delete
+         * @param options - Delete options (hard delete, etc.)
+         * @returns BatchResult with succeeded and failed IDs
+         *
+         * @example
+         * const result = await graph.batch.delete(['id1', 'id2', 'id3'], { hard: false });
+         * console.log(`Deleted: ${result.succeeded.length}, Failed: ${result.failed.length}`);
+         * result.failed.forEach(f => console.error(`Failed ${f.id}: ${f.error}`));
+         */
+        delete: async (ids, options) => {
+            const results = await Promise.allSettled(ids.map(id => this.delete(id, options)));
+            const succeeded = [];
+            const failed = [];
+            results.forEach((result, index) => {
+                const id = ids[index];
+                if (!id)
+                    return;
+                if (result.status === 'fulfilled') {
+                    succeeded.push(id);
+                }
+                else {
+                    failed.push({
+                        id,
+                        error: result.reason?.message || 'Unknown error',
+                    });
+                }
+            });
+            return { succeeded, failed };
+        },
+    };
+    /**
+     * Time series operations
+     */
+    timeseries = {
+        /**
+         * Get time series values.
+         *
+         * `withIds` pulls further time series into the same request and `aggregate` combines the
+         * values sharing a timestamp. Entries carry only timestamp and value, so a multi-ID request
+         * yields one merged series — read a single ID per request when values must stay attributable.
+         *
+         * @throws {EntityNotFoundError} if time series doesn't exist
+         * @throws {NetworkError} on HTTP errors
+         * @throws {TimeoutError} on request timeout
+         */
+        get: async (id, options) => {
+            try {
+                const qs = buildQueryString({
+                    from: options?.from,
+                    to: options?.to,
+                    limit: options?.limit,
+                    order: options?.order,
+                    with: options?.withIds?.join(','),
+                    aggregate: options?.aggregate,
+                    includeDeleted: options?.includeDeleted,
+                });
+                return await this._request(this.withScope({
+                    path: `${GRAPH_BASE}/${encodeURIComponent(id)}/values${qs}`,
+                    method: 'GET',
+                }, options));
+            }
+            catch (error) {
+                throw parseError(error, 'graph.timeseries.get', { id, ...options });
+            }
+        },
+        /**
+         * Add time series values
+         *
+         * @throws {EntityNotFoundError} if time series doesn't exist
+         * @throws {ValidationError} if values format is invalid
+         * @throws {NetworkError} on HTTP errors
+         * @throws {TimeoutError} on request timeout
+         */
+        add: async (id, values, options) => {
+            try {
+                await this._request(this.withScope({
+                    path: `${GRAPH_BASE}/${encodeURIComponent(id)}/values`,
+                    method: 'POST',
+                    body: { values },
+                    contentType: 'application/json',
+                }, options));
+            }
+            catch (error) {
+                throw parseError(error, 'graph.timeseries.add', { id, count: values.length, ...options });
+            }
+        },
+        /**
+         * Query time series with filters
+         *
+         * @throws {ValidationError} if query options are invalid
+         * @throws {NetworkError} on HTTP errors
+         * @throws {TimeoutError} on request timeout
+         */
+        query: async (options) => {
+            try {
+                const qs = buildQueryString({
+                    ids: options.ids?.join(','),
+                    from: options.from,
+                    to: options.to,
+                    limit: options.limit,
+                    order: options.order,
+                    aggregate: options.aggregate,
+                });
+                return await this._request(this.withScope({
+                    path: `${GRAPH_BASE}/query/values${qs}`,
+                    method: 'GET',
+                }, options));
+            }
+            catch (error) {
+                throw parseError(error, 'graph.timeseries.query', { ...options });
+            }
+        },
+        /**
+         * Get every value ever written for one timestamp of a time series.
+         * Keyed by timestamp, so a single-timestamp request returns a single-entry map.
+         *
+         * @throws {EntityNotFoundError} if time series doesn't exist
+         * @throws {NetworkError} on HTTP errors
+         * @throws {TimeoutError} on request timeout
+         */
+        history: async (id, timestamp, options) => {
+            try {
+                const qs = buildQueryString({
+                    timestamp,
+                    includeDeleted: options?.includeDeleted,
+                });
+                return await this._request(this.withScope({
+                    path: `${GRAPH_BASE}/${encodeURIComponent(id)}/values/history${qs}`,
+                    method: 'GET',
+                }, options));
+            }
+            catch (error) {
+                throw parseError(error, 'graph.timeseries.history', { id, timestamp, ...options });
+            }
+        },
+    };
+    /**
+     * Content/blob operations
+     */
+    content = {
+        /**
+         * Upload binary content to a node
+         *
+         * @param nodeId - Node ID to attach content to
+         * @param data - Binary content as Blob
+         * @param contentType - MIME type (e.g., 'image/png', 'application/pdf')
+         * @returns Content ID for later retrieval
+         *
+         * @throws {EntityNotFoundError} if node doesn't exist
+         * @throws {ValidationError} if content is invalid
+         * @throws {NetworkError} on HTTP errors
+         * @throws {TimeoutError} on request timeout
+         */
+        set: async (nodeId, data, contentType, options) => {
+            try {
+                const result = await this._request(this.withScope({
+                    path: `${GRAPH_BASE}/${encodeURIComponent(nodeId)}/content`,
+                    method: 'POST',
+                    body: data,
+                    contentType,
+                }, options));
+                return result.contentId;
+            }
+            catch (error) {
+                throw parseError(error, 'graph.content.set', {
+                    nodeId,
+                    contentType,
+                    size: data.size,
+                    ...options,
+                });
+            }
+        },
+        /**
+         * Download binary content from a node
+         *
+         * @param nodeId - Node ID
+         * @param contentId - Content ID returned from set operation
+         * @returns Binary content as Blob
+         *
+         * @throws {EntityNotFoundError} if node or content doesn't exist
+         * @throws {NetworkError} on HTTP errors
+         * @throws {TimeoutError} on request timeout
+         */
+        get: async (nodeId, contentId, options) => {
+            try {
+                const qs = buildQueryString({ contentId });
+                return await this._request(this.withScope({
+                    path: `${GRAPH_BASE}/${encodeURIComponent(nodeId)}/content${qs}`,
+                    method: 'GET',
+                }, options));
+            }
+            catch (error) {
+                throw parseError(error, 'graph.content.get', { nodeId, contentId, ...options });
+            }
+        },
+    };
+}