@anomira/node-sdk 0.2.0 → 0.2.2

package/README.md

@@ -38,7 +38,31 @@ ANOMIRA_APP_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 
 ## Express
 
-The middleware goes **after** `express.json()` and **before** your routes so it can read request bodies.
+The middleware goes **after** `express.json()` and **after your auth middleware** so it can read the authenticated user, and **before** your routes.
+
+### How user identity is captured automatically
+
+The SDK automatically extracts the authenticated user ID from the request — no configuration required. It tries the following sources in order:
+
+| Priority | Source | Set by |
+|---|---|---|
+| 1 | `req.user.id` / `.sub` / `.userId` / `._id` / `.uid` | Passport.js, express-jwt v6, Firebase Admin, @fastify/jwt |
+| 2 | `req.auth.sub` / `.id` / `.userId` | express-jwt v7+ |
+| 3 | `req.userId` / `req.accountId` / `req.customerId` | Custom middleware |
+| 4 | `req.session.userId` / `req.session.user.id` | express-session |
+| 5 | JWT decode from `Authorization: Bearer ...` | **Automatic fallback — works even without explicit auth middleware** |
+
+Tier 5 is the safety net: if your auth middleware hasn't set `req.user` yet, the SDK decodes the JWT token in the `Authorization` header itself (without verifying the signature — it only reads the `sub` / `id` claim). This means user tracking works even if middleware registration order is incorrect.
+
+**The only requirement:** if you use a custom auth pattern not listed above, pass `getUserId`:
+
+```ts
+const anomira = new Anomira({
+  apiKey:    process.env.ANOMIRA_API_KEY!,
+  appId:     process.env.ANOMIRA_APP_ID!,
+  getUserId: (req) => (req as any).myCustomField?.userId,
+});
+```
 
 ```ts
 // app.ts (TypeScript)