@superblocksteam/sdk-api 2.0.93 → 2.0.94-next.1

package/src/integrations/slack/README.md

@@ -4,8 +4,8 @@ Send messages, manage channels, and interact with Slack workspaces.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                       |
+| ----------------------------- | ------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Slack API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Send messages, manage channels, and interact with Slack workspaces.
 ### Post a Message
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, slack } from "@superblocksteam/sdk-api";
 
 const PostMessageResponseSchema = z.object({
   ok: z.boolean(),
@@ -32,6 +32,9 @@ const OPS_SLACK = "a1b2c3d4-5678-90ab-cdef-222222222222";
 
 export default api({
   name: "SlackExample",
+  integrations: {
+    slack: slack(OPS_SLACK),
+  },
   input: z.object({
     channel: z.string(),
     message: z.string(),
@@ -40,9 +43,7 @@ export default api({
     messageId: z.string(),
   }),
   async run(ctx, { channel, message }) {
-    const slack = ctx.slack(OPS_SLACK);
-
-    const result = await slack.apiRequest(
+    const result = await ctx.integrations.slack.apiRequest(
       {
         method: "POST",
         path: "/chat.postMessage",
@@ -51,7 +52,7 @@ export default api({
           text: message,
         },
       },
-      { response: PostMessageResponseSchema }
+      { response: PostMessageResponseSchema },
     );
 
     return { messageId: result.ts };
@@ -62,7 +63,7 @@ export default api({
 ### Post with Block Kit
 
 ```typescript
-const result = await slack.apiRequest(
+const result = await ctx.integrations.slack.apiRequest(
   {
     method: "POST",
     path: "/chat.postMessage",
@@ -97,7 +98,7 @@ const result = await slack.apiRequest(
       ],
     },
   },
-  { response: PostMessageResponseSchema }
+  { response: PostMessageResponseSchema },
 );
 ```
 
@@ -113,7 +114,7 @@ const ListChannelsResponseSchema = z.object({
       is_private: z.boolean(),
       is_archived: z.boolean(),
       num_members: z.number().optional(),
-    })
+    }),
   ),
   response_metadata: z
     .object({
@@ -122,7 +123,7 @@ const ListChannelsResponseSchema = z.object({
     .optional(),
 });
 
-const result = await slack.apiRequest(
+const result = await ctx.integrations.slack.apiRequest(
   {
     method: "GET",
     path: "/conversations.list",
@@ -131,7 +132,7 @@ const result = await slack.apiRequest(
       limit: 100,
     },
   },
-  { response: ListChannelsResponseSchema }
+  { response: ListChannelsResponseSchema },
 );
 
 result.channels.forEach((channel) => {
@@ -157,13 +158,13 @@ const UserInfoResponseSchema = z.object({
   }),
 });
 
-const result = await slack.apiRequest(
+const result = await ctx.integrations.slack.apiRequest(
   {
     method: "GET",
     path: "/users.info",
     params: { user: "U123456789" },
   },
-  { response: UserInfoResponseSchema }
+  { response: UserInfoResponseSchema },
 );
 
 console.log(`User: ${result.user.real_name} (${result.user.profile.email})`);
@@ -182,7 +183,7 @@ const FileUploadResponseSchema = z.object({
   }),
 });
 
-const result = await slack.apiRequest(
+const result = await ctx.integrations.slack.apiRequest(
   {
     method: "POST",
     path: "/files.upload",
@@ -193,7 +194,7 @@ const result = await slack.apiRequest(
       title: "Daily Report",
     },
   },
-  { response: FileUploadResponseSchema }
+  { response: FileUploadResponseSchema },
 );
 
 console.log(`File uploaded: ${result.file.permalink}`);
@@ -202,7 +203,7 @@ console.log(`File uploaded: ${result.file.permalink}`);
 ### Reply to a Thread
 
 ```typescript
-const result = await slack.apiRequest(
+const result = await ctx.integrations.slack.apiRequest(
   {
     method: "POST",
     path: "/chat.postMessage",
@@ -212,7 +213,7 @@ const result = await slack.apiRequest(
       thread_ts: "1234567890.123456", // Parent message timestamp
     },
   },
-  { response: PostMessageResponseSchema }
+  { response: PostMessageResponseSchema },
 );
 ```
 
@@ -226,7 +227,7 @@ const UpdateMessageResponseSchema = z.object({
   text: z.string(),
 });
 
-const result = await slack.apiRequest(
+const result = await ctx.integrations.slack.apiRequest(
   {
     method: "POST",
     path: "/chat.update",
@@ -236,7 +237,7 @@ const result = await slack.apiRequest(
       text: "Updated message text",
     },
   },
-  { response: UpdateMessageResponseSchema }
+  { response: UpdateMessageResponseSchema },
 );
 ```
 
@@ -250,7 +251,7 @@ await slack.postMessage({ ... });
 await slack.listChannels();
 
 // CORRECT - Use apiRequest
-await slack.apiRequest(
+await ctx.integrations.slack.apiRequest(
   { method: "POST", path: "/chat.postMessage", body: { ... } },
   { response: PostMessageResponseSchema }
 );
@@ -280,7 +281,7 @@ Most API methods require channel ID, not name:
 
 ```typescript
 // WRONG - Using channel name
-await slack.apiRequest(
+await ctx.integrations.slack.apiRequest(
   {
     method: "POST",
     path: "/chat.postMessage",
@@ -289,11 +290,11 @@ await slack.apiRequest(
       text: "Hello",
     },
   },
-  { response: schema }
+  { response: schema },
 );
 
 // CORRECT - Using channel ID
-await slack.apiRequest(
+await ctx.integrations.slack.apiRequest(
   {
     method: "POST",
     path: "/chat.postMessage",
@@ -302,7 +303,7 @@ await slack.apiRequest(
       text: "Hello",
     },
   },
-  { response: schema }
+  { response: schema },
 );
 ```
 
@@ -316,7 +317,7 @@ async function getAllChannels(slack: SlackClient) {
   let cursor: string | undefined;
 
   do {
-    const result = await slack.apiRequest(
+    const result = await ctx.integrations.slack.apiRequest(
       {
         method: "GET",
         path: "/conversations.list",
@@ -325,7 +326,7 @@ async function getAllChannels(slack: SlackClient) {
           ...(cursor && { cursor }),
         },
       },
-      { response: ListChannelsResponseSchema }
+      { response: ListChannelsResponseSchema },
     );
 
     allChannels.push(...result.channels);
@@ -370,7 +371,7 @@ Code block
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await slack.apiRequest(
+  const result = await ctx.integrations.slack.apiRequest(
     { method: "POST", path: "/chat.postMessage", body: { ... } },
     { response: PostMessageResponseSchema }
   );

package/src/integrations/slack/client.ts

@@ -16,6 +16,8 @@ import type { SlackClient } from "./types.js";
  * Slack API calls. At runtime, the orchestrator handles OAuth authentication
  * and API request execution.
  */
-export class SlackClientImpl extends RestApiIntegrationClient implements SlackClient {
+export class SlackClientImpl
+  extends RestApiIntegrationClient
+  implements SlackClient {
   // Inherits: name, pluginId, config, executeQuery, apiRequest()
 }

package/src/integrations/slack/index.ts

@@ -2,5 +2,5 @@
  * Slack integration module.
  */
 
-export type { SlackClient } from './types.js';
-export { SlackClientImpl } from './client.js';
+export type { SlackClient } from "./types.js";
+export { SlackClientImpl } from "./client.js";

package/src/integrations/slack/types.ts

@@ -2,8 +2,8 @@
  * Slack 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";
 
 /**
  * Slack client for API interactions.
@@ -13,15 +13,9 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const slack = ctx.slack('Ops Slack');
- *
- * // Post a message
- * const PostMessageResponseSchema = z.object({
- *   ts: z.string(),
- *   channel: z.string(),
- * });
- *
- * await slack.apiRequest(
+ * // Declare in api(): integrations: { slack: slack(INTEGRATION_ID) }
+ * // In run(), access via: ctx.integrations.slack
+ * await ctx.integrations.slack.apiRequest(
  *   {
  *     method: 'POST',
  *     path: '/chat.postMessage',
@@ -41,7 +35,7 @@ import type { SupportsApiRequest } from '../base/index.js';
  *   })),
  * });
  *
- * const result = await slack.apiRequest(
+ * const result = await ctx.integrations.slack.apiRequest(
  *   {
  *     method: 'GET',
  *     path: '/conversations.list',

package/src/integrations/smtp/client.ts

@@ -5,12 +5,12 @@
  * Sends emails with support for CC, BCC, reply-to, and attachments.
  */
 
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as SmtpPlugin } from '@superblocksteam/types/dist/src/plugins/smtp/v1/plugin_pb';
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { IntegrationError } from '../../runtime/errors.js';
-import type { SmtpClient, SmtpSendOptions } from './types.js';
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as SmtpPlugin } from "@superblocksteam/types/dist/src/plugins/smtp/v1/plugin_pb";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { IntegrationError } from "../../runtime/errors.js";
+import type { SmtpClient, SmtpSendOptions } from "./types.js";
 
 /**
  * SMTP request type derived from proto definition.
@@ -46,10 +46,10 @@ export class SmtpClientImpl implements SmtpClient, IntegrationClientImpl {
       to: options.to,
       subject: options.subject,
       body: options.body,
-      cc: options.cc ?? '',
-      bcc: options.bcc ?? '',
-      replyTo: options.replyTo ?? '',
-      attachments: options.attachments ?? '',
+      cc: options.cc ?? "",
+      bcc: options.bcc ?? "",
+      replyTo: options.replyTo ?? "",
+      attachments: options.attachments ?? "",
     };
 
     try {
@@ -59,7 +59,7 @@ export class SmtpClientImpl implements SmtpClient, IntegrationClientImpl {
         throw error;
       }
 
-      throw new IntegrationError(this.config.name, 'send', error);
+      throw new IntegrationError(this.config.name, "send", error);
     }
   }
 }

package/src/integrations/smtp/index.ts

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

package/src/integrations/smtp/types.ts

@@ -4,7 +4,7 @@
  * Provides a typed interface for sending emails via SMTP.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
+import type { BaseIntegrationClient } from "../../types.js";
 
 /**
  * Options for sending an email via SMTP.

package/src/integrations/snowflake/README.md

@@ -4,17 +4,17 @@ Execute SQL queries and statements against Snowflake data warehouses with full t
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
-| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results |
-| `execute(sql, params?)` | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
+| Method                           | Description                                                                |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `query<T>(sql, schema, params?)` | Execute a SELECT query and return validated, typed results                 |
+| `execute(sql, params?)`          | Execute a statement (INSERT, UPDATE, DELETE) and return affected row count |
 
 ## Usage
 
 ### Basic Query with Schema Validation
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, snowflake } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_SNOWFLAKE = "a1b2c3d4-5678-90ab-cdef-snowflak0001";
@@ -28,6 +28,9 @@ const UserSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    snowflake: snowflake(PROD_SNOWFLAKE),
+  },
   name: "SnowflakeExample",
   input: z.object({
     status: z.string(),
@@ -36,12 +39,10 @@ export default api({
     users: z.array(UserSchema),
   }),
   async run(ctx, { status }) {
-    const snowflake = ctx.snowflake(PROD_SNOWFLAKE);
-
-    const users = await snowflake.query(
+    const users = await ctx.integrations.snowflake.query(
       "SELECT ID, NAME, EMAIL, CREATED_AT FROM USERS WHERE STATUS = $1",
       UserSchema,
-      [status]
+      [status],
     );
 
     return { users };
@@ -59,7 +60,7 @@ const UserSchema = z.object({
   email: z.string().email(),
 });
 
-const users = await snowflake.query(
+const users = await ctx.integrations.snowflake.query(
   `SELECT
     ID as "id",
     NAME as "name",
@@ -67,31 +68,29 @@ const users = await snowflake.query(
   FROM USERS
   WHERE STATUS = $1`,
   UserSchema,
-  ["active"]
+  ["active"],
 );
 ```
 
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
-const snowflake = ctx.snowflake(PROD_SNOWFLAKE);
-
 // INSERT
-await snowflake.execute(
+await ctx.integrations.snowflake.execute(
   "INSERT INTO USERS (NAME, EMAIL) VALUES ($1, $2)",
-  ["John Doe", "john@example.com"]
+  ["John Doe", "john@example.com"],
 );
 
 // UPDATE
-const updateResult = await snowflake.execute(
+const updateResult = await ctx.integrations.snowflake.execute(
   "UPDATE USERS SET LAST_LOGIN = CURRENT_TIMESTAMP() WHERE ID = $1",
-  [userId]
+  [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
-const deleteResult = await snowflake.execute(
-  "DELETE FROM SESSIONS WHERE EXPIRES_AT < CURRENT_TIMESTAMP()"
+const deleteResult = await ctx.integrations.snowflake.execute(
+  "DELETE FROM SESSIONS WHERE EXPIRES_AT < CURRENT_TIMESTAMP()",
 );
 console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
 ```
@@ -105,7 +104,7 @@ const AnalyticsSchema = z.object({
   AVG_ORDER_VALUE: z.string(),
 });
 
-const analytics = await snowflake.query(
+const analytics = await ctx.integrations.snowflake.query(
   `SELECT
     DATE_TRUNC('day', ORDER_DATE) as DATE,
     SUM(TOTAL) as TOTAL_SALES,
@@ -114,7 +113,7 @@ const analytics = await snowflake.query(
   WHERE ORDER_DATE >= DATEADD('day', -30, CURRENT_DATE())
   GROUP BY DATE_TRUNC('day', ORDER_DATE)
   ORDER BY DATE DESC`,
-  AnalyticsSchema
+  AnalyticsSchema,
 );
 ```
 
@@ -132,7 +131,7 @@ const EventSchema = z.object({
   }),
 });
 
-const events = await snowflake.query(
+const events = await ctx.integrations.snowflake.query(
   `SELECT
     EVENT_ID,
     EVENT_TYPE,
@@ -140,7 +139,7 @@ const events = await snowflake.query(
   FROM EVENTS
   WHERE EVENT_TYPE = $1`,
   EventSchema,
-  ["user_action"]
+  ["user_action"],
 );
 ```
 
@@ -182,7 +181,7 @@ Aggregate functions like `COUNT(*)` return columns with uppercase names. The col
 
 // WRONG - Snowflake returns 'COUNT' (uppercase), not 'count'
 const schema = z.object({
-  count: z.coerce.number(),  // Fails validation - column doesn't exist
+  count: z.coerce.number(), // Fails validation - column doesn't exist
 });
 
 // CORRECT - Use uppercase column name
@@ -203,7 +202,7 @@ const StatsSchema = z.object({
   AVG_ORDER_VALUE: z.coerce.number(),
 });
 
-const stats = await snowflake.query(
+const stats = await ctx.integrations.snowflake.query(
   `SELECT
     COUNT(*) as TOTAL_ORDERS,
     SUM(AMOUNT) as TOTAL_REVENUE,
@@ -211,7 +210,7 @@ const stats = await snowflake.query(
   FROM ORDERS
   WHERE CREATED_AT > $1`,
   StatsSchema,
-  [startDate]
+  [startDate],
 );
 ```
 
@@ -240,16 +239,15 @@ Like PostgreSQL, the `query()` method requires a Zod schema:
 
 ```typescript
 // WRONG - Missing schema
-const users = await snowflake.query(
-  "SELECT * FROM USERS",
-  [/* params */]
-);
+const users = await ctx.integrations.snowflake.query("SELECT * FROM USERS", [
+  /* params */
+]);
 
 // CORRECT - Schema is required as second parameter
-const users = await snowflake.query(
+const users = await ctx.integrations.snowflake.query(
   "SELECT * FROM USERS WHERE ID = $1",
   UserSchema,
-  [userId]
+  [userId],
 );
 ```
 
@@ -308,7 +306,7 @@ When querying VARIANT, ARRAY, or OBJECT columns:
 ```typescript
 // For VARIANT column containing JSON
 const schema = z.object({
-  DATA: z.unknown(),  // Accept any JSON structure
+  DATA: z.unknown(), // Accept any JSON structure
 });
 
 // Or with specific structure
@@ -320,12 +318,12 @@ const schema = z.object({
 });
 
 // Use Snowflake's JSON functions in query
-const result = await snowflake.query(
+const result = await ctx.integrations.snowflake.query(
   `SELECT
     DATA:key::STRING as KEY,
     DATA:value::NUMBER as VALUE
   FROM MY_TABLE`,
-  z.object({ KEY: z.string(), VALUE: z.string() })
+  z.object({ KEY: z.string(), VALUE: z.string() }),
 );
 ```
 
@@ -339,9 +337,9 @@ Thrown when query results fail schema validation:
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const users = await snowflake.query(
+  const users = await ctx.integrations.snowflake.query(
     "SELECT * FROM USERS",
-    UserSchema
+    UserSchema,
   );
 } catch (error) {
   if (error instanceof QueryValidationError) {

package/src/integrations/snowflake/client.ts

@@ -19,7 +19,8 @@ import type { SnowflakeClient } from "./types.js";
  * Internal implementation of the Snowflake client.
  */
 export class SnowflakeClientImpl
-  implements SnowflakeClient, IntegrationClientImpl {
+  implements SnowflakeClient, IntegrationClientImpl
+{
   readonly config: IntegrationConfig;
   private readonly executeQuery: QueryExecutor;
 

package/src/integrations/snowflake/index.ts

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

package/src/integrations/snowflake/types.ts

@@ -4,15 +4,16 @@
  * Provides typed methods for executing Snowflake queries with runtime validation.
  */
 
-import type { z } from 'zod';
-import type { BaseIntegrationClient } from '../../types';
+import type { z } from "zod";
+import type { BaseIntegrationClient } from "../../types";
 
 /**
  * Client for executing Snowflake queries with type-safe validation.
  *
  * @example
  * ```typescript
- * const snowflake = ctx.snowflake('Production Snowflake');
+ * // Declare in api(): integrations: { snowflake: snowflake(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.snowflake
  *
  * // Query with validation
  * const UserSchema = z.object({
@@ -55,7 +56,11 @@ export interface SnowflakeClient extends BaseIntegrationClient {
    * );
    * ```
    */
-  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/snowflakecortex/client.ts

@@ -5,8 +5,8 @@
  * Snowflake Cortex integrations use the REST API Integration plugin under the hood.
  */
 
-import { RestApiIntegrationClient } from '../base/index.js';
-import type { SnowflakeCortexClient } from './types.js';
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { SnowflakeCortexClient } from "./types.js";
 
 /**
  * Internal implementation of SnowflakeCortexClient.
@@ -14,7 +14,9 @@ import type { SnowflakeCortexClient } from './types.js';
  * Extends RestApiIntegrationClient to inherit generic apiRequest() and
  * streamApiRequest() methods.
  */
-export class SnowflakeCortexClientImpl extends RestApiIntegrationClient implements SnowflakeCortexClient {
+export class SnowflakeCortexClientImpl
+  extends RestApiIntegrationClient
+  implements SnowflakeCortexClient {
   // Inherits: name, pluginId, config, executeQuery, createParam(), apiRequest(), streamApiRequest()
   // Can add Snowflake Cortex-specific methods here in the future if needed
 }

package/src/integrations/snowflakecortex/index.ts

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

package/src/integrations/snowflakecortex/types.ts

@@ -2,8 +2,11 @@
  * Snowflake Cortex client types.
  */
 
-import type { BaseIntegrationClient } from '../../types.js';
-import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/index.js';
+import type { BaseIntegrationClient } from "../../types.js";
+import type {
+  SupportsApiRequest,
+  SupportsStreamingApiRequest,
+} from "../base/index.js";
 
 /**
  * Snowflake Cortex client for inference interactions.
@@ -12,7 +15,10 @@ import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/in
  * and streamApiRequest() for streaming responses.
  */
 export interface SnowflakeCortexClient
-  extends BaseIntegrationClient, SupportsApiRequest, SupportsStreamingApiRequest {
+  extends
+    BaseIntegrationClient,
+    SupportsApiRequest,
+    SupportsStreamingApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
   // streamApiRequest() method inherited from SupportsStreamingApiRequest
 }

package/src/integrations/snowflakepostgres/client.ts

@@ -6,8 +6,8 @@
  * implementation.
  */
 
-import type { SnowflakePostgresClient } from './types.js';
-import { PostgresClientImpl } from '../postgres/client.js';
+import type { SnowflakePostgresClient } from "./types.js";
+import { PostgresClientImpl } from "../postgres/client.js";
 
 export class SnowflakePostgresClientImpl
   extends PostgresClientImpl