@insurup/sdk 0.0.1 → 0.1.1

package/README.md

@@ -1,194 +1,228 @@
 # InsurUp TypeScript SDK
 
-A comprehensive TypeScript SDK for the InsurUp platform, providing type-safe access to all insurance operations.
+[![npm version](https://img.shields.io/npm/v/@insurup/sdk.svg)](https://www.npmjs.com/package/@insurup/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
 
-## Features
+Type-safe TypeScript SDK for the InsurUp insurance platform. Zero dependencies, tree-shakeable, works everywhere.
 
-- **Type-safe**: Full TypeScript support with strict typing
-- **Cross-platform**: Works in both browser and Node.js environments
-- **Modern**: ES modules, tree-shaking support, discriminated unions
-- **Comprehensive**: Covers all InsurUp API endpoints
-- **Faithful port**: 1:1 mapping with the C# SDK API
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Result Handling](#result-handling)
+- [Configuration](#configuration)
+- [Interceptors](#interceptors)
+- [API Clients](#api-clients)
+- [Compatibility](#compatibility)
+- [License](#license)
+
+---
 
 ## Installation
 
 ```bash
 npm install @insurup/sdk
-# or
-yarn add @insurup/sdk
-# or
+```
+
+```bash
 pnpm add @insurup/sdk
 ```
 
+```bash
+yarn add @insurup/sdk
+```
+
+---
+
 ## Quick Start
 
 ```typescript
 import { DefaultInsurUpClient } from '@insurup/sdk';
 
-// Create client instance with token provider for OAuth
 const client = new DefaultInsurUpClient({
-  baseUrl: 'https://api.insurup.com/api/',
-  timeoutMs: 30000,
-  tokenProvider: () => getAccessToken() // Your OAuth token provider
+  tokenProvider: () => getAccessToken(),
 });
 
-// Fetch customer data
 const result = await client.customers.getCustomer('customer-id');
 
-if (result.kind === 'success') {
-  console.log('Customer:', result.data);
-} else {
-  console.error('Failed:', result.message);
+if (result.isSuccess) {
+  console.log(result.data);
 }
 ```
 
+---
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph SDK[DefaultInsurUpClient]
+        direction TB
+        HTTP[HttpTransport]
+        
+        subgraph Clients[Specialized Clients]
+            direction LR
+            C1[customers]
+            C2[policies]
+            C3[proposals]
+            C4[vehicles]
+            C5[properties]
+            C6[coverage]
+            C7[cases]
+            C8[agents]
+            C9[webhooks]
+            C10[...]
+        end
+    end
+    
+    App[Your Application] --> SDK
+    HTTP --> API[InsurUp API]
+    Clients --> HTTP
+```
+
+The SDK uses a **compositional architecture**:
+
+- `DefaultInsurUpClient` aggregates 17 specialized clients
+- All clients share a single `HttpTransport` instance
+- Request/response interceptors hook into the transport layer
+- Results use discriminated unions for type-safe error handling
+
+---
+
 ## Result Handling
 
-The SDK uses discriminated unions for type-safe result handling:
+Every API call returns an `InsurUpResult<T>` — a discriminated union that's either a success or an error:
 
 ```typescript
-const result = await client.customers.getCustomer('customer-id');
+const result = await client.customers.getCustomer('id');
 
-// Type-safe result handling
+// Pattern 1: Boolean check
+if (result.isSuccess) {
+  console.log(result.data); // fully typed
+} else {
+  console.error(result.message);
+}
+
+// Pattern 2: Switch on kind
 switch (result.kind) {
   case 'success':
-    console.log('Customer data:', result.data);
-    break;
+    return result.data;
   case 'server-error':
-    console.error('Server error:', result.detail, result.status);
-    break;
+    throw new Error(`${result.type}: ${result.message}`);
   case 'client-error':
-    console.error('Client error:', result.type, result.exception);
-    break;
+    throw new Error(`Network error: ${result.message}`);
 }
 
-// Or use type guards
-if (result.isSuccess) {
-  // TypeScript knows this is Success<T>
-  console.log(result.data);
-} else {
-  // TypeScript knows this is ServerError | ClientError
-  console.error(result.message);
-}
-```
-
-## Configuration Options
+// Pattern 3: Throw on error
+import { getDataOrThrow } from '@insurup/sdk';
 
-```typescript
-const client = new DefaultInsurUpClient({
-  baseUrl: 'https://api.insurup.com/api/',  // API base URL
-  customHeaders: {                          // Custom headers for all requests
-    'X-Custom-Header': 'value'
-  },
-  userAgent: 'MyApp/1.0.0',                // User agent (Node.js only)
-  timeoutMs: 30000                         // Request timeout in milliseconds
-});
+const customer = getDataOrThrow(await client.customers.getCustomer('id'));
 ```
 
-## Available Operations
-
-### Customer Management
-- `client.customers.createCustomer()` - Create new customer
-- `client.customers.getCustomer()` - Get customer by ID
-- `client.customers.getCurrentCustomer()` - Get current customer
-- `client.customers.updateCustomer()` - Update customer
-- `client.customers.deleteCustomer()` - Delete customer
-- Email and phone number management methods
+### Error Types
 
-### Policy Management
-- `client.policies.getPolicyDetail()` - Get policy details
-- `client.policies.fetchPolicyDocument()` - Fetch policy document URL
-- `client.policies.sendPolicyDocumentToCustomer()` - Send document to customer
-- `client.policies.setPolicyRepresentative()` - Set policy representative
+| Kind | Types |
+|------|-------|
+| `server-error` | `Unauthorized`, `AccessDenied`, `ResourceNotFound`, `InputValidation`, `BusinessValidation`, `Upstream` |
+| `client-error` | `Timeout`, `HttpRequestFailed`, `JsonDeserialization`, `NullResponse` |
 
-## Error Types
+---
 
-### Server Errors
-- `AccessDenied` - Access denied (403)
-- `Unauthorized` - Authentication required (401)
-- `ResourceNotFound` - Resource not found (404)
-- `InputValidation` - Validation errors (400)
-- `BusinessValidation` - Business rule violations
-- And more...
+## Configuration
 
-### Client Errors
-- `Timeout` - Request timeout
-- `HttpRequestFailed` - Network/HTTP errors
-- `JsonSerialization` - JSON serialization errors
-- `JsonDeserialization` - JSON parsing errors
-- `NullResponse` - Unexpected null response
-
-## Advanced Usage
+```typescript
+const client = new DefaultInsurUpClient({
+  baseUrl: 'https://api.insurup.com/api/',
+  tokenProvider: () => getAccessToken(),
+  timeoutMs: 30000,
+  customHeaders: { 'X-Request-Source': 'my-app' },
+  retry: { retries: 3, backoffStrategy: 'exponential' },
+  onRequest: (config) => config,
+  onResponse: (result, config) => result,
+});
+```
 
-### Using Endpoints Directly
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | `https://api.insurup.com/api/` | API base URL |
+| `tokenProvider` | `() => string \| Promise<string>` | — | OAuth token provider |
+| `timeoutMs` | `number` | `30000` | Request timeout |
+| `customHeaders` | `Record<string, string>` | — | Headers for all requests |
+| `retry` | `RetryOptions` | — | Retry configuration |
+| `onRequest` | `RequestInterceptor` | — | Pre-request hook |
+| `onResponse` | `ResponseInterceptor` | — | Post-response hook |
 
-```typescript
-import { Endpoints } from '@insurup/sdk';
+---
 
-// Access endpoint constants
-const customerEndpoint = Endpoints.customers.getCustomer.render('customer-id');
-const policyEndpoint = Endpoints.policies.getPolicyDetail.render('policy-id');
-```
+## Interceptors
 
-### Custom HTTP Headers
+Add logging, correlation IDs, or transform requests/responses:
 
 ```typescript
 const client = new DefaultInsurUpClient({
-  customHeaders: {
-    'Authorization': `Bearer your-token`,
-    'X-API-Version': '1.0'
-  }
+  tokenProvider: () => token,
+  
+  onRequest: (config) => {
+    console.log(`→ ${config.method} ${config.url}`);
+    return {
+      ...config,
+      headers: { ...config.headers, 'X-Correlation-ID': crypto.randomUUID() },
+    };
+  },
+  
+  onResponse: (result, config) => {
+    console.log(`← ${config.url} ${result.isSuccess ? '✓' : '✗'}`);
+    return result;
+  },
 });
 ```
 
-## Development Status
-
-✅ **Completed:**
-- Core runtime (result types, error handling, HTTP transport)
-- Endpoint definitions (1:1 port from C# SDK)
-- Customer management client methods
-- Policy management client methods
-- Build system and packaging
+---
 
-🚧 **In Progress:**
-- Additional contract types
-- Remaining client modules (Vehicle, Property, Coverage, etc.)
-- Comprehensive test coverage
+## API Clients
 
-📋 **Planned:**
-- Complete API coverage
-- Documentation generation
-- Usage examples
-- Performance optimizations
+Access specialized clients through the main client instance:
 
-## TypeScript Support
+| Client | Description |
+|--------|-------------|
+| `client.customers` | Customer profiles, contact info, health data |
+| `client.policies` | Policy details, documents, representatives |
+| `client.proposals` | Insurance proposals, comparisons, purchasing |
+| `client.vehicles` | Vehicle data, brand/model lookups |
+| `client.properties` | Property data, DASK earthquake insurance |
+| `client.coverage` | Coverage configuration, coverage groups |
+| `client.cases` | Service requests, claims, complaints |
+| `client.agents` | Agent profiles, company connections |
+| `client.agentBranches` | Branch management |
+| `client.agentRoles` | Role-based access control |
+| `client.agentUsers` | Agency staff management |
+| `client.agentSetup` | Agent onboarding |
+| `client.webhooks` | Event notifications, integrations |
+| `client.insurance` | Companies, products, resource keys |
+| `client.files` | File uploads and management |
+| `client.languages` | Localization support |
+| `client.templates` | Document and email templates |
 
-This SDK is built with TypeScript and provides full type safety:
+---
 
-```typescript
-import type { CreateCustomerEndpointRequest, InsurUpResult, GetCustomerEndpointResponse } from '@insurup/sdk';
+## Compatibility
 
-// All request/response types are strongly typed
-const request: CreateCustomerEndpointRequest = {
-  type: 'INDIVIDUAL',
-  identityNumber: '12345678901',
-  fillMissingFields: true
-};
+| Environment | Support |
+|-------------|---------|
+| Node.js | 18+ |
+| Browsers | ES2022+ (Chrome 94+, Firefox 93+, Safari 15+) |
+| Bun | ✓ |
+| Deno | ✓ |
 
-// Results are discriminated unions for type safety
-const result: InsurUpResult<GetCustomerEndpointResponse> = await client.customers.getCustomer('id');
-```
+Dual ESM/CJS builds included. Full tree-shaking support.
 
-## Browser Compatibility
-
-- Modern browsers with ES2022 support
-- Node.js 18+
-- Supports both ESM and CommonJS
+---
 
 ## License
 
-MIT License - see LICENSE file for details.
-
-## Contributing
-
-This SDK is automatically generated from the C# SDK. Please contribute to the main InsurUp repository.
+[MIT](LICENSE)

package/dist/index.cjs

@@ -109,17 +109,33 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@insurup/sdk",
-  version: "0.1.0",
-  description: "TypeScript SDK for InsurUp platform - A comprehensive client library for insurance operations",
+  version: "0.1.1",
+  description: "Type-safe TypeScript SDK for the InsurUp insurance platform. Zero dependencies, tree-shakeable, works everywhere.",
   keywords: [
+    "insurup",
     "insurance",
     "sdk",
     "typescript",
     "api-client",
-    "insurup"
+    "policy",
+    "claims",
+    "coverage",
+    "vehicle-insurance",
+    "property-insurance"
   ],
   author: "InsurUp Team",
   license: "MIT",
+  homepage: "https://github.com/InsurUp/ts-sdk#readme",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/InsurUp/ts-sdk.git"
+  },
+  bugs: {
+    url: "https://github.com/InsurUp/ts-sdk/issues"
+  },
+  engines: {
+    node: ">=18"
+  },
   type: "module",
   sideEffects: false,
   main: "./dist/index.cjs",