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

package/src/integrations/circleci/README.md

@@ -4,8 +4,8 @@ Trigger pipelines, manage jobs, and interact with CircleCI's CI/CD platform.
 
 ## Methods
 
-| Method | Description |
-| ------ | ----------- |
+| Method                        | Description                                          |
+| ----------------------------- | ---------------------------------------------------- |
 | `apiRequest(options, schema)` | Make any CircleCI API request with schema validation |
 
 ## Usage
@@ -13,7 +13,7 @@ Trigger pipelines, manage jobs, and interact with CircleCI's CI/CD platform.
 ### Trigger a Pipeline
 
 ```typescript
-import { api, z } from "@superblocksteam/sdk-api";
+import { api, z, circleci } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_CIRCLECI = "a1b2c3d4-5678-90ab-cdef-circleci0001";
@@ -26,14 +26,19 @@ const PipelineSchema = z.object({
   trigger: z.object({
     type: z.string(),
   }),
-  vcs: z.object({
-    branch: z.string().optional(),
-    tag: z.string().optional(),
-  }).optional(),
+  vcs: z
+    .object({
+      branch: z.string().optional(),
+      tag: z.string().optional(),
+    })
+    .optional(),
 });
 
 export default api({
   name: "CircleCIExample",
+  integrations: {
+    circleci: circleci(PROD_CIRCLECI),
+  },
   input: z.object({
     projectSlug: z.string(), // e.g., "gh/owner/repo"
     branch: z.string(),
@@ -43,9 +48,7 @@ export default api({
     number: z.number(),
   }),
   async run(ctx, { projectSlug, branch }) {
-    const circleci = ctx.circleci(PROD_CIRCLECI);
-
-    const result = await circleci.apiRequest(
+    const result = await ctx.integrations.circleci.apiRequest(
       {
         method: "POST",
         path: `/api/v2/project/${projectSlug}/pipeline`,
@@ -56,7 +59,7 @@ export default api({
           },
         },
       },
-      { response: PipelineSchema }
+      { response: PipelineSchema },
     );
 
     return { pipelineId: result.id, number: result.number };
@@ -67,12 +70,12 @@ export default api({
 ### Get Pipeline Status
 
 ```typescript
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
     path: `/api/v2/pipeline/${pipelineId}`,
   },
-  { response: PipelineSchema }
+  { response: PipelineSchema },
 );
 
 console.log(`Pipeline #${result.number}: ${result.state}`);
@@ -96,12 +99,12 @@ const ListWorkflowsResponseSchema = z.object({
   next_page_token: z.string().nullable(),
 });
 
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
     path: `/api/v2/pipeline/${pipelineId}/workflow`,
   },
-  { response: ListWorkflowsResponseSchema }
+  { response: ListWorkflowsResponseSchema },
 );
 
 result.items.forEach((wf) => {
@@ -127,12 +130,12 @@ const ListJobsResponseSchema = z.object({
   next_page_token: z.string().nullable(),
 });
 
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
     path: `/api/v2/workflow/${workflowId}/job`,
   },
-  { response: ListJobsResponseSchema }
+  { response: ListJobsResponseSchema },
 );
 
 result.items.forEach((job) => {
@@ -156,12 +159,12 @@ const JobDetailSchema = z.object({
   parallel_runs: z.array(z.object({ index: z.number(), status: z.string() })),
 });
 
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
     path: `/api/v2/project/${projectSlug}/job/${jobNumber}`,
   },
-  { response: JobDetailSchema }
+  { response: JobDetailSchema },
 );
 ```
 
@@ -172,7 +175,7 @@ const RetryResponseSchema = z.object({
   workflow_id: z.string(),
 });
 
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
     path: `/api/v2/workflow/${workflowId}/rerun`,
@@ -180,7 +183,7 @@ const result = await circleci.apiRequest(
       from_failed: true, // Only rerun failed jobs
     },
   },
-  { response: RetryResponseSchema }
+  { response: RetryResponseSchema },
 );
 
 console.log(`Retrying workflow: ${result.workflow_id}`);
@@ -193,12 +196,12 @@ const CancelResponseSchema = z.object({
   message: z.string(),
 });
 
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
     path: `/api/v2/workflow/${workflowId}/cancel`,
   },
-  { response: CancelResponseSchema }
+  { response: CancelResponseSchema },
 );
 ```
 
