@simplr-ai/node 1.1.0 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 Simplr's **server-side** SDK for Node.js — run fraud/identity checks, score orders, ingest edge logs, and verify webhook signatures, all with your secret key.
 
-> This is the backend SDK. For client-side device signals, RUM, and feature-flag evaluation use [`@simplr-ai/fraud-sdk`](https://www.npmjs.com/package/@simplr-ai/fraud-sdk) (browser) or `simplify_fraud` (Flutter).
+> This is the backend SDK. For client-side device signals, RUM, and feature-flag evaluation use [`@simplr-ai/js`](https://www.npmjs.com/package/@simplr-ai/js) (browser) or `simplr_fraud` (Flutter).
 
 Docs: https://docs.simplr.so/docs/sdks/node
 
@@ -73,7 +73,7 @@ import { Simplr } from "@simplr-ai/node";
 const simplr = new Simplr({ apiKey: process.env.SIMPLR_API_KEY! });
 const app = express();
 
-app.post("/hooks/simplify", express.raw({ type: "application/json" }), (req, res) => {
+app.post("/hooks/simplr", express.raw({ type: "application/json" }), (req, res) => {
   const sig = req.header("X-Simplr-Signature")!;
   try {
     const event = simplr.webhooks.constructEvent(req.body, sig, process.env.SIMPLR_WEBHOOK_SECRET!);
@@ -106,8 +106,100 @@ if (simplr.flags.isEnabled("new-checkout")) {
 simplr.flags.isEnabled("beta", { userId: "u1", attributes: { plan: "growth" } });
 ```
 
+### Targeting a named environment
+
+`environment` accepts a named environment slug (e.g. `"dev"`, `"uat"`, `"prod"`) as well as the legacy `"live"`/`"test"` key modes. When omitted, the API falls back to the public key's own live/test mode.
+
+```ts
+// On the Simplr client (forwarded to simplr.flags):
+const simplr = new Simplr({ apiKey, publicKey, environment: "uat" });
+
+// Or standalone:
+import { SimplrFlags } from "@simplr-ai/node";
+const flags = new SimplrFlags({ publicKey, environment: "uat" });
+await flags.initialize();
+```
+
 You can also use `SimplrFlags` standalone.
 
+## Profiles (`simplr.profiles`)
+
+Anonymous user profiles + order fraud monitoring. Identify a user, score orders, read a user's risk, and report outcomes back to improve scoring.
+
+```ts
+// Create/update an anonymous profile and (optionally) link a device.
+const { profile, is_new } = await simplr.profiles.identify("user-123", {
+  profileType: "customer",
+  fingerprintHash: "9f2a…", // from a client device-signal collector
+});
+
+// Score an order.
+const result = await simplr.profiles.submitOrder({
+  order_id: "order-1",
+  external_id: "user-123",
+  amount: 4999,
+  currency: "USD",
+});
+
+// Read a user's current risk profile.
+const risk = await simplr.profiles.getProfileRisk("user-123");
+
+// Feed back a confirmed outcome (chargeback, manual review, …).
+await simplr.profiles.reportOutcome("user-123", "fraud"); // or "legitimate"
+```
+
+## RUM (`simplr.rum`)
+
+Server-side Real User Monitoring. Events are batched and flushed to `/v1/rum/events`. The flush timer is installed with `unref()`, so it never keeps your process alive. There is no DOM auto-capture on the server — report views/actions/errors/logs explicitly.
+
+```ts
+simplr.rum.initialize({ applicationId: "my-api", environment: "production" });
+
+simplr.rum.setUser("user-123", { plan: "pro" });
+simplr.rum.addAttribute("region", "eu-west-1");
+
+simplr.rum.trackView("POST /checkout");
+simplr.rum.trackAction("charge_card", { gateway: "stripe" });
+simplr.rum.log("info", "checkout completed", { orderId: "order-1" });
+
+try {
+  // …
+} catch (err) {
+  simplr.rum.trackError(err as Error);
+}
+
+await simplr.rum.flush();        // force a flush
+await simplr.rum.stopSession();  // emit session_end, flush, stop timer
+```
+
+## AI delegation (`simplr.ai`)
+
+OAuth-like AI authentication — mint, validate, and revoke delegation tokens that an end user shares with their AI agent.
+
+```ts
+// Mint a token (only returned once).
+const delegation = await simplr.ai.createDelegation({
+  userId: "user-123",
+  binding: "verified_device",
+  expiresInDays: 7,
+  fingerprintHash: "9f2a…",
+});
+
+// Validate (introspect) an incoming token on your AI gateway.
+const check = await simplr.ai.validate(token, { aiProvider: "anthropic", action: "read_orders" });
+if (!check.valid) { /* reject */ }
+
+// Manage delegations.
+await simplr.ai.list("user-123");
+await simplr.ai.get(delegation.delegationId);
+await simplr.ai.stats();
+await simplr.ai.revoke(delegation.delegationId, "user revoked");
+await simplr.ai.revokeAllForUser("user-123", "logout"); // returns count
+
+```
+
+> The browser SDK's interactive `connect()` popup flow is web-only and is intentionally omitted from the server SDK.
+
 ## Admin / measurement (`SimplrAdmin`)
 
 Dashboard operations — usage/measurement, feature-flag CRUD, and RUM analytics — require a **portal token** (JWT), not an API key:

package/dist/index.cjs

@@ -21,9 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   Simplr: () => Simplr,
+  SimplrAI: () => SimplrAI,
   SimplrAdmin: () => SimplrAdmin,
   SimplrError: () => SimplrError,
   SimplrFlags: () => SimplrFlags,
+  SimplrProfiles: () => SimplrProfiles,
+  SimplrRUM: () => SimplrRUM,
   WebhookVerificationError: () => WebhookVerificationError,
   constructWebhookEvent: () => constructEvent,
   default: () => src_default,
@@ -210,7 +213,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 || [];
@@ -246,6 +249,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, {
@@ -392,6 +684,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;
@@ -409,9 +707,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
@@ -443,9 +745,12 @@ var src_default = Simplr;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Simplr,
+  SimplrAI,
   SimplrAdmin,
   SimplrError,
   SimplrFlags,
+  SimplrProfiles,
+  SimplrRUM,
   WebhookVerificationError,
   constructWebhookEvent,
   verifyWebhook