loguard-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# loguard-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+JavaScript and TypeScript telemetry for browser applications and Node servers.
+Supports structured logs, page views, explicit actions, exceptions, HTTP outcomes,
+and correlated action timing through Loguard's existing `POST /v1/logs` API.
+
+Requires Node 22+ on the server and a modern browser supporting Fetch,
+AbortController, and Web Crypto. No React or Next.js dependency is required.
+
+```sh
+npm install loguard-sdk
+```
+
+## Browser
+
+Initialize once after the browser application mounts. Imports are SSR-safe;
+calling `createBrowserTelemetry` during SSR is intentionally rejected.
+
+```ts
+import { createBrowserTelemetry } from 'loguard-sdk';
+
+const telemetry = createBrowserTelemetry({
+  collectorUrl: '/api/telemetry',
+  service: 'deel-browser',
+  environment: 'production',
+  release: '2026.10.15',
+  capture: { pageViews: true, errors: true, clicks: true },
+});
+
+telemetry.action('invoice.preview.opened');
+telemetry.page('/invoices/:id'); // Use when automatic page capture is disabled.
+telemetry.captureException(new Error('Invoice preview failed'));
+
+// During application teardown:
+await telemetry.shutdown();
+```
+
+Automatic capture is opt-in. Click capture only observes elements with an
+explicit stable name; it never scrapes text, form values, or input contents:
+
+```html
+<button data-loguard-action="invoice.save.clicked">Save invoice</button>
+```
+
+Page capture follows `pushState`, `replaceState`, and `popstate`. Queries and
+fragments are removed; numeric IDs, UUIDs, email segments, and reset tokens are
+normalized. Supply `normalizeRoute(pathname)` for application-specific routes
+that contain names or other private data. Do not enable both automatic and manual
+page tracking for the same navigation.
+
+The SDK uses a random in-memory session ID for each instance, not an authentication
+cookie or persistent tracking identifier. Browser user IDs are discarded; the
+collector derives identity from the application's authenticated session.
+
+## Server
+
+Keep the ingestion key only in the server's environment. Use your deployed
+ingestion endpoint, including `/v1/logs`; there is no assumed public hostname.
+
+```ts
+import { createServerTelemetry } from 'loguard-sdk/server';
+
+const telemetry = createServerTelemetry({
+  ingestUrl: process.env.LOGUARD_INGEST_URL!,
+  apiKey: process.env.LOGUARD_API_KEY!,
+  service: 'deel-api',
+  environment: 'production',
+});
+
+const invoice = await telemetry.measureAction(
+  'invoice.create',
+  () => persistInvoice(),
+  { operationId: requestOperationId, userId: authenticatedUser.id },
+);
+// Emits invoice.create.started and invoice.create.completed/failed.
+// The original result or thrown error is preserved.
+
+telemetry.request('/api/invoices/:id', {
+  method: 'POST', statusCode: 201, durationMs: 142,
+});
+await telemetry.flush();
+```
+
+`measureAction` considers a resolved operation successful: wrap the committed
+operation, not an earlier button click or a function that resolves with an error
+tuple. Provider acceptance is distinct from eventual email/payment delivery.
+
+Server clients do not create background timers. In serverless handlers, await
+`flush()` or register that promise with the hosting platform's supported
+post-response lifecycle mechanism. A floating `void flush()` is not a durable
+delivery guarantee. Long-lived servers should call `shutdown()` on termination.
+
+## Browser Collector: Next.js App Router
+
+```ts
+// app/api/telemetry/route.ts
+import { createCollector } from 'loguard-sdk/server';
+import { auth } from '@/auth'; // Your existing session implementation.
+
+export const POST = createCollector({
+  ingestUrl: process.env.LOGUARD_INGEST_URL!,
+  apiKey: process.env.LOGUARD_API_KEY!,
+  service: 'deel-browser',
+  environment: 'production',
+  allowedEvents: ['page.viewed', 'application.exception', 'invoice.save.clicked'],
+  authorize: async () => {
+    const session = await auth();
+    return session?.user?.id ? { userId: session.user.id } : null;
+  },
+});
+```
+
+Only the session callback and event allowlist belong to the host app. The SDK
+handles body limits, contract validation, sanitization, trusted context,
+forwarding, timeouts, and partial acknowledgements. The auth import above is
+application-owned; it is not provided by this package.
+
+## Browser Collector: Node / Next.js Pages Router
+
+```ts
+// pages/api/telemetry.ts
+import { createNodeCollector } from 'loguard-sdk/node';
+import { getSession } from '@/session'; // Your existing session implementation.
+
+export const config = { api: { bodyParser: false } };
+
+export default createNodeCollector({
+  publicOrigin: 'https://your-application.example',
+  ingestUrl: process.env.LOGUARD_INGEST_URL!,
+  apiKey: process.env.LOGUARD_API_KEY!,
+  service: 'deel-browser',
+  environment: 'production',
+  allowedEvents: ['page.viewed', 'application.exception', 'invoice.save.clicked'],
+  authorize: async (req, res) => {
+    const session = await getSession(req, res);
+    return session?.user?.id ? { userId: session.user.id } : null;
+  },
+});
+```
+
+`publicOrigin` is explicit so forwarded Host headers cannot determine origin
+policy. Use `bodyParser: false` to enforce SDK byte limits while streaming. The
+adapter also accepts already-parsed JSON, but any earlier parsing limits are then
+the host's responsibility.
+
+Unauthenticated login/signup pages require a separate explicit public policy,
+for example `authorize: () => ({})`, with a small event allowlist and rate limiting.
+Use the optional `rateLimit(request)` callback or your existing platform limiter.
+An Origin check is not authentication and cannot prevent requests from scripts.
+
+## Script Include
+
+The npm artifact also includes `dist/loguard.global.js`, a standalone browser
+bundle. Self-host this file or serve it from a package CDN pinned to the installed
+version, then initialize it after loading:
+
+```html
+<script src="/vendor/loguard.global.js"></script>
+<script>
+  const telemetry = LoguardTelemetry.createBrowserTelemetry({
+    collectorUrl: '/api/telemetry',
+    service: 'website',
+    environment: 'production',
+    capture: { pageViews: true, clicks: true, errors: true }
+  });
+</script>
+```
+
+Keep the API key out of HTML, browser options, and `NEXT_PUBLIC_`/`VITE_` variables.
+The browser client only accepts a same-origin collector URL.
+
+## Documentation
+
+- [API reference](docs/api.md)
+- [Event contract and versioning](docs/contracts.md)
+- [Delivery, security, and operational limits](docs/operations.md)
+
+This is an initial `0.1.0` release. It does not implement a durable browser outbox,
+anomaly detection, or exactly-once storage. SDK acceptance means queued locally;
+an ingestion acknowledgement means durable queue acceptance, not completed
+processing or a successful user operation.

