@superblocksteam/sdk-api 0.0.5 → 0.0.7

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)