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

package/src/integrations/anthropic/types.ts

@@ -2,8 +2,11 @@
  * Anthropic 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";
 
 /**
  * Anthropic client for Claude AI model interactions.
@@ -16,7 +19,8 @@ import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/in
  * ```typescript
  * import { z } from 'zod';
  *
- * const anthropic = ctx.integration('Production Anthropic');
+ * // Declare in api(): integrations: { ai: anthropic(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.ai
  *
  * // Define request and response schemas
  * const CreateMessageRequestSchema = z.object({
@@ -38,7 +42,7 @@ import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/in
  * });
  *
  * // Create a message
- * const message = await anthropic.apiRequest(
+ * const message = await ctx.integrations.ai.apiRequest(
  *   {
  *     method: 'POST',
  *     path: '/v1/messages',
@@ -75,7 +79,10 @@ import type { SupportsApiRequest, SupportsStreamingApiRequest } from '../base/in
  * ```
  */
 export interface AnthropicClient
-  extends BaseIntegrationClient, SupportsApiRequest, SupportsStreamingApiRequest {
+  extends
+    BaseIntegrationClient,
+    SupportsApiRequest,
+    SupportsStreamingApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
   // streamApiRequest() method inherited from SupportsStreamingApiRequest
 }

package/src/integrations/asana/README.md

