@clocknext/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,580 @@
+/**
+ * Public types for the ClockNext SDK.
+ *
+ * The signal types mirror the server's `recordSchema` (the body of
+ * `POST /api/v1/usage`) as a discriminated union, so the per-type required
+ * fields the server enforces with Zod refinements are enforced here at compile
+ * time instead of surfacing as runtime 422s.
+ */
+type SignalType = "wallet" | "credit" | "outcome";
+type SignalStatus = "SUCCESS" | "FAILURE" | "PENDING";
+/** Token counts for a signal. All default to 0. */
+interface Tokens {
+    input?: number;
+    output?: number;
+    cache?: number;
+}
+interface SignalBase {
+    /** The customer this usage belongs to (required). */
+    customerId: string;
+    /**
+     * The model's catalog id — must be enabled in your ClockNext org
+     * (Settings → Models). Matched case-insensitively against `OrgModel.modelId`.
+     */
+    model: string;
+    /** Token counts for this call. */
+    tokens?: Tokens;
+    /** Optional member (email) this usage is attributed to. */
+    member?: string;
+    /** Defaults to SUCCESS. */
+    status?: SignalStatus;
+    /** Free-form metadata. Credit rules can target `custom.<key>` paths. */
+    custom?: Record<string, unknown>;
+    /**
+     * Stable, unique id for this logical event. Generated automatically if
+     * omitted. Pass a deterministic value to dedupe across process restarts.
+     */
+    idempotencyKey?: string;
+}
+/** Meters a credit, identified by the credit's stable `key`. */
+interface CreditSignal extends SignalBase {
+    type: "credit";
+    /** The Credit's stable key (assigned when the credit was created). */
+    key: string;
+}
+/** Debits the customer's wallet in USD at the model's cost. */
+interface WalletSignal extends SignalBase {
+    type: "wallet";
+}
+/** Advances one step of a multi-call outcome workflow, by the step's `key`. */
+interface OutcomeSignal extends SignalBase {
+    type: "outcome";
+    /** The OutcomeStep's stable key — identifies the outcome AND the step. */
+    key: string;
+}
+type Signal = CreditSignal | WalletSignal | OutcomeSignal;
+/** Helper input shapes for the per-type convenience methods. */
+type CreditInput = Omit<CreditSignal, "type">;
+type WalletInput = Omit<WalletSignal, "type">;
+type OutcomeInput = Omit<OutcomeSignal, "type">;
+interface SerializedRuleApplication {
+    ruleId: string | null;
+    ruleName: string;
+    creditsApplied: number;
+}
+interface SerializedOutcomeAttribution {
+    name: string;
+    step: string;
+    completed: boolean;
+    progressSteps: string[];
+    totalSteps: number;
+}
+interface SerializedUsageLog {
+    id: string;
+    customerId: string;
+    modelName: string | null;
+    creditName: string | null;
+    member: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    cacheTokens: number;
+    /** Total credits deducted: the call's real per-model provider cost as a
+     *  fraction of the credit's base price (i.e. cost + your margin), plus any
+     *  credit-rule add-ons; 0 for wallet-money calls. */
+    credit: number;
+    providedCost: number;
+    customerCost: number;
+    status: SignalStatus;
+    appliedRules: SerializedRuleApplication[];
+    outcome: SerializedOutcomeAttribution | null;
+    createdAt: string;
+}
+/** Result of a single signal send (sync mode, or `{ wait: true }`). */
+interface TrackResult {
+    /** The idempotency key the event was sent with. */
+    idempotencyKey: string;
+    /** True when the signal was buffered (async mode) and not yet sent. */
+    queued: boolean;
+    /** The computed usage log — present only once the signal has been sent. */
+    usageLog?: SerializedUsageLog | null;
+}
+interface UsageList {
+    customer: {
+        id: string;
+        name: string;
+        creditAllowance: number;
+    };
+    totals: {
+        count: number;
+        cost: number;
+        revenue: number;
+        profit: number;
+        creditsUsed: number;
+    };
+    logs: SerializedUsageLog[];
+}
+interface ApiCustomer {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    email: string | null;
+    website: string | null;
+    phone: string | null;
+    legalName: string | null;
+    addressLine1: string | null;
+    addressLine2: string | null;
+    city: string | null;
+    state: string | null;
+    country: string | null;
+    pincode: string | null;
+    taxId: string | null;
+    notes: string | null;
+    logoUrl: string | null;
+    currencyCode: string;
+    creditAllowance: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Writable customer profile fields. `null` clears a column; omit to leave it. */
+interface CustomerProfileInput {
+    name?: string;
+    description?: string | null;
+    email?: string | null;
+    website?: string | null;
+    phone?: string | null;
+    legalName?: string | null;
+    addressLine1?: string | null;
+    addressLine2?: string | null;
+    city?: string | null;
+    state?: string | null;
+    country?: string | null;
+    pincode?: string | null;
+    taxId?: string | null;
+    notes?: string | null;
+    logoUrl?: string | null;
+    creditAllowance?: number;
+    /** ISO 4217 (3 letters); must be enabled for the org. */
+    currencyCode?: string;
+}
+/** `name` is required on create. */
+type CreateCustomerInput = CustomerProfileInput & {
+    name: string;
+};
+interface CustomerList {
+    customers: ApiCustomer[];
+    nextCursor: string | null;
+}
+type RevenueRange = "30d" | "6m" | "1y" | "all";
+/** Loosely typed insight payloads (revenue/balances/plan) — server shapes the
+ *  detail; we surface the whole envelope minus the `ok` flag. */
+type CustomerBalances = {
+    customerId: string;
+    currency: {
+        code: string;
+        rateUsd: number;
+    };
+    hasPlan: boolean;
+    wallet: {
+        balanceUsd: number;
+    } | null;
+    credits: unknown[];
+    outcomes: unknown[];
+    units: unknown[];
+};
+type CustomerPlan = {
+    customerId: string;
+    currency: {
+        code: string;
+        rateUsd: number;
+    };
+    plan: Record<string, unknown> | null;
+};
+type CustomerRevenue = {
+    customerId: string;
+    range: RevenueRange;
+    window: unknown;
+    bucket: unknown;
+    currency: {
+        code: string;
+        rateUsd: number;
+    };
+    revenue: number;
+    cost: number;
+    profit: number;
+    grossMargin: number;
+    deltas: Record<string, unknown>;
+    trend: unknown[];
+};
+interface PortalTokenInput {
+    customerId: string;
+    ttlSeconds?: number;
+    memberEmail?: string;
+}
+interface PortalToken {
+    token: string;
+    /** Unix seconds. */
+    expiresAt: number;
+    /** Seconds until expiry. */
+    expiresIn: number;
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+interface Logger {
+    debug?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+}
+type DropReason = "queue_full" | "send_failed";
+interface ClockNextConfig {
+    /** The org API key (`cnk_…`). Required. */
+    apiKey: string;
+    /** API base URL. Defaults to https://app.clocknext.com */
+    baseUrl?: string;
+    /**
+     * "async" (default) buffers signals and flushes in the background.
+     * "sync" awaits every send inside `track()`.
+     */
+    mode?: "async" | "sync";
+    /** Per-request timeout (ms). Default 10_000. */
+    timeoutMs?: number;
+    /** Background batching config (async mode). */
+    batch?: {
+        /** Flush when this many signals are buffered. Default 20. */
+        maxSize?: number;
+        /** Flush at least this often (ms). Default 2000. */
+        maxIntervalMs?: number;
+        /** Max concurrent in-flight sends per flush. Default 5. */
+        maxConcurrency?: number;
+        /** Drop new signals once the buffer reaches this size. Default 10_000. */
+        maxQueueSize?: number;
+    };
+    /** Retry policy for transient failures. */
+    retry?: {
+        /** Total attempts including the first. Default 5. */
+        maxAttempts?: number;
+        /** Base backoff (ms). Default 200. */
+        baseDelayMs?: number;
+        /** Max backoff (ms). Default 10_000. */
+        maxDelayMs?: number;
+    };
+    /** Injectable fetch (defaults to global fetch). */
+    fetch?: FetchLike;
+    logger?: Logger;
+    /** Called when a signal permanently fails (after retries / non-retryable). */
+    onError?: (error: unknown, signal?: Signal) => void;
+    /** Called after each successful background flush with the sent count. */
+    onFlush?: (sentCount: number) => void;
+    /** Called before each retry attempt. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }) => void;
+    /** Called when a signal is dropped without being sent. */
+    onDrop?: (signal: Signal, reason: DropReason) => void;
+}
+/** Fully-resolved config with defaults applied. */
+interface ResolvedConfig {
+    apiKey: string;
+    baseUrl: string;
+    mode: "async" | "sync";
+    timeoutMs: number;
+    batch: {
+        maxSize: number;
+        maxIntervalMs: number;
+        maxConcurrency: number;
+        maxQueueSize: number;
+    };
+    retry: {
+        maxAttempts: number;
+        baseDelayMs: number;
+        maxDelayMs: number;
+    };
+    fetch: FetchLike;
+    logger: Logger;
+    onError?: (error: unknown, signal?: Signal) => void;
+    onFlush?: (sentCount: number) => void;
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }) => void;
+    onDrop?: (signal: Signal, reason: DropReason) => void;
+}
+
+interface RequestOptions {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+    /** Reused across retries — what makes a retried write safe. */
+    idempotencyKey?: string;
+    /** Disable retries for this call (rarely needed). */
+    retry?: boolean;
+}
+/**
+ * The single HTTP seam. Builds the authenticated request, enforces a timeout,
+ * unwraps the `{ ok, ... }` envelope, maps failures to typed errors, and retries
+ * transient ones with backoff + jitter — reusing the same idempotency key on
+ * every attempt.
+ */
+declare class Transport {
+    private readonly cfg;
+    constructor(cfg: ResolvedConfig);
+    request<T = unknown>(opts: RequestOptions): Promise<T>;
+    /** One attempt: fetch + timeout + envelope/status handling. */
+    private once;
+    private headers;
+    private buildUrl;
+}
+
+/**
+ * The `customers` resource — full CRUD over the org's customers plus the
+ * read-only insight endpoints (usage / balances / plan / revenue). Every call
+ * is scoped to the API key's organisation server-side; a customer in another
+ * org resolves as a NotFoundError.
+ */
+declare class Customers {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Create a customer. `POST /api/v1/customers`. */
+    create(input: CreateCustomerInput): Promise<ApiCustomer>;
+    /** List customers, most-recent first (cursor-paginated). `GET /api/v1/customers`. */
+    list(params?: {
+        limit?: number;
+        q?: string;
+        cursor?: string;
+    }): Promise<CustomerList>;
+    /**
+     * Async iterator over ALL customers, transparently following the cursor.
+     * `for await (const c of cnk.customers.iterate()) { … }`
+     */
+    iterate(params?: {
+        limit?: number;
+        q?: string;
+    }): AsyncGenerator<ApiCustomer>;
+    /** Fetch one customer. `GET /api/v1/customers/:id`. */
+    get(id: string): Promise<ApiCustomer>;
+    /** Update a customer (partial). `PATCH /api/v1/customers/:id`. */
+    update(id: string, input: CustomerProfileInput): Promise<ApiCustomer>;
+    /** Delete a customer (members, invitations, usage logs cascade). */
+    delete(id: string): Promise<void>;
+    /** A customer's usage history. `GET /api/v1/customers/:id/usage`. */
+    usage(id: string, params?: {
+        limit?: number;
+    }): Promise<UsageList>;
+    /** Wallet / credit / outcome / unit balances. `GET …/:id/balances`. */
+    balances(id: string): Promise<CustomerBalances>;
+    /** The customer's current plan. `GET …/:id/plan`. */
+    plan(id: string): Promise<CustomerPlan>;
+    /** Revenue / cost / profit / margin over a window. `GET …/:id/revenue`. */
+    revenue(id: string, params?: {
+        range?: RevenueRange;
+    }): Promise<CustomerRevenue>;
+}
+
+/**
+ * The `portal` resource — mint a short-lived embed token for one of your
+ * customers, then render `<iframe src=".../portal/embed?token=<token>">`. The
+ * HS256 signing secret never leaves ClockNext; your backend only needs its API
+ * key. `POST /api/v1/portal/token`.
+ */
+declare class Portal {
+    private readonly transport;
+    constructor(transport: Transport);
+    createToken(input: PortalTokenInput): Promise<PortalToken>;
+}
+
+/** One buffered, wire-ready signal awaiting a background flush. */
+interface QueuedSignal {
+    /** The exact JSON body to POST to /api/v1/usage. */
+    body: Record<string, unknown>;
+    /** Reused across retries. */
+    idempotencyKey: string;
+    /** The original signal — passed to onError/onDrop hooks. */
+    signal: Signal;
+}
+/**
+ * Pluggable buffer. The default is in-memory; a host that needs to survive a
+ * crash *before* send can implement this against disk/Redis/SQLite.
+ */
+interface QueueStore {
+    push(item: QueuedSignal): void;
+    /** Remove and return up to `n` items (FIFO). */
+    take(n: number): QueuedSignal[];
+    size(): number;
+}
+
+/**
+ * Background send engine for async-mode signals. Buffers wire-ready signals and
+ * flushes them when the buffer reaches `maxSize` OR every `maxIntervalMs`,
+ * whichever comes first — the Segment/Amberflo pattern. The Transport owns
+ * retries; `close()` drains and awaits in-flight sends so a serverless process
+ * can flush before it freezes.
+ */
+declare class Flusher {
+    private readonly transport;
+    private readonly cfg;
+    private readonly queue;
+    private timer;
+    private draining;
+    private closed;
+    constructor(transport: Transport, cfg: ResolvedConfig);
+    /** Buffer one signal. Drops (with onDrop) when closed or the queue is full. */
+    enqueue(item: QueuedSignal): void;
+    /** Arm the interval timer if it isn't already running. */
+    private arm;
+    /**
+     * Send everything currently buffered. Overlapping calls share the single
+     * in-progress drain, so total in-flight sends never exceed `maxConcurrency`.
+     */
+    flush(): Promise<void>;
+    /** Drain the buffer in concurrency-bounded waves until it's empty. */
+    private drain;
+    /** Send one item; never throws — failures surface via onError/onDrop. */
+    private send;
+    get size(): number;
+    /** Flush remaining signals, then refuse further enqueues. */
+    close(): Promise<void>;
+}
+
+/** Builds the `POST /api/v1/usage` body from a typed Signal. */
+declare function signalToWire(signal: Signal): Record<string, unknown>;
+/**
+ * The `signals` resource: record usage signals and read them back.
+ *
+ * In async mode (default), `track()` buffers the signal and returns immediately
+ * with `{ queued: true }`. Pass `{ wait: true }` (or construct the client in
+ * `sync` mode) to await the send and receive the computed `usageLog`.
+ */
+declare class Signals {
+    private readonly transport;
+    private readonly flusher;
+    private readonly cfg;
+    constructor(transport: Transport, flusher: Flusher, cfg: ResolvedConfig);
+    track(signal: Signal, opts?: {
+        wait?: boolean;
+    }): Promise<TrackResult>;
+    /** Meter a named credit. */
+    credit(input: CreditInput, opts?: {
+        wait?: boolean;
+    }): Promise<TrackResult>;
+    /** Debit the customer's wallet at model cost. */
+    wallet(input: WalletInput, opts?: {
+        wait?: boolean;
+    }): Promise<TrackResult>;
+    /** Advance one step of an outcome workflow. */
+    outcome(input: OutcomeInput, opts?: {
+        wait?: boolean;
+    }): Promise<TrackResult>;
+    /** Recent usage logs + totals for a customer. `GET /api/v1/usage`. */
+    list(params: {
+        customerId: string;
+        limit?: number;
+    }): Promise<UsageList>;
+}
+
+/**
+ * The ClockNext client.
+ *
+ * ```ts
+ * const cnk = new ClockNext({ apiKey: process.env.CLOCKNEXT_API_KEY! });
+ *
+ * await cnk.signals.credit({
+ *   customerId: "cus_123",
+ *   model: "gpt-4o",          // catalog model id
+ *   key: "api_credit",        // the credit's stable key
+ *   tokens: { input: 1200, output: 340 },
+ * });
+ *
+ * // before a serverless function returns / on shutdown:
+ * await cnk.flush();
+ * ```
+ */
+declare class ClockNext {
+    /** Record + read usage signals. */
+    readonly signals: Signals;
+    /** Manage customers and read their insights. */
+    readonly customers: Customers;
+    /** Mint customer-portal embed tokens. */
+    readonly portal: Portal;
+    private readonly cfg;
+    private readonly flusher;
+    constructor(config: ClockNextConfig);
+    /** Number of signals currently buffered (async mode). */
+    get pending(): number;
+    /** Force-send all buffered signals now. Await before a serverless return. */
+    flush(): Promise<void>;
+    /** Flush and stop the background timer. Call on graceful shutdown. */
+    close(): Promise<void>;
+}
+
+/**
+ * Typed error hierarchy. The server returns `{ ok: false, error }` with a
+ * meaningful HTTP status; we map that status to a class so callers can branch
+ * on the *kind* of failure (e.g. allowance exhausted ⇒ upsell; network ⇒ ignore,
+ * it's queued) rather than string-matching messages.
+ */
+declare class ClockNextError extends Error {
+    /** HTTP status, when the failure came from a server response. */
+    readonly status?: number;
+    /** The idempotency key of the offending signal, when applicable. */
+    readonly idempotencyKey?: string;
+    /** Whether the SDK considers this failure worth retrying. */
+    readonly retryable: boolean;
+    constructor(message: string, opts?: {
+        status?: number;
+        idempotencyKey?: string;
+        retryable?: boolean;
+    });
+}
+/** 401 — missing / invalid / expired API key. */
+declare class AuthError extends ClockNextError {
+}
+/** 400 — malformed request / schema validation failure. */
+declare class ValidationError extends ClockNextError {
+}
+/** 404 — unknown customer (also returned for cross-org access). */
+declare class NotFoundError extends ClockNextError {
+}
+/** 422 — no active plan, meter not in plan, model not enabled, member missing. */
+declare class PlanError extends ClockNextError {
+}
+/** 422 — insufficient credits / units / outcomes for the call. */
+declare class AllowanceError extends ClockNextError {
+}
+/** 409 — conflict (e.g. idempotency-key reuse with a different payload). */
+declare class ConflictError extends ClockNextError {
+}
+/** 429 — rate limited. */
+declare class RateLimitError extends ClockNextError {
+    readonly retryAfterMs?: number;
+    constructor(message: string, opts?: {
+        idempotencyKey?: string;
+        retryAfterMs?: number;
+    });
+}
+/** 5xx — server-side error. */
+declare class ServerError extends ClockNextError {
+}
+/** fetch threw / request timed out — request never completed. */
+declare class NetworkError extends ClockNextError {
+    constructor(message: string, opts?: {
+        idempotencyKey?: string;
+    });
+}
+
+/**
+ * Generates a stable idempotency key for one logical event. Generated ONCE at
+ * enqueue/track time and reused across every retry of that event — regenerating
+ * per HTTP attempt would defeat dedup (the documented foot-gun in most usage
+ * SDKs).
+ *
+ * Uses the Web Crypto global (`globalThis.crypto`), which is present on Node 18+
+ * and every edge runtime — and, unlike a static `node:crypto` import, never
+ * fails to load on runtimes that lack Node built-ins. Degrades through
+ * `getRandomValues` to `Math.random` so it always returns a v4 UUID.
+ */
+declare function newIdempotencyKey(): string;
+
+export { AllowanceError, type ApiCustomer, AuthError, ClockNext, type ClockNextConfig, ClockNextError, ConflictError, type CreateCustomerInput, type CreditInput, type CreditSignal, type CustomerBalances, type CustomerList, type CustomerPlan, type CustomerProfileInput, type CustomerRevenue, type DropReason, type FetchLike, type Logger, NetworkError, NotFoundError, type OutcomeInput, type OutcomeSignal, PlanError, type PortalToken, type PortalTokenInput, type QueueStore, type QueuedSignal, RateLimitError, type RevenueRange, type SerializedOutcomeAttribution, type SerializedRuleApplication, type SerializedUsageLog, ServerError, type Signal, type SignalStatus, type SignalType, type Tokens, type TrackResult, type UsageList, ValidationError, type WalletInput, type WalletSignal, newIdempotencyKey, signalToWire };