@superblocksteam/sdk-api 2.0.89-next.0

package/src/integrations/circleci/README.md

@@ -0,0 +1,444 @@
+# CircleCI Client
+
+Trigger pipelines, manage jobs, and interact with CircleCI's CI/CD platform.
+
+## Methods
+
+| Method | Description |
+| ------ | ----------- |
+| `apiRequest(options, schema)` | Make any CircleCI API request with schema validation |
+
+## Usage
+
+### Trigger a Pipeline
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_CIRCLECI = "a1b2c3d4-5678-90ab-cdef-circleci0001";
+
+const PipelineSchema = z.object({
+  id: z.string(),
+  number: z.number(),
+  state: z.string(),
+  created_at: z.string(),
+  trigger: z.object({
+    type: z.string(),
+  }),
+  vcs: z.object({
+    branch: z.string().optional(),
+    tag: z.string().optional(),
+  }).optional(),
+});
+
+export default api({
+  name: "CircleCIExample",
+  input: z.object({
+    projectSlug: z.string(), // e.g., "gh/owner/repo"
+    branch: z.string(),
+  }),
+  output: z.object({
+    pipelineId: z.string(),
+    number: z.number(),
+  }),
+  async run(ctx, { projectSlug, branch }) {
+    const circleci = ctx.circleci(PROD_CIRCLECI);
+
+    const result = await circleci.apiRequest(
+      {
+        method: "POST",
+        path: `/api/v2/project/${projectSlug}/pipeline`,
+        body: {
+          branch: branch,
+          parameters: {
+            run_integration_tests: true,
+          },
+        },
+      },
+      { response: PipelineSchema }
+    );
+
+    return { pipelineId: result.id, number: result.number };
+  },
+});
+```
+
+### Get Pipeline Status
+
+```typescript
+const result = await circleci.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/pipeline/${pipelineId}`,
+  },
+  { response: PipelineSchema }
+);
+
+console.log(`Pipeline #${result.number}: ${result.state}`);
+```
+
+### List Pipeline Workflows
+
+```typescript
+const WorkflowSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  status: z.string(), // success, failed, running, etc.
+  created_at: z.string(),
+  stopped_at: z.string().nullable(),
+  pipeline_id: z.string(),
+  pipeline_number: z.number(),
+});
+
+const ListWorkflowsResponseSchema = z.object({
+  items: z.array(WorkflowSchema),
+  next_page_token: z.string().nullable(),
+});
+
+const result = await circleci.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/pipeline/${pipelineId}/workflow`,
+  },
+  { response: ListWorkflowsResponseSchema }
+);
+
+result.items.forEach((wf) => {
+  console.log(`${wf.name}: ${wf.status}`);
+});
+```
+
+### Get Workflow Jobs
+
+```typescript
+const JobSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.string(),
+  status: z.string(), // success, failed, running, blocked, etc.
+  started_at: z.string().nullable(),
+  stopped_at: z.string().nullable(),
+  job_number: z.number().optional(),
+});
+
+const ListJobsResponseSchema = z.object({
+  items: z.array(JobSchema),
+  next_page_token: z.string().nullable(),
+});
+
+const result = await circleci.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/workflow/${workflowId}/job`,
+  },
+  { response: ListJobsResponseSchema }
+);
+
+result.items.forEach((job) => {
+  console.log(`${job.name}: ${job.status}`);
+});
+```
+
+### Get Job Details
+
+```typescript
+const JobDetailSchema = z.object({
+  number: z.number(),
+  status: z.string(),
+  started_at: z.string(),
+  stopped_at: z.string().nullable(),
+  duration: z.number().nullable(),
+  executor: z.object({
+    type: z.string(),
+    resource_class: z.string(),
+  }),
+  parallel_runs: z.array(z.object({ index: z.number(), status: z.string() })),
+});
+
+const result = await circleci.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/project/${projectSlug}/job/${jobNumber}`,
+  },
+  { response: JobDetailSchema }
+);
+```
+
+### Retry a Workflow
+
+```typescript
+const RetryResponseSchema = z.object({
+  workflow_id: z.string(),
+});
+
+const result = await circleci.apiRequest(
+  {
+    method: "POST",
+    path: `/api/v2/workflow/${workflowId}/rerun`,
+    body: {
+      from_failed: true, // Only rerun failed jobs
+    },
+  },
+  { response: RetryResponseSchema }
+);
+
+console.log(`Retrying workflow: ${result.workflow_id}`);
+```
+
+### Cancel a Workflow
+
+```typescript
+const CancelResponseSchema = z.object({
+  message: z.string(),
+});
+
+const result = await circleci.apiRequest(
+  {
+    method: "POST",
+    path: `/api/v2/workflow/${workflowId}/cancel`,
+  },
+  { response: CancelResponseSchema }
+);
+```
+
+### List Project Pipelines
+
+```typescript
+const ListPipelinesResponseSchema = z.object({
+  items: z.array(PipelineSchema),
+  next_page_token: z.string().nullable(),
+});
+
+const result = await circleci.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/project/${projectSlug}/pipeline`,
+    params: {
+      branch: "main",
+      "page-token": undefined, // For pagination
+    },
+  },
+  { response: ListPipelinesResponseSchema }
+);
+
+result.items.forEach((pipeline) => {
+  console.log(`Pipeline #${pipeline.number}: ${pipeline.state}`);
+});
+```
+
+### Get Project Settings
+
+```typescript
+const ProjectSchema = z.object({
+  slug: z.string(),
+  name: z.string(),
+  organization_name: z.string(),
+  vcs_info: z.object({
+    vcs_url: z.string(),
+    provider: z.string(),
+    default_branch: z.string(),
+  }),
+});
+
+const result = await circleci.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/project/${projectSlug}`,
+  },
+  { response: ProjectSchema }
+);
+```
+
+### Get Job Artifacts
+
+```typescript
+const ArtifactSchema = z.object({
+  path: z.string(),
+  node_index: z.number(),
+  url: z.string(),
+});
+
+const ListArtifactsResponseSchema = z.object({
+  items: z.array(ArtifactSchema),
+  next_page_token: z.string().nullable(),
+});
+
+const result = await circleci.apiRequest(
+  {
+    method: "GET",
+    path: `/api/v2/project/${projectSlug}/${jobNumber}/artifacts`,
+  },
+  { response: ListArtifactsResponseSchema }
+);
+
+result.items.forEach((artifact) => {
+  console.log(`Artifact: ${artifact.path} -> ${artifact.url}`);
+});
+```
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await circleci.triggerPipeline({ ... });
+await circleci.getWorkflow({ ... });
+
+// CORRECT - Use apiRequest
+await circleci.apiRequest(
+  { method: "POST", path: `/api/v2/project/${slug}/pipeline`, body: { ... } },
+  { response: PipelineSchema }
+);
+```
+
+### Project Slug Format
+
+Project slugs follow the pattern `{vcs}/{org}/{repo}`:
+
+```typescript
+// GitHub
+const slug = "gh/my-org/my-repo";
+
+// Bitbucket
+const slug = "bb/my-workspace/my-repo";
+
+// GitLab
+const slug = "gl/my-group/my-repo";
+```
+
+### API Version in Path
+
+Always include `/api/v2/`:
+
+```typescript
+// WRONG
+const path = `/project/${slug}/pipeline`;
+
+// CORRECT
+const path = `/api/v2/project/${slug}/pipeline`;
+```
+
+### Pipeline Parameters
+
+Pipeline parameters must be defined in your config.yml:
+
+```typescript
+// In .circleci/config.yml:
+// parameters:
+//   run_integration_tests:
+//     type: boolean
+//     default: false
+
+const body = {
+  branch: "main",
+  parameters: {
+    run_integration_tests: true, // Must match config.yml parameter
+  },
+};
+```
+
+### Status Values
+
+Different resources have different status values:
+
+```typescript
+// Pipeline states
+const pipelineStates = ["created", "errored", "setup", "setup-pending", "pending", "running"];
+
+// Workflow statuses
+const workflowStatuses = [
+  "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",
+  "blocked",
+];
+```
+
+### Pagination
+
+CircleCI uses `next_page_token`:
+
+```typescript
+async function getAllPipelines(circleci: CircleCIClient, projectSlug: string) {
+  const allPipelines: Pipeline[] = [];
+  let pageToken: string | undefined;
+
+  do {
+    const result = await circleci.apiRequest(
+      {
+        method: "GET",
+        path: `/api/v2/project/${projectSlug}/pipeline`,
+        params: pageToken ? { "page-token": pageToken } : {},
+      },
+      { response: ListPipelinesResponseSchema }
+    );
+
+    allPipelines.push(...result.items);
+    pageToken = result.next_page_token ?? undefined;
+  } while (pageToken);
+
+  return allPipelines;
+}
+```
+
+### Rerun Options
+
+When rerunning workflows:
+
+```typescript
+// Rerun all jobs
+await circleci.apiRequest(
+  {
+    method: "POST",
+    path: `/api/v2/workflow/${workflowId}/rerun`,
+    body: {
+      from_failed: false, // Rerun everything
+    },
+  },
+  { response: RetryResponseSchema }
+);
+
+// Rerun only failed jobs
+await circleci.apiRequest(
+  {
+    method: "POST",
+    path: `/api/v2/workflow/${workflowId}/rerun`,
+    body: {
+      from_failed: true, // Only failed jobs
+    },
+  },
+  { response: RetryResponseSchema }
+);
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await circleci.apiRequest(
+    { method: "POST", path: `/api/v2/project/${slug}/pipeline`, body: { ... } },
+    { response: PipelineSchema }
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [CircleCI API Documentation](https://circleci.com/docs/api/v2/index.html)
+- [Pipeline](https://circleci.com/docs/api/v2/index.html#tag/Pipeline)
+- [Workflow](https://circleci.com/docs/api/v2/index.html#tag/Workflow)
+- [Job](https://circleci.com/docs/api/v2/index.html#tag/Job)

package/src/integrations/circleci/client.ts

@@ -0,0 +1,21 @@
+/**
+ * CircleCI client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * CircleCI integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from '../base/index.js';
+import type { CircleCIClient } from './types.js';
+
+/**
+ * Internal implementation of CircleCIClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * CircleCI API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class CircleCIClientImpl extends RestApiIntegrationClient implements CircleCIClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/circleci/index.ts

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

package/src/integrations/circleci/types.ts

@@ -0,0 +1,34 @@
+/**
+ * CircleCI client types.
+ */
+
+import type { BaseIntegrationClient } from '../../types.js';
+import type { SupportsApiRequest } from '../base/index.js';
+
+/**
+ * CircleCI client for API interactions.
+ *
+ * Provides generic API request method for interacting with CircleCI's API.
+ * Use apiRequest() to make calls to any CircleCI API endpoint.
+ *
+ * @example
+ * ```typescript
+ * const circleci = ctx.circleCI('My CircleCI');
+ *
+ * // Make API requests
+ * const ResponseSchema = z.object({
+ *   // Define your response schema
+ * });
+ *
+ * const result = await circleci.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/project',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface CircleCIClient extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}

package/src/integrations/cockroachdb/README.md

@@ -0,0 +1,144 @@
+# CockroachDB Client
+
+Execute SQL queries and statements against CockroachDB databases with full type safety and runtime validation.
+
+## 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 |
+
+## Usage
+
+### Basic Query with Schema Validation
+
+```typescript
+import { api, z } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_COCKROACHDB = "a1b2c3d4-5678-90ab-cdef-cockroac0001";
+
+const UserSchema = z.object({
+  id: z.string(), // UUIDs are common in CockroachDB
+  name: z.string(),
+  email: z.string().email(),
+  created_at: z.string(),
+});
+
+export default api({
+  name: "CockroachDBExample",
+  input: z.object({
+    status: z.string(),
+  }),
+  output: z.object({
+    users: z.array(UserSchema),
+  }),
+  async run(ctx, { status }) {
+    const cockroachdb = ctx.cockroachdb(PROD_COCKROACHDB);
+
+    const users = await cockroachdb.query(
+      "SELECT id, name, email, created_at FROM users WHERE status = $1",
+      UserSchema,
+      [status]
+    );
+
+    return { users };
+  },
+});
+```
+
+### Executing INSERT, UPDATE, DELETE Statements
+
+```typescript
+const cockroachdb = ctx.cockroachdb(PROD_COCKROACHDB);
+
+// INSERT with RETURNING
+await cockroachdb.execute(
+  "INSERT INTO users (name, email) VALUES ($1, $2)",
+  ["John Doe", "john@example.com"]
+);
+
+// UPDATE
+const updateResult = await cockroachdb.execute(
+  "UPDATE users SET last_login = now() WHERE id = $1",
+  [userId]
+);
+console.log(`Updated ${updateResult.rowCount} rows`);
+
+// DELETE
+const deleteResult = await cockroachdb.execute(
+  "DELETE FROM sessions WHERE expires_at < now()"
+);
+console.log(`Deleted ${deleteResult.rowCount} expired sessions`);
+```
+
+### Array Parameters
+
+CockroachDB supports PostgreSQL-style arrays:
+
+```typescript
+const items = await cockroachdb.query(
+  "SELECT * FROM items WHERE id = ANY($1)",
+  ItemSchema,
+  [[1, 2, 3]]
+);
+```
+
+## Common Pitfalls
+
+### UUID Primary Keys
+
+CockroachDB commonly uses UUIDs for primary keys:
+
+```typescript
+const schema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+});
+```
+
+### DECIMAL Values Returned as Strings
+
+```typescript
+const schema = z.object({
+  balance: z.string().transform((val) => parseFloat(val)),
+});
+```
+
+### Schema Parameter is Required
+
+```typescript
+// CORRECT - Schema is required
+const users = await cockroachdb.query("SELECT * FROM users", UserSchema);
+```
+
+### NULL Handling
+
+```typescript
+const schema = z.object({
+  name: z.string(),
+  bio: z.string().nullable(),
+});
+```
+
+## Error Handling
+
+```typescript
+import { QueryValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const users = await cockroachdb.query("SELECT * FROM users", UserSchema);
+} catch (error) {
+  if (error instanceof QueryValidationError) {
+    console.error("Row index:", error.details.rowIndex);
+    console.error("Validation errors:", error.details.errors);
+  }
+}
+```
+
+## API Reference
+
+- [CockroachDB Documentation](https://www.cockroachlabs.com/docs/)
+- [CockroachDB SQL Reference](https://www.cockroachlabs.com/docs/stable/sql-statements.html)
+- [CockroachDB Data Types](https://www.cockroachlabs.com/docs/stable/data-types.html)