@robosystems/client 0.2.2 → 0.2.4

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, 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 type { RegisterUserData, RegisterUserResponses, RegisterUserErrors, LoginUserData, LoginUserResponses, LoginUserErrors, LogoutUserData, LogoutUserResponses, 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, UpdateUserData, UpdateUserResponses, UpdateUserErrors, GetAllCreditSummariesData, GetAllCreditSummariesResponses, GetAllCreditSummariesErrors, UpdateUserPasswordData, UpdateUserPasswordResponses, UpdateUserPasswordErrors, ListUserApiKeysData, ListUserApiKeysResponses, CreateUserApiKeyData, CreateUserApiKeyResponses, CreateUserApiKeyErrors, RevokeUserApiKeyData, RevokeUserApiKeyResponses, RevokeUserApiKeyErrors, UpdateUserApiKeyData, UpdateUserApiKeyResponses, UpdateUserApiKeyErrors, GetUserLimitsData, GetUserLimitsResponses, GetUserLimitsErrors, GetUserUsageData, GetUserUsageResponses, GetAllSharedRepositoryLimitsData, GetAllSharedRepositoryLimitsResponses, GetSharedRepositoryLimitsData, GetSharedRepositoryLimitsResponses, GetSharedRepositoryLimitsErrors, GetUserUsageOverviewData, GetUserUsageOverviewResponses, 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, GetAvailableExtensionsErrors, 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> & {
@@ -53,7 +53,7 @@ export const loginUser = <ThrowOnError extends boolean = false>(options: Options
  * Logout user and invalidate session.
  */
 export const logoutUser = <ThrowOnError extends boolean = false>(options?: Options<LogoutUserData, ThrowOnError>) => {
-    return (options?.client ?? _heyApiClient).post<LogoutUserResponses, LogoutUserErrors, ThrowOnError>({
+    return (options?.client ?? _heyApiClient).post<LogoutUserResponses, unknown, ThrowOnError>({
         url: '/v1/auth/logout',
         ...options
     });
@@ -242,7 +242,7 @@ export const getServiceStatus = <ThrowOnError extends boolean = false>(options?:
  * Returns information about the currently authenticated user.
  */
 export const getCurrentUser = <ThrowOnError extends boolean = false>(options?: Options<GetCurrentUserData, ThrowOnError>) => {
-    return (options?.client ?? _heyApiClient).get<GetCurrentUserResponses, GetCurrentUserErrors, ThrowOnError>({
+    return (options?.client ?? _heyApiClient).get<GetCurrentUserResponses, unknown, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -340,7 +340,7 @@ export const updateUserPassword = <ThrowOnError extends boolean = false>(options
  * Get all API keys for the current user.
  */
 export const listUserApiKeys = <ThrowOnError extends boolean = false>(options?: Options<ListUserApiKeysData, ThrowOnError>) => {
-    return (options?.client ?? _heyApiClient).get<ListUserApiKeysResponses, ListUserApiKeysErrors, ThrowOnError>({
+    return (options?.client ?? _heyApiClient).get<ListUserApiKeysResponses, unknown, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -453,7 +453,7 @@ export const getUserLimits = <ThrowOnError extends boolean = false>(options?: Op
  * Retrieve current usage statistics and remaining limits for the authenticated user
  */
 export const getUserUsage = <ThrowOnError extends boolean = false>(options?: Options<GetUserUsageData, ThrowOnError>) => {
-    return (options?.client ?? _heyApiClient).get<GetUserUsageResponses, GetUserUsageErrors, ThrowOnError>({
+    return (options?.client ?? _heyApiClient).get<GetUserUsageResponses, unknown, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -474,7 +474,7 @@ export const getUserUsage = <ThrowOnError extends boolean = false>(options?: Opt
  * Get rate limit status for all shared repositories the user has access to.
  */
 export const getAllSharedRepositoryLimits = <ThrowOnError extends boolean = false>(options?: Options<GetAllSharedRepositoryLimitsData, ThrowOnError>) => {
-    return (options?.client ?? _heyApiClient).get<GetAllSharedRepositoryLimitsResponses, GetAllSharedRepositoryLimitsErrors, ThrowOnError>({
+    return (options?.client ?? _heyApiClient).get<GetAllSharedRepositoryLimitsResponses, unknown, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -524,7 +524,7 @@ export const getSharedRepositoryLimits = <ThrowOnError extends boolean = false>(
  * Get a high-level overview of usage statistics for the current user.
  */
 export const getUserUsageOverview = <ThrowOnError extends boolean = false>(options?: Options<GetUserUsageOverviewData, ThrowOnError>) => {
-    return (options?.client ?? _heyApiClient).get<GetUserUsageOverviewResponses, GetUserUsageOverviewErrors, ThrowOnError>({
+    return (options?.client ?? _heyApiClient).get<GetUserUsageOverviewResponses, unknown, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -1291,9 +1291,8 @@ export const recommendAgent = <ThrowOnError extends boolean = false>(options: Op
  * - 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.
  */
 export const listMcpTools = <ThrowOnError extends boolean = false>(options: Options<ListMcpToolsData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).get<ListMcpToolsResponses, ListMcpToolsErrors, ThrowOnError>({
@@ -1346,8 +1345,11 @@ export const listMcpTools = <ThrowOnError extends boolean = false>(options: Opti
  * - `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.
  */
 export const callMcpTool = <ThrowOnError extends boolean = false>(options: Options<CallMcpToolData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).post<CallMcpToolResponses, CallMcpToolErrors, ThrowOnError>({
@@ -1654,6 +1656,13 @@ export const getGraphUsageStats = <ThrowOnError extends boolean = false>(options
  * 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)
@@ -1725,13 +1734,38 @@ export const executeCypherQuery = <ThrowOnError extends boolean = false>(options
  * 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
  *
- * This shows what actually exists in the database right now - the runtime state.
- * For the declared schema definition, use GET /schema/export instead.
+ * **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
+ *
+ * **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.
  */
@@ -1753,8 +1787,54 @@ export const getGraphSchema = <ThrowOnError extends boolean = false>(options: Op
 };
 
 /**
- * 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.
  */
 export const exportGraphSchema = <ThrowOnError extends boolean = false>(options: Options<ExportGraphSchemaData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).get<ExportGraphSchemaResponses, ExportGraphSchemaErrors, ThrowOnError>({
@@ -2405,12 +2485,11 @@ export const getSubgraphQuota = <ThrowOnError extends boolean = false>(options:
  * List Staging Tables
  * 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:**
+ * **Returned Metrics:**
  * - Table name and type (node/relationship)
  * - File count per table
  * - Total storage size in bytes
@@ -2432,43 +2511,12 @@ export const getSubgraphQuota = <ThrowOnError extends boolean = false>(options:
  * 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:**
+ * **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
- *
- * **Note:**
- * Table queries are included - no credit consumption.
+ * - Table queries are included - no credit consumption
  */
 export const listTables = <ThrowOnError extends boolean = false>(options: Options<ListTablesData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).get<ListTablesResponses, ListTablesErrors, ThrowOnError>({
@@ -2491,7 +2539,6 @@ export const listTables = <ThrowOnError extends boolean = false>(options: Option
  * 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.
@@ -2504,59 +2551,26 @@ export const listTables = <ThrowOnError extends boolean = false>(options: Option
  * - 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)
+ * **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:**
- * - `created`: File record created, not yet uploaded
- * - `uploading`: Upload in progress
+ * - `pending`: Upload URL generated, awaiting upload
  * - `uploaded`: Successfully uploaded, ready for ingestion
+ * - `disabled`: Excluded from ingestion
+ * - `archived`: Soft deleted
  * - `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:**
+ * **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
- *
- * **Note:**
- * File listing is included - no credit consumption.
+ * - File listing is included - no credit consumption
  */
 export const listTableFiles = <ThrowOnError extends boolean = false>(options: Options<ListTableFilesData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).get<ListTableFilesResponses, ListTableFilesErrors, ThrowOnError>({
@@ -2579,14 +2593,13 @@ export const listTableFiles = <ThrowOnError extends boolean = false>(options: Op
  * 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
+ * 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 (using curl, axios, etc.)
+ * 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
@@ -2603,52 +2616,14 @@ export const listTableFiles = <ThrowOnError extends boolean = false>(options: Op
  * - 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"}'
- * ```
+ * Tables are automatically created on first file upload with type inferred from name
+ * (e.g., "Transaction" → relationship) and empty schema populated during ingestion.
  *
- * **Tips:**
+ * **Important Notes:**
  * - 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.
+ * - Upload URL generation is included - no credit consumption
  */
 export const getUploadUrl = <ThrowOnError extends boolean = false>(options: Options<GetUploadUrlData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).post<GetUploadUrlResponses, GetUploadUrlErrors, ThrowOnError>({
@@ -2675,7 +2650,6 @@ export const getUploadUrl = <ThrowOnError extends boolean = false>(options: Opti
  * 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.
@@ -2699,30 +2673,12 @@ export const getUploadUrl = <ThrowOnError extends boolean = false>(options: Opti
  * - 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:**
+ * **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
- *
- * **Note:**
- * File deletion is included - no credit consumption.
+ * - File deletion is included - no credit consumption
  */
 export const deleteFile = <ThrowOnError extends boolean = false>(options: Options<DeleteFileData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).delete<DeleteFileResponses, DeleteFileErrors, ThrowOnError>({
@@ -2745,7 +2701,6 @@ export const deleteFile = <ThrowOnError extends boolean = false>(options: Option
  * 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.
@@ -2757,33 +2712,8 @@ export const deleteFile = <ThrowOnError extends boolean = false>(options: Option
  * - 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.
+ * File info retrieval is included - no credit consumption
  */
 export const getFileInfo = <ThrowOnError extends boolean = false>(options: Options<GetFileInfoData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).get<GetFileInfoResponses, GetFileInfoErrors, ThrowOnError>({
@@ -2806,8 +2736,7 @@ export const getFileInfo = <ThrowOnError extends boolean = false>(options: Optio
  * Update File Upload Status
  * Update file status after upload completes.
  *
- * **Purpose:**
- * Mark files as uploaded after successful S3 upload. The backend validates
+ * 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.
  *
@@ -2832,40 +2761,15 @@ export const getFileInfo = <ThrowOnError extends boolean = false>(options: Optio
  * - **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"}'
- * ```
+ * Enforced per subscription tier. Returns HTTP 413 if limit exceeded.
+ * Check current usage before large uploads.
  *
- * **Tips:**
+ * **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)
- *
- * **Note:**
- * Status updates are included - no credit consumption.
+ * - Status updates are included - no credit consumption
  */
 export const updateFileStatus = <ThrowOnError extends boolean = false>(options: Options<UpdateFileStatusData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).patch<UpdateFileStatusResponses, UpdateFileStatusErrors, ThrowOnError>({
@@ -2892,7 +2796,6 @@ export const updateFileStatus = <ThrowOnError extends boolean = false>(options:
  * Ingest Tables to Graph
  * 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.
  *
@@ -2933,55 +2836,19 @@ export const updateFileStatus = <ThrowOnError extends boolean = false>(options:
  * - 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:**
+ * **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
- *
- * **Note:**
- * Table ingestion is included - no credit consumption.
+ * - Table ingestion is included - no credit consumption
  */
 export const ingestTables = <ThrowOnError extends boolean = false>(options: Options<IngestTablesData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).post<IngestTablesResponses, IngestTablesErrors, ThrowOnError>({
@@ -3008,10 +2875,16 @@ export const ingestTables = <ThrowOnError extends boolean = false>(options: Opti
  * Query Staging Tables with SQL
  * 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.
  *
+ * **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
@@ -3031,27 +2904,12 @@ export const ingestTables = <ThrowOnError extends boolean = false>(options: Opti
  * - 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;
- * ```
+ * **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
@@ -3064,7 +2922,7 @@ export const ingestTables = <ThrowOnError extends boolean = false>(options: Opti
  * Use the graph query endpoint instead: `POST /v1/graphs/{graph_id}/query`
  *
  * **Note:**
- * Staging table queries are included - no credit consumption.
+ * Staging table queries are included - no credit consumption
  */
 export const queryTables = <ThrowOnError extends boolean = false>(options: Options<QueryTablesData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).post<QueryTablesResponses, QueryTablesErrors, ThrowOnError>({
@@ -3089,7 +2947,40 @@ export const queryTables = <ThrowOnError extends boolean = false>(options: Optio
 
 /**
  * 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.
  */
 export const getGraphs = <ThrowOnError extends boolean = false>(options?: Options<GetGraphsData, ThrowOnError>) => {
     return (options?.client ?? _heyApiClient).get<GetGraphsResponses, GetGraphsErrors, ThrowOnError>({
@@ -3174,10 +3065,37 @@ export const createGraph = <ThrowOnError extends boolean = false>(options: Optio
 
 /**
  * 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.
  */
 export const getAvailableExtensions = <ThrowOnError extends boolean = false>(options?: Options<GetAvailableExtensionsData, ThrowOnError>) => {
-    return (options?.client ?? _heyApiClient).get<GetAvailableExtensionsResponses, unknown, ThrowOnError>({
+    return (options?.client ?? _heyApiClient).get<GetAvailableExtensionsResponses, GetAvailableExtensionsErrors, ThrowOnError>({
         security: [
             {
                 name: 'X-API-Key',
@@ -3195,7 +3113,35 @@ export const getAvailableExtensions = <ThrowOnError extends boolean = false>(opt
 
 /**
  * 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.
  */
 export const selectGraph = <ThrowOnError extends boolean = false>(options: Options<SelectGraphData, ThrowOnError>) => {
     return (options.client ?? _heyApiClient).post<SelectGraphResponses, SelectGraphErrors, ThrowOnError>({