@robosystems/client 0.2.13 → 0.2.15

package/sdk/sdk.gen.js

@@ -2,8 +2,8 @@
 // This file is auto-generated by @hey-api/openapi-ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.batchProcessQueries = exports.executeSpecificAgent = exports.getAgentMetadata = exports.autoSelectAgent = exports.listAgents = exports.syncConnection = exports.getConnection = exports.deleteConnection = exports.oauthCallback = exports.initOAuth = exports.createLinkToken = exports.exchangeLinkToken = exports.getConnectionOptions = exports.createConnection = exports.listConnections = exports.getOrgUsage = exports.getOrgLimits = exports.updateOrgMemberRole = exports.removeOrgMember = exports.inviteOrgMember = exports.listOrgMembers = exports.listOrgGraphs = exports.updateOrg = exports.getOrg = exports.createOrg = exports.listUserOrgs = exports.updateUserApiKey = exports.revokeUserApiKey = exports.createUserApiKey = exports.listUserApiKeys = exports.updateUserPassword = exports.updateUser = exports.getCurrentUser = exports.getServiceStatus = exports.getCaptchaConfig = exports.completeSsoAuth = exports.ssoTokenExchange = exports.generateSsoToken = exports.resetPassword = exports.validateResetToken = exports.forgotPassword = exports.checkPasswordStrength = exports.getPasswordPolicy = exports.verifyEmail = exports.resendVerificationEmail = exports.refreshAuthSession = exports.getCurrentAuthUser = exports.logoutUser = exports.loginUser = exports.registerUser = void 0;
