@simplr-ai/node 1.0.0 → 1.1.1

package/dist/index.cjs

@@ -21,7 +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,
@@ -56,7 +61,7 @@ async function apiRequest(cfg, method, path, body) {
       method,
       headers: {
         "Content-Type": "application/json",
-        "X-API-Key": cfg.apiKey
+        ...cfg.authHeaders
       },
       body: body !== void 0 ? JSON.stringify(body) : void 0,
       signal: controller.signal
@@ -137,6 +142,402 @@ var EdgeResource = class {
   }
 };
 
+// src/flags.ts
+function murmurHash3(input, seed = 0) {
+  let h1 = seed;
+  const c1 = 3432918353;
+  const c2 = 461845907;
+  for (let i = 0; i < input.length; i++) {
+    let k1 = input.charCodeAt(i);
+    k1 = Math.imul(k1, c1);
+    k1 = k1 << 15 | k1 >>> 17;
+    k1 = Math.imul(k1, c2);
+    h1 ^= k1;
+    h1 = h1 << 13 | h1 >>> 19;
+    h1 = Math.imul(h1, 5) + 3864292196;
+  }
+  h1 ^= input.length;
+  h1 ^= h1 >>> 16;
+  h1 = Math.imul(h1, 2246822507);
+  h1 ^= h1 >>> 13;
+  h1 = Math.imul(h1, 3266489909);
+  h1 ^= h1 >>> 16;
+  return h1 >>> 0;
+}
+function matchRule(rule, attributes) {
+  const actual = attributes[rule.attribute];
+  switch (rule.op) {
+    case "eq":
+      return String(actual) === rule.value;
+    case "neq":
+      return String(actual) !== rule.value;
+    case "contains":
+      return String(actual ?? "").includes(rule.value);
+    default:
+      return false;
+  }
+}
+var SimplrFlags = class {
+  cfg;
+  environment;
+  refreshIntervalMs;
+  flags = {};
+  defaultUserId;
+  timer = null;
+  ready = false;
+  constructor(options) {
+    if (!options?.publicKey) throw new Error("SimplrFlags: `publicKey` is required");
+    this.cfg = {
+      authHeaders: { "X-API-Key": options.publicKey },
+      baseUrl: (options.baseUrl || "https://api.simplr.sh").replace(/\/+$/, ""),
+      timeoutMs: options.timeoutMs ?? 15e3,
+      fetchImpl: options.fetch ?? globalThis.fetch
+    };
+    this.environment = options.environment;
+    this.refreshIntervalMs = options.refreshIntervalMs ?? 6e4;
+  }
+  /** Fetch the flag config once and start the background refresh. */
+  async initialize() {
+    await this.refresh();
+    this.ready = true;
+    if (this.refreshIntervalMs > 0) {
+      this.timer = setInterval(() => {
+        void this.refresh();
+      }, this.refreshIntervalMs);
+      this.timer?.unref?.();
+    }
+  }
+  /** Set the default identifier used for bucketing when none is passed to isEnabled. */
+  setUser(userId) {
+    this.defaultUserId = userId;
+  }
+  /** Re-fetch the flag config (counts as one billable request). */
+  async refresh() {
+    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 || [];
+      const map = {};
+      for (const f of list) map[f.key] = f;
+      this.flags = map;
+    } catch {
+    }
+  }
+  /** Evaluate a flag locally. Deterministic per user; no network call. */
+  isEnabled(key, ctx = {}) {
+    const f = this.flags[key];
+    if (!f || !f.enabled) return false;
+    const uid = ctx.userId || this.defaultUserId || "anonymous";
+    if (f.target_user_ids?.includes(uid)) return true;
+    if (ctx.attributes && f.rules?.length && f.rules.some((r) => matchRule(r, ctx.attributes))) {
+      return true;
+    }
+    if (f.rollout_percentage >= 100) return true;
+    if (f.rollout_percentage <= 0) return false;
+    return murmurHash3(`${key}:${uid}`) % 100 < f.rollout_percentage;
+  }
+  getAll() {
+    return { ...this.flags };
+  }
+  isReady() {
+    return this.ready;
+  }
+  /** Stop the background refresh timer. */
+  dispose() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+};
+
+// 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, {
@@ -191,6 +592,91 @@ function constructEvent(payload, header, secret, options = {}) {
 }
 var webhooks = { verify, constructEvent };
 