package/dist/chunk-4UI4EGMM.js

@@ -0,0 +1,308 @@
+import {
+  API_VERSION,
+  EVENT_SCHEMA_VERSION,
+  MAX_BATCH_BYTES,
+  MAX_BATCH_EVENTS,
+  MAX_EVENT_BYTES,
+  SDK_VERSION,
+  acknowledgementSchema,
+  eventSchema
+} from "./chunk-ISRLGH43.js";
+
+// src/privacy.ts
+var forbidden = /password|passwd|secret|token|cookie|authorization|api[_-]?key|^email$|^organization_?id$|^app_?id$/i;
+function redactText(text) {
+  return text.replace(/\/reset\/[^\s/?#]+/gi, "/reset/:token").replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, "[redacted]").replace(
+    /\b(?:password|secret|token|authorization|api[_-]?key)\s*[:=]\s*(?:bearer\s+)?[^\s,;}]+/gi,
+    "[redacted]"
+  ).replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "[redacted email]");
+}
+function sanitize(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+  if (depth > 8) throw new Error("Metadata nesting exceeds the SDK limit");
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "string") return redactText(value);
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (!value || typeof value !== "object" || seen.has(value))
+    throw new Error("Metadata must be finite, acyclic JSON");
+  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+    throw new Error("Metadata must contain plain objects");
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (value.length > 100) throw new Error("Metadata array exceeds the SDK limit");
+      return value.map((item) => sanitize(item, depth + 1, seen));
+    }
+    const entries = Object.entries(value);
+    if (entries.length > 64) throw new Error("Metadata object exceeds the SDK limit");
+    return Object.fromEntries(
+      entries.filter(([, item]) => item !== void 0).map(([key, item]) => [
+        key,
+        forbidden.test(key) ? "[redacted]" : sanitize(item, depth + 1, seen)
+      ])
+    );
+  } finally {
+    seen.delete(value);
+  }
+}
+function normalizeRoute(value) {
+  const url = new URL(value, "https://route.invalid");
+  return url.pathname.split("/").map((part, index, parts) => {
+    if (index > 1 && parts[index - 1] === "reset") return ":token";
+    if (/^\d+$/.test(part) || /^[a-f0-9]{8}-[a-f0-9-]{27,}$/i.test(part) || /%40|@/i.test(part) || part.length > 48)
+      return ":id";
+    return part;
+  }).join("/");
+}
+
+// src/client.ts
+function encodeBatch(events) {
+  return JSON.stringify({
+    apiVersion: API_VERSION,
+    eventSchemaVersion: EVENT_SCHEMA_VERSION,
+    events
+  });
+}
+function byteLength(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+var TelemetryClient = class {
+  queue = [];
+  inFlight = null;
+  closed = false;
+  totalAccepted = 0;
+  totalDropped = 0;
+  notifying = false;
+  options;
+  delivery;
+  constructor(options, delivery) {
+    if (!options.service?.trim() || !["development", "staging", "production"].includes(options.environment))
+      throw new Error("A service and valid environment are required");
+    for (const value of [
+      options.maxBufferEvents ?? 500,
+      options.maxAttempts ?? 3,
+      options.timeoutMs ?? 3e3
+    ]) {
+      if (!Number.isInteger(value) || value < 1)
+        throw new Error("SDK limits must be positive integers");
+    }
+    if (!Number.isFinite(options.retryBaseMs ?? 1e3) || (options.retryBaseMs ?? 1e3) < 0)
+      throw new Error("Retry delay must be nonnegative");
+    this.options = { ...options };
+    this.delivery = delivery;
+  }
+  diagnostic(code, count = 1) {
+    if (this.notifying) return;
+    this.notifying = true;
+    try {
+      this.options.onDiagnostic?.({ code, count });
+    } catch {
+    } finally {
+      this.notifying = false;
+    }
+  }
+  track(input) {
+    if (this.closed || this.options.enabled === false) return false;
+    if (this.queue.length >= (this.options.maxBufferEvents ?? 500)) {
+      this.diagnostic("buffer_full");
+      this.totalDropped++;
+      return false;
+    }
+    try {
+      const result = eventSchema.safeParse({
+        ...input,
+        eventSchemaVersion: EVENT_SCHEMA_VERSION,
+        eventId: input.eventId ?? crypto.randomUUID(),
+        timestamp: input.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+        level: input.level ?? "info",
+        message: redactText(input.message ?? input.name),
+        environment: this.options.environment,
+        service: this.options.service,
+        source: this.delivery.source,
+        release: this.options.release,
+        ...input.endpoint ? { endpoint: normalizeRoute(input.endpoint) } : {},
+        ...input.metadata ? { metadata: sanitize(input.metadata) } : {}
+      });
+      if (!result.success || byteLength(JSON.stringify(result.data)) > MAX_EVENT_BYTES)
+        throw new Error("Invalid telemetry event");
+      if (this.queue.some((item) => item.event.eventId === result.data.eventId)) return false;
+      this.queue.push({ event: result.data, attempts: 0, nextAt: 0 });
+      return true;
+    } catch {
+      this.totalDropped++;
+      this.diagnostic("invalid_event");
+      return false;
+    }
+  }
+  log(message, details = {}) {
+    return this.track({ ...details, name: "application.log", eventType: "log", message });
+  }
+  page(route, details = {}) {
+    return this.track({ ...details, name: "page.viewed", eventType: "page_view", endpoint: route });
+  }
+  action(name, details = {}) {
+    return this.track({ ...details, name, eventType: "action" });
+  }
+  request(endpoint, details) {
+    return this.track({
+      ...details,
+      endpoint,
+      name: "http.request.completed",
+      eventType: "request",
+      level: details.level ?? (details.statusCode >= 500 ? "error" : details.statusCode >= 400 ? "warn" : "info")
+    });
+  }
+  async measureAction(name, operation, details = {}) {
+    if (this.closed || this.options.enabled === false) return operation();
+    let operationId;
+    try {
+      operationId = details.operationId ?? crypto.randomUUID();
+    } catch {
+      return operation();
+    }
+    const start = performance.now();
+    this.action(`${name}.started`, { ...details, operationId });
+    try {
+      const result = await operation();
+      this.action(`${name}.completed`, {
+        ...details,
+        operationId,
+        outcome: "success",
+        durationMs: performance.now() - start
+      });
+      return result;
+    } catch (error) {
+      this.action(`${name}.failed`, {
+        ...details,
+        operationId,
+        outcome: "failure",
+        level: "error",
+        durationMs: performance.now() - start
+      });
+      throw error;
+    }
+  }
+  captureException(error, details = {}) {
+    return this.track({
+      ...details,
+      name: "application.exception",
+      eventType: "exception",
+      level: "error",
+      message: error instanceof Error ? error.message : "Unknown application error",
+      metadata: {
+        ...details.metadata,
+        errorName: error instanceof Error ? error.name : "Error",
+        stack: error instanceof Error ? error.stack ?? "" : ""
+      }
+    });
+  }
+  stats() {
+    return { accepted: this.totalAccepted, dropped: this.totalDropped, pending: this.queue.length };
+  }
+  flush() {
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.deliver().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+  async deliver() {
+    while (true) {
+      const batch = [];
+      for (const item of this.queue) {
+        if (item.nextAt > Date.now()) continue;
+        if (batch.length === MAX_BATCH_EVENTS || byteLength(encodeBatch([...batch.map((x) => x.event), item.event])) > MAX_BATCH_BYTES)
+          break;
+        batch.push(item);
+      }
+      if (!batch.length) return this.stats();
+      batch.forEach((item) => item.attempts++);
+      let retryAfter = 0;
+      const accepted = /* @__PURE__ */ new Set();
+      const rejected = /* @__PURE__ */ new Set();
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.options.timeoutMs ?? 3e3);
+      try {
+        const response = await (this.options.fetch ?? globalThis.fetch)(this.delivery.endpoint, {
+          method: "POST",
+          credentials: this.delivery.source === "browser" ? "same-origin" : "omit",
+          headers: {
+            "Content-Type": "application/json",
+            "X-Loguard-SDK-Version": SDK_VERSION,
+            "X-Loguard-Event-Schema": String(EVENT_SCHEMA_VERSION),
+            ...this.delivery.headers
+          },
+          body: encodeBatch(batch.map((item) => item.event)),
+          signal: controller.signal,
+          keepalive: this.delivery.keepalive
+        });
+        const retryHeader = response.headers.get("retry-after");
+        if (retryHeader)
+          retryAfter = Math.min(
+            6e4,
+            Math.max(
+              0,
+              /^\d+$/.test(retryHeader) ? Number(retryHeader) * 1e3 : Date.parse(retryHeader) - Date.now()
+            ) || 0
+          );
+        if (response.status === 202) {
+          const ack = acknowledgementSchema.safeParse(await response.json());
+          if (!ack.success) throw new Error("Invalid acknowledgement");
+          ack.data.accepted.forEach((id) => accepted.add(id));
+          ack.data.rejected.filter((item) => item.code !== "queue_rejected").forEach((item) => {
+            if (item.eventId) rejected.add(item.eventId);
+          });
+        } else if (response.status >= 400 && response.status < 500 && response.status !== 408 && response.status !== 429) {
+          batch.forEach((item) => rejected.add(item.event.eventId));
+        }
+      } catch {
+        this.diagnostic("transport_error", batch.length);
+      } finally {
+        clearTimeout(timer);
+      }
+      const complete = /* @__PURE__ */ new Set();
+      let retry = false;
+      for (const item of batch) {
+        if (accepted.has(item.event.eventId)) {
+          this.totalAccepted++;
+          complete.add(item);
+        } else if (rejected.has(item.event.eventId) || item.attempts >= (this.options.maxAttempts ?? 3)) {
+          this.totalDropped++;
+          complete.add(item);
+          this.diagnostic("dropped");
+        } else {
+          retry = true;
+          const delay = Math.min(
+            3e4,
+            (this.options.retryBaseMs ?? 1e3) * 2 ** (item.attempts - 1)
+          );
+          item.nextAt = Date.now() + Math.max(retryAfter, delay * (0.5 + Math.random()));
+        }
+      }
+      this.queue = this.queue.filter((item) => !complete.has(item));
+      if (retry) return this.stats();
+    }
+  }
+  async shutdown(timeoutMs = 3e3) {
+    this.closed = true;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+      throw new Error("Shutdown timeout must be nonnegative");
+    const deadline = Date.now() + timeoutMs;
+    do {
+      await this.flush();
+      if (!this.queue.length || Date.now() >= deadline) break;
+      await new Promise(
+        (resolve) => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now())))
+      );
+    } while (Date.now() < deadline);
+    return this.stats();
+  }
+};
+
+export {
+  redactText,
+  sanitize,
+  normalizeRoute,
+  encodeBatch,
+  byteLength,
+  TelemetryClient
+};

