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

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) {

package/src/integrations/box/README.md

@@ -75,7 +75,7 @@ export default api({
     const result = await ctx.integrations.box.apiRequest(
       {
         method: "GET",
-        path: `/2.0/folders/${folderId}/items`,
+        path: `/folders/${folderId}/items`,
         params: {
           limit: limit,
           offset: 0,
@@ -133,7 +133,7 @@ const FileInfoSchema = z.object({
 const file = await ctx.integrations.box.apiRequest(
   {
     method: "GET",
-    path: `/2.0/files/${fileId}`,
+    path: `/files/${fileId}`,
     params: {
       fields:
         "id,name,size,created_at,modified_at,created_by,modified_by,parent,sha1,shared_link",
@@ -154,7 +154,7 @@ const DownloadUrlResponseSchema = z.string();
 const content = await ctx.integrations.box.apiRequest(
   {
     method: "GET",
-    path: `/2.0/files/${fileId}/content`,
+    path: `/files/${fileId}/content`,
   },
   { response: DownloadUrlResponseSchema },
 );
@@ -172,7 +172,7 @@ const UploadResponseSchema = z.object({
 const result = await ctx.integrations.box.apiRequest(
   {
     method: "POST",
-    path: "/2.0/files/content",
+    path: "/files/content",
     headers: {
       "Content-Type": "multipart/form-data",
     },
@@ -209,7 +209,7 @@ const FolderInfoSchema = z.object({
 const folder = await ctx.integrations.box.apiRequest(
   {
     method: "POST",
-    path: "/2.0/folders",
+    path: "/folders",
     body: {
       name: "New Folder",
       parent: {
@@ -229,7 +229,7 @@ console.log(`Created folder: ${folder.name} (${folder.id})`);
 const copiedFile = await ctx.integrations.box.apiRequest(
   {
     method: "POST",
-    path: `/2.0/files/${fileId}/copy`,
+    path: `/files/${fileId}/copy`,
     body: {
       parent: {
         id: destinationFolderId,
@@ -247,7 +247,7 @@ const copiedFile = await ctx.integrations.box.apiRequest(
 const movedFile = await ctx.integrations.box.apiRequest(
   {
     method: "PUT",
-    path: `/2.0/files/${fileId}`,
+    path: `/files/${fileId}`,
     body: {
       parent: {
         id: newParentFolderId,
@@ -264,7 +264,7 @@ const movedFile = await ctx.integrations.box.apiRequest(
 const updatedFile = await ctx.integrations.box.apiRequest(
   {
     method: "PUT",
-    path: `/2.0/files/${fileId}`,
+    path: `/files/${fileId}`,
     body: {
       name: "renamed-file.txt",
       description: "Updated file description",
@@ -281,7 +281,7 @@ const updatedFile = await ctx.integrations.box.apiRequest(
 await ctx.integrations.box.apiRequest(
   {
     method: "DELETE",
-    path: `/2.0/files/${fileId}`,
+    path: `/files/${fileId}`,
   },
   { response: z.void() },
 );
@@ -304,7 +304,7 @@ const SharedLinkSchema = z.object({
 const file = await ctx.integrations.box.apiRequest(
   {
     method: "PUT",
-    path: `/2.0/files/${fileId}`,
+    path: `/files/${fileId}`,
     params: {
       fields: "shared_link",
     },
@@ -337,7 +337,7 @@ const SearchResponseSchema = z.object({
 const result = await ctx.integrations.box.apiRequest(
   {
     method: "GET",
-    path: "/2.0/search",
+    path: "/search",
     params: {
       query: "quarterly report",
       type: "file",
@@ -372,7 +372,7 @@ const CommentSchema = z.object({
 const comment = await ctx.integrations.box.apiRequest(
   {
     method: "POST",
-    path: "/2.0/comments",
+    path: "/comments",
     body: {
       item: {
         type: "file",
@@ -400,22 +400,22 @@ await box.uploadFile({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.box.apiRequest(
-  { method: "GET", path: `/2.0/folders/${folderId}/items`, params: { ... } },
+  { method: "GET", path: `/folders/${folderId}/items`, params: { ... } },
   { response: ListItemsResponseSchema }
 );
 ```
 
 ### API Version in Path
 
-Box API paths include version:
+The base URL already includes `/2.0`, so do not repeat it in paths:
 
 ```typescript
-// CORRECT - Include version
-const path = "/2.0/files/123";
-const path = "/2.0/folders/0/items";
-
-// WRONG - Missing version
+// CORRECT - No version prefix (base URL already has /2.0)
 const path = "/files/123";
+const path = "/folders/0/items";
+
+// WRONG - Duplicates version from base URL
+const path = "/2.0/files/123";
 ```
 
 ### Root Folder ID is "0"
@@ -437,7 +437,7 @@ Use `fields` to get specific data:
 ```typescript
 // Without fields, you get minimal data
 const result = await ctx.integrations.box.apiRequest(
-  { method: "GET", path: `/2.0/files/${fileId}` },
+  { method: "GET", path: `/files/${fileId}` },
   { response: FileSchema },
 );
 
@@ -445,7 +445,7 @@ const result = await ctx.integrations.box.apiRequest(
 const result = await ctx.integrations.box.apiRequest(
   {
     method: "GET",
-    path: `/2.0/files/${fileId}`,
+    path: `/files/${fileId}`,
     params: {
       fields: "id,name,size,created_at,modified_at,parent,shared_link",
     },
@@ -477,7 +477,7 @@ Use `If-Match` with etag for safe updates:
 const result = await ctx.integrations.box.apiRequest(
   {
     method: "PUT",
-    path: `/2.0/files/${fileId}`,
+    path: `/files/${fileId}`,
     headers: {
       "If-Match": file.etag, // Prevents overwriting concurrent changes
     },
@@ -503,7 +503,7 @@ async function getAllItems(box: BoxClient, folderId: string) {
     const result = await ctx.integrations.box.apiRequest(
       {
         method: "GET",
-        path: `/2.0/folders/${folderId}/items`,
+        path: `/folders/${folderId}/items`,
         params: { limit, offset, fields: "id,name,type" },
       },
       { response: ListItemsResponseSchema },
@@ -557,7 +557,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.box.apiRequest(
-    { method: "GET", path: `/2.0/folders/${folderId}/items`, params: { ... } },
+    { method: "GET", path: `/folders/${folderId}/items`, params: { ... } },
     { response: ListItemsResponseSchema }
   );
 } catch (error) {

package/src/integrations/box/types.ts

@@ -24,7 +24,7 @@ import type { SupportsApiRequest } from "../base/index.js";
  * const result = await box.apiRequest(
  *   {
  *     method: 'GET',
- *     path: '/2.0/folders/0',
+ *     path: '/folders/0',
  *   },
  *   { response: ResponseSchema }
  * );

package/src/integrations/circleci/README.md

@@ -51,7 +51,7 @@ export default api({
     const result = await ctx.integrations.circleci.apiRequest(
       {
         method: "POST",
-        path: `/api/v2/project/${projectSlug}/pipeline`,
+        path: `/project/${projectSlug}/pipeline`,
         body: {
           branch: branch,
           parameters: {
@@ -73,7 +73,7 @@ export default api({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/pipeline/${pipelineId}`,
+    path: `/pipeline/${pipelineId}`,
   },
   { response: PipelineSchema },
 );
@@ -102,7 +102,7 @@ const ListWorkflowsResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/pipeline/${pipelineId}/workflow`,
+    path: `/pipeline/${pipelineId}/workflow`,
   },
   { response: ListWorkflowsResponseSchema },
 );
@@ -133,7 +133,7 @@ const ListJobsResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/workflow/${workflowId}/job`,
+    path: `/workflow/${workflowId}/job`,
   },
   { response: ListJobsResponseSchema },
 );
@@ -162,7 +162,7 @@ const JobDetailSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/project/${projectSlug}/job/${jobNumber}`,
+    path: `/project/${projectSlug}/job/${jobNumber}`,
   },
   { response: JobDetailSchema },
 );
@@ -178,7 +178,7 @@ const RetryResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
-    path: `/api/v2/workflow/${workflowId}/rerun`,
+    path: `/workflow/${workflowId}/rerun`,
     body: {
       from_failed: true, // Only rerun failed jobs
     },
@@ -199,7 +199,7 @@ const CancelResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
-    path: `/api/v2/workflow/${workflowId}/cancel`,
+    path: `/workflow/${workflowId}/cancel`,
   },
   { response: CancelResponseSchema },
 );
@@ -216,7 +216,7 @@ const ListPipelinesResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/project/${projectSlug}/pipeline`,
+    path: `/project/${projectSlug}/pipeline`,
     params: {
       branch: "main",
       "page-token": undefined, // For pagination
@@ -247,7 +247,7 @@ const ProjectSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/project/${projectSlug}`,
+    path: `/project/${projectSlug}`,
   },
   { response: ProjectSchema },
 );
@@ -270,7 +270,7 @@ const ListArtifactsResponseSchema = z.object({
 const result = await ctx.integrations.circleci.apiRequest(
   {
     method: "GET",
-    path: `/api/v2/project/${projectSlug}/${jobNumber}/artifacts`,
+    path: `/project/${projectSlug}/${jobNumber}/artifacts`,
   },
   { response: ListArtifactsResponseSchema },
 );
@@ -295,7 +295,7 @@ await circleci.getWorkflow({ ... });
 
 // CORRECT - Use apiRequest
 await ctx.integrations.circleci.apiRequest(
-  { method: "POST", path: `/api/v2/project/${slug}/pipeline`, body: { ... } },
+  { method: "POST", path: `/project/${slug}/pipeline`, body: { ... } },
   { response: PipelineSchema }
 );
 ```
@@ -317,13 +317,13 @@ const slug = "gl/my-group/my-repo";
 
 ### API Version in Path
 
-Always include `/api/v2/`:
+The base URL already includes `/api/v2`, so do not repeat it in paths:
 
 ```typescript
-// WRONG
+// CORRECT - No version prefix (base URL already has /api/v2)
 const path = `/project/${slug}/pipeline`;
 
-// CORRECT
+// WRONG - Duplicates version from base URL
 const path = `/api/v2/project/${slug}/pipeline`;
 ```
 
@@ -406,7 +406,7 @@ async function getAllPipelines(circleci: CircleCIClient, projectSlug: string) {
     const result = await ctx.integrations.circleci.apiRequest(
       {
         method: "GET",
-        path: `/api/v2/project/${projectSlug}/pipeline`,
+        path: `/project/${projectSlug}/pipeline`,
         params: pageToken ? { "page-token": pageToken } : {},
       },
       { response: ListPipelinesResponseSchema },
@@ -429,7 +429,7 @@ When rerunning workflows:
 await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
-    path: `/api/v2/workflow/${workflowId}/rerun`,
+    path: `/workflow/${workflowId}/rerun`,
     body: {
       from_failed: false, // Rerun everything
     },
@@ -441,7 +441,7 @@ await ctx.integrations.circleci.apiRequest(
 await ctx.integrations.circleci.apiRequest(
   {
     method: "POST",
-    path: `/api/v2/workflow/${workflowId}/rerun`,
+    path: `/workflow/${workflowId}/rerun`,
     body: {
       from_failed: true, // Only failed jobs
     },
@@ -457,7 +457,7 @@ import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.circleci.apiRequest(
-    { method: "POST", path: `/api/v2/project/${slug}/pipeline`, body: { ... } },
+    { method: "POST", path: `/project/${slug}/pipeline`, body: { ... } },
     { response: PipelineSchema }
   );
 } catch (error) {