ragora 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ragora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,397 @@
+# Ragora Node.js SDK
+
+Official Node.js/TypeScript SDK for the [Ragora](https://ragora.app) RAG API. Build AI-powered knowledge bases with semantic search and chat completions.
+
+[![npm version](https://badge.fury.io/js/ragora.svg)](https://www.npmjs.com/package/ragora)
+[![Node.js 18+](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+npm install ragora
+```
+
+Or with other package managers:
+
+```bash
+pnpm add ragora
+yarn add ragora
+```
+
+## Quick Start
+
+```typescript
+import { RagoraClient } from 'ragora';
+
+const client = new RagoraClient({ apiKey: 'your-api-key' });
+
+// Create a collection
+const collection = await client.createCollection({
+  name: 'My Knowledge Base',
+  description: 'Documentation and guides',
+});
+console.log(`Created collection: ${collection.id}`);
+
+// Upload a document
+const upload = await client.uploadDocument({
+  file: new Blob(['Hello world']),
+  filename: 'hello.txt',
+  collectionId: collection.id,
+});
+console.log(`Uploaded: ${upload.filename} (ID: ${upload.id})`);
+
+// Wait for processing to complete
+const status = await client.waitForDocument(upload.id);
+console.log(`Processing complete: ${status.vectorCount} vectors created`);
+
+// Search the collection
+const results = await client.search({
+  collectionId: collection.id,
+  query: 'How do I get started?',
+  topK: 5,
+});
+results.results.forEach((result) => {
+  console.log(`Score: ${result.score.toFixed(3)} - ${result.content.slice(0, 100)}...`);
+});
+
+// Chat with your knowledge base
+const response = await client.chat({
+  collectionId: collection.id,
+  messages: [{ role: 'user', content: 'Summarize the main concepts' }],
+});
+console.log(response.choices[0].message.content);
+```
+
+## Features
+
+- **Fetch-based** - Works in Node.js, browsers, and edge runtimes
+- **Full TypeScript** - Complete type definitions included
+- **Streaming support** - Real-time chat completions with async iterators
+- **Document management** - Upload, track progress, and manage documents
+- **Collection CRUD** - Create, update, delete, and list collections
+- **Cost tracking** - Monitor API costs per request
+- **Next.js ready** - Works with App Router and Pages Router
+
+## API Reference
+
+### Client Initialization
+
+```typescript
+import { RagoraClient } from 'ragora';
+
+// Basic usage
+const client = new RagoraClient({ apiKey: 'your-api-key' });
+
+// With custom settings
+const client = new RagoraClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.ragora.app', // default
+  timeout: 30000, // milliseconds
+  fetch: customFetch, // optional custom fetch implementation
+});
+```
+
+### Collections
+
+```typescript
+// Create a collection
+const collection = await client.createCollection({
+  name: 'My Collection',
+  description: 'Optional description',
+  slug: 'my-collection', // optional, auto-generated if not provided
+});
+
+// List collections
+const collections = await client.listCollections({ limit: 20, offset: 0 });
+for (const coll of collections.data) {
+  console.log(`${coll.name}: ${coll.totalDocuments} documents`);
+}
+
+// Get a collection by ID or slug
+const collection = await client.getCollection('collection-id-or-slug');
+
+// Update a collection
+const updated = await client.updateCollection('collection-id', {
+  name: 'New Name',
+  description: 'Updated description',
+});
+
+// Delete a collection
+const result = await client.deleteCollection('collection-id');
+console.log(result.message);
+```
+
+### Documents
+
+```typescript
+// Upload a document (Node.js with Buffer)
+import { readFileSync } from 'fs';
+
+const upload = await client.uploadDocument({
+  file: readFileSync('./document.pdf'),
+  filename: 'document.pdf',
+  collectionId: 'collection-id', // optional, uses default if not provided
+});
+
+// Upload a document (Browser with Blob/File)
+const upload = await client.uploadDocument({
+  file: fileInput.files[0], // from <input type="file">
+  filename: fileInput.files[0].name,
+  collectionId: 'collection-id',
+});
+
+// Check document status
+const status = await client.getDocumentStatus(upload.id);
+console.log(`Status: ${status.status}`);
+console.log(`Progress: ${status.progressPercent}%`);
+console.log(`Stage: ${status.progressStage}`);
+
+// Wait for processing to complete
+const status = await client.waitForDocument(upload.id, {
+  timeout: 300000, // max wait time in ms (default: 5 minutes)
+  pollInterval: 2000, // time between status checks in ms
+});
+
+// List documents in a collection
+const documents = await client.listDocuments({
+  collectionId: 'collection-id',
+  limit: 50,
+  offset: 0,
+});
+
+// Delete a document
+const result = await client.deleteDocument('document-id');
+```
+
+### Search
+
+```typescript
+const results = await client.search({
+  collectionId: 'collection-id',
+  query: 'What is machine learning?',
+  topK: 5, // number of results
+  threshold: 0.7, // minimum relevance score (0-1)
+  filter: { type: 'doc' }, // optional metadata filter
+});
+
+for (const result of results.results) {
+  console.log(`Score: ${result.score.toFixed(3)}`);
+  console.log(`Content: ${result.content}`);
+  console.log(`Document ID: ${result.documentId}`);
+  console.log('---');
+}
+```
+
+### Chat Completions
+
+```typescript
+// Non-streaming
+const response = await client.chat({
+  collectionId: 'collection-id',
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Explain RAG' },
+  ],
+  model: 'gpt-4o-mini', // optional
+  temperature: 0.7, // optional
+  maxTokens: 1000, // optional
+  systemPrompt: 'Custom system prompt', // optional
+});
+
+console.log(response.choices[0].message.content);
+console.log(`Sources used: ${response.sources.length}`);
+
+// Streaming
+for await (const chunk of client.chatStream({
+  collectionId: 'collection-id',
+  messages: [{ role: 'user', content: 'Explain RAG' }],
+})) {
+  process.stdout.write(chunk.content);
+
+  // Sources are included in the final chunk
+  if (chunk.sources.length > 0) {
+    console.log(`\n\nSources: ${chunk.sources.length}`);
+  }
+}
+```
+
+### Marketplace
+
+```typescript
+// Browse marketplace products
+const products = await client.listMarketplace({ limit: 10, search: 'AI' });
+for (const product of products.data) {
+  console.log(`${product.title} - ${product.averageRating.toFixed(1)} stars`);
+}
+
+// Get product details (by ID or slug)
+const product = await client.getMarketplaceProduct('product-slug');
+console.log(`${product.title}: ${product.totalVectors} vectors`);
+if (product.listings) {
+  for (const listing of product.listings) {
+    console.log(`  ${listing.type}: $${listing.priceAmountUsd}`);
+  }
+}
+```
+
+### Credits
+
+```typescript
+const balance = await client.getBalance();
+console.log(`Balance: $${balance.balanceUsd.toFixed(2)} ${balance.currency}`);
+```
+
+## Response Metadata
+
+Every response includes metadata from API headers:
+
+```typescript
+const response = await client.search({...});
+
+console.log(`Request ID: ${response.requestId}`);
+console.log(`API Version: ${response.apiVersion}`);
+console.log(`Cost: $${response.costUsd?.toFixed(4)}`);
+console.log(`Remaining balance: $${response.balanceRemainingUsd?.toFixed(2)}`);
+console.log(`Rate limit: ${response.rateLimitRemaining}/${response.rateLimitLimit}`);
+console.log(`Rate limit resets in: ${response.rateLimitReset}s`);
+```
+
+## Error Handling
+
+```typescript
+import { RagoraClient, RagoraError } from 'ragora';
+
+const client = new RagoraClient({ apiKey: 'your-api-key' });
+
+try {
+  const results = await client.search({...});
+} catch (error) {
+  if (error instanceof RagoraError) {
+    console.log(`Error: ${error.message}`);
+    console.log(`Status code: ${error.statusCode}`);
+    console.log(`Request ID: ${error.requestId}`);
+
+    if (error.isRateLimited) {
+      console.log('Rate limited - wait and retry');
+    } else if (error.isAuthError) {
+      console.log('Check your API key');
+    } else if (error.isRetryable) {
+      console.log('Temporary error - safe to retry');
+    }
+  }
+}
+```
+
+## Next.js Integration
+
+### App Router (Server Components)
+
+```typescript
+// app/api/search/route.ts
+import { RagoraClient } from 'ragora';
+import { NextResponse } from 'next/server';
+
+const client = new RagoraClient({
+  apiKey: process.env.RAGORA_API_KEY!,
+});
+
+export async function POST(request: Request) {
+  const { query, collectionId } = await request.json();
+
+  const results = await client.search({
+    collectionId,
+    query,
+    topK: 5,
+  });
+
+  return NextResponse.json(results);
+}
+```
+
+### Streaming Chat (App Router)
+
+```typescript
+// app/api/chat/route.ts
+import { RagoraClient } from 'ragora';
+
+const client = new RagoraClient({
+  apiKey: process.env.RAGORA_API_KEY!,
+});
+
+export async function POST(request: Request) {
+  const { messages, collectionId } = await request.json();
+
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      for await (const chunk of client.chatStream({
+        collectionId,
+        messages,
+      })) {
+        controller.enqueue(encoder.encode(chunk.content));
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+}
+```
+
+### Pages Router
+
+```typescript
+// pages/api/chat.ts
+import { RagoraClient } from 'ragora';
+import type { NextApiRequest, NextApiResponse } from 'next';
+
+const client = new RagoraClient({
+  apiKey: process.env.RAGORA_API_KEY!,
+});
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  const { messages, collectionId } = req.body;
+
+  const response = await client.chat({
+    collectionId,
+    messages,
+  });
+
+  res.status(200).json(response);
+}
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory for complete, runnable examples:
+
+| Example | Description | Command |
+|---------|-------------|---------|
+| [Search](examples/search.ts) | Search documents and access response metadata | `npm run example:search` |
+| [Chat](examples/chat.ts) | Chat completions with RAG context | `npm run example:chat` |
+| [Streaming](examples/streaming.ts) | Streaming chat responses | `npm run example:streaming` |
+| [Collections CRUD](examples/collections-crud.ts) | Create, list, get, update, delete collections | `npm run example:collections` |
+| [Documents](examples/documents.ts) | Upload, process, list, delete documents | `npm run example:documents` |
+| [Marketplace](examples/marketplace.ts) | Browse marketplace products and listings | `npm run example:marketplace` |
+| [Credits](examples/credits.ts) | Check balance and track costs | `npm run example:credits` |
+
+Set your API key before running:
+
+```bash
+export RAGORA_API_KEY="your-api-key"
+npm run example:search
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Ragora Website](https://ragora.app)
+- [API Documentation](https://docs.ragora.app)
+- [GitHub Repository](https://github.com/velarynai/ragora-node)

package/dist/client.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Ragora API Client
+ *
+ * Fetch-based HTTP client for the Ragora API.
+ */
+import type { ChatRequest, ChatResponse, ChatStreamChunk, Collection, CollectionListRequest, CollectionListResponse, CreateCollectionRequest, CreditBalance, DeleteResponse, DocumentListRequest, DocumentListResponse, DocumentStatus, MarketplaceListRequest, MarketplaceListResponse, MarketplaceProduct, SearchRequest, SearchResponse, UpdateCollectionRequest, UploadDocumentRequest, UploadResponse } from './types.js';
+export interface RagoraClientOptions {
+    /** Your Ragora API key */
+    apiKey: string;
+    /** API base URL (default: https://api.ragora.app) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Custom fetch implementation (for testing or environments without global fetch) */
+    fetch?: typeof fetch;
+}
+export declare class RagoraClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly fetchFn;
+    constructor(options: RagoraClientOptions);
+    /**
+     * Extract metadata from response headers.
+     */
+    private extractMetadata;
+    /**
+     * Make an API request.
+     */
+    private request;
+    /**
+     * Handle error responses.
+     */
+    private handleError;
+    /**
+     * Search for relevant documents in a collection.
+     */
+    search(request: SearchRequest): Promise<SearchResponse>;
+    /**
+     * Generate a chat completion with RAG context.
+     */
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Stream a chat completion with RAG context.
+     */
+    chatStream(request: ChatRequest): AsyncGenerator<ChatStreamChunk>;
+    /**
+     * Get current credit balance.
+     */
+    getBalance(): Promise<CreditBalance>;
+    /**
+     * List your collections.
+     */
+    listCollections(request?: CollectionListRequest): Promise<CollectionListResponse>;
+    /**
+     * Get a specific collection by ID or slug.
+     */
+    getCollection(collectionId: string): Promise<Collection>;
+    /**
+     * Create a new collection.
+     */
+    createCollection(request: CreateCollectionRequest): Promise<Collection>;
+    /**
+     * Update an existing collection.
+     */
+    updateCollection(collectionId: string, request: UpdateCollectionRequest): Promise<Collection>;
+    /**
+     * Delete a collection and all its documents.
+     */
+    deleteCollection(collectionId: string): Promise<DeleteResponse>;
+    /**
+     * Upload a document to a collection.
+     */
+    uploadDocument(request: UploadDocumentRequest): Promise<UploadResponse>;
+    /**
+     * Get the processing status of a document.
+     */
+    getDocumentStatus(documentId: string): Promise<DocumentStatus>;
+    /**
+     * List documents in a collection.
+     */
+    listDocuments(request?: DocumentListRequest): Promise<DocumentListResponse>;
+    /**
+     * Delete a document.
+     */
+    deleteDocument(documentId: string): Promise<DeleteResponse>;
+    /**
+     * Wait for a document to finish processing.
+     */
+    waitForDocument(documentId: string, options?: {
+        /** Maximum time to wait in milliseconds (default: 300000 = 5 minutes) */
+        timeout?: number;
+        /** Time between status checks in milliseconds (default: 2000) */
+        pollInterval?: number;
+    }): Promise<DocumentStatus>;
+    /**
+     * List public marketplace products.
+     */
+    listMarketplace(request?: MarketplaceListRequest): Promise<MarketplaceListResponse>;
+    /**
+     * Get a marketplace product by ID or slug.
+     */
+    getMarketplaceProduct(idOrSlug: string): Promise<MarketplaceProduct>;
+    /**
+     * Map a raw marketplace product response to the SDK type.
+     */
+    private mapMarketplaceProduct;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}