@commissionsight/sdk 2.0.0

package/dist/index.js

@@ -0,0 +1,390 @@
+/** Lightweight typed client for the CommissionSight API. */
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'ApiError';
+    }
+}
+export class CommissionSightClient {
+    baseUrl;
+    token;
+    fetchFn;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.token = opts.token;
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    setToken(token) {
+        this.token = token;
+    }
+    async request(path, init = {}) {
+        const headers = new Headers(init.headers);
+        if (this.token)
+            headers.set('authorization', `Bearer ${this.token}`);
+        if (init.body && !(init.body instanceof FormData)) {
+            headers.set('content-type', 'application/json');
+        }
+        const res = await this.fetchFn(`${this.baseUrl}${path}`, { ...init, headers });
+        const text = await res.text();
+        const body = text ? JSON.parse(text) : null;
+        if (!res.ok) {
+            const message = body && typeof body === 'object' && 'title' in body ? String(body.title) : res.statusText;
+            throw new ApiError(res.status, message, body);
+        }
+        return body;
+    }
+    /** Like `request` but returns the raw response body as text (e.g. a CSV
+     * download). Errors still surface as `ApiError` from the problem+json body. */
+    async requestText(path, init = {}) {
+        const headers = new Headers(init.headers);
+        if (this.token)
+            headers.set('authorization', `Bearer ${this.token}`);
+        const res = await this.fetchFn(`${this.baseUrl}${path}`, { ...init, headers });
+        const text = await res.text();
+        if (!res.ok) {
+            let body = null;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch {
+                // non-JSON error body — fall back to the status text
+            }
+            const message = body && typeof body === 'object' && 'title' in body
+                ? String(body.title)
+                : res.statusText;
+            throw new ApiError(res.status, message, body);
+        }
+        return text;
+    }
+    // --- carriers / configs ---
+    listCarriers(params = {}) {
+        return this.request(`/carriers${query({ withConfig: params.withConfig ? 'true' : undefined })}`);
+    }
+    getCarrier(carrierId) {
+        return this.request(`/carriers/${carrierId}`);
+    }
+    listConfigs(carrierId) {
+        return this.request(`/carriers/${carrierId}/configs`);
+    }
+    getConfigVersion(carrierId, version) {
+        return this.request(`/carriers/${carrierId}/configs/${version}`);
+    }
+    /** Create an account-scoped carrier config override. */
+    createConfig(carrierId, config) {
+        return this.request(`/carriers/${carrierId}/configs`, {
+            method: 'POST',
+            body: JSON.stringify(config),
+        });
+    }
+    /** Dry-run a config against a sample file (maps + previews, persists nothing). */
+    testConfig(carrierId, config, file) {
+        const form = new FormData();
+        form.set('config', JSON.stringify(config));
+        form.set('file', file);
+        return this.request(`/carriers/${carrierId}/configs/test`, { method: 'POST', body: form });
+    }
+    /** Infer a draft config from a sample file. */
+    inferConfig(carrierId, file, opts = {}) {
+        const form = new FormData();
+        form.set('file', file);
+        if (opts.sheetName)
+            form.set('sheetName', opts.sheetName);
+        return this.request(`/carriers/${carrierId}/configs/infer`, {
+            method: 'POST',
+            body: form,
+        });
+    }
+    // --- files ---
+    async uploadFile(input) {
+        const form = new FormData();
+        form.set('file', input.file);
+        form.set('carrierId', input.carrierId);
+        form.set('periodYear', String(input.periodYear));
+        form.set('periodMonth', String(input.periodMonth));
+        if (input.webhookUrl)
+            form.set('webhookUrl', input.webhookUrl);
+        if (input.replace)
+            form.set('replace', 'true');
+        const headers = input.idempotencyKey ? { 'idempotency-key': input.idempotencyKey } : undefined;
+        return this.request('/files', { method: 'POST', body: form, headers });
+    }
+    listFiles(params = {}) {
+        return this.request(`/files${query(params)}`);
+    }
+    getFile(fileId) {
+        return this.request(`/files/${fileId}`);
+    }
+    /**
+     * Re-process (re-score) a file's period without re-uploading — recomputes
+     * statuses/deltas against the current baseline. Use after uploading an earlier
+     * month out of order (see `FileSummary.rescoreSuggested`).
+     */
+    rescoreFile(fileId) {
+        return this.request(`/files/${fileId}/rescore`, { method: 'POST' });
+    }
+    /**
+     * Retract (unapply) a file's carrier+period — deletes the period's data with no
+     * re-upload and re-scores the following month. Scoped to the whole carrier+period
+     * (all files for it), so a period split across files clears as a unit. Returns
+     * `409` (`already_retracted`) if the file was already retracted/replaced.
+     */
+    retractFile(fileId) {
+        return this.request(`/files/${fileId}`, { method: 'DELETE' });
+    }
+    /**
+     * Purge the raw statement bytes from object storage (data retention). The file
+     * row + scored results remain; the file can no longer be re-ingested. Idempotent.
+     */
+    purgeFile(fileId) {
+        return this.request(`/files/${fileId}/purge`, {
+            method: 'POST',
+        });
+    }
+    // --- jobs ---
+    listJobs(params = {}) {
+        return this.request(`/jobs${query(params)}`);
+    }
+    getJob(jobId) {
+        return this.request(`/jobs/${jobId}`);
+    }
+    /** Download the exception file (rejected rows + their errors) for a job as CSV
+     * text. Retained for 30 days; a purged or absent file throws `ApiError` (404). */
+    downloadExceptions(jobId) {
+        return this.requestText(`/jobs/${jobId}/exceptions`);
+    }
+    getJobResults(jobId, params = {}) {
+        const { owedOnly, chargeback, ...rest } = params;
+        return this.request(`/jobs/${jobId}/results${query({
+            ...rest,
+            owedOnly: owedOnly ? 'true' : undefined,
+            chargeback: chargeback ? 'true' : undefined,
+        })}`);
+    }
+    getJobDeltas(jobId, params = {}) {
+        return this.request(`/jobs/${jobId}/deltas${query(params)}`);
+    }
+    retryJob(jobId) {
+        return this.request(`/jobs/${jobId}/retry`, {
+            method: 'POST',
+        });
+    }
+    // --- members ---
+    listMembers(params = {}) {
+        return this.request(`/members${query(params)}`);
+    }
+    getMember(memberRefId) {
+        return this.request(`/members/${memberRefId}`);
+    }
+    getMemberTimeline(memberRefId) {
+        return this.request(`/members/${memberRefId}/timeline`);
+    }
+    /** Full audit journey of a member: every period it appeared, the source file,
+     * commission/premium, status + flags, and field-level changes — in order. */
+    getMemberJourney(memberRefId) {
+        return this.request(`/members/${memberRefId}/journey`);
+    }
+    /** Full audit journey of a single policy (member-scoped). */
+    getPolicyJourney(policyRefId) {
+        return this.request(`/policies/${policyRefId}/journey`);
+    }
+    /** Where/when a member was last seen (period + originating file). */
+    getMemberLastSeen(memberRefId) {
+        return this.request(`/members/${memberRefId}/last-seen`);
+    }
+    // --- team ---
+    /** List the account's members. */
+    listTeam() {
+        return this.request('/team');
+    }
+    /** Invite a teammate by email (passwordless — they sign in with a one-time code). */
+    inviteTeammate(email) {
+        return this.request('/team/invites', {
+            method: 'POST',
+            body: JSON.stringify({ email }),
+        });
+    }
+    /** Remove a teammate and revoke their sessions. */
+    removeTeammate(userId) {
+        return this.request(`/team/${userId}`, { method: 'DELETE' });
+    }
+    // --- audit ---
+    /** Read the account's audit trail (newest first). Filter by `action`. */
+    listAudit(params = {}) {
+        return this.request(`/audit${query(params)}`);
+    }
+    // --- comparisons / reports ---
+    compare(params) {
+        return this.request(`/comparisons${query(params)}`);
+    }
+    rollup(period, carrierId) {
+        return this.request(`/reports/rollup${query({ period, carrierId })}`);
+    }
+    /** Chargebacks for a period, each enriched with the policy's original payout. */
+    listChargebacks(params = {}) {
+        return this.request(`/chargebacks${query(params)}`);
+    }
+    attrition(period, carrierId) {
+        return this.request(`/reports/attrition${query({ period, carrierId })}`);
+    }
+    attritionSeries(params = {}) {
+        return this.request(`/reports/attrition-series${query(params)}`);
+    }
+    dataQuality(period) {
+        return this.request(`/reports/data-quality${query({ period })}`);
+    }
+    // --- expected commission rates (the "owed" model inputs) ---
+    listExpectedRates(carrierId) {
+        return this.request(`/expected-rates${query({ carrierId })}`);
+    }
+    /** Upsert the contracted rate for a carrier (+ optional plan). Re-posting the
+     * same carrier+plan updates it. `rateValue` is a fraction for percent_of_premium.
+     * Returns `rescoredPeriods`: how many already-processed periods were re-scored to
+     * bring their stored "commission owed" totals in line with the new rate. */
+    upsertExpectedRate(input) {
+        return this.request('/expected-rates', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    deleteExpectedRate(id) {
+        return this.request(`/expected-rates/${id}`, { method: 'DELETE' });
+    }
+    // --- webhooks ---
+    listWebhooks() {
+        return this.request('/webhooks');
+    }
+    /** Subscribe to job events. The signing `secret` is returned ONCE on creation. */
+    createWebhook(input) {
+        return this.request('/webhooks', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    deleteWebhook(id) {
+        return this.request(`/webhooks/${id}`, { method: 'DELETE' });
+    }
+    // --- session / service ---
+    /** The account behind the current token. */
+    me() {
+        return this.request('/me');
+    }
+    /** Liveness probe (no auth required). */
+    health() {
+        return this.request('/health');
+    }
+    // --- billing / profile ---
+    getBilling() {
+        return this.request('/billing');
+    }
+    updateBilling(body) {
+        return this.request('/billing', { method: 'PUT', body: JSON.stringify(body) });
+    }
+    billingPreview() {
+        return this.request('/billing/preview');
+    }
+    createSetupIntent() {
+        return this.request('/billing/setup-intent', { method: 'POST' });
+    }
+    savePaymentMethod(paymentMethodId) {
+        return this.request('/billing/payment-method', { method: 'POST', body: JSON.stringify({ paymentMethodId }) });
+    }
+    // --- admin (role=admin session required) ---
+    admin = {
+        listAccounts: (status) => this.request(`/admin/accounts${query({ status })}`),
+        setBillingRate: (accountId, rateCents) => this.request(`/admin/accounts/${accountId}/billing-rate`, { method: 'PUT', body: JSON.stringify({ rateCents }) }),
+        getAccountBilling: (accountId) => this.request(`/admin/accounts/${accountId}/billing`),
+        /** Per-account dashboard: counts + latest-period rollup (members, status mix,
+         * owed, at-risk, chargebacks). */
+        accountOverview: (accountId) => this.request(`/admin/accounts/${accountId}/overview`),
+        accountFiles: (accountId, params = {}) => this.request(`/admin/accounts/${accountId}/files${query(params)}`),
+        accountJobs: (accountId, params = {}) => this.request(`/admin/accounts/${accountId}/jobs${query(params)}`),
+        accountUsers: (accountId) => this.request(`/admin/accounts/${accountId}/users`),
+        /** Recent scheduled-maintenance (cron) runs + the task schedule — System tab. */
+        cronRuns: (params = {}) => this.request(`/admin/system/cron-runs${query(params)}`),
+        /** Platform billing/revenue summary — heartbeats, projected revenue, A/R. */
+        revenue: () => this.request('/admin/revenue'),
+        /** Set an account's AI-assistant monthly cap (cents) and pass-through billing. */
+        setAiSettings: (accountId, settings) => this.request(`/admin/accounts/${accountId}/ai-settings`, { method: 'PUT', body: JSON.stringify(settings) }),
+        setSurcharge: (accountId, enabled) => this.request(`/admin/accounts/${accountId}/surcharge`, { method: 'PUT', body: JSON.stringify({ enabled }) }),
+        approveAccount: (accountId) => this.request(`/admin/accounts/${accountId}/approve`, { method: 'POST' }),
+        /** Provision (or re-provision) an account's data store. Pass a connString to
+         * use a database created out of band; omit it to auto-create a Neon DB. */
+        provisionAccount: (accountId, connString) => this.request(`/admin/accounts/${accountId}/provision`, {
+            method: 'POST',
+            body: JSON.stringify(connString ? { connString } : {}),
+        }),
+        createAccount: (name) => this.request('/admin/accounts', {
+            method: 'POST',
+            body: JSON.stringify({ name }),
+        }),
+        /** Purge ALL raw statement bytes for an account from object storage (retention). */
+        purgeAccountFiles: (accountId) => this.request(`/admin/accounts/${accountId}/purge-files`, { method: 'POST' }),
+        issueToken: (accountId, label) => this.request(`/admin/accounts/${accountId}/tokens`, { method: 'POST', body: JSON.stringify({ label }) }),
+        /** List an account's API tokens — metadata only (never the secret). */
+        listTokens: (accountId) => this.request(`/admin/accounts/${accountId}/tokens`),
+        revokeToken: (tokenId) => this.request(`/admin/tokens/${tokenId}/revoke`, {
+            method: 'POST',
+        }),
+        storeCredentials: (accountId, body) => this.request(`/admin/accounts/${accountId}/credentials`, { method: 'PUT', body: JSON.stringify(body) }),
+        createCarrier: (name, slug) => this.request('/admin/carriers', {
+            method: 'POST',
+            body: JSON.stringify({ name, slug }),
+        }),
+        renameCarrier: (id, name, slug) => this.request(`/admin/carriers/${id}`, {
+            method: 'PUT',
+            body: JSON.stringify({ name, ...(slug ? { slug } : {}) }),
+        }),
+        /** Onboarding: infer a draft config from a sample statement (CSV/XLSX). */
+        inferConfig: (carrierId, file, opts = {}) => {
+            const form = new FormData();
+            form.append('file', file);
+            if (opts.sheetName)
+                form.append('sheetName', opts.sheetName);
+            if (opts.fileType)
+                form.append('fileType', opts.fileType);
+            return this.request(`/admin/carriers/${carrierId}/configs/infer`, {
+                method: 'POST',
+                body: form,
+            });
+        },
+        listUsers: () => this.request('/admin/users'),
+        createUser: (body) => this.request('/admin/users', { method: 'POST', body: JSON.stringify(body) }),
+        /** Update a user's role. A user's account link is immutable (set at invite). */
+        updateUser: (id, body) => this.request(`/admin/users/${id}`, {
+            method: 'PUT',
+            body: JSON.stringify(body),
+        }),
+        deleteUser: (id) => this.request(`/admin/users/${id}`, { method: 'DELETE' }),
+        createGlobalConfig: (carrierId, config) => this.request(`/admin/carriers/${carrierId}/configs`, {
+            method: 'POST',
+            body: JSON.stringify(config),
+        }),
+        listCarrierConfigs: (carrierId) => this.request(`/admin/carriers/${carrierId}/configs`),
+        updateCarrierConfig: (carrierId, configId, config) => this.request(`/admin/carriers/${carrierId}/configs/${configId}`, { method: 'PUT', body: JSON.stringify(config) }),
+        addAllowlist: (email) => this.request('/admin/allowlist', {
+            method: 'POST',
+            body: JSON.stringify({ email }),
+        }),
+        listJobs: (params = {}) => this.request(`/admin/jobs${query(params)}`),
+        jobDetail: (jobId) => this.request(`/admin/jobs/${jobId}`),
+        retryJob: (jobId) => this.request(`/admin/jobs/${jobId}/retry`, {
+            method: 'POST',
+        }),
+        rescoreJob: (jobId) => this.request(`/admin/jobs/${jobId}/rescore`, { method: 'POST' }),
+        metrics: () => this.request('/admin/metrics'),
+        logs: (params = {}) => this.request(`/admin/logs${query(params)}`),
+    };
+}
+export function query(params) {
+    const entries = Object.entries(params).filter(([, v]) => v !== undefined && v !== '');
+    if (entries.length === 0)
+        return '';
+    const sp = new URLSearchParams();
+    for (const [k, v] of entries)
+        sp.set(k, String(v));
+    return `?${sp.toString()}`;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@commissionsight/sdk",
+  "version": "2.0.0",
+  "description": "Lightweight, zero-dependency TypeScript client for the CommissionSight API.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/commissionsight/sdk.git"
+  },
+  "keywords": [
+    "commissionsight",
+    "commission",
+    "insurance",
+    "carrier",
+    "api-client",
+    "sdk",
+    "typescript"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}