@insurup/sdk 0.0.1

package/README.md

@@ -0,0 +1,194 @@
+# InsurUp TypeScript SDK
+
+A comprehensive TypeScript SDK for the InsurUp platform, providing type-safe access to all insurance operations.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install @insurup/sdk
+# or
+yarn add @insurup/sdk
+# or
+pnpm 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
+});
+
+// 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);
+}
+```
+
+## Result Handling
+
+The SDK uses discriminated unions for type-safe result handling:
+
+```typescript
+const result = await client.customers.getCustomer('customer-id');
+
+// Type-safe result handling
+switch (result.kind) {
+  case 'success':
+    console.log('Customer data:', result.data);
+    break;
+  case 'server-error':
+    console.error('Server error:', result.detail, result.status);
+    break;
+  case 'client-error':
+    console.error('Client error:', result.type, result.exception);
+    break;
+}
+
+// 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
+
+```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
+});
+```
+
+## 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
+
+### 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
+
+## 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...
+
+### Client Errors
+- `Timeout` - Request timeout
+- `HttpRequestFailed` - Network/HTTP errors
+- `JsonSerialization` - JSON serialization errors
+- `JsonDeserialization` - JSON parsing errors
+- `NullResponse` - Unexpected null response
+
+## Advanced Usage
+
+### Using Endpoints Directly
+
+```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');
+```
+
+### Custom HTTP Headers
+
+```typescript
+const client = new DefaultInsurUpClient({
+  customHeaders: {
+    'Authorization': `Bearer your-token`,
+    'X-API-Version': '1.0'
+  }
+});
+```
+
+## 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
+
+📋 **Planned:**
+- Complete API coverage
+- Documentation generation
+- Usage examples
+- Performance optimizations
+
+## TypeScript Support
+
+This SDK is built with TypeScript and provides full type safety:
+
+```typescript
+import type { CreateCustomerEndpointRequest, InsurUpResult, GetCustomerEndpointResponse } from '@insurup/sdk';
+
+// All request/response types are strongly typed
+const request: CreateCustomerEndpointRequest = {
+  type: 'INDIVIDUAL',
+  identityNumber: '12345678901',
+  fillMissingFields: true
+};
+
+// Results are discriminated unions for type safety
+const result: InsurUpResult<GetCustomerEndpointResponse> = await client.customers.getCustomer('id');
+```
+
+## 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.