@@ -210,7 +213,7 @@ const ListPipelinesResponseSchema = z.object({
   next_page_token: z.string().nullable(),
 });
 
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
     path: `/api/v2/project/${projectSlug}/pipeline`,
@@ -219,7 +222,7 @@ const result = await circleci.apiRequest(
       "page-token": undefined, // For pagination
     },
   },
-  { response: ListPipelinesResponseSchema }
+  { response: ListPipelinesResponseSchema },
 );
 
 result.items.forEach((pipeline) => {
@@ -241,12 +244,12 @@ const ProjectSchema = z.object({
   }),
 });
 
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
     path: `/api/v2/project/${projectSlug}`,
   },
-  { response: ProjectSchema }
+  { response: ProjectSchema },
 );
 ```
 
@@ -264,12 +267,12 @@ const ListArtifactsResponseSchema = z.object({
   next_page_token: z.string().nullable(),
 });
 
-const result = await circleci.apiRequest(
+const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
     path: `/api/v2/project/${projectSlug}/${jobNumber}/artifacts`,
   },
-  { response: ListArtifactsResponseSchema }
+  { response: ListArtifactsResponseSchema },
 );
 
 result.items.forEach((artifact) => {
@@ -287,7 +290,7 @@ await circleci.triggerPipeline({ ... });
 await circleci.getWorkflow({ ... });
 
 // CORRECT - Use apiRequest
-await circleci.apiRequest(
+await ctx.integrations.circleci.apiRequest(
   { method: "POST", path: `/api/v2/project/${slug}/pipeline`, body: { ... } },
   { response: PipelineSchema }
 );
@@ -345,19 +348,43 @@ Different resources have different status values:
 
 ```typescript
 // Pipeline states
-const pipelineStates = ["created", "errored", "setup", "setup-pending", "pending", "running"];
+const pipelineStates = [
+  "created",
+  "errored",
+  "setup",
+  "setup-pending",
+  "pending",
+  "running",
+];
 
 // Workflow statuses
 const workflowStatuses = [
-  "success", "running", "not_run", "failed", "error",
-  "failing", "on_hold", "canceled", "unauthorized",
+  "success",
+  "running",
+  "not_run",
+  "failed",
+  "error",
+  "failing",
+  "on_hold",
+  "canceled",
+  "unauthorized",
 ];
 
 // Job statuses
 const jobStatuses = [
-  "success", "running", "not_run", "failed", "retried",
-  "queued", "not_running", "infrastructure_fail", "timedout",
-  "on_hold", "terminated-unknown", "canceled", "unauthorized",
+  "success",
+  "running",
+  "not_run",
+  "failed",
+  "retried",
+  "queued",
+  "not_running",
+  "infrastructure_fail",
+  "timedout",
+  "on_hold",
+  "terminated-unknown",
+  "canceled",
+  "unauthorized",
   "blocked",
 ];
 ```
@@ -372,13 +399,13 @@ async function getAllPipelines(circleci: CircleCIClient, projectSlug: string) {
   let pageToken: string | undefined;
 
   do {
-    const result = await circleci.apiRequest(
+    const result = await ctx.integrations.circleci.apiRequest(
       {
         method: "GET",
         path: `/api/v2/project/${projectSlug}/pipeline`,
         params: pageToken ? { "page-token": pageToken } : {},
       },
-      { response: ListPipelinesResponseSchema }
+      { response: ListPipelinesResponseSchema },
     );
 
     allPipelines.push(...result.items);
@@ -395,7 +422,7 @@ When rerunning workflows:
 
 ```typescript
 // Rerun all jobs
-await circleci.apiRequest(
+await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
     path: `/api/v2/workflow/${workflowId}/rerun`,
@@ -403,11 +430,11 @@ await circleci.apiRequest(
       from_failed: false, // Rerun everything
     },
   },
-  { response: RetryResponseSchema }
+  { response: RetryResponseSchema },
 );
 
 // Rerun only failed jobs
