@simplr-ai/node 1.1.0 → 1.1.1

package/dist/index.d.ts

@@ -12,6 +12,13 @@ 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). */
@@ -74,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 {
@@ -129,8 +263,13 @@ 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;
@@ -172,6 +311,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;
@@ -299,6 +555,12 @@ 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?;
@@ -314,4 +576,4 @@ declare class Simplr {
     checkBulk(items: CheckInput[]): Promise<BulkResult<CheckResult>>;
 }
 
-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 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 };

package/dist/index.js

@@ -183,7 +183,7 @@ var SimplrFlags = class {
   }
   /** Re-fetch the flag config (counts as one billable request). */
   async refresh() {
-    const path = this.environment ? `/v1/flags?environment=${this.environment}` : "/v1/flags";
+    const path = this.environment ? `/v1/flags?environment=${encodeURIComponent(this.environment)}` : "/v1/flags";
     try {
       const content = await apiRequest(this.cfg, "GET", path);
       const list = content?.flags || [];
@@ -219,6 +219,295 @@ var SimplrFlags = class {
   }
 };
 
+// src/profiles.ts
+var SimplrProfiles = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  /**
+   * Identify a user — creates or updates an anonymous profile and (optionally)
+   * links a device fingerprint. POST /v1/profiles.
+   */
+  identify(externalId, options) {
+    const { profileType, fingerprintHash, ...rest } = options ?? {};
+    const body = {
+      external_id: externalId,
+      profile_type: profileType || "customer",
+      ...rest
+    };
+    if (fingerprintHash) body.fingerprint_hash = fingerprintHash;
+    return apiRequest(this.cfg, "POST", "/v1/profiles", body);
+  }
+  /** Submit an order for real-time fraud scoring. POST /v1/orders. */
+  submitOrder(order) {
+    return apiRequest(this.cfg, "POST", "/v1/orders", order);
+  }
+  /** Get the risk profile for a user. GET /v1/profiles/{externalId}. */
+  getProfileRisk(externalId) {
+    return apiRequest(
+      this.cfg,
+      "GET",
+      `/v1/profiles/${encodeURIComponent(externalId)}`
+    );
+  }
+  /** Report a profile as fraud or legitimate. POST /v1/profiles/{externalId}/outcome. */
+  async reportOutcome(externalId, outcome) {
+    await apiRequest(
+      this.cfg,
+      "POST",
+      `/v1/profiles/${encodeURIComponent(externalId)}/outcome`,
+      { outcome }
+    );
+  }
+};
+
+// src/rum.ts
+var DEFAULT_BATCH_SIZE = 30;
+var DEFAULT_FLUSH_INTERVAL = 1e4;
+var DEFAULT_ENDPOINT = "/v1/rum/events";
+function genId() {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
+}
+var SimplrRUM = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  config = null;
+  initialized = false;
+  queue = [];
+  timer = null;
+  flushing = false;
+  sessionId = null;
+  currentViewId = null;
+  userId;
+  userAttributes;
+  globalAttributes = {};
+  batchSize = DEFAULT_BATCH_SIZE;
+  endpoint = DEFAULT_ENDPOINT;
+  /** Initialize the SDK, start a session, and begin the flush timer. */
+  initialize(config) {
+    if (this.initialized) return;
+    this.config = config;
+    this.batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    this.sessionId = genId();
+    this.initialized = true;
+    this.trackEvent("session_start");
+    const interval = config.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
+    if (interval > 0) {
+      this.timer = setInterval(() => {
+        void this.flush();
+      }, interval);
+      this.timer?.unref?.();
+    }
+  }
+  isInitialized() {
+    return this.initialized;
+  }
+  /** Associate subsequent events with a user. */
+  setUser(userId, attributes) {
+    this.userId = userId;
+    this.userAttributes = attributes;
+  }
+  clearUser() {
+    this.userId = void 0;
+    this.userAttributes = void 0;
+  }
+  addAttribute(key, value) {
+    this.globalAttributes[key] = value;
+  }
+  removeAttribute(key) {
+    delete this.globalAttributes[key];
+  }
+  /** Track a screen/page view. */
+  trackView(name, attributes) {
+    if (!this.initialized) return;
+    this.currentViewId = genId();
+    this.trackEvent("view", {
+      view: { id: this.currentViewId, name },
+      attributes
+    });
+  }
+  /** Track a user action. */
+  trackAction(name, attributes) {
+    if (!this.initialized) return;
+    this.trackEvent("action", { action: { name, type: "custom" }, attributes });
+  }
+  /** Track an error. */
+  trackError(error, attributes) {
+    if (!this.initialized) return;
+    const data = error instanceof Error ? { message: error.message, stack: error.stack, type: error.constructor.name } : error;
+    this.trackEvent("error", { error: data, attributes });
+  }
+  /** Emit a log line. */
+  log(level, message, attributes) {
+    if (!this.initialized) return;
+    this.trackEvent("log", { log: { level, message }, attributes });
+  }
+  trackEvent(type, data) {
+    if (!this.initialized || !this.sessionId) return;
+    const event = {
+      type,
+      timestamp: Date.now(),
+      sessionId: this.sessionId,
+      viewId: this.currentViewId || void 0,
+      userId: this.userId,
+      applicationId: this.config.applicationId,
+      applicationVersion: this.config?.applicationVersion,
+      environment: this.config?.environment,
+      userAttributes: this.userAttributes,
+      globalAttributes: Object.keys(this.globalAttributes).length > 0 ? this.globalAttributes : void 0,
+      ...data
+    };
+    this.queue.push(event);
+    if (this.queue.length >= this.batchSize) void this.flush();
+  }
+  /** Flush queued events to POST /v1/rum/events. */
+  async flush() {
+    if (this.flushing || this.queue.length === 0) return;
+    this.flushing = true;
+    const events = this.queue;
+    this.queue = [];
+    try {
+      await apiRequest(this.cfg, "POST", this.endpoint, {
+        events,
+        sentAt: Date.now()
+      });
+    } catch {
+      this.queue = [...events, ...this.queue];
+    } finally {
+      this.flushing = false;
+    }
+  }
+  /** End the session, flush remaining events, and stop the timer. */
+  async stopSession() {
+    if (!this.initialized) return;
+    this.trackEvent("session_end");
+    await this.flush();
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.initialized = false;
+  }
+  getSessionId() {
+    return this.sessionId;
+  }
+  getViewId() {
+    return this.currentViewId;
+  }
+};
+
+// src/ai.ts
+function mapDelegation(d) {
+  return {
+    delegationId: d.delegation_id,
+    endUserId: d.end_user_id,
+    bindingMode: d.binding_mode,
+    status: d.status,
+    expiresAt: d.expires_at,
+    useCount: d.use_count,
+    lastUsedAt: d.last_used_at,
+    createdAt: d.created_at
+  };
+}
+var SimplrAI = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  /** Create a new AI delegation token for a user. POST /v1/ai/delegations. */
+  async createDelegation(options) {
+    const content = await apiRequest(this.cfg, "POST", "/v1/ai/delegations", {
+      end_user_id: options.userId,
+      end_user_email: options.email,
+      binding: options.binding || "any_location",
+      expires_in_days: options.expiresInDays || 7,
+      session_id: options.sessionId,
+      fingerprint_hash: options.fingerprintHash
+    });
+    const d = content.delegation;
+    return {
+      token: d.token,
+      delegationId: d.delegation_id,
+      expiresAt: d.expires_at,
+      bindingMode: d.binding_mode
+    };
+  }
+  /** Validate (introspect) an AI delegation token. POST /v1/ai/validate. */
+  async validate(token, options) {
+    try {
+      const content = await apiRequest(this.cfg, "POST", "/v1/ai/validate", {
+        token,
+        fingerprint_hash: options?.fingerprintHash,
+        ai_provider: options?.aiProvider,
+        action: options?.action
+      });
+      return {
+        valid: true,
+        sessionType: content.session_type,
+        endUserId: content.end_user_id,
+        delegation: content.delegation ? {
+          delegationId: content.delegation.delegation_id,
+          bindingMode: content.delegation.binding_mode,
+          expiresAt: content.delegation.expires_at,
+          useCount: content.delegation.use_count
+        } : void 0
+      };
+    } catch (err) {
+      return { valid: false, error: err instanceof Error ? err.message : "Validation failed" };
+    }
+  }
+  /** Revoke a delegation. POST /v1/ai/delegations/{id}/revoke. */
+  async revoke(delegationId, reason) {
+    await apiRequest(
+      this.cfg,
+      "POST",
+      `/v1/ai/delegations/${encodeURIComponent(delegationId)}/revoke`,
+      { reason }
+    );
+  }
+  /** List delegations, optionally filtered by user. GET /v1/ai/delegations. */
+  async list(userId) {
+    const path = userId ? `/v1/ai/delegations?end_user_id=${encodeURIComponent(userId)}` : "/v1/ai/delegations";
+    const content = await apiRequest(this.cfg, "GET", path);
+    return (content.delegations || []).map(mapDelegation);
+  }
+  /** Get a single delegation. GET /v1/ai/delegations/{id}. */
+  async get(delegationId) {
+    const content = await apiRequest(
+      this.cfg,
+      "GET",
+      `/v1/ai/delegations/${encodeURIComponent(delegationId)}`
+    );
+    return mapDelegation(content.delegation);
+  }
+  /** Get delegation statistics. GET /v1/ai/stats. */
+  async stats() {
+    const content = await apiRequest(this.cfg, "GET", "/v1/ai/stats");
+    const s = content.stats;
+    return {
+      totalDelegations: s.total_delegations,
+      activeDelegations: s.active_delegations,
+      totalUses: s.total_uses,
+      delegationsByBinding: {
+        verifiedDevice: s.delegations_by_binding.verified_device,
+        anyLocation: s.delegations_by_binding.any_location
+      }
+    };
+  }
+  /** Revoke all delegations for a user (e.g. on logout). POST /v1/ai/revoke-all. */
+  async revokeAllForUser(userId, reason) {
+    const content = await apiRequest(this.cfg, "POST", "/v1/ai/revoke-all", {
+      end_user_id: userId,
+      reason
+    });
+    return content.revoked_count;
+  }
+};
+
 // src/webhooks.ts
 var webhooks_exports = {};
 __export(webhooks_exports, {
@@ -365,6 +654,12 @@ var Simplr = class {
   orders;
   phone;
   edge;
+  /** Anonymous user profiles + order fraud monitoring. */
+  profiles;
+  /** Real User Monitoring — batched events to /v1/rum/events. */
+  rum;
+  /** AI delegation — OAuth-like AI authentication. */
+  ai;
   /** Webhook signature helpers (no network). */
   webhooks = webhooks_exports;
   _flags;
@@ -382,9 +677,13 @@ var Simplr = class {
     this.orders = new OrdersResource(this.cfg);
     this.phone = new PhoneResource(this.cfg);
     this.edge = new EdgeResource(this.cfg);
+    this.profiles = new SimplrProfiles(this.cfg);
+    this.rum = new SimplrRUM(this.cfg);
+    this.ai = new SimplrAI(this.cfg);
     if (options.publicKey) {
       this._flags = new SimplrFlags({
         publicKey: options.publicKey,
+        environment: options.environment,
         baseUrl: this.cfg.baseUrl,
         timeoutMs: this.cfg.timeoutMs,
         fetch: this.cfg.fetchImpl
@@ -415,9 +714,12 @@ var Simplr = class {
 var src_default = Simplr;
 export {
   Simplr,
+  SimplrAI,
   SimplrAdmin,
   SimplrError,
   SimplrFlags,
+  SimplrProfiles,
+  SimplrRUM,
   WebhookVerificationError,
   constructEvent as constructWebhookEvent,
   src_default as default,