@pmate/log-sdk 0.4.0 → 0.5.0

package/README.md

@@ -3,31 +3,73 @@
 ## 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`.
 
 | 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. Other native languages 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 +88,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 +118,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 +153,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/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.5.0",
   "description": "PMate browser, React and Node logs with access and profile context",
   "type": "module",
   "sideEffects": false,
@@ -25,10 +25,14 @@
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
+    },
+    "./event": {
+      "types": "./dist/event.d.ts",
+      "import": "./dist/event.js"
     }
   },
   "dependencies": {
-    "@pmate/log": "0.2.1"
+    "@pmate/log": "0.3.0"
   },
   "peerDependencies": {
     "react": ">=18"