@katerai/sdk 0.3.0 → 0.5.0

package/src/resources/v1/connections/connections.ts

@@ -4,6 +4,7 @@ import { APIResource } from '../../../core/resource';
 import * as DatabasesAPI from './databases';
 import { DatabaseDeleteSchemaParams, Databases } from './databases';
 import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
 import { RequestOptions } from '../../../internal/request-options';
 import { path } from '../../../internal/utils/path';
 
@@ -21,6 +22,10 @@ export class Connections extends APIResource {
    * Get a single warehouse connection by kater_id.
    *
    * Returns connection from the database (source of truth) with full hierarchy.
+   * Supports content negotiation via Accept header (handled by MultiFormatRoute):
+   *
+   * - application/json (default): Returns JSON response
+   * - application/yaml: Returns YAML representation
    *
    * RLS: Filtered to current client (DualClientRLSDB).
    *
@@ -30,6 +35,23 @@ export class Connections extends APIResource {
     return this._client.get(path`/api/v1/connections/${connectionID}`, options);
   }
 
+  /**
+   * Update a warehouse connection's metadata.
+   *
+   * Updates name, label, and/or description fields.
+   *
+   * RLS: Filtered to current client (ClientRLSDB).
+   *
+   * Raises: ConnectionNotFoundError: If connection doesn't exist (404)
+   */
+  update(
+    connectionID: string,
+    body: ConnectionUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<Connection> {
+    return this._client.patch(path`/api/v1/connections/${connectionID}`, { body, ...options });
+  }
+
   /**
    * List all warehouse connections for the client.
    *
@@ -43,6 +65,23 @@ export class Connections extends APIResource {
     return this._client.get('/api/v1/connections', options);
   }
 
+  /**
+   * Delete a warehouse connection.
+   *
+   * Soft-deletes the connection record and cascades to all associated databases and
+   * schemas, setting deleted_at and deleted_by fields.
+   *
+   * RLS: Filtered to current client (ClientRLSDB).
+   *
+   * Raises: ConnectionNotFoundError: If connection doesn't exist (404)
+   */
+  delete(connectionID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/api/v1/connections/${connectionID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
   /**
    * Get decrypted warehouse credentials for a connection.
    *
@@ -71,12 +110,12 @@ export class Connections extends APIResource {
 /**
  * Response model for a single connection.
  *
- * All data comes from the database (source of truth). The id field serves as the
- * kater_id.
+ * All data comes from the database (source of truth). JSON responses use 'id'
+ * field; YAML responses transform to 'kater_id' via MultiFormatRoute.
  */
 export interface Connection {
   /**
-   * Connection ID (also the kater_id)
+   * Connection ID
    */
   id: string;
 
@@ -95,16 +134,6 @@ export interface Connection {
    */
   databases: Array<Connection.Database>;
 
-  /**
-   * Connection description
-   */
-  description: string | null;
-
-  /**
-   * Human-readable label
-   */
-  label: string | null;
-
   /**
    * Connection name
    */
@@ -116,39 +145,49 @@ export interface Connection {
   updated_at: string;
 
   /**
-   * Snowflake account identifier
+   * Warehouse-specific configuration
    */
-  account?: string | null;
+  warehouse_metadata:
+    | Connection.SnowflakeMetadata
+    | Connection.PostgresMetadata
+    | Connection.DatabricksMetadata
+    | Connection.ClickHouseMetadata
+    | Connection.MssqlMetadata;
 
   /**
-   * Database host (PostgreSQL, MSSQL, ClickHouse)
+   * Warehouse type (snowflake, postgresql, etc.)
    */
-  host?: string | null;
+  warehouse_type: string;
 
   /**
-   * Databricks HTTP path
+   * Default timezone for the connection
    */
-  http_path?: string | null;
+  database_timezone?: string | null;
 
   /**
-   * Database port (PostgreSQL, MSSQL, ClickHouse)
+   * Connection description
    */
-  port?: number | null;
+  description?: string | null;
 
   /**
-   * Snowflake role
+   * Human-readable label
    */
-  role?: string | null;
+  label?: string | null;
 
   /**
-   * Databricks server hostname
+   * Query timeout in seconds
    */
-  server_hostname?: string | null;
+  query_timeout?: number | null;
 
   /**
-   * Snowflake or Databricks warehouse name
+   * Timezone conversion mode (do_not_convert, convert_to_utc)
    */
-  warehouse?: string | null;
+  query_timezone_conversion?: string | null;
+
+  /**
+   * Sync identifier for schema sync
+   */
+  sync_id?: string | null;
 }
 
 export namespace Connection {
@@ -162,14 +201,9 @@ export namespace Connection {
     id: string;
 
     /**
-     * Database description
-     */
-    description: string | null;
-
-    /**
-     * Human-readable label
+     * Actual name of the database in the warehouse
      */
-    label: string | null;
+    database_object_name: string;
 
     /**
      * Database name
@@ -181,10 +215,20 @@ export namespace Connection {
      */
     schemas: Array<Database.Schema>;
 
+    /**
+     * Database description
+     */
+    description?: string | null;
+
+    /**
+     * Human-readable label
+     */
+    label?: string | null;
+
     /**
      * Timezone for the database
      */
-    timezone: string | null;
+    timezone?: string | null;
   }
 
   export namespace Database {
@@ -198,21 +242,136 @@ export namespace Connection {
       id: string;
 
       /**
-       * Schema description
+       * Actual name of the schema in the warehouse
        */
-      description: string | null;
+      database_object_name: string;
 
       /**
-       * Human-readable label
+       * Schema name
        */
-      label: string | null;
+      name: string;
 
       /**
-       * Schema name
+       * Schema description
        */
-      name: string;
+      description?: string | null;
+
+      /**
+       * Human-readable label
+       */
+      label?: string | null;
     }
   }
+
+  /**
+   * Snowflake-specific warehouse metadata.
+   */
+  export interface SnowflakeMetadata {
+    /**
+     * Authentication method
+     */
+    auth_method: 'username_password' | 'key_pair';
+
+    /**
+     * Snowflake role
+     */
+    role: string;
+
+    /**
+     * Snowflake account identifier
+     */
+    snowflake_account_id: string;
+
+    /**
+     * Compute warehouse name
+     */
+    warehouse: string;
+
+    /**
+     * Warehouse type discriminator
+     */
+    warehouse_type: 'snowflake';
+  }
+
+  /**
+   * PostgreSQL-specific warehouse metadata.
+   */
+  export interface PostgresMetadata {
+    /**
+     * Database host
+     */
+    host: string;
+
+    /**
+     * Database port
+     */
+    port: number;
+
+    /**
+     * Warehouse type discriminator
+     */
+    warehouse_type: 'postgresql';
+  }
+
+  /**
+   * Databricks-specific warehouse metadata.
+   */
+  export interface DatabricksMetadata {
+    /**
+     * SQL warehouse HTTP path
+     */
+    http_path: string;
+
+    /**
+     * Databricks server hostname
+     */
+    server_hostname: string;
+
+    /**
+     * Warehouse type discriminator
+     */
+    warehouse_type: 'databricks';
+  }
+
+  /**
+   * ClickHouse-specific warehouse metadata.
+   */
+  export interface ClickHouseMetadata {
+    /**
+     * ClickHouse host
+     */
+    host: string;
+
+    /**
+     * ClickHouse port
+     */
+    port: number;
+
+    /**
+     * Warehouse type discriminator
+     */
+    warehouse_type: 'clickhouse';
+  }
+
+  /**
+   * Microsoft SQL Server-specific warehouse metadata.
+   */
+  export interface MssqlMetadata {
+    /**
+     * SQL Server host
+     */
+    host: string;
+
+    /**
+     * SQL Server port
+     */
+    port: number;
+
+    /**
+     * Warehouse type discriminator
+     */
+    warehouse_type: 'mssql';
+  }
 }
 
 /**
@@ -220,9 +379,9 @@ export namespace Connection {
  */
 export interface DatabaseConfig {
   /**
-   * Database name
+   * The actual name of the database object in the warehouse
    */
-  name: string;
+  database_object_name: string;
 
   /**
    * Description of the database
@@ -234,6 +393,11 @@ export interface DatabaseConfig {
    */
   label?: string | null;
 
+  /**
+   * Database name (defaults to database_object_name if not set)
+   */
+  name?: string | null;
+
   /**
    * Schema configurations to include (empty = discover all schemas)
    */
@@ -251,9 +415,9 @@ export namespace DatabaseConfig {
    */
   export interface Schema {
     /**
-     * Schema name
+     * The actual name of the schema object in the warehouse
      */
-    name: string;
+    database_object_name: string;
 
     /**
      * Description of the schema
@@ -264,6 +428,11 @@ export namespace DatabaseConfig {
      * Human-readable label for the schema (defaults to name if not set)
      */
     label?: string | null;
+
+    /**
+     * Schema name (defaults to database_object_name if not set)
+     */
+    name?: string | null;
   }
 }
 
@@ -287,7 +456,7 @@ export namespace ConnectionRetrieveCredentialResponse {
     /**
      * Database name
      */
-    database: string | null;
+    database: string;
 
     /**
      * Database host
@@ -385,7 +554,7 @@ export namespace ConnectionRetrieveCredentialResponse {
       /**
        * Passphrase if key is encrypted
        */
-      private_key_passphrase: string | null;
+      private_key_passphrase?: string | null;
     }
   }
 
@@ -418,11 +587,6 @@ export namespace ConnectionRetrieveCredentialResponse {
    * ClickHouse credential response.
    */
   export interface ClickHouseCredentialResponse {
-    /**
-     * Database name
-     */
-    database: string | null;
-
     /**
      * ClickHouse host
      */
@@ -447,17 +611,17 @@ export namespace ConnectionRetrieveCredentialResponse {
      * Warehouse type
      */
     warehouse_type: 'clickhouse';
+
+    /**
+     * Database name
+     */
+    database?: string | null;
   }
 
   /**
    * Microsoft SQL Server credential response.
    */
   export interface MssqlCredentialResponse {
-    /**
-     * Database name
-     */
-    database: string | null;
-
     /**
      * SQL Server host
      */
@@ -482,29 +646,40 @@ export namespace ConnectionRetrieveCredentialResponse {
      * Warehouse type
      */
     warehouse_type: 'mssql';
+
+    /**
+     * Database name
+     */
+    database?: string | null;
   }
 }
 
 /**
  * Response for syncing views.
  *
- * Returned after successfully creating a PR with merged ViewSchema files.
+ * Returned after successfully creating a PR with merged ViewSchema files, or
+ * indicating that all views are already up to date.
  */
 export interface ConnectionSyncResponse {
   /**
-   * GitHub PR number
+   * Number of views in the PR
    */
-  pr_number: number;
+  views_updated: number;
 
   /**
-   * GitHub PR URL
+   * Status message
    */
-  pr_url: string;
+  message?: string | null;
 
   /**
-   * Number of views in the PR
+   * GitHub PR number
    */
-  views_updated: number;
+  pr_number?: number | null;
+
+  /**
+   * GitHub PR URL
+   */
+  pr_url?: string | null;
 }
 
 export type ConnectionCreateParams =
@@ -527,7 +702,7 @@ export declare namespace ConnectionCreateParams {
     host: string;
 
     /**
-     * Name of the connection
+     * Name of the connection (snake_case: lowercase letters, numbers, underscores)
      */
     name: string;
 
@@ -546,6 +721,11 @@ export declare namespace ConnectionCreateParams {
      */
     warehouse_type: 'postgresql';
 
+    /**
+     * Default timezone for the connection (e.g., 'UTC', 'America/New_York')
+     */
+    database_timezone?: string | null;
+
     /**
      * Description of the connection
      */
@@ -560,6 +740,16 @@ export declare namespace ConnectionCreateParams {
      * Database port
      */
     port?: number;
+
+    /**
+     * Query timeout in seconds (1-3600)
+     */
+    query_timeout?: number | null;
+
+    /**
+     * Timezone conversion mode: 'do_not_convert' or 'convert_to_utc'
+     */
+    query_timezone_conversion?: string | null;
   }
 
   export interface SnowflakeConnectionConfig {
@@ -579,7 +769,7 @@ export declare namespace ConnectionCreateParams {
     databases: Array<DatabaseConfig>;
 
     /**
-     * Name of the connection
+     * Name of the connection (snake_case: lowercase letters, numbers, underscores)
      */
     name: string;
 
@@ -603,6 +793,11 @@ export declare namespace ConnectionCreateParams {
      */
     warehouse_type: 'snowflake';
 
+    /**
+     * Default timezone for the connection (e.g., 'UTC', 'America/New_York')
+     */
+    database_timezone?: string | null;
+
     /**
      * Description of the connection
      */
@@ -612,6 +807,16 @@ export declare namespace ConnectionCreateParams {
      * Human-readable label for the connection (defaults to name if not set)
      */
     label?: string | null;
+
+    /**
+     * Query timeout in seconds (1-3600)
+     */
+    query_timeout?: number | null;
+
+    /**
+     * Timezone conversion mode: 'do_not_convert' or 'convert_to_utc'
+     */
+    query_timezone_conversion?: string | null;
   }
 
   export namespace SnowflakeConnectionConfig {
@@ -668,7 +873,7 @@ export declare namespace ConnectionCreateParams {
     http_path: string;
 
     /**
-     * Name of the connection
+     * Name of the connection (snake_case: lowercase letters, numbers, underscores)
      */
     name: string;
 
@@ -682,6 +887,11 @@ export declare namespace ConnectionCreateParams {
      */
     warehouse_type: 'databricks';
 
+    /**
+     * Default timezone for the connection (e.g., 'UTC', 'America/New_York')
+     */
+    database_timezone?: string | null;
+
     /**
      * Description of the connection
      */
@@ -691,6 +901,16 @@ export declare namespace ConnectionCreateParams {
      * Human-readable label for the connection (defaults to name if not set)
      */
     label?: string | null;
+
+    /**
+     * Query timeout in seconds (1-3600)
+     */
+    query_timeout?: number | null;
+
+    /**
+     * Timezone conversion mode: 'do_not_convert' or 'convert_to_utc'
+     */
+    query_timezone_conversion?: string | null;
   }
 
   export interface ClickHouseConnectionConfig {
@@ -705,7 +925,7 @@ export declare namespace ConnectionCreateParams {
     host: string;
 
     /**
-     * Name of the connection
+     * Name of the connection (snake_case: lowercase letters, numbers, underscores)
      */
     name: string;
 
@@ -724,6 +944,11 @@ export declare namespace ConnectionCreateParams {
      */
     warehouse_type: 'clickhouse';
 
+    /**
+     * Default timezone for the connection (e.g., 'UTC', 'America/New_York')
+     */
+    database_timezone?: string | null;
+
     /**
      * Description of the connection
      */
@@ -738,6 +963,16 @@ export declare namespace ConnectionCreateParams {
      * ClickHouse port
      */
     port?: number;
+
+    /**
+     * Query timeout in seconds (1-3600)
+     */
+    query_timeout?: number | null;
+
+    /**
+     * Timezone conversion mode: 'do_not_convert' or 'convert_to_utc'
+     */
+    query_timezone_conversion?: string | null;
   }
 
   export interface MssqlConnectionConfig {
@@ -752,7 +987,7 @@ export declare namespace ConnectionCreateParams {
     host: string;
 
     /**
-     * Name of the connection
+     * Name of the connection (snake_case: lowercase letters, numbers, underscores)
      */
     name: string;
 
@@ -771,6 +1006,11 @@ export declare namespace ConnectionCreateParams {
      */
     warehouse_type: 'mssql';
 
+    /**
+     * Default timezone for the connection (e.g., 'UTC', 'America/New_York')
+     */
+    database_timezone?: string | null;
+
     /**
      * Description of the connection
      */
@@ -785,9 +1025,36 @@ export declare namespace ConnectionCreateParams {
      * SQL Server port
      */
     port?: number;
+
+    /**
+     * Query timeout in seconds (1-3600)
+     */
+    query_timeout?: number | null;
+
+    /**
+     * Timezone conversion mode: 'do_not_convert' or 'convert_to_utc'
+     */
+    query_timezone_conversion?: string | null;
   }
 }
 
+export interface ConnectionUpdateParams {
+  /**
+   * Connection description
+   */
+  description?: string | null;
+
+  /**
+   * Human-readable display label
+   */
+  label?: string | null;
+
+  /**
+   * Connection name (snake_case identifier)
+   */
+  name?: string | null;
+}
+
 Connections.Databases = Databases;
 
 export declare namespace Connections {
@@ -798,6 +1065,7 @@ export declare namespace Connections {
     type ConnectionRetrieveCredentialResponse as ConnectionRetrieveCredentialResponse,
     type ConnectionSyncResponse as ConnectionSyncResponse,
     type ConnectionCreateParams as ConnectionCreateParams,
+    type ConnectionUpdateParams as ConnectionUpdateParams,
   };
 
   export { Databases as Databases, type DatabaseDeleteSchemaParams as DatabaseDeleteSchemaParams };

package/src/resources/v1/connections/index.ts

@@ -8,5 +8,6 @@ export {
   type ConnectionRetrieveCredentialResponse,
   type ConnectionSyncResponse,
   type ConnectionCreateParams,
+  type ConnectionUpdateParams,
 } from './connections';
 export { Databases, type DatabaseDeleteSchemaParams } from './databases';