@superblocksteam/sdk-api 2.0.102 → 2.0.103-next.0

package/src/integrations/registry.ts

@@ -5,17 +5,8 @@
  * and provides factory functions for creating clients.
  */
 
-import type { IntegrationConfig, IntegrationClientImpl } from "./types.js";
-import { PostgresClientImpl } from "./postgres/index.js";
-import { SlackClientImpl } from "./slack/index.js";
-import { OpenAIClientImpl } from "./openai_v2/index.js";
-import { AnthropicClientImpl } from "./anthropic/index.js";
-import { StripeClientImpl } from "./stripe/index.js";
-import { GitHubClientImpl } from "./github/index.js";
-import { NotionClientImpl } from "./notion/index.js";
-import { SnowflakeClientImpl } from "./snowflake/index.js";
-import { SnowflakeCortexClientImpl } from "./snowflakecortex/index.js";
 import { AirtableClientImpl } from "./airtable/index.js";
+import { AnthropicClientImpl } from "./anthropic/index.js";
 import { AsanaClientImpl } from "./asana/index.js";
 import { BitbucketClientImpl } from "./bitbucket/index.js";
 import { BoxClientImpl } from "./box/index.js";
@@ -28,49 +19,58 @@ import { ElasticSearchClientImpl } from "./elasticsearch/index.js";
 import { FireworksClientImpl } from "./fireworks/index.js";
 import { FrontClientImpl } from "./front/index.js";
 import { GeminiClientImpl } from "./gemini/index.js";
+import { GitHubClientImpl } from "./github/index.js";
 import { GoogleAnalyticsClientImpl } from "./googleanalytics/index.js";
 import { GoogleDriveClientImpl } from "./googledrive/index.js";
+import { GraphQLClientImpl } from "./graphql/index.js";
 import { GroqClientImpl } from "./groq/index.js";
 import { HubSpotClientImpl } from "./hubspot/index.js";
 import { IntercomClientImpl } from "./intercom/index.js";
 import { JiraClientImpl } from "./jira/index.js";
 import { LaunchDarklyClientImpl } from "./launchdarkly/index.js";
 import { MistralClientImpl } from "./mistral/index.js";
+import { NotionClientImpl } from "./notion/index.js";
+import { OpenAIClientImpl } from "./openai_v2/index.js";
 import { PagerDutyClientImpl } from "./pagerduty/index.js";
 import { PerplexityClientImpl } from "./perplexity/index.js";
+import { PostgresClientImpl } from "./postgres/index.js";
 import { SegmentClientImpl } from "./segment/index.js";
 import { SendGridClientImpl } from "./sendgrid/index.js";
+import { SlackClientImpl } from "./slack/index.js";
+import { SnowflakeClientImpl } from "./snowflake/index.js";
+import { SnowflakeCortexClientImpl } from "./snowflakecortex/index.js";
 import { StabilityAIClientImpl } from "./stabilityai/index.js";
+import { StripeClientImpl } from "./stripe/index.js";
 import { TwilioClientImpl } from "./twilio/index.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "./types.js";
 import { ZendeskClientImpl } from "./zendesk/index.js";
 import { ZoomClientImpl } from "./zoom/index.js";
-import { GraphQLClientImpl } from "./graphql/index.js";
 // SQL Database clients
-import { MySQLClientImpl } from "./mysql/index.js";
+import { AthenaClientImpl } from "./athena/index.js";
+import { BigQueryClientImpl } from "./bigquery/index.js";
+import { CockroachDBClientImpl } from "./cockroachdb/index.js";
+import { DatabricksClientImpl } from "./databricks/index.js";
 import { MariaDBClientImpl } from "./mariadb/index.js";
 import { MSSQLClientImpl } from "./mssql/index.js";
-import { CockroachDBClientImpl } from "./cockroachdb/index.js";
+import { MySQLClientImpl } from "./mysql/index.js";
 import { OracleDBClientImpl } from "./oracledb/index.js";
 import { RedshiftClientImpl } from "./redshift/index.js";
