@delegance/sdk 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delegance Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -12,7 +12,55 @@ yarn add @delegance/sdk
 pnpm add @delegance/sdk
 ```
 
-## Quick Start
+Requires Node 18 or newer. The package ships CommonJS, ESM, and TypeScript types.
+
+## Availability
+
+- **Quoting over the API is live for enrolled companies.** Delegance turns it on account by account today.
+- **Public access opens on 2026-10-06.** From that date a new account created with `createSignup()` can quote.
+- **Until an account has access,** the instant-quote, bind, and payment calls throw a `DeleganceError` with `statusCode` 503 and `reason` `'not_available'`. The SDK does not retry that answer.
+- **A licensed Delegance broker reviews every bind.** `instantQuotes.bind()` creates a request. It never charges a card and never binds coverage by itself.
+
+## Sign up and quote
+
+```typescript
+import { createSignup, newDeviceSecret, DeleganceClient } from '@delegance/sdk';
+
+// 1. Create the account. Keep `device.secret` on this machine only.
+const signup = createSignup();
+const account = await signup.createAccount({
+  name: 'Acme Bakery',
+  contactEmail: 'owner@acmebakery.com',
+  industry: 'commercial bakery',
+  companySize: '2-10',
+});
+const device = newDeviceSecret();
+const { enrollmentId } = await signup.enroll(account.bootstrapKey, {
+  deviceSecretHash: device.hash,
+  firstName: 'Dana',
+  lastName: 'Owner',
+});
+await signup.requestVerification(account.bootstrapKey);
+
+// 2. The owner clicks the emailed confirm link. Then collect the API key.
+const result = await signup.waitForKey(enrollmentId, device.secret);
+if (result.status !== 'ready') throw new Error('Confirm link not clicked yet');
+
+// 3. Quote general liability.
+const client = new DeleganceClient({ apiKey: result.apiKey });
+const session = await client.instantQuotes.start(['general_liability']);
+// Answer session.questions (keyed by question id), then submit.
+const submitted = await client.instantQuotes.submit({
+  submissionId: session.submissionId,
+  sessionVersion: session.sessionVersion,
+  answers: {},
+});
+const status = await client.instantQuotes.waitForQuotes(session.submissionId);
+```
+
+The [`@delegance/cli`](https://www.npmjs.com/package/@delegance/cli) package runs the same flow from a terminal (`delegance signup`, `delegance quote start`).
+
+## Quick Start (existing API key)
 
 ```typescript
 import { DeleganceClient } from '@delegance/sdk';
@@ -70,8 +118,8 @@ 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: API base URL (default: https://portal.delegancebrokerage.com)
+  baseUrl: 'https://portal.delegancebrokerage.com',
   
   // Optional: Request timeout in ms (default: 30000)
   timeout: 30000,
@@ -239,6 +287,39 @@ if (result.status === 'completed') {
 }
 ```
 
+### Appetite
+
+Which carriers will write a risk. Needs an API key with the `appetite:read` scope, which `read` and `write` do not include. A warm cache hit returns the result at once; a cold match returns a job to poll.
+
+```typescript
+const start = await client.appetite.match({
+  state: 'CA',
+  industry: 'commercial bakery',
+  coverageTypes: ['general_liability', 'workers_comp'],
+});
+
+const result = start.status === 'succeeded'
+  ? start
+  : await client.appetite.waitForMatch(start.jobId);
+
+for (const c of result.carrierResults) {
+  console.log(c.carrier, c.overallStatus, c.productsAvailable);
+}
+```
+
+### Leads
+
+Send a prospect business to Delegance. Idempotent on `externalId`, and a contact email that already belongs to a company returns that company.
+
+```typescript
+const { companyId } = await client.leads.create({
+  name: 'Riverbend Bakery',
+  contactEmail: 'owner@riverbend.example',
+  state: 'TX',
+  externalId: 'crm-4411',
+});
+```
+
 ## Error Handling
 
 The SDK throws typed errors for different scenarios:
@@ -246,8 +327,10 @@ The SDK throws typed errors for different scenarios:
 ```typescript
 import { 
   AuthenticationError,
+  ForbiddenError,
   ValidationError,
   NotFoundError,
+  NotImplementedError,
   RateLimitError,
   DeleganceError
 } from '@delegance/sdk';
@@ -257,8 +340,12 @@ try {
 } catch (error) {
   if (error instanceof AuthenticationError) {
     console.error('Invalid API key');
+  } else if (error instanceof ForbiddenError) {
+    console.error('Key lacks the scope for this call');
   } else if (error instanceof NotFoundError) {
     console.error('Document not found');
+  } else if (error instanceof NotImplementedError) {
+    console.error('Not available over the API yet:', error.message);
   } else if (error instanceof ValidationError) {
     console.error('Invalid input:', error.details);
   } else if (error instanceof RateLimitError) {
@@ -269,6 +356,8 @@ try {
 }
 ```
 
+The SDK retries network failures and 5xx responses other than 501. It never retries a 4xx or a 501.
+
 ## TypeScript Support
 
 The SDK is written in TypeScript and includes full type definitions:
@@ -294,8 +383,8 @@ if (!result.success) {
 
 ## Getting an API Key
 
-1. Log in to the Delegance dashboard
-2. Navigate to Settings > API Keys
+1. Log in to the portal at https://portal.delegancebrokerage.com
+2. Open Settings > API keys
 3. Click "Create API Key"
 4. Copy the key (it's only shown once!)
 
@@ -303,6 +392,5 @@ 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
+- Documentation: https://portal.delegancebrokerage.com/docs/sdk
+- Email: support@delegancebrokerage.com