featurebase-node 0.15.0 → 0.15.2

package/src/resources/training-data/files.ts

@@ -0,0 +1,431 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Training data teaches the AI agent about your product beyond your public Help Center: training files (documents, policies, internal notes) and Q&A entries (question variants with the exact answer to give). Use these endpoints to keep that knowledge in sync from your own systems — for example, pushing resolved support conversations, internal runbooks, or SOP documents automatically.
+ */
+export class Files extends APIResource {
+  /**
+   * Adds a document the AI agent can learn from. Provide exactly one source:
+   *
+   * - **Inline text** — `{ "name": "refund-policy.md", "content": "..." }`. Markdown
+   *   or plain text is stored as-is and indexing is attempted before the response
+   *   returns; check `indexStatus` (`status` is `completed`). Best for content you
+   *   generate yourself, such as an SOP compiled from resolved conversations.
+   * - **Remote file** — `{ "url": "https://..." }` (optional `name`). The file (PDF,
+   *   DOCX, PPTX, XLSX, TXT, HTML, …; max 50 MB) is downloaded and converted to text
+   *   in the background. The response returns immediately with
+   *   `status: "processing"`; poll the file until it is `completed` or `failed`.
+   * - **Multipart upload** — send `multipart/form-data` with the document in a
+   *   `file` part and, optionally, a JSON `data` field such as `{"name": "..."}`.
+   *   Converted in the background like a remote file.
+   *
+   * **Keeping files in sync (create-or-update).** Pass your own `externalId` (unique
+   * per workspace) and the same request becomes idempotent: a new ID creates the
+   * file (`201`), a known ID with different content updates that file in place and
+   * re-indexes it (`200`), and a known ID with identical content is a no-op (`200`,
+   * no embedding work). Add a `source` label to group everything one pipeline owns,
+   * then list by `source` to find entries to remove. Every response carries
+   * `contentHash` so you can diff a whole library from the list endpoint.
+   *
+   * Without `externalId`, uploading a file whose name and bytes match an existing
+   * file returns the existing file with status `200` instead of creating a
+   * duplicate. Multipart uploads over 50 MB are rejected with `413`.
+   *
+   * @example
+   * ```ts
+   * const trainingFile =
+   *   await client.trainingData.files.create();
+   * ```
+   */
+  create(
+    params: FileCreateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<TrainingFile> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params ?? {};
+    return this._client.post('/v2/training_data/files', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns a training file including its extracted text (`content`). Poll this
+   * endpoint after an upload until `status` is `completed`.
+   *
+   * @example
+   * ```ts
+   * const trainingFile =
+   *   await client.trainingData.files.retrieve(
+   *     '67ec1234abcd5678ef901234',
+   *   );
+   * ```
+   */
+  retrieve(
+    id: string,
+    params: FileRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<TrainingFile> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.get(path`/v2/training_data/files/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Renames a training file, replaces content, or sets externalId / source. Indexing
+   * is attempted before returning when content is available. Check status and
+   * indexStatus; HTTP success alone does not establish search readiness. Serialize
+   * updates to a source identity in your pipeline.
+   *
+   * @example
+   * ```ts
+   * const trainingFile = await client.trainingData.files.update(
+   *   '67ec1234abcd5678ef901234',
+   * );
+   * ```
+   */
+  update(id: string, params: FileUpdateParams, options?: RequestOptions): APIPromise<TrainingFile> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.patch(path`/v2/training_data/files/${id}`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Returns uploaded training files, newest first, with cursor pagination. Filter by
+   * `externalId` (exact) or `source`. The extracted text is omitted from list
+   * responses — compare `contentHash` to detect changes, and retrieve a single file
+   * to read it.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const trainingFile of client.trainingData.files.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    params: FileListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<TrainingFilesCursorPage, TrainingFile> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.getAPIList('/v2/training_data/files', CursorPage<TrainingFile>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Removes a training file from the workspace and attempts search-index cleanup.
+   * In-flight answers may already contain earlier knowledge.
+   *
+   * @example
+   * ```ts
+   * const file = await client.trainingData.files.delete(
+   *   '67ec1234abcd5678ef901234',
+   * );
+   * ```
+   */
+  delete(
+    id: string,
+    params: FileDeleteParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<FileDeleteResponse> {
+    const { 'Featurebase-Version': featurebaseVersion } = params ?? {};
+    return this._client.delete(path`/v2/training_data/files/${id}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export type TrainingFilesCursorPage = CursorPage<TrainingFile>;
+
+export interface TrainingFile {
+  /**
+   * Training file ID
+   */
+  id: string;
+
+  /**
+   * Characters of extracted text
+   */
+  characterCount: number | null;
+
+  /**
+   * SHA-256 (hex) of the stored source: for inline text and content edits the
+   * trimmed text, for uploads and URLs the original bytes. Compare it with your own
+   * hash to detect changes without downloading `content`.
+   */
+  contentHash: string | null;
+
+  /**
+   * First 200 characters of the extracted text
+   */
+  contentPreview: string | null;
+
+  /**
+   * ISO timestamp of the upload
+   */
+  createdAt: string;
+
+  /**
+   * Your own identifier for this file, if one was set
+   */
+  externalId: string | null;
+
+  /**
+   * Size of the originally uploaded source in bytes (unchanged by content edits)
+   */
+  fileSize: number | null;
+
+  /**
+   * Whether the content is searchable by the AI agent. `pending` while indexing,
+   * `indexed` when the AI agent can use it, `failed` if indexing failed (the content
+   * is stored and indexing is retried hourly).
+   */
+  indexStatus: 'pending' | 'indexed' | 'failed';
+
+  /**
+   * MIME type of the originally uploaded source
+   */
+  mimeType: string | null;
+
+  /**
+   * File name shown in the dashboard
+   */
+  name: string;
+
+  /**
+   * Object type identifier
+   */
+  object: 'training_file';
+
+  /**
+   * Conversion error message when `status` is `failed`
+   */
+  processingError: string | null;
+
+  /**
+   * Pipeline label, if one was set
+   */
+  source: string | null;
+
+  /**
+   * `processing` while the file is being converted to text, `completed` once the
+   * content is stored, `failed` if conversion failed (see `processingError`).
+   */
+  status: 'processing' | 'completed' | 'failed';
+
+  /**
+   * ISO timestamp of the last change
+   */
+  updatedAt: string;
+
+  /**
+   * Words of extracted text
+   */
+  wordCount: number | null;
+
+  /**
+   * Full extracted text (markdown). Returned when retrieving or updating a single
+   * file; omitted from list and create responses.
+   */
+  content?: string | null;
+
+  /**
+   * On create and update responses: `created`, `updated` (same `externalId` or same
+   * name and bytes, content replaced and re-indexed), or `unchanged` (identical
+   * content, nothing done). Absent on reads.
+   */
+  outcome?: 'created' | 'updated' | 'unchanged';
+}
+
+export interface FileDeleteResponse {
+  /**
+   * ID of the deleted training file
+   */
+  id: string;
+
+  /**
+   * Indicates the resource was deleted
+   */
+  deleted: true;
+
+  /**
+   * Object type identifier
+   */
+  object: 'training_file';
+}
+
+export interface FileCreateParams {
+  /**
+   * Body param: Text or markdown to train on. Stored as-is; indexing is attempted
+   * before returning. Check indexStatus. Cannot be combined with `url`.
+   */
+  content?: string;
+
+  /**
+   * Body param: Your own identifier for this entry (unique per workspace). When
+   * provided, the request creates the entry if the ID is new and otherwise updates
+   * the existing entry in place — an unchanged payload is a no-op. Use it to keep
+   * the AI agent in sync with a system of record without tracking Featurebase IDs.
+   */
+  externalId?: string;
+
+  /**
+   * Body param: Display name of the file. Required with `content`; optional with
+   * `url` (defaults to the downloaded file name) or a multipart upload (defaults to
+   * the uploaded file name).
+   */
+  name?: string;
+
+  /**
+   * Body param: Free-form label for the pipeline or system this entry came from.
+   * Filter lists by it to review or sweep everything from one source.
+   */
+  source?: string;
+
+  /**
+   * Body param: Public http(s) URL of a document to download and convert (PDF, DOCX,
+   * TXT, HTML, …; max 50 MB). Conversion runs in the background — poll the file
+   * until `status` is `completed`. Cannot be combined with `content`.
+   */
+  url?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface FileRetrieveParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface FileUpdateParams {
+  /**
+   * Body param: Replacement text/markdown. Indexing is attempted before returning;
+   * check indexStatus.
+   */
+  content?: string;
+
+  /**
+   * Body param: Your own identifier for this entry (unique per workspace).
+   */
+  externalId?: string;
+
+  /**
+   * Body param: New display name
+   */
+  name?: string;
+
+  /**
+   * Body param: Free-form label for the pipeline or system this entry came from.
+   * Filter lists by it to review or sweep everything from one source.
+   */
+  source?: string;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface FileListParams extends CursorPageParams {
+  /**
+   * Query param: Only return the entry with this `externalId`
+   */
+  externalId?: string;
+
+  /**
+   * Query param: Only return entries with this `source` label
+   */
+  source?: string;
+
+  /**
+   * Query param: Only return files in this processing state
+   */
+  status?: 'processing' | 'completed' | 'failed';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export interface FileDeleteParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export declare namespace Files {
+  export {
+    type TrainingFile as TrainingFile,
+    type FileDeleteResponse as FileDeleteResponse,
+    type TrainingFilesCursorPage as TrainingFilesCursorPage,
+    type FileCreateParams as FileCreateParams,
+    type FileRetrieveParams as FileRetrieveParams,
+    type FileUpdateParams as FileUpdateParams,
+    type FileListParams as FileListParams,
+    type FileDeleteParams as FileDeleteParams,
+  };
+}

package/src/resources/training-data/index.ts

@@ -0,0 +1,31 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Files,
+  type TrainingFile,
+  type FileDeleteResponse,
+  type FileCreateParams,
+  type FileRetrieveParams,
+  type FileUpdateParams,
+  type FileListParams,
+  type FileDeleteParams,
+  type TrainingFilesCursorPage,
+} from './files';
+export {
+  QnaResource,
+  type Qna,
+  type QnaDeleteResponse,
+  type QnaCreateParams,
+  type QnaRetrieveParams,
+  type QnaUpdateParams,
+  type QnaListParams,
+  type QnaDeleteParams,
+  type QnasCursorPage,
+} from './qna';
+export {
+  TrainingData,
+  type KnowledgeSearch,
+  type Oracle,
+  type TrainingDataOracleParams,
+  type TrainingDataSearchParams,
+} from './training-data';