@pmate/log-sdk 0.4.0 → 0.6.0

package/README.md

@@ -1,33 +1,120 @@
 # @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.
 
-## App and Web APIs
+## 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 |
 | --- | --- | --- | --- |
-| `log.app.append(topic, entry)` / `log.app.captureError(error)` | Program diagnostics, HTTP requests, bot activity, auth, heartbeat, polling, deployment, console, vitals and crashes | `app-logs` | 48 hours |
-| `log.web.pageView()` | Explicit browser page visit, with current pathname and generated page-view ID | `web-logs` | 1 year |
-| `log.web.track(name, properties)` | Explicitly defined user behavior | `web-logs` | 1 year |
+| `log.runtime.append(topic, entry)` / `log.runtime.captureError(error)` | Program diagnostics, HTTP requests, bot activity, auth, heartbeat, polling, deployment, console, vitals and crashes | `app-logs` | 48 hours |
+| `log.event.pageView()` | Explicit browser page visit, with current pathname and generated page-view ID | `web-logs` | 1 year |
+| `log.event.track(name, properties)` | Explicitly defined user behavior | `web-logs` | 1 year |
 
-React exposes both scopes. Node exposes only `app`; `app.append` rejects `pv`
+React exposes both scopes. Node exposes only `runtime`; `runtime.append` rejects `pv`
 and `behavior` topics. Callers cannot set the category or destination chain.
 Retention is enforced by chain configuration, not by the SDK queue.
-Automatic page views use the Web route. Browser errors, console and vitals use
-App even though they originate in the browser. Intake grants must explicitly
+Automatic page views use the Event route. Browser errors, console and vitals use
+Runtime even though they originate in the browser. Intake grants must explicitly
 allow each category/topic pair.
 
 ```tsx
 const log = useLog() // @pmate/log-sdk/react
-log.app.append("application", { data: { event: "sync.failed" } })
-log.web.track("signup.clicked", { button: "signup" })
-log.web.pageView() // use when manually recording a page visit
+log.runtime.append("application", { data: { event: "sync.failed" } })
+log.event.track("signup.clicked", { button: "signup" })
+log.event.pageView() // use when manually recording a page visit
+```
+
+## Public event keys and initialization
+
+Create a log intake key at https://dev.pmate.chat/log-keys. Bind a registered service,
+application, environment, platform, allowed topics and quota. Creation is the only
+provisioning step: there is no per-topic init or manual table creation. Instantiate
+the SDK once per application. The key determines service/environment server-side;
+no user login or account token is needed to append events. It cannot read logs.
+
+```ts
+import { createLogger } from '@pmate/log-sdk/browser'
+const log = createLogger({
+  endpoint: 'https://log-api.pmate.chat',
+  eventKey: 'KEY_FROM_DEVELOPERS', appId: 'pmate:hello',
+})
+log.event.track('signup.clicked', { source: 'home' })
+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. 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.
+
+Web keys may restrict exact HTTP(S) Origins. Native keys need no Origin. Quotas
+are per active intake process (production uses one process); no distributed quota
+is claimed. Disable/rotation writes are confirmed against the Store index before
+success; new requests then reject the old key. In-flight writes may complete.
+Storage errors fail closed. Plaintext keys are returned once; list responses omit
+digests. The current single management writer serializes mutations; deploying
+multiple management writers requires storage-level concurrency control first.
+
+An `eventKey` only sends behavior/PV. Automatic runtime diagnostics require the
+existing scoped `key` plus serviceId/environment; diagnostics are not routed through
+the event key. Both keys can be provided to one browser/React logger.
+
+The SDK now exposes only `runtime` / `event`. Update previous `.app` / `.web`
+call sites before upgrading. Existing static grants and old request categories
+are explicitly translated at legacy HTTP ingress during migration; physical
+`app-logs` / `web-logs` chains and historical rows are unchanged.
+
 ## Identity
 `accessId` is a random tab visit ID. Reload/history restore reuses sessionStorage; a new document navigation starts a visit (including new/duplicated tabs). An SPA route change retains it. After 30 minutes without interaction, the next interaction or explicit event starts another visit. Storage failures fall back to memory. Background vitals do not extend the visit. This is not a persistent visitor ID.
 
@@ -46,7 +133,7 @@ function App({ profileId }) {
 }
 function Content() {
   const log = useLog()
-  return <button onClick={() => log.app.append('application', {data:{event:'feature.opened'}})}>Open</button>
+  return <button onClick={() => log.runtime.append('application', {data:{event:'feature.opened'}})}>Open</button>
 }
 ```
 Keep provider options stable. Initialization happens after mount, is SSR-safe, and suppresses React StrictMode's discarded initialization. Automatic PV/vitals/errors retain the existing browser SDK behavior. `beforeSend` can redact application-specific paths or drop an event. Never include credentials or request/response bodies.
