@tambo-ai/typescript-sdk 0.31.0

package/src/error.ts

@@ -0,0 +1,130 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { castToError, Headers } from './core';
+
+export class TamboAIError extends Error {}
+
+export class APIError<
+  TStatus extends number | undefined = number | undefined,
+  THeaders extends Headers | undefined = Headers | undefined,
+  TError extends Object | undefined = Object | undefined,
+> extends TamboAIError {
+  /** HTTP status for the response that caused the error */
+  readonly status: TStatus;
+  /** HTTP headers for the response that caused the error */
+  readonly headers: THeaders;
+  /** JSON body of the response that caused the error */
+  readonly error: TError;
+
+  constructor(status: TStatus, error: TError, message: string | undefined, headers: THeaders) {
+    super(`${APIError.makeMessage(status, error, message)}`);
+    this.status = status;
+    this.headers = headers;
+    this.error = error;
+  }
+
+  private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
+    const msg =
+      error?.message ?
+        typeof error.message === 'string' ?
+          error.message
+        : JSON.stringify(error.message)
+      : error ? JSON.stringify(error)
+      : message;
+
+    if (status && msg) {
+      return `${status} ${msg}`;
+    }
+    if (status) {
+      return `${status} status code (no body)`;
+    }
+    if (msg) {
+      return msg;
+    }
+    return '(no status code or body)';
+  }
+
+  static generate(
+    status: number | undefined,
+    errorResponse: Object | undefined,
+    message: string | undefined,
+    headers: Headers | undefined,
+  ): APIError {
+    if (!status || !headers) {
+      return new APIConnectionError({ message, cause: castToError(errorResponse) });
+    }
+
+    const error = errorResponse as Record<string, any>;
+
+    if (status === 400) {
+      return new BadRequestError(status, error, message, headers);
+    }
+
+    if (status === 401) {
+      return new AuthenticationError(status, error, message, headers);
+    }
+
+    if (status === 403) {
+      return new PermissionDeniedError(status, error, message, headers);
+    }
+
+    if (status === 404) {
+      return new NotFoundError(status, error, message, headers);
+    }
+
+    if (status === 409) {
+      return new ConflictError(status, error, message, headers);
+    }
+
+    if (status === 422) {
+      return new UnprocessableEntityError(status, error, message, headers);
+    }
+
+    if (status === 429) {
+      return new RateLimitError(status, error, message, headers);
+    }
+
+    if (status >= 500) {
+      return new InternalServerError(status, error, message, headers);
+    }
+
+    return new APIError(status, error, message, headers);
+  }
+}
+
+export class APIUserAbortError extends APIError<undefined, undefined, undefined> {
+  constructor({ message }: { message?: string } = {}) {
+    super(undefined, undefined, message || 'Request was aborted.', undefined);
+  }
+}
+
+export class APIConnectionError extends APIError<undefined, undefined, undefined> {
+  constructor({ message, cause }: { message?: string | undefined; cause?: Error | undefined }) {
+    super(undefined, undefined, message || 'Connection error.', undefined);
+    // in some environments the 'cause' property is already declared
+    // @ts-ignore
+    if (cause) this.cause = cause;
+  }
+}
+
+export class APIConnectionTimeoutError extends APIConnectionError {
+  constructor({ message }: { message?: string } = {}) {
+    super({ message: message ?? 'Request timed out.' });
+  }
+}
+
+export class BadRequestError extends APIError<400, Headers> {}
+
+export class AuthenticationError extends APIError<401, Headers> {}
+
+export class PermissionDeniedError extends APIError<403, Headers> {}
+
+export class NotFoundError extends APIError<404, Headers> {}
+
+export class ConflictError extends APIError<409, Headers> {}
+
+export class UnprocessableEntityError extends APIError<422, Headers> {}
+
+export class RateLimitError extends APIError<429, Headers> {}
+
+export class InternalServerError extends APIError<number, Headers> {}

package/src/index.ts

