@simplr-ai/node 1.0.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!);
@@ -87,6 +87,136 @@ app.post("/hooks/simplify", express.raw({ type: "application/json" }), (req, res
 
 `verify(payload, header, secret, { toleranceSec })` returns a boolean; `constructEvent(...)` returns the parsed event or throws `WebhookVerificationError`.
 
+## Server-side feature flags
+
+Evaluate flags on the backend. Flag config is read with a **public** key (`pk_…`), so pass one alongside your secret key; evaluation is local and deterministic (same bucketing as the browser SDK).
+
+```ts
+const simplr = new Simplr({
+  apiKey: process.env.SIMPLR_API_KEY!,       // sk_… for checks/orders/etc.
+  publicKey: process.env.SIMPLR_PUBLIC_KEY!, // pk_… for flags
+});
+
+await simplr.flags.initialize();
+simplr.flags.setUser("user_123");
+
+if (simplr.flags.isEnabled("new-checkout")) {
+  // gate a backend code path
+}
+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:
+
+```ts
+import { SimplrAdmin } from "@simplr-ai/node";
+
+const admin = new SimplrAdmin({ token: process.env.SIMPLR_PORTAL_TOKEN! });
+
+await admin.usage.stats(orgId);     // usage counters
+await admin.usage.billing(orgId);   // per-service totals + estimated cost (API measurement)
+await admin.flags.create(orgId, { key: "new-checkout", environment: "test", rollout_percentage: 10 });
+await admin.flags.update(orgId, flagId, { rollout_percentage: 50 });
+await admin.rum.overview(orgId, { application_id: "my-app" });
+await admin.rum.sessions(orgId, { page: 1, limit: 50 });
+```
+
 ## Errors
 
 Non-2xx responses throw `SimplrError` with `.status` and `.body`.