@robosystems/client 0.2.0 → 0.2.2

package/sdk.gen.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 import type { Options as ClientOptions, TDataShape, Client } from './client';
-import type { RegisterUserData, RegisterUserResponses, RegisterUserErrors, LoginUserData, LoginUserResponses, LoginUserErrors, LogoutUserData, LogoutUserResponses, LogoutUserErrors, GetCurrentAuthUserData, GetCurrentAuthUserResponses, GetCurrentAuthUserErrors, RefreshAuthSessionData, RefreshAuthSessionResponses, RefreshAuthSessionErrors, ResendVerificationEmailData, ResendVerificationEmailResponses, ResendVerificationEmailErrors, VerifyEmailData, VerifyEmailResponses, VerifyEmailErrors, GetPasswordPolicyData, GetPasswordPolicyResponses, CheckPasswordStrengthData, CheckPasswordStrengthResponses, CheckPasswordStrengthErrors, ForgotPasswordData, ForgotPasswordResponses, ForgotPasswordErrors, ValidateResetTokenData, ValidateResetTokenResponses, ValidateResetTokenErrors, ResetPasswordData, ResetPasswordResponses, ResetPasswordErrors, GenerateSsoTokenData, GenerateSsoTokenResponses, GenerateSsoTokenErrors, SsoTokenExchangeData, SsoTokenExchangeResponses, SsoTokenExchangeErrors, CompleteSsoAuthData, CompleteSsoAuthResponses, CompleteSsoAuthErrors, GetCaptchaConfigData, GetCaptchaConfigResponses, GetServiceStatusData, GetServiceStatusResponses, GetCurrentUserData, GetCurrentUserResponses, GetCurrentUserErrors, UpdateUserData, UpdateUserResponses, UpdateUserErrors, GetAllCreditSummariesData, GetAllCreditSummariesResponses, GetAllCreditSummariesErrors, UpdateUserPasswordData, UpdateUserPasswordResponses, UpdateUserPasswordErrors, ListUserApiKeysData, ListUserApiKeysResponses, ListUserApiKeysErrors, CreateUserApiKeyData, CreateUserApiKeyResponses, CreateUserApiKeyErrors, RevokeUserApiKeyData, RevokeUserApiKeyResponses, RevokeUserApiKeyErrors, UpdateUserApiKeyData, UpdateUserApiKeyResponses, UpdateUserApiKeyErrors, GetUserLimitsData, GetUserLimitsResponses, GetUserLimitsErrors, GetUserUsageData, GetUserUsageResponses, GetUserUsageErrors, GetAllSharedRepositoryLimitsData, GetAllSharedRepositoryLimitsResponses, GetAllSharedRepositoryLimitsErrors, GetSharedRepositoryLimitsData, GetSharedRepositoryLimitsResponses, GetSharedRepositoryLimitsErrors, GetUserUsageOverviewData, GetUserUsageOverviewResponses, GetUserUsageOverviewErrors, GetDetailedUserAnalyticsData, GetDetailedUserAnalyticsResponses, GetDetailedUserAnalyticsErrors, GetUserSharedSubscriptionsData, GetUserSharedSubscriptionsResponses, GetUserSharedSubscriptionsErrors, SubscribeToSharedRepositoryData, SubscribeToSharedRepositoryResponses, SubscribeToSharedRepositoryErrors, UpgradeSharedRepositorySubscriptionData, UpgradeSharedRepositorySubscriptionResponses, UpgradeSharedRepositorySubscriptionErrors, CancelSharedRepositorySubscriptionData, CancelSharedRepositorySubscriptionResponses, CancelSharedRepositorySubscriptionErrors, GetSharedRepositoryCreditsData, GetSharedRepositoryCreditsResponses, GetSharedRepositoryCreditsErrors, GetRepositoryCreditsData, GetRepositoryCreditsResponses, GetRepositoryCreditsErrors, ListConnectionsData, ListConnectionsResponses, ListConnectionsErrors, CreateConnectionData, CreateConnectionResponses, CreateConnectionErrors, GetConnectionOptionsData, GetConnectionOptionsResponses, GetConnectionOptionsErrors, ExchangeLinkTokenData, ExchangeLinkTokenResponses, ExchangeLinkTokenErrors, CreateLinkTokenData, CreateLinkTokenResponses, CreateLinkTokenErrors, InitOAuthData, InitOAuthResponses, InitOAuthErrors, OauthCallbackData, OauthCallbackResponses, OauthCallbackErrors, DeleteConnectionData, DeleteConnectionResponses, DeleteConnectionErrors, GetConnectionData, GetConnectionResponses, GetConnectionErrors, SyncConnectionData, SyncConnectionResponses, SyncConnectionErrors, AutoSelectAgentData, AutoSelectAgentResponses, AutoSelectAgentErrors, ExecuteSpecificAgentData, ExecuteSpecificAgentResponses, ExecuteSpecificAgentErrors, BatchProcessQueriesData, BatchProcessQueriesResponses, BatchProcessQueriesErrors, ListAgentsData, ListAgentsResponses, ListAgentsErrors, GetAgentMetadataData, GetAgentMetadataResponses, GetAgentMetadataErrors, RecommendAgentData, RecommendAgentResponses, RecommendAgentErrors, ListMcpToolsData, ListMcpToolsResponses, ListMcpToolsErrors, CallMcpToolData, CallMcpToolResponses, CallMcpToolErrors, ListBackupsData, ListBackupsResponses, ListBackupsErrors, CreateBackupData, CreateBackupResponses, CreateBackupErrors, GetBackupDownloadUrlData, GetBackupDownloadUrlResponses, GetBackupDownloadUrlErrors, RestoreBackupData, RestoreBackupResponses, RestoreBackupErrors, GetBackupStatsData, GetBackupStatsResponses, GetBackupStatsErrors, GetGraphMetricsData, GetGraphMetricsResponses, GetGraphMetricsErrors, GetGraphUsageStatsData, GetGraphUsageStatsResponses, GetGraphUsageStatsErrors, ExecuteCypherQueryData, ExecuteCypherQueryResponses, ExecuteCypherQueryErrors, GetGraphSchemaData, GetGraphSchemaResponses, GetGraphSchemaErrors, ExportGraphSchemaData, ExportGraphSchemaResponses, ExportGraphSchemaErrors, ValidateSchemaData, ValidateSchemaResponses, ValidateSchemaErrors, GetCurrentGraphBillData, GetCurrentGraphBillResponses, GetCurrentGraphBillErrors, GetGraphUsageDetailsData, GetGraphUsageDetailsResponses, GetGraphUsageDetailsErrors, GetGraphBillingHistoryData, GetGraphBillingHistoryResponses, GetGraphBillingHistoryErrors, GetGraphMonthlyBillData, GetGraphMonthlyBillResponses, GetGraphMonthlyBillErrors, GetCreditSummaryData, GetCreditSummaryResponses, GetCreditSummaryErrors, ListCreditTransactionsData, ListCreditTransactionsResponses, ListCreditTransactionsErrors, CheckCreditBalanceData, CheckCreditBalanceResponses, CheckCreditBalanceErrors, GetStorageUsageData, GetStorageUsageResponses, GetStorageUsageErrors, CheckStorageLimitsData, CheckStorageLimitsResponses, CheckStorageLimitsErrors, GetDatabaseHealthData, GetDatabaseHealthResponses, GetDatabaseHealthErrors, GetDatabaseInfoData, GetDatabaseInfoResponses, GetDatabaseInfoErrors, GetGraphLimitsData, GetGraphLimitsResponses, GetGraphLimitsErrors, ListSubgraphsData, ListSubgraphsResponses, ListSubgraphsErrors, CreateSubgraphData, CreateSubgraphResponses, CreateSubgraphErrors, DeleteSubgraphData, DeleteSubgraphResponses, DeleteSubgraphErrors, GetSubgraphInfoData, GetSubgraphInfoResponses, GetSubgraphInfoErrors, GetSubgraphQuotaData, GetSubgraphQuotaResponses, GetSubgraphQuotaErrors, ListTablesV1GraphsGraphIdTablesGetData, ListTablesV1GraphsGraphIdTablesGetResponses, ListTablesV1GraphsGraphIdTablesGetErrors, ListTableFilesV1GraphsGraphIdTablesTableNameFilesGetData, ListTableFilesV1GraphsGraphIdTablesTableNameFilesGetResponses, ListTableFilesV1GraphsGraphIdTablesTableNameFilesGetErrors, GetUploadUrlV1GraphsGraphIdTablesTableNameFilesPostData, GetUploadUrlV1GraphsGraphIdTablesTableNameFilesPostResponses, GetUploadUrlV1GraphsGraphIdTablesTableNameFilesPostErrors, DeleteFileV1GraphsGraphIdTablesFilesFileIdDeleteData, DeleteFileV1GraphsGraphIdTablesFilesFileIdDeleteResponses, DeleteFileV1GraphsGraphIdTablesFilesFileIdDeleteErrors, GetFileInfoV1GraphsGraphIdTablesFilesFileIdGetData, GetFileInfoV1GraphsGraphIdTablesFilesFileIdGetResponses, GetFileInfoV1GraphsGraphIdTablesFilesFileIdGetErrors, UpdateFileV1GraphsGraphIdTablesFilesFileIdPatchData, UpdateFileV1GraphsGraphIdTablesFilesFileIdPatchResponses, UpdateFileV1GraphsGraphIdTablesFilesFileIdPatchErrors, IngestTablesV1GraphsGraphIdTablesIngestPostData, IngestTablesV1GraphsGraphIdTablesIngestPostResponses, IngestTablesV1GraphsGraphIdTablesIngestPostErrors, QueryTablesV1GraphsGraphIdTablesQueryPostData, QueryTablesV1GraphsGraphIdTablesQueryPostResponses, QueryTablesV1GraphsGraphIdTablesQueryPostErrors, GetGraphsData, GetGraphsResponses, GetGraphsErrors, CreateGraphData, CreateGraphResponses, CreateGraphErrors, GetAvailableExtensionsData, GetAvailableExtensionsResponses, SelectGraphData, SelectGraphResponses, SelectGraphErrors, GetServiceOfferingsData, GetServiceOfferingsResponses, GetServiceOfferingsErrors, StreamOperationEventsData, StreamOperationEventsResponses, StreamOperationEventsErrors, GetOperationStatusData, GetOperationStatusResponses, GetOperationStatusErrors, CancelOperationData, CancelOperationResponses, CancelOperationErrors } from './types.gen';
+import type { RegisterUserData, RegisterUserResponses, RegisterUserErrors, LoginUserData, LoginUserResponses, LoginUserErrors, LogoutUserData, LogoutUserResponses, LogoutUserErrors, GetCurrentAuthUserData, GetCurrentAuthUserResponses, GetCurrentAuthUserErrors, RefreshAuthSessionData, RefreshAuthSessionResponses, RefreshAuthSessionErrors, ResendVerificationEmailData, ResendVerificationEmailResponses, ResendVerificationEmailErrors, VerifyEmailData, VerifyEmailResponses, VerifyEmailErrors, GetPasswordPolicyData, GetPasswordPolicyResponses, CheckPasswordStrengthData, CheckPasswordStrengthResponses, CheckPasswordStrengthErrors, ForgotPasswordData, ForgotPasswordResponses, ForgotPasswordErrors, ValidateResetTokenData, ValidateResetTokenResponses, ValidateResetTokenErrors, ResetPasswordData, ResetPasswordResponses, ResetPasswordErrors, GenerateSsoTokenData, GenerateSsoTokenResponses, GenerateSsoTokenErrors, SsoTokenExchangeData, SsoTokenExchangeResponses, SsoTokenExchangeErrors, CompleteSsoAuthData, CompleteSsoAuthResponses, CompleteSsoAuthErrors, GetCaptchaConfigData, GetCaptchaConfigResponses, GetServiceStatusData, GetServiceStatusResponses, GetCurrentUserData, GetCurrentUserResponses, GetCurrentUserErrors, UpdateUserData, UpdateUserResponses, UpdateUserErrors, GetAllCreditSummariesData, GetAllCreditSummariesResponses, GetAllCreditSummariesErrors, UpdateUserPasswordData, UpdateUserPasswordResponses, UpdateUserPasswordErrors, ListUserApiKeysData, ListUserApiKeysResponses, ListUserApiKeysErrors, CreateUserApiKeyData, CreateUserApiKeyResponses, CreateUserApiKeyErrors, RevokeUserApiKeyData, RevokeUserApiKeyResponses, RevokeUserApiKeyErrors, UpdateUserApiKeyData, UpdateUserApiKeyResponses, UpdateUserApiKeyErrors, GetUserLimitsData, GetUserLimitsResponses, GetUserLimitsErrors, GetUserUsageData, GetUserUsageResponses, GetUserUsageErrors, GetAllSharedRepositoryLimitsData, GetAllSharedRepositoryLimitsResponses, GetAllSharedRepositoryLimitsErrors, GetSharedRepositoryLimitsData, GetSharedRepositoryLimitsResponses, GetSharedRepositoryLimitsErrors, GetUserUsageOverviewData, GetUserUsageOverviewResponses, GetUserUsageOverviewErrors, GetDetailedUserAnalyticsData, GetDetailedUserAnalyticsResponses, GetDetailedUserAnalyticsErrors, GetUserSharedSubscriptionsData, GetUserSharedSubscriptionsResponses, GetUserSharedSubscriptionsErrors, SubscribeToSharedRepositoryData, SubscribeToSharedRepositoryResponses, SubscribeToSharedRepositoryErrors, UpgradeSharedRepositorySubscriptionData, UpgradeSharedRepositorySubscriptionResponses, UpgradeSharedRepositorySubscriptionErrors, CancelSharedRepositorySubscriptionData, CancelSharedRepositorySubscriptionResponses, CancelSharedRepositorySubscriptionErrors, GetSharedRepositoryCreditsData, GetSharedRepositoryCreditsResponses, GetSharedRepositoryCreditsErrors, GetRepositoryCreditsData, GetRepositoryCreditsResponses, GetRepositoryCreditsErrors, ListConnectionsData, ListConnectionsResponses, ListConnectionsErrors, CreateConnectionData, CreateConnectionResponses, CreateConnectionErrors, GetConnectionOptionsData, GetConnectionOptionsResponses, GetConnectionOptionsErrors, ExchangeLinkTokenData, ExchangeLinkTokenResponses, ExchangeLinkTokenErrors, CreateLinkTokenData, CreateLinkTokenResponses, CreateLinkTokenErrors, InitOAuthData, InitOAuthResponses, InitOAuthErrors, OauthCallbackData, OauthCallbackResponses, OauthCallbackErrors, DeleteConnectionData, DeleteConnectionResponses, DeleteConnectionErrors, GetConnectionData, GetConnectionResponses, GetConnectionErrors, SyncConnectionData, SyncConnectionResponses, SyncConnectionErrors, AutoSelectAgentData, AutoSelectAgentResponses, AutoSelectAgentErrors, ExecuteSpecificAgentData, ExecuteSpecificAgentResponses, ExecuteSpecificAgentErrors, BatchProcessQueriesData, BatchProcessQueriesResponses, BatchProcessQueriesErrors, ListAgentsData, ListAgentsResponses, ListAgentsErrors, GetAgentMetadataData, GetAgentMetadataResponses, GetAgentMetadataErrors, RecommendAgentData, RecommendAgentResponses, RecommendAgentErrors, ListMcpToolsData, ListMcpToolsResponses, ListMcpToolsErrors, CallMcpToolData, CallMcpToolResponses, CallMcpToolErrors, ListBackupsData, ListBackupsResponses, ListBackupsErrors, CreateBackupData, CreateBackupResponses, CreateBackupErrors, GetBackupDownloadUrlData, GetBackupDownloadUrlResponses, GetBackupDownloadUrlErrors, RestoreBackupData, RestoreBackupResponses, RestoreBackupErrors, GetBackupStatsData, GetBackupStatsResponses, GetBackupStatsErrors, GetGraphMetricsData, GetGraphMetricsResponses, GetGraphMetricsErrors, GetGraphUsageStatsData, GetGraphUsageStatsResponses, GetGraphUsageStatsErrors, ExecuteCypherQueryData, ExecuteCypherQueryResponses, ExecuteCypherQueryErrors, GetGraphSchemaData, GetGraphSchemaResponses, GetGraphSchemaErrors, ExportGraphSchemaData, ExportGraphSchemaResponses, ExportGraphSchemaErrors, ValidateSchemaData, ValidateSchemaResponses, ValidateSchemaErrors, GetCurrentGraphBillData, GetCurrentGraphBillResponses, GetCurrentGraphBillErrors, GetGraphUsageDetailsData, GetGraphUsageDetailsResponses, GetGraphUsageDetailsErrors, GetGraphBillingHistoryData, GetGraphBillingHistoryResponses, GetGraphBillingHistoryErrors, GetGraphMonthlyBillData, GetGraphMonthlyBillResponses, GetGraphMonthlyBillErrors, GetCreditSummaryData, GetCreditSummaryResponses, GetCreditSummaryErrors, ListCreditTransactionsData, ListCreditTransactionsResponses, ListCreditTransactionsErrors, CheckCreditBalanceData, CheckCreditBalanceResponses, CheckCreditBalanceErrors, GetStorageUsageData, GetStorageUsageResponses, GetStorageUsageErrors, CheckStorageLimitsData, CheckStorageLimitsResponses, CheckStorageLimitsErrors, GetDatabaseHealthData, GetDatabaseHealthResponses, GetDatabaseHealthErrors, GetDatabaseInfoData, GetDatabaseInfoResponses, GetDatabaseInfoErrors, GetGraphLimitsData, GetGraphLimitsResponses, GetGraphLimitsErrors, ListSubgraphsData, ListSubgraphsResponses, ListSubgraphsErrors, CreateSubgraphData, CreateSubgraphResponses, CreateSubgraphErrors, DeleteSubgraphData, DeleteSubgraphResponses, DeleteSubgraphErrors, GetSubgraphInfoData, GetSubgraphInfoResponses, GetSubgraphInfoErrors, GetSubgraphQuotaData, GetSubgraphQuotaResponses, GetSubgraphQuotaErrors, ListTablesData, ListTablesResponses, ListTablesErrors, ListTableFilesData, ListTableFilesResponses, ListTableFilesErrors, GetUploadUrlData, GetUploadUrlResponses, GetUploadUrlErrors, DeleteFileData, DeleteFileResponses, DeleteFileErrors, GetFileInfoData, GetFileInfoResponses, GetFileInfoErrors, UpdateFileStatusData, UpdateFileStatusResponses, UpdateFileStatusErrors, IngestTablesData, IngestTablesResponses, IngestTablesErrors, QueryTablesData, QueryTablesResponses, QueryTablesErrors, GetGraphsData, GetGraphsResponses, GetGraphsErrors, CreateGraphData, CreateGraphResponses, CreateGraphErrors, GetAvailableExtensionsData, GetAvailableExtensionsResponses, SelectGraphData, SelectGraphResponses, SelectGraphErrors, GetServiceOfferingsData, GetServiceOfferingsResponses, GetServiceOfferingsErrors, StreamOperationEventsData, StreamOperationEventsResponses, StreamOperationEventsErrors, GetOperationStatusData, GetOperationStatusResponses, GetOperationStatusErrors, CancelOperationData, CancelOperationResponses, CancelOperationErrors } from './types.gen';
 import { client as _heyApiClient } from './client.gen';
 
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = ClientOptions<TData, ThrowOnError> & {
@@ -2403,10 +2403,75 @@ export const getSubgraphQuota = <ThrowOnError extends boolean = false>(options:
 
 /**
  * List Staging Tables
- * List all DuckDB staging tables for a graph
+ * List all DuckDB staging tables with comprehensive metrics and status.
+ *
+ * **Purpose:**
+ * 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.
+ *
+ * **What You Get:**
+ * - 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
+ *
+ * **Example Response:**
+ * ```json
+ * {
+ * "tables": [
+ * {
+ * "table_name": "Entity",
+ * "row_count": 5000,
+ * "file_count": 3,
+ * "total_size_bytes": 2457600,
+ * "s3_location": "s3://bucket/user-staging/user123/graph456/Entity***.parquet"
+ * },
+ * {
+ * "table_name": "Transaction",
+ * "row_count": 15000,
+ * "file_count": 5,
+ * "total_size_bytes": 8192000,
+ * "s3_location": "s3://bucket/user-staging/user123/graph456/Transaction***.parquet"
+ * }
+ * ],
+ * "total_count": 2
+ * }
+ * ```
+ *
+ * **Example Usage:**
+ * ```bash
+ * curl -H "Authorization: Bearer YOUR_TOKEN" \
+ * https://api.robosystems.ai/v1/graphs/kg123/tables
+ * ```
+ *
+ * **Tips:**
+ * - 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
+ *
+ * **Note:**
+ * Table queries are included - no credit consumption.
  */
-export const listTablesV1GraphsGraphIdTablesGet = <ThrowOnError extends boolean = false>(options: Options<ListTablesV1GraphsGraphIdTablesGetData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).get<ListTablesV1GraphsGraphIdTablesGetResponses, ListTablesV1GraphsGraphIdTablesGetErrors, ThrowOnError>({
+export const listTables = <ThrowOnError extends boolean = false>(options: Options<ListTablesData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<ListTablesResponses, ListTablesErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2423,11 +2488,78 @@ export const listTablesV1GraphsGraphIdTablesGet = <ThrowOnError extends boolean
 };
 
 /**
- * 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.
+ *
+ * **Purpose:**
+ * 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
+ *
+ * **What You Get:**
+ * - File ID and name
+ * - File format (parquet, csv, etc.)
+ * - Size in bytes
+ * - Row count (if available)
+ * - Upload status and method
+ * - Creation and upload timestamps
+ * - S3 key for reference
+ *
+ * **Upload Status Values:**
+ * - `created`: File record created, not yet uploaded
+ * - `uploading`: Upload in progress
+ * - `uploaded`: Successfully uploaded, ready for ingestion
+ * - `failed`: Upload failed
+ *
+ * **Example Response:**
+ * ```json
+ * {
+ * "graph_id": "kg123",
+ * "table_name": "Entity",
+ * "files": [
+ * {
+ * "file_id": "f123",
+ * "file_name": "entities_batch1.parquet",
+ * "file_format": "parquet",
+ * "size_bytes": 1048576,
+ * "row_count": 5000,
+ * "upload_status": "uploaded",
+ * "upload_method": "presigned_url",
+ * "created_at": "2025-10-28T10:00:00Z",
+ * "uploaded_at": "2025-10-28T10:01:30Z",
+ * "s3_key": "user-staging/user123/kg123/Entity/entities_batch1.parquet"
+ * }
+ * ],
+ * "total_files": 1,
+ * "total_size_bytes": 1048576
+ * }
+ * ```
+ *
+ * **Example Usage:**
+ * ```bash
+ * curl -H "Authorization: Bearer YOUR_TOKEN" \
+ * https://api.robosystems.ai/v1/graphs/kg123/tables/Entity/files
+ * ```
+ *
+ * **Tips:**
+ * - 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
+ *
+ * **Note:**
+ * File listing is included - no credit consumption.
  */
-export const listTableFilesV1GraphsGraphIdTablesTableNameFilesGet = <ThrowOnError extends boolean = false>(options: Options<ListTableFilesV1GraphsGraphIdTablesTableNameFilesGetData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).get<ListTableFilesV1GraphsGraphIdTablesTableNameFilesGetResponses, ListTableFilesV1GraphsGraphIdTablesTableNameFilesGetErrors, ThrowOnError>({
+export const listTableFiles = <ThrowOnError extends boolean = false>(options: Options<ListTableFilesData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<ListTableFilesResponses, ListTableFilesErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2444,11 +2576,82 @@ export const listTableFilesV1GraphsGraphIdTablesTableNameFilesGet = <ThrowOnErro
 };
 
 /**
- * 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.
+ *
+ * **Purpose:**
+ * Initiate 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 (using curl, axios, etc.)
+ * 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:**
+ * If the table doesn't exist, it's automatically created with:
+ * - Type inferred from name (e.g., "Transaction" → relationship)
+ * - Empty schema (populated on ingestion)
+ * - Ready for file uploads
+ *
+ * **Example Response:**
+ * ```json
+ * {
+ * "upload_url": "https://bucket.s3.amazonaws.com/path?X-Amz-Algorithm=...",
+ * "expires_in": 3600,
+ * "file_id": "f123-456-789",
+ * "s3_key": "user-staging/user123/kg456/Entity/f123.../data.parquet"
+ * }
+ * ```
+ *
+ * **Example Usage:**
+ * ```bash
+ * # Step 1: Get upload URL
+ * curl -X POST "https://api.robosystems.ai/v1/graphs/kg123/tables/Entity/files" \
+ * -H "Authorization: Bearer YOUR_TOKEN" \
+ * -H "Content-Type: application/json" \
+ * -d '{
+ * "file_name": "entities.parquet",
+ * "content_type": "application/x-parquet"
+ * }'
+ *
+ * # Step 2: Upload file directly to S3
+ * curl -X PUT "$UPLOAD_URL" \
+ * -H "Content-Type: application/x-parquet" \
+ * --data-binary "@entities.parquet"
+ *
+ * # Step 3: Mark as uploaded
+ * curl -X PATCH "https://api.robosystems.ai/v1/graphs/kg123/tables/files/$FILE_ID" \
+ * -H "Authorization: Bearer YOUR_TOKEN" \
+ * -H "Content-Type: application/json" \
+ * -d '{"status": "uploaded"}'
+ * ```
+ *
+ * **Tips:**
+ * - Presigned URLs expire (default: 1 hour)
+ * - Use appropriate Content-Type header when uploading to S3
+ * - File extension must match content type
+ * - Large files benefit from direct S3 upload
+ *
+ * **Note:**
+ * Upload URL generation is included - no credit consumption.
  */
-export const getUploadUrlV1GraphsGraphIdTablesTableNameFilesPost = <ThrowOnError extends boolean = false>(options: Options<GetUploadUrlV1GraphsGraphIdTablesTableNameFilesPostData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).post<GetUploadUrlV1GraphsGraphIdTablesTableNameFilesPostResponses, GetUploadUrlV1GraphsGraphIdTablesTableNameFilesPostErrors, ThrowOnError>({
+export const getUploadUrl = <ThrowOnError extends boolean = false>(options: Options<GetUploadUrlData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<GetUploadUrlResponses, GetUploadUrlErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2469,11 +2672,60 @@ export const getUploadUrlV1GraphsGraphIdTablesTableNameFilesPost = <ThrowOnError
 };
 
 /**
- * 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.
+ *
+ * **Purpose:**
+ * 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
+ *
+ * **Example Response:**
+ * ```json
+ * {
+ * "status": "deleted",
+ * "file_id": "f123",
+ * "file_name": "entities_batch1.parquet",
+ * "message": "File deleted successfully. DuckDB will automatically exclude it from queries."
+ * }
+ * ```
+ *
+ * **Example Usage:**
+ * ```bash
+ * curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" \
+ * https://api.robosystems.ai/v1/graphs/kg123/tables/files/f123
+ * ```
+ *
+ * **Tips:**
+ * - 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
+ *
+ * **Note:**
+ * File deletion is included - no credit consumption.
  */
-export const deleteFileV1GraphsGraphIdTablesFilesFileIdDelete = <ThrowOnError extends boolean = false>(options: Options<DeleteFileV1GraphsGraphIdTablesFilesFileIdDeleteData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).delete<DeleteFileV1GraphsGraphIdTablesFilesFileIdDeleteResponses, DeleteFileV1GraphsGraphIdTablesFilesFileIdDeleteErrors, ThrowOnError>({
+export const deleteFile = <ThrowOnError extends boolean = false>(options: Options<DeleteFileData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).delete<DeleteFileResponses, DeleteFileErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2490,11 +2742,51 @@ export const deleteFileV1GraphsGraphIdTablesFilesFileIdDelete = <ThrowOnError ex
 };
 
 /**
- * Get File Info
- * Get detailed information about a specific file
+ * Get File Information
+ * Get detailed information about a specific file.
+ *
+ * **Purpose:**
+ * 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
+ *
+ * **Example Response:**
+ * ```json
+ * {
+ * "file_id": "f123",
+ * "graph_id": "kg123",
+ * "table_id": "t456",
+ * "table_name": "Entity",
+ * "file_name": "entities_batch1.parquet",
+ * "file_format": "parquet",
+ * "size_bytes": 1048576,
+ * "row_count": 5000,
+ * "upload_status": "uploaded",
+ * "upload_method": "presigned_url",
+ * "created_at": "2025-10-28T10:00:00Z",
+ * "uploaded_at": "2025-10-28T10:01:30Z",
+ * "s3_key": "user-staging/user123/kg123/Entity/entities_batch1.parquet"
+ * }
+ * ```
+ *
+ * **Example Usage:**
+ * ```bash
+ * curl -H "Authorization: Bearer YOUR_TOKEN" \
+ * https://api.robosystems.ai/v1/graphs/kg123/tables/files/f123
+ * ```
+ *
+ * **Note:**
+ * File info retrieval is included - no credit consumption.
  */
-export const getFileInfoV1GraphsGraphIdTablesFilesFileIdGet = <ThrowOnError extends boolean = false>(options: Options<GetFileInfoV1GraphsGraphIdTablesFilesFileIdGetData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).get<GetFileInfoV1GraphsGraphIdTablesFilesFileIdGetResponses, GetFileInfoV1GraphsGraphIdTablesFilesFileIdGetErrors, ThrowOnError>({
+export const getFileInfo = <ThrowOnError extends boolean = false>(options: Options<GetFileInfoData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).get<GetFileInfoResponses, GetFileInfoErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2511,11 +2803,72 @@ export const getFileInfoV1GraphsGraphIdTablesFilesFileIdGet = <ThrowOnError exte
 };
 
 /**
- * Update File
- * Update file metadata after upload (size, row count). Marks file as completed.
+ * Update File Upload Status
+ * Update file status after upload completes.
+ *
+ * **Purpose:**
+ * Mark 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:
+ * - Prevents uploads exceeding tier limit
+ * - Returns HTTP 413 if limit exceeded
+ * - Check current usage before large uploads
+ *
+ * **Example Response:**
+ * ```json
+ * {
+ * "status": "success",
+ * "file_id": "f123",
+ * "upload_status": "uploaded",
+ * "file_size_bytes": 1048576,
+ * "row_count": 5000,
+ * "message": "File validated and ready for ingestion"
+ * }
+ * ```
+ *
+ * **Example Usage:**
+ * ```bash
+ * # After uploading file to S3 presigned URL
+ * curl -X PATCH "https://api.robosystems.ai/v1/graphs/kg123/tables/files/f123" \
+ * -H "Authorization: Bearer YOUR_TOKEN" \
+ * -H "Content-Type: application/json" \
+ * -d '{"status": "uploaded"}'
+ * ```
+ *
+ * **Tips:**
+ * - 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)
+ *
+ * **Note:**
+ * Status updates are included - no credit consumption.
  */
-export const updateFileV1GraphsGraphIdTablesFilesFileIdPatch = <ThrowOnError extends boolean = false>(options: Options<UpdateFileV1GraphsGraphIdTablesFilesFileIdPatchData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).patch<UpdateFileV1GraphsGraphIdTablesFilesFileIdPatchResponses, UpdateFileV1GraphsGraphIdTablesFilesFileIdPatchErrors, ThrowOnError>({
+export const updateFileStatus = <ThrowOnError extends boolean = false>(options: Options<UpdateFileStatusData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).patch<UpdateFileStatusResponses, UpdateFileStatusErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2537,10 +2890,101 @@ export const updateFileV1GraphsGraphIdTablesFilesFileIdPatch = <ThrowOnError ext
 
 /**
  * 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).
+ * Load all files from S3 into DuckDB staging tables and ingest into Kuzu graph database.
+ *
+ * **Purpose:**
+ * 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
+ *
+ * **Example Request:**
+ * ```bash
+ * curl -X POST "https://api.robosystems.ai/v1/graphs/kg123/tables/ingest" \
+ * -H "Authorization: Bearer YOUR_TOKEN" \
+ * -H "Content-Type: application/json" \
+ * -d '{
+ * "ignore_errors": true,
+ * "rebuild": false
+ * }'
+ * ```
+ *
+ * **Example Response:**
+ * ```json
+ * {
+ * "status": "success",
+ * "graph_id": "kg123",
+ * "total_tables": 5,
+ * "successful_tables": 5,
+ * "failed_tables": 0,
+ * "skipped_tables": 0,
+ * "total_rows_ingested": 25000,
+ * "total_execution_time_ms": 15420.5,
+ * "results": [
+ * {
+ * "table_name": "Entity",
+ * "status": "success",
+ * "rows_ingested": 5000,
+ * "execution_time_ms": 3200.1,
+ * "error": null
+ * }
+ * ]
+ * }
+ * ```
+ *
+ * **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.
+ *
+ * **Tips:**
+ * - 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
+ *
+ * **Note:**
+ * Table ingestion is included - no credit consumption.
  */
-export const ingestTablesV1GraphsGraphIdTablesIngestPost = <ThrowOnError extends boolean = false>(options: Options<IngestTablesV1GraphsGraphIdTablesIngestPostData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).post<IngestTablesV1GraphsGraphIdTablesIngestPostResponses, IngestTablesV1GraphsGraphIdTablesIngestPostErrors, ThrowOnError>({
+export const ingestTables = <ThrowOnError extends boolean = false>(options: Options<IngestTablesData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<IngestTablesResponses, IngestTablesErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -2562,10 +3006,68 @@ export const ingestTablesV1GraphsGraphIdTablesIngestPost = <ThrowOnError extends
 
 /**
  * Query Staging Tables with SQL
- * Execute SQL queries on DuckDB staging tables
+ * Execute SQL queries on DuckDB staging tables for data inspection and validation.
+ *
+ * **Purpose:**
+ * Query raw staging data directly with SQL before ingestion into the graph database.
+ * Useful for data quality checks, validation, and exploratory analysis.
+ *
+ * **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
+ *
+ * **Example Queries:**
+ * ```sql
+ * -- Count rows in staging table
+ * SELECT COUNT(*) FROM Entity;
+ *
+ * -- 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;
+ *
+ * -- Join across tables
+ * SELECT e.name, COUNT(t.id) as transaction_count
+ * FROM Entity e
+ * LEFT JOIN Transaction t ON e.identifier = t.entity_id
+ * GROUP BY e.name
+ * ORDER BY transaction_count DESC;
+ * ```
+ *
+ * **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.
  */
-export const queryTablesV1GraphsGraphIdTablesQueryPost = <ThrowOnError extends boolean = false>(options: Options<QueryTablesV1GraphsGraphIdTablesQueryPostData, ThrowOnError>) => {
-    return (options.client ?? _heyApiClient).post<QueryTablesV1GraphsGraphIdTablesQueryPostResponses, QueryTablesV1GraphsGraphIdTablesQueryPostErrors, ThrowOnError>({
+export const queryTables = <ThrowOnError extends boolean = false>(options: Options<QueryTablesData, ThrowOnError>) => {
+    return (options.client ?? _heyApiClient).post<QueryTablesResponses, QueryTablesErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',