Skip to main content

​
JavaScript/TypeScript SDK

npm version License: MIT The official JavaScript/TypeScript SDK for interacting with Plugged.in’s Library API. Easily manage documents, create AI-generated content, and perform RAG queries with full type safety.

NPM Package

View on NPM Registry

GitHub Repository

Source code and examples

​
Installation

  • npm
  • yarn
  • pnpm
npm install pluggedinkit-js

​
Quick Start

import { PluggedInClient } from 'pluggedinkit-js';

// Initialize the client
const client = new PluggedInClient({
  apiKey: 'your-api-key',
  // baseUrl defaults to https://plugged.in
});

// List documents
const documents = await client.documents.list({
  limit: 10,
  source: 'all'
});

// Search documents
const results = await client.documents.search('machine learning', {
  tags: ['ai', 'ml']
});

// Query RAG
const ragResponse = await client.rag.query('What are the latest updates?');
console.log(ragResponse.answer);
console.log('Matched documents:', ragResponse.documentIds);

​
Authentication

Get your API key from your Plugged.in Profile and configure the client: 
const client = new PluggedInClient({
  apiKey: process.env.PLUGGEDIN_API_KEY,
  baseUrl: process.env.PLUGGEDIN_BASE_URL || 'https://plugged.in',
  timeout: 60000, // 60 seconds
  maxRetries: 5,
  debug: true // Enable debug logging
});

// Update API key at runtime
client.setApiKey('new-api-key');

​
Core Features

​
Document Management

​
List Documents

import { DocumentFilters, DocumentSource, SortOrder } from 'pluggedinkit-js';

const filters: DocumentFilters = {
  source: 'ai_generated',
  tags: ['report', 'analysis'],
  sort: 'date_desc',
  limit: 20,
  offset: 0,
  category: 'documentation',
  dateFrom: '2024-01-01T00:00:00Z',
  modelProvider: 'anthropic'
};

const response = await client.documents.list(filters);

console.log(`Found ${response.total} documents`);
response.documents.forEach(doc => {
  console.log(`- ${doc.title} (${doc.fileSize} bytes)`);
});

​
Get Document

// Get metadata only
const doc = await client.documents.get('document-id');

// Get document with content and version history
const fullDoc = await client.documents.get('document-id', {
  includeContent: true,
  includeVersions: true
});

console.log(fullDoc.content);
console.log(`Version: ${fullDoc.version}`);

​
Search Documents

const searchResults = await client.documents.search('quarterly report', {
  modelProvider: 'anthropic',
  dateFrom: '2024-01-01T00:00:00Z',
  tags: ['finance', 'q4']
}, 10, 0);

searchResults.results.forEach(result => {
  console.log(`${result.title}`);
  console.log(`  Relevance: ${result.relevanceScore}`);
  console.log(`  Snippet: ${result.snippet}`);
});

​
Create AI-Generated Document

const newDoc = await client.documents.create(
  'API Integration Guide',
  '# API Integration Guide\n\n## Introduction\n\n...',
  {
    format: 'md',
    category: 'documentation',
    tags: ['api', 'integration', 'guide'],
    model: {
      name: 'claude-3-opus',
      provider: 'anthropic',
      version: '20240229'
    },
    prompt: 'Create a comprehensive API integration guide',
    context: 'User requested comprehensive API documentation',
    updateReason: 'Initial creation',
    changesFromPrompt: 'Created new guide as requested',
    changeSummary: 'New comprehensive API integration guide',
    conversationContext: [
      { role: 'user', content: 'Create an API guide' },
      { role: 'assistant', content: "I'll create a comprehensive guide..." }
    ],
    sourceDocuments: ['doc-123', 'doc-456'],
    visibility: 'workspace',
    sessionId: 'session-789',
    generationParams: {
      temperature: 0.7,
      maxTokens: 4000,
      topP: 0.9
    },
    // Dynamic fields - add any custom metadata
    customField: 'Any custom value',
    projectMetadata: {
      team: 'engineering',
      version: '1.0.0'
    }
  }
);

console.log(`Created document: ${newDoc.id}`);
// Access all metadata including custom fields
console.log('All metadata:', newDoc.aiMetadata);

​
Update Document

const updateResult = await client.documents.update('document-id', {
  operation: 'append',
  content: '\n\n## New Section\n\nAdditional content here.',
  metadata: {
    changeSummary: 'Added implementation details section',
    model: {
      name: 'gpt-4',
      provider: 'openai',
      version: '0613'
    },
    updateReason: 'Added new section on authentication',
    changesFromPrompt: 'User requested additional auth details',
    prompt: 'Add a section about OAuth 2.0 authentication',
    lastUpdatedBy: {
      name: 'gpt-4',
      provider: 'openai',
      version: '0613'
    },
    lastUpdateTimestamp: '2024-01-15T10:30:00Z',
    conversationContext: [
      { role: 'user', content: 'Add OAuth 2.0 section' },
      { role: 'assistant', content: 'Adding authentication details...' }
    ],
    // Custom metadata fields
    customUpdateMetadata: {
      reviewedBy: 'security-team',
      complianceCheck: 'passed'
    }
  }
});