@@ -4,8 +4,8 @@ Create tasks, manage projects, and track work in Asana.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                       |
+| ----------------------------- | ------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Asana API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Create tasks, manage projects, and track work in Asana.
 ### Create a Task
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, asana } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_ASANA = "a1b2c3d4-5678-90ab-cdef-asana0000001";
@@ -34,6 +34,9 @@ const CreateTaskResponseSchema = z.object({
 
 export default api({
   name: "AsanaExample",
+  integrations: {
+    asana: asana(PROD_ASANA),
+  },
   input: z.object({
     projectId: z.string(),
     name: z.string(),
@@ -43,9 +46,7 @@ export default api({
     taskId: z.string(),
   }),
   async run(ctx, { projectId, name, description }) {
-    const asana = ctx.asana(PROD_ASANA);
-
-    const result = await asana.apiRequest(
+    const result = await ctx.integrations.asana.apiRequest(
       {
         method: "POST",
         path: "/api/1.0/tasks",
@@ -57,7 +58,7 @@ export default api({
           },
         },
       },
-      { response: CreateTaskResponseSchema }
+      { response: CreateTaskResponseSchema },
     );
 
     return { taskId: result.data.gid };
@@ -74,7 +75,7 @@ const ListTasksResponseSchema = z.object({
       gid: z.string(),
       name: z.string(),
       completed: z.boolean(),
-    })
+    }),
   ),
   next_page: z
     .object({
@@ -84,7 +85,7 @@ const ListTasksResponseSchema = z.object({
     .nullable(),
 });
 
-const result = await asana.apiRequest(
+const result = await ctx.integrations.asana.apiRequest(
   {
     method: "GET",
     path: `/api/1.0/projects/${projectId}/tasks`,
@@ -93,7 +94,7 @@ const result = await asana.apiRequest(
       completed_since: "now", // Only incomplete tasks
     },
   },
-  { response: ListTasksResponseSchema }
+  { response: ListTasksResponseSchema },
 );
 
 result.data.forEach((task) => {
@@ -104,7 +105,7 @@ result.data.forEach((task) => {
 ### Update a Task
 
 ```typescript
-const result = await asana.apiRequest(
+const result = await ctx.integrations.asana.apiRequest(
   {
     method: "PUT",
     path: `/api/1.0/tasks/${taskId}`,
@@ -115,14 +116,14 @@ const result = await asana.apiRequest(
       },
     },
   },
-  { response: z.object({ data: TaskSchema }) }
+  { response: z.object({ data: TaskSchema }) },
 );
 ```
 
 ### Assign a Task
 
 ```typescript
-const result = await asana.apiRequest(
+const result = await ctx.integrations.asana.apiRequest(
   {
     method: "PUT",
     path: `/api/1.0/tasks/${taskId}`,
@@ -133,7 +134,7 @@ const result = await asana.apiRequest(
       },
     },
   },
-  { response: z.object({ data: TaskSchema }) }
+  { response: z.object({ data: TaskSchema }) },
 );
 ```
 
@@ -146,11 +147,11 @@ const ListProjectsResponseSchema = z.object({
       gid: z.string(),
       name: z.string(),
       archived: z.boolean(),
-    })
+    }),
   ),
 });
 
-const result = await asana.apiRequest(
+const result = await ctx.integrations.asana.apiRequest(
   {
     method: "GET",
     path: "/api/1.0/projects",
@@ -160,7 +161,7 @@ const result = await asana.apiRequest(
       archived: false,
     },
   },
-  { response: ListProjectsResponseSchema }
+  { response: ListProjectsResponseSchema },
 );
 ```
 
@@ -174,7 +175,7 @@ const CreateProjectResponseSchema = z.object({
   }),
 });
 
-const result = await asana.apiRequest(
+const result = await ctx.integrations.asana.apiRequest(
   {
     method: "POST",
     path: "/api/1.0/projects",
@@ -188,7 +189,7 @@ const result = await asana.apiRequest(
       },
     },
   },
-  { response: CreateProjectResponseSchema }
+  { response: CreateProjectResponseSchema },
 );
 ```
 
@@ -203,7 +204,7 @@ const StoryResponseSchema = z.object({
   }),
 });
 
-const result = await asana.apiRequest(
+const result = await ctx.integrations.asana.apiRequest(
   {
     method: "POST",
     path: `/api/1.0/tasks/${taskId}/stories`,
@@ -213,7 +214,7 @@ const result = await asana.apiRequest(
       },
     },
   },
-  { response: StoryResponseSchema }
+  { response: StoryResponseSchema },
 );
 ```
 
@@ -225,30 +226,30 @@ const SearchResponseSchema = z.object({
     z.object({
       gid: z.string(),
       name: z.string(),
-    })
+    }),
   ),
 });
 
-const result = await asana.apiRequest(
+const result = await ctx.integrations.asana.apiRequest(
   {
     method: "GET",
     path: "/api/1.0/workspaces/{workspace_gid}/tasks/search",
     params: {
       "text.value": "urgent",
-      "completed": false,
+      completed: false,
       "assignee.any": userId,
-      "sort_by": "due_date",
-      "sort_ascending": true,
+      sort_by: "due_date",
+      sort_ascending: true,
     },
   },
-  { response: SearchResponseSchema }
+  { response: SearchResponseSchema },
 );
 ```
 
 ### Get Subtasks
 
 ```typescript
-const result = await asana.apiRequest(
+const result = await ctx.integrations.asana.apiRequest(
   {
     method: "GET",
     path: `/api/1.0/tasks/${taskId}/subtasks`,
@@ -256,7 +257,7 @@ const result = await asana.apiRequest(
       opt_fields: "name,completed,assignee.name",
     },
   },
-  { response: ListTasksResponseSchema }
+  { response: ListTasksResponseSchema },
 );
 ```
 
@@ -270,7 +271,7 @@ await asana.createTask({ ... });
 await asana.getTasks({ ... });
 
 // CORRECT - Use apiRequest
-await asana.apiRequest(
+await ctx.integrations.asana.apiRequest(
   { method: "POST", path: "/api/1.0/tasks", body: { data: { ... } } },
   { response: CreateTaskResponseSchema }
 );
@@ -283,7 +284,8 @@ Asana wraps request bodies and responses in a `data` object:
 ```typescript
 // Request body
 const body = {
-  data: {  // Wrapped in data
+  data: {
+    // Wrapped in data
     name: "Task name",
     notes: "Description",
   },
@@ -291,7 +293,7 @@ const body = {
 
 // Response
 const schema = z.object({
-  data: TaskSchema,  // Wrapped in data
+  data: TaskSchema, // Wrapped in data
 });
 ```
 
@@ -355,8 +357,8 @@ Asana uses ISO date format (YYYY-MM-DD):
 ```typescript
 const body = {
   data: {
-    due_on: "2024-12-31",         // Date only
-    due_at: "2024-12-31T17:00:00.000Z",  // Date and time
+    due_on: "2024-12-31", // Date only
+    due_at: "2024-12-31T17:00:00.000Z", // Date and time
     start_on: "2024-12-01",
   },
 };
@@ -372,7 +374,7 @@ async function getAllTasks(asana: AsanaClient, projectId: string) {
   let offset: string | undefined;
 
   do {
-    const result = await asana.apiRequest(
+    const result = await ctx.integrations.asana.apiRequest(
       {
         method: "GET",
         path: `/api/1.0/projects/${projectId}/tasks`,
@@ -381,7 +383,7 @@ async function getAllTasks(asana: AsanaClient, projectId: string) {
           ...(offset && { offset }),
         },
       },
-      { response: ListTasksResponseSchema }
+      { response: ListTasksResponseSchema },
     );
 
     allTasks.push(...result.data);
@@ -398,7 +400,7 @@ async function getAllTasks(asana: AsanaClient, projectId: string) {
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await asana.apiRequest(
+  const result = await ctx.integrations.asana.apiRequest(
     { method: "POST", path: "/api/1.0/tasks", body: { data: { ... } } },
     { response: CreateTaskResponseSchema }
   );

package/src/integrations/asana/client.ts

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

package/src/integrations/asana/index.ts

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

package/src/integrations/asana/types.ts

@@ -2,8 +2,8 @@
  * Asana 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";
 
 /**
  * Asana client for API interactions.
@@ -13,7 +13,8 @@ import type { SupportsApiRequest } from '../base/index.js';
  *
  * @example
  * ```typescript
- * const asana = ctx.asana('My Asana');
+ * // Declare in api(): integrations: { asana: asana(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.asana
  *
  * // Make API requests
  * const ResponseSchema = z.object({

package/src/integrations/athena/README.md

@@ -4,17 +4,17 @@ Execute SQL queries against Amazon Athena with full type safety and runtime vali
 
 ## 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, athena } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_ATHENA = "a1b2c3d4-5678-90ab-cdef-athena000001";
@@ -28,6 +28,9 @@ const LogSchema = z.object({
 
 export default api({
   name: "AthenaExample",
+  integrations: {
+    athena: athena(PROD_ATHENA),
+  },
   input: z.object({
     level: z.string(),
   }),
@@ -35,15 +38,13 @@ export default api({
     logs: z.array(LogSchema),
   }),
   async run(ctx, { level }) {
-    const athena = ctx.athena(PROD_ATHENA);
-
-    const logs = await athena.query(
+    const logs = await ctx.integrations.athena.query(
       `SELECT timestamp, level, message, request_id
        FROM logs
        WHERE level = $1
        LIMIT 100`,
       LogSchema,
-      [level]
+      [level],
     );
 
     return { logs };
@@ -61,13 +62,13 @@ const EventSchema = z.object({
   created_at: z.string(),
 });
 
-const events = await athena.query(
+const events = await ctx.integrations.athena.query(
   `SELECT event_id, event_type, user_id, created_at
    FROM events
    WHERE date_partition = $1
      AND event_type = $2`,
   EventSchema,
-  ["2024-01-15", "purchase"]
+  ["2024-01-15", "purchase"],
 );
 ```
 
@@ -80,7 +81,7 @@ const StatsSchema = z.object({
   unique_users: z.coerce.number(),
 });
 
-const stats = await athena.query(
+const stats = await ctx.integrations.athena.query(
   `SELECT
     DATE(created_at) as date,
     COUNT(*) as total_events,
@@ -89,7 +90,7 @@ const stats = await athena.query(
   WHERE created_at >= DATE_ADD('day', -7, CURRENT_DATE)
   GROUP BY DATE(created_at)
   ORDER BY date DESC`,
-  StatsSchema
+  StatsSchema,
 );
 ```
 
@@ -111,7 +112,10 @@ const schema = z.object({
 
 ```typescript
 // CORRECT - Schema is required
-const logs = await athena.query("SELECT * FROM logs", LogSchema);
+const logs = await ctx.integrations.athena.query(
+  "SELECT * FROM logs",
+  LogSchema,
+);
 ```
 
 ### NULL Handling
@@ -129,10 +133,10 @@ Always use partition filters when possible to reduce data scanned:
 
 ```typescript
 // GOOD - Uses partition filter
-const logs = await athena.query(
+const logs = await ctx.integrations.athena.query(
   "SELECT * FROM logs WHERE date_partition = $1",
   LogSchema,
-  ["2024-01-15"]
+  ["2024-01-15"],
 );
 ```
 
@@ -142,7 +146,10 @@ const logs = await athena.query(
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const logs = await athena.query("SELECT * FROM logs", LogSchema);
+  const logs = await ctx.integrations.athena.query(
+    "SELECT * FROM logs",
+    LogSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     console.error("Row index:", error.details.rowIndex);

package/src/integrations/athena/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 AthenaPlugin } from '@superblocksteam/types/dist/src/plugins/athena/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 { AthenaClient } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as AthenaPlugin } from "@superblocksteam/types/dist/src/plugins/athena/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 { AthenaClient } from "./types.js";
 
 /**
  * Internal implementation of the Athena client.
@@ -73,7 +73,7 @@ export class AthenaClientImpl implements AthenaClient, IntegrationClientImpl {
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from Athena query, got: ${describeType(result)}`,
         );
       }
@@ -109,27 +109,30 @@ export class AthenaClientImpl implements AthenaClient, IntegrationClientImpl {
         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/athena/index.ts

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

package/src/integrations/athena/types.ts

@@ -4,15 +4,16 @@
  * Provides typed methods for executing Athena 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 Athena queries with type-safe validation.
  *
  * @example
  * ```typescript
- * const athena = ctx.athena('Production Athena');
+ * // Declare in api(): integrations: { athena: athena(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.athena
  *
  * // Query with validation
  * const LogSchema = z.object({
@@ -40,7 +41,11 @@ export interface AthenaClient 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/base/graphql-integration-client.ts

@@ -5,10 +5,10 @@
  * Handles proto message construction and response validation.
  */
 
-import type { IntegrationConfig, IntegrationClientImpl } from '../types.js';
-import type { QueryExecutor } from '../registry.js';
-import { z } from 'zod';
-import { RestApiValidationError } from '../../errors.js';
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { QueryExecutor } from "../registry.js";
+import { z } from "zod";
+import { RestApiValidationError } from "../../errors.js";
 
 /**
  * Base class for GraphQL integration clients.
@@ -43,7 +43,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
   async query<TResponse>(
     query: string,
     schema: { response: z.ZodSchema<TResponse> },
-    variables?: Record<string, unknown>
+    variables?: Record<string, unknown>,
   ): Promise<TResponse> {
     return this.executeGraphQL(query, schema, variables);
   }
@@ -59,7 +59,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
   async mutation<TResponse>(
     mutation: string,
     schema: { response: z.ZodSchema<TResponse> },
-    variables?: Record<string, unknown>
+    variables?: Record<string, unknown>,
   ): Promise<TResponse> {
     return this.executeGraphQL(mutation, schema, variables);
   }
@@ -73,7 +73,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
   private async executeGraphQL<TResponse>(
     queryString: string,
     schema: { response: z.ZodSchema<TResponse> },
-    variables?: Record<string, unknown>
+    variables?: Record<string, unknown>,
   ): Promise<TResponse> {
     // Build graphql.v1.Plugin proto message
     const request = {
@@ -81,7 +81,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
       custom: variables
         ? {
             variables: {
-              key: 'variables',
+              key: "variables",
               value: JSON.stringify(variables),
             },
           }
@@ -100,7 +100,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     // Schema is REQUIRED - always validate
     const result = schema.response.safeParse(response);
     if (!result.success) {
-      throw new RestApiValidationError('GraphQL response validation failed', {
+      throw new RestApiValidationError("GraphQL response validation failed", {
         zodError: result.error,
         data: response,
       });

package/src/integrations/base/index.ts

@@ -2,13 +2,13 @@
  * Base clients for integrations.
  */
 
-export { RestApiIntegrationClient } from './rest-api-integration-client.js';
-export type { RestApiRequest } from './rest-api-integration-client.js';
-export { GraphQLIntegrationClient } from './graphql-integration-client.js';
+export { RestApiIntegrationClient } from "./rest-api-integration-client.js";
+export type { RestApiRequest } from "./rest-api-integration-client.js";
+export { GraphQLIntegrationClient } from "./graphql-integration-client.js";
 export type {
   ApiRequestOptions,
   ApiRequestSchema,
   SupportsApiRequest,
   StreamApiRequestSchema,
   SupportsStreamingApiRequest,
-} from './types.js';
+} from "./types.js";