@superblocksteam/sdk-api 0.0.5 → 0.0.7

package/src/integrations/restapiintegration/README.md

@@ -0,0 +1,320 @@
+# 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 |
+
+## 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 };
+  },
+});
+```
+
+## 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 method is `apiRequest()`. 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/restapiintegration/docs.manifest.json

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

package/src/integrations/restapiintegration/types.ts

@@ -3,10 +3,7 @@
  */
 
 import type { BaseIntegrationClient } from "../../types.js";
-import type {
-  SupportsApiRequest,
-  SupportsStreamingApiRequest,
-} from "../base/index.js";
+import type { SupportsApiRequest } from "../base/index.js";
 
 /**
  * REST API Integration client for making HTTP requests to configured endpoints.
@@ -34,7 +31,4 @@ import type {
  * ```
  */
 export interface RestApiIntegrationPluginClient
-  extends
-    BaseIntegrationClient,
-    SupportsApiRequest,
-    SupportsStreamingApiRequest {}
+  extends BaseIntegrationClient, SupportsApiRequest {}

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

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

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/README.md

@@ -77,7 +77,7 @@ const opportunities = await ctx.integrations.salesforce.query(
 ### Create a Record
 
 ```typescript
-await salesforce.create("Account", {
+await ctx.integrations.salesforce.create("Account", {
   Name: "Acme Corp",
   Industry: "Technology",
   Website: "https://acme.example.com",
@@ -87,7 +87,7 @@ await salesforce.create("Account", {
 ### Read a Record by ID
 
 ```typescript
-const account = await salesforce.read(
+const account = await ctx.integrations.salesforce.read(
   "Account",
   "001xx000003DGb2AAG",
   z.object({
@@ -101,7 +101,7 @@ const account = await salesforce.read(
 ### Update a Record
 
 ```typescript
-await salesforce.update("Account", "001xx000003DGb2AAG", {
+await ctx.integrations.salesforce.update("Account", "001xx000003DGb2AAG", {
   Name: "Acme Corp (Updated)",
   Industry: "Software",
 });
@@ -116,7 +116,7 @@ await ctx.integrations.salesforce.remove("Account", "001xx000003DGb2AAG");
 ### Bulk Create
 
 ```typescript
-await salesforce.bulkCreate("Contact", [
+await ctx.integrations.salesforce.bulkCreate("Contact", [
   { FirstName: "Alice", LastName: "Smith", Email: "alice@example.com" },
   { FirstName: "Bob", LastName: "Jones", Email: "bob@example.com" },
   { FirstName: "Charlie", LastName: "Lee", Email: "charlie@example.com" },
@@ -126,7 +126,7 @@ await salesforce.bulkCreate("Contact", [
 ### Bulk Update
 
 ```typescript
-await salesforce.bulkUpdate("Contact", [
+await ctx.integrations.salesforce.bulkUpdate("Contact", [
   { Id: "003xx000004TmiQAAS", Email: "alice-new@example.com" },
   { Id: "003xx000004TmiRAAS", Email: "bob-new@example.com" },
 ]);
@@ -135,7 +135,7 @@ await salesforce.bulkUpdate("Contact", [
 ### Bulk Delete
 
 ```typescript
-await salesforce.bulkDelete("Contact", [
+await ctx.integrations.salesforce.bulkDelete("Contact", [
   { Id: "003xx000004TmiQAAS" },
   { Id: "003xx000004TmiRAAS" },
 ]);
@@ -144,7 +144,7 @@ await salesforce.bulkDelete("Contact", [
 ### Bulk Upsert
 
 ```typescript
-await salesforce.bulkUpsert(
+await ctx.integrations.salesforce.bulkUpsert(
   "Account",
   [
     { ExternalId__c: "EXT-001", Name: "Acme Corp", Industry: "Tech" },
@@ -198,12 +198,14 @@ Bulk update and delete records must include the `Id` field:
 
 ```typescript
 // CORRECT
-await salesforce.bulkUpdate("Contact", [
+await ctx.integrations.salesforce.bulkUpdate("Contact", [
   { Id: "003xx000004TmiQAAS", Email: "new@example.com" },
 ]);
 
 // WRONG - Missing Id field
-await salesforce.bulkUpdate("Contact", [{ Email: "new@example.com" }]);
+await ctx.integrations.salesforce.bulkUpdate("Contact", [
+  { Email: "new@example.com" },
+]);
 ```
 
 ## Error Handling

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

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

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

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

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

package/src/integrations/sendgrid/README.md

@@ -13,7 +13,7 @@ Send transactional emails, manage contacts, and interact with SendGrid's email A
 ### Send a Simple Email
 
 ```typescript
-import { api, z, sendgrid } from "@superblocksteam/sdk-api";
+import { api, z, sendGrid } from "@superblocksteam/sdk-api";
 
 // Integration ID from the integrations panel
 const PROD_SENDGRID = "a1b2c3d4-5678-90ab-cdef-sendgrid0001";
@@ -23,7 +23,7 @@ const SendEmailResponseSchema = z.object({}).optional();
 
 export default api({
   integrations: {
-    sendgrid: sendgrid(PROD_SENDGRID),
+    sendgrid: sendGrid(PROD_SENDGRID),
   },
   name: "SendGridExample",
   input: z.object({

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

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