@simplr-ai/node 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,9 +1,33 @@
+type NetworkSource = "frontend" | "backend";
+interface NetworkLogEntry {
+    id: string;
+    source: NetworkSource;
+    timestamp: string;
+    sdk?: string;
+    applicationId?: string;
+    environment?: string;
+    method: string;
+    url: string;
+    requestHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    status?: number;
+    statusText?: string;
+    responseHeaders?: Record<string, string>;
+    responseBody?: unknown;
+    durationMs?: number;
+    ok?: boolean;
+    error?: string;
+}
+type NetworkLogger = (entry: NetworkLogEntry) => void;
+
 interface HttpConfig {
-    /** Auth headers to send (e.g. { "X-API-Key": "sk_…" } or { Authorization: "Bearer …" }). */
     authHeaders: Record<string, string>;
     baseUrl: string;
     timeoutMs: number;
     fetchImpl: typeof fetch;
+    onNetworkLog?: NetworkLogger;
+    logBodies?: boolean;
+    redactFields?: string[];
 }
 
 type RiskLevel = "low" | "medium" | "high" | "critical";
@@ -12,12 +36,24 @@ interface SimplrOptions {
     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). */
     timeoutMs?: number;
     /** Override the fetch implementation (defaults to global fetch). */
     fetch?: typeof fetch;
+    onNetworkLog?: NetworkLogger;
+    logBodies?: boolean;
+    redactFields?: string[];
+    shipNetworkLogs?: boolean;
+    applicationId?: string;
 }
 interface CheckInput {
     email?: string;
@@ -74,6 +110,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 {
@@ -129,12 +292,20 @@ interface FlagsOptions {
     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. */
-    environment?: "live" | "test";
+    /**
+     * 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;
+    onNetworkLog?: NetworkLogger;
+    logBodies?: boolean;
+    redactFields?: string[];
 }
 interface EvalContext {
     userId?: string;
@@ -172,6 +343,123 @@ declare class SimplrFlags {
     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;
@@ -217,6 +505,27 @@ declare class WebhookVerificationError extends Error {
     constructor(message: string);
 }
 
+interface ShipperConfig {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl: typeof fetch;
+    sdk: string;
+    applicationId?: string;
+    environment?: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+}
+declare class NetworkLogShipper {
+    private readonly cfg;
+    private queue;
+    private timer;
+    constructor(cfg: ShipperConfig);
+    start(): void;
+    add(entry: NetworkLogEntry): void;
+    flush(): Promise<void>;
+    stop(): void;
+}
+
 interface SimplrAdminOptions {
     /** Portal token (JWT) for dashboard/admin operations. */
     token: string;
@@ -299,9 +608,16 @@ 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?;
+    private readonly shipper?;
     constructor(options: SimplrOptions);
     /**
      * Server-side feature flags. Requires a `publicKey` in the constructor options
@@ -312,6 +628,8 @@ declare class Simplr {
     check(input: CheckInput): Promise<CheckResult>;
     /** Run up to 100 checks at once. */
     checkBulk(items: CheckInput[]): Promise<BulkResult<CheckResult>>;
+    flushNetworkLogs(): Promise<void>;
+    close(): void;
 }
 
-export { type BulkResult, type CheckInput, type CheckResult, type EdgeLogEntry, type EvalContext, type FlagDefinition, type FlagRule, type FlagsOptions, type OrderInput, type OrderResult, type PhoneOutcome, type PhoneReportInput, type RiskLevel, Simplr, SimplrAdmin, type SimplrAdminOptions, SimplrError, SimplrFlags, 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 NetworkLogEntry, NetworkLogShipper, type NetworkLogger, type NetworkSource, type OrderInput, type OrderResult, type PhoneOutcome, type PhoneReportInput, type ProfileResult, type ProfileRiskResult, type RUMEvent, type RUMEventBatch, type RUMEventType, type RUMLogLevel, type RiskLevel, type ShipperConfig, 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 };