Skip to main content

​
Installation

The Raptor TypeScript SDK provides a simple, type-safe interface for interacting with the Raptor Data API.

​
Requirements

  • Node.js: 18.0.0 or higher
  • TypeScript (optional): 4.5.0 or higher
  • Package Manager: npm, yarn, or pnpm

​
Install the SDK

npm install @raptor-data/ts-sdk
The package name is @raptor-data/ts-sdk (with hyphens), not @raptordata/sdk.

​
Get Your API Key

  1. Sign up at raptordata.dev/app
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Copy the API key (shown only once)

​
Basic Setup

​
TypeScript / ES Modules

import Raptor from '@raptor-data/ts-sdk';

const raptor = new Raptor({
  apiKey: 'your-api-key-here'
});

​
CommonJS

const Raptor = require('@raptor-data/ts-sdk').default;

const raptor = new Raptor({
  apiKey: 'your-api-key-here'
});

​
Configuration Options

const raptor = new Raptor({
  // Required
  apiKey: string,

  // Optional
  baseUrl?: string,              // Default: 'https://api.raptordata.dev'
  timeout?: number,               // Default: 300000 (5 minutes)
  maxPollAttempts?: number,       // Default: 300
  pollTimeout?: number            // Default: 300000 (5 minutes)
});

​
Configuration Details

​
apiKey
string
required
Your Raptor API key from the dashboard
​
baseUrl
string
default:"https://api.raptordata.dev"
API base URL. Override for local development or custom deployments
​
timeout
number
default:"300000"
Request timeout in milliseconds (5 minutes default)
​
maxPollAttempts
number
default:"300"
Maximum polling attempts when waiting for processing to complete
​
pollTimeout
number
default:"300000"
Total polling timeout in milliseconds (5 minutes default)

​
Environment Variables

Store your API key securely using environment variables:

​
Create .env file

# .env
RAPTOR_API_KEY=rd_live_abc123def456...

​
Load with dotenv

import Raptor from '@raptor-data/ts-sdk';
import dotenv from 'dotenv';

dotenv.config();

const raptor = new Raptor({
  apiKey: process.env.RAPTOR_API_KEY
});

​
Next.js

# .env.local
RAPTOR_API_KEY=rd_live_abc123def456...
In Next.js, only use the SDK in server-side code (API routes, getServerSideProps, Server Components). Never expose API keys in client-side code.
// app/api/process/route.ts
import Raptor from '@raptor-data/ts-sdk';

const raptor = new Raptor({
  apiKey: process.env.RAPTOR_API_KEY
});

export async function POST(request: Request) {
  const formData = await request.formData();
  const file = formData.get('file');

  const result = await raptor.process(file);
  return Response.json(result);
}

​
Verify Installation

Test your setup with a simple script: 
import Raptor from '@raptor-data/ts-sdk';

const raptor = new Raptor({
  apiKey: process.env.RAPTOR_API_KEY
});

async function test() {
  try {
    // Get auto-link settings (quick API test)
    const settings = await raptor.getAutoLinkSettings();
    console.log('✅ SDK configured successfully');
    console.log('Auto-link settings:', settings);
  } catch (error) {
    console.error('❌ Configuration error:', error.message);
  }
}

test();
Run the script: 
node test.js
# or with ts-node
ts-node test.ts
Expected output: 
✅ SDK configured successfully
Auto-link settings: { autoLinkEnabled: true, autoLinkThreshold: 0.85 }

​
TypeScript Configuration

For optimal TypeScript support, ensure your tsconfig.json includes: 
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true
  }
}

​
Type Definitions

The SDK includes full TypeScript type definitions: 
import Raptor, {
  type RaptorConfig,
  type ProcessOptions,
  type ProcessResponse,
  type Document,
  type DocumentVersion,
  type ProcessingVariant,
  type Chunk,
  type DedupSummary
} from '@raptor-data/ts-sdk';

const raptor: Raptor = new Raptor({ apiKey: 'key' });

const options: ProcessOptions = {
  chunkSize: 512,
  strategy: 'semantic'
};

const result: ProcessResponse = await raptor.process(file, options);

​
Troubleshooting

​
Module not found

Error: 
Cannot find module '@raptor-data/ts-sdk'
Solutions:
  1. Verify installation: npm list @raptor-data/ts-sdk
  2. Check package name (should be @raptor-data/ts-sdk, not @raptordata/sdk)
  3. Delete node_modules and reinstall: 
    rm -rf node_modules package-lock.json
npm install

​
TypeScript errors

Error: 
Cannot find module '@raptor-data/ts-sdk' or its corresponding type declarations
Solution: Ensure moduleResolution is set to "node" in tsconfig.json: 
{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

​
API key errors

Error: 
unauthorized: Invalid or missing API key
Solutions:
  1. Verify API key is correct
  2. Check environment variable is loaded: 
    console.log('API Key:', process.env.RAPTOR_API_KEY); // Should not be undefined
  3. Verify .env file is in the correct location
  4. If using Next.js, restart the dev server after changing .env.local

​
Network errors

Error: 
ECONNREFUSED or ETIMEDOUT
Solutions:
  1. Check internet connection
  2. Verify firewall settings
  3. Try increasing timeout: 
    const raptor = new Raptor({
  apiKey: 'key',
  timeout: 600000 // 10 minutes
});

​
Next Steps

Quickstart

Upload your first document

Processing

Learn about document processing options

Authentication

API key best practices

Error Handling

Handle errors gracefully