truefoundry-gateway-sdk 0.1.0 → 0.2.0-rc.1

package/README.md

@@ -25,6 +25,7 @@ Call the gateway directly — not via the control-plane `/api/llm` proxy. The te
 - [Request and Response Types](#request-and-response-types)
 - [Exception Handling](#exception-handling)
 - [Streaming Response](#streaming-response)
+- [Binary Response](#binary-response)
 - [Pagination](#pagination)
 - [Advanced](#advanced)
   - [Subpackage Exports](#subpackage-exports)
@@ -124,7 +125,7 @@ following namespace:
 ```typescript
 import { TrueFoundryGateway } from "truefoundry-gateway-sdk";
 
-const request: TrueFoundryGateway.DraftSessionsListRequest = {
+const request: TrueFoundryGateway.AgentsDownloadSandboxFileRequest = {
     ...
 };
 ```
@@ -164,6 +165,395 @@ for await (const item of response) {
 }
 ```
 
+## Binary Response
+
+You can consume binary data from endpoints using the `BinaryResponse` type which lets you choose how to consume the data:
+
+```typescript
+const response = await client.private.agents.downloadSandboxFile(...);
+const stream: ReadableStream<Uint8Array> = response.stream();
+// const arrayBuffer: ArrayBuffer = await response.arrayBuffer();
+// const blob: Blob = response.blob();
+// const bytes: Uint8Array = response.bytes();
+// You can only use the response body once, so you must choose one of the above methods.
+// If you want to check if the response body has been used, you can use the following property.
+const bodyUsed = response.bodyUsed;
+```
+<details>
+<summary>Save binary response to a file</summary>
+
+<blockquote>
+<details>
+<summary>Node.js</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+import { createWriteStream } from 'fs';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const stream = response.stream();
+const nodeStream = Readable.fromWeb(stream);
+const writeStream = createWriteStream('path/to/file');
+
+await pipeline(nodeStream, writeStream);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await writeFile('path/to/file', Buffer.from(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const blob = await response.blob();
+const arrayBuffer = await blob.arrayBuffer();
+await writeFile('output.bin', Buffer.from(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const bytes = await response.bytes();
+await writeFile('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bun</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const stream = response.stream();
+await Bun.write('path/to/file', stream);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await Bun.write('path/to/file', arrayBuffer);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const blob = await response.blob();
+await Bun.write('path/to/file', blob);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const bytes = await response.bytes();
+await Bun.write('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Deno</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const stream = response.stream();
+const file = await Deno.open('path/to/file', { write: true, create: true });
+await stream.pipeTo(file.writable);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const blob = await response.blob();
+const arrayBuffer = await blob.arrayBuffer();
+await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const bytes = await response.bytes();
+await Deno.writeFile('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Browser</summary>
+
+<blockquote>
+<details>
+<summary>Blob (most-efficient)</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const blob = await response.blob();
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ReadableStream</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const stream = response.stream();
+const reader = stream.getReader();
+const chunks = [];
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  chunks.push(value);
+}
+
+const blob = new Blob(chunks);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const arrayBuffer = await response.arrayBuffer();
+const blob = new Blob([arrayBuffer]);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const bytes = await response.bytes();
+const blob = new Blob([bytes]);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<details>
+<summary>Convert binary response to text</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const stream = response.stream();
+const text = await new Response(stream).text();
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const arrayBuffer = await response.arrayBuffer();
+const text = new TextDecoder().decode(arrayBuffer);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const blob = await response.blob();
+const text = await blob.text();
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.private.agents.downloadSandboxFile(...);
+
+const bytes = await response.bytes();
+const text = new TextDecoder().decode(bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+
 ## Pagination
 
 List endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:
@@ -172,7 +562,7 @@ List endpoints are paginated. The SDK provides an iterator so that you can simpl
 import { TrueFoundryGateway } from "truefoundry-gateway-sdk";
 
 const client = new TrueFoundryGateway({ environment: "YOUR_BASE_URL", apiKey: "YOUR_API_KEY" });
-const pageableResponse = await client.private.agents.draftSessions.list({
+const pageableResponse = await client.private.agents.sessions.list({
     agentName: "agent_name",
     limit: 1,
     order: "asc",
@@ -185,7 +575,7 @@ for await (const item of pageableResponse) {
 }
 
 // Or you can manually iterate page-by-page
-let page = await client.private.agents.draftSessions.list({
+let page = await client.private.agents.sessions.list({
     agentName: "agent_name",
     limit: 1,
     order: "asc",

package/dist/cjs/BaseClient.js

@@ -43,8 +43,8 @@ function normalizeClientOptions(options) {
     const headers = (0, headers_js_1.mergeHeaders)({
         "X-Fern-Language": "JavaScript",
         "X-Fern-SDK-Name": "truefoundry-gateway-sdk",
-        "X-Fern-SDK-Version": "0.1.0",
-        "User-Agent": "truefoundry-gateway-sdk/0.1.0",
+        "X-Fern-SDK-Version": "0.2.0-rc.1",
+        "User-Agent": "truefoundry-gateway-sdk/0.2.0-rc.1",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options === null || options === void 0 ? void 0 : options.headers);

package/dist/cjs/CustomClient.d.ts

@@ -9,8 +9,12 @@ export declare namespace TrueFoundryGateway {
     interface RequestOptions extends BaseTrueFoundryGateway.RequestOptions {
     }
 }
+/** Asynchronous client for the TrueFoundry Gateway API. */
 export declare class TrueFoundryGateway extends BaseTrueFoundryGateway {
     protected _agents: AgentsClient | undefined;
     constructor(_options: TrueFoundryGateway.Options);
+    /**
+     * @returns {AgentsClient} Low-level agents client. Prefer {@link AgentSessionClient} for the high-level API.
+     */
     get agents(): AgentsClient;
 }

package/dist/cjs/CustomClient.js

@@ -2,12 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TrueFoundryGateway = void 0;
 const Client_js_1 = require("./Client.js");
+/** Asynchronous client for the TrueFoundry Gateway API. */
 class TrueFoundryGateway extends Client_js_1.TrueFoundryGateway {
     constructor(_options) {
         var _a;
         const options = Object.assign(Object.assign({}, _options), { environment: (_a = _options.environment) !== null && _a !== void 0 ? _a : "" });
         super(options);
     }
+    /**
+     * @returns {AgentsClient} Low-level agents client. Prefer {@link AgentSessionClient} for the high-level API.
+     */
     get agents() {
         var _a;
         return ((_a = this._agents) !== null && _a !== void 0 ? _a : (this._agents = this.private.agents));

package/dist/cjs/agents/AgentSession.d.ts

@@ -5,23 +5,60 @@ import * as core from "../core/index.js";
 import { PreparedTurn } from "./PreparedTurn.js";
 import { Turn } from "./Turn.js";
 type RequestOptions = SessionsClient.RequestOptions;
+/**
+ * A session enriched with convenience methods: prepareTurn, listTurns, getTurn, cancel.
+ */
 export declare class AgentSession implements TrueFoundryGatewayApi.Session {
     #private;
+    /** Unique identifier of this session. */
     readonly id: string;
+    /** Name of the agent for this session. */
     readonly agentName: string;
+    /** Optional user-visible title for the session. */
     readonly title?: string;
+    /** Subject that created this session. */
     readonly createdBySubject: TrueFoundryGatewayApi.Subject;
+    /** ISO-8601 timestamp when the session was created. */
     readonly createdAt: string;
+    /** ISO-8601 timestamp when the session was last updated. */
     readonly updatedAt: string;
     constructor(session: TrueFoundryGatewayApi.Session, client: TrueFoundryGateway);
+    /**
+     * Stage a turn locally; call `execute()` to start `createTurn`.
+     *
+     * @param opts.input - Turn input items passed to createTurn.
+     * @param opts.previousTurnId - Previous turn to chain from. Default `auto`.
+     * @returns {PreparedTurn} Staged turn.
+     */
     prepareTurn(opts?: {
         input?: TrueFoundryGatewayApi.TurnInputItem[];
         previousTurnId?: TrueFoundryGatewayApi.PreviousTurnIdInput;
     }): PreparedTurn;
+    /**
+     * List turns in this session.
+     *
+     * @param opts.pageToken - Token from the previous response nextPageToken.
+     * @param opts.limit - Page size. Default 10.
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {core.Page<Turn, TrueFoundryGatewayApi.ListTurnsResponse>} Paginated turns.
+     */
     listTurns(opts?: TrueFoundryGatewayApi.agents.SessionsListTurnsRequest, requestOptions?: RequestOptions): Promise<core.Page<Turn, TrueFoundryGatewayApi.ListTurnsResponse>>;
+    /**
+     * Fetch a turn by ID.
+     *
+     * @param opts.turnId - Unique identifier of the turn to fetch.
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {Turn} Turn data.
+     */
     getTurn(opts: {
         turnId: string;
     }, requestOptions?: RequestOptions): Promise<Turn>;
+    /**
+     * Cancel the running last turn for the session.
+     *
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {void}
+     */
     cancel(requestOptions?: RequestOptions): Promise<void>;
 }
 export {};

package/dist/cjs/agents/AgentSession.js

@@ -58,6 +58,9 @@ exports.AgentSession = void 0;
 const core = __importStar(require("../core/index.js"));
 const PreparedTurn_js_1 = require("./PreparedTurn.js");
 const Turn_js_1 = require("./Turn.js");
+/**
+ * A session enriched with convenience methods: prepareTurn, listTurns, getTurn, cancel.
+ */
 class AgentSession {
     constructor(session, client) {
         _AgentSession_client.set(this, void 0);
@@ -69,9 +72,24 @@ class AgentSession {
         this.updatedAt = session.updatedAt;
         __classPrivateFieldSet(this, _AgentSession_client, client, "f");
     }
+    /**
+     * Stage a turn locally; call `execute()` to start `createTurn`.
+     *
+     * @param opts.input - Turn input items passed to createTurn.
+     * @param opts.previousTurnId - Previous turn to chain from. Default `auto`.
+     * @returns {PreparedTurn} Staged turn.
+     */
     prepareTurn(opts) {
         return new PreparedTurn_js_1.PreparedTurn({ input: opts === null || opts === void 0 ? void 0 : opts.input, previousTurnId: opts === null || opts === void 0 ? void 0 : opts.previousTurnId }, this, __classPrivateFieldGet(this, _AgentSession_client, "f"));
     }
+    /**
+     * List turns in this session.
+     *
+     * @param opts.pageToken - Token from the previous response nextPageToken.
+     * @param opts.limit - Page size. Default 10.
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {core.Page<Turn, TrueFoundryGatewayApi.ListTurnsResponse>} Paginated turns.
+     */
     listTurns(opts, requestOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             const client = __classPrivateFieldGet(this, _AgentSession_client, "f");
@@ -88,12 +106,25 @@ class AgentSession {
             });
         });
     }
+    /**
+     * Fetch a turn by ID.
+     *
+     * @param opts.turnId - Unique identifier of the turn to fetch.
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {Turn} Turn data.
+     */
     getTurn(opts, requestOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield __classPrivateFieldGet(this, _AgentSession_client, "f").agents.sessions.getTurn(this.id, opts.turnId, requestOptions);
             return new Turn_js_1.Turn(response.data, this, __classPrivateFieldGet(this, _AgentSession_client, "f"));
         });
     }
+    /**
+     * Cancel the running last turn for the session.
+     *
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {void}
+     */
     cancel(requestOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             yield __classPrivateFieldGet(this, _AgentSession_client, "f").agents.sessions.cancel(this.id, {}, requestOptions);

package/dist/cjs/agents/AgentSessionClient.d.ts

@@ -7,11 +7,41 @@ export declare namespace AgentSessionClient {
     type Options = TrueFoundryGateway.Options;
     type RequestOptions = SessionsClient.RequestOptions;
 }
+/**
+ * Entry-point for the high-level agent API. Wraps TrueFoundryGateway and returns
+ * enriched AgentSession objects instead of raw response types.
+ */
 export declare class AgentSessionClient {
     private readonly client;
     constructor(options: AgentSessionClient.Options);
+    /**
+     * Create a new session for a named agent.
+     *
+     * @param opts.agentName - Name of the agent to create a session for.
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {AgentSession} Session created.
+     */
     createSession(opts: TrueFoundryGatewayApi.agents.CreateSessionRequest, requestOptions?: AgentSessionClient.RequestOptions): Promise<AgentSession>;
+    /**
+     * List sessions for an agent.
+     *
+     * @param opts.agentName - Name of the agent whose sessions to list.
+     * @param opts.limit - Page size. Default 10.
+     * @param opts.order - Sort by creation time. Default `desc`.
+     * @param opts.pageToken - Token from the previous response nextPageToken.
+     * @param opts.startTimestamp - Inclusive lower bound on createdAt (ISO-8601).
+     * @param opts.endTimestamp - Inclusive upper bound on createdAt (ISO-8601).
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {core.Page<AgentSession, TrueFoundryGatewayApi.ListSessionsResponse>} Paginated sessions.
+     */
     listSessions(opts: TrueFoundryGatewayApi.agents.SessionsListRequest, requestOptions?: AgentSessionClient.RequestOptions): Promise<core.Page<AgentSession, TrueFoundryGatewayApi.ListSessionsResponse>>;
+    /**
+     * Fetch a session by ID.
+     *
+     * @param opts.sessionId - Unique identifier of the session to fetch.
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {AgentSession} Session data.
+     */
     getSession(opts: {
         sessionId: string;
     }, requestOptions?: AgentSessionClient.RequestOptions): Promise<AgentSession>;

package/dist/cjs/agents/AgentSessionClient.js

@@ -46,16 +46,39 @@ exports.AgentSessionClient = void 0;
 const CustomClient_js_1 = require("../CustomClient.js");
 const core = __importStar(require("../core/index.js"));
 const AgentSession_js_1 = require("./AgentSession.js");
+/**
+ * Entry-point for the high-level agent API. Wraps TrueFoundryGateway and returns
+ * enriched AgentSession objects instead of raw response types.
+ */
 class AgentSessionClient {
     constructor(options) {
         this.client = new CustomClient_js_1.TrueFoundryGateway(options);
     }
+    /**
+     * Create a new session for a named agent.
+     *
+     * @param opts.agentName - Name of the agent to create a session for.
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {AgentSession} Session created.
+     */
     createSession(opts, requestOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.client.agents.sessions.create(opts, requestOptions);
             return new AgentSession_js_1.AgentSession(response.data, this.client);
         });
     }
+    /**
+     * List sessions for an agent.
+     *
+     * @param opts.agentName - Name of the agent whose sessions to list.
+     * @param opts.limit - Page size. Default 10.
+     * @param opts.order - Sort by creation time. Default `desc`.
+     * @param opts.pageToken - Token from the previous response nextPageToken.
+     * @param opts.startTimestamp - Inclusive lower bound on createdAt (ISO-8601).
+     * @param opts.endTimestamp - Inclusive upper bound on createdAt (ISO-8601).
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {core.Page<AgentSession, TrueFoundryGatewayApi.ListSessionsResponse>} Paginated sessions.
+     */
     listSessions(opts, requestOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             const page = yield this.client.agents.sessions.list(opts, requestOptions);
@@ -74,6 +97,13 @@ class AgentSessionClient {
             });
         });
     }
+    /**
+     * Fetch a session by ID.
+     *
+     * @param opts.sessionId - Unique identifier of the session to fetch.
+     * @param requestOptions - Overrides client timeout, retries, abortSignal, headers, queryParams.
+     * @returns {AgentSession} Session data.
+     */
     getSession(opts, requestOptions) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.client.agents.sessions.get(opts.sessionId, requestOptions);