@@ -0,0 +1,229 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { type Agent } from './_shims/index';
+import * as Core from './core';
+import * as Errors from './error';
+import * as Pagination from './pagination';
+import { type OffsetAndLimitParams, OffsetAndLimitResponse } from './pagination';
+import * as Uploads from './uploads';
+import * as API from './resources/index';
+import {
+  ComponentGenerateParams,
+  ComponentGenerateResponse,
+  ComponentHydrateParams,
+  ComponentHydrateResponse,
+  Components,
+  LegacyChatMessage,
+} from './resources/components';
+import { Beta } from './resources/beta/beta';
+
+export interface ClientOptions {
+  /**
+   * API key used for authentication
+   */
+  apiKey?: string | null | undefined;
+
+  /**
+   * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
+   *
+   * Defaults to process.env['TAMBO_AI_BASE_URL'].
+   */
+  baseURL?: string | null | undefined;
+
+  /**
+   * The maximum amount of time (in milliseconds) that the client should wait for a response
+   * from the server before timing out a single request.
+   *
+   * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
+   * much longer than this timeout before the promise succeeds or fails.
+   */
+  timeout?: number | undefined;
+
+  /**
+   * An HTTP agent used to manage HTTP(S) connections.
+   *
+   * If not provided, an agent will be constructed by default in the Node.js environment,
+   * otherwise no agent is used.
+   */
+  httpAgent?: Agent | undefined;
+
+  /**
+   * Specify a custom `fetch` function implementation.
+   *
+   * If not provided, we use `node-fetch` on Node.js and otherwise expect that `fetch` is
+   * defined globally.
+   */
+  fetch?: Core.Fetch | undefined;
+
+  /**
+   * The maximum number of times that the client will retry a request in case of a
+   * temporary failure, like a network error or a 5XX error from the server.
+   *
+   * @default 0
+   */
+  maxRetries?: number | undefined;
+
+  /**
+   * Default headers to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * header to `undefined` or `null` in request options.
+   */
+  defaultHeaders?: Core.Headers | undefined;
+
+  /**
+   * Default query parameters to include with every request to the API.
+   *
+   * These can be removed in individual requests by explicitly setting the
+   * param to `undefined` in request options.
+   */
+  defaultQuery?: Core.DefaultQuery | undefined;
+}
+
+/**
+ * API Client for interfacing with the Tambo AI API.
+ */
+export class TamboAI extends Core.APIClient {
+  apiKey: string | null;
+
+  private _options: ClientOptions;
+
+  /**
+   * API Client for interfacing with the Tambo AI API.
+   *
+   * @param {string | null | undefined} [opts.apiKey=process.env['TAMBO_API_KEY'] ?? null]
+   * @param {string} [opts.baseURL=process.env['TAMBO_AI_BASE_URL']] - Override the default base URL for the API.
+   * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
+   * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
+   * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
+   * @param {number} [opts.maxRetries=0] - The maximum number of times the client will retry a request.
+   * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
+   * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
+   */
+  constructor({
+    baseURL = Core.readEnv('TAMBO_AI_BASE_URL'),
+    apiKey = Core.readEnv('TAMBO_API_KEY') ?? null,
+    ...opts
+  }: ClientOptions = {}) {
+    const options: ClientOptions = {
+      apiKey,
+      ...opts,
+      baseURL,
+    };
+
+    super({
+      baseURL: options.baseURL!,
+      timeout: options.timeout ?? 60000 /* 1 minute */,
+      httpAgent: options.httpAgent,
+      maxRetries: options.maxRetries,
+      fetch: options.fetch,
+    });
+
+    this._options = options;
+
+    this.apiKey = apiKey;
+  }
+
+  components: API.Components = new API.Components(this);
+  beta: API.Beta = new API.Beta(this);
+
+  protected override defaultQuery(): Core.DefaultQuery | undefined {
+    return this._options.defaultQuery;
+  }
+
+  protected override defaultHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    return {
+      ...super.defaultHeaders(opts),
+      ...this._options.defaultHeaders,
+    };
+  }
+
+  protected override validateHeaders(headers: Core.Headers, customHeaders: Core.Headers) {
+    if (this.apiKey && headers['x-api-key']) {
+      return;
+    }
+    if (customHeaders['x-api-key'] === null) {
+      return;
+    }
+
+    throw new Error(
+      'Could not resolve authentication method. Expected the apiKey to be set. Or for the "x-api-key" headers to be explicitly omitted',
+    );
+  }
+
+  protected override authHeaders(opts: Core.FinalRequestOptions): Core.Headers {
+    if (this.apiKey == null) {
+      return {};
+    }
+    return { 'x-api-key': this.apiKey };
+  }
+
+  static TamboAI = this;
+  static DEFAULT_TIMEOUT = 60000; // 1 minute
+
+  static TamboAIError = Errors.TamboAIError;
+  static APIError = Errors.APIError;
+  static APIConnectionError = Errors.APIConnectionError;
+  static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
+  static APIUserAbortError = Errors.APIUserAbortError;
+  static NotFoundError = Errors.NotFoundError;
+  static ConflictError = Errors.ConflictError;
+  static RateLimitError = Errors.RateLimitError;
+  static BadRequestError = Errors.BadRequestError;
+  static AuthenticationError = Errors.AuthenticationError;
+  static InternalServerError = Errors.InternalServerError;
+  static PermissionDeniedError = Errors.PermissionDeniedError;
+  static UnprocessableEntityError = Errors.UnprocessableEntityError;
+
+  static toFile = Uploads.toFile;
+  static fileFromPath = Uploads.fileFromPath;
+}
+
+TamboAI.Components = Components;
+TamboAI.Beta = Beta;
+export declare namespace TamboAI {
+  export type RequestOptions = Core.RequestOptions;
+
+  export import OffsetAndLimit = Pagination.OffsetAndLimit;
+  export {
+    type OffsetAndLimitParams as OffsetAndLimitParams,
+    type OffsetAndLimitResponse as OffsetAndLimitResponse,
+  };
+
+  export {
+    Components as Components,
+    type LegacyChatMessage as LegacyChatMessage,
+    type ComponentGenerateResponse as ComponentGenerateResponse,
+    type ComponentHydrateResponse as ComponentHydrateResponse,
+    type ComponentGenerateParams as ComponentGenerateParams,
+    type ComponentHydrateParams as ComponentHydrateParams,
+  };
+
+  export { Beta as Beta };
+
+  export type AvailableComponent = API.AvailableComponent;
+  export type ComponentContextToolMetadata = API.ComponentContextToolMetadata;
+  export type ToolCallRequest = API.ToolCallRequest;
+  export type ToolParameters = API.ToolParameters;
+}
+
+export { toFile, fileFromPath } from './uploads';
+export {
+  TamboAIError,
+  APIError,
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  APIUserAbortError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  BadRequestError,
+  AuthenticationError,
+  InternalServerError,
+  PermissionDeniedError,
+  UnprocessableEntityError,
+} from './error';
+
+export default TamboAI;
+export { generateStream, hydrateStream } from './lib/streaming-components';
+export { advanceStream } from './lib/advance-stream';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/lib/advance-stream.ts

