langwatch 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { L as Logger, C as ConsoleLogger, N as NoOpLogger } from './index-D7rKIGrO.js';
-export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, d as getLangWatchTracer } from './implementation-8fGNr_Mq.js';
-import { p as paths, P as PromptResponse, g as CreatePromptBody, U as UpdatePromptBody, h as PromptData, F as FetchPolicy, i as Prompt, a as LangWatchSpan } from './types-DQiByKdr.js';
+export { F as FilterableBatchSpanProcessor, L as LangWatchExporter, S as SpanProcessingExcludeRule, g as getLangWatchLogger, d as getLangWatchTracer } from './implementation-7POf4yX4.js';
+import { p as paths, P as PromptResponse, g as CreatePromptBody, U as UpdatePromptBody, T as TagDefinition, h as CreatedTag, o as operations, i as PromptData, F as FetchPolicy, j as Prompt, a as LangWatchSpan } from './types-B4TSe7JR.js';
 import openApiCreateClient from 'openapi-fetch';
 import { z } from 'zod';
 export { l as attributes } from './types-DYLY4SyT.js';
@@ -27,6 +27,7 @@ interface InternalConfig {
 }
 
 type SyncAction = "created" | "updated" | "conflict" | "up_to_date";
+type AssignTagResult = NonNullable<operations["putApiPromptsByIdTagsByTag"]["responses"]["200"]["content"]["application/json"]>;
 type ConfigData = NonNullable<paths["/api/prompts/{id}/sync"]["post"]["requestBody"]>["content"]["application/json"]["configData"];
 interface SyncResult {
     action: SyncAction;
@@ -68,11 +69,15 @@ declare class PromptsApiService {
     /**
      * Fetches a single prompt by its ID.
      * @param id The prompt's unique identifier.
+     * @param options Optional parameters for the request.
+     * @param options.version Specific version to fetch (numeric string or "latest").
+     * @param options.tag Tag to fetch (e.g., "production", "staging", or a custom tag).
      * @returns Raw PromptResponse data.
      * @throws {PromptsApiError} If the API call fails.
      */
     get: (id: string, options?: {
         version?: string;
+        tag?: string;
     }) => Promise<PromptResponse>;
     /**
      * Validates if a prompt exists.
@@ -96,6 +101,42 @@ declare class PromptsApiService {
      * @throws {PromptsApiError} If the API call fails.
      */
     update(id: string, params: UpdatePromptBody): Promise<PromptResponse>;
+    /**
+     * Lists all prompt tags (built-in and custom) for the organization.
+     * @returns Array of tag definitions.
+     * @throws {PromptsApiError} If the API call fails.
+     */
+    listTags(): Promise<TagDefinition[]>;
+    /**
+     * Creates a custom prompt tag for the organization.
+     * @param params.name The tag name (must match /^[a-z][a-z0-9_-]*$/).
+     * @returns The created tag.
+     * @throws {PromptsApiError} If the API call fails.
+     */
+    createTag({ name }: {
+        name: string;
+    }): Promise<CreatedTag>;
+    /**
+     * Deletes a custom prompt tag by name.
+     * @param tagName The tag name to delete.
+     * @throws {PromptsApiError} If the API call fails.
+     */
+    deleteTag(tagName: string): Promise<void>;
+    /**
+     * Renames an existing prompt tag.
+     * @param tag The current tag name.
+     * @param name The new tag name.
+     * @throws {PromptsApiError} If the API call fails.
+     */
+    renameTag({ tag, name }: {
+        tag: string;
+        name: string;
+    }): Promise<void>;
+    assignTag({ id, tag, versionId, }: {
+        id: string;
+        tag: string;
+        versionId: string;
+    }): Promise<AssignTagResult>;
     /**
      * Deletes a prompt by its ID.
      * @param id The prompt's unique identifier.
@@ -284,6 +325,8 @@ declare class LocalPromptsService {
 interface GetPromptOptions {
     /** Specific version to fetch */
     version?: string;
+    /** Tag to fetch (e.g., "production", "staging", or a custom tag) */
+    tag?: string;
     /** Fetch policy to use */
     fetchPolicy?: FetchPolicy;
     /** Cache TTL in minutes (only used with CACHE_TTL policy) */
@@ -301,6 +344,18 @@ declare class PromptsFacade implements Pick<PromptsApiService, "sync" | "delete"
     private readonly promptsApiService;
     private readonly localPromptsService;
     private readonly cache;
+    readonly tags: {
+        assign(id: string, params: {
+            tag: string;
+            versionId: string;
+        }): Promise<AssignTagResult>;
+        list(): Promise<TagDefinition[]>;
+        create(params: {
+            name: string;
+        }): Promise<CreatedTag>;
+        delete(tagName: string): Promise<void>;
+        rename(oldName: string, newName: string): Promise<void>;
+    };
     constructor(config: InternalConfig & PromptsFacadeDependencies);
     /**
      * Creates a new prompt.
@@ -311,7 +366,11 @@ declare class PromptsFacade implements Pick<PromptsApiService, "sync" | "delete"
     create(data: CreatePromptBody): Promise<Prompt>;
     /**
      * Retrieves a prompt by handle or ID.
-     * @param handleOrId The prompt's handle or unique identifier.
+     *
+     * Supports shorthand `handle:tag` syntax — e.g. `get("pizza-prompt:production")`.
+     * Shorthand is parsed server-side; the SDK passes the string through as-is.
+     *
+     * @param handleOrId The prompt's handle, unique identifier, or `handle:tag` shorthand.
      * @param options Optional parameters for the request.
      * @returns The Prompt instance.
      * @throws {PromptsError} If the prompt is not found or the API call fails.
@@ -320,9 +379,6 @@ declare class PromptsFacade implements Pick<PromptsApiService, "sync" | "delete"
     private getMaterializedFirst;
     private getAlwaysFetch;
     private getMaterializedOnly;
-    /**
-     * Builds a cache key that includes both handle and version to prevent collisions.
-     */
     private buildCacheKey;
     private getCacheTtl;
     /**
@@ -357,7 +413,33 @@ declare class PromptsFacade implements Pick<PromptsApiService, "sync" | "delete"
  * Types for the Dataset API
  */
 /**
- * A single entry in a dataset
+ * A column type definition for a dataset.
+ */
+type DatasetColumnType = {
+    /** Column name */
+    name: string;
+    /** Column data type */
+    type: string;
+};
+/**
+ * Metadata for a dataset.
+ */
+type DatasetMetadata = {
+    /** Unique dataset identifier */
+    id: string;
+    /** Human-readable dataset name */
+    name: string;
+    /** URL-safe slug */
+    slug: string;
+    /** Column type definitions */
+    columnTypes: DatasetColumnType[];
+    /** When the dataset was created */
+    createdAt?: string;
+    /** When the dataset was last updated */
+    updatedAt?: string;
+};
+/**
+ * A single entry in a dataset.
  */
 type DatasetEntry<T extends Record<string, unknown> = Record<string, unknown>> = {
     /** Unique identifier for this entry */
@@ -374,76 +456,351 @@ type DatasetEntry<T extends Record<string, unknown> = Record<string, unknown>> =
     updatedAt: string;
 };
 /**
- * A dataset containing multiple entries
+ * A dataset containing metadata and entries.
  */
-type Dataset<T extends Record<string, unknown> = Record<string, unknown>> = {
+type Dataset<T extends Record<string, unknown> = Record<string, unknown>> = DatasetMetadata & {
     /** Array of dataset entries */
     entries: DatasetEntry<T>[];
 };
 /**
- * Options for getting a dataset
+ * Options for getting a dataset.
  */
 type GetDatasetOptions = {
     /** Skip tracing for this operation */
     ignoreTracing?: boolean;
 };
+/**
+ * Options for listing datasets.
+ */
+type ListDatasetsOptions = {
+    /** Page number (1-based) */
+    page?: number;
+    /** Number of items per page */
+    limit?: number;
+};
+/**
+ * Pagination metadata returned by paginated API endpoints.
+ */
+type Pagination = {
+    /** Current page number (1-based) */
+    page: number;
+    /** Number of items per page */
+    limit: number;
+    /** Total number of items across all pages */
+    total: number;
+    /** Total number of pages */
+    totalPages: number;
+};
+/**
+ * A dataset in a list response, including record count.
+ */
+type DatasetListItem = DatasetMetadata & {
+    /** Number of records in the dataset */
+    recordCount: number;
+};
+/**
+ * Paginated response wrapper for dataset endpoints.
+ */
+type PaginatedResponse<T> = {
+    data: T[];
+    pagination: Pagination;
+};
+/**
+ * API response for listing datasets.
+ */
+type ListDatasetsApiResponse = PaginatedResponse<DatasetListItem>;
+/**
+ * Options for creating a dataset.
+ */
+type CreateDatasetOptions = {
+    /** Dataset name */
+    name: string;
+    /** Column type definitions (defaults to empty array) */
+    columnTypes?: DatasetColumnType[];
+};
+/**
+ * Options for updating a dataset.
+ */
+type UpdateDatasetOptions = {
+    /** New dataset name */
+    name?: string;
+    /** New column type definitions */
+    columnTypes?: DatasetColumnType[];
+};
+/**
+ * API response for a record.
+ */
+type DatasetRecordResponse = {
+    id: string;
+    datasetId: string;
+    projectId: string;
+    entry: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * API response for batch create records.
+ */
+type BatchCreateRecordsResponse = {
+    data: DatasetRecordResponse[];
+};
+/**
+ * API response for deleting records.
+ */
+type DeleteRecordsResponse = {
+    deletedCount: number;
+};
+/**
+ * API response for uploading a file.
+ * Covers both upload-to-existing (records) and create-from-file (recordsCreated, datasetId) responses.
+ */
+type UploadResponse = {
+    dataset?: DatasetMetadata;
+    records?: DatasetRecordResponse[];
+    recordsCreated?: number;
+    datasetId?: string;
+};
+/**
+ * Options for listing records in a dataset.
+ */
+type ListRecordsOptions = {
+    /** Page number (1-based) */
+    page?: number;
+    /** Number of items per page */
+    limit?: number;
+};
+/**
+ * API response for listing records in a dataset.
+ */
+type ListRecordsApiResponse = PaginatedResponse<DatasetRecordResponse>;
+/**
+ * API response for creating a dataset from a file upload.
+ */
+type CreateFromUploadResponse = DatasetMetadata & {
+    /** Number of records created from the uploaded file */
+    recordsCreated: number;
+};
 
 type DatasetsFacadeConfig = {
     langwatchApiClient: LangwatchApiClient;
     logger: Logger;
+    endpoint: string;
+    apiKey: string;
 };
 /**
- * Facade for dataset operations
- *
- * Provides a simple interface for fetching datasets from LangWatch.
+ * Facade for dataset operations in the LangWatch SDK.
+ * Provides a simplified interface for managing datasets, records, and file uploads.
  *
  * @example
  * ```typescript
  * const langwatch = new LangWatch({ apiKey: "your-api-key" });
  *
+ * // List all datasets
+ * const datasets = await langwatch.datasets.list();
+ *
  * // Get a dataset by slug or ID
  * const dataset = await langwatch.datasets.get("my-dataset");
  *
- * // Use with evaluation
- * const evaluation = langwatch.experiments.init("my-experiment");
- * await evaluation.run(dataset.entries.map(e => e.entry), async ({ item, index }) => {
- *   const output = await myLLM(item.input);
- *   await evaluation.evaluate("my-evaluator", {
- *     data: { input: item.input, output, expected_output: item.expected_output },
- *     settings: {}
- *   });
+ * // Create a new dataset
+ * const newDataset = await langwatch.datasets.create({
+ *   name: "my-dataset",
+ *   columnTypes: [{ name: "input", type: "string" }],
  * });
+ *
+ * // Update a dataset
+ * const updated = await langwatch.datasets.update("my-dataset", { name: "new-name" });
+ *
+ * // Delete a dataset
+ * const archived = await langwatch.datasets.delete("my-dataset");
+ *
+ * // Create records
+ * const records = await langwatch.datasets.createRecords("my-dataset", [
+ *   { input: "hello", output: "world" },
+ * ]);
+ *
+ * // Update a record
+ * const record = await langwatch.datasets.updateRecord("my-dataset", "rec-1", { input: "updated" });
+ *
+ * // Delete records
+ * const result = await langwatch.datasets.deleteRecords("my-dataset", ["rec-1", "rec-2"]);
+ *
+ * // Upload a file (append to existing or create new)
+ * const uploadResult = await langwatch.datasets.upload("my-dataset", file);
+ *
+ * // Upload with replace strategy (delete all records first)
+ * await langwatch.datasets.upload("my-dataset", file, { ifExists: "replace" });
  * ```
  */
 declare class DatasetsFacade {
     #private;
     constructor(config: DatasetsFacadeConfig);
     /**
-     * Fetches a dataset by its slug or ID
+     * Lists all datasets for the project, with optional pagination.
+     *
+     * @param options - Pagination options (page, limit)
+     * @returns Paginated list of datasets with metadata
+     */
+    list: (options?: ListDatasetsOptions) => Promise<ListDatasetsApiResponse>;
+    /**
+     * Creates a new dataset.
+     *
+     * @param options - Dataset creation options (name, columnTypes)
+     * @returns The created dataset metadata
+     */
+    create: (options: CreateDatasetOptions) => Promise<DatasetMetadata>;
+    /**
+     * Fetches a dataset by its slug or ID, returning metadata and entries.
      *
      * @param slugOrId - The slug or ID of the dataset to fetch
      * @param options - Optional configuration
-     * @returns The dataset with all entries
+     * @returns The dataset with metadata and entries
      *
      * @example
      * ```typescript
      * // Get dataset by slug
      * const dataset = await langwatch.datasets.get("product-qa");
      *
-     * // Get dataset by ID
-     * const dataset = await langwatch.datasets.get("ds_abc123");
-     *
      * // Typed dataset
      * type MyDatasetEntry = { input: string; expected_output: string; };
      * const dataset = await langwatch.datasets.get<MyDatasetEntry>("my-dataset");
      *
      * // Iterate over entries
      * for (const entry of dataset.entries) {
-     *   console.log(entry.entry.input);  // typed as string
+     *   console.log(entry.entry.input);
      * }
      * ```
      */
     get: <T extends Record<string, unknown> = Record<string, unknown>>(slugOrId: string, options?: GetDatasetOptions) => Promise<Dataset<T>>;
+    /**
+     * Updates a dataset by its slug or ID.
+     *
+     * @param slugOrId - The slug or ID of the dataset to update
+     * @param options - Fields to update (name, columnTypes)
+     * @returns The updated dataset metadata
+     */
+    update: (slugOrId: string, options: UpdateDatasetOptions) => Promise<DatasetMetadata>;
+    /**
+     * Deletes (archives) a dataset by its slug or ID.
+     *
+     * @param slugOrId - The slug or ID of the dataset to delete
+     * @returns The archived dataset metadata
+     */
+    delete: (slugOrId: string) => Promise<DatasetMetadata>;
+    /**
+     * Creates records in a dataset in batch.
+     *
+     * @param slugOrId - The slug or ID of the dataset
+     * @param entries - Array of record entries to create
+     * @returns The created records with IDs
+     */
+    createRecords: (slugOrId: string, entries: Record<string, unknown>[]) => Promise<BatchCreateRecordsResponse>;
+    /**
+     * Updates a single record in a dataset.
+     *
+     * @param slugOrId - The slug or ID of the dataset
+     * @param recordId - The ID of the record to update
+     * @param entry - The updated entry data
+     * @returns The updated record
+     */
+    updateRecord: (slugOrId: string, recordId: string, entry: Record<string, unknown>) => Promise<DatasetRecordResponse>;
+    /**
+     * Deletes records from a dataset by IDs.
+     *
+     * @param slugOrId - The slug or ID of the dataset
+     * @param recordIds - Array of record IDs to delete
+     * @returns Object with the count of deleted records
+     */
+    deleteRecords: (slugOrId: string, recordIds: string[]) => Promise<DeleteRecordsResponse>;
+    /**
+     * Lists records in a dataset with optional pagination.
+     *
+     * @param slugOrId - The slug or ID of the dataset
+     * @param options - Pagination options (page, limit)
+     * @returns Paginated list of records
+     *
+     * @example
+     * ```typescript
+     * // List first page of records
+     * const result = await langwatch.datasets.listRecords("my-dataset");
+     *
+     * // With pagination
+     * const page2 = await langwatch.datasets.listRecords("my-dataset", { page: 2, limit: 25 });
+     * ```
+     */
+    listRecords: (slugOrId: string, options?: ListRecordsOptions) => Promise<ListRecordsApiResponse>;
+    /**
+     * Uploads a file to a dataset with a configurable strategy for handling existing datasets.
+     *
+     * Strategies:
+     * - `"append"` (default): Upload to existing dataset; if not found, create a new one.
+     * - `"replace"`: Delete all existing records, then upload; if not found, create a new one.
+     * - `"error"`: Throw a 409 error if the dataset already exists; if not found, create a new one.
+     *
+     * @param slugOrId - The slug or ID of the dataset
+     * @param file - The file to upload (File or Blob)
+     * @param options - Upload options including the ifExists strategy
+     * @returns The upload result
+     *
+     * @example
+     * ```typescript
+     * const file = new File(["input,output\nhello,world"], "data.csv", { type: "text/csv" });
+     *
+     * // Append to existing or create new
+     * await langwatch.datasets.upload("my-dataset", file);
+     *
+     * // Replace all records
+     * await langwatch.datasets.upload("my-dataset", file, { ifExists: "replace" });
+     *
+     * // Fail if dataset already exists
+     * await langwatch.datasets.upload("my-dataset", file, { ifExists: "error" });
+     * ```
+     */
+    upload: (slugOrId: string, file: File | Blob, options?: {
+        ifExists?: "append" | "replace" | "error";
+    }) => Promise<UploadResponse>;
+}
+
+/**
+ * Errors for the Dataset API
+ */
+/**
+ * Base error for all dataset operations.
+ */
+declare class DatasetError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a dataset is not found (404).
+ */
+declare class DatasetNotFoundError extends DatasetError {
+    constructor(slugOrId: string);
+}
+/**
+ * Error from the Dataset API with operation context.
+ * Aligns with PromptsApiError pattern: includes operation and originalError fields.
+ */
+declare class DatasetApiError extends DatasetError {
+    readonly status: number;
+    readonly operation: string;
+    readonly originalError?: unknown;
+    constructor(message: string, status: number, operation: string, originalError?: unknown);
+}
+/**
+ * Thrown for client-side validation failures (e.g. empty name, no update fields, empty entries).
+ * Distinguished from DatasetApiError which represents server-side errors.
+ */
+declare class DatasetValidationError extends DatasetError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a dataset operation exceeds the plan limit (403).
+ * The message includes the upgrade/subscription URL from the server.
+ */
+declare class DatasetPlanLimitError extends DatasetError {
+    readonly limitType: string;
+    readonly current?: number;
+    readonly max?: number;
+    constructor(message: string, originalError?: unknown);
 }
 
 /**
@@ -1231,6 +1588,8 @@ declare class LangWatch {
 type EvaluatorResponse = NonNullable<paths["/api/evaluators"]["get"]["responses"]["200"]["content"]["application/json"]>[number];
 type EvaluatorField = EvaluatorResponse["fields"][number];
 type CreateEvaluatorBody = NonNullable<paths["/api/evaluators"]["post"]["requestBody"]>["content"]["application/json"];
+type UpdateEvaluatorBody = NonNullable<paths["/api/evaluators/{id}"]["put"]["requestBody"]>["content"]["application/json"];
+type DeleteEvaluatorResponse = paths["/api/evaluators/{id}"]["delete"]["responses"]["200"]["content"]["application/json"];
 
 /**
  * Service for retrieving evaluator resources via the LangWatch API.
@@ -1253,6 +1612,14 @@ declare class EvaluatorsApiService {
      * Creates a new evaluator.
      */
     create(params: CreateEvaluatorBody): Promise<EvaluatorResponse>;
+    /**
+     * Updates an evaluator by its ID.
+     */
+    update(id: string, params: UpdateEvaluatorBody): Promise<EvaluatorResponse>;
+    /**
+     * Deletes (archives) an evaluator by its ID.
+     */
+    delete(id: string): Promise<DeleteEvaluatorResponse>;
 }
 
 declare class EvaluatorsApiError extends Error {
@@ -1266,4 +1633,4 @@ declare const logger: {
     NoOpLogger: typeof NoOpLogger;
 };
 
-export { type CreateEvaluatorBody, type EvaluateOptions, type EvaluationCost, EvaluationError, type EvaluationResult, type EvaluationStatus, EvaluationsApiError, EvaluationsFacade, EvaluatorCallError, EvaluatorError, type EvaluatorField, EvaluatorNotFoundError, type EvaluatorResponse, EvaluatorsApiError, EvaluatorsApiService, Experiment, ExperimentApiError, ExperimentError, type EvaluateOptions$1 as ExperimentEvaluateOptions, type EvaluationResult$1 as ExperimentEvaluationResult, type EvaluationStatus$1 as ExperimentEvaluationStatus, ExperimentInitError, type ExperimentInitOptions, ExperimentsFacade, FetchPolicy, type GetPromptOptions, LangWatch, type LogOptions, type RunCallback, type RunContext, type RunOptions, type TargetInfo, type TargetMetadata, TargetMetadataConflictError, type TargetType, logger };
+export { type BatchCreateRecordsResponse, type CreateDatasetOptions, type CreateEvaluatorBody, type CreateFromUploadResponse, type Dataset, DatasetApiError, type DatasetColumnType, type DatasetEntry, DatasetError, type DatasetListItem, type DatasetMetadata, DatasetNotFoundError, DatasetPlanLimitError, type DatasetRecordResponse, DatasetValidationError, DatasetsFacade, type DeleteRecordsResponse, type EvaluateOptions, type EvaluationCost, EvaluationError, type EvaluationResult, type EvaluationStatus, EvaluationsApiError, EvaluationsFacade, EvaluatorCallError, EvaluatorError, type EvaluatorField, EvaluatorNotFoundError, type EvaluatorResponse, EvaluatorsApiError, EvaluatorsApiService, Experiment, ExperimentApiError, ExperimentError, type EvaluateOptions$1 as ExperimentEvaluateOptions, type EvaluationResult$1 as ExperimentEvaluationResult, type EvaluationStatus$1 as ExperimentEvaluationStatus, ExperimentInitError, type ExperimentInitOptions, ExperimentsFacade, FetchPolicy, type GetDatasetOptions, type GetPromptOptions, LangWatch, type ListDatasetsApiResponse, type ListDatasetsOptions, type ListRecordsApiResponse, type ListRecordsOptions, type LogOptions, type PaginatedResponse, type Pagination, type RunCallback, type RunContext, type RunOptions, type TargetInfo, type TargetMetadata, TargetMetadataConflictError, type TargetType, type UpdateDatasetOptions, type UploadResponse, logger };