@advizorconnect/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 — 2026-03-02
+
+Initial release.
+
+### Features
+
+- **32 typed methods** across 7 API tag groups:
+  - Integration (2): list/get group advisors
+  - Sessions (13): full call lifecycle from create through end-and-capture
+  - Owner / API Keys (4): CRUD + rotation with overlap windows
+  - Widget (3): token minting, config, advisor listing
+  - Owner / Widget (2): security settings (allowed origins)
+  - Owner / Invites (5): create, list, rotate, revoke, send
+  - Owner / Groups (4): slug management, settings
+- **`V1SdkError`** with structured fields: `status`, `message`, `code`, `requestId`, `retryable`
+- **AbortController timeout** — 20s default, configurable via `timeoutMs`
+- **Custom fetch injection** — pass your own `fetchImpl` for testing or custom HTTP clients
+- **Generated types** from OpenAPI v1 spec via `openapi-typescript`
+- **Tree-shakeable** ESM package with `sideEffects: false`

package/README.md

@@ -0,0 +1,191 @@
+# @advizorconnect/sdk
+
+Typed TypeScript SDK for the Advizor Connect v1 integration API. Build custom caller experiences on top of the Advizor Connect platform.
+
+## Installation
+
+```bash
+npm install @advizorconnect/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createV1Client } from '@advizorconnect/sdk';
+
+const client = createV1Client({
+  baseUrl: 'https://api.advizor-connect.com',
+  apiKey: 'your-api-key', // from owner dashboard → Settings → API Keys
+});
+
+// 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,
+  callerPhone: '+15551234567',
+  idempotencyKey: crypto.randomUUID(),
+});
+
+console.log('Session created:', session.id, session.status);
+```
+
+## Authentication
+
+All API calls require a group API key passed as a Bearer token. Create API keys from the owner dashboard under **Settings → API Keys**.
+
+```typescript
+const client = createV1Client({
+  baseUrl: 'https://api.advizor-connect.com',
+  apiKey: process.env.ADVIZOR_CONNECT_API_KEY!,
+});
+```
+
+## 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:
+
+```typescript
+import { V1SdkError } from '@advizorconnect/sdk';
+
+try {
+  await client.createSession({ ... });
+} 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
+    }
+  }
+}
+```
+
+## TypeScript Types
+
+The SDK exports generated types from the OpenAPI spec for full type safety:
+
+```typescript
+import type {
+  IntegrationAdvisor,
+  SessionEnvelope,
+  ApiSession,
+  LedgerEvent,
+  ApiKeyRecord,
+  InviteRecord,
+} from '@advizorconnect/sdk';
+```
+
+For advanced usage, raw OpenAPI path/component types are also available:
+
+```typescript
+import type { paths, components, operations } from '@advizorconnect/sdk';
+```
+
+## 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
+
+- Node.js 18+ (or any runtime with global `fetch`)
+- API key from the owner dashboard
+
+## License
+
+Proprietary. See LICENSE for details.

package/dist/client.d.ts

