// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as KnowledgeBasesAPI from './knowledge-bases';
import * as FilesAPI from '../files';
import * as KnowledgeBasesFilesAPI from './files';
import {
  FileBatchAddParams,
  FileBatchRemoveParams,
  FileListParams,
  FileMoveParams,
  Files,
  KBAPIResponseFileOperation,
  KBAPIResponseMoveFiles,
} from './files';
import * as UsersAPI from '../users/users';
import { APIPromise } from '../../core/api-promise';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class KnowledgeBases extends APIResource {
  files: KnowledgeBasesFilesAPI.Files = new KnowledgeBasesFilesAPI.Files(this._client);

  /**
   * Create a new knowledge base with specified properties.
   *
   * - Requires KNOWLEDGE_BASE_CREATE permission
   * - Returns the created knowledge base with complete metadata
   */
  create(body: KnowledgeBaseCreateParams, options?: RequestOptions): APIPromise<APIResponseKnowledgeBase> {
    return this._client.post('/knowledge-bases', { body, ...options });
  }

  /**
   * Retrieve detailed information about a specific knowledge base.
   *
   * - Requires KNOWLEDGE_BASE_READ permission
   * - Checks access permissions and enabled status
   * - Returns complete knowledge base metadata
   */
  retrieve(id: string, options?: RequestOptions): APIPromise<APIResponseKnowledgeBase> {
    return this._client.get(path`/knowledge-bases/${id}`, options);
  }

  /**
   * Update knowledge base properties.
   *
   * - Requires KNOWLEDGE_BASE_UPDATE permission
   * - Only the owner can update the knowledge base
   * - All fields are optional
   */
  update(
    id: string,
    body: KnowledgeBaseUpdateParams,
    options?: RequestOptions,
  ): APIPromise<APIResponseKnowledgeBase> {
    return this._client.patch(path`/knowledge-bases/${id}`, { body, ...options });
  }

  /**
   * Get paginated list of knowledge bases with optional filtering and search.
   *
   * - Requires KNOWLEDGE_BASE_READ permission
   * - Returns knowledge bases accessible by the current user
   * - Supports filtering by type (personal/shared) and enabled status
   */
  list(
    query: KnowledgeBaseListParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<APIResponseKnowledgeBaseList> {
    return this._client.get('/knowledge-bases', { query, ...options });
  }

  /**
   * Permanently delete a knowledge base.
   *
   * - Requires KNOWLEDGE_BASE_DELETE permission
   * - Only the owner can delete the knowledge base
   * - Cascades delete to related files and grants
   * - Cannot be undone
   */
  delete(id: string, options?: RequestOptions): APIPromise<APIResponseKnowledgeBaseDelete> {
    return this._client.delete(path`/knowledge-bases/${id}`, options);
  }
}

export interface APIResponseKnowledgeBase extends UsersAPI.APIResponseBase {
  data?: APIResponseKnowledgeBase.Data;
}

export namespace APIResponseKnowledgeBase {
  export interface Data {
    knowledgeBase: KnowledgeBasesAPI.KnowledgeBase;
  }
}

export interface APIResponseKnowledgeBaseDelete extends UsersAPI.APIResponseBase {
  data?: APIResponseKnowledgeBaseDelete.Data;
}

export namespace APIResponseKnowledgeBaseDelete {
  export interface Data {
    success: boolean;

    message?: string | null;
  }
}

export interface APIResponseKnowledgeBaseFileOperation extends UsersAPI.APIResponseBase {
  data: KnowledgeBaseFileOperationResult;
}

export interface APIResponseKnowledgeBaseList extends UsersAPI.APIResponseBase {
  data?: APIResponseKnowledgeBaseList.Data;
}

export namespace APIResponseKnowledgeBaseList {
  export interface Data {
    knowledgeBases: Array<KnowledgeBasesAPI.KnowledgeBaseListItem>;

    total: number;
  }
}

export interface APIResponseMoveKnowledgeBaseFiles extends UsersAPI.APIResponseBase {
  data: MoveKnowledgeBaseFilesResult;
}

export interface CreateKnowledgeBaseRequest {
  name: string;

  avatar?: string | null;

  description?: string | null;

  isPublic?: boolean | null;

  settings?: { [key: string]: unknown } | null;

  type?: 'personal' | 'shared' | null;
}

export interface KBAPIResponseFileList extends UsersAPI.APIResponseBase {
  data?: KBAPIResponseFileList.Data;
}

export namespace KBAPIResponseFileList {
  export interface Data {
    files: Array<FilesAPI.File>;

    total: number;

    /**
     * Total size in bytes of all matched files
     */
    totalSize?: string;
  }
}

export interface KBFile {
  id?: string;

  chunking?: KBFile.Chunking | null;

  createdAt?: string | null;

  embedding?: KBFile.Embedding | null;

  fileHash?: string | null;

  fileType?: string | null;

  knowledgeBaseId?: string | null;

  knowledgeBases?: Array<KBFile.KnowledgeBase> | null;

  metadata?: { [key: string]: unknown } | null;

  name?: string | null;

  size?: number | null;

  updatedAt?: string | null;

  url?: string | null;

  userId?: string | null;
}

export namespace KBFile {
  export interface Chunking {
    id?: string | null;

    /**
     * Chunk count for the related file (only for chunking tasks)
     */
    count?: number | null;

    error?: Chunking.Error | null;

    status?: 'pending' | 'processing' | 'success' | 'error' | null;

    type?: 'chunk' | 'embedding' | 'image_generation' | null;
  }

  export namespace Chunking {
    export interface Error {
      body: Error.Body;

      name: string;
    }

    export namespace Error {
      export interface Body {
        detail: string;
      }
    }
  }

  export interface Embedding {
    id?: string | null;

    /**
     * Chunk count for the related file (only for chunking tasks)
     */
    count?: number | null;

    error?: Embedding.Error | null;

    status?: 'pending' | 'processing' | 'success' | 'error' | null;

    type?: 'chunk' | 'embedding' | 'image_generation' | null;
  }

  export namespace Embedding {
    export interface Error {
      body: Error.Body;

      name: string;
    }

    export namespace Error {
      export interface Body {
        detail: string;
      }
    }
  }

  export interface KnowledgeBase {
    id: string;

    name: string;

    avatar?: string | null;

    description?: string | null;
  }
}

export interface KnowledgeBase {
  id: string;

  accessedAt: string;

  createdAt: string;

  enabled: boolean;

  name: string;

  updatedAt: string;

  userId: string;

  avatar?: string | null;

  clientId?: string | null;

  description?: string | null;

  isPublic?: boolean | null;

  settings?: { [key: string]: unknown } | null;

  type?: 'personal' | 'shared' | null;
}

export interface KnowledgeBaseFileOperationResult {
  failed: Array<KnowledgeBaseFileOperationResult.Failed>;

  successed: Array<string>;
}

export namespace KnowledgeBaseFileOperationResult {
  export interface Failed {
    fileId: string;

    reason: string;
  }
}

export interface KnowledgeBaseListItem extends KnowledgeBase {
  /**
   * Access type/source of the current user for this knowledge base
   */
  accessType?: 'owner' | 'userGrant' | 'roleGrant' | 'public';
}

export interface MoveKnowledgeBaseFilesResult {
  failed: Array<MoveKnowledgeBaseFilesResult.Failed>;

  successed: Array<string>;
}

export namespace MoveKnowledgeBaseFilesResult {
  export interface Failed {
    fileId: string;

    reason: string;
  }
}

export interface UpdateKnowledgeBaseRequest {
  avatar?: string | null;

  description?: string | null;

  enabled?: boolean | null;

  isPublic?: boolean | null;

  name?: string | null;

  settings?: { [key: string]: unknown } | null;

  type?: 'personal' | 'shared' | null;
}

export interface KnowledgeBaseCreateParams {
  /**
   * Knowledge base name (required)
   */
  name: string;

  /**
   * Knowledge base avatar URL
   */
  avatar?: string | null;

  /**
   * Knowledge base description
   */
  description?: string | null;

  /**
   * Whether the knowledge base is public (default false)
   */
  isPublic?: boolean | null;

  /**
   * Knowledge base settings
   */
  settings?: { [key: string]: unknown } | null;

  /**
   * Knowledge base type (default personal)
   */
  type?: 'personal' | 'shared' | null;
}

export interface KnowledgeBaseUpdateParams {
  /**
   * Knowledge base avatar URL
   */
  avatar?: string | null;

  /**
   * Knowledge base description
   */
  description?: string | null;

  /**
   * Whether the knowledge base is enabled
   */
  enabled?: boolean | null;

  /**
   * Whether the knowledge base is public
   */
  isPublic?: boolean | null;

  /**
   * Knowledge base name
   */
  name?: string | null;

  /**
   * Knowledge base settings
   */
  settings?: { [key: string]: unknown } | null;

  /**
   * Knowledge base type
   */
  type?: 'personal' | 'shared' | null;
}

export interface KnowledgeBaseListParams {
  /**
   * Filter by enabled status
   */
  enabled?: boolean;

  /**
   * Search keyword for name or description (case-insensitive)
   */
  keyword?: string;

  /**
   * Page number (default 1)
   */
  page?: number;

  /**
   * Items per page (default 20, max 100)
   */
  pageSize?: number;

  /**
   * Filter by knowledge base type
   */
  type?: 'personal' | 'shared';
}

KnowledgeBases.Files = Files;

export declare namespace KnowledgeBases {
  export {
    type APIResponseKnowledgeBase as APIResponseKnowledgeBase,
    type APIResponseKnowledgeBaseDelete as APIResponseKnowledgeBaseDelete,
    type APIResponseKnowledgeBaseFileOperation as APIResponseKnowledgeBaseFileOperation,
    type APIResponseKnowledgeBaseList as APIResponseKnowledgeBaseList,
    type APIResponseMoveKnowledgeBaseFiles as APIResponseMoveKnowledgeBaseFiles,
    type CreateKnowledgeBaseRequest as CreateKnowledgeBaseRequest,
    type KBAPIResponseFileList as KBAPIResponseFileList,
    type KBFile as KBFile,
    type KnowledgeBase as KnowledgeBase,
    type KnowledgeBaseFileOperationResult as KnowledgeBaseFileOperationResult,
    type KnowledgeBaseListItem as KnowledgeBaseListItem,
    type MoveKnowledgeBaseFilesResult as MoveKnowledgeBaseFilesResult,
    type UpdateKnowledgeBaseRequest as UpdateKnowledgeBaseRequest,
    type KnowledgeBaseCreateParams as KnowledgeBaseCreateParams,
    type KnowledgeBaseUpdateParams as KnowledgeBaseUpdateParams,
    type KnowledgeBaseListParams as KnowledgeBaseListParams,
  };

  export {
    Files as Files,
    type KBAPIResponseFileOperation as KBAPIResponseFileOperation,
    type KBAPIResponseMoveFiles as KBAPIResponseMoveFiles,
    type FileListParams as FileListParams,
    type FileBatchAddParams as FileBatchAddParams,
    type FileBatchRemoveParams as FileBatchRemoveParams,
    type FileMoveParams as FileMoveParams,
  };
}