@pmate/log-sdk 0.5.0 → 0.6.1

package/README.md

@@ -1,12 +1,57 @@
 # @pmate/log-sdk
 
+## Web: initialize once, then report user actions
+
+```ts
+import { web } from '@pmate/log-sdk/web'
+
+web.init({
+  key: 'KEY_FROM_DEVELOPERS',
+  appId: 'pmate:hello',
+  auto: { pv: true, webVitals: true }, // defaults to both enabled
+})
+web.track('signup.clicked', { entry: 'home' })
+web.identify('profile-alice') // optional self-reported profile selection
+web.reset() // clear profile on logout; preserve the anonymous visit
+await web.flush()
+// await web.close() on application teardown, not on every route
+```
+
+Create a Web key with `pv`, `behavior` and `vitals` at https://dev.pmate.chat/log-keys.
+Existing keys retain their original scopes. If your key excludes a topic, disable
+its automatic collection. `web.pageView()` records a manual visit; turn off
+`auto.pv` when your router explicitly records visits to avoid double counting.
+The SDK strips URL query strings/fragments and records available CLS, FCP, INP,
+LCP and TTFB separately from PV. SPA changes never move delayed document metrics
+to a new route. Metrics remain runtime logs (48h); user events remain event logs (1y).
+
+`init` is synchronous local configuration; it makes no registration or login request.
+The default endpoint is `https://log-api.pmate.chat`; an optional `endpoint` supports
+another deployment (HTTPS, or HTTP localhost for tests). Same-configuration init
+is idempotent, changed configuration requires awaiting `close()`. Pre-init calls
+are ignored with a one-time warning. Importing is SSR-safe; initialize in a client
+lifecycle. `createWebLogger()` provides an isolated instance for tests or multiple
+independent applications; normally use the singleton `web`.
+
+Properties/identity are captured at event time. `identify` does not sign in a user,
+and never takes an auth token. The in-memory queue holds 200 entries by default,
+batches at most 50 entries/48 KiB, attempts an entry at most 3 times using the
+original ID/time, and flushes every 5 seconds and on hide. `flush` drains all topics;
+`close` stops listeners/admission and drains. Delivery is best effort; no disk queue.
+Use explicit behavior events; do not send personal data in properties or path names.
+
+Native Swift/Kotlin SDKs in `parrot-native` expose the equivalent
+`PmateLog.initSDK`, `screen`, `track`, `identify`, `reset`, `flush`, `close` API,
+with automatic app foreground/background events. Their examples are generated by
+the Key console for the selected platform.
+
 ## Background
 PMate logs need to connect anonymous page visits, signed-in Profiles and backend requests without merging different Profiles of one Account. This SDK adds access/profile context to the existing topic log protocol. It reuses `@pmate/log` for browser delivery and supports the same ingest protocol or a trusted Store sink on Node.
 
 ## Runtime and Event APIs
 
 Classification follows event meaning, not the runtime or the presence of HTTP.
-The API exposes separate scopes; there is no top-level `append` or `track`.
+The lower-level browser/React APIs expose separate runtime/event scopes. The Web scenario entry provides direct pageView/track methods.
 
 | API | Meaning | Chain | Retention |
 | --- | --- | --- | --- |
@@ -48,7 +93,7 @@ await log.flush()
 
 For native JavaScript clients, use `@pmate/log-sdk/event` with the same options plus
 `platform: 'ios'` or `'android'`. It has no browser/Node dependencies; call
-`log.event.pageView('/screen')` explicitly. Other native languages can POST
+`log.event.pageView('/screen')` explicitly. Custom clients can POST
 `{category:'event',topic:'behavior',items:[{id,time,data:{appId,platform,event}}]}`
 to `/event/logs/batch` with `x-pmate-log-key`. IDs and timestamps must be retained
 on retries. Profile/access IDs are optional untrusted client claims.

package/dist/errors.js

@@ -11,12 +11,30 @@ export function errorInput(error, context = {}) {
         }
     }).slice(0, 4000);
     const value = error instanceof Error ? error : new Error("Non-Error exception");
