{"_id":"@denserai/retriever-sdk","name":"@denserai/retriever-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@denserai/retriever-sdk","version":"0.1.0","description":"Official TypeScript SDK for Denser Retriever Platform","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build","publish:npm":"node publish.js","publish:test":"npm pack --dry-run"},"keywords":["rag","denser","retriever","sdk","ai"],"author":"","license":"MIT","devDependencies":{"typescript":"^5.0.0","@types/node":"^18.0.0"},"dependencies":{"axios":"^1.6.0"},"_id":"@denserai/retriever-sdk@0.1.0","gitHead":"5914c371582ce005664927cbe4ef07bda634a06f","_nodeVersion":"24.13.0","_npmVersion":"10.8.0","dist":{"integrity":"sha512-GavH+9yxoxIPm+AhVqw1iCNBnXD1t0RjbbZPhk6BA7DyzOGS7yvHsRdgVhl6TOesRPFkPAKmFMt4ibK0tnNHJw==","shasum":"780d3a1e15d616582865f9abcfa460ad38fb821a","tarball":"https://registry.npmjs.org/@denserai/retriever-sdk/-/retriever-sdk-0.1.0.tgz","fileCount":6,"unpackedSize":26574,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCID5QObyBtfM3ft9gMcKlEpQuhy2CCuxWl1aznooqYxfMAiEAj27kup3A1T3KFsfp8tYn16spxgecsBW4rFTYE7RV88k="}]},"_npmUser":{"name":"jotyyy","email":"jotyy318@gmail.com"},"directories":{},"maintainers":[{"name":"gaosong886","email":"gaosong886@gmail.com"},{"name":"jotyyy","email":"jotyy318@gmail.com"},{"name":"denser","email":"support@denser.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/retriever-sdk_0.1.0_1770876923797_0.2851536461534012"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-12T06:15:23.734Z","0.1.0":"2026-02-12T06:15:23.946Z","modified":"2026-02-12T06:15:24.117Z"},"maintainers":[{"name":"gaosong886","email":"gaosong886@gmail.com"},{"name":"jotyyy","email":"jotyy318@gmail.com"},{"name":"denser","email":"support@denser.ai"}],"description":"Official TypeScript SDK for Denser Retriever Platform","keywords":["rag","denser","retriever","sdk","ai"],"license":"MIT","readme":"# Denser Retriever SDK for TypeScript\r\n\r\nThe official TypeScript SDK for Denser Retriever Platform. Build powerful semantic search and retrieval applications with an intuitive API for knowledge base management, document ingestion, and intelligent querying.\r\n\r\n## Table of Contents\r\n\r\n- [Installation](#installation)\r\n- [Quick Start](#quick-start)\r\n- [Configuration](#configuration)\r\n- [API Reference](#api-reference)\r\n  - [Account Methods](#account-methods)\r\n  - [Knowledge Base Methods](#knowledge-base-methods)\r\n  - [Document Methods](#document-methods)\r\n  - [Query Methods](#query-methods)\r\n- [Error Handling](#error-handling)\r\n\r\n## Installation\r\n\r\nInstall the SDK via npm:\r\n\r\n```bash\r\nnpm install @denserai/retriever-sdk\r\n```\r\n\r\n## Quick Start\r\n\r\n```typescript\r\nimport { DenserRetriever } from \"@denserai/retriever-sdk\";\r\n\r\nconst client = new DenserRetriever({\r\n  apiKey: \"your-api-key\"\r\n});\r\n\r\nasync function quickExample() {\r\n  // Create a knowledge base\r\n  const kb = await client.createKnowledgeBase(\"My First KB\");\r\n  const kbId = kb.data.id;\r\n\r\n  // Import text content\r\n  await client.importTextContentAndPoll(\r\n    kbId,\r\n    \"Getting Started\",\r\n    \"Denser Retriever enables semantic search across your documents.\"\r\n  );\r\n\r\n  // Search\r\n  const results = await client.query(\"semantic search\", {\r\n    knowledgeBaseIds: [kbId],\r\n    limit: 5\r\n  });\r\n\r\n  console.log(results.data);\r\n\r\n  // Cleanup\r\n  await client.deleteKnowledgeBase(kbId);\r\n}\r\n```\r\n\r\n## Configuration\r\n\r\nInitialize the client with your API credentials:\r\n\r\n```typescript\r\nimport { DenserRetriever } from \"@denserai/retriever-sdk\";\r\n\r\nconst client = new DenserRetriever({\r\n  apiKey: \"YOUR_API_KEY\",        // Required: Your API key\r\n  timeout: 30000                  // Optional: Request timeout in ms (default: 10000)\r\n});\r\n```\r\n\r\n## API Reference\r\n\r\nAll methods return a `Promise<ApiResponse<T>>` where `T` is the response data type.\r\n\r\n### Account Methods\r\n\r\n#### `getUsage(): Promise<ApiResponse<UsageData>>`\r\n\r\nRetrieve current usage statistics for your organization.\r\n\r\n```typescript\r\nconst usage = await client.getUsage();\r\nconsole.log(`Knowledge Bases: ${usage.data.knowledgeBaseCount}`);\r\nconsole.log(`Storage Used: ${usage.data.storageUsed} bytes`);\r\n```\r\n\r\n**Response:**\r\n\r\n```typescript\r\n{\r\n  success: boolean;\r\n  data: {\r\n    knowledgeBaseCount: number;\r\n    storageUsed: number; // bytes\r\n  }\r\n}\r\n```\r\n\r\n#### `getBalance(): Promise<ApiResponse<BalanceData>>`\r\n\r\nRetrieve current credit balance for your account.\r\n\r\n```typescript\r\nconst balance = await client.getBalance();\r\nconsole.log(`Balance: ${balance.data.balance} credits`);\r\n```\r\n\r\n**Response:**\r\n\r\n```typescript\r\n{\r\n  success: boolean;\r\n  data: {\r\n    balance: number;\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n### Knowledge Base Methods\r\n\r\n#### `createKnowledgeBase(name: string, description?: string): Promise<ApiResponse<KnowledgeBase>>`\r\n\r\nCreate a new knowledge base.\r\n\r\n**Parameters:**\r\n\r\n- `name` - Knowledge base name (required)\r\n- `description` - Optional description\r\n\r\n```typescript\r\nconst kb = await client.createKnowledgeBase(\r\n  \"Technical Documentation\",\r\n  \"Product docs and API references\"\r\n);\r\nconst kbId = kb.data.id;\r\n```\r\n\r\n**Response:**\r\n\r\n```typescript\r\n{\r\n  success: boolean;\r\n  data: {\r\n    id: string;\r\n    name: string;\r\n    description: string | null;\r\n    createdAt: string;\r\n    updatedAt: string;\r\n  }\r\n}\r\n```\r\n\r\n#### `listKnowledgeBases(): Promise<ApiResponse<KnowledgeBase[]>>`\r\n\r\nList all knowledge bases in your organization.\r\n\r\n```typescript\r\nconst kbs = await client.listKnowledgeBases();\r\nkbs.data.forEach(kb => {\r\n  console.log(`${kb.name} (ID: ${kb.id})`);\r\n});\r\n```\r\n\r\n#### `updateKnowledgeBase(id: string, data: UpdateKBData): Promise<ApiResponse<KnowledgeBase>>`\r\n\r\nUpdate knowledge base metadata.\r\n\r\n**Parameters:**\r\n\r\n- `id` - Knowledge base ID (required)\r\n- `data.name` - New name (optional)\r\n- `data.description` - New description (optional)\r\n\r\n```typescript\r\nawait client.updateKnowledgeBase(kbId, {\r\n  name: \"Updated Name\",\r\n  description: \"Updated description\"\r\n});\r\n```\r\n\r\n#### `deleteKnowledgeBase(id: string): Promise<ApiResponse<{id: string}>>`\r\n\r\nPermanently delete a knowledge base and all its documents.\r\n\r\n```typescript\r\nawait client.deleteKnowledgeBase(kbId);\r\n```\r\n\r\n---\r\n\r\n### Document Methods\r\n\r\n#### File Upload Workflow\r\n\r\nUploading files requires a three-step process:\r\n\r\n##### Step 1: Get Presigned URL\r\n\r\n#### `presignUploadUrl(knowledgeBaseId: string, fileName: string, size: number): Promise<ApiResponse<PresignedUrlData>>`\r\n\r\nGenerate a presigned S3 URL for file upload.\r\n\r\n**Parameters:**\r\n\r\n- `knowledgeBaseId` - Target knowledge base ID\r\n- `fileName` - File name with extension\r\n- `size` - File size in bytes (max: 52,428,800)\r\n\r\n```typescript\r\nconst presign = await client.presignUploadUrl(kbId, \"document.pdf\", 1024000);\r\nconst { fileId, uploadUrl, expiresAt } = presign.data;\r\n```\r\n\r\n##### Step 2: Upload File to S3\r\n\r\nUse any HTTP client (e.g., axios, fetch) to PUT the file to the presigned URL:\r\n\r\n```typescript\r\nimport axios from \"axios\";\r\nimport fs from \"fs\";\r\n\r\nconst fileStream = fs.createReadStream(filePath);\r\nawait axios.put(uploadUrl, fileStream, {\r\n  headers: {\r\n    \"Content-Type\": \"application/octet-stream\",\r\n    \"Content-Length\": fileSize\r\n  }\r\n});\r\n```\r\n\r\n##### Step 3: Register and Process\r\n\r\n#### `importFile(fileId: string): Promise<ApiResponse<DocumentInfo>>`\r\n\r\nRegister the uploaded file for processing.\r\n\r\n```typescript\r\nconst doc = await client.importFile(fileId);\r\nconsole.log(`Document ID: ${doc.data.id}, Status: ${doc.data.status}`);\r\n```\r\n\r\n#### `importFileAndPoll(fileId: string, options?: PollOptions): Promise<ApiResponse<DocumentInfo>>`\r\n\r\nRegister file and automatically poll until processing completes.\r\n\r\n**Parameters:**\r\n\r\n- `fileId` - File ID from presignUploadUrl\r\n- `options.intervalMs` - Polling interval in milliseconds (default: 2000)\r\n- `options.timeoutMs` - Maximum wait time in milliseconds (default: 600000)\r\n\r\n```typescript\r\nconst doc = await client.importFileAndPoll(fileId, {\r\n  intervalMs: 2000,\r\n  timeoutMs: 600000\r\n});\r\n// Returns when status is \"processed\" or throws on \"failed\"/\"timeout\"\r\n```\r\n\r\n---\r\n\r\n#### Text Content Import\r\n\r\n#### `importTextContent(knowledgeBaseId: string, title: string, content: string): Promise<ApiResponse<DocumentInfo>>`\r\n\r\nImport text content directly as a document.\r\n\r\n**Parameters:**\r\n\r\n- `knowledgeBaseId` - Target knowledge base ID\r\n- `title` - Document title (max: 256 chars)\r\n- `content` - Text content (max: 1,000,000 chars)\r\n\r\n```typescript\r\nconst doc = await client.importTextContent(\r\n  kbId,\r\n  \"API Documentation\",\r\n  \"Complete API reference and usage examples...\"\r\n);\r\n```\r\n\r\n#### `importTextContentAndPoll(knowledgeBaseId: string, title: string, content: string, options?: PollOptions): Promise<ApiResponse<DocumentInfo>>`\r\n\r\nImport text content and poll until processing completes.\r\n\r\n```typescript\r\nconst doc = await client.importTextContentAndPoll(\r\n  kbId,\r\n  \"Release Notes\",\r\n  \"Version 2.0 includes...\",\r\n  { intervalMs: 1000, timeoutMs: 300000 }\r\n);\r\n```\r\n\r\n---\r\n\r\n#### Document Management\r\n\r\n#### `listDocuments(knowledgeBaseId: string): Promise<ApiResponse<DocumentInfo[]>>`\r\n\r\nList all documents in a knowledge base.\r\n\r\n```typescript\r\nconst docs = await client.listDocuments(kbId);\r\ndocs.data.forEach(doc => {\r\n  console.log(`${doc.title} - ${doc.status} (${doc.size} bytes)`);\r\n});\r\n```\r\n\r\n**Response:**\r\n\r\n```typescript\r\n{\r\n  success: boolean;\r\n  data: Array<{\r\n    id: string;\r\n    title: string;\r\n    type: string;\r\n    size: number;\r\n    status: \"pending\" | \"processing\" | \"processed\" | \"failed\" | \"timeout\";\r\n    createdAt: string;\r\n  }>\r\n}\r\n```\r\n\r\n#### `getDocumentStatus(documentId: string): Promise<ApiResponse<DocumentStatusData>>`\r\n\r\nCheck document processing status.\r\n\r\n```typescript\r\nconst status = await client.getDocumentStatus(docId);\r\nconsole.log(`Status: ${status.data.status}`);\r\n```\r\n\r\n**Status Values:**\r\n\r\n- `pending` - Queued for processing\r\n- `processing` - Currently being processed\r\n- `processed` - Successfully processed and searchable\r\n- `failed` - Processing failed\r\n- `timeout` - Processing timed out\r\n\r\n#### `deleteDocument(documentId: string): Promise<ApiResponse<{id: string}>>`\r\n\r\nPermanently delete a document.\r\n\r\n```typescript\r\nawait client.deleteDocument(docId);\r\n```\r\n\r\n---\r\n\r\n### Query Methods\r\n\r\n#### `query(content: string, options?: QueryOptions): Promise<ApiResponse<QueryResultItem[]>>`\r\n\r\nPerform semantic search across knowledge bases.\r\n\r\n**Parameters:**\r\n\r\n- `content` - Search query (required, 1-8192 chars)\r\n- `options.knowledgeBaseIds` - Filter by specific knowledge bases (optional)\r\n- `options.limit` - Maximum results (optional, default: 10, max: 50)\r\n\r\n```typescript\r\n// Search across all knowledge bases\r\nconst results = await client.query(\"machine learning algorithms\");\r\n\r\n// Search within specific knowledge bases\r\nconst results = await client.query(\"deployment guide\", {\r\n  knowledgeBaseIds: [kbId1, kbId2],\r\n  limit: 20\r\n});\r\n\r\n// Process results\r\nresults.data.forEach(item => {\r\n  console.log(`Score: ${item.score.toFixed(3)}`);\r\n  console.log(`Title: ${item.title}`);\r\n  console.log(`Content: ${item.content}`);\r\n  console.log(`Document: ${item.document_id}`);\r\n  console.log(`KB: ${item.knowledge_base_id}`);\r\n  console.log(`Metadata:`, item.metadata);\r\n  console.log(\"---\");\r\n});\r\n```\r\n\r\n**Response:**\r\n\r\n```typescript\r\n{\r\n  success: boolean;\r\n  data: Array<{\r\n    id: string;\r\n    score: number;\r\n    document_id: string;\r\n    knowledge_base_id: string;\r\n    title: string;\r\n    type: string;\r\n    content: string;\r\n    metadata?: {\r\n      source?: string | null;\r\n      annotations?: string;\r\n    }\r\n  }>\r\n}\r\n```\r\n\r\n## Error Handling\r\n\r\nThe SDK throws `APIError` for all API-related errors, providing structured error information for robust error handling.\r\n\r\n### APIError Class\r\n\r\n```typescript\r\nclass APIError extends Error {\r\n  code: string;           // Machine-readable error code\r\n  message: string;        // Human-readable error message\r\n  httpStatus: number;     // HTTP status code\r\n  data?: object;          // Additional error context\r\n}\r\n```\r\n\r\n### Error Handling Pattern\r\n\r\n```typescript\r\nimport { DenserRetriever, APIError } from \"@denserai/retriever-sdk\";\r\n\r\ntry {\r\n  const results = await client.query(\"search term\", {\r\n    knowledgeBaseIds: [\"invalid-kb-id\"],\r\n    limit: 5\r\n  });\r\n  console.log(results.data);\r\n} catch (error) {\r\n  if (error instanceof APIError) {\r\n    console.error(`[${error.code}] ${error.message}`);\r\n    console.error(`HTTP Status: ${error.httpStatus}`);\r\n    \r\n    // Handle specific error codes\r\n    switch (error.code) {\r\n      case \"INSUFFICIENT_CREDITS\":\r\n        console.error(\"Please top up your account to continue.\");\r\n        break;\r\n      case \"NOT_FOUND\":\r\n        console.error(\"The requested resource does not exist.\");\r\n        break;\r\n      case \"STORAGE_LIMIT_EXCEEDED\":\r\n        console.error(\"Storage quota exceeded:\", error.data);\r\n        break;\r\n      case \"KNOWLEDGE_BASE_LIMIT_EXCEEDED\":\r\n        console.error(\"Maximum knowledge bases reached.\");\r\n        break;\r\n      default:\r\n        console.error(\"An error occurred:\", error.message);\r\n    }\r\n  } else {\r\n    console.error(\"Unexpected error:\", error);\r\n  }\r\n}\r\n```\r\n\r\n### Common Error Codes\r\n\r\n| Error Code | HTTP Status | Description |\r\n| --------- | ----------- | ----------- |\r\n| `INPUT_VALIDATION_FAILED` | 422 | Request parameters failed validation |\r\n| `UNAUTHORIZED` | 401 | Invalid or missing API key |\r\n| `FORBIDDEN` | 403 | Access to resource is denied |\r\n| `NOT_FOUND` | 404 | Requested resource does not exist |\r\n| `INSUFFICIENT_CREDITS` | 403 | Account has insufficient credits |\r\n| `STORAGE_LIMIT_EXCEEDED` | 403 | Storage quota exceeded |\r\n| `KNOWLEDGE_BASE_LIMIT_EXCEEDED` | 403 | Maximum knowledge bases reached |\r\n| `INTERNAL_SERVER_ERROR` | 500 | Server encountered an error |\r\n","readmeFilename":"README.md","_rev":"1-7285768fa3e623b178e0135e96a60a6a"}