@kbforge/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,283 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  KBForge: () => KBForge,
+  KBForgeError: () => KBForgeError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://kbforge.app";
+var KBForgeError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "KBForgeError";
+    this.status = status;
+  }
+};
+var KBForge = class {
+  constructor(config) {
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Knowledge Bases (permission: "manage")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.knowledgeBases = {
+      list: () => {
+        return this.request("GET", "/knowledge-bases");
+      },
+      create: (options) => {
+        return this.request("POST", "/knowledge-bases", options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/knowledge-bases/${id}`);
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Documents (permission: "ingest" for upload, "manage" for list/delete)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.documents = {
+      list: (knowledgeBaseId) => {
+        return this.request("GET", `/documents?kb=${knowledgeBaseId}`);
+      },
+      upload: async (options) => {
+        const formData = new FormData();
+        formData.append("file", options.file, options.fileName);
+        formData.append("knowledgeBaseId", options.knowledgeBaseId);
+        const res = await this.requestRaw("POST", "/documents", formData, {});
+        return res.json();
+      },
+      uploadText: (options) => {
+        return this.request("POST", "/documents", options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/documents/${id}`);
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Chunks (permission: "chunks")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.chunks = {
+      list: (documentId, options) => {
+        const params = new URLSearchParams({ document_id: documentId });
+        if (options?.activeOnly) params.set("active_only", "true");
+        return this.request("GET", `/chunks?${params}`);
+      },
+      get: (id) => {
+        return this.request("GET", `/chunks/${id}`);
+      },
+      create: (options) => {
+        return this.request("POST", "/chunks", options);
+      },
+      update: (id, options) => {
+        return this.request("PATCH", `/chunks/${id}`, options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/chunks/${id}`);
+      },
+      split: (id, position) => {
+        return this.request("POST", `/chunks/${id}/split`, { position });
+      },
+      bulk: (options) => {
+        return this.request("POST", "/chunks/bulk", options);
+      },
+      merge: (chunkIds) => {
+        return this.request("POST", "/chunks/merge", { chunkIds });
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Tags (permission: "manage")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.tags = {
+      list: (knowledgeBaseId) => {
+        return this.request("GET", `/tags?kb=${knowledgeBaseId}`);
+      },
+      create: (options) => {
+        return this.request("POST", "/tags", options);
+      },
+      update: (id, options) => {
+        return this.request("PATCH", `/tags/${id}`, options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/tags/${id}`);
+      },
+      addDocuments: (tagId, documentIds) => {
+        return this.request("POST", `/tags/${tagId}/documents`, { documentIds });
+      },
+      removeDocument: (tagId, documentId) => {
+        return this.request("DELETE", `/tags/${tagId}/documents/${documentId}`);
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Segments (permission: "manage")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.segments = {
+      list: (knowledgeBaseId) => {
+        return this.request("GET", `/segments?kb=${knowledgeBaseId}`);
+      },
+      create: (options) => {
+        return this.request("POST", "/segments", options);
+      },
+      update: (id, options) => {
+        return this.request("PATCH", `/segments/${id}`, options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/segments/${id}`);
+      },
+      addDocuments: (segmentId, documentIds) => {
+        return this.request("POST", `/segments/${segmentId}/documents`, {
+          documentIds
+        });
+      },
+      removeDocument: (segmentId, documentId) => {
+        return this.request(
+          "DELETE",
+          `/segments/${segmentId}/documents/${documentId}`
+        );
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Analytics (permission: "admin")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.analytics = {
+      overview: (knowledgeBaseId) => {
+        return this.request("GET", `/analytics?kb=${knowledgeBaseId}`);
+      },
+      queriesPerDay: (knowledgeBaseId, days) => {
+        const params = new URLSearchParams({ kb: knowledgeBaseId });
+        if (days) params.set("days", String(days));
+        return this.request("GET", `/analytics/queries-per-day?${params}`);
+      },
+      topQueries: (knowledgeBaseId, limit) => {
+        const params = new URLSearchParams({ kb: knowledgeBaseId });
+        if (limit) params.set("limit", String(limit));
+        return this.request("GET", `/analytics/top-queries?${params}`);
+      },
+      topDocuments: (knowledgeBaseId, limit) => {
+        const params = new URLSearchParams({ kb: knowledgeBaseId });
+        if (limit) params.set("limit", String(limit));
+        return this.request("GET", `/analytics/top-documents?${params}`);
+      },
+      gaps: (knowledgeBaseId, limit) => {
+        const params = new URLSearchParams({ kb: knowledgeBaseId });
+        if (limit) params.set("limit", String(limit));
+        return this.request("GET", `/analytics/gaps?${params}`);
+      }
+    };
+    if (!config.apiKey) throw new Error("apiKey is required");
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({ error: res.statusText }));
+      throw new KBForgeError(
+        data.error || `Request failed with status ${res.status}`,
+        res.status
+      );
+    }
+    return res.json();
+  }
+  async requestRaw(method, path, body, headers) {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        ...headers,
+        ...body && !headers?.["Content-Type"] ? { "Content-Type": "application/json" } : {}
+      },
+      body: body instanceof FormData ? body : body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({ error: res.statusText }));
+      throw new KBForgeError(
+        data.error || `Request failed with status ${res.status}`,
+        res.status
+      );
+    }
+    return res;
+  }
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Retrieve (permission: "retrieve")
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  async retrieve(options) {
+    return this.request("POST", "/retrieve", options);
+  }
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Chat (permission: "retrieve")
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  async chat(options) {
+    const res = await this.requestRaw("POST", "/chat", options);
+    if (!res.body) {
+      throw new KBForgeError("No response body", 500);
+    }
+    return this.parseSSE(res.body);
+  }
+  async chatText(options) {
+    const stream = await this.chat(options);
+    let text = "";
+    for await (const event of stream) {
+      text += event.content;
+    }
+    return text;
+  }
+  async *parseSSE(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || !trimmed.startsWith("data: ")) continue;
+          const data = trimmed.slice(6);
+          if (data === "[DONE]") return;
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.content) yield parsed;
+          } catch {
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KBForge,
+  KBForgeError
+});

package/dist/index.d.cts

@@ -0,0 +1,337 @@
+interface RetrieveOptions {
+    query: string;
+    knowledgeBase: string;
+    limit?: number;
+    threshold?: number;
+    segment?: string;
+    tag?: string;
+}
+interface RetrieveChunk {
+    content: string;
+    score: number;
+    documentTitle: string;
+    documentId: string;
+    chunkId: string;
+    metadata: Record<string, unknown>;
+    pinned: boolean;
+    boost: number;
+}
+interface RetrieveResponse {
+    chunks: RetrieveChunk[];
+    query: string;
+    model: string;
+    latencyMs: number;
+}
+interface ChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface ChatOptions {
+    knowledgeBase: string;
+    messages: ChatMessage[];
+    systemPrompt?: string;
+    segment?: string;
+    tag?: string;
+}
+interface ChatStreamEvent {
+    content: string;
+}
+interface KnowledgeBase {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    embeddingModel: string | null;
+    documentCount: number | null;
+    status: string | null;
+    createdAt: string;
+}
+interface CreateKnowledgeBaseOptions {
+    name: string;
+    description?: string;
+}
+interface Document {
+    id: string;
+    title: string;
+    fileName: string | null;
+    mimeType: string | null;
+    fileSizeBytes: number | null;
+    status: string | null;
+    chunkCount: number | null;
+    createdAt: string;
+}
+interface UploadDocumentOptions {
+    knowledgeBaseId: string;
+    file: File | Blob;
+    fileName?: string;
+}
+interface UploadTextDocumentOptions {
+    knowledgeBaseId: string;
+    title: string;
+    content: string;
+}
+interface Chunk {
+    id: string;
+    documentId: string;
+    knowledgeBaseId: string;
+    content: string;
+    chunkIndex: number;
+    tokenCount: number;
+    isActive: boolean;
+    isEdited: boolean;
+    pinned: boolean;
+    boost: number;
+    originalContent: string | null;
+    modality: string;
+    createdAt: string;
+}
+interface ChunkListItem {
+    id: string;
+    content: string;
+    chunkIndex: number;
+    tokenCount: number;
+    isActive: boolean;
+    isEdited: boolean;
+    pinned: boolean;
+    boost: number;
+    modality: string;
+    createdAt: string;
+}
+interface ChunkListResponse {
+    chunks: ChunkListItem[];
+    documentId: string;
+    total: number;
+}
+interface CreateChunkOptions {
+    documentId: string;
+    knowledgeBaseId: string;
+    content: string;
+    insertAfterIndex?: number;
+}
+interface CreateChunkResponse {
+    id: string;
+    chunkIndex: number;
+    tokenCount: number;
+    status: string;
+}
+interface UpdateChunkOptions {
+    content?: string;
+    isActive?: boolean;
+    pinned?: boolean;
+    boost?: number;
+}
+interface UpdateChunkResponse {
+    id: string;
+    updated: boolean;
+    reembedding: boolean;
+}
+interface SplitChunkResponse {
+    split: boolean;
+    originalId: string;
+    chunks: {
+        id: string;
+        chunkIndex: number;
+        tokenCount: number;
+    }[];
+}
+type BulkAction = "activate" | "deactivate" | "pin" | "unpin" | "boost" | "delete";
+interface BulkChunkOptions {
+    action: BulkAction;
+    chunkIds: string[];
+    boostValue?: number;
+}
+interface BulkChunkResponse {
+    action: string;
+    affected: number;
+    requested: number;
+}
+interface MergeChunkResponse {
+    merged: boolean;
+    originalIds: string[];
+    chunk: {
+        id: string;
+        chunkIndex: number;
+        tokenCount: number;
+    };
+}
+interface Tag {
+    id: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    documentCount?: number;
+    createdAt: string;
+}
+interface CreateTagOptions {
+    knowledgeBaseId: string;
+    name: string;
+    description?: string;
+    color?: string;
+}
+interface UpdateTagOptions {
+    name?: string;
+    description?: string;
+    color?: string;
+}
+interface Segment {
+    id: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    documentCount?: number;
+    createdAt: string;
+}
+interface CreateSegmentOptions {
+    knowledgeBaseId: string;
+    name: string;
+    description?: string;
+    color?: string;
+}
+interface UpdateSegmentOptions {
+    name?: string;
+    description?: string;
+    color?: string;
+}
+interface AnalyticsOverview {
+    totalQueries: number;
+    queriesToday: number;
+    queriesThisWeek: number;
+    avgLatencyMs: number;
+    avgResultCount: number;
+    avgTopScore: number;
+}
+interface QueriesPerDay {
+    date: string;
+    count: number;
+}
+interface TopQuery {
+    queryText: string;
+    count: number;
+    avgScore: number;
+}
+interface TopDocument {
+    documentId: string;
+    documentTitle: string;
+    hitCount: number;
+}
+interface GapQuery {
+    queryText: string;
+    count: number;
+    avgScore: number;
+    lastSeen: string;
+}
+interface KBForgeConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+
+declare class KBForgeError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+declare class KBForge {
+    private apiKey;
+    private baseUrl;
+    constructor(config: KBForgeConfig);
+    private request;
+    private requestRaw;
+    retrieve(options: RetrieveOptions): Promise<RetrieveResponse>;
+    chat(options: ChatOptions): Promise<AsyncIterable<ChatStreamEvent>>;
+    chatText(options: ChatOptions): Promise<string>;
+    private parseSSE;
+    readonly knowledgeBases: {
+        list: () => Promise<{
+            knowledgeBases: KnowledgeBase[];
+        }>;
+        create: (options: CreateKnowledgeBaseOptions) => Promise<KnowledgeBase>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly documents: {
+        list: (knowledgeBaseId: string) => Promise<{
+            documents: Document[];
+            total: number;
+        }>;
+        upload: (options: UploadDocumentOptions) => Promise<{
+            id: string;
+            title: string;
+            status: string;
+        }>;
+        uploadText: (options: UploadTextDocumentOptions) => Promise<{
+            id: string;
+            title: string;
+            status: string;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly chunks: {
+        list: (documentId: string, options?: {
+            activeOnly?: boolean;
+        }) => Promise<ChunkListResponse>;
+        get: (id: string) => Promise<Chunk>;
+        create: (options: CreateChunkOptions) => Promise<CreateChunkResponse>;
+        update: (id: string, options: UpdateChunkOptions) => Promise<UpdateChunkResponse>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        split: (id: string, position: number) => Promise<SplitChunkResponse>;
+        bulk: (options: BulkChunkOptions) => Promise<BulkChunkResponse>;
+        merge: (chunkIds: string[]) => Promise<MergeChunkResponse>;
+    };
+    readonly tags: {
+        list: (knowledgeBaseId: string) => Promise<{
+            tags: Tag[];
+        }>;
+        create: (options: CreateTagOptions) => Promise<Tag>;
+        update: (id: string, options: UpdateTagOptions) => Promise<{
+            updated: boolean;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        addDocuments: (tagId: string, documentIds: string[]) => Promise<{
+            added: number;
+        }>;
+        removeDocument: (tagId: string, documentId: string) => Promise<{
+            removed: boolean;
+        }>;
+    };
+    readonly segments: {
+        list: (knowledgeBaseId: string) => Promise<{
+            segments: Segment[];
+        }>;
+        create: (options: CreateSegmentOptions) => Promise<Segment>;
+        update: (id: string, options: UpdateSegmentOptions) => Promise<{
+            updated: boolean;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        addDocuments: (segmentId: string, documentIds: string[]) => Promise<{
+            added: number;
+        }>;
+        removeDocument: (segmentId: string, documentId: string) => Promise<{
+            removed: boolean;
+        }>;
+    };
+    readonly analytics: {
+        overview: (knowledgeBaseId: string) => Promise<AnalyticsOverview>;
+        queriesPerDay: (knowledgeBaseId: string, days?: number) => Promise<{
+            data: QueriesPerDay[];
+        }>;
+        topQueries: (knowledgeBaseId: string, limit?: number) => Promise<{
+            data: TopQuery[];
+        }>;
+        topDocuments: (knowledgeBaseId: string, limit?: number) => Promise<{
+            data: TopDocument[];
+        }>;
+        gaps: (knowledgeBaseId: string, limit?: number) => Promise<{
+            data: GapQuery[];
+        }>;
+    };
+}
+
+export { type AnalyticsOverview, type BulkAction, type BulkChunkOptions, type BulkChunkResponse, type ChatMessage, type ChatOptions, type ChatStreamEvent, type Chunk, type ChunkListItem, type ChunkListResponse, type CreateChunkOptions, type CreateChunkResponse, type CreateKnowledgeBaseOptions, type CreateSegmentOptions, type CreateTagOptions, type Document, type GapQuery, KBForge, type KBForgeConfig, KBForgeError, type KnowledgeBase, type MergeChunkResponse, type QueriesPerDay, type RetrieveChunk, type RetrieveOptions, type RetrieveResponse, type Segment, type SplitChunkResponse, type Tag, type TopDocument, type TopQuery, type UpdateChunkOptions, type UpdateChunkResponse, type UpdateSegmentOptions, type UpdateTagOptions, type UploadDocumentOptions, type UploadTextDocumentOptions };

package/dist/index.d.ts

@@ -0,0 +1,337 @@
+interface RetrieveOptions {
+    query: string;
+    knowledgeBase: string;
+    limit?: number;
+    threshold?: number;
+    segment?: string;
+    tag?: string;
+}
+interface RetrieveChunk {
+    content: string;
+    score: number;
+    documentTitle: string;
+    documentId: string;
+    chunkId: string;
+    metadata: Record<string, unknown>;
+    pinned: boolean;
+    boost: number;
+}
+interface RetrieveResponse {
+    chunks: RetrieveChunk[];
+    query: string;
+    model: string;
+    latencyMs: number;
+}
+interface ChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface ChatOptions {
+    knowledgeBase: string;
+    messages: ChatMessage[];
+    systemPrompt?: string;
+    segment?: string;
+    tag?: string;
+}
+interface ChatStreamEvent {
+    content: string;
+}
+interface KnowledgeBase {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    embeddingModel: string | null;
+    documentCount: number | null;
+    status: string | null;
+    createdAt: string;
+}
+interface CreateKnowledgeBaseOptions {
+    name: string;
+    description?: string;
+}
+interface Document {
+    id: string;
+    title: string;
+    fileName: string | null;
+    mimeType: string | null;
+    fileSizeBytes: number | null;
+    status: string | null;
+    chunkCount: number | null;
+    createdAt: string;
+}
+interface UploadDocumentOptions {
+    knowledgeBaseId: string;
+    file: File | Blob;
+    fileName?: string;
+}
+interface UploadTextDocumentOptions {
+    knowledgeBaseId: string;
+    title: string;
+    content: string;
+}
+interface Chunk {
+    id: string;
+    documentId: string;
+    knowledgeBaseId: string;
+    content: string;
+    chunkIndex: number;
+    tokenCount: number;
+    isActive: boolean;
+    isEdited: boolean;
+    pinned: boolean;
+    boost: number;
+    originalContent: string | null;
+    modality: string;
+    createdAt: string;
+}
+interface ChunkListItem {
+    id: string;
+    content: string;
+    chunkIndex: number;
+    tokenCount: number;
+    isActive: boolean;
+    isEdited: boolean;
+    pinned: boolean;
+    boost: number;
+    modality: string;
+    createdAt: string;
+}
+interface ChunkListResponse {
+    chunks: ChunkListItem[];
+    documentId: string;
+    total: number;
+}
+interface CreateChunkOptions {
+    documentId: string;
+    knowledgeBaseId: string;
+    content: string;
+    insertAfterIndex?: number;
+}
+interface CreateChunkResponse {
+    id: string;
+    chunkIndex: number;
+    tokenCount: number;
+    status: string;
+}
+interface UpdateChunkOptions {
+    content?: string;
+    isActive?: boolean;
+    pinned?: boolean;
+    boost?: number;
+}
+interface UpdateChunkResponse {
+    id: string;
+    updated: boolean;
+    reembedding: boolean;
+}
+interface SplitChunkResponse {
+    split: boolean;
+    originalId: string;
+    chunks: {
+        id: string;
+        chunkIndex: number;
+        tokenCount: number;
+    }[];
+}
+type BulkAction = "activate" | "deactivate" | "pin" | "unpin" | "boost" | "delete";
+interface BulkChunkOptions {
+    action: BulkAction;
+    chunkIds: string[];
+    boostValue?: number;
+}
+interface BulkChunkResponse {
+    action: string;
+    affected: number;
+    requested: number;
+}
+interface MergeChunkResponse {
+    merged: boolean;
+    originalIds: string[];
+    chunk: {
+        id: string;
+        chunkIndex: number;
+        tokenCount: number;
+    };
+}
+interface Tag {
+    id: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    documentCount?: number;
+    createdAt: string;
+}
+interface CreateTagOptions {
+    knowledgeBaseId: string;
+    name: string;
+    description?: string;
+    color?: string;
+}
+interface UpdateTagOptions {
+    name?: string;
+    description?: string;
+    color?: string;
+}
+interface Segment {
+    id: string;
+    name: string;
+    description: string | null;
+    color: string | null;
+    documentCount?: number;
+    createdAt: string;
+}
+interface CreateSegmentOptions {
+    knowledgeBaseId: string;
+    name: string;
+    description?: string;
+    color?: string;
+}
+interface UpdateSegmentOptions {
+    name?: string;
+    description?: string;
+    color?: string;
+}
+interface AnalyticsOverview {
+    totalQueries: number;
+    queriesToday: number;
+    queriesThisWeek: number;
+    avgLatencyMs: number;
+    avgResultCount: number;
+    avgTopScore: number;
+}
+interface QueriesPerDay {
+    date: string;
+    count: number;
+}
+interface TopQuery {
+    queryText: string;
+    count: number;
+    avgScore: number;
+}
+interface TopDocument {
+    documentId: string;
+    documentTitle: string;
+    hitCount: number;
+}
+interface GapQuery {
+    queryText: string;
+    count: number;
+    avgScore: number;
+    lastSeen: string;
+}
+interface KBForgeConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+
+declare class KBForgeError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+declare class KBForge {
+    private apiKey;
+    private baseUrl;
+    constructor(config: KBForgeConfig);
+    private request;
+    private requestRaw;
+    retrieve(options: RetrieveOptions): Promise<RetrieveResponse>;
+    chat(options: ChatOptions): Promise<AsyncIterable<ChatStreamEvent>>;
+    chatText(options: ChatOptions): Promise<string>;
+    private parseSSE;
+    readonly knowledgeBases: {
+        list: () => Promise<{
+            knowledgeBases: KnowledgeBase[];
+        }>;
+        create: (options: CreateKnowledgeBaseOptions) => Promise<KnowledgeBase>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly documents: {
+        list: (knowledgeBaseId: string) => Promise<{
+            documents: Document[];
+            total: number;
+        }>;
+        upload: (options: UploadDocumentOptions) => Promise<{
+            id: string;
+            title: string;
+            status: string;
+        }>;
+        uploadText: (options: UploadTextDocumentOptions) => Promise<{
+            id: string;
+            title: string;
+            status: string;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+    };
+    readonly chunks: {
+        list: (documentId: string, options?: {
+            activeOnly?: boolean;
+        }) => Promise<ChunkListResponse>;
+        get: (id: string) => Promise<Chunk>;
+        create: (options: CreateChunkOptions) => Promise<CreateChunkResponse>;
+        update: (id: string, options: UpdateChunkOptions) => Promise<UpdateChunkResponse>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        split: (id: string, position: number) => Promise<SplitChunkResponse>;
+        bulk: (options: BulkChunkOptions) => Promise<BulkChunkResponse>;
+        merge: (chunkIds: string[]) => Promise<MergeChunkResponse>;
+    };
+    readonly tags: {
+        list: (knowledgeBaseId: string) => Promise<{
+            tags: Tag[];
+        }>;
+        create: (options: CreateTagOptions) => Promise<Tag>;
+        update: (id: string, options: UpdateTagOptions) => Promise<{
+            updated: boolean;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        addDocuments: (tagId: string, documentIds: string[]) => Promise<{
+            added: number;
+        }>;
+        removeDocument: (tagId: string, documentId: string) => Promise<{
+            removed: boolean;
+        }>;
+    };
+    readonly segments: {
+        list: (knowledgeBaseId: string) => Promise<{
+            segments: Segment[];
+        }>;
+        create: (options: CreateSegmentOptions) => Promise<Segment>;
+        update: (id: string, options: UpdateSegmentOptions) => Promise<{
+            updated: boolean;
+        }>;
+        delete: (id: string) => Promise<{
+            deleted: boolean;
+        }>;
+        addDocuments: (segmentId: string, documentIds: string[]) => Promise<{
+            added: number;
+        }>;
+        removeDocument: (segmentId: string, documentId: string) => Promise<{
+            removed: boolean;
+        }>;
+    };
+    readonly analytics: {
+        overview: (knowledgeBaseId: string) => Promise<AnalyticsOverview>;
+        queriesPerDay: (knowledgeBaseId: string, days?: number) => Promise<{
+            data: QueriesPerDay[];
+        }>;
+        topQueries: (knowledgeBaseId: string, limit?: number) => Promise<{
+            data: TopQuery[];
+        }>;
+        topDocuments: (knowledgeBaseId: string, limit?: number) => Promise<{
+            data: TopDocument[];
+        }>;
+        gaps: (knowledgeBaseId: string, limit?: number) => Promise<{
+            data: GapQuery[];
+        }>;
+    };
+}
+
+export { type AnalyticsOverview, type BulkAction, type BulkChunkOptions, type BulkChunkResponse, type ChatMessage, type ChatOptions, type ChatStreamEvent, type Chunk, type ChunkListItem, type ChunkListResponse, type CreateChunkOptions, type CreateChunkResponse, type CreateKnowledgeBaseOptions, type CreateSegmentOptions, type CreateTagOptions, type Document, type GapQuery, KBForge, type KBForgeConfig, KBForgeError, type KnowledgeBase, type MergeChunkResponse, type QueriesPerDay, type RetrieveChunk, type RetrieveOptions, type RetrieveResponse, type Segment, type SplitChunkResponse, type Tag, type TopDocument, type TopQuery, type UpdateChunkOptions, type UpdateChunkResponse, type UpdateSegmentOptions, type UpdateTagOptions, type UploadDocumentOptions, type UploadTextDocumentOptions };

package/dist/index.js

@@ -0,0 +1,255 @@
+// src/client.ts
+var DEFAULT_BASE_URL = "https://kbforge.app";
+var KBForgeError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "KBForgeError";
+    this.status = status;
+  }
+};
+var KBForge = class {
+  constructor(config) {
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Knowledge Bases (permission: "manage")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.knowledgeBases = {
+      list: () => {
+        return this.request("GET", "/knowledge-bases");
+      },
+      create: (options) => {
+        return this.request("POST", "/knowledge-bases", options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/knowledge-bases/${id}`);
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Documents (permission: "ingest" for upload, "manage" for list/delete)
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.documents = {
+      list: (knowledgeBaseId) => {
+        return this.request("GET", `/documents?kb=${knowledgeBaseId}`);
+      },
+      upload: async (options) => {
+        const formData = new FormData();
+        formData.append("file", options.file, options.fileName);
+        formData.append("knowledgeBaseId", options.knowledgeBaseId);
+        const res = await this.requestRaw("POST", "/documents", formData, {});
+        return res.json();
+      },
+      uploadText: (options) => {
+        return this.request("POST", "/documents", options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/documents/${id}`);
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Chunks (permission: "chunks")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.chunks = {
+      list: (documentId, options) => {
+        const params = new URLSearchParams({ document_id: documentId });
+        if (options?.activeOnly) params.set("active_only", "true");
+        return this.request("GET", `/chunks?${params}`);
+      },
+      get: (id) => {
+        return this.request("GET", `/chunks/${id}`);
+      },
+      create: (options) => {
+        return this.request("POST", "/chunks", options);
+      },
+      update: (id, options) => {
+        return this.request("PATCH", `/chunks/${id}`, options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/chunks/${id}`);
+      },
+      split: (id, position) => {
+        return this.request("POST", `/chunks/${id}/split`, { position });
+      },
+      bulk: (options) => {
+        return this.request("POST", "/chunks/bulk", options);
+      },
+      merge: (chunkIds) => {
+        return this.request("POST", "/chunks/merge", { chunkIds });
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Tags (permission: "manage")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.tags = {
+      list: (knowledgeBaseId) => {
+        return this.request("GET", `/tags?kb=${knowledgeBaseId}`);
+      },
+      create: (options) => {
+        return this.request("POST", "/tags", options);
+      },
+      update: (id, options) => {
+        return this.request("PATCH", `/tags/${id}`, options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/tags/${id}`);
+      },
+      addDocuments: (tagId, documentIds) => {
+        return this.request("POST", `/tags/${tagId}/documents`, { documentIds });
+      },
+      removeDocument: (tagId, documentId) => {
+        return this.request("DELETE", `/tags/${tagId}/documents/${documentId}`);
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Segments (permission: "manage")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.segments = {
+      list: (knowledgeBaseId) => {
+        return this.request("GET", `/segments?kb=${knowledgeBaseId}`);
+      },
+      create: (options) => {
+        return this.request("POST", "/segments", options);
+      },
+      update: (id, options) => {
+        return this.request("PATCH", `/segments/${id}`, options);
+      },
+      delete: (id) => {
+        return this.request("DELETE", `/segments/${id}`);
+      },
+      addDocuments: (segmentId, documentIds) => {
+        return this.request("POST", `/segments/${segmentId}/documents`, {
+          documentIds
+        });
+      },
+      removeDocument: (segmentId, documentId) => {
+        return this.request(
+          "DELETE",
+          `/segments/${segmentId}/documents/${documentId}`
+        );
+      }
+    };
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Analytics (permission: "admin")
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    this.analytics = {
+      overview: (knowledgeBaseId) => {
+        return this.request("GET", `/analytics?kb=${knowledgeBaseId}`);
+      },
+      queriesPerDay: (knowledgeBaseId, days) => {
+        const params = new URLSearchParams({ kb: knowledgeBaseId });
+        if (days) params.set("days", String(days));
+        return this.request("GET", `/analytics/queries-per-day?${params}`);
+      },
+      topQueries: (knowledgeBaseId, limit) => {
+        const params = new URLSearchParams({ kb: knowledgeBaseId });
+        if (limit) params.set("limit", String(limit));
+        return this.request("GET", `/analytics/top-queries?${params}`);
+      },
+      topDocuments: (knowledgeBaseId, limit) => {
+        const params = new URLSearchParams({ kb: knowledgeBaseId });
+        if (limit) params.set("limit", String(limit));
+        return this.request("GET", `/analytics/top-documents?${params}`);
+      },
+      gaps: (knowledgeBaseId, limit) => {
+        const params = new URLSearchParams({ kb: knowledgeBaseId });
+        if (limit) params.set("limit", String(limit));
+        return this.request("GET", `/analytics/gaps?${params}`);
+      }
+    };
+    if (!config.apiKey) throw new Error("apiKey is required");
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({ error: res.statusText }));
+      throw new KBForgeError(
+        data.error || `Request failed with status ${res.status}`,
+        res.status
+      );
+    }
+    return res.json();
+  }
+  async requestRaw(method, path, body, headers) {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        ...headers,
+        ...body && !headers?.["Content-Type"] ? { "Content-Type": "application/json" } : {}
+      },
+      body: body instanceof FormData ? body : body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({ error: res.statusText }));
+      throw new KBForgeError(
+        data.error || `Request failed with status ${res.status}`,
+        res.status
+      );
+    }
+    return res;
+  }
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Retrieve (permission: "retrieve")
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  async retrieve(options) {
+    return this.request("POST", "/retrieve", options);
+  }
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Chat (permission: "retrieve")
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  async chat(options) {
+    const res = await this.requestRaw("POST", "/chat", options);
+    if (!res.body) {
+      throw new KBForgeError("No response body", 500);
+    }
+    return this.parseSSE(res.body);
+  }
+  async chatText(options) {
+    const stream = await this.chat(options);
+    let text = "";
+    for await (const event of stream) {
+      text += event.content;
+    }
+    return text;
+  }
+  async *parseSSE(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || !trimmed.startsWith("data: ")) continue;
+          const data = trimmed.slice(6);
+          if (data === "[DONE]") return;
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.content) yield parsed;
+          } catch {
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+};
+export {
+  KBForge,
+  KBForgeError
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kbforge/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the KBForge API — semantic search and RAG chat over your knowledge bases",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "kbforge",
+    "knowledge-base",
+    "rag",
+    "semantic-search",
+    "sdk",
+    "api"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Avililla/kbforge",
+    "directory": "packages/sdk"
+  }
+}