-import { AthenaClientImpl } from "./athena/index.js";
-import { DatabricksClientImpl } from "./databricks/index.js";
-import { BigQueryClientImpl } from "./bigquery/index.js";
 // REST API clients
-import { MongoDBClientImpl } from "./mongodb/index.js";
-import { DynamoDBClientImpl } from "./dynamodb/index.js";
 import { CosmosDBClientImpl } from "./cosmosdb/index.js";
 import { CouchbaseClientImpl } from "./couchbase/index.js";
-import { S3ClientImpl } from "./s3/index.js";
+import { DynamoDBClientImpl } from "./dynamodb/index.js";
 import { GCSClientImpl } from "./gcs/index.js";
 import { GoogleSheetsClientImpl } from "./gsheets/index.js";
 import { KafkaClientImpl } from "./kafka/index.js";
 import { KinesisClientImpl } from "./kinesis/index.js";
-import { SalesforceClientImpl } from "./salesforce/index.js";
-import { RedisClientImpl } from "./redis/index.js";
-import { SuperblocksOCRClientImpl } from "./superblocks-ocr/index.js";
 import { LakebaseClientImpl } from "./lakebase/index.js";
-import { SnowflakePostgresClientImpl } from "./snowflakepostgres/index.js";
+import { MongoDBClientImpl } from "./mongodb/index.js";
+import { RedisClientImpl } from "./redis/index.js";
+import { S3ClientImpl } from "./s3/index.js";
+import { SalesforceClientImpl } from "./salesforce/index.js";
 import { SmtpClientImpl } from "./smtp/index.js";
+import { SnowflakePostgresClientImpl } from "./snowflakepostgres/index.js";
+import { SuperblocksOCRClientImpl } from "./superblocks-ocr/index.js";
 // REST API plugins
 import { RestApiIntegrationPluginClientImpl } from "./restapiintegration/index.js";
 // Code execution clients

package/src/integrations/restapiintegration/README.md

