@advizorconnect/sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.2.0 — Prepared 2026-05-09 (not yet published)
+
+Release preparation for the public SDK auth/runtime hardening package. This entry
+records the package contents intended for `@advizorconnect/sdk@0.2.0`; it does
+not claim that npm publish, dist-tag changes, or `0.1.0` deprecation have
+occurred. Those external npm mutations require explicit operator approval.
+
+### Added
+
+- Auth-specific ESM entrypoints:
+  - `@advizorconnect/sdk/integration` with `createIntegrationClient` for server/BFF group API-key integration and session operations.
+  - `@advizorconnect/sdk/owner` with `createOwnerClient` for Supabase owner/admin token operations.
+  - `@advizorconnect/sdk/widget` with `createWidgetClient` for browser-safe widget-token and public operations.
+- Package metadata for a public, provenance-backed npm release target: Node `>=22`, subpath export/type declarations, repository/homepage/bugs metadata, keywords, and public publish config.
+- Operation-aware retry helper behavior with bounded backoff, jitter, `Retry-After` support, retry exhaustion metadata, and SDK-authored retry-safety metadata.
+
+### Changed
+
+- Root `createV1Client` remains available for one-release compatibility but is deprecated in favor of auth-specific clients.
+- SDK transport errors now normalize network failures, timeouts, and response-body read failures into `V1SdkError` with stable `code`, `requestId`, `retryable`, `cause`, and operation metadata fields.
+- Group API-key clients fail closed in known browser/window/worker runtimes unless the explicitly unsafe test-only override is supplied.
+- Unsafe side-effecting SDK operations do not retry automatically unless the SDK marks the operation idempotent; generic `RetryOptions.idempotencyKey` is for custom retry functions and does not override SDK side-effect metadata.
+
+### Release status
+
+- Package build readiness, packed-package smoke evidence, staging platform smoke, production readiness, npm publish, dist-tag mutation, and `0.1.0` deprecation are separate gates.
+- `0.2.0` publish preparation can be performed by the release workflow, but actual npm publish/deprecate/dist-tag mutations have not been run as part of SRV-045.
+
 ## 0.1.0 — 2026-03-02
 
 Initial release.

package/README.md

@@ -1,30 +1,49 @@
 # @advizorconnect/sdk
 
-Typed TypeScript SDK for the Advizor Connect v1 integration API. Build custom caller experiences on top of the Advizor Connect platform.
+Typed ESM TypeScript SDK for Advizor Connect v1 APIs. Version `0.2.0` prepares the package contract for public consumption by separating credential-specific clients and keeping group API keys out of browser runtimes by default.
 
 ## Installation
 
+After `@advizorconnect/sdk@0.2.0` is published:
+
 ```bash
 npm install @advizorconnect/sdk
 ```
 
-## Quick Start
+Until that publish happens, public npm `latest` remains `0.1.0`; repo-local validation uses the package source in `server/sdk` or the file-linked `examples/paimoney-sdk` dependency.
+
+## Requirements
+
+- Node.js `>=22`
+- ESM (`import`) consumers
+- A server/BFF environment for group API-key integration calls
+
+## Public entrypoints
+
+| Entrypoint | Factory | Credential | Intended runtime |
+|------------|---------|------------|------------------|
+| `@advizorconnect/sdk/integration` | `createIntegrationClient` | Group API key as `Authorization: Bearer ...` | Server/BFF only |
+| `@advizorconnect/sdk/owner` | `createOwnerClient` | Supabase owner access token from `getAccessToken()` per request | Owner-authenticated app or BFF |
+| `@advizorconnect/sdk/widget` | `createWidgetClient` | Optional short-lived widget token as `X-AC-Widget-Token`; public routes need no token | Browser/widget-safe |
+| `@advizorconnect/sdk` | `createV1Client` | Legacy API-key option | Deprecated compatibility surface for one release |
+
+Group API keys are server-side credentials. Known browser and worker runtimes fail closed for API-key clients unless the explicitly unsafe test-only override is supplied.
+
+## Integration client (server/BFF)
 
 ```typescript
-import { createV1Client } from '@advizorconnect/sdk';
+import { createIntegrationClient } from '@advizorconnect/sdk/integration';
 
-const client = createV1Client({
+const client = createIntegrationClient({
   baseUrl: 'https://api.advizor-connect.com',
-  apiKey: 'your-api-key', // from owner dashboard → Settings → API Keys
+  apiKey: process.env.ADVIZOR_CONNECT_API_KEY!,
 });
 
-// List available advisors
 const { advisors } = await client.listGroupAdvisors({
   groupId: 'your-group-id',
   onlineStatus: 'available',
 });
 
-// Create a session with the first available advisor
 const { session } = await client.createSession({
   groupId: 'your-group-id',
   advisorId: advisors[0].id,
@@ -35,119 +54,82 @@ const { session } = await client.createSession({
 console.log('Session created:', session.id, session.status);
 ```
 