@@ -76,7 +163,7 @@ const log = createLogger({
   endpoint: 'https://log-api.pmate.chat', token: process.env.LOG_INGEST_TOKEN,
 })
 await log.withRequest(request, {profileId: authenticatedProfile?.id}, async scope => {
-  log.app.append('application', {data:{event:'http.request', requestId:scope.requestId}})
+  log.runtime.append('application', {data:{event:'http.request', requestId:scope.requestId}})
   // business work; report completion/error without raw bodies
 })
 await log.close()
@@ -111,7 +198,7 @@ The envelope `id` is the event deduplication key. PV counts pv events; sessions
 ## Error and crash diagnostics
 
 Caught exceptions need explicit reporting; a global rejection listener cannot see
-an exception already handled by application code. Use `log.app.captureError(error,
+an exception already handled by application code. Use `log.runtime.captureError(error,
 { operation: 'chat.send' })` on browser, React and Node loggers. Error records use
 the `error` topic and include bounded message/stack diagnostics with URL queries
 removed. Applications must redact domain-specific sensitive strings before

package/dist/accessTransport.js

@@ -32,7 +32,7 @@ export function createAppAccessLogger(options) {
                     ...(status !== undefined ? { status } : {}), ...(durationMs !== undefined ? { durationMs } : {}),
                     ...(outcome ? { outcome } : {}) } };
             const request = new Request("https://logging.invalid", { headers: { "x-request-id": requestId } });
-            const entry = logger.withRequest(request, {}, () => logger.app.append("application", {
+            const entry = logger.withRequest(request, {}, () => logger.runtime.append("application", {
                 time: safe.time, content: `${method} ${route}${status === undefined ? "" : ` ${status}`}`,
                 data: { ...safe.data, event: safe.type, level: safe.level },
             }));

package/dist/blockchainSink.js

@@ -4,7 +4,7 @@ import { blockchainEndpoint } from "./blockchainEndpoint.js";
 export function createAppLogSink(options) {
     const target = `${blockchainEndpoint(options.blockchainUrl)}/chains/app-logs/logs`;
     return async (batch, signal) => {
-        if (batch.category !== "app")
+        if (batch.category !== "runtime")
             throw Object.assign(Error("App sink rejects web logs"), { retryable: false });
         const logs = batch.items.map(item => {
             const { kind, topic, v, data } = buildLogEnvelope(batch.serviceId, batch.topic, batch.environment, item);

package/dist/browser.d.ts

@@ -9,11 +9,11 @@ export type BrowserLoggerOptions = BrowserLogOptions & {
 export type BrowserLogger = ReturnType<typeof createLogger>;
 /** Own one instance per application document. Server imports never touch window. */
 export declare function createLogger(options: BrowserLoggerOptions): {
-    app: {
+    runtime: {
         append(topic: string, input: LogInput | string): void;
         captureError(error: unknown, context?: Parameters<typeof errorInput>[1]): void;
     };
-    web: {
+    event: {
         pageView(): void;
         track(name: string, properties?: Record<string, unknown>): void;
     };

package/dist/browser.js

@@ -62,10 +62,10 @@ export function createLogger(options) {
         throw error;
     }
     return {
-        app: {
+        runtime: {
             append(topic, input) {
                 if (["pv", "behavior"].includes(topic))
-                    throw Error("PV and behavior require the web API");
+                    throw Error("PV and behavior require the event API");
                 if (!closed) {
                     access.touch();
                     transport.append(topic, input);
@@ -75,7 +75,7 @@ export function createLogger(options) {
                 this.append("error", errorInput(error, context));
             },
         },
-        web: {
+        event: {
             pageView() { if (!closed) {
                 access.touch();
                 transport.pageView();

package/dist/event.d.ts

@@ -0,0 +1,24 @@
+export type EventLoggerOptions = {
+    endpoint: string;
+    eventKey: string;
+    appId: string;
+    platform: "web" | "ios" | "android";
+    accessId?: string;
+    profileId?: string;
+    maxQueue?: number;
+    flushIntervalMs?: number;
+    fetcher?: typeof fetch;
+    onWarning?: (event: {
+        code: "event_dropped";
+        count: number;
+    }) => void;
+};
+/** Fetch-only event client for native JavaScript runtimes and trusted explicit callers. No DOM or Node imports. */
+export declare function createLogger(options: EventLoggerOptions): {
+    event: {
+        track(name: string, properties?: Record<string, unknown>): void;
+        pageView(path: string): void;
+    };
+    flush: () => Promise<void>;
+    close(): Promise<void>;
+};

package/dist/event.js

@@ -0,0 +1,97 @@
+import { redact, validateAppId, validId } from "./shared.js";
+/** Fetch-only event client for native JavaScript runtimes and trusted explicit callers. No DOM or Node imports. */
+export function createLogger(options) {
+    validateAppId(options.appId);
+    const url = new URL(options.endpoint);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))))
+        throw Error("Invalid event endpoint");
+    if (!/^lk_[a-f0-9]{24}_[a-zA-Z0-9_-]{43}$/.test(options.eventKey) || !["web", "ios", "android"].includes(options.platform))
+        throw Error("Invalid event configuration");
+    if ((options.accessId !== undefined && !validId(options.accessId)) || (options.profileId !== undefined && !validId(options.profileId)))
+        throw Error("Invalid event identity");
+    const max = Number.isSafeInteger(options.maxQueue) ? Math.max(1, Math.min(1000, options.maxQueue)) : 200;
+    const queue = [];
+    let closed = false, pending, closePromise;
+    const warn = () => { try {
+        options.onWarning?.({ code: "event_dropped", count: 1 });
+    }
+    catch { /* Best effort. */ } };
+    const append = (topic, data) => {
+        if (closed)
+            return;
+        const entry = { id: crypto.randomUUID(), time: Date.now(), data: redact({ ...data, appId: options.appId, platform: options.platform, ...(options.accessId ? { accessId: options.accessId } : {}), ...(options.profileId ? { profileId: options.profileId } : {}), identitySource: "client" }) };
+        const bytes = new TextEncoder().encode(JSON.stringify(entry)).length;
+        if (bytes > 32000) {
+            warn();
+            return;
+        }
+        if (queue.length >= max) {
+            queue.shift();
+            warn();
+        }
+        queue.push({ topic, entry, attempts: 0, bytes });
+    };
+    const flush = () => {
+        if (pending)
+            return pending;
+        pending = (async () => {
+            let budget = queue.length * 3;
+            while (queue.length && budget > 0) {
+                const topic = queue[0].topic, batch = [];
+                let bytes = 512;
+                for (const item of queue)
+                    if (item.topic === topic && batch.length < 50 && bytes + item.bytes <= 48000) {
+                        batch.push(item);
+                        bytes += item.bytes;
+                    }
+                for (const item of batch) {
+                    queue.splice(queue.indexOf(item), 1);
+                    item.attempts++;
+                }
+                budget -= batch.length;
+                let retry = true;
+                try {
+                    const response = await (options.fetcher ?? fetch)(url.href.replace(/\/$/, "") + "/event/logs/batch", { method: "POST", credentials: "omit", redirect: "error", signal: AbortSignal.timeout(8000), headers: { "Content-Type": "application/json", "x-pmate-log-key": options.eventKey }, body: JSON.stringify({ category: "event", topic, items: batch.map(item => item.entry) }) });
+                    retry = response.status >= 500 || [408, 429].includes(response.status);
+                    if (response.ok) {
+                        const result = await response.json();
+                        retry = result?.success !== true || result?.data?.accepted !== batch.length;
+                    }
+                    else
+                        await response.body?.cancel();
+                }
+                catch { /* Retry original IDs. */ }
+                if (retry)
+                    for (const item of batch) {
+                        if (item.attempts < 3 && queue.length < max)
+                            queue.push(item);
+                        else
+                            warn();
+                    }
+            }
+        })().finally(() => { pending = undefined; });
+        return pending;
+    };
+    const timer = setInterval(() => void flush(), Math.max(1000, options.flushIntervalMs ?? 5000));
+    timer.unref?.();
+    return {
+        event: {
+            track(name, properties = {}) {
+                if (!/^[a-zA-Z0-9_.-]{1,64}$/.test(name))
+                    throw Error("Invalid behavior event");
+                append("behavior", { ...properties, event: name });
+            },
+            pageView(path) {
+                if (!path.startsWith("/") || path.length > 2048 || /[?#]/.test(path))
+                    throw Error("Use a path without query or fragment");
+                append("pv", { path, pageViewId: crypto.randomUUID() });
+            },
+        },
+        flush,
+        close() { if (!closePromise) {
+            closed = true;
+            clearInterval(timer);
+            closePromise = flush();
+        } return closePromise; },
+    };
+}

package/dist/node.d.ts

@@ -1,7 +1,7 @@
 import { errorInput } from "./errors.js";
 import { type LogContext, type LogEntry, type LogInput } from "./shared.js";
 export type LogBatch = {
-    category: "app";
+    category: "runtime";
     serviceId: string;
     environment: string;
     topic: string;
@@ -30,7 +30,7 @@ export type NodeLoggerOptions = {
     }) => void;
 };
 export declare function createLogger(options: NodeLoggerOptions): {
-    app: {
+    runtime: {
         captureError(error: unknown, context?: Parameters<typeof errorInput>[1]): void;
         append(topic: string, input: LogInput | string): {
             id: string;

package/dist/node.js

@@ -59,7 +59,7 @@ export function createLogger(options) {
                 budget -= selected.length;
                 const controller = new AbortController();
                 let timeout;
-                const writing = Promise.resolve().then(() => sink({ category: "app", serviceId: options.serviceId, environment: options.environment, topic, items: selected.map(item => item.entry) }, controller.signal));
+                const writing = Promise.resolve().then(() => sink({ category: "runtime", serviceId: options.serviceId, environment: options.environment, topic, items: selected.map(item => item.entry) }, controller.signal));
                 void writing.then(() => { stalled = false; }, () => { stalled = false; });
                 try {
                     await Promise.race([writing, new Promise((_, reject) => {
@@ -87,13 +87,13 @@ export function createLogger(options) {
     const timer = setInterval(() => { void flush(); }, Math.max(1000, options.flushIntervalMs ?? 5000));
     timer.unref();
     return {
-        app: {
+        runtime: {
             captureError(error, context) {
                 this.append("error", errorInput(error, context));
             },
             append(topic, input) {
                 if (["pv", "behavior"].includes(topic))
-                    throw Error("PV and behavior require the web API");
+                    throw Error("PV and behavior require the event API");
                 if (closing)
                     return;
                 if (!/^[a-z][a-z0-9-]{0,31}$/.test(topic))

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import { Component, type ErrorInfo, type ReactNode } from "react";
 import { type BrowserLogger, type BrowserLoggerOptions } from "./browser.js";
-export type ReactLogger = Pick<BrowserLogger, "app" | "web" | "fetch" | "flush">;
+export type ReactLogger = Pick<BrowserLogger, "runtime" | "event" | "fetch" | "flush">;
 /** Keep options stable for the Provider's lifetime. Update identity through profileId. */
 export declare function LogProvider({ options, profileId, children }: {
     options: Omit<BrowserLoggerOptions, "profileId">;

package/dist/react.js

@@ -16,26 +16,26 @@ export function LogProvider({ options, profileId, children }) {
     const buffered = useRef([]);
     identity.current = profileId;
     const value = useMemo(() => ({
-        web: {
+        event: {
             track(name, properties) {
                 if (!/^[a-zA-Z0-9_.-]{1,64}$/.test(name))
                     throw Error("Invalid behavior event");
                 const profile = identity.current;
-                void ready.promise.then(instance => { instance?.setProfileId(profile); instance?.web.track(name, properties); });
+                void ready.promise.then(instance => { instance?.setProfileId(profile); instance?.event.track(name, properties); });
             },
             pageView() {
                 const profile = identity.current;
-                void ready.promise.then(instance => { instance?.setProfileId(profile); instance?.web.pageView(); });
+                void ready.promise.then(instance => { instance?.setProfileId(profile); instance?.event.pageView(); });
             },
         },
-        app: {
-            captureError(error, context) { value.app.append("error", errorInput(error, context)); },
+        runtime: {
+            captureError(error, context) { value.runtime.append("error", errorInput(error, context)); },
             append(topic, input) {
                 if (["pv", "behavior"].includes(topic))
-                    throw Error("PV and behavior require the web API");
+                    throw Error("PV and behavior require the event API");
                 if (logger.current) {
                     logger.current.setProfileId(identity.current);
-                    logger.current.app.append(topic, input);
+                    logger.current.runtime.append(topic, input);
                 }
                 else {
                     if (buffered.current.length >= 200)
@@ -72,7 +72,7 @@ export function LogProvider({ options, profileId, children }) {
             ready.resolve(instance);
             for (const item of buffered.current.splice(0)) {
                 instance.setProfileId(item.profileId);
-                instance.app.append(item.topic, item.input);
+                instance.runtime.append(item.topic, item.input);
             }
             instance.setProfileId(identity.current);
         });
@@ -103,7 +103,7 @@ export class LogErrorBoundary extends Component {
     static getDerivedStateFromError() { return { failed: true }; }
     componentDidCatch(error, info) {
         try {
-            this.context?.app.append("error", errorInput(error, { operation: "react.render", componentStack: info.componentStack ?? undefined, fatal: true }));
+            this.context?.runtime.append("error", errorInput(error, { operation: "react.render", componentStack: info.componentStack ?? undefined, fatal: true }));
             void this.context?.flush().catch(() => { });
         }
         catch { /* Reporting must not crash the fallback. */ }

package/dist/shared.js

@@ -13,7 +13,7 @@ export function withContext(input, context) {
     const { appId: _app, accessId: _access, profileId: _profile, requestId: _request, identitySource: _source, ...data } = value.data ?? {};
     return { ...value, data: { ...data, ...context, contextVersion: SCHEMA_VERSION } };
 }
-const sensitive = /^(authorization|cookie|setcookie|password|secret|token|accesstoken|refreshtoken|accesskey|apikey|privatekey|requestbody|responsebody)$/i;
+const sensitive = /^(authorization|cookie|setcookie|password|secret|token|accesstoken|refreshtoken|accesskey|apikey|privatekey|eventkey|logkey|requestbody|responsebody)$/i;
 export function redact(value, depth = 0, seen = new WeakSet()) {
     if (value === undefined)
         return undefined;

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/dist/writer.js

@@ -4,7 +4,7 @@ import { redact } from "./shared.js";
 /** Adapt an existing transactional chain appender without changing its commit semantics. */
 export function createAppAppendSink(appendLogs) {
     return async (batch) => {
-        if (batch.category !== "app")
+        if (batch.category !== "runtime")
             throw Object.assign(Error("App sink rejects web logs"), { retryable: false });
         await appendLogs(batch.items.map(entry => buildLogEnvelope(batch.serviceId, batch.topic, batch.environment, entry)));
     };
@@ -24,7 +24,7 @@ export function createAppLogWriter(options) {
         // Validate before invoking a caller's transactional appender.
         for (const entry of entries)
             buildLogEnvelope(options.serviceId, options.topic, options.environment, entry);
-        await options.sink({ category: "app", serviceId: options.serviceId, environment: options.environment, topic: options.topic, items: entries }, AbortSignal.timeout(options.timeoutMs ?? 8000));
+        await options.sink({ category: "runtime", serviceId: options.serviceId, environment: options.environment, topic: options.topic, items: entries }, AbortSignal.timeout(options.timeoutMs ?? 8000));
         if (options.stdout !== false)
             for (const entry of entries) {
                 try {

package/package.json

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