-exports.listOrgSubscriptions = exports.createPortalSession = exports.getOrgBillingCustomer = exports.cancelOperation = exports.getOperationStatus = exports.streamOperationEvents = exports.getServiceOfferings = exports.selectGraph = exports.getAvailableGraphTiers = exports.getAvailableExtensions = exports.createGraph = exports.getGraphs = exports.queryTables = exports.ingestTables = exports.updateFileStatus = exports.getFileInfo = exports.deleteFile = exports.getUploadUrl = exports.listTableFiles = exports.listTables = exports.upgradeSubscription = exports.createRepositorySubscription = exports.getGraphSubscription = exports.getSubgraphQuota = exports.getSubgraphInfo = exports.deleteSubgraph = exports.createSubgraph = exports.listSubgraphs = exports.getGraphLimits = exports.getDatabaseInfo = exports.getDatabaseHealth = exports.checkStorageLimits = exports.getStorageUsage = exports.checkCreditBalance = exports.listCreditTransactions = exports.getCreditSummary = exports.validateSchema = exports.exportGraphSchema = exports.getGraphSchema = exports.executeCypherQuery = exports.getGraphUsageAnalytics = exports.getGraphMetrics = exports.getBackupStats = exports.restoreBackup = exports.getBackupDownloadUrl = exports.createBackup = exports.listBackups = exports.callMcpTool = exports.listMcpTools = exports.recommendAgent = void 0;
-exports.getCheckoutStatus = exports.createCheckoutSession = exports.getOrgUpcomingInvoice = exports.listOrgInvoices = exports.cancelOrgSubscription = exports.getOrgSubscription = void 0;
+exports.cancelOperation = exports.getOperationStatus = exports.streamOperationEvents = exports.getServiceOfferings = exports.selectGraph = exports.getAvailableGraphTiers = exports.getAvailableExtensions = exports.createGraph = exports.getGraphs = exports.updateFile = exports.getFile = exports.deleteFile = exports.createFileUpload = exports.listFiles = exports.materializeGraph = exports.getMaterializationStatus = exports.saveView = exports.createView = exports.queryTables = exports.listTables = exports.upgradeSubscription = exports.createRepositorySubscription = exports.getGraphSubscription = exports.getSubgraphQuota = exports.getSubgraphInfo = exports.deleteSubgraph = exports.createSubgraph = exports.listSubgraphs = exports.getGraphLimits = exports.getDatabaseInfo = exports.getDatabaseHealth = exports.checkStorageLimits = exports.getStorageUsage = exports.checkCreditBalance = exports.listCreditTransactions = exports.getCreditSummary = exports.validateSchema = exports.exportGraphSchema = exports.getGraphSchema = exports.executeCypherQuery = exports.getGraphUsageAnalytics = exports.getGraphMetrics = exports.getBackupStats = exports.restoreBackup = exports.getBackupDownloadUrl = exports.createBackup = exports.listBackups = exports.callMcpTool = exports.listMcpTools = exports.recommendAgent = void 0;
+exports.getCheckoutStatus = exports.createCheckoutSession = exports.getOrgUpcomingInvoice = exports.listOrgInvoices = exports.cancelOrgSubscription = exports.getOrgSubscription = exports.listOrgSubscriptions = exports.createPortalSession = exports.getOrgBillingCustomer = void 0;
 const client_gen_1 = require("./client.gen");
 /**
  * Register New User
@@ -1103,6 +1103,13 @@ exports.listAgents = listAgents;
  * - Leverage conversation history for contextual understanding
  * - Enable RAG for knowledge base enrichment
  *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * Agents operate on the specified graph/subgraph's data independently. RAG enrichment
+ * and knowledge base search are scoped to the specific graph/subgraph.
+ *
  * See request/response examples in the "Examples" dropdown below.
  */
 const autoSelectAgent = (options) => {
@@ -1287,6 +1294,13 @@ exports.recommendAgent = recommendAgent;
  * - User permissions and subscription tier
  * - Backend capabilities (Kuzu, Neo4j, etc.)
  *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * The returned tool list is identical for parent graphs and subgraphs, as all
+ * MCP tools work uniformly across graph boundaries.
+ *
  * **Note:**
  * MCP tool listing is included - no credit consumption required.
  */
@@ -1341,6 +1355,13 @@ exports.listMcpTools = listMcpTools;
  * - `408 Request Timeout`: Tool execution exceeded timeout
  * - Clients should implement exponential backoff on errors
  *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * MCP tools operate on the specified graph/subgraph independently. Each subgraph
+ * has its own schema, data, and can be queried separately via MCP.
+ *
  * **Credit Model:**
  * MCP tool execution is included - no credit consumption required. Database
  * operations (queries, schema inspection, analytics) are completely free.
@@ -1691,11 +1712,14 @@ const getGraphUsageAnalytics = (options) => {
 };
 exports.getGraphUsageAnalytics = getGraphUsageAnalytics;
 /**
- * Execute Cypher Query (Read-Only)
- * Execute a read-only Cypher query with intelligent response optimization.
+ * Execute Cypher Query
+ * Execute a Cypher query with intelligent response optimization.
  *
- * **IMPORTANT: This endpoint is READ-ONLY.** Write operations (CREATE, MERGE, SET, DELETE) are not allowed.
- * To load data into your graph, use the staging pipeline:
+ * **IMPORTANT: Write operations depend on graph type:**
+ * - **Main Graphs**: READ-ONLY. Write operations (CREATE, MERGE, SET, DELETE) are not allowed.
+ * - **Subgraphs**: WRITE-ENABLED. Full Cypher write operations are supported for development and report creation.
+ *
+ * To load data into main graphs, use the staging pipeline:
  * 1. Create file upload: `POST /v1/graphs/{graph_id}/tables/{table_name}/files`
  * 2. Ingest to graph: `POST /v1/graphs/{graph_id}/tables/ingest`
  *
@@ -1748,6 +1772,12 @@ exports.getGraphUsageAnalytics = getGraphUsageAnalytics;
  * - `503 Service Unavailable`: Circuit breaker open or SSE disabled
  * - Clients should implement exponential backoff
  *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * Subgraphs share the same instance as their parent graph and have independent data.
+ *
  * **Note:**
  * Query operations are included - no credit consumption required.
  * Queue position is based on subscription tier for priority.
@@ -1810,6 +1840,14 @@ exports.executeCypherQuery = executeCypherQuery;
  * Property discovery is limited to 10 properties per node type for performance.
  * For complete schema definitions, use `/schema/export`.
  *
+ * ## Subgraph Support
+ *
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * Each subgraph has independent schema and data. The returned schema reflects
+ * only the specified graph/subgraph's actual structure.
+ *
  * This operation is included - no credit consumption required.
  */
 const getGraphSchema = (options) => {
@@ -1919,6 +1957,13 @@ exports.exportGraphSchema = exportGraphSchema;
  * - Performance problems
  * - Naming conflicts
  *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * Schema validation is performed against the specified graph/subgraph's current
+ * schema and data structure.
+ *
  * This operation is included - no credit consumption required.
  */
 const validateSchema = (options) => {
@@ -2115,6 +2160,13 @@ exports.checkStorageLimits = checkStorageLimits;
  * - **Resource Usage**: Memory and storage consumption
  * - **Alerts**: Active warnings or issues
  *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * Health metrics are specific to the requested graph/subgraph. Subgraphs share the
+ * same physical instance as their parent but have independent health indicators.
+ *
  * This endpoint provides essential monitoring data for operational visibility.
  */
 const getDatabaseHealth = (options) => {
@@ -2153,6 +2205,13 @@ exports.getDatabaseHealth = getDatabaseHealth;
  * - **Backup Status**: Backup availability and recency
  * - **Timestamps**: Creation and modification dates
  *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * Returned metrics are specific to the requested graph/subgraph. Subgraphs have
+ * independent size, node/relationship counts, and backup status.
+ *
  * This endpoint provides essential database information for capacity planning and monitoring.
  */
 const getDatabaseInfo = (options) => {
@@ -2186,7 +2245,7 @@ exports.getDatabaseInfo = getDatabaseInfo;
  *
  * This unified endpoint provides all limits in one place for easier client integration.
  *
- * **Note**: Limits vary based on subscription tier (Standard, Enterprise, Premium).
+ * **Note**: Limits vary based on subscription tier (kuzu-standard, kuzu-large, kuzu-xlarge).
  */
 const getGraphLimits = (options) => {
     return (options.client ?? client_gen_1.client).get({
@@ -2237,7 +2296,7 @@ const listSubgraphs = (options) => {
 exports.listSubgraphs = listSubgraphs;
 /**
  * Create Subgraph
- * Create a new subgraph within a parent graph.
+ * Create a new subgraph within a parent graph, with optional data forking.
  *
  * **Requirements:**
  * - Valid authentication
@@ -2247,8 +2306,23 @@ exports.listSubgraphs = listSubgraphs;
  * - Must be within subgraph quota limits
  * - Subgraph name must be unique within the parent graph
  *
+ * **Fork Mode:**
+ * When `fork_parent=true`, the operation:
+ * - Returns immediately with an operation_id for SSE monitoring
+ * - Copies data from parent graph to the new subgraph
+ * - Supports selective forking via metadata.fork_options
+ * - Tracks progress in real-time via SSE
+ *
  * **Returns:**
- * - Created subgraph details including its unique ID
+ * - Without fork: Immediate SubgraphResponse with created subgraph details
+ * - With fork: Operation response with SSE monitoring endpoint
+ *
+ * **Subgraph ID format:** `{parent_id}_{subgraph_name}` (e.g., kg1234567890abcdef_dev)
+ *
+ * **Usage:**
+ * - Subgraphs share parent's credit pool
+ * - Subgraph ID can be used in all standard `/v1/graphs/{graph_id}*` endpoints
+ * - Permissions inherited from parent graph
  */
 const createSubgraph = (options) => {
     return (options.client ?? client_gen_1.client).post({
@@ -2278,6 +2352,7 @@ exports.createSubgraph = createSubgraph;
  * **Requirements:**
  * - Must be a valid subgraph (not parent graph)
  * - User must have admin access to parent graph
+ * - Subgraph name must be alphanumeric (1-20 characters)
  * - Optional backup before deletion
  *
  * **Deletion Options:**
@@ -2291,6 +2366,11 @@ exports.createSubgraph = createSubgraph;
  * **Backup Location:**
  * If backup requested, stored in S3 Kuzu database bucket at:
  * `s3://{kuzu_s3_bucket}/{instance_id}/{database_name}_{timestamp}.backup`
+ *
+ * **Notes:**
+ * - Use the subgraph name (e.g., 'dev', 'staging') not the full subgraph ID
+ * - Deletion does not affect parent graph's credit pool or permissions
+ * - Backup creation consumes credits from parent graph's allocation
  */
 const deleteSubgraph = (options) => {
     return (options.client ?? client_gen_1.client).delete({
@@ -2304,7 +2384,7 @@ const deleteSubgraph = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/subgraphs/{subgraph_id}',
+        url: '/v1/graphs/{graph_id}/subgraphs/{subgraph_name}',
         ...options,
         headers: {
             'Content-Type': 'application/json',
@@ -2319,6 +2399,7 @@ exports.deleteSubgraph = deleteSubgraph;
  *
  * **Requirements:**
  * - User must have read access to parent graph
+ * - Subgraph name must be alphanumeric (1-20 characters)
  *
  * **Response includes:**
  * - Full subgraph metadata
@@ -2334,6 +2415,10 @@ exports.deleteSubgraph = deleteSubgraph;
  * - Edge count
  * - Database size on disk
  * - Schema information
+ *
+ * **Note:**
+ * Use the subgraph name (e.g., 'dev', 'staging') not the full subgraph ID.
+ * The full ID is returned in the response (e.g., 'kg0123456789abcdef_dev').
  */
 const getSubgraphInfo = (options) => {
     return (options.client ?? client_gen_1.client).get({
@@ -2347,7 +2432,7 @@ const getSubgraphInfo = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/subgraphs/{subgraph_id}/info',
+        url: '/v1/graphs/{graph_id}/subgraphs/{subgraph_name}/info',
         ...options
     });
 };
@@ -2528,44 +2613,66 @@ const listTables = (options) => {
 };
 exports.listTables = listTables;
 /**
- * List Files in Staging Table
- * List all files uploaded to a staging table with comprehensive metadata.
+ * Query Staging Tables with SQL
+ * Execute SQL queries on DuckDB staging tables for data inspection and validation.
  *
- * Get a complete inventory of all files in a staging table, including upload status,
- * file sizes, row counts, and S3 locations. Essential for monitoring upload progress
- * and validating data before ingestion.
+ * Query raw staging data directly with SQL before ingestion into the graph database.
+ * Useful for data quality checks, validation, and exploratory analysis.
+ *
+ * **Security Best Practice - Use Parameterized Queries:**
+ * ALWAYS use query parameters instead of string concatenation to prevent SQL injection:
+ * - ✅ SAFE: `SELECT * FROM Entity WHERE type = ? LIMIT ?` with `parameters: ["Company", 100]`
+ * - ❌ UNSAFE: `SELECT * FROM Entity WHERE type = 'Company' LIMIT 100` with user input concatenated into SQL string
+ *
+ * Query parameters provide automatic escaping and type safety. Use `?` placeholders with parameters array.
  *
  * **Use Cases:**
- * - Monitor file upload progress
- * - Verify files are ready for ingestion
- * - Check file formats and sizes
- * - Track storage usage per table
- * - Identify failed or incomplete uploads
- * - Pre-ingestion validation
+ * - Validate data quality before graph ingestion
+ * - Inspect row-level data for debugging
+ * - Run analytics on staging tables
+ * - Check for duplicates, nulls, or data issues
+ * - Preview data transformations
  *
- * **Returned Metadata:**
- * - File ID, name, and format (parquet, csv, json)
- * - Size in bytes and row count (if available)
- * - Upload status and method
- * - Creation and upload timestamps
- * - S3 key for reference
+ * **Workflow:**
+ * 1. Upload data files via `POST /tables/{table_name}/files`
+ * 2. Query staging tables to validate: `POST /tables/query`
+ * 3. Fix any data issues by re-uploading
+ * 4. Ingest validated data: `POST /tables/ingest`
  *
- * **Upload Status Values:**
- * - `pending`: Upload URL generated, awaiting upload
- * - `uploaded`: Successfully uploaded, ready for ingestion
- * - `disabled`: Excluded from ingestion
- * - `archived`: Soft deleted
- * - `failed`: Upload failed
+ * **Supported SQL:**
+ * - Full DuckDB SQL syntax
+ * - SELECT, JOIN, WHERE, GROUP BY, ORDER BY
+ * - Aggregations, window functions, CTEs
+ * - Multiple table joins across staging area
  *
- * **Important Notes:**
- * - Only `uploaded` files are ingested
- * - Check `row_count` to estimate data volume
- * - Use `total_size_bytes` for storage monitoring
- * - Files with `failed` status should be deleted and re-uploaded
- * - File listing is included - no credit consumption
+ * **Common Operations:**
+ * - Count rows: `SELECT COUNT(*) FROM Entity`
+ * - Filter by type: `SELECT * FROM Entity WHERE entity_type = ? LIMIT ?` with `parameters: ["Company", 100]`
+ * - Check for nulls: `SELECT * FROM Entity WHERE name IS NULL LIMIT 10`
+ * - Find duplicates: `SELECT identifier, COUNT(*) as cnt FROM Entity GROUP BY identifier HAVING COUNT(*) > 1`
+ * - Filter amounts: `SELECT * FROM Transaction WHERE amount > ? AND date >= ?` with `parameters: [1000, "2024-01-01"]`
+ *
+ * **Limits:**
+ * - Query timeout: 30 seconds
+ * - Result limit: 10,000 rows (use LIMIT clause)
+ * - Read-only: No INSERT, UPDATE, DELETE
+ * - User's tables only: Cannot query other users' data
+ *
+ * **Subgraph Support:**
+ * This endpoint accepts both parent graph IDs and subgraph IDs.
+ * - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+ * - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+ * Each subgraph has its own independent staging tables.
+ *
+ * **Shared Repositories:**
+ * Shared repositories (SEC, etc.) do not allow direct SQL queries.
+ * Use the graph query endpoint instead: `POST /v1/graphs/{graph_id}/query`
+ *
+ * **Note:**
+ * Staging table queries are included - no credit consumption
  */
-const listTableFiles = (options) => {
-    return (options.client ?? client_gen_1.client).get({
+const queryTables = (options) => {
+    return (options.client ?? client_gen_1.client).post({
         security: [
             {
                 name: 'X-API-Key',
@@ -2576,48 +2683,35 @@ const listTableFiles = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/{table_name}/files',
-        ...options
+        url: '/v1/graphs/{graph_id}/tables/query',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options.headers
+        }
     });
 };
-exports.listTableFiles = listTableFiles;
+exports.queryTables = queryTables;
 /**
- * Get File Upload URL
- * Generate a presigned S3 URL for secure file upload.
- *
- * Initiates file upload to a staging table by generating a secure, time-limited
- * presigned S3 URL. Files are uploaded directly to S3, bypassing the API for
- * optimal performance.
+ * Create View
+ * Generate financial report view from data source (dual-mode support).
  *
- * **Upload Workflow:**
- * 1. Call this endpoint to get presigned URL
- * 2. PUT file directly to S3 URL
- * 3. Call PATCH /tables/files/{file_id} with status='uploaded'
- * 4. Backend validates file and calculates metrics
- * 5. File ready for ingestion
+ * **Mode 1: Transaction Aggregation (generate_from_transactions)**
+ * - Aggregates raw transaction data to trial balance
+ * - Creates facts on-demand
+ * - Shows real-time reporting from source of truth
  *
- * **Supported Formats:**
- * - Parquet (`application/x-parquet` with `.parquet` extension)
- * - CSV (`text/csv` with `.csv` extension)
- * - JSON (`application/json` with `.json` extension)
- *
- * **Validation:**
- * - File extension must match content type
- * - File name 1-255 characters
- * - No path traversal characters (.. / \)
- * - Auto-creates table if it doesn't exist
- *
- * **Auto-Table Creation:**
- * Tables are automatically created on first file upload with type inferred from name
- * (e.g., "Transaction" → relationship) and empty schema populated during ingestion.
+ * **Mode 2: Existing Facts (pivot_existing_facts)**
+ * - Queries existing Fact nodes
+ * - Supports multi-dimensional analysis
+ * - Works with SEC filings and pre-computed facts
  *
- * **Important Notes:**
- * - Presigned URLs expire (default: 1 hour)
- * - Use appropriate Content-Type header when uploading to S3
- * - File extension must match content type
- * - Upload URL generation is included - no credit consumption
+ * Both modes:
+ * - Build FactGrid from data
+ * - Generate pivot table presentation
+ * - Return consistent response format
  */
-const getUploadUrl = (options) => {
+const createView = (options) => {
     return (options.client ?? client_gen_1.client).post({
         security: [
             {
@@ -2629,7 +2723,7 @@ const getUploadUrl = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/{table_name}/files',
+        url: '/v1/graphs/{graph_id}/views',
         ...options,
         headers: {
             'Content-Type': 'application/json',
@@ -2637,43 +2731,41 @@ const getUploadUrl = (options) => {
         }
     });
 };
-exports.getUploadUrl = getUploadUrl;
+exports.createView = createView;
 /**
- * Delete File from Staging
- * Delete a file from S3 storage and database tracking.
+ * Save View
+ * Save or update view as materialized report in the graph.
  *
- * Remove unwanted, duplicate, or incorrect files from staging tables before ingestion.
- * The file is deleted from both S3 and database tracking, and table statistics
- * are automatically recalculated.
+ * Converts computed view results into persistent Report, Fact, and Structure nodes.
+ * This establishes what data exists in the subgraph, which then defines what
+ * needs to be exported for publishing to the parent graph.
  *
- * **Use Cases:**
- * - Remove duplicate uploads
- * - Delete files with incorrect data
- * - Clean up failed uploads
- * - Fix data quality issues before ingestion
- * - Manage storage usage
+ * **Create Mode** (no report_id provided):
+ * - Generates new report_id from entity + period + report type
+ * - Creates new Report, Facts, and Structures
  *
- * **What Happens:**
- * 1. File deleted from S3 storage
- * 2. Database tracking record removed
- * 3. Table statistics recalculated (file count, size, row count)
- * 4. DuckDB automatically excludes file from future queries
+ * **Update Mode** (report_id provided):
+ * - Deletes all existing Facts and Structures for the report
+ * - Updates Report metadata
+ * - Creates fresh Facts and Structures from current view
+ * - Useful for refreshing reports with updated data or view configurations
  *
- * **Security:**
- * - Write access required (verified via auth)
- * - Shared repositories block file deletions
- * - Full audit trail of deletion operations
- * - Cannot delete after ingestion to graph
+ * **This is NOT publishing** - it only creates nodes in the subgraph workspace.
+ * Publishing (export → parquet → parent ingest) happens separately.
  *
- * **Important Notes:**
- * - Delete files before ingestion for best results
- * - Table statistics update automatically
- * - No need to refresh DuckDB - exclusion is automatic
- * - Consider re-uploading corrected version after deletion
- * - File deletion is included - no credit consumption
+ * Creates/Updates:
+ * - Report node with metadata
+ * - Fact nodes with all aspects (period, entity, element, unit)
+ * - PresentationStructure nodes (how facts are displayed)
+ * - CalculationStructure nodes (how facts roll up)
+ *
+ * Returns:
+ * - report_id: Unique identifier used as parquet export prefix
+ * - parquet_export_prefix: Filename prefix for future exports
+ * - All created facts and structures
  */
-const deleteFile = (options) => {
-    return (options.client ?? client_gen_1.client).delete({
+const saveView = (options) => {
+    return (options.client ?? client_gen_1.client).post({
         security: [
             {
                 name: 'X-API-Key',
@@ -2684,30 +2776,43 @@ const deleteFile = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/files/{file_id}',
-        ...options
+        url: '/v1/graphs/{graph_id}/views/save',
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options.headers
+        }
     });
 };
-exports.deleteFile = deleteFile;
+exports.saveView = saveView;
 /**
- * Get File Information
- * Get detailed information about a specific file.
+ * Get Materialization Status
+ * Get current materialization status for the graph.
  *
- * Retrieve comprehensive metadata for a single file, including upload status,
- * size, row count, and timestamps. Useful for validating individual files
- * before ingestion.
+ * Shows whether the graph is stale (DuckDB has changes not yet in graph database),
+ * when it was last materialized, and how long since last materialization.
+ *
+ * **Status Information:**
+ * - Whether graph is currently stale
+ * - Reason for staleness if applicable
+ * - When graph became stale
+ * - When graph was last materialized
+ * - Total materialization count
+ * - Hours since last materialization
  *
  * **Use Cases:**
- * - Validate file upload completion
- * - Check file metadata before ingestion
- * - Debug upload issues
- * - Verify file format and size
- * - Track file lifecycle
+ * - Decide if materialization is needed
+ * - Monitor graph freshness
+ * - Track materialization history
+ * - Understand data pipeline state
  *
- * **Note:**
- * File info retrieval is included - no credit consumption
+ * **Important Notes:**
+ * - Stale graph means DuckDB has changes not in graph
+ * - Graph becomes stale after file deletions
+ * - Materialization clears staleness
+ * - Status retrieval is included - no credit consumption
  */
-const getFileInfo = (options) => {
+const getMaterializationStatus = (options) => {
     return (options.client ?? client_gen_1.client).get({
         security: [
             {
@@ -2719,52 +2824,67 @@ const getFileInfo = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/files/{file_id}',
+        url: '/v1/graphs/{graph_id}/materialize/status',
         ...options
     });
 };
-exports.getFileInfo = getFileInfo;
+exports.getMaterializationStatus = getMaterializationStatus;
 /**
- * Update File Upload Status
- * Update file status after upload completes.
+ * Materialize Graph from DuckDB
+ * Rebuild entire graph from DuckDB staging tables (materialized view pattern).
  *
- * Marks files as uploaded after successful S3 upload. The backend validates
- * the file, calculates size and row count, enforces storage limits, and
- * registers the DuckDB table for queries.
+ * This endpoint rebuilds the complete graph database from the current state of DuckDB
+ * staging tables. It automatically discovers all tables, ingests them in the correct
+ * order (nodes before relationships), and clears the staleness flag.
  *
- * **Status Values:**
- * - `uploaded`: File successfully uploaded to S3 (triggers validation)
- * - `disabled`: Exclude file from ingestion
- * - `archived`: Soft delete file
- *
- * **What Happens on 'uploaded' Status:**
- * 1. Verify file exists in S3
- * 2. Calculate actual file size
- * 3. Enforce tier storage limits
- * 4. Calculate or estimate row count
- * 5. Update table statistics
- * 6. Register DuckDB external table
- * 7. File ready for ingestion
- *
- * **Row Count Calculation:**
- * - **Parquet**: Exact count from file metadata
- * - **CSV**: Count rows (minus header)
- * - **JSON**: Count array elements
- * - **Fallback**: Estimate from file size if reading fails
- *
- * **Storage Limits:**
- * Enforced per subscription tier. Returns HTTP 413 if limit exceeded.
- * Check current usage before large uploads.
+ * **When to Use:**
+ * - After batch uploads (files uploaded with ingest_to_graph=false)
+ * - After cascade file deletions (graph marked stale)
+ * - To ensure graph consistency with DuckDB state
+ * - Periodic full refresh
  *
- * **Important Notes:**
- * - Always call this after S3 upload completes
- * - Check response for actual row count
- * - Storage limit errors (413) mean tier upgrade needed
- * - DuckDB registration failures are non-fatal (retried later)
- * - Status updates are included - no credit consumption
+ * **What Happens:**
+ * 1. Discovers all tables for the graph from PostgreSQL registry
+ * 2. Sorts tables (nodes before relationships)
+ * 3. Ingests all tables from DuckDB to graph in order
+ * 4. Clears staleness flag on success
+ * 5. Returns detailed materialization report
+ *
+ * **Staleness Check:**
+ * By default, only materializes if graph is stale (after deletions or missed ingestions).
+ * Use `force=true` to rebuild regardless of staleness.
+ *
+ * **Rebuild Feature:**
+ * Setting `rebuild=true` regenerates the entire graph database from scratch:
+ * - Deletes existing graph database
+ * - Recreates with fresh schema from active GraphSchema
+ * - Ingests all data files
+ * - Safe operation - DuckDB is source of truth
+ * - Useful for schema changes or data corrections
+ * - Graph marked as 'rebuilding' during process
+ *
+ * **Table Ordering:**
+ * Node tables (PascalCase) are ingested before relationship tables (UPPERCASE) to
+ * ensure referential integrity.
+ *
+ * **Error Handling:**
+ * With `ignore_errors=true` (default), continues materializing even if individual
+ * rows fail. Failed rows are logged but don't stop the process.
+ *
+ * **Concurrency Control:**
+ * Only one materialization can run per graph at a time. If another materialization is in progress,
+ * you'll receive a 409 Conflict error. The distributed lock automatically expires after
+ * the configured TTL (default: 1 hour) to prevent deadlocks from failed materializations.
+ *
+ * **Performance:**
+ * Full graph materialization can take minutes for large datasets. Consider running
+ * during off-peak hours for production systems.
+ *
+ * **Credits:**
+ * Materialization is included - no credit consumption
  */
-const updateFileStatus = (options) => {
-    return (options.client ?? client_gen_1.client).patch({
+const materializeGraph = (options) => {
+    return (options.client ?? client_gen_1.client).post({
         security: [
             {
                 name: 'X-API-Key',
@@ -2775,7 +2895,7 @@ const updateFileStatus = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/files/{file_id}',
+        url: '/v1/graphs/{graph_id}/materialize',
         ...options,
         headers: {
             'Content-Type': 'application/json',
@@ -2783,66 +2903,89 @@ const updateFileStatus = (options) => {
         }
     });
 };
-exports.updateFileStatus = updateFileStatus;
+exports.materializeGraph = materializeGraph;
 /**
- * Ingest Tables to Graph
- * Load all files from S3 into DuckDB staging tables and ingest into Kuzu graph database.
+ * List Files in Graph
+ * List all files in the graph with optional filtering.
  *
- * Orchestrates the complete data pipeline from S3 staging files into the Kuzu graph database.
- * Processes all tables in a single bulk operation with comprehensive error handling and metrics.
+ * Get a complete inventory of files across all tables or filtered by table name,
+ * status, or other criteria. Files are first-class resources with independent lifecycle.
+ *
+ * **Query Parameters:**
+ * - `table_name` (optional): Filter by table name
+ * - `status` (optional): Filter by upload status (uploaded, pending, failed, etc.)
  *
  * **Use Cases:**
- * - Initial graph population from uploaded data
- * - Incremental data updates with new files
- * - Complete database rebuild from source files
- * - Recovery from failed ingestion attempts
+ * - Monitor file upload progress across all tables
+ * - Verify files are ready for ingestion
+ * - Check file metadata and sizes
+ * - Track storage usage per graph
+ * - Identify failed or incomplete uploads
+ * - Audit file provenance
  *
- * **Workflow:**
- * 1. Upload data files via `POST /tables/{table_name}/files`
- * 2. Files are validated and marked as 'uploaded'
- * 3. Trigger ingestion: `POST /tables/ingest`
- * 4. DuckDB staging tables created from S3 patterns
- * 5. Data copied row-by-row from DuckDB to Kuzu
- * 6. Per-table results and metrics returned
+ * **Returned Metadata:**
+ * - File ID, name, and format (parquet, csv, json)
+ * - Size in bytes and row count (if available)
+ * - Upload status and timestamps
+ * - DuckDB and graph ingestion status
+ * - Table association
  *
- * **Rebuild Feature:**
- * Setting `rebuild=true` regenerates the entire graph database from scratch:
- * - Deletes existing Kuzu database
- * - Recreates with fresh schema from active GraphSchema
- * - Ingests all data files
- * - Safe operation - S3 is source of truth
- * - Useful for schema changes or data corrections
- * - Graph marked as 'rebuilding' during process
+ * **File Lifecycle Tracking:**
+ * Multi-layer status across S3 → DuckDB → Graph pipeline
  *
- * **Error Handling:**
- * - Per-table error isolation with `ignore_errors` flag
- * - Partial success support (some tables succeed, some fail)
- * - Detailed error reporting per table
- * - Graph status tracking throughout process
- * - Automatic failure recovery and cleanup
+ * **Important Notes:**
+ * - Files are graph-scoped, not table-scoped
+ * - Use table_name parameter to filter by table
+ * - File listing is included - no credit consumption
+ */
+const listFiles = (options) => {
+    return (options.client ?? client_gen_1.client).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            },
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/v1/graphs/{graph_id}/files',
+        ...options
+    });
+};
+exports.listFiles = listFiles;
+/**
+ * Create File Upload
+ * Generate presigned S3 URL for file upload.
  *
- * **Performance:**
- * - Processes all tables in sequence
- * - Each table timed independently
- * - Total execution metrics provided
- * - Scales to thousands of files
- * - Optimized for large datasets
+ * Initiate file upload by generating a secure, time-limited presigned S3 URL.
+ * Files are first-class resources uploaded directly to S3.
  *
- * **Concurrency Control:**
- * Only one ingestion can run per graph at a time. If another ingestion is in progress,
- * you'll receive a 409 Conflict error. The distributed lock automatically expires after
- * the configured TTL (default: 1 hour) to prevent deadlocks from failed ingestions.
+ * **Request Body:**
+ * - `file_name`: Name of the file (1-255 characters)
+ * - `file_format`: Format (parquet, csv, json)
+ * - `table_name`: Table to associate file with
+ *
+ * **Upload Workflow:**
+ * 1. Call this endpoint to get presigned URL
+ * 2. PUT file directly to S3 URL
+ * 3. Call PATCH /files/{file_id} with status='uploaded'
+ * 4. Backend validates and stages in DuckDB immediately
+ * 5. Background task ingests to graph
+ *
+ * **Supported Formats:**
+ * - Parquet, CSV, JSON
+ *
+ * **Auto-Table Creation:**
+ * Tables are automatically created if they don't exist.
  *
  * **Important Notes:**
- * - Only files with 'uploaded' status are processed
- * - Tables with no uploaded files are skipped
- * - Use `ignore_errors=false` for strict validation
- * - Monitor progress via per-table results
- * - Check graph metadata for rebuild status
- * - Wait for current ingestion to complete before starting another
- * - Table ingestion is included - no credit consumption
- */
-const ingestTables = (options) => {
+ * - Presigned URLs expire (default: 1 hour)
+ * - Files are graph-scoped, independent resources
+ * - Upload URL generation is included - no credit consumption
+ */
+const createFileUpload = (options) => {
     return (options.client ?? client_gen_1.client).post({
         security: [
             {
@@ -2854,7 +2997,7 @@ const ingestTables = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/ingest',
+        url: '/v1/graphs/{graph_id}/files',
         ...options,
         headers: {
             'Content-Type': 'application/json',
@@ -2862,62 +3005,102 @@ const ingestTables = (options) => {
         }
     });
 };
-exports.ingestTables = ingestTables;
+exports.createFileUpload = createFileUpload;
 /**
- * Query Staging Tables with SQL
- * Execute SQL queries on DuckDB staging tables for data inspection and validation.
+ * Delete File
+ * Delete file from all layers.
  *
- * Query raw staging data directly with SQL before ingestion into the graph database.
- * Useful for data quality checks, validation, and exploratory analysis.
+ * Remove file from S3, database tracking, and optionally from DuckDB and graph.
+ * Files are deleted by file_id, independent of table context.
  *
- * **Security Best Practice - Use Parameterized Queries:**
- * ALWAYS use query parameters instead of string concatenation to prevent SQL injection:
- * - ✅ SAFE: `SELECT * FROM Entity WHERE type = ? LIMIT ?` with `parameters: ["Company", 100]`
- * - ❌ UNSAFE: `SELECT * FROM Entity WHERE type = 'Company' LIMIT 100` with user input concatenated into SQL string
+ * **Query Parameters:**
+ * - `cascade` (optional, default=false): Delete from all layers including DuckDB
  *
- * Query parameters provide automatic escaping and type safety. Use `?` placeholders with parameters array.
+ * **What Happens (cascade=false):**
+ * 1. File deleted from S3
+ * 2. Database record removed
+ * 3. Table statistics updated
+ *
+ * **What Happens (cascade=true):**
+ * 1. File data deleted from all DuckDB tables (by file_id)
+ * 2. Graph marked as stale
+ * 3. File deleted from S3
+ * 4. Database record removed
+ * 5. Table statistics updated
  *
  * **Use Cases:**
- * - Validate data quality before graph ingestion
- * - Inspect row-level data for debugging
- * - Run analytics on staging tables
- * - Check for duplicates, nulls, or data issues
- * - Preview data transformations
+ * - Remove incorrect or duplicate files
+ * - Clean up failed uploads
+ * - Delete files before graph ingestion
+ * - Surgical data removal with cascade
  *
- * **Workflow:**
- * 1. Upload data files via `POST /tables/{table_name}/files`
- * 2. Query staging tables to validate: `POST /tables/query`
- * 3. Fix any data issues by re-uploading
- * 4. Ingest validated data: `POST /tables/ingest`
+ * **Security:**
+ * - Write access required
+ * - Shared repositories block deletions
+ * - Full audit trail
  *
- * **Supported SQL:**
- * - Full DuckDB SQL syntax
- * - SELECT, JOIN, WHERE, GROUP BY, ORDER BY
- * - Aggregations, window functions, CTEs
- * - Multiple table joins across staging area
+ * **Important:**
+ * - Use cascade=true for immediate DuckDB cleanup
+ * - Graph rebuild recommended after cascade deletion
+ * - File deletion is included - no credit consumption
+ */
+const deleteFile = (options) => {
+    return (options.client ?? client_gen_1.client).delete({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            },
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/v1/graphs/{graph_id}/files/{file_id}',
+        ...options
+    });
+};
+exports.deleteFile = deleteFile;
+/**
+ * Get File Information
+ * Get detailed information about a specific file.
  *
- * **Common Operations:**
- * - Count rows: `SELECT COUNT(*) FROM Entity`
- * - Filter by type: `SELECT * FROM Entity WHERE entity_type = ? LIMIT ?` with `parameters: ["Company", 100]`
- * - Check for nulls: `SELECT * FROM Entity WHERE name IS NULL LIMIT 10`
- * - Find duplicates: `SELECT identifier, COUNT(*) as cnt FROM Entity GROUP BY identifier HAVING COUNT(*) > 1`
- * - Filter amounts: `SELECT * FROM Transaction WHERE amount > ? AND date >= ?` with `parameters: [1000, "2024-01-01"]`
+ * Retrieve comprehensive metadata for a single file by file_id, independent of
+ * table context. Files are first-class resources with complete lifecycle tracking.
  *
- * **Limits:**
- * - Query timeout: 30 seconds
- * - Result limit: 10,000 rows (use LIMIT clause)
- * - Read-only: No INSERT, UPDATE, DELETE
- * - User's tables only: Cannot query other users' data
+ * **Returned Information:**
+ * - File ID, name, format, size
+ * - Upload status and timestamps
+ * - **Enhanced Multi-Layer Status** (new in this version):
+ * - S3 layer: upload_status, uploaded_at, size_bytes, row_count
+ * - DuckDB layer: duckdb_status, duckdb_staged_at, duckdb_row_count
+ * - Graph layer: graph_status, graph_ingested_at
+ * - Table association
+ * - S3 location
+ *
+ * **Multi-Layer Pipeline Visibility:**
+ * The `layers` object provides independent status tracking across the three-tier
+ * data pipeline:
+ * - **S3 (Immutable Source)**: File upload and validation
+ * - **DuckDB (Mutable Staging)**: Immediate queryability with file provenance
+ * - **Graph (Immutable View)**: Optional graph database materialization
+ *
+ * Each layer shows its own status, timestamp, and row count (where applicable),
+ * enabling precise debugging and monitoring of the data ingestion flow.
  *
- * **Shared Repositories:**
- * Shared repositories (SEC, etc.) do not allow direct SQL queries.
- * Use the graph query endpoint instead: `POST /v1/graphs/{graph_id}/query`
+ * **Use Cases:**
+ * - Validate file upload completion
+ * - Monitor multi-layer ingestion progress in real-time
+ * - Debug upload or staging issues at specific layers
+ * - Verify file metadata and row counts
+ * - Track file provenance through the pipeline
+ * - Identify bottlenecks in the ingestion process
  *
  * **Note:**
- * Staging table queries are included - no credit consumption
+ * File info retrieval is included - no credit consumption
  */
-const queryTables = (options) => {
-    return (options.client ?? client_gen_1.client).post({
+const getFile = (options) => {
+    return (options.client ?? client_gen_1.client).get({
         security: [
             {
                 name: 'X-API-Key',
@@ -2928,7 +3111,53 @@ const queryTables = (options) => {
                 type: 'http'
             }
         ],
-        url: '/v1/graphs/{graph_id}/tables/query',
+        url: '/v1/graphs/{graph_id}/files/{file_id}',
+        ...options
+    });
+};
+exports.getFile = getFile;
+/**
+ * Update File Status
+ * Update file status and trigger processing.
+ *
+ * Update file status after upload completion. Setting status='uploaded' triggers
+ * immediate DuckDB staging and optional graph ingestion.
+ *
+ * **Request Body:**
+ * - `status`: New status (uploaded, disabled, failed)
+ * - `ingest_to_graph` (optional): If true, auto-ingest to graph after DuckDB staging
+ *
+ * **What Happens (status='uploaded'):**
+ * 1. File validated in S3
+ * 2. Row count calculated
+ * 3. DuckDB staging triggered immediately (Celery task)
+ * 4. If ingest_to_graph=true, graph ingestion queued
+ * 5. File queryable in DuckDB within seconds
+ *
+ * **Use Cases:**
+ * - Signal upload completion
+ * - Trigger immediate DuckDB staging
+ * - Enable/disable files
+ * - Mark failed uploads
+ *
+ * **Important:**
+ * - Files must exist in S3 before marking uploaded
+ * - DuckDB staging happens asynchronously
+ * - Graph ingestion is optional (ingest_to_graph flag)
+ */
+const updateFile = (options) => {
+    return (options.client ?? client_gen_1.client).patch({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            },
+            {
+                scheme: 'bearer',
+                type: 'http'
+            }
+        ],
+        url: '/v1/graphs/{graph_id}/files/{file_id}',
         ...options,
         headers: {
             'Content-Type': 'application/json',
@@ -2936,7 +3165,7 @@ const queryTables = (options) => {
         }
     });
 };
-exports.queryTables = queryTables;
+exports.updateFile = updateFile;
 /**
  * Get User Graphs and Repositories
  * List all graph databases and shared repositories accessible to the current user.