-## Authentication
+## Owner client
+
+```typescript
+import { createOwnerClient } from '@advizorconnect/sdk/owner';
+
+const ownerClient = createOwnerClient({
+  baseUrl: 'https://api.advizor-connect.com',
+  getAccessToken: async () => {
+    const { data } = await supabase.auth.getSession();
+    return data.session?.access_token ?? null;
+  },
+});
+
+const keys = await ownerClient.listApiKeys({ groupId: 'your-group-id' });
+```
+
+`getAccessToken()` is called for every SDK request and must provide a Supabase owner/admin user JWT. Owner clients do not accept group API keys.
 
-All API calls require a group API key passed as a Bearer token. Create API keys from the owner dashboard under **Settings → API Keys**.
+## Widget/public client
 
 ```typescript
-const client = createV1Client({
+import { createWidgetClient } from '@advizorconnect/sdk/widget';
+
+const widgetClient = createWidgetClient({
   baseUrl: 'https://api.advizor-connect.com',
-  apiKey: process.env.ADVIZOR_CONNECT_API_KEY!,
+  getWidgetToken: async () => widgetTokenFromYourEmbedFlow,
 });
+
+const config = await widgetClient.getWidgetConfig({ groupId: 'your-group-id' });
+```
+
+The widget client exposes browser-safe widget-token and public routes only. It does not expose owner/admin methods or group API-key integration methods.
+
+## Retry helper
+
+```typescript
+import { withRetry } from '@advizorconnect/sdk';
+
+const session = await withRetry(
+  () => client.createSession({
+    groupId: 'your-group-id',
+    advisorId: 'advisor-id',
+    callerPhone: '+15551234567',
+    idempotencyKey: crypto.randomUUID(),
+  }),
+  { maxAttempts: 3, backoffMs: 500 },
+);
 ```
 
-## Client Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `baseUrl` | `string` | *required* | API server URL |
-| `apiKey` | `string` | *required* | Group API key (Bearer token) |
-| `fetchImpl` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation |
-| `timeoutMs` | `number` | `20000` | Request timeout in milliseconds |
-
-## API Methods
-
-### Integration
-
-| Method | Description |
-|--------|-------------|
-| `listGroupAdvisors({ groupId, sort?, order?, onlineStatus?, minBillableMinutes30d? })` | List advisors in a group with optional filters |
-| `getGroupAdvisor({ groupId, advisorId })` | Get a single advisor's details |
-
-### Sessions
-
-| Method | Description |
-|--------|-------------|
-| `createSession({ groupId, advisorId, callerPhone, idempotencyKey, ... })` | Create a new call session |
-| `getSession({ sessionId })` | Get session details and status |
-| `getSessionLedger({ sessionId })` | Get billing ledger for a session |
-| `sendOtp({ sessionId })` | Send OTP to caller's phone |
-| `verifyPhone({ sessionId, otp })` | Verify caller phone with OTP code |
-| `createStripeIntent({ sessionId, holdCents? })` | Create a Stripe PaymentIntent for hold |
-| `createPayPalOrder({ sessionId, holdCents? })` | Create a PayPal order for hold |
-| `authorizePayPalOrder({ sessionId, orderId })` | Authorize a PayPal order |
-| `authorizeHold({ sessionId, paymentIntentId?, holdCents? })` | Confirm payment hold authorization |
-| `startConnecting({ sessionId })` | Initiate telephony bridge |
-| `markConnected({ sessionId })` | Mark session as connected (call active) |
-| `tick({ sessionId, asOfIso? })` | Record a billing tick (~60s intervals) |
-| `endAndCapture({ sessionId, reason? })` | End the call and capture payment |
-| `submitSessionReview({ sessionId, rating, body?, authorName? })` | Submit a post-call review |
-
-### Owner / API Keys
-
-| Method | Description |
-|--------|-------------|
-| `listApiKeys({ groupId })` | List all API keys for a group |
-| `createApiKey({ groupId, name, scopes?, expiresAt? })` | Create a new API key |
-| `rotateApiKey({ groupId, keyId, overlapSeconds?, name?, expiresAt? })` | Rotate an API key with overlap window |
-| `revokeApiKey({ groupId, keyId })` | Revoke an API key |
-
-### Widget
-
-| Method | Description |
-|--------|-------------|
-| `mintWidgetToken({ groupId })` | Mint a short-lived widget auth token |
-| `getWidgetConfig({ groupId })` | Get widget configuration |
-| `listWidgetAdvisors({ groupId })` | List advisors visible in the widget |
-| `getWidgetSecurity({ groupId })` | Get widget security settings |
-| `updateWidgetSecurity({ groupId, allowedOrigins })` | Update allowed origins for widget |
-
-### Owner / Invites
-
-| Method | Description |
-|--------|-------------|
-| `createInvite({ groupId, email? })` | Create an advisor invite |
-| `listInvites({ groupId, status? })` | List invites for a group |
-| `rotateInvite({ groupId, inviteId })` | Rotate invite token |
-| `revokeInvite({ groupId, inviteId })` | Revoke an invite |
-| `sendInvite({ groupId, inviteId })` | Send invite email |
-
-### Owner / Groups
-
-| Method | Description |
-|--------|-------------|
-| `getGroupBySlug({ slug })` | Look up a group by its URL slug |
-| `updateGroupSlug({ groupId, slug })` | Change a group's URL slug |
-| `getGroupSettings({ groupId })` | Get group settings |
-| `updateGroupSettings({ groupId, requireCallerOtp? })` | Update group settings |
-
-## Error Handling
-
-All API errors throw `V1SdkError` with structured fields:
+`withRetry` retries only `V1SdkError` instances marked `retryable === true` and respects SDK operation metadata. Read/idempotent operations can retry when opted in; unsafe side-effecting SDK operations do not retry automatically unless the SDK operation is documented as idempotent.
+
+## Error handling
+
+All API, timeout, network, and response-body transport failures are normalized as `V1SdkError` where possible:
 
 ```typescript
 import { V1SdkError } from '@advizorconnect/sdk';
 
 try {
-  await client.createSession({ ... });
+  await client.getSession({ sessionId: 'session-id' });
 } catch (err) {
   if (err instanceof V1SdkError) {
-    console.error('Status:', err.status);       // HTTP status code
-    console.error('Message:', err.message);      // Human-readable message
-    console.error('Code:', err.code);            // Machine-readable error code
-    console.error('Request ID:', err.requestId); // For support reference
-    console.error('Retryable:', err.retryable);  // Whether to retry
-
-    if (err.retryable) {
-      // Safe to retry with backoff
-    }
+    console.error('Status:', err.status);
+    console.error('Message:', err.message);
+    console.error('Code:', err.code);
+    console.error('Request ID:', err.requestId);
+    console.error('Retryable:', err.retryable);
+    console.error('Operation:', err.operationId);
+    console.error('Cause:', err.cause);
   }
 }
 ```
 