-await circleci.apiRequest(
+await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
     path: `/api/v2/workflow/${workflowId}/rerun`,
@@ -415,7 +442,7 @@ await circleci.apiRequest(
       from_failed: true, // Only failed jobs
     },
   },
-  { response: RetryResponseSchema }
+  { response: RetryResponseSchema },
 );
 ```
 
@@ -425,7 +452,7 @@ await circleci.apiRequest(
 import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await circleci.apiRequest(
+  const result = await ctx.integrations.circleci.apiRequest(
     { method: "POST", path: `/api/v2/project/${slug}/pipeline`, body: { ... } },
     { response: PipelineSchema }
   );

package/src/integrations/circleci/client.ts

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

package/src/integrations/circleci/index.ts

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

package/src/integrations/circleci/types.ts

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

package/src/integrations/cockroachdb/README.md

@@ -4,17 +4,17 @@ Execute SQL queries and statements against CockroachDB databases with full type
 
 ## 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, cockroachdb } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_COCKROACHDB = "a1b2c3d4-5678-90ab-cdef-cockroac0001";
@@ -28,6 +28,9 @@ const UserSchema = z.object({
 
 export default api({
   name: "CockroachDBExample",
+  integrations: {
+    db: cockroachdb(PROD_COCKROACHDB),
+  },
   input: z.object({
     status: z.string(),
   }),
@@ -35,12 +38,10 @@ export default api({
     users: z.array(UserSchema),
   }),
   async run(ctx, { status }) {
-    const cockroachdb = ctx.cockroachdb(PROD_COCKROACHDB);
-
-    const users = await cockroachdb.query(
+    const users = await ctx.integrations.db.query(
       "SELECT id, name, email, created_at FROM users WHERE status = $1",
       UserSchema,
-      [status]
+      [status],
     );
 
     return { users };
@@ -51,24 +52,22 @@ export default api({
 ### Executing INSERT, UPDATE, DELETE Statements
 
 ```typescript
-const cockroachdb = ctx.cockroachdb(PROD_COCKROACHDB);
-
 // INSERT with RETURNING
-await cockroachdb.execute(
+await ctx.integrations.db.execute(
   "INSERT INTO users (name, email) VALUES ($1, $2)",
-  ["John Doe", "john@example.com"]
+  ["John Doe", "john@example.com"],
 );
 
 // UPDATE
-const updateResult = await cockroachdb.execute(
+const updateResult = await ctx.integrations.db.execute(
   "UPDATE users SET last_login = now() WHERE id = $1",
-  [userId]
+  [userId],
 );
 console.log(`Updated ${updateResult.rowCount} rows`);
 
 // DELETE
-const deleteResult = await cockroachdb.execute(
-  "DELETE FROM sessions WHERE expires_at < now()"
+const deleteResult = await ctx.integrations.db.execute(
+  "DELETE FROM sessions WHERE expires_at < now()",
 );
 console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
 ```
@@ -78,10 +77,10 @@ console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
 CockroachDB supports PostgreSQL-style arrays:
 
 ```typescript
-const items = await cockroachdb.query(
+const items = await ctx.integrations.db.query(
   "SELECT * FROM items WHERE id = ANY($1)",
   ItemSchema,
-  [[1, 2, 3]]
+  [[1, 2, 3]],
 );
 ```
 
@@ -110,7 +109,10 @@ const schema = z.object({
 
 ```typescript
 // CORRECT - Schema is required
-const users = await cockroachdb.query("SELECT * FROM users", UserSchema);
+const users = await ctx.integrations.db.query(
+  "SELECT * FROM users",
+  UserSchema,
+);
 ```
 
 ### NULL Handling
@@ -128,7 +130,10 @@ const schema = z.object({
 import { QueryValidationError } from "@superblocksteam/sdk-api";
 
 try {
-  const users = await cockroachdb.query("SELECT * FROM users", UserSchema);
+  const users = await ctx.integrations.db.query(
+    "SELECT * FROM users",
+    UserSchema,
+  );
 } catch (error) {
   if (error instanceof QueryValidationError) {
     console.error("Row index:", error.details.rowIndex);

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

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

package/src/integrations/cockroachdb/types.ts

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