@delegance/sdk

TypeScript SDK for integrating with the Delegance Brokerage platform.

Installation

npm install @delegance/sdk
# or
yarn add @delegance/sdk
# or
pnpm add @delegance/sdk

Quick Start

import { DeleganceClient } from '@delegance/sdk';
import fs from 'fs';

// Initialize the client
const client = new DeleganceClient({
  apiKey: 'dlg_xxxxxxxx_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
});

// Create a company
const company = await client.companies.create({
  name: 'ABC Construction',
  industry: 'construction',
  companySize: '11-25',
  contactEmail: '[email protected]',
  fein: '12-3456789',
  address: {
    street: '123 Main St',
    city: 'Austin',
    state: 'TX',
    zip: '78701'
  }
});

console.log('Created company:', company.id);

// Upload a policy document
const doc = await client.documents.upload({
  companyId: company.id,
  file: fs.readFileSync('./GL-Policy-2025.pdf'),
  fileName: 'GL-Policy-2025.pdf',
  documentType: 'policy'
});

console.log('Document uploaded:', doc.id, 'Status:', doc.status);

// Wait for extraction to complete
const result = await client.documents.waitForExtraction(doc.id, {
  timeoutMs: 60000,
  onStatusChange: (status) => console.log('Processing:', status)
});

if (result.extraction) {
  console.log('Extracted policies:', result.extraction.policies);
}

Configuration

Client Options

const client = new DeleganceClient({
  // Required: Your API key
  apiKey: 'dlg_xxxxxxxx_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  
  // Optional: API base URL (default: https://app.delegance.ai)
  baseUrl: 'https://app.delegance.ai',
  
  // Optional: Request timeout in ms (default: 30000)
  timeout: 30000,
  
  // Optional: Number of retry attempts (default: 3)
  retries: 3,
  
  // Optional: Custom headers
  headers: {
    'X-Custom-Header': 'value'
  }
});

Environment Variables

You can also create a client from environment variables:

import { createClientFromEnv } from '@delegance/sdk';

// Reads DELEGANCE_API_KEY and optionally DELEGANCE_BASE_URL
const client = createClientFromEnv();

API Reference

Companies

Create a Company

const company = await client.companies.create({
  name: 'ABC Construction',           // Required
  industry: 'construction',           // Required
  companySize: '11-25',              // Required: '1', '2-10', '11-25', '26-50', '51-100', '100-499', '500+'
  contactEmail: '[email protected]',   // Required
  
  // Optional fields
  legalName: 'ABC Construction LLC',
  fein: '12-3456789',
  website: 'https://abc.com',
  yearEstablished: '2015',
  companyStructure: 'LLC',
  description: 'Commercial construction company',
  contactPhone: '+1-555-123-4567',
  externalId: 'ams-12345',           // For deduplication
  address: {
    street: '123 Main St',
    suite: 'Suite 100',
    city: 'Austin',
    state: 'TX',
    zip: '78701'
  }
});

List Companies

// List your company
const companies = await client.companies.list();

// Include companies created via this API key
const allCompanies = await client.companies.list({ includeCreated: true });

Upsert (Create if not exists)

const { company, isExisting } = await client.companies.upsert({
  name: 'ABC Construction',
  industry: 'construction',
  companySize: '11-25',
  contactEmail: '[email protected]',
  externalId: 'ams-12345'  // Deduplication key
});

if (isExisting) {
  console.log('Company already existed');
}

Documents

Upload a Document

import fs from 'fs';

const doc = await client.documents.upload({
  companyId: 'company-uuid',
  file: fs.readFileSync('./policy.pdf'),  // Buffer, Blob, or base64 string
  fileName: 'policy.pdf',
  
  // Optional
  documentType: 'policy',    // 'policy', 'loss_run', 'financial_statement', 'sov', 'application', 'certificate', 'endorsement', 'bor', 'other'
  externalId: 'doc-123',     // For deduplication
  metadata: { source: 'ams' }
});

Upload Multiple Documents

const { documents, errors } = await client.documents.uploadBatch([
  { companyId, file: buffer1, fileName: 'policy1.pdf' },
  { companyId, file: buffer2, fileName: 'policy2.pdf' },
  { companyId, file: buffer3, fileName: 'policy3.pdf' }
], { concurrency: 3 });

console.log(`Uploaded ${documents.length} documents`);
if (errors.length > 0) {
  console.error('Failed uploads:', errors);
}

Get Document Status

const doc = await client.documents.get('document-uuid');

console.log('Status:', doc.status);
// 'pending' | 'processing' | 'completed' | 'processed' | 'error' | 'failed'

if (doc.extraction) {
  console.log('Extracted policies:', doc.extraction.policies);
}

List Documents

// List all documents
const { documents, pagination } = await client.documents.list();

// Filter by type and status
const policies = await client.documents.list({
  documentType: 'policy',
  status: 'completed',
  limit: 50,
  offset: 0
});

// Paginate
while (pagination.hasMore) {
  const next = await client.documents.list({ offset: pagination.offset + 50 });
  // ...
}

Wait for Extraction

const result = await client.documents.waitForExtraction('document-uuid', {
  timeoutMs: 120000,      // 2 minutes max
  pollIntervalMs: 2000,   // Check every 2 seconds
  onStatusChange: (status) => console.log('Status:', status)
});

if (result.status === 'completed') {
  console.log('Policies found:', result.extraction?.policies.length);
} else if (result.status === 'error') {
  console.error('Processing failed:', result.error?.message);
}

Error Handling

The SDK throws typed errors for different scenarios:

import { 
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  DeleganceError
} from '@delegance/sdk';

try {
  await client.documents.get('invalid-uuid');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.error('Document not found');
  } else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.details);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof DeleganceError) {
    console.error('API error:', error.message, 'Status:', error.statusCode);
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type {
  Company,
  Document,
  DocumentWithExtraction,
  ExtractedPolicy,
  CreateCompanyInput,
  UploadDocumentInput
} from '@delegance/sdk';

// Use Zod schemas for validation
import { CreateCompanySchema, DocumentTypeSchema } from '@delegance/sdk';

const result = CreateCompanySchema.safeParse(data);
if (!result.success) {
  console.error(result.error.issues);
}

Getting an API Key

1. Log in to the Delegance dashboard
2. Navigate to Settings > API Keys
3. Click "Create API Key"
4. Copy the key (it's only shown once!)

API keys have the format: dlg_xxxxxxxx_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Support

• Documentation: https://docs.delegance.ai
• Issues: https://github.com/delegance/delegance-sdk/issues
• Email: [email protected]