ragpack-js 0.1.0

package/dist/index.js

@@ -0,0 +1,302 @@
+// src/requester.ts
+function createRequester(config) {
+  return async function req(path, init) {
+    const isFormData = init?.body instanceof FormData;
+    const res = await fetch(`${config.baseUrl}/api/v1${path}`, {
+      ...init,
+      headers: {
+        ...!isFormData && { "Content-Type": "application/json" },
+        Authorization: `Bearer ${config.apiKey}`,
+        ...init?.headers
+      }
+    });
+    if (res.status === 204) return void 0;
+    const body = await res.json();
+    if (!res.ok) throw new RagPackError(res.status, body.error ?? res.statusText);
+    return body;
+  };
+}
+var RagPackError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "RagPackError";
+  }
+};
+
+// src/resources/jobs.ts
+var JobsResource = class {
+  constructor(req, slug) {
+    this.req = req;
+    this.slug = slug;
+  }
+  /** List ingestion jobs for this collection, or all jobs if no collection is scoped. */
+  async list() {
+    const path = this.slug ? `/collections/${this.slug}/jobs` : "/jobs";
+    const r = await this.req(path);
+    return r.jobs;
+  }
+  /**
+   * Get a single ingestion job by ID.
+   * @param id - The job ID.
+   */
+  async get(id) {
+    const r = await this.req(`/collections/${this.slug}/jobs/${id}`);
+    return r.job;
+  }
+  /**
+   * Poll until the job reaches a terminal state (`complete` or `failed`).
+   * Throws {@link RagPackError} if the job fails or the timeout is exceeded.
+   *
+   * @example
+   * ```ts
+   * const job = await collection.ingest(file);
+   * await collection.jobs.waitUntilComplete(job.id);
+   * console.log("ingestion done, ready to search");
+   * ```
+   */
+  async waitUntilComplete(id, options = {}) {
+    const { pollIntervalMs = 1500, timeoutMs = 3e5 } = options;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const job = await this.get(id);
+      if (job.status === "complete") return job;
+      if (job.status === "failed") {
+        throw new RagPackError(422, job.error ?? "ingestion job failed");
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new RagPackError(408, `job ${id} did not complete within ${timeoutMs}ms`);
+  }
+};
+
+// src/resources/documents.ts
+var DocumentsResource = class {
+  constructor(req, slug) {
+    this.req = req;
+    this.slug = slug;
+  }
+  /**
+   * List documents in this collection.
+   * @param options.limit - Max number of documents to return. Defaults to 50.
+   * @param options.offset - Pagination offset. Defaults to 0.
+   */
+  async list(options) {
+    const params = new URLSearchParams({
+      limit: String(options?.limit ?? 50),
+      offset: String(options?.offset ?? 0)
+    });
+    const r = await this.req(
+      `/collections/${this.slug}/documents?${params}`
+    );
+    return r.documents;
+  }
+  /**
+   * Delete a document and all its chunks from this collection.
+   * @param id - The document ID.
+   */
+  delete(id) {
+    return this.req(`/collections/${this.slug}/documents/${id}`, {
+      method: "DELETE"
+    });
+  }
+};
+
+// src/resources/query.ts
+var QueryResource = class {
+  constructor(req, slug) {
+    this.req = req;
+    this.slug = slug;
+  }
+  /**
+   * Find semantically similar content within this collection.
+   * @returns Ranked results with similarity scores and source chunks.
+   */
+  async findSimilar(options) {
+    const r = await this.req(
+      `/collections/${this.slug}/query`,
+      {
+        method: "POST",
+        body: JSON.stringify({ query: options.query, top_k: options.topK ?? 5 })
+      }
+    );
+    return r.results;
+  }
+};
+
+// src/collection-client.ts
+var CollectionClient = class {
+  constructor(slug, req) {
+    this.slug = slug;
+    this._req = req;
+    this.jobs = new JobsResource(req, slug);
+    this.documents = new DocumentsResource(req, slug);
+    this._query = new QueryResource(req, slug);
+  }
+  ingest(input, filename) {
+    if (input instanceof Blob) {
+      const form = new FormData();
+      form.append("file", input, filename);
+      return this._req(`/collections/${this.slug}/ingest`, {
+        method: "POST",
+        body: form
+      });
+    }
+    return this._req(`/collections/${this.slug}/ingest`, {
+      method: "POST",
+      body: JSON.stringify({ file_uri: input.uri, mime_type: input.mimeType })
+    });
+  }
+  /**
+   * Find semantically similar content in this collection.
+   * @example
+   * ```ts
+   * const results = await collection.findSimilar({ query: "what is RagPack?", topK: 10 });
+   * ```
+   */
+  findSimilar(options) {
+    return this._query.findSimilar(options);
+  }
+  /**
+   * Full RAG pipeline: retrieve relevant chunks, build context, expand the
+   * prompt template, and call the configured LLM — all server-side.
+   *
+   * @example
+   * ```ts
+   * const { answer, chunks } = await collection.rag({
+   *   prompt: "basic-rag",
+   *   query: "How do I reset my password?",
+   * });
+   * ```
+   */
+  rag(options) {
+    return this._req(`/collections/${this.slug}/rag`, {
+      method: "POST",
+      body: JSON.stringify({
+        query: options.query,
+        top_k: options.topK ?? 5,
+        ...options.promptSlug ? { prompt_slug: options.promptSlug } : {},
+        ...options.model ? { model: options.model } : {},
+        ...options.minSimilarity != null ? { min_similarity: options.minSimilarity } : {}
+      })
+    });
+  }
+};
+
+// src/resources/collections.ts
+var CollectionsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** List all collections. */
+  async list() {
+    const r = await this.req("/collections");
+    return r.collections;
+  }
+  /**
+   * Create a new collection and return a scoped client for it.
+   * @param name - Display name for the collection.
+   * @param options.embedModel - Embedding model to use. Defaults to the server's configured provider.
+   * @param options.chunkConfig - Override chunking behaviour for this collection.
+   *   Omit to use server defaults.
+   *
+   * @example
+   * ```ts
+   * const collection = await client.collections.create("my-docs");
+   * await collection.ingest(file);
+   * ```
+   */
+  async create(name, options) {
+    const col = await this.req("/collections", {
+      method: "POST",
+      body: JSON.stringify({
+        name,
+        embed_model: options?.embedModel,
+        chunk_config: options?.chunkConfig
+      })
+    });
+    return new CollectionClient(col.slug, this.req);
+  }
+  /**
+   * Get a collection by its slug.
+   * @param slug - The collection's URL-safe identifier.
+   */
+  get(slug) {
+    return this.req(`/collections/${slug}`);
+  }
+  /**
+   * Delete a collection and all its documents.
+   * @param slug - The collection's URL-safe identifier.
+   */
+  delete(slug) {
+    return this.req(`/collections/${slug}`, { method: "DELETE" });
+  }
+};
+
+// src/resources/prompts.ts
+var PromptsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** List all prompt templates (built-in system prompts first, then custom). */
+  async list() {
+    const r = await this.req("/prompts");
+    return [...r.system ?? [], ...r.user ?? []];
+  }
+  /** Fetch a prompt template by slug. */
+  get(slug) {
+    return this.req(`/prompts/${slug}`);
+  }
+};
+
+// src/resources/llms.ts
+var LLMsResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** List all configured LLM models and the server default. */
+  list() {
+    return this.req("/llms");
+  }
+};
+
+// src/resources/embedders.ts
+var EmbeddersResource = class {
+  constructor(req) {
+    this.req = req;
+  }
+  /** List all configured embedding models and the server default. */
+  list() {
+    return this.req("/embedders");
+  }
+};
+
+// src/index.ts
+var RagPack = class {
+  constructor(config) {
+    this._req = createRequester(config);
+    this.collections = new CollectionsResource(this._req);
+    this.prompts = new PromptsResource(this._req);
+    this.llms = new LLMsResource(this._req);
+    this.embedders = new EmbeddersResource(this._req);
+  }
+  /**
+   * Scope all operations to a specific collection.
+   * @param slug - The collection's URL-safe identifier.
+   *
+   * @example
+   * ```ts
+   * const collection = client.collection("my-docs");
+   * await collection.ingest(file);
+   * await collection.findSimilar({ query: "..." });
+   * await collection.jobs.list();
+   * ```
+   */
+  collection(slug) {
+    return new CollectionClient(slug, this._req);
+  }
+};
+export {
+  RagPack,
+  RagPackError
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "ragpack-js",
+  "version": "0.1.0",
+  "description": "TypeScript client for the Ragpack self-hosted RAG engine",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run build"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.4",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.62.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eozsahin1993/ragpack.git",
+    "directory": "sdks/js"
+  }
+}