telnyx 7.14.0 → 7.16.0

package/src/resources/storage/sqldbs/sqldbs.ts

@@ -0,0 +1,179 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as ActionsAPI from './actions';
+import { ActionQueryParams, ActionQueryResponse, Actions } from './actions';
+import { APIPromise } from '../../../core/api-promise';
+import {
+  DefaultFlatPagination,
+  type DefaultFlatPaginationParams,
+  PagePromise,
+} from '../../../core/pagination';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Manage SQL databases and run SQL against them
+ */
+export class Sqldbs extends APIResource {
+  actions: ActionsAPI.Actions = new ActionsAPI.Actions(this._client);
+
+  /**
+   * Lists the SQL databases for the authenticated user's organization. Results use
+   * page-based pagination (`page[number]`/`page[size]`) and can be filtered and
+   * sorted.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const sqlDatabase of client.storage.sqldbs.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: SqldbListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<SqlDatabasesDefaultFlatPagination, SqlDatabase> {
+    return this._client.getAPIList('/storage/sqldbs', DefaultFlatPagination<SqlDatabase>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Creates a new SQL database. Provisioning is asynchronous: the database is
+   * returned with status `pending` and becomes usable once it reaches
+   * `provision_ok`.
+   *
+   * @example
+   * ```ts
+   * const sqlDatabaseResponseWrapper =
+   *   await client.storage.sqldbs.create({
+   *     name: 'my-database',
+   *   });
+   * ```
+   */
+  create(body: SqldbCreateParams, options?: RequestOptions): APIPromise<SqlDatabaseResponseWrapper> {
+    return this._client.post('/storage/sqldbs', { body, ...options });
+  }
+
+  /**
+   * Deletes a SQL database and all of the data it holds. Deletion is asynchronous
+   * and returns `202` with an empty body — the record is not removed synchronously.
+   * Poll `GET /storage/sqldbs/{id}`, which returns `404` once the database has been
+   * purged; there is no durable `deleted` state. A database still bound by a
+   * function is refused with `409` unless `force=true`.
+   *
+   * @example
+   * ```ts
+   * await client.storage.sqldbs.delete(
+   *   '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   * );
+   * ```
+   */
+  delete(
+    id: string,
+    params: SqldbDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { force } = params ?? {};
+    return this._client.delete(path`/storage/sqldbs/${id}`, {
+      query: { force },
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Retrieves a SQL database by its ID, including its provisioning status.
+   *
+   * @example
+   * ```ts
+   * const sqlDatabaseResponseWrapper =
+   *   await client.storage.sqldbs.retrieve(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   );
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<SqlDatabaseResponseWrapper> {
+    return this._client.get(path`/storage/sqldbs/${id}`, options);
+  }
+}
+
+export type SqlDatabasesDefaultFlatPagination = DefaultFlatPagination<SqlDatabase>;
+
+export interface SqlDatabase {
+  id?: string;
+
+  created_at?: string;
+
+  name?: string;
+
+  record_type?: string;
+
+  /**
+   * Provisioning status. A database is usable once `status` is `provision_ok`. Once
+   * deletion completes, the database no longer appears in the API.
+   */
+  status?: 'pending' | 'provision_ok' | 'provision_failed' | 'deleting' | 'delete_failed';
+
+  updated_at?: string;
+}
+
+export interface SqlDatabaseResponseWrapper {
+  data?: SqlDatabase;
+}
+
+export interface SqldbListParams extends DefaultFlatPaginationParams {
+  /**
+   * Filter by exact name match.
+   */
+  'filter[name]'?: string;
+
+  /**
+   * Filter by provisioning status.
+   */
+  'filter[status]'?: 'pending' | 'provision_ok' | 'provision_failed' | 'deleting' | 'delete_failed';
+
+  /**
+   * Sort field; prefix with `-` for descending order.
+   */
+  sort?: 'name' | '-name' | 'status' | '-status' | 'created_at' | '-created_at';
+}
+
+export interface SqldbCreateParams {
+  /**
+   * Database name. Lowercase letters, numbers, and hyphens only; must start and end
+   * with a letter or number.
+   */
+  name: string;
+}
+
+export interface SqldbDeleteParams {
+  /**
+   * Delete the database even when functions still bind it. Their bindings stop
+   * resolving.
+   */
+  force?: boolean;
+}
+
+Sqldbs.Actions = Actions;
+
+export declare namespace Sqldbs {
+  export {
+    type SqlDatabase as SqlDatabase,
+    type SqlDatabaseResponseWrapper as SqlDatabaseResponseWrapper,
+    type SqlDatabasesDefaultFlatPagination as SqlDatabasesDefaultFlatPagination,
+    type SqldbListParams as SqldbListParams,
+    type SqldbCreateParams as SqldbCreateParams,
+    type SqldbDeleteParams as SqldbDeleteParams,
+  };
+
+  export {
+    Actions as Actions,
+    type ActionQueryResponse as ActionQueryResponse,
+    type ActionQueryParams as ActionQueryParams,
+  };
+}

package/src/resources/storage/sqldbs.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './sqldbs/index';

package/src/resources/storage/storage.ts

@@ -27,6 +27,7 @@ import {
 } from './cloudfs/cloudfs';
 import * as KvsAPI from './kvs/kvs';
 import {
+  EdgeComputePaginationMeta,
   KvCreateParams,
   KvListParams,
   KvNamespace,
@@ -43,6 +44,16 @@ import {
   MigrationRetrieveResponse,
   Migrations,
 } from './migrations/migrations';
+import * as SqldbsAPI from './sqldbs/sqldbs';
+import {
+  SqlDatabase,
+  SqlDatabaseResponseWrapper,
+  SqlDatabasesDefaultFlatPagination,
+  SqldbCreateParams,
+  SqldbDeleteParams,
+  SqldbListParams,
+  Sqldbs,
+} from './sqldbs/sqldbs';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 
@@ -57,6 +68,7 @@ export class Storage extends APIResource {
   migrations: MigrationsAPI.Migrations = new MigrationsAPI.Migrations(this._client);
   kvs: KvsAPI.Kvs = new KvsAPI.Kvs(this._client);
   cloudfs: CloudfsAPI.Cloudfs = new CloudfsAPI.Cloudfs(this._client);
+  sqldbs: SqldbsAPI.Sqldbs = new SqldbsAPI.Sqldbs(this._client);
 
   /**
    * List the external storage providers and regions supported as migration sources.
@@ -99,6 +111,7 @@ Storage.MigrationSources = MigrationSources;
 Storage.Migrations = Migrations;
 Storage.Kvs = Kvs;
 Storage.Cloudfs = Cloudfs;
+Storage.Sqldbs = Sqldbs;
 
 export declare namespace Storage {
   export { type StorageListMigrationSourceCoverageResponse as StorageListMigrationSourceCoverageResponse };
@@ -130,6 +143,7 @@ export declare namespace Storage {
 
   export {
     Kvs as Kvs,
+    type EdgeComputePaginationMeta as EdgeComputePaginationMeta,
     type KvNamespace as KvNamespace,
     type KvNamespaceResponseWrapper as KvNamespaceResponseWrapper,
     type KvNamespacesDefaultFlatPagination as KvNamespacesDefaultFlatPagination,
@@ -147,4 +161,14 @@ export declare namespace Storage {
     type CloudfCreateParams as CloudfCreateParams,
     type CloudfUpdateParams as CloudfUpdateParams,
   };
+
+  export {
+    Sqldbs as Sqldbs,
+    type SqlDatabase as SqlDatabase,
+    type SqlDatabaseResponseWrapper as SqlDatabaseResponseWrapper,
+    type SqlDatabasesDefaultFlatPagination as SqlDatabasesDefaultFlatPagination,
+    type SqldbListParams as SqldbListParams,
+    type SqldbCreateParams as SqldbCreateParams,
+    type SqldbDeleteParams as SqldbDeleteParams,
+  };
 }

package/src/resources/web-search/index.ts

@@ -0,0 +1,17 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Research,
+  type ResearchCitation,
+  type ResearchCreateResponse,
+  type ResearchRetrieveResponse,
+  type ResearchCreateParams,
+} from './research';
+export {
+  WebSearch,
+  type WebSearchResult,
+  type WebSearchCreateResponse,
+  type WebSearchContentsResponse,
+  type WebSearchCreateParams,
+  type WebSearchContentsParams,
+} from './web-search';

package/src/resources/web-search/research.ts

@@ -0,0 +1,180 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ResearchAPI from './research';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Deep research with citations and async task polling.
+ */
+export class Research extends APIResource {
+  /**
+   * Starts a deep research task that runs multiple searches, reads sources, and
+   * synthesizes an answer with citations.
+   *
+   * ## Synchronous mode (default)
+   *
+   * When `background` is `false` or omitted, the request blocks until the research
+   * completes and returns the answer with citations. This can take up to 120 seconds
+   * depending on `research_effort`.
+   *
+   * ## Asynchronous mode
+   *
+   * When `background` is `true`, the request returns immediately with a `task_id`
+   * and `status: pending`. Poll `GET /web_search/research/{task_id}` to check when
+   * the research completes and retrieve the answer.
+   *
+   * @example
+   * ```ts
+   * const research = await client.webSearch.research.create({
+   *   query:
+   *     'Compare the performance of RAG vs fine-tuning for domain-specific QA',
+   *   max_sources: 20,
+   *   research_effort: 'standard',
+   * });
+   * ```
+   */
+  create(body: ResearchCreateParams, options?: RequestOptions): APIPromise<ResearchCreateResponse> {
+    return this._client.post('/web_search/research', { body, ...options });
+  }
+
+  /**
+   * Polls the status of a previously started asynchronous research task. When the
+   * status is `completed`, the response includes the answer and citations. When the
+   * status is `failed`, the response includes an error message.
+   *
+   * @example
+   * ```ts
+   * const research = await client.webSearch.research.retrieve(
+   *   'bf3026a5-dd57-44dd-b922-200041be3a4b',
+   * );
+   * ```
+   */
+  retrieve(taskID: string, options?: RequestOptions): APIPromise<ResearchRetrieveResponse> {
+    return this._client.get(path`/web_search/research/${taskID}`, options);
+  }
+}
+
+export interface ResearchCitation {
+  /**
+   * Title of the source page.
+   */
+  title: string;
+
+  /**
+   * Source URL.
+   */
+  url: string;
+
+  /**
+   * Relevant excerpt from the source (if available).
+   */
+  snippet?: string;
+}
+
+export interface ResearchCreateResponse {
+  /**
+   * Synchronous research response (when `background` is false or unset).
+   */
+  data?: ResearchCreateResponse.ResearchResponseSync | ResearchCreateResponse.ResearchResponseAsync;
+}
+
+export namespace ResearchCreateResponse {
+  /**
+   * Synchronous research response (when `background` is false or unset).
+   */
+  export interface ResearchResponseSync {
+    /**
+     * The synthesized research answer.
+     */
+    answer: string;
+
+    /**
+     * Sources cited in the answer.
+     */
+    citations?: Array<ResearchAPI.ResearchCitation>;
+  }
+
+  /**
+   * Asynchronous research response (when `background` is true).
+   */
+  export interface ResearchResponseAsync {
+    /**
+     * Current status of the research task.
+     */
+    status: 'pending' | 'running' | 'completed' | 'failed';
+
+    /**
+     * Unique identifier for the research task. Use this to poll the status.
+     */
+    task_id: string;
+  }
+}
+
+export interface ResearchRetrieveResponse {
+  data?: ResearchRetrieveResponse.Data;
+}
+
+export namespace ResearchRetrieveResponse {
+  export interface Data {
+    /**
+     * Current status of the research task.
+     */
+    status: 'pending' | 'running' | 'completed' | 'failed';
+
+    /**
+     * The research task identifier.
+     */
+    task_id: string;
+
+    /**
+     * The synthesized research answer (present when status is `completed`).
+     */
+    answer?: string;
+
+    /**
+     * Sources cited in the answer (present when status is `completed`).
+     */
+    citations?: Array<ResearchAPI.ResearchCitation>;
+
+    /**
+     * Always present in poll responses; `null` unless the task failed.
+     */
+    error?: string | null;
+  }
+}
+
+export interface ResearchCreateParams {
+  /**
+   * The research question or topic.
+   */
+  query: string;
+
+  /**
+   * When `true`, the research runs asynchronously. The response returns a `task_id`
+   * immediately instead of waiting for the result. Poll
+   * `GET /web_search/research/{task_id}` to check status.
+   */
+  background?: boolean;
+
+  /**
+   * Maximum number of sources to use.
+   */
+  max_sources?: number;
+
+  /**
+   * Research depth level. `lite` is fastest, `deep` is most thorough.
+   */
+  research_effort?: 'lite' | 'standard' | 'deep';
+}
+
+export declare namespace Research {
+  export {
+    type ResearchCitation as ResearchCitation,
+    type ResearchCreateResponse as ResearchCreateResponse,
+    type ResearchRetrieveResponse as ResearchRetrieveResponse,
+    type ResearchCreateParams as ResearchCreateParams,
+  };
+}

package/src/resources/web-search/web-search.ts

@@ -0,0 +1,266 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as WebSearchAPI from './web-search';
+import * as ResearchAPI from './research';
+import {
+  Research,
+  ResearchCitation,
+  ResearchCreateParams,
+  ResearchCreateResponse,
+  ResearchRetrieveResponse,
+} from './research';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+
+export class WebSearch extends APIResource {
+  research: ResearchAPI.Research = new ResearchAPI.Research(this._client);
+
+  /**
+   * Performs a real-time web search and returns structured, LLM-ready JSON results
+   * with titles, URLs, descriptions, and snippets. Supports filtering by domain,
+   * country, safe search, freshness, and live crawl.
+   *
+   * **Note:** `include_domains` and `exclude_domains` cannot be used in the same
+   * request. Use one or the other.
+   *
+   * @example
+   * ```ts
+   * const webSearch = await client.webSearch.create({
+   *   query: 'latest AI agent frameworks',
+   *   count: 10,
+   *   country: 'US',
+   *   freshness: 'week',
+   *   include_domains: ['arxiv.org', 'github.com'],
+   *   safesearch: 'moderate',
+   * });
+   * ```
+   */
+  create(body: WebSearchCreateParams, options?: RequestOptions): APIPromise<WebSearchCreateResponse> {
+    return this._client.post('/web_search', { body, ...options });
+  }
+
+  /**
+   * Retrieves clean HTML or Markdown content from a list of URLs. Supports up to 20
+   * URLs per request (public API limit). Specify which formats to return: `html`,
+   * `markdown`, `metadata`.
+   *
+   * @example
+   * ```ts
+   * const response = await client.webSearch.contents({
+   *   urls: [
+   *     'https://en.wikipedia.org/wiki/Artificial_intelligence',
+   *   ],
+   *   crawl_timeout: 10,
+   *   formats: ['markdown', 'metadata'],
+   * });
+   * ```
+   */
+  contents(body: WebSearchContentsParams, options?: RequestOptions): APIPromise<WebSearchContentsResponse> {
+    return this._client.post('/web_search/contents', { body, ...options });
+  }
+}
+
+export interface WebSearchResult {
+  /**
+   * Short description or excerpt.
+   */
+  description: string;
+
+  /**
+   * Relevant text snippets from the page.
+   */
+  snippets: Array<string>;
+
+  /**
+   * Result title.
+   */
+  title: string;
+
+  /**
+   * Result URL.
+   */
+  url: string;
+
+  /**
+   * Favicon URL (if available).
+   */
+  favicon_url?: string;
+
+  /**
+   * Thumbnail image URL (if available).
+   */
+  thumbnail_url?: string;
+}
+
+export interface WebSearchCreateResponse {
+  data?: WebSearchCreateResponse.Data;
+}
+
+export namespace WebSearchCreateResponse {
+  export interface Data {
+    results?: Data.Results;
+  }
+
+  export namespace Data {
+    export interface Results {
+      /**
+       * Web search results.
+       */
+      web: Array<WebSearchAPI.WebSearchResult>;
+
+      /**
+       * News search results. Present only when the query surfaces news results.
+       */
+      news?: Array<WebSearchAPI.WebSearchResult>;
+    }
+  }
+}
+
+export interface WebSearchContentsResponse {
+  data?: WebSearchContentsResponse.Data;
+}
+
+export namespace WebSearchContentsResponse {
+  export interface Data {
+    results?: Array<Data.Result>;
+  }
+
+  export namespace Data {
+    export interface Result {
+      /**
+       * The source URL.
+       */
+      url: string;
+
+      /**
+       * Cleaned HTML content (if `html` format requested; may also be present on freshly
+       * crawled pages).
+       */
+      html?: string;
+
+      /**
+       * Markdown content (if `markdown` format requested).
+       */
+      markdown?: string;
+
+      /**
+       * Page metadata (if `metadata` format requested).
+       */
+      metadata?: Result.Metadata;
+
+      /**
+       * Page title (if available).
+       */
+      title?: string;
+    }
+
+    export namespace Result {
+      /**
+       * Page metadata (if `metadata` format requested).
+       */
+      export interface Metadata {
+        /**
+         * Favicon URL (if available).
+         */
+        favicon_url?: string;
+
+        /**
+         * Site name. Often empty.
+         */
+        site_name?: string;
+
+        [k: string]: unknown;
+      }
+    }
+  }
+}
+
+export interface WebSearchCreateParams {
+  /**
+   * The search query text.
+   */
+  query: string;
+
+  /**
+   * Number of results to return (1-100).
+   */
+  count?: number;
+
+  /**
+   * Two-letter country code (ISO 3166-1 alpha-2) to bias results.
+   */
+  country?: string;
+
+  /**
+   * Exclude results from these domains (bare hostnames, e.g. `pinterest.com`).
+   */
+  exclude_domains?: Array<string>;
+
+  /**
+   * Time-based filter for results. Common values: `day`, `week`, `month`, `year`.
+   */
+  freshness?: string;
+
+  /**
+   * Restrict results to these domains (bare hostnames, e.g. `arxiv.org`).
+   */
+  include_domains?: Array<string>;
+
+  /**
+   * When true, the provider crawls pages in real-time for fresh content. The boolean
+   * is translated to the provider's internal enum internally; callers always pass
+   * `true` or `false`.
+   */
+  livecrawl?: boolean;
+
+  /**
+   * Safe search filter level.
+   */
+  safesearch?: 'off' | 'moderate' | 'strict';
+}
+
+export interface WebSearchContentsParams {
+  /**
+   * List of URLs to retrieve content from (max 20 for public API).
+   */
+  urls: Array<string>;
+
+  /**
+   * Timeout for crawling each URL, in seconds (1-60).
+   */
+  crawl_timeout?: number;
+
+  /**
+   * Content formats to return. If omitted, `html` and `metadata` are returned by
+   * default. Retrieval is best-effort per URL: a format field appears only when that
+   * content could be produced, and a freshly crawled page may also include `html`
+   * even when not requested.
+   */
+  formats?: Array<'html' | 'markdown' | 'metadata'>;
+
+  /**
+   * Maximum age of cached content in seconds. `null` means no limit.
+   */
+  max_age?: number | null;
+}
+
+WebSearch.Research = Research;
+
+export declare namespace WebSearch {
+  export {
+    type WebSearchResult as WebSearchResult,
+    type WebSearchCreateResponse as WebSearchCreateResponse,
+    type WebSearchContentsResponse as WebSearchContentsResponse,
+    type WebSearchCreateParams as WebSearchCreateParams,
+    type WebSearchContentsParams as WebSearchContentsParams,
+  };
+
+  export {
+    Research as Research,
+    type ResearchCitation as ResearchCitation,
+    type ResearchCreateResponse as ResearchCreateResponse,
+    type ResearchRetrieveResponse as ResearchRetrieveResponse,
+    type ResearchCreateParams as ResearchCreateParams,
+  };
+}

package/src/resources/web-search.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './web-search/index';