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

package/src/integrations/base/rest-api-integration-client.ts

@@ -16,7 +16,10 @@ import type {
   StreamApiRequestSchema,
   SupportsStreamingApiRequest,
 } from "./types.js";
-import { RestApiValidationError, StreamChunkValidationError } from "../../errors.js";
+import {
+  RestApiValidationError,
+  StreamChunkValidationError,
+} from "../../errors.js";
 import type { z } from "zod";
 
 export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
@@ -29,7 +32,11 @@ export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
  * Also supports streaming API requests when a streaming executor is provided.
  */
 export abstract class RestApiIntegrationClient
-  implements IntegrationClientImpl, SupportsApiRequest, SupportsStreamingApiRequest {
+  implements
+    IntegrationClientImpl,
+    SupportsApiRequest,
+    SupportsStreamingApiRequest
+{
   readonly name: string;
   readonly pluginId: string;
   readonly config: IntegrationConfig;
@@ -61,7 +68,9 @@ export abstract class RestApiIntegrationClient
 
   async apiRequest<TBody, TResponse>(
     options: ApiRequestOptions<TBody>,
-    schema: ApiRequestSchema<TBody, TResponse> & { response: z.ZodSchema<TResponse> },
+    schema: ApiRequestSchema<TBody, TResponse> & {
+      response: z.ZodSchema<TResponse>;
+    },
   ): Promise<TResponse> {
     // Validate that body schema is provided if body is present
     if (options.body !== undefined) {
@@ -267,7 +276,9 @@ export abstract class RestApiIntegrationClient
     }
 
     // Execute the streaming request
-    const stream = this.executeStreamingQuery(request as Record<string, unknown>);
+    const stream = this.executeStreamingQuery(
+      request as Record<string, unknown>,
+    );
 
     // Validate and yield each chunk
     let chunkIndex = 0;

package/src/integrations/base/types.ts

@@ -2,7 +2,7 @@
  * Shared types for REST API Integration (OpenAPI) based clients.
  */
 
-import type { z } from 'zod';
+import type { z } from "zod";
 
 /**
  * Options for making a generic REST API request.
@@ -11,7 +11,7 @@ export interface ApiRequestOptions<TBody = unknown> {
   /**
    * HTTP method for the request.
    */
-  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
 
   /**
    * API endpoint path (e.g., "/users", "/repos/owner/repo")
@@ -67,14 +67,9 @@ export interface SupportsApiRequest {
    *
    * @example
    * ```typescript
-   * const client = ctx.slack('Ops Slack');
-   *
-   * const ResponseSchema = z.object({
-   *   ts: z.string(),
-   *   channel: z.string(),
-   * });
-   *
-   * const result = await client.apiRequest(
+   * // Declare in api(): integrations: { slack: slack(INTEGRATION_ID) }
+   * // In run(), access via: ctx.integrations.<name>
+   * const result = await ctx.integrations.slack.apiRequest(
    *   {
    *     method: 'POST',
    *     path: '/chat.postMessage',
@@ -96,7 +91,9 @@ export interface SupportsApiRequest {
    */
   apiRequest<TBody, TResponse>(
     options: ApiRequestOptions<TBody>,
-    schema: ApiRequestSchema<TBody, TResponse> & { response: z.ZodSchema<TResponse> }
+    schema: ApiRequestSchema<TBody, TResponse> & {
+      response: z.ZodSchema<TResponse>;
+    },
   ): Promise<TResponse>;
 }
 

package/src/integrations/bigquery/README.md

@@ -4,17 +4,17 @@ Execute SQL queries against Google BigQuery with full type safety and runtime va
 
 ## 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, bigquery } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_BIGQUERY = "a1b2c3d4-5678-90ab-cdef-bigquery0001";
@@ -27,6 +27,9 @@ const EventSchema = z.object({
 });
 
 export default api({
+  integrations: {
+    bigquery: bigquery(PROD_BIGQUERY),
+  },
   input: z.object({
     event_name: z.string(),
   }),
@@ -34,15 +37,13 @@ export default api({
     events: z.array(EventSchema),
   }),
   async run(ctx, { event_name }) {
-    const bigquery = ctx.bigquery(PROD_BIGQUERY);
-
-    const events = await bigquery.query(
+    const events = await ctx.integrations.bigquery.query(
       `SELECT event_id, event_name, user_id, timestamp
        FROM \`project.dataset.events\`
        WHERE event_name = $1
        LIMIT 100`,
       EventSchema,
-      [event_name]
+      [event_name],
     );
 
     return { events };
@@ -53,12 +54,10 @@ export default api({
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
-const bigquery = ctx.bigquery(PROD_BIGQUERY);
-
 // INSERT
-await bigquery.execute(
+await ctx.integrations.bigquery.execute(
   "INSERT INTO `project.dataset.metrics` (name, value, timestamp) VALUES ($1, $2, CURRENT_TIMESTAMP())",
-  ["cpu_usage", "75.5"]
+  ["cpu_usage", "75.5"],
 );
 ```
 
@@ -71,7 +70,7 @@ const AnalyticsSchema = z.object({
   unique_users: z.coerce.number(),
 });
 
-const analytics = await bigquery.query(
+const analytics = await ctx.integrations.bigquery.query(
   `SELECT
     DATE(timestamp) as date,
     COUNT(*) as total_events,
@@ -80,7 +79,7 @@ const analytics = await bigquery.query(
   WHERE timestamp >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
   GROUP BY date
   ORDER BY date DESC`,
-  AnalyticsSchema
+  AnalyticsSchema,
 );
 ```
 
@@ -93,11 +92,11 @@ const UserActivitySchema = z.object({
     z.object({
       event_name: z.string(),
       count: z.coerce.number(),
-    })
+    }),
   ),
 });
 
-const activity = await bigquery.query(
+const activity = await ctx.integrations.bigquery.query(
   `SELECT
     user_id,
     ARRAY_AGG(STRUCT(event_name, count)) as events
@@ -107,7 +106,7 @@ const activity = await bigquery.query(
     GROUP BY user_id, event_name
   )
   GROUP BY user_id`,
-  UserActivitySchema
+  UserActivitySchema,
 );
 ```
 
@@ -138,7 +137,10 @@ const schema = z.object({
 
 ```typescript
 // CORRECT - Schema is required
-const events = await bigquery.query("SELECT * FROM `project.dataset.events`", EventSchema);
+const events = await ctx.integrations.bigquery.query(
+  "SELECT * FROM `project.dataset.events`",
+  EventSchema,
+);
 ```
 
 ### NULL Handling
@@ -169,7 +171,10 @@ const query = `
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const events = await bigquery.query("SELECT * FROM `project.dataset.events`", EventSchema);
+  const events = await ctx.integrations.bigquery.query(
+    "SELECT * FROM `project.dataset.events`",
+    EventSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     console.error("Row index:", error.details.rowIndex);

package/src/integrations/bigquery/client.ts

@@ -5,20 +5,22 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from 'zod';
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { Plugin as BigQueryPlugin } from '@superblocksteam/types/dist/src/plugins/bigquery/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 { BigQueryClient } from './types.js';
+import type { z } from "zod";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import type { Plugin as BigQueryPlugin } from "@superblocksteam/types/dist/src/plugins/bigquery/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 { BigQueryClient } from "./types.js";
 
 /**
  * Internal implementation of the BigQuery client.
  */
-export class BigQueryClientImpl implements BigQueryClient, IntegrationClientImpl {
+export class BigQueryClientImpl
+  implements BigQueryClient, IntegrationClientImpl
+{
   readonly config: IntegrationConfig;
   private readonly executeQuery: QueryExecutor;
 
@@ -71,7 +73,7 @@ export class BigQueryClientImpl implements BigQueryClient, IntegrationClientImpl
       if (!Array.isArray(result)) {
         throw new IntegrationError(
           this.config.name,
-          'query',
+          "query",
           `Expected array result from BigQuery query, got: ${describeType(result)}`,
         );
       }
@@ -107,27 +109,30 @@ export class BigQueryClientImpl implements BigQueryClient, 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/bigquery/index.ts

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

package/src/integrations/bigquery/types.ts

@@ -4,15 +4,16 @@
  * Provides typed methods for executing BigQuery 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 BigQuery queries with type-safe validation.
  *
  * @example
  * ```typescript
- * const bigquery = ctx.bigquery('Production BigQuery');
+ * // Declare in api(): integrations: { bigquery: bigquery(INTEGRATION_ID) }
+ * // In run(), access via ctx.integrations.bigquery
  *
  * // Query with validation
  * const EventSchema = z.object({
@@ -40,7 +41,11 @@ export interface BigQueryClient 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/bitbucket/README.md

@@ -4,8 +4,8 @@ Manage repositories, pull requests, and interact with Bitbucket's APIs.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                           |
+| ----------------------------- | ----------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any Bitbucket API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Manage repositories, pull requests, and interact with Bitbucket's APIs.
 ### List Repositories
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, bitbucket } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_BITBUCKET = "a1b2c3d4-5678-90ab-cdef-bitbucke0001";
@@ -41,6 +41,9 @@ const ListReposResponseSchema = z.object({
 
 export default api({
   name: "BitbucketExample",
+  integrations: {
+    bitbucket: bitbucket(PROD_BITBUCKET),
+  },
   input: z.object({
     workspace: z.string(),
   }),
@@ -48,9 +51,7 @@ export default api({
     repos: z.array(z.object({ name: z.string(), url: z.string() })),
   }),
   async run(ctx, { workspace }) {
-    const bitbucket = ctx.bitbucket(PROD_BITBUCKET);
-
-    const result = await bitbucket.apiRequest(
+    const result = await ctx.integrations.bitbucket.apiRequest(
       {
         method: "GET",
         path: `/2.0/repositories/${workspace}`,
@@ -58,7 +59,7 @@ export default api({
           pagelen: 50,
         },
       },
-      { response: ListReposResponseSchema }
+      { response: ListReposResponseSchema },
     );
 
     return {
@@ -74,12 +75,12 @@ export default api({
 ### Get Repository
 
 ```typescript
-const repo = await bitbucket.apiRequest(
+const repo = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
     path: `/2.0/repositories/${workspace}/${repoSlug}`,
   },
-  { response: RepositorySchema }
+  { response: RepositorySchema },
 );
 
 console.log(`${repo.full_name}: ${repo.is_private ? "private" : "public"}`);
@@ -107,7 +108,7 @@ const PullRequestSchema = z.object({
   }),
 });
 
-const pr = await bitbucket.apiRequest(
+const pr = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
     path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests`,
@@ -123,7 +124,7 @@ const pr = await bitbucket.apiRequest(
       close_source_branch: true,
     },
   },
-  { response: PullRequestSchema }
+  { response: PullRequestSchema },
 );
 
 console.log(`Created PR #${pr.id}: ${pr.links.html.href}`);
@@ -139,7 +140,7 @@ const ListPRsResponseSchema = z.object({
   next: z.string().optional(),
 });
 
-const result = await bitbucket.apiRequest(
+const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
     path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests`,
@@ -148,7 +149,7 @@ const result = await bitbucket.apiRequest(
       pagelen: 25,
     },
   },
-  { response: ListPRsResponseSchema }
+  { response: ListPRsResponseSchema },
 );
 
 result.values.forEach((pr) => {
@@ -161,12 +162,14 @@ result.values.forEach((pr) => {
 ```typescript
 const MergeResponseSchema = z.object({
   state: z.string(),
-  merge_commit: z.object({
-    hash: z.string(),
-  }).optional(),
+  merge_commit: z
+    .object({
+      hash: z.string(),
+    })
+    .optional(),
 });
 
-const result = await bitbucket.apiRequest(
+const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
     path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/merge`,
@@ -177,7 +180,7 @@ const result = await bitbucket.apiRequest(
       merge_strategy: "squash", // merge_commit, squash, fast_forward
     },
   },
-  { response: MergeResponseSchema }
+  { response: MergeResponseSchema },
 );
 ```
 
@@ -190,9 +193,11 @@ const CommitSchema = z.object({
   date: z.string(),
   author: z.object({
     raw: z.string(),
-    user: z.object({
-      display_name: z.string(),
-    }).optional(),
+    user: z
+      .object({
+        display_name: z.string(),
+      })
+      .optional(),
   }),
 });
 
@@ -201,7 +206,7 @@ const ListCommitsResponseSchema = z.object({
   next: z.string().optional(),
 });
 
-const result = await bitbucket.apiRequest(
+const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
     path: `/2.0/repositories/${workspace}/${repoSlug}/commits`,
@@ -210,7 +215,7 @@ const result = await bitbucket.apiRequest(
       pagelen: 10,
     },
   },
-  { response: ListCommitsResponseSchema }
+  { response: ListCommitsResponseSchema },
 );
 ```
 
@@ -224,7 +229,7 @@ const BranchSchema = z.object({
   }),
 });
 
-const branch = await bitbucket.apiRequest(
+const branch = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
     path: `/2.0/repositories/${workspace}/${repoSlug}/refs/branches`,
@@ -235,7 +240,7 @@ const branch = await bitbucket.apiRequest(
       },
     },
   },
-  { response: BranchSchema }
+  { response: BranchSchema },
 );
 ```
 
@@ -243,12 +248,12 @@ const branch = await bitbucket.apiRequest(
 
 ```typescript
 // Note: Returns raw file content, not JSON
-const content = await bitbucket.apiRequest(
+const content = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
     path: `/2.0/repositories/${workspace}/${repoSlug}/src/main/README.md`,
   },
-  { response: z.string() }
+  { response: z.string() },
 );
 ```
 
@@ -266,7 +271,7 @@ const CommentSchema = z.object({
   }),
 });
 
-const comment = await bitbucket.apiRequest(
+const comment = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
     path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/comments`,
@@ -276,7 +281,7 @@ const comment = await bitbucket.apiRequest(
       },
     },
   },
-  { response: CommentSchema }
+  { response: CommentSchema },
 );
 ```
 
@@ -290,7 +295,7 @@ await bitbucket.createPullRequest({ ... });
 await bitbucket.listRepos();
 
 // CORRECT - Use apiRequest
-await bitbucket.apiRequest(
+await ctx.integrations.bitbucket.apiRequest(
   { method: "POST", path: `/2.0/repositories/${workspace}/${repo}/pullrequests`, body: { ... } },
   { response: PullRequestSchema }
 );
@@ -325,18 +330,22 @@ const path = `/2.0/repositories/myusername/myrepo`;
 Bitbucket uses `pagelen` and `next` URL:
 
 ```typescript
-async function getAllPRs(bitbucket: BitbucketClient, workspace: string, repo: string) {
+async function getAllPRs(
+  bitbucket: BitbucketClient,
+  workspace: string,
+  repo: string,
+) {
   const allPRs: PullRequest[] = [];
   let url = `/2.0/repositories/${workspace}/${repo}/pullrequests`;
 
   while (url) {
-    const result = await bitbucket.apiRequest(
+    const result = await ctx.integrations.bitbucket.apiRequest(
       {
         method: "GET",
         path: url,
         params: url.includes("?") ? {} : { pagelen: 50 },
       },
-      { response: ListPRsResponseSchema }
+      { response: ListPRsResponseSchema },
     );
 
     allPRs.push(...result.values);
@@ -355,10 +364,14 @@ PR states are uppercase:
 const states = ["OPEN", "MERGED", "DECLINED", "SUPERSEDED"];
 
 // WRONG
-params: { state: "open" }
+params: {
+  state: "open";
+}
 
 // CORRECT
-params: { state: "OPEN" }
+params: {
+  state: "OPEN";
+}
 ```
 
 ### Branch Names in Paths
@@ -377,9 +390,12 @@ File content endpoints return raw text, not JSON:
 
 ```typescript
 // This returns raw file content as string
-const content = await bitbucket.apiRequest(
-  { method: "GET", path: `/2.0/repositories/${workspace}/${repo}/src/main/file.txt` },
-  { response: z.string() }  // Not a JSON schema
+const content = await ctx.integrations.bitbucket.apiRequest(
+  {
+    method: "GET",
+    path: `/2.0/repositories/${workspace}/${repo}/src/main/file.txt`,
+  },
+  { response: z.string() }, // Not a JSON schema
 );
 ```
 
@@ -389,9 +405,9 @@ const content = await bitbucket.apiRequest(
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await bitbucket.apiRequest(
+  const result = await ctx.integrations.bitbucket.apiRequest(
     { method: "GET", path: `/2.0/repositories/${workspace}/${repo}` },
-    { response: RepositorySchema }
+    { response: RepositorySchema },
   );
 } catch (error) {
   if (error instanceof RestApiValidationError) {

package/src/integrations/bitbucket/client.ts

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

package/src/integrations/bitbucket/index.ts

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

package/src/integrations/bitbucket/types.ts

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