@@ -0,0 +1,47 @@
+import { Response } from 'node-fetch';
+import TamboAI from '..';
+import * as Core from '../core';
+import { ThreadAdvanceParams, ThreadAdvanceResponse } from '../resources/beta';
+
+export async function advanceStream(
+  client: TamboAI,
+  body: ThreadAdvanceParams,
+  threadId?: string,
+  options?: Core.RequestOptions,
+): Promise<AsyncIterable<ThreadAdvanceResponse>> {
+  const responsePromise: Core.APIPromise<ThreadAdvanceResponse> = client.post(
+    `/threads${threadId ? `/${threadId}` : ''}/advancestream`,
+    {
+      body,
+      ...options,
+      headers: {
+        ...options?.headers,
+        Accept: 'text/event-stream',
+      },
+    },
+  );
+  const response = await responsePromise.asResponse();
+
+  return handleStreamResponse<ThreadAdvanceResponse>(response);
+}
+
+async function* handleStreamResponse<T>(response: Response): AsyncIterable<T> {
+  const decoder = new TextDecoder();
+  for await (const chunk of response.body) {
+    const text = decoder.decode(chunk as Uint8Array);
+
+    //handle server-combined events
+    const messages = text.split('\n').filter((msg) => msg.trim());
+
+    for (const msg of messages) {
+      if (msg === 'data: DONE') {
+        continue;
+      }
+      const jsonStr = msg.startsWith('data: ') ? msg.slice(6) : msg;
+      if (!jsonStr) {
+        continue;
+      }
+      yield JSON.parse(jsonStr) as T;
+    }
+  }
+}

package/src/lib/streaming-components.ts

