@pmate/log-sdk 0.5.0 → 0.6.0

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/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.0",
   "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"