@robosystems/client 0.2.1 → 0.2.3

package/sdk/sdk.gen.js

@@ -2,7 +2,7 @@
 // This file is auto-generated by @hey-api/openapi-ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.batchProcessQueries = exports.executeSpecificAgent = exports.autoSelectAgent = exports.syncConnection = exports.getConnection = exports.deleteConnection = exports.oauthCallback = exports.initOAuth = exports.createLinkToken = exports.exchangeLinkToken = exports.getConnectionOptions = exports.createConnection = exports.listConnections = exports.getRepositoryCredits = exports.getSharedRepositoryCredits = exports.cancelSharedRepositorySubscription = exports.upgradeSharedRepositorySubscription = exports.subscribeToSharedRepository = exports.getUserSharedSubscriptions = exports.getDetailedUserAnalytics = exports.getUserUsageOverview = exports.getSharedRepositoryLimits = exports.getAllSharedRepositoryLimits = exports.getUserUsage = exports.getUserLimits = exports.updateUserApiKey = exports.revokeUserApiKey = exports.createUserApiKey = exports.listUserApiKeys = exports.updateUserPassword = exports.getAllCreditSummaries = 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.cancelOperation = exports.getOperationStatus = exports.streamOperationEvents = exports.getServiceOfferings = exports.selectGraph = exports.getAvailableExtensions = exports.createGraph = exports.getGraphs = exports.queryTablesV1GraphsGraphIdTablesQueryPost = exports.ingestTablesV1GraphsGraphIdTablesIngestPost = exports.updateFileV1GraphsGraphIdTablesFilesFileIdPatch = exports.getFileInfoV1GraphsGraphIdTablesFilesFileIdGet = exports.deleteFileV1GraphsGraphIdTablesFilesFileIdDelete = exports.getUploadUrlV1GraphsGraphIdTablesTableNameFilesPost = exports.listTableFilesV1GraphsGraphIdTablesTableNameFilesGet = exports.listTablesV1GraphsGraphIdTablesGet = 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.getGraphMonthlyBill = exports.getGraphBillingHistory = exports.getGraphUsageDetails = exports.getCurrentGraphBill = exports.validateSchema = exports.exportGraphSchema = exports.getGraphSchema = exports.executeCypherQuery = exports.getGraphUsageStats = exports.getGraphMetrics = exports.getBackupStats = exports.restoreBackup = exports.getBackupDownloadUrl = exports.createBackup = exports.listBackups = exports.callMcpTool = exports.listMcpTools = exports.recommendAgent = exports.getAgentMetadata = exports.listAgents = void 0;