@@ -0,0 +1,483 @@
+import type { components } from './generated/v1.js';
+type FetchLike = typeof fetch;
+export type V1ClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+};
+export type ApiKeyRecord = components['schemas']['ApiKeyRecord'];
+export type InviteRecord = components['schemas']['InviteRecord'];
+export type GroupSettingsResponse = components['schemas']['GroupSettingsResponse'];
+export type WidgetConfigResponse = components['schemas']['WidgetConfigResponse'];
+export type WidgetAdvisor = components['schemas']['WidgetAdvisor'];
+export type WidgetSecurityConfig = components['schemas']['WidgetSecurityConfig'];
+export type IntegrationAdvisor = components['schemas']['IntegrationAdvisor'];
+export type IntegrationAdvisorFeedResponse = components['schemas']['IntegrationAdvisorFeedResponse'];
+export type SessionEnvelope = components['schemas']['SessionEnvelope'];
+export type ApiSession = components['schemas']['ApiSession'];
+export type LedgerEvent = components['schemas']['LedgerEvent'];
+export type ErrorResponse = components['schemas']['ErrorResponse'];
+export declare function createV1Client(options: V1ClientOptions): {
+    listGroupAdvisors(input: {
+        groupId: string;
+        sort?: "billable_minutes_30d" | "online_status" | "alphabetical";
+        order?: "asc" | "desc";
+        onlineStatus?: "online" | "offline" | "available" | "busy";
+        minBillableMinutes30d?: number;
+    }): Promise<{
+        groupId: string;
+        groupSlug: string;
+        advisors: components["schemas"]["IntegrationAdvisor"][];
+        count: number;
+        sort?: {
+            [key: string]: unknown;
+        };
+        filter?: {
+            [key: string]: unknown;
+        };
+    } & {
+        [key: string]: unknown;
+    }>;
+    getGroupAdvisor(input: {
+        groupId: string;
+        advisorId: string;
+    }): Promise<{
+        id: string;
+        groupId: string;
+        name: string;
+        avatarUrl?: string | null;
+        headline?: string | null;
+        status: "available" | "busy" | "offline";
+        available: boolean;
+        billableMinutes30d?: number;
+        lastLoginAt?: string | null;
+    } & {
+        [key: string]: unknown;
+    }>;
+    createSession(input: {
+        groupId: string;
+        advisorId: string;
+        callerPhone: string;
+        idempotencyKey: string;
+        callerUsername?: string;
+        callerEmail?: string;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    getSession(input: {
+        sessionId: string;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    getSessionLedger(input: {
+        sessionId: string;
+    }): Promise<{
+        events: components["schemas"]["LedgerEvent"][];
+    }>;
+    sendOtp(input: {
+        sessionId: string;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    verifyPhone(input: {
+        sessionId: string;
+        otp: string;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    createStripeIntent(input: {
+        sessionId: string;
+        holdCents?: 2500 | 5000;
+    }): Promise<{
+        paymentIntentId: string;
+        clientSecret: string;
+        holdCents: number;
+        currency: string;
+    }>;
+    createPayPalOrder(input: {
+        sessionId: string;
+        holdCents?: 2500 | 5000;
+    }): Promise<{
+        orderId: string;
+        holdCents: number;
+        currency: string;
+    }>;
+    authorizePayPalOrder(input: {
+        sessionId: string;
+        orderId: string;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    authorizeHold(input: {
+        sessionId: string;
+        paymentIntentId?: string;
+        holdCents?: number;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    startConnecting(input: {
+        sessionId: string;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    markConnected(input: {
+        sessionId: string;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    tick(input: {
+        sessionId: string;
+        asOfIso?: string;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    endAndCapture(input: {
+        sessionId: string;
+        reason?: string;
+    }): Promise<{
+        session: components["schemas"]["ApiSession"];
+    } & {
+        [key: string]: unknown;
+    }>;
+    submitSessionReview(input: {
+        sessionId: string;
+        rating: number;
+        body?: string;
+        authorName?: string;
+    }): Promise<{
+        ok: boolean;
+        duplicate?: boolean;
+        review?: {
+            [key: string]: unknown;
+        };
+    }>;
+    listApiKeys(input: {
+        groupId: string;
+    }): Promise<{
+        keys: components["schemas"]["ApiKeyRecord"][];
+        availableScopes: string[];
+    }>;
+    createApiKey(input: {
+        groupId: string;
+        name: string;
+        scopes?: string[];
+        expiresAt?: string;
+    }): Promise<{
+        key: components["schemas"]["ApiKeyRecord"];
+        apiKey: string;
+        availableScopes: string[];
+    }>;
+    rotateApiKey(input: {
+        groupId: string;
+        keyId: string;
+        overlapSeconds?: number;
+        name?: string;
+        expiresAt?: string;
+    }): Promise<{
+        key: components["schemas"]["ApiKeyRecord"];
+        apiKey: string;
+        previousKey: {
+            id: string;
+            expiresAt?: string | null;
+        };
+    }>;
+    revokeApiKey(input: {
+        groupId: string;
+        keyId: string;
+    }): Promise<{
+        ok: boolean;
+        revokedAt?: string | null;
+        expiresAt?: string | null;
+    }>;
+    mintWidgetToken(input: {
+        groupId: string;
+    }): Promise<{
+        token: string;
+        expiresAt: string;
+        mode: "preview" | "embed";
+    }>;
+    getWidgetConfig(input: {
+        groupId: string;
+    }): Promise<{
+        groupId: string;
+        groupSlug: string;
+        groupName: string;
+        theme: {
+            [key: string]: unknown;
+        };
+        requireCallerOtp: boolean;
+        embedTemplate: {
+            [key: string]: unknown;
+        };
+    }>;
+    listWidgetAdvisors(input: {
+        groupId: string;
+    }): Promise<{
+        groupId: string;
+        groupSlug: string;
+        advisors: components["schemas"]["WidgetAdvisor"][];
+        count: number;
+    }>;
+    getWidgetSecurity(input: {
+        groupId: string;
+    }): Promise<{
+        security: components["schemas"]["WidgetSecurityConfig"];
+        previewOrigin: string;
+    }>;
+    updateWidgetSecurity(input: {
+        groupId: string;
+        allowedOrigins: string[];
+    }): Promise<{
+        security: components["schemas"]["WidgetSecurityConfig"];
+        previewOrigin: string;
+    }>;
+    createInvite(input: {
+        groupId: string;
+        email?: string;
+    }): Promise<{
+        invite: components["schemas"]["InviteRecord"];
+    }>;
+    listInvites(input: {
+        groupId: string;
+        status?: string;
+    }): Promise<{
+        invites: components["schemas"]["InviteRecord"][];
+    }>;
+    rotateInvite(input: {
+        groupId: string;
+        inviteId: string;
+    }): Promise<{
+        ok: boolean;
+        inviteId: string;
+        invite: components["schemas"]["InviteRecord"];
+    }>;
+    revokeInvite(input: {
+        groupId: string;
+        inviteId: string;
+    }): Promise<{
+        ok: boolean;
+        inviteId: string;
+        revokedAt?: string | null;
+    }>;
+    sendInvite(input: {
+        groupId: string;
+        inviteId: string;
+    }): Promise<{
+        ok: boolean;
+        inviteId: string;
+        resendEmailId: string;
+    }>;
+    getGroupBySlug(input: {
+        slug: string;
+    }): Promise<{
+        group: {
+            id: string;
+            slug: string;
+            name: string;
+            theme?: {
+                [key: string]: unknown;
+            } | null;
+            isPersonal?: boolean;
+            requireCallerOtp?: boolean;
+        };
+        requestedSlug: string;
+        canonicalSlug: string;
+        isAlias: boolean;
+    }>;
+    updateGroupSlug(input: {
+        groupId: string;
+        slug: string;
+    }): Promise<{
+        group: {
+            [key: string]: unknown;
+        };
+    }>;
+    getGroupSettings(input: {
+        groupId: string;
+    }): Promise<{
+        settings: components["schemas"]["GroupSettingsResponse"];
+    }>;
+    updateGroupSettings(input: {
+        groupId: string;
+        requireCallerOtp?: boolean;
+    }): Promise<{
+        settings: components["schemas"]["GroupSettingsResponse"];
+    }>;
+    listOwnerAdvisors(input: {
+        groupId: string;
+    }): Promise<{
+        advisors: {
+            [key: string]: unknown;
+        }[];
+    }>;
+    moderateAdvisor(input: {
+        groupId: string;
+        advisorId: string;
+        action: "approve" | "reject" | "suspend" | "unsuspend";
+        reason?: string;
+        note?: string;
+    }): Promise<{
+        ok: boolean;
+        advisor: {
+            [key: string]: unknown;
+        };
+    }>;
+    listAdvisorModerationEvents(input: {
+        groupId: string;
+        advisorId: string;
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        events: {
+            [key: string]: unknown;
+        }[];
+    }>;
+    listGroupModerationEvents(input: {
+        groupId: string;
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        events: {
+            [key: string]: unknown;
+        }[];
+    }>;
+    removeAdvisor(input: {
+        groupId: string;
+        advisorId: string;
+        reason?: string;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    updateGroupTheme(input: {
+        groupId: string;
+        theme: Record<string, unknown>;
+    }): Promise<{
+        group: {
+            [key: string]: unknown;
+        };
+    }>;
+    getSetupState(input: {
+        groupId: string;
+    }): Promise<{
+        setupState: {
+            [key: string]: unknown;
+        };
+    }>;
+    updateSetupState(input: {
+        groupId: string;
+        setupState: Record<string, unknown>;
+    }): Promise<{
+        setupState: {
+            [key: string]: unknown;
+        };
+    }>;
+    getAnalyticsOverview(input: {
+        groupId: string;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    getAnalyticsRevenue(input: {
+        groupId: string;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    getAnalyticsSessions(input: {
+        groupId: string;
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    getWidgetEventAnalytics(input: {
+        groupId: string;
+        since?: string;
+        limit?: number;
+    }): Promise<{
+        events: {
+            [key: string]: unknown;
+        }[];
+    }>;
+    listOwnerPayouts(input: {
+        groupId: string;
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        payouts: {
+            [key: string]: unknown;
+        }[];
+        total: number;
+        page: number;
+        limit: number;
+    }>;
+    batchCreateOwnerInvites(input: {
+        groupId: string;
+        emails: string[];
+    }): Promise<{
+        results: {
+            [key: string]: unknown;
+        }[];
+    }>;
+    previewInvite(input: {
+        token: string;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    acceptInvite(input: {
+        token: string;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    createWidgetCallback(input: {
+        groupId: string;
+        body: Record<string, unknown>;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    getWidgetCallbackStatus(input: {
+        groupId: string;
+        phone: string;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    ingestWidgetEvent(input: {
+        groupId: string;
+        eventType: string;
+        sessionId: string;
+        eventData?: Record<string, unknown>;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    getGroupSitemap(input: {
+        groupSlug: string;
+    }): Promise<never>;
+    getAdvisorJsonLd(input: {
+        groupSlug: string;
+        advisorId: string;
+    }): Promise<never>;
+    getTaxonomy(): Promise<{
+        [key: string]: unknown;
+    }>;
+    generateWidgetEmbedCode(input: {
+        groupId: string;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+};
+export {};

package/dist/client.js

@@ -0,0 +1,469 @@
+import { V1SdkError } from './errors.js';
+function withQuery(path, query) {
+    if (!query)
+        return path;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v == null)
+            continue;
+        params.set(k, String(v));
+    }
+    const qs = params.toString();
+    return qs ? `${path}?${qs}` : path;
+}
+async function parseResponseBody(res) {
+    const text = await res.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export function createV1Client(options) {
+    const baseUrl = options.baseUrl.replace(/\/$/, '');
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    async function request(input) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetchImpl(withQuery(`${baseUrl}${input.path}`, input.query), {
+                method: input.method,
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Bearer ${options.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: input.body == null ? undefined : JSON.stringify(input.body),
+            });
+            const body = await parseResponseBody(res);
+            if (!res.ok) {
+                const envelope = body && typeof body === 'object' ? body : null;
+                const message = (envelope && typeof envelope.message === 'string' && envelope.message)
+                    || (envelope && typeof envelope.error === 'string' && envelope.error)
+                    || `Request failed (${res.status})`;
+                throw new V1SdkError({
+                    status: res.status,
+                    message,
+                    body,
+                    code: envelope && typeof envelope.code === 'string' ? envelope.code : null,
+                    requestId: envelope && typeof envelope.requestId === 'string' ? envelope.requestId : null,
+                    retryable: envelope && typeof envelope.retryable === 'boolean' ? envelope.retryable : null,
+                });
+            }
+            return body;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    const e = encodeURIComponent;
+    return {
+        // ── Integration (2) ──────────────────────────────────────────────
+        listGroupAdvisors(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/integration/groups/${e(input.groupId)}/advisors`,
+                query: {
+                    sort: input.sort,
+                    order: input.order,
+                    onlineStatus: input.onlineStatus,
+                    minBillableMinutes30d: input.minBillableMinutes30d,
+                },
+            });
+        },
+        getGroupAdvisor(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/integration/groups/${e(input.groupId)}/advisors/${e(input.advisorId)}`,
+            });
+        },
+        // ── Sessions (13) ────────────────────────────────────────────────
+        createSession(input) {
+            return request({
+                method: 'POST',
+                path: '/v1/sessions',
+                body: input,
+            });
+        },
+        getSession(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/sessions/${e(input.sessionId)}`,
+            });
+        },
+        getSessionLedger(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/sessions/${e(input.sessionId)}/ledger`,
+            });
+        },
+        sendOtp(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/otp/send`,
+            });
+        },
+        verifyPhone(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/verify-phone`,
+                body: { otp: input.otp },
+            });
+        },
+        createStripeIntent(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/payments/create-intent`,
+                body: input.holdCents != null ? { holdCents: input.holdCents } : {},
+            });
+        },
+        createPayPalOrder(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/payments/paypal/create-order`,
+                body: input.holdCents != null ? { holdCents: input.holdCents } : {},
+            });
+        },
+        authorizePayPalOrder(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/payments/paypal/authorize`,
+                body: { orderId: input.orderId },
+            });
+        },
+        authorizeHold(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/authorize-hold`,
+                body: {
+                    paymentIntentId: input.paymentIntentId,
+                    holdCents: input.holdCents,
+                },
+            });
+        },
+        startConnecting(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/start-connecting`,
+            });
+        },
+        markConnected(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/mark-connected`,
+            });
+        },
+        tick(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/tick`,
+                body: input.asOfIso ? { asOfIso: input.asOfIso } : {},
+            });
+        },
+        endAndCapture(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/end-and-capture`,
+                body: input.reason ? { reason: input.reason } : {},
+            });
+        },
+        submitSessionReview(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/sessions/${e(input.sessionId)}/reviews`,
+                body: {
+                    rating: input.rating,
+                    body: input.body,
+                    authorName: input.authorName,
+                },
+            });
+        },
+        // ── Owner / API Keys (4) ─────────────────────────────────────────
+        listApiKeys(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/api-keys`,
+            });
+        },
+        createApiKey(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/api-keys`,
+                body: { name: input.name, scopes: input.scopes, expiresAt: input.expiresAt },
+            });
+        },
+        rotateApiKey(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/api-keys/${e(input.keyId)}/rotate`,
+                body: {
+                    overlapSeconds: input.overlapSeconds,
+                    name: input.name,
+                    expiresAt: input.expiresAt,
+                },
+            });
+        },
+        revokeApiKey(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/api-keys/${e(input.keyId)}/revoke`,
+            });
+        },
+        // ── Widget (3) + Owner / Widget (2) ──────────────────────────────
+        mintWidgetToken(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/widget/${e(input.groupId)}/auth/token`,
+            });
+        },
+        getWidgetConfig(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/widget/${e(input.groupId)}/config`,
+            });
+        },
+        listWidgetAdvisors(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/widget/${e(input.groupId)}/advisors`,
+            });
+        },
+        getWidgetSecurity(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/widget/security`,
+            });
+        },
+        updateWidgetSecurity(input) {
+            return request({
+                method: 'PUT',
+                path: `/v1/owner/groups/${e(input.groupId)}/widget/security`,
+                body: { allowedOrigins: input.allowedOrigins },
+            });
+        },
+        // ── Owner / Invites (5) ──────────────────────────────────────────
+        createInvite(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/invites`,
+                body: input.email ? { email: input.email } : {},
+            });
+        },
+        listInvites(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/invites`,
+                query: { status: input.status },
+            });
+        },
+        rotateInvite(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/invites/${e(input.inviteId)}/rotate`,
+            });
+        },
+        revokeInvite(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/invites/${e(input.inviteId)}/revoke`,
+            });
+        },
+        sendInvite(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/invites/${e(input.inviteId)}/send`,
+            });
+        },
+        // ── Owner / Groups (4) ───────────────────────────────────────────
+        getGroupBySlug(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/groups/by-slug/${e(input.slug)}`,
+            });
+        },
+        updateGroupSlug(input) {
+            return request({
+                method: 'PATCH',
+                path: `/v1/owner/groups/${e(input.groupId)}/slug`,
+                body: { slug: input.slug },
+            });
+        },
+        getGroupSettings(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/settings`,
+            });
+        },
+        updateGroupSettings(input) {
+            return request({
+                method: 'PATCH',
+                path: `/v1/owner/groups/${e(input.groupId)}/settings`,
+                body: {
+                    requireCallerOtp: input.requireCallerOtp,
+                },
+            });
+        },
+        // ── Owner / Advisors (5) ────────────────────────────────────────
+        listOwnerAdvisors(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/advisors`,
+            });
+        },
+        moderateAdvisor(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/advisors/${e(input.advisorId)}/moderate`,
+                body: { action: input.action, reason: input.reason, note: input.note },
+            });
+        },
+        listAdvisorModerationEvents(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/advisors/${e(input.advisorId)}/events`,
+                query: { before: input.before, limit: input.limit },
+            });
+        },
+        listGroupModerationEvents(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/events`,
+                query: { before: input.before, limit: input.limit },
+            });
+        },
+        removeAdvisor(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/advisors/${e(input.advisorId)}`,
+                body: input.reason ? { reason: input.reason } : {},
+            });
+        },
+        // ── Owner / Setup & Theme (3) ───────────────────────────────────
+        updateGroupTheme(input) {
+            return request({
+                method: 'PATCH',
+                path: `/v1/owner/groups/${e(input.groupId)}/theme`,
+                body: { theme: input.theme },
+            });
+        },
+        getSetupState(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/setup-state`,
+            });
+        },
+        updateSetupState(input) {
+            return request({
+                method: 'PATCH',
+                path: `/v1/owner/groups/${e(input.groupId)}/setup-state`,
+                body: { setupState: input.setupState },
+            });
+        },
+        // ── Owner / Analytics (4) ────────────────────────────────────────
+        getAnalyticsOverview(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/analytics/overview`,
+            });
+        },
+        getAnalyticsRevenue(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/analytics/revenue`,
+            });
+        },
+        getAnalyticsSessions(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/analytics/sessions`,
+                query: { page: input.page, limit: input.limit },
+            });
+        },
+        getWidgetEventAnalytics(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/analytics/widget-events`,
+                query: { since: input.since, limit: input.limit },
+            });
+        },
+        // ── Owner / Payouts (1) ──────────────────────────────────────────
+        listOwnerPayouts(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/owner/groups/${e(input.groupId)}/payouts`,
+                query: { page: input.page, limit: input.limit },
+            });
+        },
+        // ── Owner / Invites (Batch + Public invite flow) ────────────────
+        batchCreateOwnerInvites(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/invites/batch`,
+                body: { emails: input.emails },
+            });
+        },
+        previewInvite(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/invites/${e(input.token)}/preview`,
+            });
+        },
+        acceptInvite(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/invites/${e(input.token)}/accept`,
+            });
+        },
+        // ── Widget events + callbacks (3) ────────────────────────────────
+        createWidgetCallback(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/widget/${e(input.groupId)}/callbacks`,
+                body: input.body,
+            });
+        },
+        getWidgetCallbackStatus(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/widget/${e(input.groupId)}/callbacks/status`,
+                query: { phone: input.phone },
+            });
+        },
+        ingestWidgetEvent(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/widget/${e(input.groupId)}/events`,
+                body: { eventType: input.eventType, sessionId: input.sessionId, eventData: input.eventData },
+            });
+        },
+        // ── SEO + taxonomy + widget generation (4) ───────────────────────
+        getGroupSitemap(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/seo/groups/${e(input.groupSlug)}/sitemap.xml`,
+            });
+        },
+        getAdvisorJsonLd(input) {
+            return request({
+                method: 'GET',
+                path: `/v1/seo/groups/${e(input.groupSlug)}/advisors/${e(input.advisorId)}/jsonld`,
+            });
+        },
+        getTaxonomy() {
+            return request({
+                method: 'GET',
+                path: '/v1/taxonomy',
+            });
+        },
+        generateWidgetEmbedCode(input) {
+            return request({
+                method: 'POST',
+                path: `/v1/owner/groups/${e(input.groupId)}/widget/generate`,
+            });
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class V1SdkError extends Error {
+    status: number;
+    body: unknown;
+    code: string | null;
+    requestId: string | null;
+    retryable: boolean | null;
+    constructor(input: {
+        status: number;
+        message: string;
+        body: unknown;
+        code?: string | null;
+        requestId?: string | null;
+        retryable?: boolean | null;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+export class V1SdkError extends Error {
+    status;
+    body;
+    code;
+    requestId;
+    retryable;
+    constructor(input) {
+        super(input.message);
+        this.name = 'V1SdkError';
+        this.status = input.status;
+        this.body = input.body;
+        this.code = input.code ?? null;
+        this.requestId = input.requestId ?? null;
+        this.retryable = input.retryable ?? null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { V1SdkError } from './errors.js';
+export { createV1Client } from './client.js';
+export type { V1ClientOptions } from './client.js';
+export { withRetry } from './retry.js';
+export type { RetryOptions } from './retry.js';
+export type { ApiKeyRecord, InviteRecord, GroupSettingsResponse, WidgetConfigResponse, WidgetAdvisor, WidgetSecurityConfig, IntegrationAdvisor, IntegrationAdvisorFeedResponse, SessionEnvelope, ApiSession, LedgerEvent, ErrorResponse, } from './client.js';
+export type { paths, components, operations } from './generated/v1.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { V1SdkError } from './errors.js';
+export { createV1Client } from './client.js';
+export { withRetry } from './retry.js';

package/dist/retry.d.ts

@@ -0,0 +1,23 @@
+export type RetryOptions = {
+    /** Maximum number of attempts (including the first). Default: 3 */
+    maxAttempts?: number;
+    /** Base backoff delay in milliseconds. Default: 1000 */
+    backoffMs?: number;
+    /** Maximum backoff delay in milliseconds. Default: 30000 */
+    maxBackoffMs?: number;
+};
+/**
+ * Retry an async function with exponential backoff and jitter.
+ *
+ * Only retries on `V1SdkError` where `retryable === true`.
+ * All other errors are thrown immediately.
+ *
+ * @example
+ * ```typescript
+ * const session = await withRetry(
+ *   () => client.getSession({ sessionId: 'sess_abc' }),
+ *   { maxAttempts: 5, backoffMs: 500 },
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,39 @@
+import { V1SdkError } from './errors.js';
+/**
+ * Retry an async function with exponential backoff and jitter.
+ *
+ * Only retries on `V1SdkError` where `retryable === true`.
+ * All other errors are thrown immediately.
+ *
+ * @example
+ * ```typescript
+ * const session = await withRetry(
+ *   () => client.getSession({ sessionId: 'sess_abc' }),
+ *   { maxAttempts: 5, backoffMs: 500 },
+ * );
+ * ```
+ */
+export async function withRetry(fn, options) {
+    const maxAttempts = options?.maxAttempts ?? 3;
+    const backoffMs = options?.backoffMs ?? 1000;
+    const maxBackoffMs = options?.maxBackoffMs ?? 30_000;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            const isRetryable = err instanceof V1SdkError && err.retryable === true;
+            if (!isRetryable || attempt === maxAttempts) {
+                throw err;
+            }
+            // Exponential backoff with jitter: delay = min(base * 2^(attempt-1) + jitter, max)
+            const exponentialDelay = backoffMs * Math.pow(2, attempt - 1);
+            const jitter = Math.random() * backoffMs;
+            const delay = Math.min(exponentialDelay + jitter, maxBackoffMs);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@advizorconnect/sdk",
+  "version": "0.1.0",
+  "description": "Typed SDK for Advizor Connect v1 integration APIs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}