@@ -0,0 +1,71 @@
+import { Response } from 'node-fetch';
+import { type TamboAI } from '..';
+import * as Core from '../core';
+import { Components as BetaComponents } from '../resources/beta/components';
+import { Components as BaseComponents } from '../resources/components';
+
+export async function generateStream(
+  client: TamboAI,
+  body: BaseComponents.ComponentGenerateParams | BetaComponents.ComponentGenerateParams,
+  options?: Core.RequestOptions,
+): Promise<
+  AsyncIterable<BaseComponents.ComponentGenerateResponse | BetaComponents.ComponentGenerateResponse>
+> {
+  const responsePromise: Core.APIPromise<
+    BaseComponents.ComponentGenerateResponse | BetaComponents.ComponentGenerateResponse
+  > = client.post('/components/generatestream', {
+    body,
+    ...options,
+    headers: {
+      ...options?.headers,
+      Accept: 'text/event-stream',
+    },
+  });
+  const response = await responsePromise.asResponse();
+
+  return handleStreamResponse<
+    BaseComponents.ComponentGenerateResponse | BetaComponents.ComponentGenerateResponse
+  >(response);
+}
+
+export async function hydrateStream(
+  client: TamboAI,
+  body: BaseComponents.ComponentHydrateParams | BetaComponents.ComponentHydrateParams,
+  options?: Core.RequestOptions,
+): Promise<AsyncIterable<BaseComponents.ComponentHydrateResponse | BetaComponents.ComponentHydrateResponse>> {
+  const responsePromise: Core.APIPromise<
+    BaseComponents.ComponentHydrateResponse | BetaComponents.ComponentHydrateResponse
+  > = client.post('/components/hydratestream', {
+    body,
+    ...options,
+    headers: {
+      ...options?.headers,
+      Accept: 'text/event-stream',
+    },
+  });
+  const response = await responsePromise.asResponse();
+  return handleStreamResponse<
+    BaseComponents.ComponentHydrateResponse | BetaComponents.ComponentHydrateResponse
+  >(response);
+}
+
+async function* handleStreamResponse<T>(response: Response): AsyncIterable<T> {
+  const decoder = new TextDecoder();
+  for await (const chunk of response.body) {
+    const text = decoder.decode(chunk as Uint8Array);
+
+    //handle server-combined events
+    const messages = text.split('\n').filter((msg) => msg.trim());
+
+    for (const msg of messages) {
+      if (msg === 'data: DONE') {
+        continue;
+      }
+      const jsonStr = msg.startsWith('data: ') ? msg.slice(6) : msg;
+      if (!jsonStr) {
+        continue;
+      }
+      yield JSON.parse(jsonStr) as T;
+    }
+  }
+}

package/src/pagination.ts

@@ -0,0 +1,73 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { AbstractPage, Response, APIClient, FinalRequestOptions, PageInfo } from './core';
+
+export interface OffsetAndLimitResponse<Item> {
+  items: Array<Item>;
+
+  total: number;
+
+  count: number;
+}
+
+export interface OffsetAndLimitParams {
+  offset?: number;
+
+  limit?: number;
+}
+
+export class OffsetAndLimit<Item> extends AbstractPage<Item> implements OffsetAndLimitResponse<Item> {
+  items: Array<Item>;
+
+  total: number;
+
+  count: number;
+
+  constructor(
+    client: APIClient,
+    response: Response,
+    body: OffsetAndLimitResponse<Item>,
+    options: FinalRequestOptions,
+  ) {
+    super(client, response, body, options);
+
+    this.items = body.items || [];
+    this.total = body.total || 0;
+    this.count = body.count || 0;
+  }
+
+  getPaginatedItems(): Item[] {
+    return this.items ?? [];
+  }
+
+  // @deprecated Please use `nextPageInfo()` instead
+  nextPageParams(): Partial<OffsetAndLimitParams> | null {
+    const info = this.nextPageInfo();
+    if (!info) return null;
+    if ('params' in info) return info.params;
+    const params = Object.fromEntries(info.url.searchParams);
+    if (!Object.keys(params).length) return null;
+    return params;
+  }
+
+  nextPageInfo(): PageInfo | null {
+    const offset = (this.options.query as OffsetAndLimitParams).offset ?? 0;
+    if (!offset) {
+      return null;
+    }
+
+    const length = this.getPaginatedItems().length;
+    const currentCount = offset + length;
+
+    const totalCount = this.total;
+    if (!totalCount) {
+      return null;
+    }
+
+    if (currentCount < totalCount) {
+      return { params: { offset: currentCount } };
+    }
+
+    return null;
+  }
+}

