@superblocksteam/sdk-api 0.0.5 → 0.0.7

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/asana/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "asana",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/athena/README.md

@@ -41,7 +41,7 @@ export default api({
     const logs = await ctx.integrations.athena.query(
       `SELECT timestamp, level, message, request_id
        FROM logs
-       WHERE level = $1
+       WHERE level = ?
        LIMIT 100`,
       LogSchema,
       [level],
@@ -65,8 +65,8 @@ const EventSchema = z.object({
 const events = await ctx.integrations.athena.query(
   `SELECT event_id, event_type, user_id, created_at
    FROM events
-   WHERE date_partition = $1
-     AND event_type = $2`,
+   WHERE date_partition = ?
+     AND event_type = ?`,
   EventSchema,
   ["2024-01-15", "purchase"],
 );
@@ -138,7 +138,7 @@ Always use partition filters when possible to reduce data scanned:
 ```typescript
 // GOOD - Uses partition filter
 const logs = await ctx.integrations.athena.query(
-  "SELECT * FROM logs WHERE date_partition = $1",
+  "SELECT * FROM logs WHERE date_partition = ?",
   LogSchema,
   ["2024-01-15"],
 );

package/src/integrations/athena/client.ts

@@ -5,13 +5,15 @@
  * runtime validation using Zod schemas.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as AthenaPlugin } from "@superblocksteam/types/dist/src/plugins/athena/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import { describeType } from "../utils.js";
 import type { AthenaClient } from "./types.js";
 

package/src/integrations/athena/docs.manifest.json

@@ -0,0 +1,5 @@
+{
+  "pluginId": "athena",
+  "base": "README.md",
+  "overlays": []
+}

package/src/integrations/athena/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
@@ -24,7 +25,7 @@ import type { TraceMetadata } from "../registry.js";
  * });
  *
  * const logs = await athena.query(
- *   'SELECT * FROM logs WHERE level = $1',
+ *   'SELECT * FROM logs WHERE level = ?',
  *   LogSchema,
  *   ['ERROR']
  * );
@@ -34,7 +35,7 @@ export interface AthenaClient extends BaseIntegrationClient {
   /**
    * Execute a SQL query and validate results against a Zod schema.
    *
-   * @param sql - SQL query string (use $1, $2, etc. for parameters)
+   * @param sql - SQL query string (use ? placeholders for parameters)
    * @param schema - Zod schema to validate the query results
    * @param params - Optional query parameters
    * @returns Promise resolving to validated query results

package/src/integrations/base/graphql-integration-client.ts

@@ -5,10 +5,14 @@
  * Handles proto message construction and response validation.
  */
 
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { PartialMessage } from "@bufbuild/protobuf";
 import { z } from "zod";
+
+import type { Property } from "@superblocksteam/types/dist/src/common/v1/plugin_pb";
+
 import { RestApiValidationError } from "../../errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 
 /**
  * Base class for GraphQL integration clients.
@@ -18,6 +22,8 @@ import { RestApiValidationError } from "../../errors.js";
  * - Executing queries and mutations through the orchestrator
  * - Required Zod schema validation on full GraphQL response
  * - Variables serialization for parameterized queries
+ * - Optional per-request HTTP headers (in addition to any headers configured
+ *   on the integration)
  */
 export abstract class GraphQLIntegrationClient implements IntegrationClientImpl {
   readonly name: string;
@@ -39,6 +45,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
    * @param schema - Zod schema for full response validation (REQUIRED)
    * @param variables - Optional variables for the query
    * @param metadata - Optional trace metadata for observability
+   * @param headers - Optional HTTP headers to send with the request
    * @returns Validated query result
    */
   async query<TResponse>(
@@ -46,8 +53,9 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
     metadata?: TraceMetadata,
+    headers?: Record<string, string>,
   ): Promise<TResponse> {
-    return this.executeGraphQL(query, schema, variables, metadata);
+    return this.executeGraphQL(query, schema, variables, metadata, headers);
   }
 
   /**
@@ -57,6 +65,7 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
    * @param schema - Zod schema for full response validation (REQUIRED)
    * @param variables - Optional variables for the mutation
    * @param metadata - Optional trace metadata for observability
+   * @param headers - Optional HTTP headers to send with the request
    * @returns Validated mutation result
    */
   async mutation<TResponse>(
@@ -64,8 +73,9 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
     metadata?: TraceMetadata,
+    headers?: Record<string, string>,
   ): Promise<TResponse> {
-    return this.executeGraphQL(mutation, schema, variables, metadata);
+    return this.executeGraphQL(mutation, schema, variables, metadata, headers);
   }
 
   /**
@@ -79,9 +89,17 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
     schema: { response: z.ZodSchema<TResponse> },
     variables?: Record<string, unknown>,
     metadata?: TraceMetadata,
+    headers?: Record<string, string>,
   ): Promise<TResponse> {
+    const headerProps: PartialMessage<Property>[] = [];
+    if (headers) {
+      for (const [key, value] of Object.entries(headers)) {
+        headerProps.push({ key, value });
+      }
+    }
+
     // Build graphql.v1.Plugin proto message
-    const request = {
+    const request: Record<string, unknown> = {
       body: queryString,
       custom: variables
         ? {
@@ -95,6 +113,10 @@ export abstract class GraphQLIntegrationClient implements IntegrationClientImpl
       failOnGraphqlErrors: true,
     };
 
+    if (headerProps.length > 0) {
+      request.headers = headerProps;
+    }
+
     // Execute query through orchestrator
     const response = await this.executeQuery(request, undefined, metadata);
 

package/src/integrations/base/index.ts

@@ -2,13 +2,12 @@
  * 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,
   ApiRequestSchema,
   SupportsApiRequest,
-  StreamApiRequestSchema,
-  SupportsStreamingApiRequest,
 } from "./types.js";

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;
+  }
+}