package/dist/chunk-ISRLGH43.js

@@ -0,0 +1,56 @@
+// src/contracts.ts
+import * as z from "zod";
+var SDK_VERSION = "0.1.0";
+var API_VERSION = "v1";
+var EVENT_SCHEMA_VERSION = 1;
+var MAX_BATCH_EVENTS = 100;
+var MAX_BATCH_BYTES = 60 * 1024;
+var MAX_EVENT_BYTES = 16 * 1024;
+var identifier = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+var eventSchema = z.strictObject({
+  eventSchemaVersion: z.literal(EVENT_SCHEMA_VERSION),
+  eventId: identifier,
+  timestamp: z.iso.datetime({ offset: true }),
+  level: z.enum(["debug", "info", "warn", "error", "critical"]),
+  message: z.string().min(1).max(2048),
+  environment: z.enum(["development", "staging", "production"]),
+  service: z.string().min(1).max(100),
+  source: z.enum(["browser", "server"]),
+  eventType: z.enum(["log", "page_view", "action", "request", "exception", "heartbeat"]),
+  name: z.string().regex(/^[a-z][a-z0-9_.-]{0,99}$/),
+  outcome: z.enum(["success", "failure", "cancelled", "rejected"]).optional(),
+  endpoint: z.string().max(512).optional(),
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]).optional(),
+  statusCode: z.number().int().min(100).max(599).optional(),
+  durationMs: z.number().finite().nonnegative().optional(),
+  operationId: identifier.optional(),
+  requestId: identifier.optional(),
+  traceId: z.string().regex(/^[0-9a-f]{32}$/).optional(),
+  release: z.string().max(128).optional(),
+  userId: z.string().min(1).max(128).optional(),
+  sessionId: z.string().min(1).max(128).optional(),
+  metadata: z.record(z.string().max(100), z.json()).optional()
+});
+var batchSchema = z.strictObject({
+  apiVersion: z.literal(API_VERSION),
+  eventSchemaVersion: z.literal(EVENT_SCHEMA_VERSION),
+  events: z.array(eventSchema).min(1).max(MAX_BATCH_EVENTS)
+});
+var acknowledgementSchema = z.object({
+  accepted: z.array(identifier),
+  rejected: z.array(
+    z.object({ eventId: identifier.optional(), code: z.string(), message: z.string().optional() })
+  )
+});
+
+export {
+  SDK_VERSION,
+  API_VERSION,
+  EVENT_SCHEMA_VERSION,
+  MAX_BATCH_EVENTS,
+  MAX_BATCH_BYTES,
+  MAX_EVENT_BYTES,
+  eventSchema,
+  batchSchema,
+  acknowledgementSchema
+};