+// src/admin.ts
+function qs(params) {
+  const entries = Object.entries(params).filter(([, v]) => v !== void 0 && v !== null);
+  if (!entries.length) return "";
+  return "?" + entries.map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`).join("&");
+}
+var UsageApi = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  /** Aggregate usage stats for an org. */
+  stats(orgId) {
+    return apiRequest(this.cfg, "GET", `/v1/usage/stats${qs({ org_id: orgId })}`);
+  }
+  /** Raw usage logs for an org. */
+  logs(orgId, params = {}) {
+    return apiRequest(this.cfg, "GET", `/v1/usage/logs${qs({ org_id: orgId, ...params })}`);
+  }
+  /** Billing usage breakdown (per-service totals + estimated cost). */
+  billing(orgId) {
+    return apiRequest(this.cfg, "GET", `/v1/billing/usage${qs({ org_id: orgId })}`);
+  }
+};
+var FlagsAdminApi = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  list(orgId, environment) {
+    return apiRequest(this.cfg, "GET", `/v1/feature-flags${qs({ org_id: orgId, environment })}`);
+  }
+  get(orgId, id) {
+    return apiRequest(this.cfg, "GET", `/v1/feature-flags/${id}${qs({ org_id: orgId })}`);
+  }
+  create(orgId, data) {
+    return apiRequest(this.cfg, "POST", "/v1/feature-flags", { org_id: orgId, ...data });
+  }
+  update(orgId, id, data) {
+    return apiRequest(this.cfg, "PATCH", `/v1/feature-flags/${id}`, { org_id: orgId, ...data });
+  }
+  remove(orgId, id) {
+    return apiRequest(this.cfg, "DELETE", `/v1/feature-flags/${id}${qs({ org_id: orgId })}`);
+  }
+  history(orgId, id, params = {}) {
+    return apiRequest(
+      this.cfg,
+      "GET",
+      `/v1/feature-flags/${id}/history${qs({ org_id: orgId, ...params })}`
+    );
+  }
+};
+var RumApi = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+  }
+  cfg;
+  overview(orgId, params = {}) {
+    return apiRequest(this.cfg, "GET", `/v1/rum/overview${qs({ org_id: orgId, ...params })}`);
+  }
+  sessions(orgId, params = {}) {
+    return apiRequest(this.cfg, "GET", `/v1/rum/sessions${qs({ org_id: orgId, ...params })}`);
+  }
+};
+var SimplrAdmin = class {
+  usage;
+  flags;
+  rum;
+  constructor(options) {
+    if (!options?.token) throw new Error("SimplrAdmin: `token` is required");
+    const cfg = {
+      authHeaders: { Authorization: `Bearer ${options.token}` },
+      baseUrl: (options.baseUrl || "https://api.simplr.sh").replace(/\/+$/, ""),
+      timeoutMs: options.timeoutMs ?? 15e3,
+      fetchImpl: options.fetch ?? globalThis.fetch
+    };
+    if (typeof cfg.fetchImpl !== "function") {
+      throw new Error("SimplrAdmin: no global fetch available \u2014 use Node 18+ or pass `fetch`");
+    }
+    this.usage = new UsageApi(cfg);
+    this.flags = new FlagsAdminApi(cfg);
+    this.rum = new RumApi(cfg);
+  }
+};
+
 // src/index.ts
 var DEFAULT_BASE_URL = "https://api.simplr.sh";
 var Simplr = class {
@@ -198,12 +684,19 @@ 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;
   constructor(options) {
     if (!options?.apiKey) throw new Error("Simplr: `apiKey` is required");
     this.cfg = {
-      apiKey: options.apiKey,
+      authHeaders: { "X-API-Key": options.apiKey },
       baseUrl: (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, ""),
       timeoutMs: options.timeoutMs ?? 15e3,
       fetchImpl: options.fetch ?? globalThis.fetch
@@ -214,6 +707,30 @@ 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
+      });
+    }
+  }
+  /**
+   * 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() {
+    if (!this._flags) {
+      throw new Error(
+        "Simplr.flags requires a `publicKey` \u2014 pass it to `new Simplr({ apiKey, publicKey })`."
+      );
+    }
+    return this._flags;
   }
   /** Run an identity/fraud check. Provide any of email, phone, device, behavior. */
   check(input) {
@@ -228,7 +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