@superblocksteam/sdk-api 2.0.104 → 2.0.105-next.1

package/src/index.ts

@@ -38,10 +38,14 @@
  *       throw new Error('User not found');
  *     }
  *
- *     await ctx.integrations.notifier.postMessage({
- *       channel: '#user-lookups',
- *       text: `Fetched user ${user.name}`,
- *     });
+ *     const notifyResult = await ctx.integrations.notifier.apiRequest(
+ *       { method: 'POST', path: '/chat.postMessage', body: { channel: '#user-lookups', text: `Fetched user ${user.name}` } },
+ *       { response: z.object({ channel: z.string(), ts: z.string() }) }
+ *     );
+ *
+ *     if (!notifyResult.ok) {
+ *       throw new Error(`Slack API error: ${notifyResult.error}`);
+ *     }
  *
  *     return { user };
  *   },
@@ -129,20 +133,14 @@ export {
   mongodb,
   dynamodb,
   cosmosdb,
-  couchbase,
   s3,
   gcs,
   googleSheets,
-  kafka,
-  kinesis,
   salesforce,
   redis,
   superblocksOcr,
-  python,
   restApiIntegration,
   getIntegrationDeclarations,
-  confluent,
-  redpanda,
   lakebase,
   snowflakePostgres,
   smtp,
@@ -199,19 +197,13 @@ export {
   type MongoDBRef,
   type DynamoDBRef,
   type CosmosDBRef,
-  type CouchbaseRef,
   type S3Ref,
   type GCSRef,
   type GoogleSheetsRef,
-  type KafkaRef,
-  type KinesisRef,
   type SalesforceRef,
   type RedisRef,
   type SuperblocksOCRRef,
-  type PythonRef,
   type RestApiIntegrationRef,
-  type ConfluentRef,
-  type RedpandaRef,
   type LakebaseRef,
   type SnowflakePostgresRef,
   type SmtpRef,
@@ -219,7 +211,11 @@ export {
 
 // Integration client types (for advanced use cases)
 export type { PostgresClient } from "./integrations/postgres/index.js";
-export type { SlackClient } from "./integrations/slack/index.js";
+export type {
+  SlackClient,
+  SlackResponse,
+  SlackErrorResponse,
+} from "./integrations/slack/index.js";
 export type { SnowflakeClient } from "./integrations/snowflake/index.js";
 export type { SnowflakeCortexClient } from "./integrations/snowflakecortex/index.js";
 export type { AirtableClient } from "./integrations/airtable/index.js";
@@ -259,29 +255,16 @@ export type {
   DynamoDBAttributeValue,
 } from "./integrations/dynamodb/index.js";
 export type { CosmosDBClient } from "./integrations/cosmosdb/index.js";
-export type {
-  CouchbaseClient,
-  CouchbaseIdentifier,
-} from "./integrations/couchbase/index.js";
-export type {
-  KinesisClient,
-  KinesisPutParams,
-  KinesisGetParams,
-  KinesisStreamIdentifier,
-  KinesisShardIteratorType,
-} from "./integrations/kinesis/index.js";
 export type {
   SalesforceClient,
   SalesforceCrudAction,
   SalesforceBulkAction,
 } from "./integrations/salesforce/index.js";
 export type { RedisClient } from "./integrations/redis/index.js";
-export type { KafkaClient } from "./integrations/kafka/index.js";
 export type { S3Client } from "./integrations/s3/index.js";
 export type { GCSClient } from "./integrations/gcs/index.js";
 export type { GoogleSheetsClient } from "./integrations/gsheets/index.js";
 export type { SuperblocksOCRClient } from "./integrations/superblocks-ocr/index.js";
-export type { PythonClient } from "./integrations/python/index.js";
 export type { RestApiIntegrationPluginClient } from "./integrations/restapiintegration/index.js";
 export type { LakebaseClient } from "./integrations/lakebase/index.js";
 export type { SnowflakePostgresClient } from "./integrations/snowflakepostgres/index.js";

package/src/integrations/asana/README.md

@@ -49,7 +49,7 @@ export default api({
     const result = await ctx.integrations.asana.apiRequest(
       {
         method: "POST",
-        path: "/api/1.0/tasks",
+        path: "/tasks",
         body: {
           data: {
             name: name,
@@ -88,7 +88,7 @@ const ListTasksResponseSchema = z.object({
 const result = await ctx.integrations.asana.apiRequest(
   {
     method: "GET",
-    path: `/api/1.0/projects/${projectId}/tasks`,
+    path: `/projects/${projectId}/tasks`,
     params: {
       opt_fields: "name,completed,due_on,assignee.name",
       completed_since: "now", // Only incomplete tasks
@@ -108,7 +108,7 @@ result.data.forEach((task) => {
 const result = await ctx.integrations.asana.apiRequest(
   {
     method: "PUT",
-    path: `/api/1.0/tasks/${taskId}`,
+    path: `/tasks/${taskId}`,
     body: {
       data: {
         completed: true,
@@ -126,7 +126,7 @@ const result = await ctx.integrations.asana.apiRequest(
 const result = await ctx.integrations.asana.apiRequest(
   {
     method: "PUT",
-    path: `/api/1.0/tasks/${taskId}`,
+    path: `/tasks/${taskId}`,
     body: {
       data: {
         assignee: userId, // User GID
@@ -154,7 +154,7 @@ const ListProjectsResponseSchema = z.object({
 const result = await ctx.integrations.asana.apiRequest(
   {
     method: "GET",
-    path: "/api/1.0/projects",
+    path: "/projects",
     params: {
       workspace: workspaceId,
       opt_fields: "name,archived,owner.name",
@@ -178,7 +178,7 @@ const CreateProjectResponseSchema = z.object({
 const result = await ctx.integrations.asana.apiRequest(
   {
     method: "POST",
-    path: "/api/1.0/projects",
+    path: "/projects",
     body: {
       data: {
         name: "Q1 Marketing Campaign",
@@ -207,7 +207,7 @@ const StoryResponseSchema = z.object({
 const result = await ctx.integrations.asana.apiRequest(
   {
     method: "POST",
-    path: `/api/1.0/tasks/${taskId}/stories`,
+    path: `/tasks/${taskId}/stories`,
     body: {
       data: {
         text: "Great progress on this task!",
@@ -233,7 +233,7 @@ const SearchResponseSchema = z.object({
 const result = await ctx.integrations.asana.apiRequest(
   {
     method: "GET",
-    path: "/api/1.0/workspaces/{workspace_gid}/tasks/search",
+    path: "/workspaces/{workspace_gid}/tasks/search",
     params: {
       "text.value": "urgent",
       completed: false,
@@ -252,7 +252,7 @@ const result = await ctx.integrations.asana.apiRequest(
 const result = await ctx.integrations.asana.apiRequest(
   {
     method: "GET",
-    path: `/api/1.0/tasks/${taskId}/subtasks`,
+    path: `/tasks/${taskId}/subtasks`,
     params: {
       opt_fields: "name,completed,assignee.name",
     },
@@ -276,7 +276,7 @@ await asana.getTasks({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.asana.apiRequest(
-  { method: "POST", path: "/api/1.0/tasks", body: { data: { ... } } },
+  { method: "POST", path: "/tasks", body: { data: { ... } } },
   { response: CreateTaskResponseSchema }
 );
 ```
@@ -381,7 +381,7 @@ async function getAllTasks(asana: AsanaClient, projectId: string) {
     const result = await ctx.integrations.asana.apiRequest(
       {
         method: "GET",
-        path: `/api/1.0/projects/${projectId}/tasks`,
+        path: `/projects/${projectId}/tasks`,
         params: {
           limit: 100,
           ...(offset && { offset }),
@@ -405,7 +405,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.asana.apiRequest(
-    { method: "POST", path: "/api/1.0/tasks", body: { data: { ... } } },
+    { method: "POST", path: "/tasks", body: { data: { ... } } },
     { response: CreateTaskResponseSchema }
   );
 } catch (error) {

package/src/integrations/base/index.ts

@@ -2,8 +2,9 @@
  * Base clients for integrations.
  */
 
+export { RestApiClientBase } from "./rest-api-client-base.js";
 export { RestApiIntegrationClient } from "./rest-api-integration-client.js";
-export type { RestApiRequest } from "./rest-api-integration-client.js";
+export type { RestApiRequest } from "./rest-api-client-base.js";
 export { GraphQLIntegrationClient } from "./graphql-integration-client.js";
 export type {
   ApiRequestOptions,

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

@@ -0,0 +1,134 @@
+/**
+ * Abstract base for REST API Integration clients.
+ *
+ * Owns the shared infrastructure that every REST-API-backed integration
+ * needs: config storage, parameter helpers, body validation, request
+ * construction, and query execution. Subclasses add their own
+ * `apiRequest` with whatever response-handling strategy they need
+ * (e.g. direct Zod validation, discriminated-union wrapping).
+ */
+
+import type { PartialMessage } from "@bufbuild/protobuf";
+import { z } from "zod";
+
+import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
+import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/dist/src/plugins/restapiintegration/v1/plugin_pb";
+
+import { RestApiValidationError } from "../../errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { ApiRequestOptions } from "./types.js";
+
+export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
+
+/**
+ * Shared base for all REST API Integration clients.
+ *
+ * Provides config fields, parameter helpers, body validation, request
+ * building, and query execution. Does NOT define `apiRequest` — each
+ * concrete subclass supplies its own return-type contract.
+ */
+export abstract class RestApiClientBase implements IntegrationClientImpl {
+  readonly name: string;
+  readonly pluginId: string;
+  readonly config: IntegrationConfig;
+
+  protected readonly executeQuery: QueryExecutor;
+
+  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
+    this.name = config.name;
+    this.pluginId = config.pluginId;
+    this.config = config;
+    this.executeQuery = executeQuery;
+  }
+
+  /**
+   * Create a Property object for query params / headers.
+   */
+  protected createParam(key: string, value: unknown): PartialMessage<Property> {
+    return {
+      key,
+      value: typeof value === "string" ? value : JSON.stringify(value),
+    };
+  }
+
+  /**
+   * Validate the request body, build the proto request, and execute it.
+   *
+   * Returns the raw (unvalidated) response from the orchestrator.
+   * Subclasses call this, then apply their own response handling.
+   *
+   * @param options - HTTP method, path, body, params, headers
+   * @param bodySchema - Optional Zod schema for body validation
+   * @param metadata - Optional trace metadata for observability
+   * @returns Raw response from the orchestrator
+   */
+  protected async executeApiRequest<TBody>(
+    options: ApiRequestOptions<TBody>,
+    bodySchema?: z.ZodSchema<TBody>,
+    metadata?: TraceMetadata,
+  ): Promise<unknown> {
+    // Validate request body if both body and schema are present.
+    if (options.body !== undefined && bodySchema) {
+      const bodyParseResult = bodySchema.safeParse(options.body);
+      if (!bodyParseResult.success) {
+        throw new RestApiValidationError(
+          `Request body validation failed: ${bodyParseResult.error.message}`,
+          {
+            zodError: bodyParseResult.error,
+            data: options.body,
+          },
+        );
+      }
+    }
+
+    const headers: PartialMessage<Property>[] = [];
+    if (options.headers) {
+      for (const [key, value] of Object.entries(options.headers)) {
+        headers.push(this.createParam(key, value));
+      }
+    }
+
+    const params: PartialMessage<Property>[] = [];
+    if (options.params) {
+      for (const [key, value] of Object.entries(options.params)) {
+        params.push(this.createParam(key, value));
+      }
+    }
+
+    const request: RestApiRequest = {
+      openApiAction: "genericHttpRequest",
+      httpMethod: options.method.toUpperCase(),
+      urlPath: options.path,
+      headers,
+      params,
+      responseType: "json",
+    };
+
+    if (options.body !== undefined) {
+      request.body = JSON.stringify(options.body);
+      request.bodyType = "jsonBody";
+    }
+
+    const result = await this.executeQuery(
+      request as Record<string, unknown>,
+      undefined,
+      metadata,
+    );
+
+    if (result === null || result === undefined) {
+      const nonNullResult = z.object({}).safeParse(result);
+      if (!nonNullResult.success) {
+        throw new RestApiValidationError(
+          `Integration query returned ${String(result)} — expected a JSON response object`,
+          {
+            zodError: nonNullResult.error,
+            data: result,
+          },
+        );
+      }
+    }
+
+    return result;
+  }
+}

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

@@ -1,58 +1,33 @@
 /**
- * Base client for REST API Integration (OpenAPI) based integrations.
+ * Generic REST API Integration client with Zod response validation.
  *
- * Provides common apiRequest() method for all OpenAPI-based plugins.
+ * Extends RestApiClientBase with an apiRequest() that validates the
+ * full response against a caller-supplied Zod schema and throws
+ * RestApiValidationError on mismatch.
  */
 
-import type { PartialMessage } from "@bufbuild/protobuf";
 import type { z } from "zod";
 
-import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
-import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/dist/src/plugins/restapiintegration/v1/plugin_pb";
-
 import { RestApiValidationError } from "../../errors.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import type { TraceMetadata } from "../registry.js";
+import { RestApiClientBase } from "./rest-api-client-base.js";
 import type {
   ApiRequestOptions,
   ApiRequestSchema,
   SupportsApiRequest,
 } from "./types.js";
 
-export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
-
 /**
  * Base implementation for REST API Integration clients.
  *
- * All OpenAPI-based integration clients extend this class to inherit
- * the generic apiRequest() method with runtime schema validation.
+ * All OpenAPI-based integration clients (except those with
+ * integration-specific response handling) extend this class to
+ * inherit the generic apiRequest() method with runtime Zod validation.
  */
 export abstract class RestApiIntegrationClient
-  implements IntegrationClientImpl, SupportsApiRequest
+  extends RestApiClientBase
+  implements SupportsApiRequest
 {
-  readonly name: string;
-  readonly pluginId: string;
-  readonly config: IntegrationConfig;
-
-  protected readonly executeQuery: QueryExecutor;
-
-  constructor(config: IntegrationConfig, executeQuery: QueryExecutor) {
-    this.name = config.name;
-    this.pluginId = config.pluginId;
-    this.config = config;
-    this.executeQuery = executeQuery;
-  }
-
-  /**
-   * Helper to create a Property object for params.
-   */
-  protected createParam(key: string, value: unknown): PartialMessage<Property> {
-    return {
-      key,
-      value: typeof value === "string" ? value : JSON.stringify(value),
-    };
-  }
-
   async apiRequest<TBody, TResponse>(
     options: ApiRequestOptions<TBody>,
     schema: ApiRequestSchema<TBody, TResponse> & {
@@ -60,59 +35,7 @@ export abstract class RestApiIntegrationClient
     },
     metadata?: TraceMetadata,
   ): Promise<TResponse> {
-    // Validate request body against schema if both are present.
-    // Body schema is optional — if not provided, the body is sent unvalidated.
-    if (options.body !== undefined && schema?.body) {
-      const bodyParseResult = schema.body.safeParse(options.body);
-      if (!bodyParseResult.success) {
-        throw new RestApiValidationError(
-          `Request body validation failed: ${bodyParseResult.error.message}`,
-          {
-            zodError: bodyParseResult.error,
-            data: options.body,
-          },
-        );
-      }
-    }
-
-    // Convert headers to Property array
-    const headers: PartialMessage<Property>[] = [];
-    if (options.headers) {
-      for (const [key, value] of Object.entries(options.headers)) {
-        headers.push(this.createParam(key, value));
-      }
-    }
-
-    // Convert query params to Property array
-    const params: PartialMessage<Property>[] = [];
-    if (options.params) {
-      for (const [key, value] of Object.entries(options.params)) {
-        params.push(this.createParam(key, value));
-      }
-    }
-
-    // Build the request using raw HTTP mode
-    const request: RestApiRequest = {
-      openApiAction: "genericHttpRequest",
-      httpMethod: options.method.toUpperCase(),
-      urlPath: options.path,
-      headers,
-      params,
-      responseType: "json",
-    };
-
-    // Add body if provided
-    if (options.body !== undefined) {
-      request.body = JSON.stringify(options.body);
-      request.bodyType = "jsonBody";
-    }
-
-    // Execute the request
-    const result = await this.executeQuery(
-      request as Record<string, unknown>,
-      undefined,
-      metadata,
-    );
+    const result = await this.executeApiRequest(options, schema.body, metadata);
 
     // Response schema is REQUIRED - always validate
     const responseParseResult = schema.response.safeParse(result);

package/src/integrations/bitbucket/README.md

@@ -54,7 +54,7 @@ export default api({
     const result = await ctx.integrations.bitbucket.apiRequest(
       {
         method: "GET",
-        path: `/2.0/repositories/${workspace}`,
+        path: `/repositories/${workspace}`,
         params: {
           pagelen: 50,
         },
@@ -78,7 +78,7 @@ export default api({
 const repo = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repoSlug}`,
+    path: `/repositories/${workspace}/${repoSlug}`,
   },
   { response: RepositorySchema },
 );
@@ -111,7 +111,7 @@ const PullRequestSchema = z.object({
 const pr = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests`,
+    path: `/repositories/${workspace}/${repoSlug}/pullrequests`,
     body: {
       title: "Add new feature",
       description: "This PR adds...",
@@ -143,7 +143,7 @@ const ListPRsResponseSchema = z.object({
 const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests`,
+    path: `/repositories/${workspace}/${repoSlug}/pullrequests`,
     params: {
       state: "OPEN", // OPEN, MERGED, DECLINED, SUPERSEDED
       pagelen: 25,
@@ -172,7 +172,7 @@ const MergeResponseSchema = z.object({
 const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/merge`,
+    path: `/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/merge`,
     body: {
       type: "pullrequest",
       message: "Merge pull request #123",
@@ -209,7 +209,7 @@ const ListCommitsResponseSchema = z.object({
 const result = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/commits`,
+    path: `/repositories/${workspace}/${repoSlug}/commits`,
     params: {
       branch: "main",
       pagelen: 10,
@@ -232,7 +232,7 @@ const BranchSchema = z.object({
 const branch = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/refs/branches`,
+    path: `/repositories/${workspace}/${repoSlug}/refs/branches`,
     body: {
       name: "feature/new-feature",
       target: {
@@ -251,7 +251,7 @@ const branch = await ctx.integrations.bitbucket.apiRequest(
 const content = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/src/main/README.md`,
+    path: `/repositories/${workspace}/${repoSlug}/src/main/README.md`,
   },
   { response: z.string() },
 );
@@ -274,7 +274,7 @@ const CommentSchema = z.object({
 const comment = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "POST",
-    path: `/2.0/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/comments`,
+    path: `/repositories/${workspace}/${repoSlug}/pullrequests/${prId}/comments`,
     body: {
       content: {
         raw: "LGTM! :+1:",
@@ -300,20 +300,20 @@ await bitbucket.listRepos();
 
 // CORRECT - Use apiRequest
 await ctx.integrations.bitbucket.apiRequest(
-  { method: "POST", path: `/2.0/repositories/${workspace}/${repo}/pullrequests`, body: { ... } },
+  { method: "POST", path: `/repositories/${workspace}/${repo}/pullrequests`, body: { ... } },
   { response: PullRequestSchema }
 );
 ```
 
 ### API Version in Path
 
-Always include `/2.0/` prefix:
+The base URL already includes `/2.0`, so do not repeat it in paths:
 
 ```typescript
-// WRONG - Missing version
+// CORRECT - No version prefix (base URL already has /2.0)
 const path = `/repositories/${workspace}/${repo}`;
 
-// CORRECT - Include version
+// WRONG - Duplicates version from base URL
 const path = `/2.0/repositories/${workspace}/${repo}`;
 ```
 
@@ -323,10 +323,10 @@ Use workspace slug for API calls:
 
 ```typescript
 // Workspace slug (preferred)
-const path = `/2.0/repositories/myworkspace/myrepo`;
+const path = `/repositories/myworkspace/myrepo`;
 
 // Can also be username for personal repos
-const path = `/2.0/repositories/myusername/myrepo`;
+const path = `/repositories/myusername/myrepo`;
 ```
 
 ### Pagination
@@ -340,7 +340,7 @@ async function getAllPRs(
   repo: string,
 ) {
   const allPRs: PullRequest[] = [];
-  let url = `/2.0/repositories/${workspace}/${repo}/pullrequests`;
+  let url = `/repositories/${workspace}/${repo}/pullrequests`;
 
   while (url) {
     const result = await ctx.integrations.bitbucket.apiRequest(
@@ -385,7 +385,7 @@ Branch names with slashes need encoding:
 ```typescript
 // Branch name: feature/my-feature
 const branchName = encodeURIComponent("feature/my-feature");
-const path = `/2.0/repositories/${workspace}/${repo}/src/${branchName}/file.txt`;
+const path = `/repositories/${workspace}/${repo}/src/${branchName}/file.txt`;
 ```
 
 ### Raw File Content
@@ -397,7 +397,7 @@ File content endpoints return raw text, not JSON:
 const content = await ctx.integrations.bitbucket.apiRequest(
   {
     method: "GET",
-    path: `/2.0/repositories/${workspace}/${repo}/src/main/file.txt`,
+    path: `/repositories/${workspace}/${repo}/src/main/file.txt`,
   },
   { response: z.string() }, // Not a JSON schema
 );
@@ -410,7 +410,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.bitbucket.apiRequest(
-    { method: "GET", path: `/2.0/repositories/${workspace}/${repo}` },
+    { method: "GET", path: `/repositories/${workspace}/${repo}` },
     { response: RepositorySchema },
   );
 } catch (error) {