@superblocksteam/sdk-api 2.0.105 → 2.0.106-next.1

package/src/integrations/mongodb/README.md

@@ -79,16 +79,21 @@ const UserSchema = z
     name: z.string(),
     email: z.string(),
   })
-  .nullable();
+  .nullable()
+  .optional();
 
 const user = await ctx.integrations.mongodb.run(
   "users",
   "findOne",
   UserSchema,
   {
-    query: { _id: userId },
+    query: { _id: { $oid: userId } },
   },
 );
+
+// findOne returns undefined (not null) when no document matches,
+// so use .nullable().optional() and coalesce if needed:
+const result = user ?? null;
 ```
 
 ### Insert Document
@@ -116,8 +121,8 @@ const result = await ctx.integrations.mongodb.run(
 
 ```typescript
 const UpdateResultSchema = z.object({
-  matchedCount: z.number(),
-  modifiedCount: z.number(),
+  matchedCount: z.coerce.number(),
+  modifiedCount: z.coerce.number(),
 });
 
 const result = await ctx.integrations.mongodb.run(
@@ -125,7 +130,7 @@ const result = await ctx.integrations.mongodb.run(
   "updateOne",
   UpdateResultSchema,
   {
-    filter: { _id: userId },
+    filter: { _id: { $oid: userId } },
     update: {
       $set: { status: "active", updatedAt: new Date().toISOString() },
     },
@@ -137,7 +142,7 @@ const result = await ctx.integrations.mongodb.run(
 
 ```typescript
 const DeleteResultSchema = z.object({
-  deletedCount: z.number(),
+  deletedCount: z.coerce.number(),
 });
 
 const result = await ctx.integrations.mongodb.run(
@@ -145,7 +150,7 @@ const result = await ctx.integrations.mongodb.run(
   "deleteOne",
   DeleteResultSchema,
   {
-    filter: { _id: userId },
+    filter: { _id: { $oid: userId } },
   },
 );
 ```
@@ -156,8 +161,8 @@ const result = await ctx.integrations.mongodb.run(
 const AggregateResultSchema = z.array(
   z.object({
     _id: z.string(),
-    count: z.number(),
-    totalAmount: z.number(),
+    count: z.coerce.number(),
+    totalAmount: z.coerce.number(),
   }),
 );
 
@@ -183,9 +188,14 @@ const result = await ctx.integrations.mongodb.run(
 ### Count Documents
 
 ```typescript
-const count = await ctx.integrations.mongodb.run("users", "count", z.number(), {
-  query: { status: "active" },
-});
+const count = await ctx.integrations.mongodb.run(
+  "users",
+  "count",
+  z.coerce.number(),
+  {
+    query: { status: "active" },
+  },
+);
 ```
 
 ### Find with Projection and Sort
@@ -245,6 +255,49 @@ try {
 }
 ```
 
+## Gotchas
+
+### Numeric fields are returned as strings
+
+MongoDB numeric values (e.g. `int32`, `int64`, `double`) are returned as strings by the integration. Using `z.number()` in your schema will fail with `"Expected number, received string"`. Use `z.coerce.number()` instead to automatically convert string values to numbers:
+
+```typescript
+// ❌ Will fail — MongoDB returns numbers as strings
+const Schema = z.object({ rating: z.number() });
+
+// ✅ Correct — coerces string values to numbers
+const Schema = z.object({ rating: z.coerce.number() });
+```
+
+### ObjectId fields require `$oid` syntax
+
+When querying by `_id` or any ObjectId field, passing a plain string does not match. You must wrap the value using MongoDB Extended JSON `$oid` syntax:
+
+```typescript
+// ❌ Will not match — returns null/undefined
+const bad = { query: { _id: userId } };
+
+// ✅ Correct — uses Extended JSON $oid wrapper
+const good = { query: { _id: { $oid: userId } } };
+```
+
+This applies to `findOne`, `updateOne`, `deleteOne`, and any operation filtering by ObjectId fields.
+
+### `findOne` returns `undefined` when no document matches
+
+When no document is found, `findOne` returns `undefined` rather than `null`. If your schema uses only `.nullable()`, Zod will reject `undefined` with `"Expected object, received undefined"`. Use `.nullable().optional()` to handle both cases:
+
+```typescript
+// ❌ Will fail when no document matches
+const Schema = z.object({ name: z.string() }).nullable();
+
+// ✅ Correct — handles both null and undefined
+const Schema = z.object({ name: z.string() }).nullable().optional();
+
+// Coalesce to null if needed
+const result = (await ctx.integrations.mongodb.run(...)) ?? null;
+```
+
 ## API Reference
 
 - [MongoDB Manual](https://www.mongodb.com/docs/manual/)

package/src/integrations/perplexity/README.md

@@ -58,7 +58,7 @@ export default api({
         method: "POST",
         path: "/chat/completions",
         body: {
-          model: "llama-3.1-sonar-large-128k-online",
+          model: "sonar-pro",
           messages: [
             {
               role: "system",
@@ -82,40 +82,40 @@ export default api({
 ### Using Different Models
 
 ```typescript
-// Online models - With real-time search
-const onlineResult = await ctx.integrations.perplexity.apiRequest(
+// Standard search model - Fast, lightweight
+const result = await ctx.integrations.perplexity.apiRequest(
   {
     method: "POST",
     path: "/chat/completions",
     body: {
-      model: "llama-3.1-sonar-large-128k-online", // Real-time search
+      model: "sonar", // Fast search
       messages: [{ role: "user", content: "What's the latest news about AI?" }],
     },
   },
   { response: ChatCompletionResponseSchema },
 );
 
-// Chat models - Without search, faster
-const chatResult = await ctx.integrations.perplexity.apiRequest(
+// Pro search model - Deeper content understanding
+const proResult = await ctx.integrations.perplexity.apiRequest(
   {
     method: "POST",
     path: "/chat/completions",
     body: {
-      model: "llama-3.1-sonar-large-128k-chat", // No search
+      model: "sonar-pro", // Advanced search
       messages: [{ role: "user", content: "Explain quantum computing" }],
     },
   },
   { response: ChatCompletionResponseSchema },
 );
 
-// Small models - Faster, lower cost
-const smallResult = await ctx.integrations.perplexity.apiRequest(
+// Reasoning model - Multi-step Chain-of-Thought
+const reasoningResult = await ctx.integrations.perplexity.apiRequest(
   {
     method: "POST",
     path: "/chat/completions",
     body: {
-      model: "llama-3.1-sonar-small-128k-online",
-      messages: [{ role: "user", content: "Quick fact check..." }],
+      model: "sonar-reasoning-pro",
+      messages: [{ role: "user", content: "Analyze the pros and cons of..." }],
     },
   },
   { response: ChatCompletionResponseSchema },
@@ -130,7 +130,7 @@ const result = await ctx.integrations.perplexity.apiRequest(
     method: "POST",
     path: "/chat/completions",
     body: {
-      model: "llama-3.1-sonar-large-128k-online",
+      model: "sonar-pro",
       messages: [
         {
           role: "user",
@@ -152,7 +152,7 @@ const result = await ctx.integrations.perplexity.apiRequest(
     method: "POST",
     path: "/chat/completions",
     body: {
-      model: "llama-3.1-sonar-large-128k-online",
+      model: "sonar-pro",
       messages: [
         { role: "user", content: "Recent developments in electric vehicles" },
       ],
@@ -171,7 +171,7 @@ const result = await ctx.integrations.perplexity.apiRequest(
     method: "POST",
     path: "/chat/completions",
     body: {
-      model: "llama-3.1-sonar-large-128k-online",
+      model: "sonar",
       messages: [
         { role: "user", content: "What is the capital of France?" },
         { role: "assistant", content: "The capital of France is Paris." },
@@ -203,16 +203,22 @@ await ctx.integrations.perplexity.apiRequest(
 );
 ```
 
-### Online vs Chat Models
+### Model Selection
 
-Online models perform real-time search, chat models don't:
+Choose the right model for your use case:
 
 ```typescript
-// For questions requiring current information
-const model = "llama-3.1-sonar-large-128k-online";
+// For quick answers with web search
+const model = "sonar";
+
+// For complex queries requiring deeper understanding
+const model = "sonar-pro";
 
-// For general knowledge (faster, no search)
-const model = "llama-3.1-sonar-large-128k-chat";
+// For multi-step reasoning tasks
+const model = "sonar-reasoning-pro";
+
+// For in-depth research
+const model = "sonar-deep-research";
 ```
 
 ### Citations May Be Empty
@@ -229,47 +235,32 @@ if (sources.length === 0) {
 }
 ```
 
-### Model Naming Convention
+### Available Models
 
-Perplexity models follow a specific naming pattern. Note that available models change over time — check the [Perplexity model cards](https://docs.perplexity.ai/docs/model-cards) for current options:
+Perplexity offers the following Sonar models. Check the [Perplexity models page](https://docs.perplexity.ai/docs/sonar/models) for the latest options:
 
 ```typescript
-// Pattern: llama-3.1-sonar-{size}-{context}-{type}
-// These are examples — verify current model names in the Perplexity docs
 const models = [
-  "llama-3.1-sonar-small-128k-online", // Small, online search
-  "llama-3.1-sonar-small-128k-chat", // Small, no search
-  "llama-3.1-sonar-large-128k-online", // Large, online search
-  "llama-3.1-sonar-large-128k-chat", // Large, no search
+  "sonar", // Fast, lightweight search
+  "sonar-pro", // Advanced search with deeper understanding
+  "sonar-reasoning-pro", // Multi-step Chain-of-Thought reasoning
+  "sonar-deep-research", // In-depth research for complex queries
 ];
 ```
 
-### Search Parameters Only Work with Online Models
+### Search Parameters
 
-```typescript
-// WRONG - search_domain_filter with chat model
-await ctx.integrations.perplexity.apiRequest(
-  {
-    method: "POST",
-    path: "/chat/completions",
-    body: {
-      model: "llama-3.1-sonar-large-128k-chat", // Chat model
-      messages: [...],
-      search_domain_filter: ["example.com"], // Ignored!
-    },
-  },
-  { response: schema }
-);
+All Sonar models support search by default. You can use search filters to refine results:
 
-// CORRECT - search_domain_filter with online model
+```typescript
 await ctx.integrations.perplexity.apiRequest(
   {
     method: "POST",
     path: "/chat/completions",
     body: {
-      model: "llama-3.1-sonar-large-128k-online", // Online model
+      model: "sonar-pro",
       messages: [...],
-      search_domain_filter: ["example.com"], // Works!
+      search_domain_filter: ["example.com"], // Limit search to specific domains
     },
   },
   { response: schema }
@@ -296,5 +287,5 @@ try {
 ## API Reference
 
 - [Perplexity API Documentation](https://docs.perplexity.ai/)
-- [Chat Completions](https://docs.perplexity.ai/reference/post_chat_completions)
-- [Models](https://docs.perplexity.ai/docs/model-cards)
+- [Sonar API](https://docs.perplexity.ai/api-reference/sonar-post)
+- [Models](https://docs.perplexity.ai/docs/sonar/models)

package/src/integrations/registry.ts

@@ -57,15 +57,11 @@ import { OracleDBClientImpl } from "./oracledb/index.js";
 import { RedshiftClientImpl } from "./redshift/index.js";
 // REST API clients
 import { CosmosDBClientImpl } from "./cosmosdb/index.js";
-import { CouchbaseClientImpl } from "./couchbase/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 { LakebaseClientImpl } from "./lakebase/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";
@@ -73,8 +69,6 @@ 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
-import { PythonClientImpl } from "./python/index.js";
 
 /**
  * Supported plugin IDs mapped to their client constructors.
@@ -133,18 +127,11 @@ export const SUPPORTED_PLUGINS = {
   mongodb: "mongodb",
   dynamodb: "dynamodb",
   cosmosdb: "cosmosdb",
-  couchbase: "couchbase",
   s3: "s3",
   gcs: "gcs",
   gsheets: "gsheets",
-  kafka: "kafka",
-  kinesis: "kinesis",
   salesforce: "salesforce",
-  redis: "redis",
   "superblocks-ocr": "superblocks-ocr",
-  // Kafka-compatible streaming
-  confluent: "confluent",
-  redpanda: "redpanda",
   // SQL databases (continued)
   lakebase: "lakebase",
   snowflakepostgres: "snowflakepostgres",
@@ -152,8 +139,6 @@ export const SUPPORTED_PLUGINS = {
   smtp: "smtp",
   // REST API plugins
   restapiintegration: "restapiintegration",
-  // Code execution
-  python: "python",
 } as const;
 
 export type SupportedPluginId =
@@ -183,11 +168,8 @@ export interface TraceMetadata {
  * Accepts a plugin request object that matches the protobuf Plugin definition
  * for the specific integration type (e.g., postgresql.v1.Plugin, restapi.v1.Plugin).
  *
- * For language plugins (Python, JavaScript), the bindings parameter should be passed
- * to the API execution request as `input` or `inputs` field for binding resolution.
- *
  * @param request - Plugin-specific request object matching the proto schema
- * @param bindings - Optional bindings data for binding resolution (e.g., Python/JavaScript bindings)
+ * @param bindings - Optional bindings data for binding resolution
  * @param metadata - Optional trace metadata (label, description) for diagnostics
  * @returns Promise resolving to the operation result
  */
@@ -392,9 +374,6 @@ export function createClient(
     case SUPPORTED_PLUGINS.cosmosdb:
       return new CosmosDBClientImpl(config, executeQuery);
 
-    case SUPPORTED_PLUGINS.couchbase:
-      return new CouchbaseClientImpl(config, executeQuery);
-
     case SUPPORTED_PLUGINS.s3:
       return new S3ClientImpl(config, executeQuery);
 
@@ -404,26 +383,12 @@ export function createClient(
     case SUPPORTED_PLUGINS.gsheets:
       return new GoogleSheetsClientImpl(config, executeQuery);
 
-    case SUPPORTED_PLUGINS.kafka:
-      return new KafkaClientImpl(config, executeQuery);
-
-    case SUPPORTED_PLUGINS.kinesis:
-      return new KinesisClientImpl(config, executeQuery);
-
     case SUPPORTED_PLUGINS.salesforce:
       return new SalesforceClientImpl(config, executeQuery);
 
-    case SUPPORTED_PLUGINS.redis:
-      return new RedisClientImpl(config, executeQuery);
-
     case SUPPORTED_PLUGINS["superblocks-ocr"]:
       return new SuperblocksOCRClientImpl(config, executeQuery);
 
-    // Confluent and Redpanda use the same Kafka plugin proto
-    case SUPPORTED_PLUGINS.confluent:
-    case SUPPORTED_PLUGINS.redpanda:
-      return new KafkaClientImpl(config, executeQuery);
-
     case SUPPORTED_PLUGINS.lakebase:
       return new LakebaseClientImpl(config, executeQuery);
 
@@ -436,9 +401,6 @@ export function createClient(
     case SUPPORTED_PLUGINS.restapiintegration:
       return new RestApiIntegrationPluginClientImpl(config, executeQuery);
 
-    case SUPPORTED_PLUGINS.python:
-      return new PythonClientImpl(config, executeQuery);
-
     default:
       throw new Error(
         `Unsupported plugin: ${config.pluginId}. ` +

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