@superblocksteam/sdk-api 0.0.6 → 0.0.8

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 };
  *   },
@@ -59,16 +63,7 @@ export { fileRefSchema, readableFileSchema } from "./files.js";
 export type { FileRef, ReadableFile } from "./files.js";
 
 // API definition and registry
-export {
-  api,
-  __setEntryPoint,
-  type CompiledApi,
-  // Streaming API support
-  streamingApi,
-  isStreamingApi,
-  type StreamingApiConfig,
-  type CompiledStreamingApi,
-} from "./api/index.js";
+export { api, __setEntryPoint, type CompiledApi } from "./api/index.js";
 
 // Type extraction utilities
 export type { ExtractApiInput, ExtractApiOutput } from "./api/definition.js";
@@ -138,20 +133,13 @@ export {
   mongodb,
   dynamodb,
   cosmosdb,
-  couchbase,
   s3,
   gcs,
   googleSheets,
-  kafka,
-  kinesis,
   salesforce,
-  redis,
   superblocksOcr,
-  python,
   restApiIntegration,
   getIntegrationDeclarations,
-  confluent,
-  redpanda,
   lakebase,
   snowflakePostgres,
   smtp,
@@ -208,19 +196,12 @@ 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,
@@ -228,7 +209,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";
@@ -268,29 +253,15 @@ 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";
@@ -298,15 +269,10 @@ export type { SmtpClient, SmtpSendOptions } from "./integrations/smtp/index.js";
 
 // Runtime (for orchestrator use)
 export {
-  // Unified executor (recommended - handles both regular and streaming)
-  execute,
-  // Legacy executors (still available for specific use cases)
+  // Executor
   executeApi,
-  executeStreamingApi,
-  createStreamingApiGenerator,
   // Context factories
   createApiContext,
-  createStreamingApiContext,
   // Error types
   SdkError,
   InputValidationError,
@@ -318,21 +284,12 @@ export {
 } from "./runtime/index.js";
 
 export type {
-  // Unified types (recommended)
-  UnifiedExecuteApiRequest,
-  AnyCompiledApi,
-  // Legacy types (still available)
   ExecuteApiRequest,
   ExecuteApiResponse,
   ExecuteApiSuccessResponse,
   ExecuteApiErrorResponse,
-  ExecuteStreamingApiRequest,
-  StreamingApiCallbacks,
-  StreamingApiError,
-  ExecuteStreamingApiResult,
   // Context types
   CreateContextOptions,
-  CreateStreamingContextOptions,
   ErrorCodeType,
 } from "./runtime/index.js";
 
@@ -341,6 +298,7 @@ export {
   createClient,
   isPluginSupported,
   SUPPORTED_PLUGINS,
+  SUPPORTED_PLUGIN_IDS,
 } from "./integrations/index.js";
 
 export type {
@@ -348,16 +306,17 @@ export type {
   IntegrationClientImpl,
   SupportedPluginId,
   QueryExecutor,
-  StreamingQueryExecutor,
   TraceMetadata,
   CreateClientOptions,
 } from "./integrations/index.js";
 
+// resolveIntegrationDocumentation is intentionally NOT re-exported here.
+// It uses node:fs which is incompatible with browser bundles (Vite dev server).
+// Import directly from "@superblocksteam/sdk-api/dist/integrations/documentation.js" instead.
+
 // SDK-level error types
 export {
   RestApiValidationError,
   QueryValidationError,
   CodeExecutionError,
-  StreamChunkValidationError,
-  StreamError,
 } from "./errors.js";

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

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

package/src/integrations/anthropic/README.md

@@ -4,10 +4,9 @@ Interact with Anthropic's Claude API for powerful AI conversations and text gene
 
 ## Methods
 
-| Method                                         | Description                                           |
-| ---------------------------------------------- | ----------------------------------------------------- |
-| `apiRequest(options, schema, metadata?)`       | Make any Anthropic API request with schema validation |
-| `streamApiRequest(options, schema, metadata?)` | Stream responses with real-time chunk validation      |
+| Method                                   | Description                                           |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Anthropic API request with schema validation |
 
 ## Usage
 
@@ -242,89 +241,6 @@ const result = await ctx.integrations.ai.apiRequest(
 );
 ```
 
-### Streaming Messages
-
-For real-time token streaming, use `streamApiRequest()` with `stream: true`:
-
-```typescript
-import { streamingApi, z, anthropic } from "@superblocksteam/sdk-api";
-
-// Integration ID from the integrations panel
-const PROD_ANTHROPIC = "a1b2c3d4-5678-90ab-cdef-444444444444";
-
-// Schema for Anthropic's streaming SSE events
-const AnthropicStreamEventSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("content_block_delta"),
-    index: z.number(),
-    delta: z.object({
-      type: z.literal("text_delta"),
-      text: z.string(),
-    }),
-  }),
-  z.object({ type: z.literal("message_start"), message: z.any() }),
-  z.object({
-    type: z.literal("content_block_start"),
-    index: z.number(),
-    content_block: z.any(),
-  }),
-  z.object({ type: z.literal("content_block_stop"), index: z.number() }),
-  z.object({
-    type: z.literal("message_delta"),
-    delta: z.any(),
-    usage: z.any(),
-  }),
-  z.object({ type: z.literal("message_stop") }),
-  z.object({ type: z.literal("ping") }),
-]);
-
-export default streamingApi({
-  integrations: {
-    ai: anthropic(PROD_ANTHROPIC),
-  },
-
-  input: z.object({ prompt: z.string() }),
-  chunk: z.object({ type: z.literal("text"), text: z.string() }),
-
-  async *run(ctx, { prompt }) {
-    const stream = ctx.integrations.ai.streamApiRequest(
-      {
-        method: "POST",
-        path: "/v1/messages",
-        body: {
-          model: "claude-3-5-sonnet-20241022",
-          max_tokens: 1024,
-          stream: true, // Enable streaming
-          messages: [{ role: "user", content: prompt }],
-        },
-      },
-      { chunk: AnthropicStreamEventSchema },
-    );
-
-    // Yield text chunks as they arrive
-    for await (const event of stream) {
-      if (event.type === "content_block_delta") {
-        yield { type: "text" as const, text: event.delta.text };
-      }
-    }
-  },
-});
-```
-
-#### Streaming Event Types
-
-Claude's streaming API sends these event types:
-
-| Event Type            | Description                                 |
-| --------------------- | ------------------------------------------- |
-| `message_start`       | Initial message metadata (model, id, usage) |
-| `content_block_start` | Start of a content block (text, tool_use)   |
-| `content_block_delta` | Incremental text or tool input              |
-| `content_block_stop`  | End of a content block                      |
-| `message_delta`       | Final message metadata (stop_reason, usage) |
-| `message_stop`        | Stream complete                             |
-| `ping`                | Keep-alive ping                             |
-
 ## Trace Metadata
 
 All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
@@ -333,7 +249,7 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ### No Specialized Methods
 
-The Anthropic client only provides `apiRequest()`:
+The Anthropic client only provides `apiRequest()`. There are no other specialized methods:
 
 ```typescript
 // WRONG - These methods do not exist
