@delegance/sdk 0.1.0

package/README.md

@@ -0,0 +1,308 @@
+# @delegance/sdk
+
+TypeScript SDK for integrating with the Delegance Brokerage platform.
+
+## Installation
+
+```bash
+npm install @delegance/sdk
+# or
+yarn add @delegance/sdk
+# or
+pnpm add @delegance/sdk
+```
+
+## Quick Start
+
+```typescript
+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: 'contact@abcconstruction.com',
+  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
+
+```typescript
+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:
+
+```typescript
+import { createClientFromEnv } from '@delegance/sdk';
+
+// Reads DELEGANCE_API_KEY and optionally DELEGANCE_BASE_URL
+const client = createClientFromEnv();
+```
+
+## API Reference
+
+### Companies
+
+#### Create a Company
+
+```typescript
+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: 'contact@abc.com',   // 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
+
+```typescript
+// 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)
+
+```typescript
+const { company, isExisting } = await client.companies.upsert({
+  name: 'ABC Construction',
+  industry: 'construction',
+  companySize: '11-25',
+  contactEmail: 'contact@abc.com',
+  externalId: 'ams-12345'  // Deduplication key
+});
+
+if (isExisting) {
+  console.log('Company already existed');
+}
+```
+
+### Documents
+
+#### Upload a Document
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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: support@delegance.ai