@superblocksteam/sdk-api 2.0.93-next.7 → 2.0.94-next.0

package/src/integrations/couchbase/types.ts

@@ -2,8 +2,8 @@
  * Couchbase client types.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Parameters for identifying a Couchbase document location.
@@ -28,31 +28,32 @@ export interface CouchbaseIdentifier {
  *
  * @example
  * ```typescript
- * const cb = ctx.couchbase('Production Couchbase');
+ * // Declare in api(): integrations: { cb: couchbase(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.cb
  *
  * // Run a SQL++ query
- * const users = await cb.query(
+ * const users = await ctx.integrations.cb.query(
  *   'my-bucket',
  *   'SELECT * FROM bucket WHERE status = "active"',
  *   UserSchema,
  * );
  *
  * // Insert a document
- * await cb.insert('user::123', { name: 'Alice' }, {
+ * await ctx.integrations.cb.insert('user::123', { name: 'Alice' }, {
  *   bucket: 'my-bucket',
  *   scope: '_default',
  *   collection: '_default',
  * });
  *
  * // Get a document
- * const doc = await cb.get('user::123', DocSchema, {
+ * const doc = await ctx.integrations.cb.get('user::123', DocSchema, {
  *   bucket: 'my-bucket',
  *   scope: '_default',
  *   collection: '_default',
  * });
  *
  * // Remove a document
- * await cb.remove('user::123', {
+ * await ctx.integrations.cb.remove('user::123', {
  *   bucket: 'my-bucket',
  *   scope: '_default',
  *   collection: '_default',
@@ -69,7 +70,12 @@ export interface CouchbaseClient extends BaseIntegrationClient {
    * @param params - Optional array of parameter values for server-side binding
    * @returns Array of validated result rows
    */
-  query<T>(bucket: string, sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]>;
+  query<T>(
+    bucket: string,
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]>;
 
   /**
    * Insert a document into a collection.

package/src/integrations/databricks/README.md

@@ -4,17 +4,17 @@ Execute SQL queries against Databricks SQL warehouses with full type safety and
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                           | Description                                                |
+| -------------------------------- | ---------------------------------------------------------- |
 | `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results |
-| `execute(sql, params?)` | Execute a statement and return affected row count |
+| `execute(sql, params?)`          | Execute a statement and return affected row count          |
 
 ## Usage
 
 ### Basic Query with Schema Validation
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, databricks } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_DATABRICKS = "a1b2c3d4-5678-90ab-cdef-databric0001";
@@ -27,6 +27,9 @@ const DataSchema = z.object({
 
 export default api({
   name: "DatabricksExample",
+  integrations: {
+    databricks: databricks(PROD_DATABRICKS),
+  },
   input: z.object({
     date: z.string(),
   }),
@@ -34,12 +37,10 @@ export default api({
     data: z.array(DataSchema),
   }),
   async run(ctx, { date }) {
-    const databricks = ctx.databricks(PROD_DATABRICKS);
-
-    const data = await databricks.query(
+    const data = await ctx.integrations.databricks.query(
       "SELECT id, value, timestamp FROM data WHERE date = $1",
       DataSchema,
-      [date]
+      [date],
     );
 
     return { data };
@@ -50,25 +51,23 @@ export default api({
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
-const databricks = ctx.databricks(PROD_DATABRICKS);
-
 // INSERT
-await databricks.execute(
+await ctx.integrations.databricks.execute(
   "INSERT INTO metrics (name, value) VALUES ($1, $2)",
-  ["cpu_usage", "75.5"]
+  ["cpu_usage", "75.5"],
 );
 
 // UPDATE
-const updateResult = await databricks.execute(
+const updateResult = await ctx.integrations.databricks.execute(
   "UPDATE metrics SET value = $1 WHERE name = $2",
-  ["80.0", "cpu_usage"]
+  ["80.0", "cpu_usage"],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
-const deleteResult = await databricks.execute(
+const deleteResult = await ctx.integrations.databricks.execute(
   "DELETE FROM metrics WHERE timestamp < $1",
-  ["2024-01-01"]
+  ["2024-01-01"],
 );
 console.log(`Deleted ${deleteResult.rowCount} rows`);
 ```
@@ -82,7 +81,7 @@ const AnalyticsSchema = z.object({
   order_count: z.coerce.number(),
 });
 
-const analytics = await databricks.query(
+const analytics = await ctx.integrations.databricks.query(
   `SELECT
     date,
     SUM(revenue) as total_revenue,
@@ -91,7 +90,7 @@ const analytics = await databricks.query(
   WHERE date >= DATE_SUB(CURRENT_DATE(), 30)
   GROUP BY date
   ORDER BY date DESC`,
-  AnalyticsSchema
+  AnalyticsSchema,
 );
 ```
 
@@ -117,7 +116,10 @@ const schema = z.object({
 
 ```typescript
 // CORRECT - Schema is required
-const data = await databricks.query("SELECT * FROM data", DataSchema);
+const data = await ctx.integrations.databricks.query(
+  "SELECT * FROM data",
+  DataSchema,
+);
 ```
 
 ### NULL Handling
@@ -135,7 +137,10 @@ const schema = z.object({
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const data = await databricks.query("SELECT * FROM data", DataSchema);
+  const data = await ctx.integrations.databricks.query(
+    "SELECT * FROM data",
+    DataSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     console.error("Row index:", error.details.rowIndex);

package/src/integrations/databricks/client.ts

@@ -5,15 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from 'zod';
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as DatabricksPlugin } from '@superblocksteam/types/dist/src/plugins/databricks/v1/plugin_pb';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { QueryValidationError } from '../../errors.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import { describeType } from '../utils.js';
-import type { DatabricksClient } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as DatabricksPlugin } from "@superblocksteam/types/dist/src/plugins/databricks/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { QueryValidationError } from "../../errors.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import { describeType } from "../utils.js";
+import type { DatabricksClient } from "./types.js";
 
 /**
  * Internal implementation of the Databricks client.
@@ -75,7 +75,7 @@ export class DatabricksClientImpl
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from Databricks query, got: ${describeType(result)}`,
         );
       }
@@ -111,27 +111,30 @@ export class DatabricksClientImpl
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'query', error);
+      throw new IntegrationError(this.config.name, "query", error);
     }
   }
 
-  async execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }> {
+  async execute(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rowCount: number }> {
     const request = this.buildRequest(sql, params);
 
     try {
       const result = await this.executeQuery(request);
 
       if (
-        typeof result === 'object' &&
+        typeof result === "object" &&
         result !== null &&
-        'rowCount' in result
+        "rowCount" in result
       ) {
         return { rowCount: Number(result.rowCount) || 0 };
       }
 
       return { rowCount: 0 };
     } catch (error) {
-      throw new IntegrationError(this.config.name, 'execute', error);
+      throw new IntegrationError(this.config.name, "execute", error);
     }
   }
 }

package/src/integrations/databricks/index.ts

@@ -4,5 +4,5 @@
  * @module
  */
 
-export type { DatabricksClient } from './types.js';
-export { DatabricksClientImpl } from './client.js';
+export type { DatabricksClient } from "./types.js";
+export { DatabricksClientImpl } from "./client.js";

package/src/integrations/databricks/types.ts

@@ -4,15 +4,16 @@
  * Provides typed methods for executing Databricks queries with runtime validation.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types.js';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Client for executing Databricks queries with type-safe validation.
  *
  * @example
  * ```typescript
- * const databricks = ctx.databricks('Production Databricks');
+ * // Declare in api(): integrations: { databricks: databricks(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.databricks
  *
  * // Query with validation
  * const DataSchema = z.object({
@@ -40,7 +41,11 @@ export interface DatabricksClient extends BaseIntegrationClient {
    * @throws {QueryValidationError} If results don't match schema
    * @throws {IntegrationError} If query execution fails
    */
-  query<T>(sql: string, schema: z.ZodSchema<T>, params?: unknown[]): Promise<T[]>;
+  query<T>(
+    sql: string,
+    schema: z.ZodSchema<T>,
+    params?: unknown[],
+  ): Promise<T[]>;
 
   /**
    * Execute a SQL statement (INSERT, UPDATE, DELETE) without output validation.

package/src/integrations/datadog/README.md

@@ -4,8 +4,8 @@ Query metrics, manage monitors, and interact with Datadog's monitoring and obser
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Datadog API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Query metrics, manage monitors, and interact with Datadog's monitoring and obser
 ### Query Metrics
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, datadog } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_DATADOG = "a1b2c3d4-5678-90ab-cdef-datadog00001";
@@ -36,6 +36,9 @@ const QueryMetricsResponseSchema = z.object({
 
 export default api({
   name: "DatadogExample",
+  integrations: {
+    datadog: datadog(PROD_DATADOG),
+  },
   input: z.object({
     query: z.string(),
     fromSeconds: z.number(),
@@ -45,14 +48,14 @@ export default api({
     series: z.array(
       z.object({
         metric: z.string(),
-        points: z.array(z.object({ timestamp: z.number(), value: z.number().nullable() })),
-      })
+        points: z.array(
+          z.object({ timestamp: z.number(), value: z.number().nullable() }),
+        ),
+      }),
     ),
   }),
   async run(ctx, { query, fromSeconds, toSeconds }) {
-    const datadog = ctx.datadog(PROD_DATADOG);
-
-    const result = await datadog.apiRequest(
+    const result = await ctx.integrations.datadog.apiRequest(
       {
         method: "GET",
         path: "/api/v1/query",
@@ -62,7 +65,7 @@ export default api({
           to: toSeconds,
         },
       },
-      { response: QueryMetricsResponseSchema }
+      { response: QueryMetricsResponseSchema },
     );
 
     return {
@@ -91,15 +94,19 @@ const MonitorSchema = z.object({
   overall_state: z.string(), // OK, Alert, Warn, No Data
   created: z.string(),
   modified: z.string(),
-  options: z.object({
-    thresholds: z.object({
-      critical: z.number().optional(),
-      warning: z.number().optional(),
-    }).optional(),
-  }).optional(),
+  options: z
+    .object({
+      thresholds: z
+        .object({
+          critical: z.number().optional(),
+          warning: z.number().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
 });
 
-const result = await datadog.apiRequest(
+const result = await ctx.integrations.datadog.apiRequest(
   {
     method: "GET",
     path: "/api/v1/monitor",
@@ -108,7 +115,7 @@ const result = await datadog.apiRequest(
       page_size: 50,
     },
   },
-  { response: z.array(MonitorSchema) }
+  { response: z.array(MonitorSchema) },
 );
 
 result.forEach((monitor) => {
@@ -119,7 +126,7 @@ result.forEach((monitor) => {
 ### Create a Monitor
 
 ```typescript
-const monitor = await datadog.apiRequest(
+const monitor = await ctx.integrations.datadog.apiRequest(
   {
     method: "POST",
     path: "/api/v1/monitor",
@@ -140,7 +147,7 @@ const monitor = await datadog.apiRequest(
       },
     },
   },
-  { response: MonitorSchema }
+  { response: MonitorSchema },
 );
 
 console.log(`Created monitor: ${monitor.id}`);
@@ -157,7 +164,7 @@ const EventResponseSchema = z.object({
   }),
 });
 
-const result = await datadog.apiRequest(
+const result = await ctx.integrations.datadog.apiRequest(
   {
     method: "POST",
     path: "/api/v1/events",
@@ -170,7 +177,7 @@ const result = await datadog.apiRequest(
       source_type_name: "deployment",
     },
   },
-  { response: EventResponseSchema }
+  { response: EventResponseSchema },
 );
 
 console.log(`Event created: ${result.event.url}`);
@@ -187,10 +194,12 @@ const HostSchema = z.object({
   apps: z.array(z.string()),
   tags_by_source: z.record(z.array(z.string())),
   last_reported_time: z.number(),
-  meta: z.object({
-    agent_version: z.string().optional(),
-    platform: z.string().optional(),
-  }).optional(),
+  meta: z
+    .object({
+      agent_version: z.string().optional(),
+      platform: z.string().optional(),
+    })
+    .optional(),
 });
 
 const ListHostsResponseSchema = z.object({
@@ -199,7 +208,7 @@ const ListHostsResponseSchema = z.object({
   total_returned: z.number(),
 });
 
-const result = await datadog.apiRequest(
+const result = await ctx.integrations.datadog.apiRequest(
   {
     method: "GET",
     path: "/api/v1/hosts",
@@ -210,7 +219,7 @@ const result = await datadog.apiRequest(
       count: 100,
     },
   },
-  { response: ListHostsResponseSchema }
+  { response: ListHostsResponseSchema },
 );
 
 result.host_list.forEach((host) => {
@@ -227,7 +236,7 @@ const SubmitMetricsResponseSchema = z.object({
 
 const now = Math.floor(Date.now() / 1000);
 
-const result = await datadog.apiRequest(
+const result = await ctx.integrations.datadog.apiRequest(
   {
     method: "POST",
     path: "/api/v2/series",
@@ -247,7 +256,7 @@ const result = await datadog.apiRequest(
       ],
     },
   },
-  { response: SubmitMetricsResponseSchema }
+  { response: SubmitMetricsResponseSchema },
 );
 ```
 
@@ -267,14 +276,18 @@ const LogSchema = z.object({
 
 const SearchLogsResponseSchema = z.object({
   data: z.array(LogSchema),
-  meta: z.object({
-    page: z.object({
-      after: z.string().optional(),
-    }).optional(),
-  }).optional(),
+  meta: z
+    .object({
+      page: z
+        .object({
+          after: z.string().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
 });
 
-const result = await datadog.apiRequest(
+const result = await ctx.integrations.datadog.apiRequest(
   {
     method: "POST",
     path: "/api/v2/logs/events/search",
@@ -290,7 +303,7 @@ const result = await datadog.apiRequest(
       },
     },
   },
-  { response: SearchLogsResponseSchema }
+  { response: SearchLogsResponseSchema },
 );
 
 result.data.forEach((log) => {
@@ -308,7 +321,7 @@ await datadog.queryMetrics({ ... });
 await datadog.createMonitor({ ... });
 
 // CORRECT - Use apiRequest
-await datadog.apiRequest(
+await ctx.integrations.datadog.apiRequest(
   { method: "GET", path: "/api/v1/query", params: { ... } },
   { response: QueryMetricsResponseSchema }
 );
@@ -450,7 +463,7 @@ Different Datadog sites have different base URLs:
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await datadog.apiRequest(
+  const result = await ctx.integrations.datadog.apiRequest(
     { method: "GET", path: "/api/v1/query", params: { ... } },
     { response: QueryMetricsResponseSchema }
   );

package/src/integrations/datadog/client.ts

@@ -5,8 +5,8 @@
  * Datadog integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { DatadogClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { DatadogClient } from "./types.js";
 
 /**
  * Internal implementation of DatadogClient.
@@ -16,6 +16,8 @@ import type { DatadogClient } from './types.js';
  * Datadog API calls. At runtime, the orchestrator handles authentication
  * and API request execution.
  */
-export class DatadogClientImpl extends RestApiIntegrationClient implements DatadogClient {
+export class DatadogClientImpl
+  extends RestApiIntegrationClient
+  implements DatadogClient {
   // Inherits: name, pluginId, config, executeQuery, apiRequest()
 }

package/src/integrations/datadog/index.ts

@@ -1,2 +1,2 @@
-export { DatadogClientImpl } from './client.js';
-export type { DatadogClient } from './types.js';
+export { DatadogClientImpl } from "./client.js";
+export type { DatadogClient } from "./types.js";

package/src/integrations/datadog/types.ts

@@ -2,8 +2,8 @@
  * Datadog client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { SupportsApiRequest } from '../base/index.js';
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * Datadog client for API interactions.
@@ -13,7 +13,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const datadog = ctx.datadog('My Datadog');
+ * // Declare in api(): integrations: { datadog: datadog(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.datadog
  *
  * // Make API requests
  * const ResponseSchema = z.object({
@@ -29,6 +30,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  * );
  * ```
  */
-export interface DatadogClient extends BaseIntegrationClient, SupportsApiRequest {
+export interface DatadogClient
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
 }