-## TypeScript Types
+## TypeScript types
 
-The SDK exports generated types from the OpenAPI spec for full type safety:
+Root exports include shared errors/retry helpers and generated OpenAPI types:
 
 ```typescript
 import type {
@@ -157,35 +139,24 @@ import type {
   LedgerEvent,
   ApiKeyRecord,
   InviteRecord,
+  paths,
+  components,
+  operations,
 } from '@advizorconnect/sdk';
 ```
 
-For advanced usage, raw OpenAPI path/component types are also available:
+Subpath exports include factory-specific option and client types:
 
 ```typescript
-import type { paths, components, operations } from '@advizorconnect/sdk';
+import type { IntegrationClientOptions } from '@advizorconnect/sdk/integration';
+import type { OwnerClientOptions } from '@advizorconnect/sdk/owner';
+import type { WidgetClientOptions } from '@advizorconnect/sdk/widget';
 ```
 
-## Session Lifecycle
-
-A typical call session follows this sequence:
-
-1. **Create session** — `createSession()`
-2. **Verify caller** — `sendOtp()` → `verifyPhone()`
-3. **Authorize payment** — `createStripeIntent()` → `authorizeHold()`
-4. **Connect call** — `startConnecting()` → `markConnected()`
-5. **Bill during call** — `tick()` every ~60 seconds
-6. **End and capture** — `endAndCapture()`
-
-See the [Session Lifecycle Guide](../../docs/sdk-session-lifecycle.md) for detailed code examples and state machine documentation.
-
-For a complete working example, see the [Paimoney reference app](../../examples/paimoney/) — a production-grade Next.js application demonstrating the BFF proxy integration pattern.
-
-## Requirements
+## Release status boundaries
 
-- Node.js 18+ (or any runtime with global `fetch`)
-- API key from the owner dashboard
+A successful SDK build or packed-package smoke test means the npm package artifact is locally consumable. It does not by itself mean that npm publish happened, that `0.1.0` was deprecated, that staging platform smoke passed, or that the overall public platform is production-ready. Those are separate gates owned by the release operator and the broader platform readiness work.
 
 ## License
 
-Proprietary. See LICENSE for details.
+Proprietary / unlicensed for public redistribution. See `package.json` (`UNLICENSED`) and repository terms for the current package license status.