+exports.cancelOperation = exports.getOperationStatus = exports.streamOperationEvents = exports.getServiceOfferings = exports.selectGraph = exports.getAvailableExtensions = exports.createGraph = exports.getGraphs = exports.queryTables = exports.ingestTables = exports.updateFileStatus = exports.getFileInfo = exports.deleteFile = exports.getUploadUrl = exports.listTableFiles = exports.listTables = 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.getGraphMonthlyBill = exports.getGraphBillingHistory = exports.getGraphUsageDetails = exports.getCurrentGraphBill = exports.validateSchema = exports.exportGraphSchema = exports.getGraphSchema = exports.executeCypherQuery = exports.getGraphUsageStats = exports.getGraphMetrics = exports.getBackupStats = exports.restoreBackup = exports.getBackupDownloadUrl = exports.createBackup = exports.listBackups = exports.callMcpTool = exports.listMcpTools = exports.recommendAgent = exports.getAgentMetadata = exports.listAgents = void 0;
 const client_gen_1 = require("./client.gen");
 /**
  * Register New User
@@ -1277,9 +1277,8 @@ exports.recommendAgent = recommendAgent;
  * - User permissions and subscription tier
  * - Backend capabilities (Kuzu, Neo4j, etc.)
  *
- * Credit consumption:
- * - Listing tools is included to encourage exploration
- * - Tool execution costs vary by operation complexity
+ * **Note:**
+ * MCP tool listing is included - no credit consumption required.
  */
 const listMcpTools = (options) => {
     return (options.client ?? client_gen_1.client).get({
@@ -1332,8 +1331,11 @@ exports.listMcpTools = listMcpTools;
  * - `408 Request Timeout`: Tool execution exceeded timeout
  * - Clients should implement exponential backoff on errors
  *
- * **Note:**
- * MCP tool calls are included and do not consume credits.
+ * **Credit Model:**
+ * MCP tool execution is included - no credit consumption required. Database
+ * operations (queries, schema inspection, analytics) are completely free.
+ * Only AI operations that invoke Claude or other LLM APIs consume credits,
+ * which happens at the AI agent layer, not the MCP tool layer.
  */
 const callMcpTool = (options) => {
     return (options.client ?? client_gen_1.client).post({
@@ -1640,6 +1642,13 @@ exports.getGraphUsageStats = getGraphUsageStats;
  * 1. Create file upload: `POST /v1/graphs/{graph_id}/tables/{table_name}/files`
  * 2. Ingest to graph: `POST /v1/graphs/{graph_id}/tables/ingest`
  *
+ * **Security Best Practice - Use Parameterized Queries:**
+ * ALWAYS use query parameters instead of string interpolation to prevent injection attacks:
+ * - ✅ SAFE: `MATCH (n:Entity {type: $entity_type}) RETURN n` with `parameters: {"entity_type": "Company"}`
+ * - ❌ UNSAFE: `MATCH (n:Entity {type: "Company"}) RETURN n` with user input concatenated into query string
+ *
+ * Query parameters provide automatic escaping and type safety. All examples in this API use parameterized queries.
+ *
  * This endpoint automatically selects the best execution strategy based on:
  * - Query characteristics (size, complexity)
  * - Client capabilities (SSE, NDJSON, JSON)
@@ -1711,13 +1720,38 @@ exports.executeCypherQuery = executeCypherQuery;
  * Get Runtime Graph Schema
  * Get runtime schema information for the specified graph database.
  *
- * This endpoint inspects the actual graph database structure and returns:
+ * ## What This Returns
+ *
+ * This endpoint inspects the **actual current state** of the graph database and returns:
  * - **Node Labels**: All node types currently in the database
  * - **Relationship Types**: All relationship types currently in the database
- * - **Node Properties**: Properties for each node type (limited to first 10 for performance)
+ * - **Node Properties**: Properties discovered from actual data (up to 10 properties per node type)
+ *
+ * ## Runtime vs Declared Schema
+ *
+ * **Use this endpoint** (`/schema`) when you need to know:
+ * - What data is ACTUALLY in the database right now
+ * - What properties exist on real nodes
+ * - What relationships have been created
+ * - Current database structure for querying
  *
- * This shows what actually exists in the database right now - the runtime state.
- * For the declared schema definition, use GET /schema/export instead.
+ * **Use `/schema/export` instead** when you need:
+ * - The original schema definition used to create the graph
+ * - Schema in a specific format (JSON, YAML, Cypher DDL)
+ * - Schema for documentation or version control
+ * - Schema to replicate in another graph
+ *
+ * ## Example Use Cases
+ *
+ * - **Building queries**: See what node labels and properties exist to write accurate Cypher
+ * - **Data exploration**: Discover what's in an unfamiliar graph
+ * - **Schema drift detection**: Compare runtime vs declared schema
+ * - **API integration**: Dynamically adapt to current graph structure
+ *
+ * ## Performance Note
+ *
+ * Property discovery is limited to 10 properties per node type for performance.
+ * For complete schema definitions, use `/schema/export`.
  *
  * This operation is included - no credit consumption required.
  */
@@ -1739,8 +1773,54 @@ const getGraphSchema = (options) => {
 };
 exports.getGraphSchema = getGraphSchema;
 /**
- * Export Graph Schema
- * Export the schema of an existing graph in JSON, YAML, or Cypher format
+ * Export Declared Graph Schema
+ * Export the declared schema definition of an existing graph.
+ *
+ * ## What This Returns
+ *
+ * This endpoint returns the **original schema definition** that was used to create the graph:
+ * - The schema as it was **declared** during graph creation
+ * - Complete node and relationship definitions
+ * - Property types and constraints
+ * - Schema metadata (name, version, type)
+ *
+ * ## Runtime vs Declared Schema
+ *
+ * **Use this endpoint** (`/schema/export`) when you need:
+ * - The original schema definition used to create the graph
+ * - Schema in a specific format (JSON, YAML, Cypher DDL)
+ * - Schema for documentation or version control
+ * - Schema to replicate in another graph
+ *
+ * **Use `/schema` instead** when you need:
+ * - What data is ACTUALLY in the database right now
+ * - What properties exist on real nodes (discovered from data)
+ * - Current runtime database structure for querying
+ *
+ * ## Export Formats
+ *
+ * ### JSON Format (`format=json`)
+ * Returns structured JSON with nodes, relationships, and properties.
+ * Best for programmatic access and API integration.
+ *
+ * ### YAML Format (`format=yaml`)
+ * Returns human-readable YAML with comments.
+ * Best for documentation and configuration management.
+ *
+ * ### Cypher DDL Format (`format=cypher`)
+ * Returns Cypher CREATE statements for recreating the schema.
+ * Best for database migration and replication.
+ *
+ * ## Data Statistics
+ *
+ * Set `include_data_stats=true` to include:
+ * - Node counts by label
+ * - Relationship counts by type
+ * - Total nodes and relationships
+ *
+ * This combines declared schema with runtime statistics.
+ *
+ * This operation is included - no credit consumption required.
  */
 const exportGraphSchema = (options) => {
     return (options.client ?? client_gen_1.client).get({
@@ -2389,9 +2469,42 @@ const getSubgraphQuota = (options) => {
 exports.getSubgraphQuota = getSubgraphQuota;
 /**
  * List Staging Tables
- * List all DuckDB staging tables for a graph
+ * List all DuckDB staging tables with comprehensive metrics and status.
+ *
+ * Get a complete inventory of all staging tables for a graph, including
+ * file counts, storage sizes, and row estimates. Essential for monitoring
+ * the data pipeline and determining which tables are ready for ingestion.
+ *
+ * **Returned Metrics:**
+ * - Table name and type (node/relationship)
+ * - File count per table
+ * - Total storage size in bytes
+ * - Estimated row count
+ * - S3 location pattern
+ * - Ready-for-ingestion status
+ *
+ * **Use Cases:**
+ * - Monitor data upload progress
+ * - Check which tables have files ready
+ * - Track storage consumption
+ * - Validate pipeline before ingestion
+ * - Capacity planning
+ *
+ * **Workflow:**
+ * 1. List tables to see current state
+ * 2. Upload files to empty tables
+ * 3. Re-list to verify uploads
+ * 4. Check file counts and sizes
+ * 5. Ingest when ready
+ *
+ * **Important Notes:**
+ * - Tables with `file_count > 0` have data ready
+ * - Check `total_size_bytes` for storage monitoring
+ * - Use `s3_location` to verify upload paths
+ * - Empty tables (file_count=0) are skipped during ingestion
+ * - Table queries are included - no credit consumption
  */
-const listTablesV1GraphsGraphIdTablesGet = (options) => {
+const listTables = (options) => {
     return (options.client ?? client_gen_1.client).get({
         security: [
             {
@@ -2407,12 +2520,45 @@ const listTablesV1GraphsGraphIdTablesGet = (options) => {
         ...options
     });
 };
-exports.listTablesV1GraphsGraphIdTablesGet = listTablesV1GraphsGraphIdTablesGet;
+exports.listTables = listTables;
 /**
- * List Files in Table
- * List all files uploaded to a staging table
+ * List Files in Staging Table
+ * List all files uploaded to a staging table with comprehensive metadata.
+ *
+ * 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.
+ *
+ * **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
+ *
+ * **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
+ *
+ * **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
+ *
+ * **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
  */
-const listTableFilesV1GraphsGraphIdTablesTableNameFilesGet = (options) => {
+const listTableFiles = (options) => {
     return (options.client ?? client_gen_1.client).get({
         security: [
             {
@@ -2428,12 +2574,44 @@ const listTableFilesV1GraphsGraphIdTablesTableNameFilesGet = (options) => {
         ...options
     });
 };
-exports.listTableFilesV1GraphsGraphIdTablesTableNameFilesGet = listTableFilesV1GraphsGraphIdTablesTableNameFilesGet;
+exports.listTableFiles = listTableFiles;
 /**
- * Create File Upload
- * Create a new file upload for a table and get a presigned S3 URL
+ * 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.
+ *
+ * **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
+ *
+ * **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.
+ *
+ * **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
  */
-const getUploadUrlV1GraphsGraphIdTablesTableNameFilesPost = (options) => {
+const getUploadUrl = (options) => {
     return (options.client ?? client_gen_1.client).post({
         security: [
             {
@@ -2453,12 +2631,42 @@ const getUploadUrlV1GraphsGraphIdTablesTableNameFilesPost = (options) => {
         }
     });
 };
-exports.getUploadUrlV1GraphsGraphIdTablesTableNameFilesPost = getUploadUrlV1GraphsGraphIdTablesTableNameFilesPost;
+exports.getUploadUrl = getUploadUrl;
 /**
- * Delete File
- * Delete a specific file from S3 and database tracking. DuckDB will automatically exclude it from queries.
+ * Delete File from Staging
+ * Delete a file from S3 storage and database tracking.
+ *
+ * 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.
+ *
+ * **Use Cases:**
+ * - Remove duplicate uploads
+ * - Delete files with incorrect data
+ * - Clean up failed uploads
+ * - Fix data quality issues before ingestion
+ * - Manage storage usage
+ *
+ * **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
+ *
+ * **Security:**
+ * - Write access required (verified via auth)
+ * - Shared repositories block file deletions
+ * - Full audit trail of deletion operations
+ * - Cannot delete after ingestion to graph
+ *
+ * **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
  */
-const deleteFileV1GraphsGraphIdTablesFilesFileIdDelete = (options) => {
+const deleteFile = (options) => {
     return (options.client ?? client_gen_1.client).delete({
         security: [
             {
@@ -2474,12 +2682,26 @@ const deleteFileV1GraphsGraphIdTablesFilesFileIdDelete = (options) => {
         ...options
     });
 };
-exports.deleteFileV1GraphsGraphIdTablesFilesFileIdDelete = deleteFileV1GraphsGraphIdTablesFilesFileIdDelete;
+exports.deleteFile = deleteFile;
 /**
- * Get File Info
- * Get detailed information about a specific file
+ * Get File Information
+ * Get detailed information about a specific file.
+ *
+ * Retrieve comprehensive metadata for a single file, including upload status,
+ * size, row count, and timestamps. Useful for validating individual files
+ * before ingestion.
+ *
+ * **Use Cases:**
+ * - Validate file upload completion
+ * - Check file metadata before ingestion
+ * - Debug upload issues
+ * - Verify file format and size
+ * - Track file lifecycle
+ *
+ * **Note:**
+ * File info retrieval is included - no credit consumption
  */
-const getFileInfoV1GraphsGraphIdTablesFilesFileIdGet = (options) => {
+const getFileInfo = (options) => {
     return (options.client ?? client_gen_1.client).get({
         security: [
             {
@@ -2495,12 +2717,47 @@ const getFileInfoV1GraphsGraphIdTablesFilesFileIdGet = (options) => {
         ...options
     });
 };
-exports.getFileInfoV1GraphsGraphIdTablesFilesFileIdGet = getFileInfoV1GraphsGraphIdTablesFilesFileIdGet;
+exports.getFileInfo = getFileInfo;
 /**
- * Update File
- * Update file metadata after upload (size, row count). Marks file as completed.
+ * Update File Upload Status
+ * Update file status after upload completes.
+ *
+ * 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.
+ *
+ * **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.
+ *
+ * **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
  */
-const updateFileV1GraphsGraphIdTablesFilesFileIdPatch = (options) => {
+const updateFileStatus = (options) => {
     return (options.client ?? client_gen_1.client).patch({
         security: [
             {
@@ -2520,12 +2777,66 @@ const updateFileV1GraphsGraphIdTablesFilesFileIdPatch = (options) => {
         }
     });
 };
-exports.updateFileV1GraphsGraphIdTablesFilesFileIdPatch = updateFileV1GraphsGraphIdTablesFilesFileIdPatch;
+exports.updateFileStatus = updateFileStatus;
 /**
  * Ingest Tables to Graph
- * Load all files from S3 into DuckDB staging tables and ingest into Kuzu graph database. Use rebuild=true to regenerate the entire graph from scratch (safe operation - S3 is source of truth).
- */
-const ingestTablesV1GraphsGraphIdTablesIngestPost = (options) => {
+ * Load all files from S3 into DuckDB staging tables and ingest into Kuzu graph database.
+ *
+ * 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.
+ *
+ * **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
+ *
+ * **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
+ *
+ * **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
+ *
+ * **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
+ *
+ * **Performance:**
+ * - Processes all tables in sequence
+ * - Each table timed independently
+ * - Total execution metrics provided
+ * - Scales to thousands of files
+ * - Optimized for large datasets
+ *
+ * **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.
+ *
+ * **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) => {
     return (options.client ?? client_gen_1.client).post({
         security: [
             {
@@ -2545,12 +2856,61 @@ const ingestTablesV1GraphsGraphIdTablesIngestPost = (options) => {
         }
     });
 };
-exports.ingestTablesV1GraphsGraphIdTablesIngestPost = ingestTablesV1GraphsGraphIdTablesIngestPost;
+exports.ingestTables = ingestTables;
 /**
  * Query Staging Tables with SQL
- * Execute SQL queries on DuckDB staging tables
+ * Execute SQL queries on DuckDB staging tables for data inspection and validation.
+ *
+ * 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:**
+ * - 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
+ *
+ * **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`
+ *
+ * **Supported SQL:**
+ * - Full DuckDB SQL syntax
+ * - SELECT, JOIN, WHERE, GROUP BY, ORDER BY
+ * - Aggregations, window functions, CTEs
+ * - Multiple table joins across staging area
+ *
+ * **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
+ *
+ * **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 queryTablesV1GraphsGraphIdTablesQueryPost = (options) => {
+const queryTables = (options) => {
     return (options.client ?? client_gen_1.client).post({
         security: [
             {
@@ -2570,10 +2930,43 @@ const queryTablesV1GraphsGraphIdTablesQueryPost = (options) => {
         }
     });
 };
-exports.queryTablesV1GraphsGraphIdTablesQueryPost = queryTablesV1GraphsGraphIdTablesQueryPost;
+exports.queryTables = queryTables;
 /**
  * Get User Graphs
- * Get all graph databases accessible to the current user.
+ * List all graph databases accessible to the current user with roles and selection status.
+ *
+ * Returns a comprehensive list of all graphs the user can access, including their
+ * role in each graph (admin or member) and which graph is currently selected as
+ * the active workspace.
+ *
+ * **Returned Information:**
+ * - Graph ID and display name for each accessible graph
+ * - User's role (admin/member) indicating permission level
+ * - Selection status (one graph can be marked as "selected")
+ * - Creation timestamp for each graph
+ *
+ * **Graph Roles:**
+ * - `admin`: Full access - can manage graph settings, invite users, delete graph
+ * - `member`: Read/write access - can query and modify data, cannot manage settings
+ *
+ * **Selected Graph Concept:**
+ * The "selected" graph is the user's currently active workspace. Many API operations
+ * default to the selected graph if no graph_id is provided. Users can change their
+ * selected graph via the `POST /v1/graphs/{graph_id}/select` endpoint.
+ *
+ * **Use Cases:**
+ * - Display graph selector in UI
+ * - Show user's accessible workspaces
+ * - Identify which graph is currently active
+ * - Filter graphs by role for permission-based features
+ *
+ * **Empty Response:**
+ * New users or users without graph access will receive an empty list with
+ * `selectedGraphId: null`. Users should create a new graph or request access
+ * to an existing graph.
+ *
+ * **Note:**
+ * Graph listing is included - no credit consumption required.
  */
 const getGraphs = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -2658,7 +3051,34 @@ const createGraph = (options) => {
 exports.createGraph = createGraph;
 /**
  * Get Available Schema Extensions
- * List all available schema extensions for graph creation
+ * List all available schema extensions for graph creation.
+ *
+ * Schema extensions provide pre-built industry-specific data models that extend
+ * the base graph schema with specialized nodes, relationships, and properties.
+ *
+ * **Available Extensions:**
+ * - **RoboLedger**: Complete accounting system with XBRL reporting, general ledger, and financial statements
+ * - **RoboInvestor**: Investment portfolio management and tracking
+ * - **RoboSCM**: Supply chain management and logistics
+ * - **RoboFO**: Front office operations and CRM
+ * - **RoboHRM**: Human resources management
+ * - **RoboEPM**: Enterprise performance management
+ * - **RoboReport**: Business intelligence and reporting
+ *
+ * **Extension Information:**
+ * Each extension includes:
+ * - Display name and description
+ * - Node and relationship counts
+ * - Context-aware capabilities (e.g., SEC repositories get different features than entity graphs)
+ *
+ * **Use Cases:**
+ * - Browse available extensions before creating a graph
+ * - Understand extension capabilities and data models
+ * - Plan graph schema based on business requirements
+ * - Combine multiple extensions for comprehensive data modeling
+ *
+ * **Note:**
+ * Extension listing is included - no credit consumption required.
  */
 const getAvailableExtensions = (options) => {
     return (options?.client ?? client_gen_1.client).get({
@@ -2679,7 +3099,35 @@ const getAvailableExtensions = (options) => {
 exports.getAvailableExtensions = getAvailableExtensions;
 /**
  * Select Graph
- * Select a specific graph as the active graph for the user.
+ * Select a specific graph as the active workspace for the user.
+ *
+ * The selected graph becomes the default context for operations in client applications
+ * and can be used to maintain user workspace preferences across sessions.
+ *
+ * **Functionality:**
+ * - Sets the specified graph as the user's currently selected graph
+ * - Deselects any previously selected graph (only one can be selected at a time)
+ * - Persists selection across sessions until changed
+ * - Returns confirmation with the selected graph ID
+ *
+ * **Requirements:**
+ * - User must have access to the graph (as admin or member)
+ * - Graph must exist and not be deleted
+ * - User can only select graphs they have permission to access
+ *
+ * **Use Cases:**
+ * - Switch between multiple graphs in a multi-graph environment
+ * - Set default workspace after creating a new graph
+ * - Restore user's preferred workspace on login
+ * - Support graph context switching in client applications
+ *
+ * **Client Integration:**
+ * Many client operations can default to the selected graph, simplifying API calls
+ * by eliminating the need to specify graph_id repeatedly. Check the selected
+ * graph with `GET /v1/graphs` which returns `selectedGraphId`.
+ *
+ * **Note:**
+ * Graph selection is included - no credit consumption required.
  */
 const selectGraph = (options) => {
     return (options.client ?? client_gen_1.client).post({