console.log(`Document updated to version ${updateResult.version}`);

​
RAG Operations

​
Simple Query

const rag = await client.rag.query('What are our deployment procedures?');
console.log(rag.answer);

​
Query with Sources

const { answer, sources } = await client.rag.queryWithSources(
  'Explain the authentication flow'
);

console.log('Answer:', answer);
console.log('Sources:');
sources.forEach(source => {
  console.log(`- ${source.name} (${source.id})`);
});

​
Find Relevant Documents

const matches = await client.rag.findRelevantDocuments(
  'user authentication',
  undefined,
  5 // Top 5 documents
);

matches.forEach(match => {
  console.log(`- ${match.name} (${match.id})`);
});

// Storage statistics (requires your Plugged.in user id)
const stats = await client.rag.getStorageStats('user-id-from-dashboard');
console.log(`Indexed documents: ${stats.documentsCount}`);

​
File Uploads

Important: Direct file uploads are no longer exposed via the public API. The client.uploads helpers now throw descriptive errors so existing code fails fast. Use the Plugged.in web interface or the forthcoming ingestion workflow for binary files. AI-generated content can still be created with client.documents.create or client.uploads.uploadDocument.

​
Error Handling

The SDK provides typed error classes for better error handling: 
import {
  PluggedInError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError
} from 'pluggedinkit-js';

try {
  const doc = await client.documents.get('invalid-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key - please check your credentials');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
    // Implement retry logic
  } else if (error instanceof NotFoundError) {
    console.error('Document not found');
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.details);
  } else if (error instanceof PluggedInError) {
    console.error(`API error: ${error.message}`);
  }
}

​
TypeScript Support

The SDK is written in TypeScript and provides comprehensive type definitions: 
import type {
  Document,
  DocumentFilters,
  DocumentSource,
  DocumentVisibility,
  DocumentCategory,
  RagResponse,
  UploadMetadata,
  ModelInfo,
  UpdateOperation
} from 'pluggedinkit-js';

// All types are fully documented with JSDoc comments
const filters: DocumentFilters = {
  source: 'ai_generated',
  tags: ['important'],
  sort: 'date_desc',
  limit: 10
};

// TypeScript will provide autocompletion and type checking
const doc: Document = await client.documents.get('id');
console.log(doc.title); // Type-safe property access

​
Advanced Configuration

​
Environment Variables

# .env
PLUGGEDIN_API_KEY=your-api-key
PLUGGEDIN_BASE_URL=https://plugged.in

const client = new PluggedInClient({
  apiKey: process.env.PLUGGEDIN_API_KEY!,
  baseUrl: process.env.PLUGGEDIN_BASE_URL
});

​
Custom HTTP Client

const client = new PluggedInClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://plugged.in',
  timeout: 120000, // 2 minutes
  maxRetries: 10,
  debug: process.env.NODE_ENV === 'development',
  headers: {
    'X-Custom-Header': 'value'
  }
});

​
Rate Limiting

The SDK automatically handles rate limiting with exponential backoff:
  • API Endpoints: 60 requests per minute
  • Document Search: 10 requests per hour for AI document creation
  • RAG Queries: Subject to plan limits

​
Browser Support

The SDK works in both Node.js and browser environments: 
<!-- Browser usage with CDN -->
<script src="https://unpkg.com/pluggedinkit-js/dist/browser.js"></script>
<script>
  const client = new PluggedInKit.PluggedInClient({
    apiKey: 'your-api-key'
  });
</script>

​
Examples

Complete working examples are available in the GitHub repository:

​
API Reference

​
Client Options

OptionTypeDefaultDescription
apiKeystringrequiredYour Plugged.in API key
baseUrlstringhttps://plugged.inAPI base URL
timeoutnumber60000Request timeout in milliseconds
maxRetriesnumber5Maximum retry attempts
debugbooleanfalseEnable debug logging

​
Document Methods

MethodDescription
list(filters)List documents with optional filters
get(id, options)Get a specific document
search(query, filters, limit, offset)Search documents
create(title, content, metadata)Create a new document
update(id, request)Update an existing document
delete(id)Delete a document

​
RAG Methods

MethodDescription
query(question)Returns RagResponse with answer, sources, and document IDs
queryWithSources(question)Returns answer plus structured source metadata
findRelevantDocuments(query, limit?)Returns matched document references
getStorageStats(userId)Fetch aggregated storage metrics for the authenticated user
checkAvailability()Lightweight availability check

​
Upload Methods

All binary upload helpers now throw descriptive errors because the public API no longer exposes direct upload endpoints. Use the web interface or upcoming ingestion pipeline for file uploads.

​
Support