@@ -474,7 +390,7 @@ const result = await ctx.integrations.ai.apiRequest(
 ## Error Handling
 
 ```typescript
-import { RestApiValidationError, StreamChunkValidationError } from "@superblocksteam/sdk-api";
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
 
 try {
   const result = await ctx.integrations.ai.apiRequest(
@@ -487,18 +403,6 @@ try {
     console.error("Actual response:", error.details.data);
   }
 }
-
-// For streaming requests
-try {
-  for await (const chunk of stream) {
-    // Process chunk
-  }
-} catch (error) {
-  if (error instanceof StreamChunkValidationError) {
-    console.error("Chunk validation failed at index:", error.details.chunkIndex);
-    console.error("Raw chunk:", error.details.chunk);
-  }
-}
 ```
 
 ## API Reference

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

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

package/src/integrations/anthropic/types.ts

@@ -3,16 +3,12 @@
  */
 
 import type { BaseIntegrationClient } from "../../types.js";
-import type {
-  SupportsApiRequest,
-  SupportsStreamingApiRequest,
-} from "../base/index.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * Anthropic client for Claude AI model interactions.
  *
- * Provides the generic apiRequest() method for any Anthropic API endpoint,
- * and streamApiRequest() for streaming responses.
+ * Provides the generic apiRequest() method for any Anthropic API endpoint.
  * Use this to interact with Anthropic's messages API and other endpoints.
  *
  * @example
@@ -58,31 +54,9 @@ import type {
  *   }
  * );
  *
- * // Or use streaming for real-time responses
- * const stream = anthropic.streamApiRequest(
- *   {
- *     method: 'POST',
- *     path: '/v1/messages',
- *     body: {
- *       model: 'claude-3-5-sonnet-20241022',
- *       max_tokens: 1024,
- *       stream: true,
- *       messages: [{ role: 'user', content: 'Hello!' }],
- *     },
- *   },
- *   { chunk: StreamEventSchema }
- * );
- *
- * for await (const event of stream) {
- *   // Handle streaming events
- * }
  * ```
  */
 export interface AnthropicClient
-  extends
-    BaseIntegrationClient,
-    SupportsApiRequest,
-    SupportsStreamingApiRequest {
+  extends BaseIntegrationClient, SupportsApiRequest {
   // apiRequest() method inherited from SupportsApiRequest
-  // streamApiRequest() method inherited from SupportsStreamingApiRequest
 }

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