@jazzmind/busibox-app 3.0.18

package/dist/lib/data/client.js

@@ -0,0 +1,296 @@
+/**
+ * Data Service Client for busibox-app
+ *
+ * Centralized client for communicating with the data service.
+ *
+ * Usage:
+ * ```typescript
+ * const result = await uploadChatAttachment(file, {
+ *   userId: 'user-123',
+ *   getAuthzToken: async (userId, audience, scopes) => {
+ *     // Custom token acquisition logic
+ *     return 'token';
+ *   }
+ * });
+ * ```
+ */
+// Service URL configuration
+const DEFAULT_DATA_HOST = process.env.DATA_API_HOST || process.env.DATA_CONTAINER_IP || 'localhost';
+const DEFAULT_DATA_PORT = process.env.DATA_API_PORT || process.env.DATA_SERVICE_PORT || '8002';
+const DEFAULT_DATA_URL = process.env.DATA_API_URL || `http://${DEFAULT_DATA_HOST}:${DEFAULT_DATA_PORT}`;
+/**
+ * Create an error with context about which part of the code called the data service
+ */
+function createDataError(context, url, error, statusCode) {
+    const message = error instanceof Error ? error.message : String(error);
+    const dataError = new Error(`[DATA SERVICE ERROR] ${context}: ${message}`);
+    dataError.context = context;
+    dataError.url = url;
+    dataError.statusCode = statusCode;
+    dataError.originalError = error;
+    // Log the error with full context
+    console.error(`[DATA SERVICE ERROR]`, {
+        context,
+        url,
+        statusCode,
+        error: message,
+        stack: error instanceof Error ? error.stack : undefined,
+    });
+    return dataError;
+}
+/**
+ * Get authorization header for data service calls
+ */
+async function getAuthHeader(options) {
+    // Pre-acquired token (e.g. from requireAuthWithTokenExchange)
+    if (options.accessToken) {
+        return options.accessToken.startsWith('Bearer ') ? options.accessToken : `Bearer ${options.accessToken}`;
+    }
+    // Server-side: use custom token acquisition
+    if (options.getAuthzToken && options.userId) {
+        const token = await options.getAuthzToken(options.userId, 'data-api', []);
+        return `Bearer ${token}`;
+    }
+    // No authentication provided
+    return undefined;
+}
+/**
+ * Fetch from data service with error handling, context, timeout, and automatic token refresh retry
+ */
+export async function dataFetch(context, path, options) {
+    const { userId, getAuthzToken, accessToken, purpose, dataUrl, timeout, ...fetchOptions } = options;
+    const baseUrl = dataUrl || DEFAULT_DATA_URL;
+    const url = `${baseUrl}${path}`;
+    // Default timeout of 30 seconds (can be overridden per-request)
+    const requestTimeout = timeout ?? 30000;
+    // Internal fetch function that can be retried
+    const performFetch = async (forceRefresh = false) => {
+        // Get authorization header
+        const authHeader = await getAuthHeader({ userId, getAuthzToken, accessToken, purpose });
+        // Only log if verbose logging is enabled (set VERBOSE_DATA_LOGGING=true in env)
+        if (process.env.VERBOSE_DATA_LOGGING === 'true') {
+            console.log('[DATA FETCH] Request:', {
+                url,
+                method: fetchOptions.method || 'GET',
+                hasAuthHeader: !!authHeader,
+                authHeaderPrefix: authHeader?.substring(0, 20) + '...',
+                isRetry: forceRefresh,
+            });
+        }
+        const headers = {
+            ...fetchOptions.headers,
+        };
+        if (authHeader) {
+            headers['Authorization'] = authHeader;
+        }
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
+        try {
+            const response = await fetch(url, {
+                ...fetchOptions,
+                headers,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            return response;
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Request timed out after ${requestTimeout}ms`);
+            }
+            throw err;
+        }
+    };
+    try {
+        // First attempt
+        let response = await performFetch(false);
+        // If we get a 401/403 (token expired/invalid), try refreshing the token once
+        if ((response.status === 401 || response.status === 403)) {
+            const errorText = await response.text();
+            const isTokenError = errorText.includes('JWT') ||
+                errorText.includes('token') ||
+                errorText.includes('expired') ||
+                errorText.includes('Invalid or expired');
+            if (isTokenError) {
+                console.log('[DATA FETCH] Token expired/invalid, refreshing and retrying...', {
+                    status: response.status,
+                    errorText: errorText.substring(0, 200),
+                });
+                // For server-side, we need to clear the cache manually
+                if (getAuthzToken && userId) {
+                    // Clear the token cache by requesting a new token
+                    // This will bypass the cache since we just used it and it failed
+                    const token = await getAuthzToken(userId, 'data-api', []);
+                    const headers = {
+                        ...fetchOptions.headers,
+                        'Authorization': `Bearer ${token}`,
+                    };
+                    // Use timeout for retry as well
+                    const retryController = new AbortController();
+                    const retryTimeoutId = setTimeout(() => retryController.abort(), requestTimeout);
+                    try {
+                        response = await fetch(url, {
+                            ...fetchOptions,
+                            headers,
+                            signal: retryController.signal,
+                        });
+                        clearTimeout(retryTimeoutId);
+                    }
+                    catch (retryErr) {
+                        clearTimeout(retryTimeoutId);
+                        if (retryErr instanceof Error && retryErr.name === 'AbortError') {
+                            throw new Error(`Retry request timed out after ${requestTimeout}ms`);
+                        }
+                        throw retryErr;
+                    }
+                }
+            }
+        }
+        if (!response.ok) {
+            let errorMessage = `HTTP ${response.status}`;
+            let errorBody = {};
+            try {
+                const text = await response.text();
+                // Always log errors - they're important
+                console.log('[DATA FETCH] Error response body:', text);
+                try {
+                    errorBody = JSON.parse(text);
+                    errorMessage = errorBody.error || errorBody.message || errorBody.detail || errorMessage;
+                }
+                catch {
+                    errorMessage = text || response.statusText || errorMessage;
+                }
+            }
+            catch {
+                // If we can't read body, use status text
+                errorMessage = response.statusText || errorMessage;
+            }
+            // Always log errors - they're important
+            console.log('[DATA FETCH] Request failed:', {
+                status: response.status,
+                errorMessage,
+                errorBody,
+            });
+            throw createDataError(context, url, errorMessage, response.status);
+        }
+        return response;
+    }
+    catch (error) {
+        // Check if it's already an DataServiceError
+        if (error && typeof error === 'object' && 'context' in error) {
+            throw error;
+        }
+        // Handle connection errors
+        if (error instanceof TypeError && error.message.includes('fetch failed')) {
+            const cause = error.cause;
+            if (cause && cause.code === 'ECONNREFUSED') {
+                throw createDataError(context, url, `Connection refused to data service at ${url}. Is the service running?`, undefined);
+            }
+        }
+        throw createDataError(context, url, error);
+    }
+}
+/**
+ * Get the data service base URL
+ */
+export function getDataServiceUrl(customUrl) {
+    return customUrl || DEFAULT_DATA_URL;
+}
+// ============================================================================
+// Chat Attachment Processing (Dual-Mode)
+// ============================================================================
+/**
+ * Upload a file for chat attachment
+ *
+ * @param file - File to upload
+ * @param options - Client options (tokenManager or userId + getAuthzToken)
+ * @returns File ID and metadata
+ */
+export async function uploadChatAttachment(file, options) {
+    const formData = new FormData();
+    formData.append('file', file);
+    const response = await dataFetch('Upload chat attachment', '/upload', {
+        ...options,
+        method: 'POST',
+        body: formData,
+    });
+    return response.json();
+}
+/**
+ * Parse file to markdown without full data
+ *
+ * This is for chat attachments that should be passed to the LLM
+ * without chunking, embedding, or storage in the document library.
+ *
+ * @param fileId - File ID from upload
+ * @param options - Client options
+ * @returns Parsed markdown content
+ */
+export async function parseFileToMarkdown(fileId, options) {
+    const response = await dataFetch(`Parse file ${fileId} to markdown`, `/files/${fileId}/markdown`, {
+        ...options,
+        method: 'GET',
+    });
+    const data = await response.json();
+    // Transform response to match expected format
+    return {
+        markdown: data.markdown,
+        metadata: {
+        // Data service doesn't return these fields, provide empty metadata
+        },
+    };
+}
+/**
+ * Ingest file with full processing (chunking, embeddings, storage)
+ *
+ * This is for chat attachments that the user wants to add to their
+ * document library for future searches.
+ *
+ * @param fileId - File ID from upload
+ * @param options - Client options
+ * @param ingestOptions - Data configuration
+ * @returns Data job ID and status
+ */
+export async function dataChatAttachment(fileId, options, ingestOptions = {}) {
+    const response = await dataFetch(`Ingest chat attachment ${fileId}`, `/files/${fileId}/data`, {
+        ...options,
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            collection: ingestOptions.collection || 'default',
+            chunkSize: ingestOptions.chunkSize || 512,
+            chunkOverlap: ingestOptions.chunkOverlap || 50,
+        }),
+    });
+    return response.json();
+}
+/**
+ * Get file download URL (presigned URL from MinIO)
+ *
+ * @param fileId - File ID
+ * @param options - Client options
+ * @param expirySeconds - URL expiration time in seconds (default: 3600 = 1 hour)
+ * @returns Presigned download URL
+ */
+export async function getChatAttachmentUrl(fileId, options, expirySeconds = 3600) {
+    const response = await dataFetch(`Get presigned URL for ${fileId}`, `/files/${fileId}/presigned-url?expiry=${expirySeconds}`, options);
+    const data = await response.json();
+    return data.url;
+}
+/**
+ * Delete chat attachment file
+ *
+ * @param fileId - File ID
+ * @param options - Client options
+ */
+export async function deleteChatAttachment(fileId, options) {
+    await dataFetch(`Delete chat attachment ${fileId}`, `/files/${fileId}`, {
+        ...options,
+        method: 'DELETE',
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/lib/data/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/lib/data/client.ts"],"names":[],"mappings":"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"}

package/dist/lib/data/documents.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Generic Data Documents Client for Busibox data-api.
+ *
+ * Provides document management and CRUD operations for structured data documents.
+ * Use with token from requireAuthWithTokenExchange(request, 'data-api').
+ *
+ * @example
+ * ```typescript
+ * const auth = await requireAuthWithTokenExchange(request, 'data-api');
+ * if (auth instanceof NextResponse) return auth;
+ * const docs = await ensureDocuments(auth.apiToken, { projects: { name: 'my-projects', schema, visibility: 'personal' } });
+ * const { records } = await queryRecords<Project>(auth.apiToken, docs.projects, { limit: 10 });
+ * ```
+ */
+import type { DocumentInfo, DataDocument, DataDocumentConfig, QueryOptions, QueryFilter, QueryCondition } from '../../types/data-documents';
+export type { DocumentInfo, DataDocument, QueryOptions, QueryFilter, QueryCondition };
+export interface DataDocumentsOptions {
+    /** Override data API URL (default: DATA_API_URL or http://localhost:8002) */
+    dataUrl?: string;
+    /** Filter documents by sourceApp when listing (for ensureDocuments) */
+    sourceApp?: string;
+    /** Max documents to fetch when listing */
+    limit?: number;
+}
+export interface DocumentRoleAssignment {
+    role_id: string;
+    role_name: string;
+    added_at?: string;
+    added_by?: string | null;
+}
+export interface DocumentRolesResponse {
+    documentId: string;
+    visibility: 'personal' | 'shared';
+    roleIds: string[];
+    roles: DocumentRoleAssignment[];
+}
+export declare function generateId(): string;
+export declare function getNow(): string;
+/**
+ * Strip undefined values from an object to prevent JSON serialization issues.
+ */
+export declare function cleanRecord<T>(record: T): T;
+/**
+ * Extract role IDs from a JWT token (without verification).
+ * Used for shared visibility documents.
+ */
+export declare function extractRoleIdsFromToken(token: string): string[];
+export declare function listDataDocuments(token: string, options?: DataDocumentsOptions): Promise<DocumentInfo[]>;
+export declare function createDataDocument(token: string, name: string, schema: Record<string, unknown>, visibility?: 'personal' | 'shared', options?: DataDocumentsOptions): Promise<DataDocument>;
+export declare function getDocumentByName(token: string, name: string, options?: DataDocumentsOptions): Promise<DataDocument | null>;
+export declare function getDocumentDetails(token: string, documentId: string, options?: DataDocumentsOptions): Promise<DataDocument & {
+    sourceApp?: string;
+    metadata?: Record<string, unknown>;
+}>;
+export declare function updateDocumentMetadata(token: string, documentId: string, metadata: Record<string, unknown>, schema?: Record<string, unknown>, options?: DataDocumentsOptions): Promise<void>;
+export declare function getDocumentRoles(token: string, documentId: string, options?: DataDocumentsOptions): Promise<DocumentRolesResponse>;
+export declare function updateDocumentRoles(token: string, documentId: string, roleIds: string[], visibility?: 'personal' | 'shared', options?: DataDocumentsOptions): Promise<DocumentRolesResponse>;
+export declare function ensureSchemaAndMetadata(token: string, documentId: string, schema: Record<string, unknown>, sourceApp: string, options?: DataDocumentsOptions): Promise<void>;
+export declare function queryRecords<T>(token: string, documentId: string, queryOptions?: QueryOptions, options?: DataDocumentsOptions): Promise<{
+    records: T[];
+    total: number;
+}>;
+export declare function insertRecords<T>(token: string, documentId: string, records: T[], validate?: boolean, options?: DataDocumentsOptions): Promise<{
+    count: number;
+    recordIds: string[];
+}>;
+export declare function updateRecords(token: string, documentId: string, updates: Record<string, unknown>, where?: QueryFilter | QueryCondition, validate?: boolean, options?: DataDocumentsOptions): Promise<{
+    count: number;
+}>;
+export declare function deleteRecords(token: string, documentId: string, where?: QueryFilter | QueryCondition, recordIds?: string[], options?: DataDocumentsOptions): Promise<{
+    count: number;
+}>;
+/**
+ * Ensure all configured documents exist. Creates missing ones and updates schemas.
+ *
+ * @param token - Bearer token from requireAuthWithTokenExchange
+ * @param config - Map of key -> { name, schema, visibility }
+ * @param sourceApp - App identifier for schema metadata
+ * @returns Map of key -> document ID
+ */
+export declare function ensureDocuments<T extends Record<string, DataDocumentConfig>>(token: string, config: T, sourceApp: string, options?: DataDocumentsOptions): Promise<{
+    [K in keyof T]: string;
+}>;
+//# sourceMappingURL=documents.d.ts.map

package/dist/lib/data/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../../src/lib/data/documents.ts"],"names":[],"mappings":"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"}

package/dist/lib/data/documents.js

@@ -0,0 +1,250 @@
+/**
+ * Generic Data Documents Client for Busibox data-api.
+ *
+ * Provides document management and CRUD operations for structured data documents.
+ * Use with token from requireAuthWithTokenExchange(request, 'data-api').
+ *
+ * @example
+ * ```typescript
+ * const auth = await requireAuthWithTokenExchange(request, 'data-api');
+ * if (auth instanceof NextResponse) return auth;
+ * const docs = await ensureDocuments(auth.apiToken, { projects: { name: 'my-projects', schema, visibility: 'personal' } });
+ * const { records } = await queryRecords<Project>(auth.apiToken, docs.projects, { limit: 10 });
+ * ```
+ */
+import { dataFetch, getDataServiceUrl } from './client';
+async function dataDocumentsRequest(token, path, init = {}, options) {
+    const baseUrl = options?.dataUrl || getDataServiceUrl();
+    const url = `${baseUrl}${path}`;
+    const response = await dataFetch(`Data documents ${path}`, path, {
+        accessToken: token.startsWith('Bearer ') ? token : `Bearer ${token}`,
+        dataUrl: options?.dataUrl,
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            ...init.headers,
+        },
+    });
+    return response.json();
+}
+// ==========================================================================
+// Utilities
+// ==========================================================================
+export function generateId() {
+    return crypto.randomUUID();
+}
+export function getNow() {
+    return new Date().toISOString();
+}
+/**
+ * Strip undefined values from an object to prevent JSON serialization issues.
+ */
+export function cleanRecord(record) {
+    if (!record || typeof record !== 'object')
+        return record;
+    const cleaned = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined) {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+}
+/**
+ * Extract role IDs from a JWT token (without verification).
+ * Used for shared visibility documents.
+ */
+export function extractRoleIdsFromToken(token) {
+    try {
+        const parts = token.replace(/^Bearer\s+/i, '').split('.');
+        if (parts.length !== 3)
+            return [];
+        const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const json = typeof Buffer !== 'undefined'
+            ? Buffer.from(b64, 'base64').toString('utf-8')
+            : typeof atob !== 'undefined'
+                ? atob(b64)
+                : '';
+        const payload = JSON.parse(json);
+        const roles = payload.roles || [];
+        return roles
+            .map((r) => (typeof r === 'string' ? r : r?.id))
+            .filter((id) => !!id);
+    }
+    catch {
+        return [];
+    }
+}
+// ==========================================================================
+// Document Management
+// ==========================================================================
+export async function listDataDocuments(token, options) {
+    const params = new URLSearchParams();
+    if (options?.sourceApp)
+        params.set('sourceApp', options.sourceApp);
+    if (options?.limit)
+        params.set('limit', String(options.limit));
+    const query = params.toString() ? `?${params}` : '';
+    const response = await dataDocumentsRequest(token, `/data${query}`, {}, options);
+    return response.documents || [];
+}
+export async function createDataDocument(token, name, schema, visibility = 'shared', options) {
+    const sourceApp = schema.sourceApp;
+    const roleIds = visibility === 'shared' ? extractRoleIdsFromToken(token) : undefined;
+    const effectiveVisibility = visibility === 'shared' && roleIds && roleIds.length > 0 ? 'shared' : 'personal';
+    return dataDocumentsRequest(token, '/data', {
+        method: 'POST',
+        body: JSON.stringify({
+            name,
+            schema,
+            visibility: effectiveVisibility,
+            roleIds: effectiveVisibility === 'shared' ? roleIds : undefined,
+            enableCache: false,
+            sourceApp,
+        }),
+    }, options);
+}
+export async function getDocumentByName(token, name, options) {
+    const documents = await listDataDocuments(token, options);
+    const doc = documents.find((d) => d.name === name);
+    if (!doc)
+        return null;
+    return dataDocumentsRequest(token, `/data/${doc.id}`, {}, options);
+}
+export async function getDocumentDetails(token, documentId, options) {
+    return dataDocumentsRequest(token, `/data/${documentId}?includeRecords=false`, {}, options);
+}
+export async function updateDocumentMetadata(token, documentId, metadata, schema, options) {
+    await dataDocumentsRequest(token, `/data/${documentId}`, {
+        method: 'PUT',
+        body: JSON.stringify({ metadata, schema }),
+    }, options);
+}
+export async function getDocumentRoles(token, documentId, options) {
+    return dataDocumentsRequest(token, `/data/${documentId}/roles`, {}, options);
+}
+export async function updateDocumentRoles(token, documentId, roleIds, visibility, options) {
+    return dataDocumentsRequest(token, `/data/${documentId}/roles`, {
+        method: 'PUT',
+        body: JSON.stringify({ roleIds, visibility }),
+    }, options);
+}
+export async function ensureSchemaAndMetadata(token, documentId, schema, sourceApp, options) {
+    try {
+        const doc = await getDocumentDetails(token, documentId, options);
+        const existingSchema = doc.schema;
+        const needsSourceApp = !doc.sourceApp;
+        const existingRelationNames = Object.keys(existingSchema?.relations || {});
+        const newRelationNames = Object.keys(schema.relations || {});
+        const relationsChanged = (existingRelationNames.length === 0 && newRelationNames.length > 0) ||
+            existingRelationNames.length !== newRelationNames.length ||
+            !newRelationNames.every((name) => existingRelationNames.includes(name));
+        const existingGraphNode = existingSchema?.graphNode;
+        const newGraphNode = schema.graphNode;
+        const existingGraphRels = existingSchema?.graphRelationships || [];
+        const newGraphRels = schema.graphRelationships || [];
+        const graphChanged = existingGraphNode !== newGraphNode ||
+            existingGraphRels.length !== newGraphRels.length;
+        const fieldsChanged = haveFieldsChanged(existingSchema, schema);
+        const needsSchemaUpdate = relationsChanged || graphChanged || fieldsChanged;
+        if (needsSourceApp || needsSchemaUpdate) {
+            const existingMetadata = (doc.metadata || {});
+            const mergedMetadata = { ...existingMetadata, sourceApp };
+            await updateDocumentMetadata(token, documentId, mergedMetadata, schema, options);
+        }
+    }
+    catch (error) {
+        console.warn(`[data-documents] Failed to ensure schema for document ${documentId}:`, error);
+    }
+}
+/**
+ * Compare field definitions between existing and new schemas.
+ * Detects new fields, removed fields, type changes, and enum values changes.
+ */
+function haveFieldsChanged(existingSchema, newSchema) {
+    const existingFields = (existingSchema?.fields || {});
+    const newFields = (newSchema.fields || {});
+    const existingKeys = Object.keys(existingFields);
+    const newKeys = Object.keys(newFields);
+    if (existingKeys.length !== newKeys.length)
+        return true;
+    if (!newKeys.every((k) => existingKeys.includes(k)))
+        return true;
+    for (const key of newKeys) {
+        const oldField = existingFields[key];
+        const newField = newFields[key];
+        if (!oldField)
+            return true;
+        if (oldField.type !== newField.type)
+            return true;
+        const oldEnum = oldField.values || [];
+        const newEnum = newField.values || [];
+        if (oldEnum.length !== newEnum.length)
+            return true;
+        if (!newEnum.every((v, i) => oldEnum[i] === v))
+            return true;
+    }
+    return false;
+}
+// ==========================================================================
+// Generic Record Operations
+// ==========================================================================
+export async function queryRecords(token, documentId, queryOptions = {}, options) {
+    return dataDocumentsRequest(token, `/data/${documentId}/query`, {
+        method: 'POST',
+        body: JSON.stringify({
+            select: queryOptions.select,
+            where: queryOptions.where,
+            orderBy: queryOptions.orderBy,
+            limit: queryOptions.limit || 100,
+            offset: queryOptions.offset || 0,
+        }),
+    }, options);
+}
+export async function insertRecords(token, documentId, records, validate = true, options) {
+    return dataDocumentsRequest(token, `/data/${documentId}/records`, {
+        method: 'POST',
+        body: JSON.stringify({ records, validate }),
+    }, options);
+}
+export async function updateRecords(token, documentId, updates, where, validate = true, options) {
+    return dataDocumentsRequest(token, `/data/${documentId}/records`, {
+        method: 'PUT',
+        body: JSON.stringify({ updates, where, validate }),
+    }, options);
+}
+export async function deleteRecords(token, documentId, where, recordIds, options) {
+    return dataDocumentsRequest(token, `/data/${documentId}/records`, {
+        method: 'DELETE',
+        body: JSON.stringify({ where, recordIds }),
+    }, options);
+}
+// ==========================================================================
+// ensureDocuments - Generic document setup helper
+// ==========================================================================
+/**
+ * Ensure all configured documents exist. Creates missing ones and updates schemas.
+ *
+ * @param token - Bearer token from requireAuthWithTokenExchange
+ * @param config - Map of key -> { name, schema, visibility }
+ * @param sourceApp - App identifier for schema metadata
+ * @returns Map of key -> document ID
+ */
+export async function ensureDocuments(token, config, sourceApp, options) {
+    const documents = await listDataDocuments(token, options);
+    const result = {};
+    for (const [key, docConfig] of Object.entries(config)) {
+        const existing = documents.find((d) => d.name === docConfig.name);
+        const schema = { ...docConfig.schema, sourceApp };
+        if (!existing) {
+            const created = await createDataDocument(token, docConfig.name, schema, docConfig.visibility || 'shared', options);
+            result[key] = created.id;
+        }
+        else {
+            result[key] = existing.id;
+            await ensureSchemaAndMetadata(token, existing.id, schema, sourceApp, options);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=documents.js.map