@superblocksteam/sdk-api 0.0.6 → 0.0.8

package/src/integrations/restapiintegration/overlays/response-types.md

@@ -0,0 +1,26 @@
+## Non-JSON Responses
+
+`apiRequest()` decodes responses as JSON by default. For endpoints that return non-JSON payloads (XML, CSV, HTML, plain text), pass `responseType: "text"` to receive the decoded body as a string.
+
+With `responseType: "text"` the response schema may be omitted — the raw string is returned typed `unknown`:
+
+```typescript
+const xml = await ctx.integrations.legacyApi.apiRequest({
+  method: "GET",
+  path: "/report.xml",
+  responseType: "text",
+});
+// xml is the raw XML string (typed unknown)
+```
+
+To get a typed string instead, validate with a schema matching the decoded value:
+
+```typescript
+const xml = await ctx.integrations.legacyApi.apiRequest(
+  { method: "GET", path: "/report.xml", responseType: "text" },
+  { response: z.string() },
+);
+// xml is typed string
+```
+
+JSON responses (the default) always require a response schema. Omitting the schema is only allowed together with an explicit `responseType: "text"`, so unvalidated JSON is not representable.

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": []
+}

package/src/integrations/slack/README.md

@@ -16,7 +16,6 @@ Send messages, manage channels, and interact with Slack workspaces.
 import { api, z, slack } from "@superblocksteam/sdk-api";
 
 const PostMessageResponseSchema = z.object({
-  ok: z.boolean(),
   channel: z.string(),
   ts: z.string(), // Message timestamp (unique ID)
   message: z.object({
@@ -55,6 +54,10 @@ export default api({
       { response: PostMessageResponseSchema },
     );
 
+    if (!result.ok) {
+      throw new Error(`Slack API error: ${result.error}`);
+    }
+
     return { messageId: result.ts };
   },
 });
@@ -106,7 +109,6 @@ const result = await ctx.integrations.slack.apiRequest(
 
 ```typescript
 const ListChannelsResponseSchema = z.object({
-  ok: z.boolean(),
   channels: z.array(
     z.object({
       id: z.string(),
@@ -135,6 +137,10 @@ const result = await ctx.integrations.slack.apiRequest(
   { response: ListChannelsResponseSchema },
 );
 
+if (!result.ok) {
+  throw new Error(`Slack API error: ${result.error}`);
+}
+
 result.channels.forEach((channel) => {
   console.log(`#${channel.name} (${channel.id})`);
 });
@@ -144,7 +150,6 @@ result.channels.forEach((channel) => {
 
 ```typescript
 const UserInfoResponseSchema = z.object({
-  ok: z.boolean(),
   user: z.object({
     id: z.string(),
     name: z.string(),
@@ -167,6 +172,10 @@ const result = await ctx.integrations.slack.apiRequest(
   { response: UserInfoResponseSchema },
 );
 
+if (!result.ok) {
+  throw new Error(`Slack API error: ${result.error}`);
+}
+
 console.log(`User: ${result.user.real_name} (${result.user.profile.email})`);
 ```
 
@@ -174,7 +183,6 @@ console.log(`User: ${result.user.real_name} (${result.user.profile.email})`);
 
 ```typescript
 const FileUploadResponseSchema = z.object({
-  ok: z.boolean(),
   file: z.object({
     id: z.string(),
     name: z.string(),
@@ -197,6 +205,10 @@ const result = await ctx.integrations.slack.apiRequest(
   { response: FileUploadResponseSchema },
 );
 
+if (!result.ok) {
+  throw new Error(`Slack API error: ${result.error}`);
+}
+
 console.log(`File uploaded: ${result.file.permalink}`);
 ```
 
@@ -221,7 +233,6 @@ const result = await ctx.integrations.slack.apiRequest(
 
 ```typescript
 const UpdateMessageResponseSchema = z.object({
-  ok: z.boolean(),
   channel: z.string(),
   ts: z.string(),
   text: z.string(),
@@ -333,6 +344,10 @@ async function getAllChannels(slack: SlackClient) {
       { response: ListChannelsResponseSchema },
     );
 
+    if (!result.ok) {
+      throw new Error(`Slack API error: ${result.error}`);
+    }
+
     allChannels.push(...result.channels);
     cursor = result.response_metadata?.next_cursor;
   } while (cursor);
@@ -371,30 +386,58 @@ Code block
 
 ## Error Handling
 
+Slack returns API errors as HTTP 200 with `{ ok: false, error: "error_code" }` instead of HTTP error status codes. The SDK surfaces these as the `SlackErrorResponse` branch of a discriminated union (`SlackResponse<T>`) — no exceptions, just check `result.ok`:
+
 ```typescript
-import { RestApiValidationError } from "@superblocksteam/sdk-api";
+import type { SlackResponse } from "@superblocksteam/sdk-api";
+
+const result = await ctx.integrations.slack.apiRequest(
+  { method: "POST", path: "/chat.postMessage", body: { channel, text } },
+  { response: PostMessageResponseSchema },
+);
 
-try {
-  const result = await ctx.integrations.slack.apiRequest(
-    { method: "POST", path: "/chat.postMessage", body: { ... } },
-    { response: PostMessageResponseSchema }
-  );
+if (!result.ok) {
+  // TypeScript narrows to SlackErrorResponse
+  console.error(`Slack error: ${result.error}`);
+  //              e.g. "missing_scope", "channel_not_found", "not_authed"
 
-  // Slack returns ok: false for API errors (not HTTP errors)
-  if (!result.ok) {
-    console.error("Slack API error");
-  }
-} catch (error) {
-  if (error instanceof RestApiValidationError) {
-    console.error("Validation failed:", error.details.zodError);
+  if (result.needed) {
+    console.error(`Required scopes: ${result.needed}`);
+    // e.g. "chat:write"
   }
+  return;
 }
+
+// TypeScript narrows to T & { ok: true } — all success fields accessible
+console.log(`Sent message: ${result.ts}`);
 ```
 
+### SlackResponse\<T\>
+
+Every `apiRequest` call returns `SlackResponse<T>`, a discriminated union:
+
+| Branch  | Shape                | When                                                                       |
+| ------- | -------------------- | -------------------------------------------------------------------------- |
+| Success | `T & { ok: true }`   | Slack returned `ok: true`; response validated against your Zod schema      |
+| Error   | `SlackErrorResponse` | Slack returned `ok: false`; contains `error`, optional `needed`/`provided` |
+
+`T` is your payload schema output. Define payload fields only (do not include `ok` in your response schema) and the SDK injects `ok: true` for the discriminant on success.
+
+**`SlackErrorResponse` fields:**
+
+| Field      | Type      | Description                                                  |
+| ---------- | --------- | ------------------------------------------------------------ |
+| `ok`       | `false`   | Discriminant                                                 |
+| `error`    | `string`  | Slack error code (e.g. `missing_scope`, `channel_not_found`) |
+| `needed`   | `string?` | Required OAuth scopes (present on `missing_scope` errors)    |
+| `provided` | `string?` | Current token scopes (present on `missing_scope` errors)     |
+
+Schema validation errors (Zod mismatch on a _success_ response) still throw `RestApiValidationError`. Body validation errors also throw. Only Slack's own `ok: false` errors are returned as values.
+
 ## API Reference
 
 - [Slack API Documentation](https://api.slack.com/methods)
 - [chat.postMessage](https://api.slack.com/methods/chat.postMessage)
 - [conversations.list](https://api.slack.com/methods/conversations.list)
-- [Block Kit Builder](https://app.slack.com/block-kit-builder)
 - [OAuth Scopes](https://api.slack.com/scopes)
+- [Block Kit Builder](https://app.slack.com/block-kit-builder)