@modelcost/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1208 @@
+import { z } from 'zod';
+
+/** Actions that can be taken when a budget threshold is reached. */
+declare const BudgetAction: z.ZodEnum<["alert", "throttle", "block"]>;
+type BudgetAction = z.infer<typeof BudgetAction>;
+/** Scope levels for budget policies. */
+declare const BudgetScope: z.ZodEnum<["organization", "feature", "environment", "custom"]>;
+type BudgetScope = z.infer<typeof BudgetScope>;
+/** Time periods for budget policies. */
+declare const BudgetPeriod: z.ZodEnum<["daily", "weekly", "monthly", "custom"]>;
+type BudgetPeriod = z.infer<typeof BudgetPeriod>;
+/** Supported AI providers. */
+declare const Provider: z.ZodEnum<["openai", "anthropic", "google", "aws_bedrock", "cohere", "mistral"]>;
+type Provider = z.infer<typeof Provider>;
+
+/**
+ * Zod schema for ModelCost initialization options.
+ * Validates all configuration fields and applies defaults.
+ */
+declare const ModelCostInitOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    orgId: z.ZodString;
+    environment: z.ZodDefault<z.ZodString>;
+    baseUrl: z.ZodDefault<z.ZodString>;
+    monthlyBudget: z.ZodOptional<z.ZodNumber>;
+    budgetAction: z.ZodDefault<z.ZodEnum<["alert", "throttle", "block"]>>;
+    failOpen: z.ZodDefault<z.ZodBoolean>;
+    flushIntervalMs: z.ZodDefault<z.ZodNumber>;
+    flushBatchSize: z.ZodDefault<z.ZodNumber>;
+    syncIntervalMs: z.ZodDefault<z.ZodNumber>;
+    contentPrivacy: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    environment: string;
+    apiKey: string;
+    orgId: string;
+    baseUrl: string;
+    budgetAction: "alert" | "throttle" | "block";
+    failOpen: boolean;
+    flushIntervalMs: number;
+    flushBatchSize: number;
+    syncIntervalMs: number;
+    contentPrivacy: boolean;
+    monthlyBudget?: number | undefined;
+}, {
+    apiKey: string;
+    orgId: string;
+    environment?: string | undefined;
+    baseUrl?: string | undefined;
+    monthlyBudget?: number | undefined;
+    budgetAction?: "alert" | "throttle" | "block" | undefined;
+    failOpen?: boolean | undefined;
+    flushIntervalMs?: number | undefined;
+    flushBatchSize?: number | undefined;
+    syncIntervalMs?: number | undefined;
+    contentPrivacy?: boolean | undefined;
+}>;
+type ModelCostInitOptions = z.input<typeof ModelCostInitOptionsSchema>;
+/**
+ * Resolved configuration after validation and env-var fallback.
+ */
+type ModelCostResolvedConfig = z.output<typeof ModelCostInitOptionsSchema>;
+/**
+ * Configuration manager that validates init options and reads
+ * environment variables as fallbacks.
+ */
+declare class ModelCostConfig {
+    readonly apiKey: string;
+    readonly orgId: string;
+    readonly environment: string;
+    readonly baseUrl: string;
+    readonly monthlyBudget: number | undefined;
+    readonly budgetAction: z.infer<typeof BudgetAction>;
+    readonly failOpen: boolean;
+    readonly flushIntervalMs: number;
+    readonly flushBatchSize: number;
+    readonly syncIntervalMs: number;
+    readonly contentPrivacy: boolean;
+    constructor(options: ModelCostInitOptions);
+}
+
+/**
+ * Result of a PII scan on a text string.
+ */
+interface PiiEntity {
+    type: string;
+    value: string;
+    start: number;
+    end: number;
+}
+interface PiiResult {
+    detected: boolean;
+    entities: PiiEntity[];
+    redactedText: string;
+}
+/**
+ * A governance violation detected by the full scanner.
+ */
+interface GovernanceViolation {
+    category: string;
+    type: string;
+    severity: string;
+    start: number;
+    end: number;
+}
+/**
+ * Result of a full governance scan across all categories.
+ */
+interface FullScanResult {
+    detected: boolean;
+    violations: GovernanceViolation[];
+    categories: string[];
+}
+/**
+ * Local PII scanner using regex pattern matching.
+ *
+ * Provides a fast, offline first-pass for PII detection before
+ * optionally deferring to the server-side governance scan.
+ *
+ * Also provides full governance scanning (PII, PHI, secrets, financial)
+ * for metadata-only mode where content never leaves the customer's environment.
+ */
+declare class PiiScanner {
+    /**
+     * Scan text and return all detected PII entities, plus a redacted version.
+     */
+    scan(text: string): PiiResult;
+    /**
+     * Full governance scan across multiple categories.
+     * Used in metadata-only mode where content never leaves the customer's environment.
+     */
+    fullScan(text: string, categories?: string[]): FullScanResult;
+    /**
+     * Convenience method: return only the redacted text.
+     */
+    redact(text: string): string;
+    private _scanPiiViolations;
+    private _scanPhi;
+    private _scanSecrets;
+    private _scanFinancial;
+    /**
+     * Remove overlapping entities, preferring the one that starts first
+     * (and is longest in case of a tie).
+     */
+    private _removeOverlaps;
+    /**
+     * Replace detected entities with [REDACTED] markers.
+     */
+    private _redactText;
+    /**
+     * Luhn algorithm for credit card validation.
+     */
+    static _isValidLuhn(number: string): boolean;
+}
+
+/**
+ * A single recorded call within a session.
+ */
+interface SessionCallRecord {
+    callSequence: number;
+    callType: string;
+    toolName?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cumulativeInputTokens: number;
+    costUsd: number;
+    cumulativeCostUsd: number;
+    createdAt: Date;
+}
+/**
+ * Options for creating a new SessionContext.
+ */
+interface SessionOptions {
+    sessionId: string;
+    serverSessionId?: string;
+    feature?: string;
+    userId?: string;
+    maxSpendUsd?: number;
+    maxIterations?: number;
+}
+/**
+ * Local session governance context.
+ *
+ * Tracks cumulative spend, iteration count, and call history for an
+ * agent session. Enforces budget and iteration limits before each call
+ * via `preCallCheck()`.
+ */
+declare class SessionContext {
+    readonly sessionId: string;
+    serverSessionId?: string;
+    readonly feature?: string;
+    readonly userId?: string;
+    readonly maxSpendUsd?: number;
+    readonly maxIterations?: number;
+    private _currentSpendUsd;
+    private _iterationCount;
+    private _cumulativeInputTokens;
+    private _status;
+    private _terminationReason?;
+    private _calls;
+    constructor(options: SessionOptions);
+    get currentSpendUsd(): number;
+    get iterationCount(): number;
+    get status(): string;
+    get terminationReason(): string | undefined;
+    get calls(): readonly SessionCallRecord[];
+    get remainingBudget(): number | undefined;
+    get remainingIterations(): number | undefined;
+    /**
+     * Pre-flight check before making an AI call.
+     * Throws if budget or iteration limits would be exceeded.
+     */
+    preCallCheck(estimatedCost: number): void;
+    /**
+     * Record a completed call, updating cumulative counters.
+     */
+    recordCall(options: {
+        callType: string;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        toolName?: string;
+    }): SessionCallRecord;
+    /**
+     * Close the session with a terminal status.
+     */
+    close(reason?: string): void;
+}
+
+/**
+ * Schema for budget check API response (snake_case from API -> camelCase).
+ */
+declare const BudgetCheckResponseSchema: z.ZodEffects<z.ZodObject<{
+    allowed: z.ZodBoolean;
+    action: z.ZodNullable<z.ZodString>;
+    throttle_percentage: z.ZodNullable<z.ZodNumber>;
+    reason: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: string | null;
+    throttle_percentage: number | null;
+    allowed: boolean;
+    reason: string | null;
+}, {
+    action: string | null;
+    throttle_percentage: number | null;
+    allowed: boolean;
+    reason: string | null;
+}>, {
+    allowed: boolean;
+    action: string | null;
+    throttlePercentage: number | null;
+    reason: string | null;
+}, {
+    action: string | null;
+    throttle_percentage: number | null;
+    allowed: boolean;
+    reason: string | null;
+}>;
+type BudgetCheckResponse = z.output<typeof BudgetCheckResponseSchema>;
+/**
+ * Schema for a single budget policy (snake_case from API -> camelCase).
+ */
+declare const BudgetPolicySchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scope: z.ZodEnum<["organization", "feature", "environment", "custom"]>;
+    scope_identifier: z.ZodNullable<z.ZodString>;
+    budget_amount_usd: z.ZodNumber;
+    period: z.ZodEnum<["daily", "weekly", "monthly", "custom"]>;
+    custom_period_days: z.ZodNullable<z.ZodNumber>;
+    action: z.ZodEnum<["alert", "throttle", "block"]>;
+    throttle_percentage: z.ZodNullable<z.ZodNumber>;
+    alert_thresholds: z.ZodNullable<z.ZodArray<z.ZodNumber, "many">>;
+    current_spend_usd: z.ZodNumber;
+    spend_percentage: z.ZodNumber;
+    period_start: z.ZodString;
+    is_active: z.ZodBoolean;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    scope: "custom" | "organization" | "feature" | "environment";
+    scope_identifier: string | null;
+    budget_amount_usd: number;
+    period: "custom" | "daily" | "weekly" | "monthly";
+    custom_period_days: number | null;
+    action: "alert" | "throttle" | "block";
+    throttle_percentage: number | null;
+    alert_thresholds: number[] | null;
+    current_spend_usd: number;
+    spend_percentage: number;
+    period_start: string;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}, {
+    id: string;
+    name: string;
+    scope: "custom" | "organization" | "feature" | "environment";
+    scope_identifier: string | null;
+    budget_amount_usd: number;
+    period: "custom" | "daily" | "weekly" | "monthly";
+    custom_period_days: number | null;
+    action: "alert" | "throttle" | "block";
+    throttle_percentage: number | null;
+    alert_thresholds: number[] | null;
+    current_spend_usd: number;
+    spend_percentage: number;
+    period_start: string;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}>, {
+    id: string;
+    name: string;
+    scope: "custom" | "organization" | "feature" | "environment";
+    scopeIdentifier: string | null;
+    budgetAmountUsd: number;
+    period: "custom" | "daily" | "weekly" | "monthly";
+    customPeriodDays: number | null;
+    action: "alert" | "throttle" | "block";
+    throttlePercentage: number | null;
+    alertThresholds: number[] | null;
+    currentSpendUsd: number;
+    spendPercentage: number;
+    periodStart: string;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}, {
+    id: string;
+    name: string;
+    scope: "custom" | "organization" | "feature" | "environment";
+    scope_identifier: string | null;
+    budget_amount_usd: number;
+    period: "custom" | "daily" | "weekly" | "monthly";
+    custom_period_days: number | null;
+    action: "alert" | "throttle" | "block";
+    throttle_percentage: number | null;
+    alert_thresholds: number[] | null;
+    current_spend_usd: number;
+    spend_percentage: number;
+    period_start: string;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}>;
+type BudgetPolicy = z.output<typeof BudgetPolicySchema>;
+/**
+ * Schema for the budget status API response (snake_case from API -> camelCase).
+ */
+declare const BudgetStatusResponseSchema: z.ZodEffects<z.ZodObject<{
+    policies: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        scope: z.ZodEnum<["organization", "feature", "environment", "custom"]>;
+        scope_identifier: z.ZodNullable<z.ZodString>;
+        budget_amount_usd: z.ZodNumber;
+        period: z.ZodEnum<["daily", "weekly", "monthly", "custom"]>;
+        custom_period_days: z.ZodNullable<z.ZodNumber>;
+        action: z.ZodEnum<["alert", "throttle", "block"]>;
+        throttle_percentage: z.ZodNullable<z.ZodNumber>;
+        alert_thresholds: z.ZodNullable<z.ZodArray<z.ZodNumber, "many">>;
+        current_spend_usd: z.ZodNumber;
+        spend_percentage: z.ZodNumber;
+        period_start: z.ZodString;
+        is_active: z.ZodBoolean;
+        created_at: z.ZodString;
+        updated_at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        scope: "custom" | "organization" | "feature" | "environment";
+        scope_identifier: string | null;
+        budget_amount_usd: number;
+        period: "custom" | "daily" | "weekly" | "monthly";
+        custom_period_days: number | null;
+        action: "alert" | "throttle" | "block";
+        throttle_percentage: number | null;
+        alert_thresholds: number[] | null;
+        current_spend_usd: number;
+        spend_percentage: number;
+        period_start: string;
+        is_active: boolean;
+        created_at: string;
+        updated_at: string;
+    }, {
+        id: string;
+        name: string;
+        scope: "custom" | "organization" | "feature" | "environment";
+        scope_identifier: string | null;
+        budget_amount_usd: number;
+        period: "custom" | "daily" | "weekly" | "monthly";
+        custom_period_days: number | null;
+        action: "alert" | "throttle" | "block";
+        throttle_percentage: number | null;
+        alert_thresholds: number[] | null;
+        current_spend_usd: number;
+        spend_percentage: number;
+        period_start: string;
+        is_active: boolean;
+        created_at: string;
+        updated_at: string;
+    }>, {
+        id: string;
+        name: string;
+        scope: "custom" | "organization" | "feature" | "environment";
+        scopeIdentifier: string | null;
+        budgetAmountUsd: number;
+        period: "custom" | "daily" | "weekly" | "monthly";
+        customPeriodDays: number | null;
+        action: "alert" | "throttle" | "block";
+        throttlePercentage: number | null;
+        alertThresholds: number[] | null;
+        currentSpendUsd: number;
+        spendPercentage: number;
+        periodStart: string;
+        isActive: boolean;
+        createdAt: string;
+        updatedAt: string;
+    }, {
+        id: string;
+        name: string;
+        scope: "custom" | "organization" | "feature" | "environment";
+        scope_identifier: string | null;
+        budget_amount_usd: number;
+        period: "custom" | "daily" | "weekly" | "monthly";
+        custom_period_days: number | null;
+        action: "alert" | "throttle" | "block";
+        throttle_percentage: number | null;
+        alert_thresholds: number[] | null;
+        current_spend_usd: number;
+        spend_percentage: number;
+        period_start: string;
+        is_active: boolean;
+        created_at: string;
+        updated_at: string;
+    }>, "many">;
+    total_budget_usd: z.ZodNumber;
+    total_spend_usd: z.ZodNumber;
+    policies_at_risk: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    policies: {
+        id: string;
+        name: string;
+        scope: "custom" | "organization" | "feature" | "environment";
+        scopeIdentifier: string | null;
+        budgetAmountUsd: number;
+        period: "custom" | "daily" | "weekly" | "monthly";
+        customPeriodDays: number | null;
+        action: "alert" | "throttle" | "block";
+        throttlePercentage: number | null;
+        alertThresholds: number[] | null;
+        currentSpendUsd: number;
+        spendPercentage: number;
+        periodStart: string;
+        isActive: boolean;
+        createdAt: string;
+        updatedAt: string;
+    }[];
+    total_budget_usd: number;
+    total_spend_usd: number;
+    policies_at_risk: number;
+}, {
+    policies: {
+        id: string;
+        name: string;
+        scope: "custom" | "organization" | "feature" | "environment";
+        scope_identifier: string | null;
+        budget_amount_usd: number;
+        period: "custom" | "daily" | "weekly" | "monthly";
+        custom_period_days: number | null;
+        action: "alert" | "throttle" | "block";
+        throttle_percentage: number | null;
+        alert_thresholds: number[] | null;
+        current_spend_usd: number;
+        spend_percentage: number;
+        period_start: string;
+        is_active: boolean;
+        created_at: string;
+        updated_at: string;
+    }[];
+    total_budget_usd: number;
+    total_spend_usd: number;
+    policies_at_risk: number;
+}>, {
+    policies: {
+        id: string;
+        name: string;
+        scope: "custom" | "organization" | "feature" | "environment";
+        scopeIdentifier: string | null;
+        budgetAmountUsd: number;
+        period: "custom" | "daily" | "weekly" | "monthly";
+        customPeriodDays: number | null;
+        action: "alert" | "throttle" | "block";
+        throttlePercentage: number | null;
+        alertThresholds: number[] | null;
+        currentSpendUsd: number;
+        spendPercentage: number;
+        periodStart: string;
+        isActive: boolean;
+        createdAt: string;
+        updatedAt: string;
+    }[];
+    totalBudgetUsd: number;
+    totalSpendUsd: number;
+    policiesAtRisk: number;
+}, {
+    policies: {
+        id: string;
+        name: string;
+        scope: "custom" | "organization" | "feature" | "environment";
+        scope_identifier: string | null;
+        budget_amount_usd: number;
+        period: "custom" | "daily" | "weekly" | "monthly";
+        custom_period_days: number | null;
+        action: "alert" | "throttle" | "block";
+        throttle_percentage: number | null;
+        alert_thresholds: number[] | null;
+        current_spend_usd: number;
+        spend_percentage: number;
+        period_start: string;
+        is_active: boolean;
+        created_at: string;
+        updated_at: string;
+    }[];
+    total_budget_usd: number;
+    total_spend_usd: number;
+    policies_at_risk: number;
+}>;
+type BudgetStatusResponse = z.output<typeof BudgetStatusResponseSchema>;
+
+declare const VERSION = "0.1.0";
+
+/**
+ * Schema for tracking an AI API call.
+ * API uses snake_case; we transform to camelCase for SDK consumers.
+ */
+declare const TrackRequestSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    timestamp: z.ZodString;
+    provider: z.ZodEnum<["openai", "anthropic", "google", "aws_bedrock", "cohere", "mistral"]>;
+    model: z.ZodString;
+    feature: z.ZodOptional<z.ZodString>;
+    customerId: z.ZodOptional<z.ZodString>;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    latencyMs: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    apiKey: string;
+    timestamp: string;
+    provider: "openai" | "anthropic" | "google" | "aws_bedrock" | "cohere" | "mistral";
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    feature?: string | undefined;
+    customerId?: string | undefined;
+    latencyMs?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    apiKey: string;
+    timestamp: string;
+    provider: "openai" | "anthropic" | "google" | "aws_bedrock" | "cohere" | "mistral";
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    feature?: string | undefined;
+    customerId?: string | undefined;
+    latencyMs?: number | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+type TrackRequest = z.infer<typeof TrackRequestSchema>;
+/** Schema for the track API response. */
+declare const TrackResponseSchema: z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+}, "strip", z.ZodTypeAny, {
+    status: "ok";
+}, {
+    status: "ok";
+}>;
+type TrackResponse = z.infer<typeof TrackResponseSchema>;
+
+interface CreateSessionRequest {
+    apiKey: string;
+    sessionId: string;
+    feature?: string;
+    userId?: string;
+    maxSpendUsd?: number;
+    maxIterations?: number;
+}
+interface RecordSessionCallRequest {
+    apiKey: string;
+    callSequence: number;
+    callType: string;
+    toolName?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cumulativeInputTokens: number;
+    costUsd: number;
+    cumulativeCostUsd: number;
+    piiDetected: boolean;
+}
+interface CloseSessionRequest {
+    apiKey: string;
+    status: string;
+    terminationReason?: string;
+    finalSpendUsd: number;
+    finalIterationCount: number;
+}
+interface CreateSessionResponse {
+    id: string;
+    sessionId: string;
+    status: string;
+    maxSpendUsd?: number;
+    maxIterations?: number;
+}
+
+/**
+ * Schema for a governance scan request (camelCase -> snake_case for API).
+ */
+declare const GovernanceScanRequestSchema: z.ZodObject<{
+    orgId: z.ZodString;
+    text: z.ZodString;
+    feature: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    orgId: string;
+    text: string;
+    feature?: string | undefined;
+    environment?: string | undefined;
+}, {
+    orgId: string;
+    text: string;
+    feature?: string | undefined;
+    environment?: string | undefined;
+}>;
+type GovernanceScanRequest = z.infer<typeof GovernanceScanRequestSchema>;
+/**
+ * Schema for a detected violation (snake_case from API -> camelCase).
+ */
+declare const DetectedViolationSchema: z.ZodObject<{
+    type: z.ZodString;
+    subtype: z.ZodString;
+    severity: z.ZodEnum<["low", "medium", "high"]>;
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    subtype: string;
+    severity: "low" | "medium" | "high";
+    start: number;
+    end: number;
+}, {
+    type: string;
+    subtype: string;
+    severity: "low" | "medium" | "high";
+    start: number;
+    end: number;
+}>;
+type DetectedViolation = z.infer<typeof DetectedViolationSchema>;
+/**
+ * Schema for the governance scan API response (snake_case from API -> camelCase).
+ */
+declare const GovernanceScanResponseSchema: z.ZodEffects<z.ZodObject<{
+    is_allowed: z.ZodBoolean;
+    action: z.ZodNullable<z.ZodString>;
+    violations: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        subtype: z.ZodString;
+        severity: z.ZodEnum<["low", "medium", "high"]>;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        subtype: string;
+        severity: "low" | "medium" | "high";
+        start: number;
+        end: number;
+    }, {
+        type: string;
+        subtype: string;
+        severity: "low" | "medium" | "high";
+        start: number;
+        end: number;
+    }>, "many">;
+    redacted_text: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: string | null;
+    is_allowed: boolean;
+    violations: {
+        type: string;
+        subtype: string;
+        severity: "low" | "medium" | "high";
+        start: number;
+        end: number;
+    }[];
+    redacted_text: string | null;
+}, {
+    action: string | null;
+    is_allowed: boolean;
+    violations: {
+        type: string;
+        subtype: string;
+        severity: "low" | "medium" | "high";
+        start: number;
+        end: number;
+    }[];
+    redacted_text: string | null;
+}>, {
+    isAllowed: boolean;
+    action: string | null;
+    violations: {
+        type: string;
+        subtype: string;
+        severity: "low" | "medium" | "high";
+        start: number;
+        end: number;
+    }[];
+    redactedText: string | null;
+}, {
+    action: string | null;
+    is_allowed: boolean;
+    violations: {
+        type: string;
+        subtype: string;
+        severity: "low" | "medium" | "high";
+        start: number;
+        end: number;
+    }[];
+    redacted_text: string | null;
+}>;
+type GovernanceScanResponse = z.output<typeof GovernanceScanResponseSchema>;
+/**
+ * Request to report a governance signal in metadata-only mode.
+ * No raw content is included — only classification signals.
+ */
+interface GovernanceSignalRequest {
+    organizationId: string;
+    violationType: string;
+    violationSubtype?: string;
+    severity: string;
+    userId?: string;
+    feature?: string;
+    environment?: string;
+    actionTaken: string;
+    wasAllowed: boolean;
+    detectedAt?: string;
+    source: string;
+    violationCount?: number;
+}
+
+/**
+ * Low-level HTTP client for the ModelCost API.
+ * Uses native fetch, implements circuit breaker, and supports fail-open semantics.
+ */
+declare class ModelCostClient {
+    private readonly _baseUrl;
+    private readonly _apiKey;
+    private readonly _headers;
+    private readonly _failOpen;
+    /** Circuit breaker state */
+    private _consecutiveFailures;
+    private _circuitOpenUntil;
+    constructor(config: ModelCostConfig);
+    /**
+     * Record a tracked AI API call.
+     */
+    track(request: TrackRequest): Promise<TrackResponse>;
+    /**
+     * Pre-flight budget check before making an AI call.
+     */
+    checkBudget(orgId: string, feature: string, estimatedCost: number): Promise<BudgetCheckResponse>;
+    /**
+     * Scan text for PII and governance violations.
+     */
+    scanText(request: GovernanceScanRequest): Promise<GovernanceScanResponse>;
+    /**
+     * Report a governance signal (metadata-only mode).
+     * Sends classification signals without raw content.
+     */
+    reportSignal(request: GovernanceSignalRequest): Promise<void>;
+    /**
+     * Get current budget status for an organization.
+     */
+    getBudgetStatus(orgId: string): Promise<BudgetStatusResponse>;
+    /**
+     * Create a new agent session on the server.
+     */
+    createSession(request: CreateSessionRequest): Promise<CreateSessionResponse>;
+    /**
+     * Record a call within an existing session.
+     */
+    recordSessionCall(sessionId: string, request: RecordSessionCallRequest): Promise<void>;
+    /**
+     * Close an existing session on the server.
+     */
+    closeSession(sessionId: string, request: CloseSessionRequest): Promise<void>;
+    /**
+     * Close the client (cleanup resources).
+     */
+    close(): void;
+    private _isCircuitOpen;
+    private _recordSuccess;
+    private _recordFailure;
+    private _post;
+    private _get;
+    private _request;
+    /**
+     * Returns a safe default response when operating in fail-open mode.
+     */
+    private _failOpenDefault;
+}
+
+/**
+ * Manages budget state with local caching and periodic sync.
+ * Keeps an in-memory cache of budget status to avoid hitting the API
+ * on every call, while still staying in sync with the server.
+ */
+declare class BudgetManager {
+    private _cache;
+    private _lastSync;
+    private readonly _syncIntervalMs;
+    constructor(syncIntervalMs: number);
+    /**
+     * Check whether a request with the given estimated cost is allowed.
+     * Uses the local cache if fresh, otherwise syncs from the API first.
+     */
+    check(client: ModelCostClient, orgId: string, feature: string, estimatedCost: number): Promise<BudgetCheckResponse>;
+    /**
+     * Sync the budget status from the server and populate the local cache.
+     */
+    sync(client: ModelCostClient, orgId: string): Promise<void>;
+    /**
+     * Optimistically update local spend after a tracked call,
+     * so subsequent budget checks reflect the estimated spend
+     * without waiting for the next server sync.
+     */
+    updateLocalSpend(orgId: string, _feature: string, cost: number): void;
+    /**
+     * Get the cached budget status for an org, if available.
+     */
+    getCached(orgId: string): BudgetStatusResponse | undefined;
+    /**
+     * Clear all cached state.
+     */
+    clear(): void;
+    private _isStale;
+}
+
+/**
+ * Schema describing the pricing for a single model.
+ */
+declare const ModelPricingSchema: z.ZodObject<{
+    provider: z.ZodString;
+    model: z.ZodString;
+    inputCostPer1k: z.ZodNumber;
+    outputCostPer1k: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    provider: string;
+    model: string;
+    inputCostPer1k: number;
+    outputCostPer1k: number;
+}, {
+    provider: string;
+    model: string;
+    inputCostPer1k: number;
+    outputCostPer1k: number;
+}>;
+type ModelPricing = z.infer<typeof ModelPricingSchema>;
+
+/**
+ * Known model pricing table (cost per 1,000 tokens in USD).
+ * Loaded from sdk/common/model_pricing.json at import time,
+ * refreshed at runtime via syncPricingFromApi().
+ */
+declare const MODEL_PRICING: ReadonlyMap<string, ModelPricing>;
+/**
+ * Calculate the cost of an AI call based on token counts and known pricing.
+ * Returns 0 if the model is not found in the pricing table.
+ */
+declare function calculateCost(model: string, inputTokens: number, outputTokens: number): number;
+/**
+ * Buffers track requests and periodically flushes them to the API.
+ */
+declare class CostTracker {
+    private _buffer;
+    private _flushTimer;
+    private _pricingSyncTimer;
+    private readonly _batchSize;
+    constructor(batchSize: number);
+    /**
+     * Add a track request to the buffer.
+     * Automatically flushes when buffer reaches batch size.
+     */
+    record(request: TrackRequest, client?: ModelCostClient): void;
+    /**
+     * Flush all buffered track requests to the API.
+     */
+    flush(client: ModelCostClient): Promise<void>;
+    /**
+     * Start automatic periodic flushing.
+     */
+    startAutoFlush(client: ModelCostClient, intervalMs: number): void;
+    /**
+     * Stop automatic periodic flushing.
+     */
+    stopAutoFlush(): void;
+    private static readonly _PRICING_SYNC_INTERVAL_MS;
+    /**
+     * Start periodic pricing sync from the server.
+     */
+    startPricingSync(baseUrl: string, apiKey: string): void;
+    /**
+     * Stop periodic pricing sync.
+     */
+    stopPricingSync(): void;
+    /**
+     * Get the current number of buffered requests.
+     */
+    get bufferSize(): number;
+}
+
+/**
+ * Token-bucket rate limiter.
+ *
+ * Allows `burst` tokens to be consumed immediately, and refills at `rate`
+ * tokens per second. Useful for throttling outbound API calls.
+ */
+declare class TokenBucketRateLimiter {
+    private _tokens;
+    private _lastRefill;
+    private readonly _rate;
+    private readonly _burst;
+    private readonly _strict;
+    /**
+     * @param rate - Tokens refilled per second
+     * @param burst - Maximum tokens (bucket capacity)
+     * @param strict - If true, `allow()` throws RateLimitedError instead of returning false
+     */
+    constructor(rate: number, burst: number, strict?: boolean);
+    /**
+     * Attempt to consume one token.
+     * Returns true if allowed, false if rate-limited.
+     * In strict mode, throws RateLimitedError instead of returning false.
+     */
+    allow(): boolean;
+    /**
+     * Wait until a token is available, then consume it.
+     * Resolves immediately if a token is available now.
+     */
+    wait(): Promise<void>;
+    /**
+     * Get the current number of available tokens (for inspection/testing).
+     */
+    get availableTokens(): number;
+    private _refill;
+}
+
+/**
+ * Base error class for all ModelCost SDK errors.
+ */
+declare class ModelCostError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the SDK is misconfigured (invalid API key, missing org ID, etc.).
+ */
+declare class ConfigurationError extends ModelCostError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a request is blocked because the budget has been exceeded.
+ */
+declare class BudgetExceededError extends ModelCostError {
+    readonly remainingBudget: number;
+    readonly scope: string;
+    readonly overrideUrl?: string;
+    constructor(message: string, remainingBudget: number, scope: string, overrideUrl?: string);
+}
+/**
+ * Thrown when the client is rate-limited by the ModelCost API.
+ */
+declare class RateLimitedError extends ModelCostError {
+    readonly retryAfterSeconds: number;
+    readonly limitDimension: string;
+    constructor(message: string, retryAfterSeconds: number, limitDimension: string);
+}
+/**
+ * Thrown when PII is detected in scanned text and the policy requires blocking.
+ */
+declare class PiiDetectedError extends ModelCostError {
+    readonly detectedEntities: DetectedViolation[];
+    readonly redactedText: string;
+    constructor(message: string, detectedEntities: DetectedViolation[], redactedText: string);
+}
+/**
+ * Thrown when a session's spend budget has been exceeded.
+ */
+declare class SessionBudgetExceededError extends ModelCostError {
+    readonly sessionId: string;
+    readonly currentSpend: number;
+    readonly maxSpend: number;
+    constructor(message: string, sessionId: string, currentSpend: number, maxSpend: number);
+}
+/**
+ * Thrown when a session's iteration limit has been exceeded.
+ */
+declare class SessionIterationLimitExceededError extends ModelCostError {
+    readonly sessionId: string;
+    readonly currentIterations: number;
+    readonly maxIterations: number;
+    constructor(message: string, sessionId: string, currentIterations: number, maxIterations: number);
+}
+/**
+ * Thrown when the ModelCost API returns an error response.
+ */
+declare class ModelCostApiError extends ModelCostError {
+    readonly statusCode: number;
+    readonly errorCode: string;
+    constructor(message: string, statusCode: number, errorCode: string);
+}
+
+/**
+ * Usage information extracted from a provider's API response.
+ */
+interface ExtractedUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/**
+ * Base interface that all provider wrappers must implement.
+ */
+interface BaseProvider {
+    /**
+     * Wrap an AI client with cost tracking, budget enforcement, and PII scanning.
+     * Returns a proxied version of the client.
+     */
+    wrap(client: unknown): unknown;
+    /**
+     * Extract token usage from a provider-specific API response.
+     */
+    extractUsage(response: unknown): ExtractedUsage;
+    /**
+     * Get the canonical provider name.
+     */
+    getProviderName(): string;
+}
+
+/**
+ * Provider wrapper for OpenAI-compatible clients.
+ *
+ * Intercepts `client.chat.completions.create()` calls to:
+ * 1. Run a budget pre-check
+ * 2. Scan prompt messages for PII
+ * 3. Enforce rate limits
+ * 4. Extract usage from the response and record the cost
+ */
+declare class OpenAIProvider implements BaseProvider {
+    private readonly _client;
+    private readonly _config;
+    private readonly _budgetManager;
+    private readonly _costTracker;
+    private readonly _piiScanner;
+    private readonly _rateLimiter;
+    private readonly _session?;
+    constructor(apiClient: ModelCostClient, config: ModelCostConfig, budgetManager: BudgetManager, costTracker: CostTracker, piiScanner: PiiScanner, rateLimiter: TokenBucketRateLimiter, session?: SessionContext);
+    getProviderName(): string;
+    extractUsage(response: unknown): ExtractedUsage;
+    wrap(client: unknown): unknown;
+}
+
+/**
+ * Provider wrapper for Anthropic clients.
+ *
+ * Intercepts `client.messages.create()` calls to add budget enforcement,
+ * PII scanning, rate limiting, and cost tracking.
+ */
+declare class AnthropicProvider implements BaseProvider {
+    private readonly _client;
+    private readonly _config;
+    private readonly _budgetManager;
+    private readonly _costTracker;
+    private readonly _piiScanner;
+    private readonly _rateLimiter;
+    private readonly _session?;
+    constructor(apiClient: ModelCostClient, config: ModelCostConfig, budgetManager: BudgetManager, costTracker: CostTracker, piiScanner: PiiScanner, rateLimiter: TokenBucketRateLimiter, session?: SessionContext);
+    getProviderName(): string;
+    extractUsage(response: unknown): ExtractedUsage;
+    wrap(client: unknown): unknown;
+}
+
+/**
+ * Provider wrapper for Google Generative AI clients.
+ *
+ * Intercepts `model.generateContent()` calls returned from
+ * `client.getGenerativeModel()`.
+ */
+declare class GoogleProvider implements BaseProvider {
+    private readonly _client;
+    private readonly _config;
+    private readonly _budgetManager;
+    private readonly _costTracker;
+    private readonly _piiScanner;
+    private readonly _rateLimiter;
+    private readonly _session?;
+    constructor(apiClient: ModelCostClient, config: ModelCostConfig, budgetManager: BudgetManager, costTracker: CostTracker, piiScanner: PiiScanner, rateLimiter: TokenBucketRateLimiter, session?: SessionContext);
+    getProviderName(): string;
+    extractUsage(response: unknown): ExtractedUsage;
+    wrap(client: unknown): unknown;
+    private _wrapModel;
+}
+
+interface TrackCostOptions {
+    model: string;
+    feature?: string;
+    provider?: string;
+    session?: SessionContext;
+}
+interface UsageReport {
+    totalSpendUsd: number;
+    totalBudgetUsd: number;
+    policiesAtRisk: number;
+    policies: BudgetStatusResponse["policies"];
+}
+/**
+ * Main entry point for the ModelCost Node.js SDK.
+ *
+ * Uses a static singleton pattern -- call `ModelCost.init()` once,
+ * then use the static methods from anywhere in your application.
+ *
+ * @example
+ * ```ts
+ * import { ModelCost } from "@modelcost/sdk";
+ * import OpenAI from "openai";
+ *
+ * ModelCost.init({ apiKey: "mc_...", orgId: "org-123" });
+ * const openai = ModelCost.wrap(new OpenAI());
+ * ```
+ */
+declare class ModelCost {
+    private static _instance;
+    /** Prevent direct instantiation. */
+    private constructor();
+    /**
+     * Initialize the ModelCost SDK. Must be called before any other method.
+     * Subsequent calls will re-initialize (shutting down the previous instance).
+     */
+    static init(options: ModelCostInitOptions): void;
+    /**
+     * Wrap an AI provider client with cost tracking, budget enforcement,
+     * and PII scanning. Returns a proxied version of the same client.
+     *
+     * Supports: OpenAI, Anthropic, Google Generative AI.
+     */
+    static wrap<T>(client: T, session?: SessionContext): T;
+    /**
+     * Decorator factory for tracking costs on individual functions.
+     *
+     * @example
+     * ```ts
+     * const trackedFn = ModelCost.trackCost({ model: "gpt-4o" })(myFunction);
+     * ```
+     */
+    static trackCost(options: TrackCostOptions): <TFn extends (...args: unknown[]) => unknown>(fn: TFn) => TFn;
+    /**
+     * Check whether a request is allowed under current budget policies.
+     */
+    static checkBudget(scope: string, id: string): Promise<BudgetCheckResponse>;
+    /**
+     * Get usage/spend information for a scope and period.
+     */
+    static getUsage(scope: string, _period: string): Promise<UsageReport>;
+    /**
+     * Start a new agent session with optional budget and iteration limits.
+     * Registers the session with the server (fail-open if unavailable)
+     * and returns a local SessionContext for tracking.
+     */
+    static startSession(options?: {
+        feature?: string;
+        maxSpendUsd?: number;
+        maxIterations?: number;
+        userId?: string;
+        sessionId?: string;
+    }): Promise<SessionContext>;
+    /**
+     * Close an active session, recording final state on the server.
+     */
+    static closeSession(session: SessionContext, reason?: string): Promise<void>;
+    /**
+     * Scan text for PII using the local scanner.
+     */
+    static scanPii(text: string): Promise<PiiResult>;
+    /**
+     * Flush all buffered tracking events to the API.
+     */
+    static flush(): Promise<void>;
+    /**
+     * Gracefully shut down the SDK: flush remaining events, stop timers, close client.
+     */
+    static shutdown(): Promise<void>;
+    /**
+     * Assert the SDK has been initialized and return the instance.
+     */
+    private static _requireInstance;
+}
+
+export { AnthropicProvider, type BaseProvider, BudgetAction, type BudgetCheckResponse, BudgetExceededError, BudgetManager, BudgetPeriod, type BudgetPolicy, BudgetScope, type BudgetStatusResponse, type CloseSessionRequest, ConfigurationError, CostTracker, type CreateSessionRequest, type CreateSessionResponse, type DetectedViolation, type ExtractedUsage, type FullScanResult, GoogleProvider, type GovernanceScanRequest, type GovernanceScanResponse, type GovernanceViolation, MODEL_PRICING, ModelCost, ModelCostApiError, ModelCostClient, ModelCostConfig, ModelCostError, type ModelCostInitOptions, type ModelCostResolvedConfig, type ModelPricing, OpenAIProvider, PiiDetectedError, type PiiEntity, type PiiResult, PiiScanner, Provider, RateLimitedError, type RecordSessionCallRequest, SessionBudgetExceededError, type SessionCallRecord, SessionContext, SessionIterationLimitExceededError, type SessionOptions, TokenBucketRateLimiter, type TrackCostOptions, type TrackRequest, type TrackResponse, type UsageReport, VERSION, calculateCost };