package/src/resource.ts

@@ -0,0 +1,11 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import type { TamboAI } from './index';
+
+export class APIResource {
+  protected _client: TamboAI;
+
+  constructor(client: TamboAI) {
+    this._client = client;
+  }
+}

package/src/resources/beta/beta.ts

@@ -0,0 +1,96 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../resource';
+import * as ComponentsAPI from './components';
+import {
+  ComponentGenerateParams,
+  ComponentGenerateResponse,
+  ComponentGenerateStreamParams,
+  ComponentHydrateParams,
+  ComponentHydrateResponse,
+  ComponentHydrateStreamParams,
+  Components,
+} from './components';
+import * as RegistryAPI from './registry';
+import { Registry, RegistryRetrieveResponse } from './registry';
+import * as ProjectsAPI from './projects/projects';
+import {
+  ProjectCreateParams,
+  ProjectCreateResponse,
+  ProjectDeleteResponse,
+  ProjectGetCurrentResponse,
+  ProjectRetrieveResponse,
+  ProjectUpdateParams,
+  ProjectUpdateResponse,
+  Projects,
+} from './projects/projects';
+import * as ThreadsAPI from './threads/threads';
+import {
+  ChatCompletionContentPart,
+  Thread,
+  ThreadAdvanceByIDParams,
+  ThreadAdvanceByIDResponse,
+  ThreadAdvanceParams,
+  ThreadAdvanceResponse,
+  ThreadCreateParams,
+  ThreadListParams,
+  ThreadMessage,
+  ThreadRetrieveResponse,
+  ThreadUpdateParams,
+  Threads,
+  ThreadsOffsetAndLimit,
+} from './threads/threads';
+
+export class Beta extends APIResource {
+  components: ComponentsAPI.Components = new ComponentsAPI.Components(this._client);
+  registry: RegistryAPI.Registry = new RegistryAPI.Registry(this._client);
+  projects: ProjectsAPI.Projects = new ProjectsAPI.Projects(this._client);
+  threads: ThreadsAPI.Threads = new ThreadsAPI.Threads(this._client);
+}
+
+Beta.Components = Components;
+Beta.Registry = Registry;
+Beta.Projects = Projects;
+Beta.Threads = Threads;
+Beta.ThreadsOffsetAndLimit = ThreadsOffsetAndLimit;
+
+export declare namespace Beta {
+  export {
+    Components as Components,
+    type ComponentGenerateResponse as ComponentGenerateResponse,
+    type ComponentHydrateResponse as ComponentHydrateResponse,
+    type ComponentGenerateParams as ComponentGenerateParams,
+    type ComponentGenerateStreamParams as ComponentGenerateStreamParams,
+    type ComponentHydrateParams as ComponentHydrateParams,
+    type ComponentHydrateStreamParams as ComponentHydrateStreamParams,
+  };
+
+  export { Registry as Registry, type RegistryRetrieveResponse as RegistryRetrieveResponse };
+
+  export {
+    Projects as Projects,
+    type ProjectCreateResponse as ProjectCreateResponse,
+    type ProjectRetrieveResponse as ProjectRetrieveResponse,
+    type ProjectUpdateResponse as ProjectUpdateResponse,
+    type ProjectDeleteResponse as ProjectDeleteResponse,
+    type ProjectGetCurrentResponse as ProjectGetCurrentResponse,
+    type ProjectCreateParams as ProjectCreateParams,
+    type ProjectUpdateParams as ProjectUpdateParams,
+  };
+
+  export {
+    Threads as Threads,
+    type ChatCompletionContentPart as ChatCompletionContentPart,
+    type Thread as Thread,
+    type ThreadMessage as ThreadMessage,
+    type ThreadRetrieveResponse as ThreadRetrieveResponse,
+    type ThreadAdvanceResponse as ThreadAdvanceResponse,
+    type ThreadAdvanceByIDResponse as ThreadAdvanceByIDResponse,
+    ThreadsOffsetAndLimit as ThreadsOffsetAndLimit,
+    type ThreadCreateParams as ThreadCreateParams,
+    type ThreadUpdateParams as ThreadUpdateParams,
+    type ThreadListParams as ThreadListParams,
+    type ThreadAdvanceParams as ThreadAdvanceParams,
+    type ThreadAdvanceByIDParams as ThreadAdvanceByIDParams,
+  };
+}