@simplr-ai/node 1.0.0 → 1.1.1

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 interface HttpConfig {
-    apiKey: string;
+    /** Auth headers to send (e.g. { "X-API-Key": "sk_…" } or { Authorization: "Bearer …" }). */
+    authHeaders: Record<string, string>;
     baseUrl: string;
     timeoutMs: number;
     fetchImpl: typeof fetch;
@@ -9,6 +10,15 @@ type RiskLevel = "low" | "medium" | "high" | "critical";
 interface SimplrOptions {
     /** Secret API key (sk_live_… / sk_test_…). Keep this server-side only. */
     apiKey: string;
+    /** Public key (pk_…) — enables `simplr.flags` for server-side feature-flag evaluation. */
+    publicKey?: string;
+    /**
+     * Which environment's flags `simplr.flags` should load. Accepts a named
+     * environment slug (e.g. "dev", "uat", "prod") as well as the legacy
+     * "live"/"test" key modes. When unset, the API falls back to the public
+     * key's own live/test mode.
+     */
+    environment?: string;
     /** API base URL. Defaults to https://api.simplr.sh. */
     baseUrl?: string;
     /** Per-request timeout in ms (default 15000). */
@@ -71,6 +81,133 @@ interface EdgeLogEntry {
     message: string;
     [key: string]: unknown;
 }
+interface IdentifyOptions {
+    /** Profile type. */
+    profileType?: "customer" | "cashier" | "employee";
+    /** Device fingerprint hash to link to this profile. */
+    fingerprintHash?: string;
+    /** Extra fields merged into the request body. */
+    [key: string]: unknown;
+}
+interface ProfileResult {
+    profile: {
+        id: string;
+        external_id: string;
+        profile_type: string;
+        status: string;
+        risk_score: number;
+        risk_level: string;
+        device_count: number;
+        total_orders: number;
+        first_seen_at: string;
+        last_seen_at: string;
+    };
+    is_new: boolean;
+    device_linked: boolean;
+    device_anomaly?: string;
+    [key: string]: unknown;
+}
+interface ProfileRiskResult {
+    profile: {
+        id: string;
+        external_id: string;
+        profile_type: string;
+        status: string;
+        risk_score: number;
+        risk_level: string;
+        signals: Record<string, number>;
+        device_count: number;
+        total_orders: number;
+        flagged_orders: number;
+        fraud_reports: number;
+        legitimate_reports: number;
+        first_seen_at: string;
+        last_seen_at: string;
+    };
+    [key: string]: unknown;
+}
+type RUMEventType = "session_start" | "session_end" | "view" | "action" | "error" | "log";
+type RUMLogLevel = "debug" | "info" | "warn" | "error";
+interface RUMEvent {
+    type: RUMEventType;
+    timestamp: number;
+    sessionId: string;
+    viewId?: string;
+    userId?: string;
+    applicationId: string;
+    applicationVersion?: string;
+    environment?: string;
+    view?: {
+        id: string;
+        name: string;
+    };
+    action?: {
+        name: string;
+        type: string;
+    };
+    error?: {
+        message: string;
+        stack?: string;
+        type?: string;
+    };
+    log?: {
+        level: RUMLogLevel;
+        message: string;
+    };
+    attributes?: Record<string, unknown>;
+    userAttributes?: Record<string, unknown>;
+    globalAttributes?: Record<string, unknown>;
+}
+interface RUMEventBatch {
+    events: RUMEvent[];
+    sentAt: number;
+}
+type BindingMode = "verified_device" | "any_location";
+interface CreateDelegationOptions {
+    userId: string;
+    email?: string;
+    binding?: BindingMode;
+    expiresInDays?: number;
+    sessionId?: string;
+    fingerprintHash?: string;
+}
+interface DelegationResult {
+    token: string;
+    delegationId: string;
+    expiresAt: string;
+    bindingMode: BindingMode;
+}
+interface DelegationInfo {
+    delegationId: string;
+    endUserId: string;
+    bindingMode: BindingMode;
+    status: "active" | "revoked" | "expired";
+    expiresAt: string;
+    useCount: number;
+    lastUsedAt?: string;
+    createdAt: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    sessionType?: "ai";
+    endUserId?: string;
+    delegation?: {
+        delegationId: string;
+        bindingMode: BindingMode;
+        expiresAt: string;
+        useCount: number;
+    };
+    error?: string;
+}
+interface DelegationStats {
+    totalDelegations: number;
+    activeDelegations: number;
+    totalUses: number;
+    delegationsByBinding: {
+        verifiedDevice: number;
+        anyLocation: number;
+    };
+}
 
 /** Order fraud scoring. */
 declare class OrdersResource {
@@ -109,6 +246,188 @@ declare class EdgeResource {
     ingestLogs(deviceId: string, logs: EdgeLogEntry[]): Promise<unknown>;
 }
 
+interface FlagRule {
+    attribute: string;
+    op: "eq" | "neq" | "contains";
+    value: string;
+}
+interface FlagDefinition {
+    key: string;
+    enabled: boolean;
+    rollout_percentage: number;
+    target_user_ids: string[];
+    rules: FlagRule[];
+}
+interface FlagsOptions {
+    /** Public API key (pk_live_… / pk_test_…). Required — flags read uses the public key. */
+    publicKey: string;
+    /** API base URL. Defaults to https://api.simplr.sh. */
+    baseUrl?: string;
+    /**
+     * Which environment's flags to load. Defaults to the key's own environment
+     * (the API falls back to the key's live/test mode when unset). Accepts a
+     * named environment slug (e.g. "dev", "uat", "prod") as well as the legacy
+     * "live"/"test" key modes. Sent to the API as `?environment=<value>`.
+     */
+    environment?: string;
+    /** Auto-refresh interval in ms (default 60000; 0 disables). */
+    refreshIntervalMs?: number;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+interface EvalContext {
+    userId?: string;
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Server-side feature flags with local, deterministic evaluation.
+ *
+ * ```ts
+ * const flags = new SimplrFlags({ publicKey: process.env.SIMPLR_PUBLIC_KEY! });
+ * await flags.initialize();
+ * if (flags.isEnabled("new-checkout", { userId: "user_123" })) { ... }
+ * ```
+ */
+declare class SimplrFlags {
+    private readonly cfg;
+    private readonly environment?;
+    private readonly refreshIntervalMs;
+    private flags;
+    private defaultUserId?;
+    private timer;
+    private ready;
+    constructor(options: FlagsOptions);
+    /** Fetch the flag config once and start the background refresh. */
+    initialize(): Promise<void>;
+    /** Set the default identifier used for bucketing when none is passed to isEnabled. */
+    setUser(userId: string): void;
+    /** Re-fetch the flag config (counts as one billable request). */
+    refresh(): Promise<void>;
+    /** Evaluate a flag locally. Deterministic per user; no network call. */
+    isEnabled(key: string, ctx?: EvalContext): boolean;
+    getAll(): Record<string, FlagDefinition>;
+    isReady(): boolean;
+    /** Stop the background refresh timer. */
+    dispose(): void;
+}
+
+/**
+ * Anonymous user profile management and order fraud monitoring.
+ *
+ * Works with the configured key (secret for server-side use). Mirrors the
+ * browser SimplrProfiles surface but reuses the Node http helper (which unwraps
+ * the `{ success, message, content }` envelope).
+ */
+declare class SimplrProfiles {
+    private readonly cfg;
+    constructor(cfg: HttpConfig);
+    /**
+     * Identify a user — creates or updates an anonymous profile and (optionally)
+     * links a device fingerprint. POST /v1/profiles.
+     */
+    identify(externalId: string, options?: IdentifyOptions): Promise<ProfileResult>;
+    /** Submit an order for real-time fraud scoring. POST /v1/orders. */
+    submitOrder(order: OrderInput): Promise<OrderResult>;
+    /** Get the risk profile for a user. GET /v1/profiles/{externalId}. */
+    getProfileRisk(externalId: string): Promise<ProfileRiskResult>;
+    /** Report a profile as fraud or legitimate. POST /v1/profiles/{externalId}/outcome. */
+    reportOutcome(externalId: string, outcome: "fraud" | "legitimate"): Promise<void>;
+}
+
+interface SimplrRUMConfig {
+    /** Application identifier (required). */
+    applicationId: string;
+    /** Optional version/environment tags applied to every event. */
+    applicationVersion?: string;
+    environment?: string;
+    /** Flush when this many events are queued (default 30). */
+    batchSize?: number;
+    /** Background flush interval in ms (default 10000; 0 disables the timer). */
+    flushInterval?: number;
+    /** Override the events endpoint path (default /v1/rum/events). */
+    endpoint?: string;
+}
+/**
+ * Server-side Real User Monitoring. Batches events and flushes them to
+ * POST /v1/rum/events using the configured key. Unlike the browser SDK there is
+ * no DOM auto-capture — views/actions/errors/logs are reported via the public
+ * API. A timer-based flush is installed with `unref()` so it never keeps the
+ * Node process alive.
+ */
+declare class SimplrRUM {
+    private readonly cfg;
+    private config;
+    private initialized;
+    private queue;
+    private timer;
+    private flushing;
+    private sessionId;
+    private currentViewId;
+    private userId?;
+    private userAttributes?;
+    private globalAttributes;
+    private batchSize;
+    private endpoint;
+    constructor(cfg: HttpConfig);
+    /** Initialize the SDK, start a session, and begin the flush timer. */
+    initialize(config: SimplrRUMConfig): void;
+    isInitialized(): boolean;
+    /** Associate subsequent events with a user. */
+    setUser(userId: string, attributes?: Record<string, unknown>): void;
+    clearUser(): void;
+    addAttribute(key: string, value: unknown): void;
+    removeAttribute(key: string): void;
+    /** Track a screen/page view. */
+    trackView(name: string, attributes?: Record<string, unknown>): void;
+    /** Track a user action. */
+    trackAction(name: string, attributes?: Record<string, unknown>): void;
+    /** Track an error. */
+    trackError(error: Error | {
+        message: string;
+        stack?: string;
+        type?: string;
+    }, attributes?: Record<string, unknown>): void;
+    /** Emit a log line. */
+    log(level: RUMLogLevel, message: string, attributes?: Record<string, unknown>): void;
+    private trackEvent;
+    /** Flush queued events to POST /v1/rum/events. */
+    flush(): Promise<void>;
+    /** End the session, flush remaining events, and stop the timer. */
+    stopSession(): Promise<void>;
+    getSessionId(): string | null;
+    getViewId(): string | null;
+}
+
+/**
+ * AI delegation — OAuth-like AI authentication. Lets you mint, validate and
+ * revoke delegation tokens that an end user shares with their AI agent.
+ *
+ * Reuses the Node http helper, which unwraps the `{ success, message, content }`
+ * envelope — so `apiRequest` returns the inner `content` object directly.
+ */
+declare class SimplrAI {
+    private readonly cfg;
+    constructor(cfg: HttpConfig);
+    /** Create a new AI delegation token for a user. POST /v1/ai/delegations. */
+    createDelegation(options: CreateDelegationOptions): Promise<DelegationResult>;
+    /** Validate (introspect) an AI delegation token. POST /v1/ai/validate. */
+    validate(token: string, options?: {
+        fingerprintHash?: string;
+        aiProvider?: string;
+        action?: string;
+    }): Promise<ValidationResult>;
+    /** Revoke a delegation. POST /v1/ai/delegations/{id}/revoke. */
+    revoke(delegationId: string, reason?: string): Promise<void>;
+    /** List delegations, optionally filtered by user. GET /v1/ai/delegations. */
+    list(userId?: string): Promise<DelegationInfo[]>;
+    /** Get a single delegation. GET /v1/ai/delegations/{id}. */
+    get(delegationId: string): Promise<DelegationInfo>;
+    /** Get delegation statistics. GET /v1/ai/stats. */
+    stats(): Promise<DelegationStats>;
+    /** Revoke all delegations for a user (e.g. on logout). POST /v1/ai/revoke-all. */
+    revokeAllForUser(userId: string, reason?: string): Promise<number>;
+}
+
 interface VerifyOptions {
     /** Reject signatures whose timestamp is older than this many seconds (default 300). 0 disables. */
     toleranceSec?: number;
@@ -154,6 +473,74 @@ declare class WebhookVerificationError extends Error {
     constructor(message: string);
 }
 
+interface SimplrAdminOptions {
+    /** Portal token (JWT) for dashboard/admin operations. */
+    token: string;
+    /** API base URL. Defaults to https://api.simplr.sh. */
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/** Usage / measurement reads. */
+declare class UsageApi {
+    private readonly cfg;
+    constructor(cfg: HttpConfig);
+    /** Aggregate usage stats for an org. */
+    stats(orgId: string): Promise<unknown>;
+    /** Raw usage logs for an org. */
+    logs(orgId: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    /** Billing usage breakdown (per-service totals + estimated cost). */
+    billing(orgId: string): Promise<unknown>;
+}
+/** Feature-flag administration (create/update/delete/history). */
+declare class FlagsAdminApi {
+    private readonly cfg;
+    constructor(cfg: HttpConfig);
+    list(orgId: string, environment?: "live" | "test"): Promise<unknown>;
+    get(orgId: string, id: string): Promise<unknown>;
+    create(orgId: string, data: Record<string, unknown>): Promise<unknown>;
+    update(orgId: string, id: string, data: Record<string, unknown>): Promise<unknown>;
+    remove(orgId: string, id: string): Promise<unknown>;
+    history(orgId: string, id: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+}
+/** RUM analytics reads. */
+declare class RumApi {
+    private readonly cfg;
+    constructor(cfg: HttpConfig);
+    overview(orgId: string, params?: {
+        application_id?: string;
+        start_date?: string;
+        end_date?: string;
+    }): Promise<unknown>;
+    sessions(orgId: string, params?: {
+        page?: number;
+        limit?: number;
+        user_id?: string;
+    }): Promise<unknown>;
+}
+/**
+ * Management client for dashboard/admin operations that require a portal token
+ * (usage/measurement, feature-flag CRUD, RUM analytics).
+ *
+ * ```ts
+ * const admin = new SimplrAdmin({ token: process.env.SIMPLR_PORTAL_TOKEN! });
+ * const usage = await admin.usage.billing(orgId);
+ * await admin.flags.create(orgId, { key: "new-checkout", environment: "test", rollout_percentage: 10 });
+ * ```
+ */
+declare class SimplrAdmin {
+    readonly usage: UsageApi;
+    readonly flags: FlagsAdminApi;
+    readonly rum: RumApi;
+    constructor(options: SimplrAdminOptions);
+}
+
 /**
  * Simplr server-side client.
  *
@@ -168,13 +555,25 @@ declare class Simplr {
     readonly orders: OrdersResource;
     readonly phone: PhoneResource;
     readonly edge: EdgeResource;
+    /** Anonymous user profiles + order fraud monitoring. */
+    readonly profiles: SimplrProfiles;
+    /** Real User Monitoring — batched events to /v1/rum/events. */
+    readonly rum: SimplrRUM;
+    /** AI delegation — OAuth-like AI authentication. */
+    readonly ai: SimplrAI;
     /** Webhook signature helpers (no network). */
     readonly webhooks: typeof webhooks$1;
+    private readonly _flags?;
     constructor(options: SimplrOptions);
+    /**
+     * Server-side feature flags. Requires a `publicKey` in the constructor options
+     * (flag config is read with the public key). Call `simplr.flags.initialize()` once.
+     */
+    get flags(): SimplrFlags;
     /** Run an identity/fraud check. Provide any of email, phone, device, behavior. */
     check(input: CheckInput): Promise<CheckResult>;
     /** Run up to 100 checks at once. */
     checkBulk(items: CheckInput[]): Promise<BulkResult<CheckResult>>;
 }
 
-export { type BulkResult, type CheckInput, type CheckResult, type EdgeLogEntry, type OrderInput, type OrderResult, type PhoneOutcome, type PhoneReportInput, type RiskLevel, Simplr, SimplrError, type SimplrOptions, WebhookVerificationError, constructEvent as constructWebhookEvent, Simplr as default, verify as verifyWebhook };
+export { type BindingMode, type BulkResult, type CheckInput, type CheckResult, type CreateDelegationOptions, type DelegationInfo, type DelegationResult, type DelegationStats, type EdgeLogEntry, type EvalContext, type FlagDefinition, type FlagRule, type FlagsOptions, type IdentifyOptions, type OrderInput, type OrderResult, type PhoneOutcome, type PhoneReportInput, type ProfileResult, type ProfileRiskResult, type RUMEvent, type RUMEventBatch, type RUMEventType, type RUMLogLevel, type RiskLevel, Simplr, SimplrAI, SimplrAdmin, type SimplrAdminOptions, SimplrError, SimplrFlags, type SimplrOptions, SimplrProfiles, SimplrRUM, type SimplrRUMConfig, type ValidationResult, WebhookVerificationError, constructEvent as constructWebhookEvent, Simplr as default, verify as verifyWebhook };