@superblocksteam/sdk-api 2.0.157 → 2.0.158

package/src/integrations/base/decode-worker-binary-response.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+
+import { RestApiValidationError } from "../../errors.js";
+import { decodeWorkerBinaryResponse } from "./decode-worker-binary-response.js";
+
+describe("decodeWorkerBinaryResponse", () => {
+  it("copies a Uint8Array into a plain Uint8Array with the same bytes", () => {
+    const source = new Uint8Array([1, 2, 255]);
+
+    const result = decodeWorkerBinaryResponse(source);
+
+    expect(result).toBeInstanceOf(Uint8Array);
+    expect(result.constructor).toBe(Uint8Array);
+    expect(Array.from(result)).toEqual([1, 2, 255]);
+    source[0] = 9;
+    expect(result[0]).toBe(1);
+  });
+
+  it("converts worker Buffer JSON into a plain Uint8Array", () => {
+    const result = decodeWorkerBinaryResponse({
+      type: "Buffer",
+      data: [37, 80, 68, 70],
+    });
+
+    expect(result.constructor).toBe(Uint8Array);
+    expect(Array.from(result)).toEqual([37, 80, 68, 70]);
+  });
+
+  it("converts empty Buffer JSON into a zero-length Uint8Array", () => {
+    const result = decodeWorkerBinaryResponse({ type: "Buffer", data: [] });
+
+    expect(result).toBeInstanceOf(Uint8Array);
+    expect(result.byteLength).toBe(0);
+  });
+
+  it("rejects a missing discriminant", () => {
+    expect(() => decodeWorkerBinaryResponse({ data: [1] })).toThrow(
+      RestApiValidationError,
+    );
+  });
+
+  it("rejects a non-Buffer discriminant", () => {
+    expect(() =>
+      decodeWorkerBinaryResponse({ type: "Array", data: [1] }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("rejects a non-array data field", () => {
+    expect(() =>
+      decodeWorkerBinaryResponse({ type: "Buffer", data: "00ff" }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("rejects a byte outside 0 through 255", () => {
+    expect(() =>
+      decodeWorkerBinaryResponse({ type: "Buffer", data: [256] }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("rejects a negative byte", () => {
+    expect(() =>
+      decodeWorkerBinaryResponse({ type: "Buffer", data: [-1] }),
+    ).toThrow(RestApiValidationError);
+  });
+
+  it("reports the index of a non-integer byte", () => {
+    try {
+      decodeWorkerBinaryResponse({ type: "Buffer", data: [1, 1.5] });
+    } catch (error) {
+      expect(error).toBeInstanceOf(RestApiValidationError);
+      if (!(error instanceof RestApiValidationError)) {
+        throw error;
+      }
+      expect(error.details.zodError.issues).toEqual([
+        expect.objectContaining({ path: ["data", 1] }),
+      ]);
+      return;
+    }
+    throw new Error("Expected binary response validation to fail");
+  });
+
+  it("redacts malformed binary data from validation errors", () => {
+    const data = Array.from({ length: 4096 }, () => 0);
+    data[4095] = 256;
+
+    try {
+      decodeWorkerBinaryResponse({ type: "Buffer", data });
+    } catch (error) {
+      expect(error).toBeInstanceOf(RestApiValidationError);
+      if (!(error instanceof RestApiValidationError)) {
+        throw error;
+      }
+      expect(error.details.data).toEqual({
+        dataType: "binary",
+        redacted: true,
+      });
+      return;
+    }
+    throw new Error("Expected malformed binary response to fail");
+  });
+
+  it("rejects a string payload", () => {
+    expect(() => decodeWorkerBinaryResponse("not-binary")).toThrow(
+      RestApiValidationError,
+    );
+  });
+});

package/src/integrations/base/decode-worker-binary-response.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+import {
+  REDACTED_BINARY_RESPONSE_DATA,
+  RestApiValidationError,
+} from "../../errors.js";
+
+export { REDACTED_BINARY_RESPONSE_DATA };
+
+const workerBinaryResponseSchema = z.union([
+  z.instanceof(Uint8Array).transform((value) => new Uint8Array(value)),
+  z
+    .object({
+      data: z.unknown(),
+      type: z.literal("Buffer"),
+    })
+    .transform((value, context) => {
+      if (!Array.isArray(value.data)) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "data must be an array of bytes",
+          path: ["data"],
+        });
+        return z.NEVER;
+      }
+
+      const bytes = new Uint8Array(value.data.length);
+      for (let index = 0; index < value.data.length; index += 1) {
+        const item = value.data[index];
+        if (
+          typeof item !== "number" ||
+          !Number.isInteger(item) ||
+          item < 0 ||
+          item > 255
+        ) {
+          context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "byte must be an integer from 0 through 255",
+            path: ["data", index],
+          });
+          return z.NEVER;
+        }
+        bytes[index] = item;
+      }
+
+      return bytes;
+    }),
+]);
+
+export function decodeWorkerBinaryResponse(value: unknown): Uint8Array {
+  const result = workerBinaryResponseSchema.safeParse(value);
+  if (!result.success) {
+    throw new RestApiValidationError(
+      `Binary response is malformed: ${result.error.message}`,
+      {
+        data: REDACTED_BINARY_RESPONSE_DATA,
+        zodError: result.error,
+      },
+    );
+  }
+  return result.data;
+}

package/src/integrations/base/rest-api-client-base.ts

@@ -1,13 +1,3 @@
-/**
- * Abstract base for REST API Integration clients.
- *
- * Owns the shared infrastructure that every REST-API-backed integration
- * needs: config storage, parameter helpers, body validation, request
- * construction, and query execution. Subclasses add their own
- * `apiRequest` with whatever response-handling strategy they need
- * (e.g. direct Zod validation, discriminated-union wrapping).
- */
-
 import type { PartialMessage } from "@bufbuild/protobuf";
 import { z } from "zod";
 
@@ -17,18 +7,12 @@ import type { Plugin as RestApiIntegrationPlugin } from "@superblocksteam/types/
 import { RestApiValidationError } from "../../errors.js";
 import type { QueryExecutor, TraceMetadata } from "../registry.js";
 import type { IntegrationConfig, IntegrationClientImpl } from "../types.js";
+import { decodeWorkerBinaryResponse } from "./decode-worker-binary-response.js";
 import { REST_API_RESPONSE_TYPES } from "./types.js";
 import type { ApiRequestOptions } from "./types.js";
 
 export type RestApiRequest = PartialMessage<RestApiIntegrationPlugin>;
 
-/**
- * Shared base for all REST API Integration clients.
- *
- * Provides config fields, parameter helpers, body validation, request
- * building, and query execution. Does NOT define `apiRequest` — each
- * concrete subclass supplies its own return-type contract.
- */
 export abstract class RestApiClientBase implements IntegrationClientImpl {
   readonly name: string;
   readonly pluginId: string;
@@ -53,23 +37,11 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
     };
   }
 
-  /**
-   * Validate the request body, build the proto request, and execute it.
-   *
-   * Returns the raw (unvalidated) response from the orchestrator.
-   * Subclasses call this, then apply their own response handling.
-   *
-   * @param options - Request configuration (see {@link ApiRequestOptions})
-   * @param bodySchema - Optional Zod schema for body validation
-   * @param metadata - Optional trace metadata for observability
-   * @returns Raw response from the orchestrator
-   */
   protected async executeApiRequest<TBody>(
     options: ApiRequestOptions<TBody>,
     bodySchema?: z.ZodSchema<TBody>,
     metadata?: TraceMetadata,
   ): Promise<unknown> {
-    // Validate request body if both body and schema are present.
     if (options.body !== undefined && bodySchema) {
       const bodyParseResult = bodySchema.safeParse(options.body);
       if (!bodyParseResult.success) {
@@ -97,16 +69,12 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       }
     }
 
-    // The RestApiResponseType union is erased in the bundled JS user APIs
-    // run as, so values outside it (including wire values the orchestrator
-    // implements but the SDK deliberately does not expose, like "auto")
-    // must also be rejected at runtime, before the request is issued.
     const responseTypeResult = z
       .enum(REST_API_RESPONSE_TYPES)
       .safeParse(options.responseType ?? "json");
     if (!responseTypeResult.success) {
       throw new RestApiValidationError(
-        `Unsupported responseType ${JSON.stringify(options.responseType)} — expected one of: ${REST_API_RESPONSE_TYPES.join(", ")}`,
+        `Unsupported responseType ${JSON.stringify(options.responseType)} - expected one of: ${REST_API_RESPONSE_TYPES.join(", ")}`,
         {
           zodError: responseTypeResult.error,
           data: options.responseType,
@@ -129,30 +97,34 @@ export abstract class RestApiClientBase implements IntegrationClientImpl {
       request.bodyType = "jsonBody";
     }
 
-    const result = await this.executeQuery(
-      request as Record<string, unknown>,
-      undefined,
-      metadata,
-    );
-
-    // Neither `null` nor `undefined` is a legitimate decode result for the
-    // exposed response types: JSON parses to a value the schema sees, and
-    // an empty text body decodes to "". Either value only arises from a
-    // broken execution contract, so both throw. (If "auto" is ever exposed,
-    // `null` becomes legitimate — it parses a literal `null` JSON body.)
+    const result = await this.executeQuery({ ...request }, undefined, metadata);
+
     if (result === null || result === undefined) {
-      const nonNullResult = z.object({}).safeParse(result);
-      if (!nonNullResult.success) {
-        throw new RestApiValidationError(
-          `Integration query returned ${String(result)} for responseType "${responseType}" — expected a response value`,
-          {
-            zodError: nonNullResult.error,
-            data: result,
-          },
-        );
-      }
+      throw new RestApiValidationError(
+        `Integration query returned ${String(result)} for responseType "${responseType}" - expected a response value`,
+        {
+          zodError: new z.ZodError([
+            {
+              code: z.ZodIssueCode.custom,
+              message: "response value is required",
+              path: [],
+            },
+          ]),
+          data: result,
+        },
+      );
     }
 
-    return result;
+    switch (responseType) {
+      case "binary":
+        return decodeWorkerBinaryResponse(result);
+      case "json":
+      case "text":
+        return result;
+      default: {
+        const _exhaustive: never = responseType;
+        return _exhaustive;
+      }
+    }
   }
 }

package/src/integrations/base/rest-api-integration-client.ts

@@ -1,14 +1,3 @@
-/**
- * Generic REST API Integration client with Zod response validation.
- *
- * Extends RestApiClientBase with an apiRequest() that validates the
- * full response against a caller-supplied Zod schema and throws
- * RestApiValidationError on mismatch. When no response schema is
- * provided, the raw result is returned without validation — useful for
- * non-JSON responses (e.g. XML), which can alternatively be validated
- * with a schema matching the decoded value (e.g. z.string()).
- */
-
 import { z } from "zod";
 
 import { RestApiValidationError } from "../../errors.js";
@@ -21,19 +10,14 @@ import type {
   SupportsApiRequest,
 } from "./types.js";
 
-/**
- * Base implementation for REST API Integration clients.
- *
- * All OpenAPI-based integration clients (except those with
- * integration-specific response handling) extend this class to
- * inherit the generic apiRequest() method with runtime Zod validation.
- */
 export abstract class RestApiIntegrationClient
   extends RestApiClientBase
   implements SupportsApiRequest
 {
   async apiRequest<TBody, TResponse>(
-    options: ApiRequestOptions<TBody>,
+    options: ApiRequestOptions<TBody> & {
+      responseType?: Exclude<RestApiResponseType, "binary">;
+    },
     schema: ApiRequestSchema<TBody, TResponse> & {
       response: z.ZodSchema<TResponse>;
     },
@@ -41,7 +25,14 @@ export abstract class RestApiIntegrationClient
   ): Promise<TResponse>;
   async apiRequest<TBody>(
     options: ApiRequestOptions<TBody> & {
-      responseType: Exclude<RestApiResponseType, "json">;
+      responseType: "binary";
+    },
+    schema?: ApiRequestSchema<TBody, Uint8Array>,
+    metadata?: TraceMetadata,
+  ): Promise<Uint8Array>;
+  async apiRequest<TBody>(
+    options: ApiRequestOptions<TBody> & {
+      responseType: "text";
     },
     schema?: ApiRequestSchema<TBody, unknown>,
     metadata?: TraceMetadata,
@@ -50,13 +41,10 @@ export abstract class RestApiIntegrationClient
     options: ApiRequestOptions<TBody>,
     schema?: ApiRequestSchema<TBody, TResponse>,
     metadata?: TraceMetadata,
-  ): Promise<TResponse | unknown> {
-    // The overloads make schema-less JSON unrepresentable in TypeScript,
-    // but user API code executes as bundled JS with no type enforcement —
-    // enforce the same contract at runtime, before issuing the request.
+  ): Promise<TResponse | Uint8Array | unknown> {
     if ((options.responseType ?? "json") === "json" && !schema?.response) {
       throw new RestApiValidationError(
-        'apiRequest() with responseType "json" requires a response schema — provide one, or set responseType: "text" to receive a non-JSON payload unvalidated',
+        'apiRequest() with responseType "json" requires a response schema. Provide one, or set responseType to "text" or "binary"',
         {
           zodError: new z.ZodError([
             {
@@ -76,13 +64,6 @@ export abstract class RestApiIntegrationClient
       metadata,
     );
 
-    // Without a response schema the raw result is returned as-is (typed
-    // unknown). Non-JSON responses (e.g. responseType "text" returning
-    // XML) can either omit the schema or pass one matching the decoded
-    // value, such as z.string(). Request-body validation is opt-in:
-    // executeApiRequest only validates options.body when schema.body is
-    // provided (unchanged from the previous contract, where schema.body
-    // was already optional).
     if (!schema?.response) {
       return result;
     }
@@ -93,8 +74,8 @@ export abstract class RestApiIntegrationClient
       throw new RestApiValidationError(
         `Response validation failed: ${responseParseResult.error.message}`,
         {
-          zodError: responseParseResult.error,
           data: result,
+          zodError: responseParseResult.error,
         },
       );
     }

package/src/integrations/base/types.ts

@@ -1,43 +1,13 @@
-/**
- * Shared types for REST API Integration (OpenAPI) based clients.
- */
-
 import type { z } from "zod";
 
 import type { TraceMetadata } from "../registry.js";
 
-// Re-export for backwards compatibility
 export type { TraceMetadata };
 
-/**
- * How the orchestrator should decode the HTTP response body.
- *
- * - `"json"` (default): parse the response as JSON; fails on non-JSON bodies
- * - `"text"`: return the decoded response body as a string (XML, CSV, HTML, ...)
- *
- * The orchestrator also implements `"auto"`, `"binary"`, and `"raw"` wire
- * values; they are deliberately not exposed here (widening this union later
- * is backward-compatible, narrowing it is not):
- *
- * - `"auto"` returns parsed JSON whenever the body happens to parse, which
- *   would let JSON responses bypass schema validation via the schema-less
- *   overload
- * - `"binary"` would freeze the worker's internal Buffer JSON encoding
- *   (`{ type: "Buffer", data: number[] }`, ~4x payload inflation) into the
- *   public SDK contract
- * - `"raw"` is rejected by the orchestrator for non-streaming requests
- *
- * The runtime tuple backs the request-time guard in `executeApiRequest`:
- * the type-level union is erased in the bundled JS user APIs run as, so
- * values outside it must also be rejected at runtime.
- */
-export const REST_API_RESPONSE_TYPES = ["json", "text"] as const;
+export const REST_API_RESPONSE_TYPES = ["binary", "json", "text"] as const;
 
 export type RestApiResponseType = (typeof REST_API_RESPONSE_TYPES)[number];
 
-/**
- * Options for making a generic REST API request.
- */
 export interface ApiRequestOptions<TBody = unknown> {
   /**
    * HTTP method for the request.
@@ -69,15 +39,14 @@ export interface ApiRequestOptions<TBody = unknown> {
    * How the response body should be decoded. Defaults to `"json"`.
    *
    * Use `"text"` for endpoints that return non-JSON payloads such as
-   * XML. When requesting a text response, omit the response schema (or
-   * use one matching the decoded string, e.g. `z.string()`).
+   * XML. Use `"binary"` for PDFs and other byte payloads. When
+   * requesting a text or binary response, omit the response schema (or
+   * use one matching the decoded value, e.g. `z.string()` or
+   * `z.instanceof(Uint8Array)`).
    */
   responseType?: RestApiResponseType;
 }
 
-/**
- * Schema configuration for API request validation.
- */
 export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
   /**
    * Optional Zod schema for request body validation.
@@ -96,10 +65,9 @@ export interface ApiRequestSchema<TBody = unknown, TResponse = unknown> {
  * Interface for integration clients that support generic API requests.
  *
  * Providing a response schema gives type-safe, validated results. Omitting
- * it returns the raw response as `unknown`. For non-JSON payloads (e.g.
- * `responseType: "text"` for XML), either omit the schema or supply one
- * matching the decoded value (e.g. `z.string()` for text) — object schemas
- * only make sense for JSON-shaped results.
+ * it returns the decoded response: `Uint8Array` for `responseType: "binary"`,
+ * or `unknown` for `responseType: "text"`. JSON still requires a schema.
+ * Object schemas only make sense for JSON-shaped results.
  */
 export interface SupportsApiRequest {
   /**
@@ -136,22 +104,50 @@ export interface SupportsApiRequest {
    * ```
    */
   apiRequest<TBody, TResponse>(
-    options: ApiRequestOptions<TBody>,
+    options: ApiRequestOptions<TBody> & {
+      responseType?: Exclude<RestApiResponseType, "binary">;
+    },
     schema: ApiRequestSchema<TBody, TResponse> & {
       response: z.ZodSchema<TResponse>;
     },
     metadata?: TraceMetadata,
   ): Promise<TResponse>;
 
+  /**
+   * Execute a generic API request that returns binary data.
+   *
+   * @param options - Request configuration; `responseType` must be "binary"
+   * @param schema - Optional Zod schemas for request body and decoded response validation
+   * @param metadata - Optional trace metadata for observability (label, description)
+   * @returns The decoded body as a `Uint8Array`
+   *
+   * @example
+   * ```typescript
+   * const pdf = await ctx.integrations.legacyApi.apiRequest({
+   *   method: 'GET',
+   *   path: '/file.pdf',
+   *   responseType: 'binary',
+   * });
+   * // pdf is a Uint8Array
+   * ```
+   */
+  apiRequest<TBody>(
+    options: ApiRequestOptions<TBody> & {
+      responseType: "binary";
+    },
+    schema?: ApiRequestSchema<TBody, Uint8Array>,
+    metadata?: TraceMetadata,
+  ): Promise<Uint8Array>;
+
   /**
    * Execute a generic API request without response validation.
    *
-   * This overload requires an explicit non-JSON `responseType` — JSON
+   * This overload requires an explicit `responseType: "text"` - JSON
    * responses must always be consumed through the schema overload above,
-   * so "unvalidated JSON" is unrepresentable. The decoded non-JSON
+   * so "unvalidated JSON" is unrepresentable. The decoded text
    * response is returned as-is, typed `unknown`.
    *
-   * Note: request-body validation is opt-in — it runs only when
+   * Note: request-body validation is opt-in - it runs only when
    * `schema.body` is provided. Omitting `schema` sends `options.body`
    * without validation.
    *
@@ -172,7 +168,7 @@ export interface SupportsApiRequest {
    */
   apiRequest<TBody>(
     options: ApiRequestOptions<TBody> & {
-      responseType: Exclude<RestApiResponseType, "json">;
+      responseType: "text";
     },
     schema?: ApiRequestSchema<TBody, unknown>,
     metadata?: TraceMetadata,

package/src/integrations/bigquery/README.md

@@ -27,6 +27,7 @@ const EventSchema = z.object({
 });
 
 export default api({
+  name: "GetEventCounts",
   integrations: {
     bigquery: bigquery(PROD_BIGQUERY),
   },

package/src/integrations/box/README.md

@@ -57,6 +57,9 @@ const ListItemsResponseSchema = z.object({
 
 export default api({
   name: "BoxExample",
+  integrations: {
+    box: box(PROD_BOX),
+  },
   input: z.object({
     folderId: z.string().default("0"), // "0" is root folder
     limit: z.number().default(100),

package/src/integrations/cohere/README.md

@@ -211,6 +211,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript

package/src/integrations/documentation-resolver.test.ts

@@ -839,17 +839,23 @@ describe("resolveIntegrationDocumentation", () => {
   });
 
   describe("restapiintegration responseType gating (real docs)", () => {
-    // These resolve the actual shipped docs, not a fixture: the overlay
-    // gating is the discoverability guard for the responseType feature
-    // (agents whose worker sdk-api predates it must never be told the
-    // option exists), so the real manifest content is the contract.
-
-    it("documents responseType for agents whose sdk-api supports it", async () => {
+    it("documents text responseType for agents whose sdk-api supports text only", async () => {
       const docs = await resolveIntegrationDocumentation("restapiintegration", {
         sdkVersion: "0.0.3",
       });
 
       expect(docs).toContain('responseType: "text"');
+      expect(docs).not.toContain('responseType: "binary"');
+      expect(docs).not.toContain("does not support the `responseType`");
+    });
+
+    it("documents binary responseType only for agents whose sdk-api supports it", async () => {
+      const docs = await resolveIntegrationDocumentation("restapiintegration", {
+        sdkVersion: "0.0.4",
+      });
+
+      expect(docs).toContain('responseType: "text"');
+      expect(docs).toContain('responseType: "binary"');
       expect(docs).not.toContain("does not support the `responseType`");
     });
 
@@ -860,6 +866,7 @@ describe("resolveIntegrationDocumentation", () => {
 
       expect(docs).toContain("does not support the `responseType`");
       expect(docs).not.toContain('responseType: "text"');
+      expect(docs).not.toContain('responseType: "binary"');
     });
 
     it("stays silent about responseType when the agent reports no sdk-api version", async () => {

package/src/integrations/fireworks/README.md

@@ -293,6 +293,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript

package/src/integrations/gemini/README.md

@@ -265,6 +265,14 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Use
+`:generateContent`, never `:streamGenerateContent` or `alt=sse` — streaming
+responses fail schema validation. Every call returns the complete response;
+if a UI needs real-time token streaming, handle it at the frontend layer,
+not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript

package/src/integrations/groq/README.md

@@ -251,6 +251,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript

package/src/integrations/mistral/README.md

@@ -277,6 +277,13 @@ All methods accept an optional `metadata` parameter as the last argument for dia
 
 ## Common Pitfalls
 
+### Streaming Is Not Supported
+
+`apiRequest()` does not support streaming or Server-Sent Events. Do not set
+`stream: true` — streaming responses fail schema validation. Every call
+returns the complete response; if a UI needs real-time token streaming,
+handle it at the frontend layer, not through the SDK.
+
 ### No Specialized Methods
 
 ```typescript