@@ -0,0 +1,359 @@
+# REST API Integration Client
+
+Make HTTP requests to any REST API configured with a base URL and authentication in the integrations page.
+
+This is the generic REST API Integration plugin. Unlike named integrations (Slack, GitHub, etc.) which target a specific service, this plugin works with **any** HTTP API you configure as an integration.
+
+## Methods
+
+| Method                                         | Description                                      |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `apiRequest(options, schema, metadata?)`       | Make any HTTP request with schema validation     |
+| `streamApiRequest(options, schema, metadata?)` | Stream responses with real-time chunk validation |
+
+## Usage
+
+### Basic GET Request
+
+```typescript
+import { api, z, restApiIntegration } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const MY_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const UsersResponseSchema = z.object({
+  users: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string(),
+    }),
+  ),
+});
+
+export default api({
+  name: "FetchUsers",
+  integrations: {
+    myApi: restApiIntegration(MY_API),
+  },
+  input: z.object({}),
+  output: z.object({
+    users: z.array(
+      z.object({ id: z.string(), name: z.string(), email: z.string() }),
+    ),
+  }),
+  async run(ctx) {
+    const result = await ctx.integrations.myApi.apiRequest(
+      {
+        method: "GET",
+        path: "/users",
+        params: { limit: 50 },
+      },
+      { response: UsersResponseSchema },
+    );
+
+    return { users: result.users };
+  },
+});
+```
+
+### POST Request with Body
+
+```typescript
+const CreateRecordSchema = z.object({
+  id: z.string(),
+  created_at: z.string(),
+});
+
+const record = await ctx.integrations.myApi.apiRequest(
+  {
+    method: "POST",
+    path: "/records",
+    body: {
+      title: "New Record",
+      description: "Created via Superblocks",
+      tags: ["automated"],
+    },
+    headers: {
+      "Content-Type": "application/json",
+    },
+  },
+  { response: CreateRecordSchema },
+);
+
+console.log(`Created record: ${record.id}`);
+```
+
+### PATCH/PUT Request
+
+```typescript
+const UpdateResponseSchema = z.object({
+  id: z.string(),
+  updated_at: z.string(),
+});
+
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "PATCH",
+    path: `/records/${recordId}`,
+    body: {
+      title: "Updated Title",
+      status: "published",
+    },
+    headers: {
+      "Content-Type": "application/json",
+    },
+  },
+  { response: UpdateResponseSchema },
+);
+```
+
+### DELETE Request
+
+```typescript
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "DELETE",
+    path: `/records/${recordId}`,
+  },
+  { response: z.object({}).passthrough() },
+);
+```
+
+### Search with Query Parameters
+
+```typescript
+const SearchResponseSchema = z.object({
+  items: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      score: z.number().optional(),
+    }),
+  ),
+  total: z.number(),
+});
+
+const results = await ctx.integrations.myApi.apiRequest(
+  {
+    method: "GET",
+    path: "/search",
+    params: {
+      q: "my query",
+      page: 1,
+      per_page: 25,
+    },
+  },
+  { response: SearchResponseSchema },
+);
+
+console.log(`Found ${results.total} results`);
+```
+
+### Using Multiple Integrations
+
+You can use multiple REST API Integrations in a single API, each targeting a different service:
+
+```typescript
+import { api, z, restApiIntegration, postgres } from "@superblocksteam/sdk-api";
+
+const EXTERNAL_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
+const INTERNAL_API = "e5f6a7b8-9012-34cd-ef56-222222222222";
+const MY_DB = "c3d4e5f6-7890-12ab-cdef-333333333333";
+
+export default api({
+  name: "SyncData",
+  integrations: {
+    externalApi: restApiIntegration(EXTERNAL_API),
+    internalApi: restApiIntegration(INTERNAL_API),
+    db: postgres(MY_DB),
+  },
+  input: z.object({ query: z.string() }),
+  output: z.object({ synced: z.number() }),
+  async run(ctx, { query }) {
+    // Fetch from external API
+    const external = await ctx.integrations.externalApi.apiRequest(
+      { method: "GET", path: "/data", params: { q: query } },
+      { response: z.object({ items: z.array(z.unknown()) }) },
+    );
+
+    // Push to internal API
+    await ctx.integrations.internalApi.apiRequest(
+      { method: "POST", path: "/import", body: { items: external.items } },
+      { response: z.object({ imported: z.number() }) },
+    );
+
+    return { synced: external.items.length };
+  },
+});
+```
+
+### Streaming Responses
+
+For APIs that return streaming data (e.g., Server-Sent Events), use `streamApiRequest()`:
+
+```typescript
+import { streamingApi, z, restApiIntegration } from "@superblocksteam/sdk-api";
+
+const MY_API = "a1b2c3d4-5678-90ab-cdef-111111111111";
+
+const StreamChunkSchema = z.object({
+  id: z.string(),
+  data: z.string(),
+});
+
+export default streamingApi({
+  integrations: {
+    myApi: restApiIntegration(MY_API),
+  },
+  input: z.object({ prompt: z.string() }),
+  chunk: z.object({ text: z.string() }),
+
+  async *run(ctx, { prompt }) {
+    const stream = ctx.integrations.myApi.streamApiRequest(
+      {
+        method: "POST",
+        path: "/stream",
+        body: { prompt },
+      },
+      { chunk: StreamChunkSchema },
+    );
+
+    for await (const chunk of stream) {
+      yield { text: chunk.data };
+    }
+  },
+});
+```
+
+## 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.
+
+```typescript
+const result = await ctx.integrations.myApi.apiRequest(
+  { method: "GET", path: "/users" },
+  { response: UsersResponseSchema },
+  { label: "myApi.getUsers", description: "Fetch all active users" },
+);
+```
+
+## Common Pitfalls
+
+### No `.request()` Method
+
+The only public methods are `apiRequest()` and `streamApiRequest()`. There is no `.request()` method:
+
+```typescript
+// WRONG - .request() does not exist
+await ctx.integrations.myApi.request({
+  method: "GET",
+  path: "/users",
+});
+
+// CORRECT - Use apiRequest with a response schema
+await ctx.integrations.myApi.apiRequest(
+  { method: "GET", path: "/users" },
+  { response: UsersResponseSchema },
+);
+```
+
+### Response Schema is Required
+
+`apiRequest()` requires a response schema for type safety:
+
+```typescript
+// WRONG - Missing response schema
+const result = await ctx.integrations.myApi.apiRequest({
+  method: "GET",
+  path: "/users",
+});
+
+// CORRECT - Provide a response schema
+const result = await ctx.integrations.myApi.apiRequest(
+  { method: "GET", path: "/users" },
+  { response: z.object({ users: z.array(z.unknown()) }) },
+);
+```
+
+### Use `body` Instead of `JSON.stringify`
+
+The `body` field is automatically serialized. Do not stringify it manually:
+
+```typescript
+// WRONG - Manual stringify
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "POST",
+    path: "/records",
+    body: JSON.stringify({ title: "New" }),
+  },
+  { response: ResponseSchema },
+);
+
+// CORRECT - Pass object directly
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "POST",
+    path: "/records",
+    body: { title: "New" },
+  },
+  { response: ResponseSchema },
+);
+```
+
+### Use `params` for Query Parameters
+
+Query parameters go in the `params` field, not in the URL path:
+
+```typescript
+// WRONG - Query params in path
+await ctx.integrations.myApi.apiRequest(
+  { method: "GET", path: "/search?q=hello&limit=10" },
+  { response: ResponseSchema },
+);
+
+// CORRECT - Use params field
+await ctx.integrations.myApi.apiRequest(
+  {
+    method: "GET",
+    path: "/search",
+    params: { q: "hello", limit: 10 },
+  },
+  { response: ResponseSchema },
+);
+```
+
+### Use `.passthrough()` for Flexible Schemas
+
+When the response contains fields you don't need to validate, use `.passthrough()`:
+
+```typescript
+// Strict schema - will reject unknown fields
+const StrictSchema = z.object({ id: z.string() });
+
+// Flexible schema - allows additional fields
+const FlexibleSchema = z.object({ id: z.string() }).passthrough();
+
+// For dynamic responses
+const GenericSchema = z.record(z.unknown());
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.myApi.apiRequest(
+    { method: "GET", path: "/users" },
+    { response: UsersResponseSchema },
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    // Response didn't match the schema
+    console.error("Validation failed:", error.details.zodError);
+    console.error("Actual response:", error.details.data);
+  }
+}
+```

