@orchata-ai/sdk 0.1.0

package/dist/client-Bs_xoN9p.d.cts

@@ -0,0 +1,752 @@
+/**
+ * Runtime-agnostic HTTP client using native fetch
+ */
+interface FetchClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout: number;
+    fetch: typeof fetch;
+}
+type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+interface RequestOptions {
+    method?: HttpMethod;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | undefined>;
+    timeout?: number;
+}
+/**
+ * Low-level HTTP client for making API requests.
+ * Uses native fetch for cross-runtime compatibility.
+ */
+declare class FetchClient {
+    private readonly config;
+    constructor(config: FetchClientConfig);
+    /**
+     * Make an HTTP request to the API.
+     */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Make a GET request.
+     */
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    /**
+     * Make a POST request.
+     */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Make a PATCH request.
+     */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Make a DELETE request.
+     */
+    delete<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    /**
+     * Make a multipart/form-data POST request.
+     */
+    postFormData<T>(path: string, formData: FormData): Promise<T>;
+    /**
+     * Build the full URL with query parameters.
+     */
+    private buildUrl;
+    /**
+     * Handle error responses from the API.
+     */
+    private handleErrorResponse;
+}
+
+/**
+ * Orchata SDK Types
+ *
+ * These types can be regenerated from the OpenAPI spec using:
+ *   bun run generate-types
+ */
+type LucideIcon = "folder" | "book" | "file-text" | "database" | "package" | "archive" | "briefcase" | "inbox" | "layers" | "box";
+type DocumentStatus = "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED";
+type SpaceStatus = "active" | "archived" | "all";
+type RelevanceMethod = "keyword" | "embedding" | "hybrid";
+type MatchReason = "keyword_match" | "embedding_similarity" | "both";
+interface Space {
+    id: string;
+    orgId: string;
+    name: string;
+    slug: string;
+    icon: LucideIcon;
+    description: string;
+    isArchived: boolean;
+    archivedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateSpaceParams {
+    name: string;
+    description: string;
+    icon: LucideIcon;
+}
+interface UpdateSpaceParams {
+    name?: string;
+    description?: string;
+    icon?: LucideIcon;
+    slug?: string;
+    isArchived?: boolean;
+}
+interface ListSpacesParams {
+    page?: number;
+    pageSize?: number;
+    status?: SpaceStatus;
+}
+interface ListSpacesResponse {
+    spaces: Space[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+interface SpaceResponse {
+    space: Space;
+}
+interface Document {
+    id: string;
+    orgId: string;
+    spaceId: string;
+    filename: string;
+    mimeType: string;
+    fileSize: string;
+    storageUrl: string;
+    status: DocumentStatus;
+    errorMessage: string | null;
+    embeddingModel: string;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface UploadDocumentParams {
+    spaceId: string;
+    content: string;
+    filename?: string;
+    embeddingModel?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UploadDocumentFileParams {
+    spaceId: string;
+    file: File | Blob;
+    filename?: string;
+    embeddingModel?: string;
+    metadata?: Record<string, unknown>;
+}
+interface BatchDocumentItem {
+    filename: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface BatchUploadParams {
+    spaceId: string;
+    documents: BatchDocumentItem[];
+}
+interface BatchUploadResponse {
+    successful: Array<{
+        filename: string;
+        documentId: string;
+        status: string;
+    }>;
+    failed: Array<{
+        filename: string;
+        error: string;
+    }>;
+    totalSuccessful: number;
+    totalFailed: number;
+}
+interface UpdateDocumentParams {
+    spaceId: string;
+    status?: DocumentStatus;
+    errorMessage?: string | null;
+    metadata?: Record<string, unknown>;
+}
+interface ListDocumentsParams {
+    spaceId: string;
+    page?: number;
+    pageSize?: number;
+    status?: DocumentStatus;
+}
+interface ListDocumentsResponse {
+    documents: Document[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+interface DocumentResponse {
+    document: Document;
+}
+interface DocumentContentResponse {
+    id: string;
+    filename: string;
+    content: string;
+}
+interface QueryParams {
+    query: string;
+    spaceIds: string | string[];
+    topK?: number;
+    threshold?: number;
+    metadata?: Record<string, unknown>;
+    groupBySpace?: boolean;
+}
+interface QueryResultChunk {
+    id: string;
+    content: string;
+    chunkIndex: number;
+}
+interface QueryResultDocument {
+    id: string;
+    filename: string;
+    metadata: Record<string, unknown>;
+}
+interface QueryResultSpace {
+    id: string;
+    name: string;
+    description: string;
+}
+interface QueryResultItem {
+    chunk: QueryResultChunk;
+    document: QueryResultDocument;
+    space: QueryResultSpace;
+    similarity: number;
+    metadata: Record<string, unknown>;
+}
+interface QueryResponse {
+    results: QueryResultItem[];
+    totalResults: number;
+    groupedBySpace?: Record<string, {
+        space: QueryResultSpace;
+        chunks: QueryResultItem[];
+        totalMatches: number;
+    }>;
+}
+interface SmartQueryParams {
+    query: string;
+    maxSpaces?: number;
+    relevanceMethod?: RelevanceMethod;
+    keywordWeight?: number;
+}
+interface SmartQueryResultSpace {
+    space: QueryResultSpace;
+    relevanceScore: number;
+    matchReason: MatchReason;
+}
+interface SmartQueryResponse {
+    relevantSpaces: SmartQueryResultSpace[];
+    totalSpaces: number;
+}
+interface DeleteResponse {
+    success: boolean;
+    message: string;
+}
+interface OrchataConfig {
+    /**
+     * Your Orchata API key.
+     * Can be obtained from the Orchata dashboard.
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Orchata API.
+     * @default "https://api.orchata.ai"
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom fetch implementation.
+     * Useful for testing or custom HTTP handling.
+     */
+    fetch?: typeof fetch;
+}
+
+/**
+ * Documents Resource
+ *
+ * Manage documents within spaces in Orchata.
+ */
+
+/**
+ * Documents API resource.
+ *
+ * @example
+ * ```typescript
+ * // List documents in a space
+ * const { documents } = await client.documents.list({ spaceId: 'space_123' });
+ *
+ * // Upload a document with raw content
+ * const { document } = await client.documents.upload({
+ *   spaceId: 'space_123',
+ *   content: '# My Document\n\nContent here...',
+ *   filename: 'my-doc.md'
+ * });
+ *
+ * // Upload a file (browser only)
+ * const { document } = await client.documents.uploadFile({
+ *   spaceId: 'space_123',
+ *   file: fileInput.files[0]
+ * });
+ *
+ * // Get processed content
+ * const { content } = await client.documents.getContent('doc_123', 'space_123');
+ * ```
+ */
+declare class Documents {
+    private readonly client;
+    constructor(client: FetchClient);
+    /**
+     * List documents in a space.
+     *
+     * @param params - Query parameters including spaceId
+     * @returns Paginated list of documents
+     *
+     * @example
+     * ```typescript
+     * // List all documents
+     * const { documents, total } = await client.documents.list({
+     *   spaceId: 'space_123'
+     * });
+     *
+     * // Filter by status
+     * const { documents } = await client.documents.list({
+     *   spaceId: 'space_123',
+     *   status: 'COMPLETED'
+     * });
+     *
+     * // Paginate
+     * const { documents, totalPages } = await client.documents.list({
+     *   spaceId: 'space_123',
+     *   page: 2,
+     *   pageSize: 10
+     * });
+     * ```
+     */
+    list(params: ListDocumentsParams): Promise<ListDocumentsResponse>;
+    /**
+     * Get a specific document by ID.
+     *
+     * @param id - The document ID
+     * @param spaceId - The space ID containing the document
+     * @returns The document
+     *
+     * @example
+     * ```typescript
+     * const { document } = await client.documents.get('doc_123', 'space_123');
+     * console.log(document.filename, document.status);
+     * ```
+     */
+    get(id: string, spaceId: string): Promise<DocumentResponse>;
+    /**
+     * Upload a document with raw content.
+     *
+     * This is the recommended method for programmatic uploads,
+     * especially from AI agents or backend services.
+     *
+     * @param params - Upload parameters
+     * @returns The created document
+     *
+     * @example
+     * ```typescript
+     * const { document } = await client.documents.upload({
+     *   spaceId: 'space_123',
+     *   content: '# API Documentation\n\nThis document describes...',
+     *   filename: 'api-docs.md',
+     *   metadata: { category: 'technical', version: '1.0' }
+     * });
+     * ```
+     */
+    upload(params: UploadDocumentParams): Promise<DocumentResponse>;
+    /**
+     * Upload a file as a document.
+     *
+     * This method is useful for browser-based uploads where
+     * you have access to File objects.
+     *
+     * @param params - Upload parameters including the file
+     * @returns The created document
+     *
+     * @example
+     * ```typescript
+     * // Browser file input
+     * const fileInput = document.getElementById('file') as HTMLInputElement;
+     * const { document } = await client.documents.uploadFile({
+     *   spaceId: 'space_123',
+     *   file: fileInput.files[0]
+     * });
+     * ```
+     */
+    uploadFile(params: UploadDocumentFileParams): Promise<DocumentResponse>;
+    /**
+     * Upload multiple documents in a single request.
+     *
+     * Maximum 100 documents per batch. Each document is processed
+     * independently, so partial failures are possible.
+     *
+     * @param params - Batch upload parameters
+     * @returns Results for each document
+     *
+     * @example
+     * ```typescript
+     * const result = await client.documents.batchUpload({
+     *   spaceId: 'space_123',
+     *   documents: [
+     *     { filename: 'doc1.md', content: '# Doc 1\n\nContent...' },
+     *     { filename: 'doc2.md', content: '# Doc 2\n\nContent...' },
+     *   ]
+     * });
+     *
+     * console.log(`Uploaded: ${result.totalSuccessful}`);
+     * console.log(`Failed: ${result.totalFailed}`);
+     * ```
+     */
+    batchUpload(params: BatchUploadParams): Promise<BatchUploadResponse>;
+    /**
+     * Update a document's metadata or status.
+     *
+     * @param id - The document ID
+     * @param params - Fields to update (includes spaceId)
+     * @returns The updated document
+     *
+     * @example
+     * ```typescript
+     * const { document } = await client.documents.update('doc_123', {
+     *   spaceId: 'space_123',
+     *   metadata: { reviewed: true }
+     * });
+     * ```
+     */
+    update(id: string, params: UpdateDocumentParams): Promise<DocumentResponse>;
+    /**
+     * Delete a document.
+     *
+     * This permanently removes the document and its vectors.
+     *
+     * @param id - The document ID
+     * @param spaceId - The space ID containing the document
+     * @returns Deletion confirmation
+     *
+     * @example
+     * ```typescript
+     * await client.documents.delete('doc_123', 'space_123');
+     * ```
+     */
+    delete(id: string, spaceId: string): Promise<DeleteResponse>;
+    /**
+     * Get the processed content of a document.
+     *
+     * Only available for documents with COMPLETED status.
+     *
+     * @param id - The document ID
+     * @param spaceId - The space ID containing the document
+     * @returns The processed document content
+     *
+     * @example
+     * ```typescript
+     * const { content, filename } = await client.documents.getContent(
+     *   'doc_123',
+     *   'space_123'
+     * );
+     * console.log(content);
+     * ```
+     */
+    getContent(id: string, spaceId: string): Promise<DocumentContentResponse>;
+}
+
+/**
+ * Queries Resource
+ *
+ * Query your knowledge base using semantic search.
+ */
+
+/**
+ * Queries API resource.
+ *
+ * Note: These methods are also exposed directly on the Orchata client
+ * as `client.query()` and `client.smartQuery()` for convenience.
+ */
+declare class Queries {
+    private readonly client;
+    constructor(client: FetchClient);
+    /**
+     * Query one or more spaces for similar content.
+     *
+     * Accepts a single space ID or array of space IDs. Results are merged
+     * and globally ranked by default, or can be grouped by space.
+     *
+     * @param params - Query parameters
+     * @returns Query results with matching chunks
+     *
+     * @example
+     * ```typescript
+     * // Simple query
+     * const { results } = await client.query({
+     *   spaceIds: 'space_123',
+     *   query: 'How do I reset my password?'
+     * });
+     *
+     * // Query multiple spaces
+     * const { results } = await client.query({
+     *   spaceIds: ['space_123', 'space_456'],
+     *   query: 'How do I reset my password?',
+     *   topK: 5
+     * });
+     *
+     * // Query with metadata filter
+     * const { results } = await client.query({
+     *   spaceIds: 'space_123',
+     *   query: 'API documentation',
+     *   metadata: { category: 'docs' }
+     * });
+     *
+     * // Group results by space
+     * const { groupedBySpace } = await client.query({
+     *   spaceIds: ['space_123', 'space_456'],
+     *   query: 'authentication',
+     *   groupBySpace: true
+     * });
+     * ```
+     */
+    query(params: QueryParams): Promise<QueryResponse>;
+    /**
+     * Discover the most relevant spaces for a query.
+     *
+     * Uses hybrid keyword and embedding similarity to find which
+     * spaces are most likely to contain relevant content. This is
+     * useful when you have many spaces and want to narrow down
+     * which ones to query.
+     *
+     * @param params - Smart query parameters
+     * @returns Relevant spaces ranked by relevance
+     *
+     * @example
+     * ```typescript
+     * // Find relevant spaces
+     * const { relevantSpaces } = await client.smartQuery({
+     *   query: 'How do I authenticate users?',
+     *   maxSpaces: 3
+     * });
+     *
+     * // Use different relevance methods
+     * const { relevantSpaces } = await client.smartQuery({
+     *   query: 'authentication',
+     *   relevanceMethod: 'keyword',  // or 'embedding' or 'hybrid'
+     * });
+     *
+     * // Full workflow: discover then query
+     * const { relevantSpaces } = await client.smartQuery({
+     *   query: 'user authentication'
+     * });
+     *
+     * const { results } = await client.query({
+     *   spaceIds: relevantSpaces.map(s => s.space.id),
+     *   query: 'user authentication'
+     * });
+     * ```
+     */
+    smartQuery(params: SmartQueryParams): Promise<SmartQueryResponse>;
+}
+
+/**
+ * Spaces Resource
+ *
+ * Manage knowledge base spaces in Orchata.
+ */
+
+/**
+ * Spaces API resource.
+ *
+ * @example
+ * ```typescript
+ * // List all spaces
+ * const { spaces, total } = await client.spaces.list();
+ *
+ * // Create a new space
+ * const { space } = await client.spaces.create({
+ *   name: 'Documentation',
+ *   description: 'Product documentation and guides',
+ *   icon: 'book'
+ * });
+ *
+ * // Get a specific space
+ * const { space } = await client.spaces.get('space_123');
+ *
+ * // Update a space
+ * const { space } = await client.spaces.update('space_123', {
+ *   name: 'Updated Name'
+ * });
+ *
+ * // Delete a space
+ * await client.spaces.delete('space_123');
+ * ```
+ */
+declare class Spaces {
+    private readonly client;
+    constructor(client: FetchClient);
+    /**
+     * List all spaces in your organization.
+     *
+     * @param params - Optional pagination and filter parameters
+     * @returns Paginated list of spaces
+     *
+     * @example
+     * ```typescript
+     * // List all active spaces
+     * const { spaces, total } = await client.spaces.list();
+     *
+     * // List archived spaces
+     * const { spaces } = await client.spaces.list({ status: 'archived' });
+     *
+     * // Paginate through spaces
+     * const { spaces, totalPages } = await client.spaces.list({
+     *   page: 2,
+     *   pageSize: 10
+     * });
+     * ```
+     */
+    list(params?: ListSpacesParams): Promise<ListSpacesResponse>;
+    /**
+     * Get a specific space by ID.
+     *
+     * @param id - The space ID
+     * @returns The space
+     *
+     * @example
+     * ```typescript
+     * const { space } = await client.spaces.get('space_123');
+     * console.log(space.name, space.description);
+     * ```
+     */
+    get(id: string): Promise<SpaceResponse>;
+    /**
+     * Create a new space.
+     *
+     * @param params - Space creation parameters
+     * @returns The created space
+     *
+     * @example
+     * ```typescript
+     * const { space } = await client.spaces.create({
+     *   name: 'Knowledge Base',
+     *   description: 'Company knowledge and documentation',
+     *   icon: 'database'
+     * });
+     * ```
+     */
+    create(params: CreateSpaceParams): Promise<SpaceResponse>;
+    /**
+     * Update an existing space.
+     *
+     * @param id - The space ID
+     * @param params - Fields to update
+     * @returns The updated space
+     *
+     * @example
+     * ```typescript
+     * const { space } = await client.spaces.update('space_123', {
+     *   name: 'Updated Name',
+     *   description: 'New description'
+     * });
+     * ```
+     */
+    update(id: string, params: UpdateSpaceParams): Promise<SpaceResponse>;
+    /**
+     * Delete (archive) a space.
+     *
+     * @param id - The space ID
+     * @returns Deletion confirmation
+     *
+     * @example
+     * ```typescript
+     * await client.spaces.delete('space_123');
+     * ```
+     */
+    delete(id: string): Promise<DeleteResponse>;
+}
+
+/**
+ * Orchata Client
+ *
+ * The main entry point for the Orchata SDK.
+ */
+
+/**
+ * Orchata SDK Client
+ *
+ * @example
+ * ```typescript
+ * import { Orchata } from '@orchata-ai/sdk';
+ *
+ * const client = new Orchata({ apiKey: 'oai_xxx' });
+ *
+ * // List spaces
+ * const { spaces } = await client.spaces.list();
+ *
+ * // Query documents
+ * const results = await client.query({
+ *   spaceIds: ['space_123'],
+ *   query: 'What is the meaning of life?'
+ * });
+ * ```
+ */
+declare class Orchata {
+    readonly spaces: Spaces;
+    readonly documents: Documents;
+    /**
+     * Query one or more spaces for similar content.
+     *
+     * @example
+     * ```typescript
+     * // Query a single space
+     * const results = await client.query({
+     *   spaceIds: 'space_123',
+     *   query: 'How do I reset my password?'
+     * });
+     *
+     * // Query multiple spaces
+     * const results = await client.query({
+     *   spaceIds: ['space_123', 'space_456'],
+     *   query: 'How do I reset my password?',
+     *   topK: 5
+     * });
+     *
+     * // Query with metadata filter
+     * const results = await client.query({
+     *   spaceIds: 'space_123',
+     *   query: 'API documentation',
+     *   metadata: { category: 'docs' }
+     * });
+     * ```
+     */
+    readonly query: Queries["query"];
+    /**
+     * Discover the most relevant spaces for a query.
+     *
+     * Uses hybrid keyword and embedding similarity to find
+     * which spaces are most likely to contain relevant content.
+     *
+     * @example
+     * ```typescript
+     * const { relevantSpaces } = await client.smartQuery({
+     *   query: 'How do I authenticate users?',
+     *   maxSpaces: 3
+     * });
+     *
+     * // Use the discovered spaces for a full query
+     * const results = await client.query({
+     *   spaceIds: relevantSpaces.map(s => s.space.id),
+     *   query: 'How do I authenticate users?'
+     * });
+     * ```
+     */
+    readonly smartQuery: Queries["smartQuery"];
+    private readonly _client;
+    private readonly _queries;
+    constructor(config: OrchataConfig);
+}
+
+export { Queries as A, type BatchDocumentItem as B, type CreateSpaceParams as C, type DocumentStatus as D, type LucideIcon as L, type MatchReason as M, Orchata as O, type QueryParams as Q, type RelevanceMethod as R, type SpaceStatus as S, type UpdateSpaceParams as U, type OrchataConfig as a, type DeleteResponse as b, type Space as c, type ListSpacesParams as d, type ListSpacesResponse as e, type SpaceResponse as f, type Document as g, type UploadDocumentParams as h, type UploadDocumentFileParams as i, type BatchUploadParams as j, type BatchUploadResponse as k, type UpdateDocumentParams as l, type ListDocumentsParams as m, type ListDocumentsResponse as n, type DocumentResponse as o, type DocumentContentResponse as p, type QueryResultChunk as q, type QueryResultDocument as r, type QueryResultSpace as s, type QueryResultItem as t, type QueryResponse as u, type SmartQueryParams as v, type SmartQueryResultSpace as w, type SmartQueryResponse as x, Spaces as y, Documents as z };