+    const seen = new Set();
+    const describe = (input, depth = 0) => {
+        if (!input || typeof input !== "object" || depth >= 3 || seen.has(input))
+            return undefined;
+        seen.add(input);
+        const item = input;
+        const diagnostic = {};
+        for (const key of ["source", "stage", "database", "tables", "mode", "attempt"]) {
+            const entry = item.diagnostic?.[key];
+            if (typeof entry === "string")
+                diagnostic[key] = clean(entry);
+            else if (typeof entry === "number" && Number.isFinite(entry))
+                diagnostic[key] = entry;
+        }
+        return { name: clean(item.name ?? "Error"), message: clean(item.message ?? ""), ...(item.stack ? { stack: clean(item.stack) } : {}), ...(Object.keys(diagnostic).length ? { diagnostic } : {}), ...(item.cause ? { cause: describe(item.cause, depth + 1) } : {}), ...(item.inner ? { inner: describe(item.inner, depth + 1) } : {}) };
+    };
+    const details = describe(value);
     return { data: {
             event: context.fatal ? "runtime.crash" : "runtime.error",
             errorName: clean(value.name), message: clean(value.message),
             ...(value.stack ? { stack: clean(value.stack) } : {}),
             ...(context.operation ? { operation: context.operation } : {}),
             ...(context.componentStack ? { componentStack: clean(context.componentStack) } : {}),
+            ...(details ? { errorDetails: details } : {}),
             fatal: context.fatal ?? false,
         } };
 }

package/dist/web.d.ts

@@ -0,0 +1,35 @@
+export type WebLogOptions = {
+    key: string;
+    appId: string;
+    endpoint?: string;
+    /** Automatic page visits (including SPA navigation) and document metrics. Both default to true. */
+    auto?: {
+        pv?: boolean;
+        webVitals?: boolean;
+    };
+    flushIntervalMs?: number;
+    maxQueue?: number;
+};
+/** One lifecycle per browser application. Importing this entry is safe during SSR. */
+export declare function createWebLogger(): {
+    init(options: WebLogOptions): /*elided*/ any;
+    pageView(): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    /** A self-reported profile ID, never a login credential. Applies only to future events. */
+    identify(profileId: string): void;
+    /** Clear profile selection on logout; the anonymous visit remains continuous. */
+    reset(): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+};
+export declare const web: {
+    init(options: WebLogOptions): /*elided*/ any;
+    pageView(): void;
+    track(name: string, properties?: Record<string, unknown>): void;
+    /** A self-reported profile ID, never a login credential. Applies only to future events. */
+    identify(profileId: string): void;
+    /** Clear profile selection on logout; the anonymous visit remains continuous. */
+    reset(): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+};

package/dist/web.js

@@ -0,0 +1,56 @@
+import { createLogger } from "./browser.js";
+const defaults = (options) => ({
+    key: options.key, appId: options.appId, endpoint: options.endpoint ?? "https://log-api.pmate.chat",
+    auto: { pv: options.auto?.pv ?? true, webVitals: options.auto?.webVitals ?? true },
+    flushIntervalMs: options.flushIntervalMs ?? 5000, maxQueue: options.maxQueue ?? 200,
+});
+/** One lifecycle per browser application. Importing this entry is safe during SSR. */
+export function createWebLogger() {
+    let logger;
+    let configuration, closing, warned = false;
+    const current = () => {
+        if (!logger && !warned) {
+            warned = true;
+            console.warn("PMate web log: call init before reporting events.");
+        }
+        return logger;
+    };
+    const api = {
+        init(options) {
+            const config = defaults(options), signature = JSON.stringify(config);
+            if (closing)
+                throw Error("Await web.close() before initializing again");
+            if (logger) {
+                if (configuration !== signature)
+                    throw Error("Web log is already initialized; close before changing configuration");
+                return api;
+            }
+            logger = createLogger({ endpoint: config.endpoint, eventKey: config.key, appId: config.appId,
+                pageViews: config.auto.pv, vitals: config.auto.webVitals, errors: false,
+                flushIntervalMs: config.flushIntervalMs, maxQueue: config.maxQueue });
+            configuration = signature;
+            warned = false;
+            return api;
+        },
+        pageView() { current()?.event.pageView(); },
+        track(name, properties = {}) { current()?.event.track(name, properties); },
+        /** A self-reported profile ID, never a login credential. Applies only to future events. */
+        identify(profileId) { current()?.setProfileId(profileId); },
+        /** Clear profile selection on logout; the anonymous visit remains continuous. */
+        reset() { current()?.setProfileId(null); },
+        flush() { return current()?.flush() ?? Promise.resolve(); },
+        close() {
+            if (closing)
+                return closing;
+            const previous = logger;
+            logger = undefined;
+            configuration = undefined;
+            if (!previous)
+                return Promise.resolve();
+            closing = previous.close().finally(() => { closing = undefined; });
+            return closing;
+        },
+    };
+    return api;
+}
+export const web = createWebLogger();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/log-sdk",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "PMate browser, React and Node logs with access and profile context",
   "type": "module",
   "sideEffects": false,
@@ -29,10 +29,14 @@
     "./event": {
       "types": "./dist/event.d.ts",
       "import": "./dist/event.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js"
     }
   },
   "dependencies": {
-    "@pmate/log": "0.3.0"
+    "@pmate/log": "0.3.1"
   },
   "peerDependencies": {
     "react": ">=18"