package/src/integrations/s3/client.ts

@@ -4,13 +4,15 @@
  * Uses the native S3 plugin type from @superblocksteam/types.
  */
 
-import type { z } from "zod";
 import type { PartialMessage } from "@bufbuild/protobuf";
+import type { z } from "zod";
+
 import type { Plugin as S3Plugin } from "@superblocksteam/types/dist/src/plugins/s3/v1/plugin_pb";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { RestApiValidationError } from "../../errors.js";
 import { IntegrationError } from "../../runtime/errors.js";
+import type { QueryExecutor, TraceMetadata } from "../registry.js";
+import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
 import type {
   S3Client,
   S3Action,

package/src/integrations/s3/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";
 
@@ -129,7 +130,9 @@ export interface S3Client extends BaseIntegrationClient {
    *
    * @param bucket - Bucket name
    * @param path - Object key/path
-   * @param body - File content (base64 or text)
+   * @param body - String content stored verbatim (no base64 decoding is performed).
+   *   Suitable for plain text, JSON, or CSV. For binary files (PDF, DOCX, images),
+   *   use {@link S3Client.uploadMultipleObjects | uploadMultipleObjects} with file references instead.
    * @param metadata - Optional trace metadata for diagnostics
    */
   uploadObject(

package/src/integrations/salesforce/client.ts

@@ -6,10 +6,11 @@
  */
 
 import type { z } from "zod";
-import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
-import type { QueryExecutor, TraceMetadata } from "../registry.js";
+
 import { QueryValidationError, RestApiValidationError } 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 { SalesforceClient } from "./types.js";
 

package/src/integrations/salesforce/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { z } from "zod";
+
 import type { BaseIntegrationClient } from "../../types.js";
 import type { TraceMetadata } from "../registry.js";