@pmate/log-sdk 0.3.0 → 0.5.0

package/README.md

@@ -3,6 +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.
 
+## 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.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 `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 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.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.
 
@@ -21,7 +88,7 @@ function App({ profileId }) {
 }
 function Content() {
   const log = useLog()
-  return <button onClick={() => log.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.
@@ -36,20 +103,49 @@ await log.close()
 ```
 `log.fetch` adds `x-pmate-access-id` and `x-request-id` only to explicitly allowed API origins. It also sends `x-pmate-profile-id` when a profile is selected; this is an untrusted selection claim, not authentication. The server must verify the selected profile belongs to the authenticated account and expected App before passing it to Node context. It refuses redirects on those requests. APIs must allow these headers in CORS. Global fetch is never patched. Only the wrapped requests carry correlation.
 
+## Entry points
+
+React applications report through `@pmate/log-sdk/react`. Node services import
+`createLogger` and transport helpers from `@pmate/log-sdk`. The `/node` export
+remains a compatibility alias. `@pmate/log` is the SDK's internal browser transport;
+applications should not initialize a second logger with it.
+
 ## Node
 ```ts
-import { createLogger } from '@pmate/log-sdk/node'
+import { createLogger } from '@pmate/log-sdk'
 const log = createLogger({
   appId: 'pmate:hello', serviceId: 'pmate:hello-api', environment: 'prod',
   endpoint: 'https://log-api.pmate.chat', token: process.env.LOG_INGEST_TOKEN,
 })
 await log.withRequest(request, {profileId: authenticatedProfile?.id}, async scope => {
-  log.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()
 ```
-Use authenticatedProfile from server authentication, never a client body/header. AsyncLocalStorage isolates concurrent requests and anonymous requests clear inherited identity. Alternatively provide `sink(batch, signal)` backed by existing `@pmate/store`; the sink must preserve item IDs/time, respect cancellation and report acceptance. The queue is bounded, attempts at most three times with the original event ID, reports failures without payloads, and does not block business work. `close()` stops admission and drains outstanding events; telemetry is best effort.
+Use authenticatedProfile from server authentication, never a client body/header. AsyncLocalStorage isolates concurrent requests and anonymous requests clear inherited identity. For private-network writes, use the SDK sink:
+
+```ts
+import { createLogger, createAppLogSink } from "@pmate/log-sdk"
+const log = createLogger({
+  appId: "pmate:hello", serviceId: "pmate:hello-api", environment: "prod",
+  sink: createAppLogSink({
+    blockchainUrl: process.env.BLOCKCHAIN_BASE_URL!, // node01: http://infra01:6801
+    authorization: serviceSigner, // service-owned signature
+    proxyToken: process.env.PMATE_CHAIN_PROXY_TOKEN, // for HTTPS chain-proxy
+  }),
+})
+```
+
+`createAppAccessLogger` and `withFetchAccess` use this same Node logger queue.
+They preserve server request IDs and allowlisted route templates. `createAppLogWriter`
+provides acknowledged `append`/`appendMany` for audit/deployment records; failures
+propagate instead of being silently queued. `createAppAppendSink` adapts an existing
+transactional appender. Do not replace required audit acknowledgement with
+best-effort telemetry. SDK stdout includes the original event ID and
+`logUpload: "application"`, so the collector does not upload it again.
+
+Alternatively provide a custom `sink(batch, signal)`; the sink must preserve item IDs/time, respect cancellation and report acceptance. The queue is bounded, attempts at most three times with the original event ID, reports failures without payloads, and does not block business work. `close()` stops admission and drains outstanding events; telemetry is best effort.
 
 ## Counting
 The envelope `id` is the event deduplication key. PV counts pv events; sessions deduplicate `(appId, accessId)`; Profile UV deduplicates `(appId, profileId)` in a defined time window/topic. Missing identifiers are reported separately. Never count HTTP requests or vitals as page views, or infer first-ever visits from a limited retention window.
@@ -57,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.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.d.ts

@@ -0,0 +1,21 @@
+import { type BlockchainSinkOptions } from "./blockchainSink.js";
+import type { AccessRecord } from "./httpAccess.js";
+/** HTTP records share the Node SDK queue, redaction, IDs and acknowledged sink. */
+export declare function createAppAccessLogger(options: BlockchainSinkOptions & {
+    service: string;
+    env: string;
+    chain?: string;
+    stdout?: (record: AccessRecord & {
+        logUpload: "application";
+        id: string;
+    }) => void;
+    warn?: (event: {
+        type: "access-log-dropped" | "access-log-write-failed";
+        count: number;
+    }) => void;
+    timeoutMs?: number;
+}): {
+    emit(record: AccessRecord): void;
+    flush: () => Promise<void>;
+    close: () => Promise<void>;
+};

package/dist/accessTransport.js

@@ -0,0 +1,49 @@
+import { createLogger } from "./node.js";
+import { createAppLogSink } from "./blockchainSink.js";
+/** HTTP records share the Node SDK queue, redaction, IDs and acknowledged sink. */
+export function createAppAccessLogger(options) {
+    if ((options.chain ?? "app-logs") !== "app-logs")
+        throw Error("Access logs require app-logs");
+    if (!/^[a-zA-Z0-9_.:-]{1,64}$/.test(options.env))
+        throw Error("Invalid log environment");
+    let sink;
+    try {
+        sink = createAppLogSink(options);
+    }
+    catch {
+        throw Error("Invalid access log blockchain endpoint");
+    }
+    const logger = createLogger({ appId: options.service, serviceId: options.service, environment: options.env,
+        sink, stdout: false, maxQueue: 1000, timeoutMs: options.timeoutMs,
+        onWarning(event) {
+            if (event.code === "log_dropped") {
+                try {
+                    (options.warn ?? console.warn)({ type: "access-log-write-failed", count: event.count });
+                }
+                catch { /* Best effort. */ }
+            }
+        },
+    });
+    return {
+        emit(record) {
+            const { requestId, method, route, status, durationMs, outcome } = record.data;
+            const safe = { time: record.time, type: record.type, level: record.level,
+                data: { schemaVersion: 1, service: options.service, env: options.env, requestId, method, route,
+                    ...(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.runtime.append("application", {
+                time: safe.time, content: `${method} ${route}${status === undefined ? "" : ` ${status}`}`,
+                data: { ...safe.data, event: safe.type, level: safe.level },
+            }));
+            if (!entry)
+                return;
+            try {
+                (options.stdout ?? (value => console.info(JSON.stringify(value))))({ ...safe, id: entry.id, logUpload: "application" });
+            }
+            catch { /* Best effort. */ }
+            void logger.flush();
+        },
+        flush: logger.flush, close: logger.close,
+    };
+}

package/dist/blockchainEndpoint.d.ts

@@ -0,0 +1,4 @@
+/** Server-configured destinations only. Public writers use HTTPS chain-proxy;
+ * services on the private network may connect directly to infra01. */
+export declare function blockchainEndpoint(value: string): string;
+export declare function serviceBlockchainUrl(env: Record<string, string | undefined>): string;

package/dist/blockchainEndpoint.js

@@ -0,0 +1,23 @@
+/** Server-configured destinations only. Public writers use HTTPS chain-proxy;
+ * services on the private network may connect directly to infra01. */
+export function blockchainEndpoint(value) {
+    const url = new URL(value);
+    const host = url.hostname;
+    const octets = /^\d+\.\d+\.\d+\.\d+$/.test(host) ? host.split(".").map(Number) : [];
+    const privateIPv4 = octets.length === 4 && octets.every(n => n >= 0 && n <= 255) &&
+        (octets[0] === 10 || (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31) ||
+            (octets[0] === 192 && octets[1] === 168));
+    const internal = privateIPv4 || ["infra01", "localhost", "127.0.0.1", "[::1]"].includes(host);
+    if (url.username || url.password || url.search || url.hash ||
+        (url.protocol !== "https:" && !(url.protocol === "http:" && internal)))
+        throw new Error("Invalid blockchain endpoint: use HTTPS or private-network HTTP without credentials, query or fragment");
+    if (host === "indexer.pmate.chat" && /^\/infra\/blockchain(?:\/|$)/.test(url.pathname))
+        throw new Error("Retired blockchain endpoint: use private infra01 or HTTPS chain-proxy");
+    return url.toString().replace(/\/+$/, "");
+}
+export function serviceBlockchainUrl(env) {
+    const value = env.ACCESS_LOG_BLOCKCHAIN_URL ?? env.BLOCKCHAIN_BASE_URL ?? env.BLOCKCHAIN_ENDPOINT;
+    if (!value)
+        throw new Error("Missing ACCESS_LOG_BLOCKCHAIN_URL or BLOCKCHAIN_BASE_URL");
+    return blockchainEndpoint(value);
+}

package/dist/blockchainSink.d.ts

@@ -0,0 +1,9 @@
+import type { LogBatch } from "./node.js";
+export type BlockchainSinkOptions = {
+    blockchainUrl: string;
+    authorization: (action: "write", chain: string) => string | Promise<string>;
+    proxyToken?: string;
+    fetcher?: typeof fetch;
+};
+/** Encoding and one acknowledged append. The Node logger owns batching/retries. */
+export declare function createAppLogSink(options: BlockchainSinkOptions): (batch: LogBatch, signal: AbortSignal) => Promise<void>;

package/dist/blockchainSink.js

@@ -0,0 +1,32 @@
+import { buildLogEnvelope } from "./logEnvelope.js";
+import { blockchainEndpoint } from "./blockchainEndpoint.js";
+/** Encoding and one acknowledged append. The Node logger owns batching/retries. */
+export function createAppLogSink(options) {
+    const target = `${blockchainEndpoint(options.blockchainUrl)}/chains/app-logs/logs`;
+    return async (batch, signal) => {
+        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);
+            return { kind, topic, v, data };
+        });
+        const authorization = await options.authorization("write", "app-logs");
+        if (!authorization.startsWith("Bearer ") || authorization.length <= 7)
+            throw Object.assign(Error("Log service authorization required"), { retryable: false });
+        const response = await (options.fetcher ?? fetch)(target, {
+            method: "POST", redirect: "error", signal,
+            headers: { Authorization: authorization, "Content-Type": "application/json",
+                ...(options.proxyToken ? { "x-proxy-token": options.proxyToken } : {}) },
+            body: JSON.stringify({ logs }),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw Object.assign(Error("Log append rejected"), {
+                retryable: response.status >= 500 || [408, 429].includes(response.status),
+            });
+        }
+        const receipt = await response.json();
+        if (!receipt.success || receipt.data?.appended !== logs.length || !receipt.data.acceptedAt)
+            throw Error("Log append receipt missing");
+    };
+}

package/dist/browser.d.ts

@@ -9,11 +9,16 @@ 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): {
-    captureError(error: unknown, context?: Parameters<typeof errorInput>[1]): void;
+    runtime: {
+        append(topic: string, input: LogInput | string): void;
+        captureError(error: unknown, context?: Parameters<typeof errorInput>[1]): void;
+    };
+    event: {
+        pageView(): void;
+        track(name: string, properties?: Record<string, unknown>): void;
+    };
     getContext: () => LogContext;
-    track(name: string, properties?: Record<string, unknown>): void;
     setProfileId(value?: string | null): void;
-    append(topic: string, input: LogInput | string): void;
     /** Explicit request wrapper: never patches global fetch or decorates unlisted origins. */
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
     flush: () => Promise<void>;

package/dist/browser.js

@@ -62,14 +62,32 @@ export function createLogger(options) {
         throw error;
     }
     return {
-        captureError(error, context) {
-            this.append("error", errorInput(error, context));
+        runtime: {
+            append(topic, input) {
+                if (["pv", "behavior"].includes(topic))
+                    throw Error("PV and behavior require the event API");
+                if (!closed) {
+                    access.touch();
+                    transport.append(topic, input);
+                }
+            },
+            captureError(error, context) {
+                this.append("error", errorInput(error, context));
+            },
+        },
+        event: {
+            pageView() { if (!closed) {
+                access.touch();
+                transport.pageView();
+            } },
+            track(name, properties = {}) {
+                if (!closed) {
+                    access.touch();
+                    transport.track(name, properties);
+                }
+            },
         },
         getContext: context,
-        track(name, properties = {}) { if (!closed) {
-            access.touch();
-            transport.track(name, properties);
-        } },
         setProfileId(value) {
             if (closed)
                 return;
@@ -82,10 +100,6 @@ export function createLogger(options) {
             access.touch();
             transport.append("application", { data: { event: next ? "identity.identified" : "identity.cleared" } });
         },
-        append(topic, input) { if (!closed) {
-            access.touch();
-            transport.append(topic, input);
-        } },
         /** Explicit request wrapper: never patches global fetch or decorates unlisted origins. */
         fetch(input, init) {
             const url = new URL(input instanceof Request ? input.url : String(input), location.href);

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/fetchAccess.d.ts

@@ -0,0 +1,11 @@
+import { accessRecorder } from "./httpAccess.js";
+export type AccessContext = {
+    requestId: string;
+    /** Set only from the framework's matched route template, never the raw URL. */
+    setRoute(template: string): void;
+};
+/** Wrap the outer Fetch handler, including its error/404 handlers.
+ * Body completion means the runtime consumed the stream, not peer acknowledgement.
+ * Does not inspect, clone or buffer request/response payloads.
+ */
+export declare function withFetchAccess(handler: (request: Request, context: AccessContext) => Response | Promise<Response>, options: Parameters<typeof accessRecorder>[0]): (request: Request) => Promise<Response>;

package/dist/fetchAccess.js

@@ -0,0 +1,91 @@
+import { accessRecorder } from "./httpAccess.js";
+/** Wrap the outer Fetch handler, including its error/404 handlers.
+ * Body completion means the runtime consumed the stream, not peer acknowledgement.
+ * Does not inspect, clone or buffer request/response payloads.
+ */
+export function withFetchAccess(handler, options) {
+    const recorder = accessRecorder(options);
+    return async (request) => {
+        const record = recorder.start(request.method, request.headers.get("x-request-id"));
+        let route, status = 499, finished = false;
+        let cancelBody;
+        const finish = (outcome) => {
+            if (finished)
+                return;
+            finished = true;
+            request.signal.removeEventListener("abort", abort);
+            record.finish(status, route, outcome);
+        };
+        const abort = () => { finish("aborted"); cancelBody?.(); };
+        request.signal.addEventListener("abort", abort, { once: true });
+        if (request.signal.aborted)
+            abort();
+        try {
+            const response = await handler(request, { requestId: record.requestId, setRoute(value) { route = value; } });
+            status = response.status;
+            const headers = new Headers(response.headers);
+            headers.set("x-request-id", record.requestId);
+            if (!response.body) {
+                finish("response");
+                return new Response(null, { status, statusText: response.statusText, headers });
+            }
+            const reader = response.body.getReader();
+            let ended = false;
+            const stop = async (reason) => {
+                if (ended)
+                    return;
+                ended = true;
+                try {
+                    await reader.cancel(reason);
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            };
+            const body = new ReadableStream({
+                start(controller) {
+                    cancelBody = () => {
+                        if (ended)
+                            return;
+                        controller.error(new DOMException("Request aborted", "AbortError"));
+                        void stop().catch(() => { });
+                    };
+                    if (request.signal.aborted)
+                        cancelBody();
+                },
+                async pull(controller) {
+                    if (ended)
+                        return;
+                    try {
+                        const result = await reader.read();
+                        if (ended)
+                            return;
+                        if (result.done) {
+                            ended = true;
+                            reader.releaseLock();
+                            controller.close();
+                            finish("response");
+                        }
+                        else
+                            controller.enqueue(result.value);
+                    }
+                    catch (error) {
+                        if (ended)
+                            return;
+                        ended = true;
+                        reader.releaseLock();
+                        controller.error(error);
+                        finish("error");
+                    }
+                },
+                async cancel(reason) { finish("aborted"); await stop(reason); },
+            }, { highWaterMark: 0 });
+            return new Response(body, { status, statusText: response.statusText, headers });
+        }
+        catch (error) {
+            status = 500;
+            finish("error");
+            throw error;
+        }
+    };
+}

package/dist/httpAccess.d.ts

@@ -0,0 +1,30 @@
+export type AccessRecord = {
+    time: number;
+    type: "http.request" | "http.access";
+    level: "info" | "warn" | "error";
+    data: {
+        schemaVersion: 1;
+        service: string;
+        env: string;
+        requestId: string;
+        method: string;
+        route: string;
+        status?: number;
+        durationMs?: number;
+        outcome?: "response" | "error" | "aborted";
+    };
+};
+/** Only accepts server-configured route templates; never pass request.pathname. */
+export declare function accessRecorder(options: {
+    service: string;
+    env: string;
+    routes: string[];
+    emit: (record: AccessRecord) => void;
+    now?: () => number;
+    monotonic?: () => number;
+}): {
+    start(method: string, upstreamRequestId?: string | null): {
+        requestId: string;
+        finish(status: number, route?: string, outcome?: "response" | "error" | "aborted"): void;
+    };
+};

package/dist/httpAccess.js

@@ -0,0 +1,30 @@
+/** Only accepts server-configured route templates; never pass request.pathname. */
+export function accessRecorder(options) {
+    const now = options.now ?? Date.now;
+    const monotonic = options.monotonic ?? (() => performance.now());
+    const routes = new Set(options.routes);
+    const emit = (record) => { try {
+        options.emit(record);
+    }
+    catch { /* Observability cannot fail a request. */ } };
+    return {
+        start(method, upstreamRequestId) {
+            const started = monotonic();
+            const data = { schemaVersion: 1, service: options.service, env: options.env,
+                requestId: upstreamRequestId && /^(?:[a-fA-F0-9]{32}|[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$/.test(upstreamRequestId) ? upstreamRequestId : crypto.randomUUID(), method: /^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|CONNECT|TRACE)$/.test(method) ? method : "OTHER", route: "pending" };
+            // Completion records retain request outcome without doubling every request.
+            let finished = false;
+            return {
+                requestId: data.requestId,
+                finish(status, route, outcome = "response") {
+                    if (finished)
+                        return;
+                    finished = true;
+                    const code = Number.isInteger(status) && status >= 100 && status <= 599 ? status : 500;
+                    emit({ time: now(), type: "http.access", level: code >= 500 || outcome === "error" ? "error" : code >= 400 || outcome === "aborted" ? "warn" : "info",
+                        data: { ...data, route: route && routes.has(route) ? route : "unmatched", status: code, durationMs: Math.max(0, monotonic() - started), outcome } });
+                },
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./shared.js";
+export * from "./node.js";
+export * from "./blockchainEndpoint.js";
+export * from "./blockchainSink.js";
+export * from "./httpAccess.js";
+export * from "./fetchAccess.js";
+export * from "./accessTransport.js";
+export * from "./writer.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./shared.js";
+export * from "./node.js";
+export * from "./blockchainEndpoint.js";
+export * from "./blockchainSink.js";
+export * from "./httpAccess.js";
+export * from "./fetchAccess.js";
+export * from "./accessTransport.js";
+export * from "./writer.js";

package/dist/logEnvelope.d.ts

@@ -0,0 +1,20 @@
+import { type LogEntry } from "./shared.js";
+/** AppLog's version-1 StdTable wire format. This module has no Store runtime
+ * dependency, so the published Node SDK also works in standard Node.js. */
+export declare function buildLogEnvelope(serviceId: string, topic: string, environment: string, entry: LogEntry): {
+    kind: 10000;
+    topic: string;
+    v: number;
+    data: {
+        type: "create";
+        after: {
+            data?: Record<string, unknown> | undefined;
+            content?: string | undefined;
+            id: string;
+            time: number;
+            serviceId: string;
+            topic: string;
+            environment: string;
+        };
+    };
+};

package/dist/logEnvelope.js

@@ -0,0 +1,25 @@
+import { redact } from "./shared.js";
+/** AppLog's version-1 StdTable wire format. This module has no Store runtime
+ * dependency, so the published Node SDK also works in standard Node.js. */
+export function buildLogEnvelope(serviceId, topic, environment, entry) {
+    const parts = /^([a-z0-9][a-z0-9-]*):([a-z0-9][a-z0-9_-]*)$/.exec(serviceId);
+    const name = parts ? `logs_${parts[2]}_${topic}` : "";
+    if (!parts || parts[1].length > 30 || name.length > 63 ||
+        !/^[a-z][a-z0-9-]{0,31}$/.test(topic) || ["pv", "behavior"].includes(topic))
+        throw Object.assign(Error("Invalid application log service/topic"), { retryable: false });
+    if (!/^[a-zA-Z0-9_.:-]{1,64}$/.test(environment) ||
+        !entry.id || entry.id.length > 256 || entry.id.includes("\0") ||
+        !Number.isSafeInteger(entry.time) || entry.time < 0)
+        throw Object.assign(Error("Invalid log environment or identity"), { retryable: false });
+    if ((entry.content !== undefined && typeof entry.content !== "string") ||
+        (entry.data !== undefined && (!entry.data || typeof entry.data !== "object" || Array.isArray(entry.data))) ||
+        (!entry.content?.trim() && entry.data === undefined))
+        throw Object.assign(Error("Invalid log content/data"), { retryable: false });
+    const row = { id: entry.id, time: entry.time, serviceId, topic, environment,
+        ...(entry.content !== undefined ? { content: entry.content } : {}),
+        ...(entry.data !== undefined ? { data: redact(entry.data) } : {}) };
+    const data = { type: "create", after: row };
+    if (new TextEncoder().encode(JSON.stringify(data)).length > 64 * 1024)
+        throw Object.assign(Error("Log exceeds 64 KiB"), { retryable: false });
+    return { kind: 10000, topic: `@${parts[1]}/${name}`, v: 1, data };
+}

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;
@@ -17,19 +17,31 @@ export type NodeLoggerOptions = {
     sink?: (batch: LogBatch, signal: AbortSignal) => Promise<void>;
     maxQueue?: number;
     flushIntervalMs?: number;
+    timeoutMs?: number;
+    stdout?: false | ((entry: LogEntry & {
+        serviceId: string;
+        environment: string;
+        topic: string;
+        logUpload: "application";
+    }) => void);
     onWarning?: (event: {
         code: "log_dropped" | "log_send_failed";
         count: number;
     }) => void;
 };
 export declare function createLogger(options: NodeLoggerOptions): {
-    captureError(error: unknown, context?: Parameters<typeof errorInput>[1]): void;
+    runtime: {
+        captureError(error: unknown, context?: Parameters<typeof errorInput>[1]): void;
+        append(topic: string, input: LogInput | string): {
+            id: string;
+            time: number;
+        } | undefined;
+    };
     getContext: () => LogContext;
     /** verifiedProfile comes from server authentication, never request headers/body. */
     withRequest<T>(request: Request, verifiedProfile: {
         profileId?: string | null;
     }, run: (scope: LogContext) => T): T;
-    append(topic: string, input: LogInput | string): void;
     flush: () => Promise<void>;
     close(): Promise<void>;
 };

package/dist/node.js

@@ -4,6 +4,9 @@ import { randomUUID } from "node:crypto";
 import { ACCESS_HEADER, REQUEST_HEADER, redact, validId, validateAppId, withContext } from "./shared.js";
 export function createLogger(options) {
     validateAppId(options.appId);
+    const timeoutMs = options.timeoutMs ?? 8000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
+        throw Error("Invalid log timeout");
     if (!/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9_-]*$/.test(options.serviceId) || !/^[a-zA-Z0-9_.:-]{1,64}$/.test(options.environment))
         throw Error("Invalid service or environment");
     const endpoint = options.endpoint ? new URL(options.endpoint) : undefined;
@@ -56,11 +59,11 @@ 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) => {
-                            timeout = setTimeout(() => { stalled = true; controller.abort(); reject(Error("Log sink timed out")); }, 8000);
+                            timeout = setTimeout(() => { stalled = true; controller.abort(); reject(Error("Log sink timed out")); }, timeoutMs);
                         })]);
                 }
                 catch (error) {
@@ -84,8 +87,43 @@ export function createLogger(options) {
     const timer = setInterval(() => { void flush(); }, Math.max(1000, options.flushIntervalMs ?? 5000));
     timer.unref();
     return {
-        captureError(error, context) {
-            this.append("error", errorInput(error, context));
+        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 event API");
+                if (closing)
+                    return;
+                if (!/^[a-z][a-z0-9-]{0,31}$/.test(topic))
+                    throw Error("Invalid topic");
+                try {
+                    const value = withContext(input, context.getStore() ?? anonymous);
+                    const entry = { id: randomUUID(), time: value.time ?? Date.now(),
+                        ...(value.content !== undefined ? { content: redact(value.content) } : {}), data: redact(value.data) };
+                    const bytes = new TextEncoder().encode(JSON.stringify(entry)).length;
+                    if (!Number.isSafeInteger(entry.time) || entry.time < 0 || bytes > 32000) {
+                        warn("log_dropped", 1);
+                        return;
+                    }
+                    if (queue.length >= maxQueue) {
+                        queue.shift();
+                        warn("log_dropped", 1);
+                    }
+                    queue.push({ topic, entry, bytes, attempts: 0 });
+                    if (options.stdout !== false) {
+                        try {
+                            (options.stdout ?? (value => console.info(JSON.stringify(value))))({ ...entry, serviceId: options.serviceId, environment: options.environment, topic, logUpload: "application" });
+                        }
+                        catch { /* Logging cannot fail business work. */ }
+                    }
+                    return { id: entry.id, time: entry.time };
+                }
+                catch {
+                    warn("log_dropped", 1);
+                }
+            },
         },
         getContext: () => context.getStore() ?? anonymous,
         /** verifiedProfile comes from server authentication, never request headers/body. */
@@ -98,30 +136,6 @@ export function createLogger(options) {
                 requestId: validId(requestId) ? requestId : randomUUID(), identitySource: verifiedProfile.profileId ? "authenticated" : "anonymous" };
             return context.run(scope, () => run(scope));
         },
-        append(topic, input) {
-            if (closing)
-                return;
-            if (!/^[a-z][a-z0-9-]{0,31}$/.test(topic))
-                throw Error("Invalid topic");
-            try {
-                const value = withContext(input, context.getStore() ?? anonymous);
-                const entry = { id: randomUUID(), time: value.time ?? Date.now(),
-                    ...(value.content !== undefined ? { content: redact(value.content) } : {}), data: redact(value.data) };
-                const bytes = new TextEncoder().encode(JSON.stringify(entry)).length;
-                if (!Number.isSafeInteger(entry.time) || entry.time < 0 || bytes > 32000) {
-                    warn("log_dropped", 1);
-                    return;
-                }
-                if (queue.length >= maxQueue) {
-                    queue.shift();
-                    warn("log_dropped", 1);
-                }
-                queue.push({ topic, entry, bytes, attempts: 0 });
-            }
-            catch {
-                warn("log_dropped", 1);
-            }
-        },
         flush,
         async close() { closing = true; clearInterval(timer); await flush(); if (queue.length && !stalled)
             await flush(); if (queue.length) {

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, "append" | "fetch" | "flush" | "captureError" | "track">;
+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,22 +16,33 @@ export function LogProvider({ options, profileId, children }) {
     const buffered = useRef([]);
     identity.current = profileId;
     const value = useMemo(() => ({
-        track(name, properties) {
-            if (!/^[a-zA-Z0-9_.-]{1,64}$/.test(name))
-                throw Error("Invalid behavior event");
-            void ready.promise.then(instance => { instance?.setProfileId(identity.current); instance?.track(name, properties); });
+        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?.event.track(name, properties); });
+            },
+            pageView() {
+                const profile = identity.current;
+                void ready.promise.then(instance => { instance?.setProfileId(profile); instance?.event.pageView(); });
+            },
         },
-        captureError(error, context) { value.append("error", errorInput(error, context)); },
-        append(topic, input) {
-            if (logger.current) {
-                logger.current.setProfileId(identity.current);
-                logger.current.append(topic, input);
-            }
-            else {
-                if (buffered.current.length >= 200)
-                    buffered.current.shift();
-                buffered.current.push({ topic, input, profileId: identity.current });
-            }
+        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 event API");
+                if (logger.current) {
+                    logger.current.setProfileId(identity.current);
+                    logger.current.runtime.append(topic, input);
+                }
+                else {
+                    if (buffered.current.length >= 200)
+                        buffered.current.shift();
+                    buffered.current.push({ topic, input, profileId: identity.current });
+                }
+            },
         },
         async fetch(input, init) {
             const instance = logger.current ?? await ready.promise;
@@ -61,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.append(item.topic, item.input);
+                instance.runtime.append(item.topic, item.input);
             }
             instance.setProfileId(identity.current);
         });
@@ -92,7 +103,7 @@ export class LogErrorBoundary extends Component {
     static getDerivedStateFromError() { return { failed: true }; }
     componentDidCatch(error, info) {
         try {
-            this.context?.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,8 +13,10 @@ 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;
     if (typeof value === "string")
         return value.slice(0, 4000).replace(/\bBearer\s+[^\s,;]+/gi, "Bearer [redacted]");
     if (value === null || typeof value === "boolean" || typeof value === "number")

package/dist/writer.d.ts

@@ -0,0 +1,22 @@
+import { buildLogEnvelope } from "./logEnvelope.js";
+import { type LogInput } from "./shared.js";
+import type { LogBatch, NodeLoggerOptions } from "./node.js";
+export type LogWriteInput = LogInput & {
+    id?: string;
+};
+export type LogSink = (batch: LogBatch, signal: AbortSignal) => Promise<void>;
+/** Adapt an existing transactional chain appender without changing its commit semantics. */
+export declare function createAppAppendSink(appendLogs: (logs: ReturnType<typeof buildLogEnvelope>[]) => Promise<void>): LogSink;
+/** Explicit acknowledgement for audit/deployment writes. Errors propagate to
+ * the caller; ordinary best-effort telemetry should use createLogger instead. */
+export declare function createAppLogWriter(options: {
+    serviceId: string;
+    environment: string;
+    topic: string;
+    sink: LogSink;
+    timeoutMs?: number;
+    stdout?: NodeLoggerOptions["stdout"];
+}): {
+    appendMany: (inputs: (LogWriteInput | string)[]) => Promise<void>;
+    append: (input: LogWriteInput | string) => Promise<void>;
+};

package/dist/writer.js

@@ -0,0 +1,38 @@
+import { randomUUID } from "node:crypto";
+import { buildLogEnvelope } from "./logEnvelope.js";
+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 !== "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)));
+    };
+}
+/** Explicit acknowledgement for audit/deployment writes. Errors propagate to
+ * the caller; ordinary best-effort telemetry should use createLogger instead. */
+export function createAppLogWriter(options) {
+    const appendMany = async (inputs) => {
+        if (!inputs.length)
+            return;
+        const entries = inputs.map(input => {
+            const value = typeof input === "string" ? { content: input } : input;
+            return { id: value.id ?? randomUUID(), time: value.time ?? Date.now(),
+                ...(value.content !== undefined ? { content: redact(value.content) } : {}),
+                ...(value.data !== undefined ? { data: redact(value.data) } : {}) };
+        });
+        // 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: "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 {
+                    (options.stdout ?? (row => console.info(JSON.stringify(row))))({ ...entry, serviceId: options.serviceId,
+                        environment: options.environment, topic: options.topic, logUpload: "application" });
+                }
+                catch { /* Best effort stdout. */ }
+            }
+    };
+    return { appendMany, append: (input) => appendMany([input]) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/log-sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "PMate browser, React and Node logs with access and profile context",
   "type": "module",
   "sideEffects": false,
@@ -10,8 +10,9 @@
   ],
   "exports": {
     ".": {
-      "types": "./dist/shared.d.ts",
-      "import": "./dist/shared.js"
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "default": "./dist/shared.js"
     },
     "./browser": {
       "types": "./dist/browser.d.ts",
@@ -24,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.0"
+    "@pmate/log": "0.3.0"
   },
   "peerDependencies": {
     "react": ">=18"