nuxt-observe 0.0.2

package/dist/runtime/shared/schema/tiers.d.ts

@@ -0,0 +1,5 @@
+import type { CanonicalEvent } from './event.js';
+export declare const PROGRESSIVE_TIERS: readonly ["stream", "grouping", "journey", "activity", "rollout"];
+export type Tier = (typeof PROGRESSIVE_TIERS)[number];
+/** Which tiers a given event satisfies. `stream` is always included for a valid event. */
+export declare function classifyTiers(event: CanonicalEvent): Tier[];

package/dist/runtime/shared/schema/tiers.js

@@ -0,0 +1,9 @@
+export const PROGRESSIVE_TIERS = ["stream", "grouping", "journey", "activity", "rollout"];
+export function classifyTiers(event) {
+  const tiers = ["stream"];
+  if (event.error) tiers.push("grouping");
+  if (event.trace?.traceId) tiers.push("journey");
+  if (event.session || event.route || event.feature) tiers.push("activity");
+  if (event.source?.version) tiers.push("rollout");
+  return tiers;
+}

package/dist/runtime/shared/types/module-options.d.ts

@@ -0,0 +1,119 @@
+import type { ServiceSeed, GroupSeed } from '../schema/registry.js';
+import type { ObserveUser } from '../auth/schema.js';
+export interface ModuleOptions {
+    /** Dashboard mount path. @default '/observe' */
+    prefix?: string;
+    /** Log/metric retention window in days. @default 30 */
+    retentionDays?: number;
+    /** SQLite storage location (relative to project root). */
+    database?: {
+        /** @default '.data/observe.sqlite3' */
+        path?: string;
+    };
+    /** Service registry seed: upserted by slug at boot. */
+    services?: ServiceSeed[];
+    /** Group seed: upserted by slug at boot. */
+    groups?: GroupSeed[];
+    /** Ingest endpoint tuning. */
+    ingest?: {
+        /**
+         * Public base URL of this dashboard's ingest endpoint, for reverse-proxied installs
+         * where the request host differs from the URL clients should POST to. Used to build
+         * the copy-paste key snippet. Falls back to the request origin when unset.
+         */
+        ingestBaseUrl?: string;
+        /** Max request bytes (content-length) before 413. @default 1048576 (1 MiB) */
+        maxBytes?: number;
+        /** Max events per batch before 413 (canonical cap rides zod at 500). @default 500 */
+        maxEvents?: number;
+        /**
+         * CORS policy for the public ingest routes. Per-service `kind`/`allowedOrigins`
+         * drive the origin dynamically; these values are the fallback when a request
+         * resolves no browser service. `origin` defaults to `[]` (no cross-origin grant
+         * unless a service opts in); set `'*'` to restore a global collector.
+         */
+        cors?: {
+            origin?: string | string[];
+            methods?: string[];
+            allowHeaders?: string[];
+            maxAge?: string;
+        };
+        /** Optional per-service ingest rate limit (in-memory token bucket). Off unless set. */
+        rateLimit?: {
+            perServicePerMinute?: number;
+            burst?: number;
+        };
+    };
+    /**
+     * Phase-1 auth (CP5). Provider selection + config-seeded dashboard users.
+     * `users` is the single, unified user seed surface — it powers the config
+     * provider now and, in CP16, seeds the DB-provider's gated bootstrap-admin
+     * fallback (see src/runtime/shared/auth/roles.ts). There is no separate
+     * top-level `users` list.
+     */
+    auth?: {
+        /** @default 'config' */
+        provider?: 'config' | 'db' | 'jwt';
+        /** Config-seeded users, validated with observeUserSchema at build time. */
+        users?: ObserveUser[];
+        /**
+         * External-JWT VERIFICATION config (CP16). Verify only, never issue. Secrets live in
+         * server-only runtimeConfig, backed by env (NUXT_OBSERVE_AUTH_JWT_SECRET /
+         * NUXT_OBSERVE_AUTH_JWT_PUBLIC_KEY). When `enabled`, a valid `Authorization: Bearer`
+         * token authenticates any /api/observe/* route statelessly, regardless of `provider`.
+         */
+        jwt?: {
+            /** Turns the Bearer fallback + the `jwt` provider on. @default false */
+            enabled?: boolean;
+            /** Accepted signing algorithms. @default ['HS256'] */
+            algorithms?: Array<'HS256' | 'RS256'>;
+            /** HS256 shared secret (or via NUXT_OBSERVE_AUTH_JWT_SECRET). */
+            secret?: string;
+            /** RS256 SPKI public key (or via NUXT_OBSERVE_AUTH_JWT_PUBLIC_KEY). */
+            publicKey?: string;
+            /** RS256 remote JWKS endpoint (alternative to a static publicKey). */
+            jwksUri?: string;
+            issuer?: string;
+            audience?: string;
+            /** Clock-skew allowance, e.g. '60s'. */
+            clockTolerance?: string;
+            /** Claim carrying the role. @default 'observe_role' */
+            roleClaim?: string;
+            /** Claim carrying the subject. @default 'sub' */
+            subjectClaim?: string;
+            /** Claim carrying the { services, groups } slug assignment (token source). @default 'observe_assignment' */
+            assignmentsClaim?: string;
+            /** Maps a raw role claim value to an observe Role. Unmapped => 'viewer'. */
+            roleMap?: Record<string, 'admin' | 'manager' | 'viewer'>;
+            /** Where role/assignment come from: the token itself, or the DB identity it maps to. @default 'token' */
+            claimsSource?: 'token' | 'db';
+        };
+        /** Optional session cookie overrides passed to nuxt-auth-utils. */
+        session?: {
+            maxAge?: number;
+            name?: string;
+        };
+    };
+}
+export declare const DEFAULT_PREFIX = "/observe";
+export declare const OBSERVE_API_BASE = "/api/observe";
+export declare const OBSERVE_INGEST_ROUTE = "/api/observe/ingest";
+export declare const DEFAULT_DATABASE_PATH = ".data/observe.sqlite3";
+export declare const DEFAULT_MAX_INGEST_BYTES = 1048576;
+export declare const DEFAULT_MAX_INGEST_EVENTS = 500;
+/** defu-mergeable defaults. Deep so `database`/`ingest` merge rather than replace. */
+export declare const DEFAULT_OPTIONS: {
+    prefix: string;
+    retentionDays: number;
+    database: {
+        path: string;
+    };
+    ingest: {
+        maxBytes: number;
+        maxEvents: number;
+    };
+    auth: {
+        provider: "config";
+        users: never[];
+    };
+};

package/dist/runtime/shared/types/module-options.js

@@ -0,0 +1,13 @@
+export const DEFAULT_PREFIX = "/observe";
+export const OBSERVE_API_BASE = "/api/observe";
+export const OBSERVE_INGEST_ROUTE = "/api/observe/ingest";
+export const DEFAULT_DATABASE_PATH = ".data/observe.sqlite3";
+export const DEFAULT_MAX_INGEST_BYTES = 1048576;
+export const DEFAULT_MAX_INGEST_EVENTS = 500;
+export const DEFAULT_OPTIONS = {
+  prefix: DEFAULT_PREFIX,
+  retentionDays: 30,
+  database: { path: DEFAULT_DATABASE_PATH },
+  ingest: { maxBytes: DEFAULT_MAX_INGEST_BYTES, maxEvents: DEFAULT_MAX_INGEST_EVENTS },
+  auth: { provider: "config", users: [] }
+};

package/dist/runtime/shared/types/storage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Query filter for the logs table. Minimal in CP2 (enough to verify ingest);
+ * CP3 reuses and extends this for the analytical query helpers.
+ */
+export interface LogFilter {
+    from?: number;
+    to?: number;
+    level?: number;
+    minLevel?: number;
+    app?: string;
+    serviceId?: string;
+    /**
+     * RBAC scope set (CP6): ANDs `service_id IN (...)` onto the query. `'*'` or absent means
+     * no scope restriction (admin); `[]` matches nothing (empty assignment -> zero rows).
+     * Callers pass the result of `getAllowedServiceIds` straight through.
+     */
+    serviceIds?: string[] | '*';
+    traceId?: string;
+    session?: string;
+    user?: string;
+    errorFingerprint?: string;
+    route?: string;
+    feature?: string;
+    version?: string;
+    levels?: number[];
+    versions?: string[];
+    q?: string;
+    limit?: number;
+    offset?: number;
+    order?: 'asc' | 'desc';
+}

package/dist/runtime/shared/utils/format-relative.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The dashboard's WHEN helper: a compact relative timestamp for feed rows and stat
+ * cards. Pure and `now`-injectable so SSR and client render the same string for the
+ * same instant. Past ~30 days a relative label stops being useful; fall back to a
+ * locale date.
+ */
+export declare function formatRelative(ms: number, now?: number): string;

package/dist/runtime/shared/utils/format-relative.js

@@ -0,0 +1,11 @@
+const MINUTE_MS = 6e4;
+const HOUR_MS = 36e5;
+const DAY_MS = 864e5;
+export function formatRelative(ms, now = Date.now()) {
+  const delta = now - ms;
+  if (delta < MINUTE_MS) return "just now";
+  if (delta < HOUR_MS) return `${Math.floor(delta / MINUTE_MS)}m ago`;
+  if (delta < DAY_MS) return `${Math.floor(delta / HOUR_MS)}h ago`;
+  if (delta < 30 * DAY_MS) return `${Math.floor(delta / DAY_MS)}d ago`;
+  return new Date(ms).toLocaleDateString();
+}

package/dist/runtime/shared/utils/frogger-snippet.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copy-paste ingest snippets for a freshly minted key. Framework-free: rendered
+ * server-side (the route computes the origin and passes the full result to the
+ * reveal modal) so the client never re-derives the URL or re-fetches the key.
+ *
+ * The frogger ingest path is `/api/observe/ingest/frogger`. frogger's browser
+ * transport POSTs a bare $fetch with no custom header, so a browser source MUST
+ * carry the key on `?key=`; a server transport can instead send it as `x-api-key`.
+ */
+/** The guaranteed-correct ingest URL with the key on the query string. */
+export declare function buildIngestUrl(origin: string, key: string): string;
+export declare function buildFroggerSnippet(opts: {
+    origin: string;
+    key: string;
+}): {
+    rawUrl: string;
+    serverPluginSnippet: string;
+    configSnippet: string;
+};

package/dist/runtime/shared/utils/frogger-snippet.js

@@ -0,0 +1,33 @@
+const INGEST_PATH = "/api/observe/ingest/frogger";
+function trimOrigin(origin) {
+  return origin.replace(/\/+$/, "");
+}
+export function buildIngestUrl(origin, key) {
+  return `${trimOrigin(origin)}${INGEST_PATH}?key=${key}`;
+}
+export function buildFroggerSnippet(opts) {
+  const base = `${trimOrigin(opts.origin)}${INGEST_PATH}`;
+  const rawUrl = buildIngestUrl(opts.origin, opts.key);
+  const serverPluginSnippet = [
+    `// server/plugins/observe.ts`,
+    `import { createHttpTransport, addGlobalTransport } from '#frogger/server'`,
+    ``,
+    `export default defineNitroPlugin(() => {`,
+    `  addGlobalTransport(createHttpTransport({`,
+    `    endpoint: '${base}',`,
+    `    apiKey: '${opts.key}',`,
+    `  }))`,
+    `})`
+  ].join("\n");
+  const configSnippet = [
+    `// frogger.config.ts`,
+    `import { defineFroggerOptions } from '#frogger/config'`,
+    ``,
+    `export default defineFroggerOptions({`,
+    `  transports: [`,
+    `    { type: 'http', endpoint: '${rawUrl}' },`,
+    `  ],`,
+    `})`
+  ].join("\n");
+  return { rawUrl, serverPluginSnippet, configSnippet };
+}

package/dist/runtime/shared/utils/observe-config.d.ts

@@ -0,0 +1,9 @@
+import type { ModuleOptions } from '../types/module-options.js';
+/** Type-safe config helper for nuxt-observe.config.ts (mirrors defineFroggerOptions). */
+export declare function defineObserveOptions(options: ModuleOptions): ModuleOptions;
+/**
+ * CP0 loader stub: reads an optional nuxt-observe.config.{ts,js} from the project
+ * root and returns its default export. Precedence/merge hardening is deferred to a
+ * later checkpoint; for now the nuxt.config `observe` key alone is enough to boot.
+ */
+export declare function loadObserveConfig(rootDir: string): Promise<ModuleOptions | null>;

package/dist/runtime/shared/utils/observe-config.js

@@ -0,0 +1,17 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+export function defineObserveOptions(options) {
+  return options;
+}
+export async function loadObserveConfig(rootDir) {
+  const candidates = ["nuxt-observe.config.ts", "nuxt-observe.config.js"];
+  const file = candidates.map((f) => join(rootDir, f)).find(existsSync);
+  if (!file) return null;
+  try {
+    const mod = await import(file);
+    const cfg = mod.default ?? mod;
+    return typeof cfg === "function" ? cfg() : cfg;
+  } catch {
+    return null;
+  }
+}

package/dist/runtime/shared/utils/period.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Dashboard time-window definition, shared by the overview endpoint (CP7) and the
+ * chart checkpoints (CP8+) so every screen agrees on what "24h" means. Framework-free
+ * and pure: `now` is injectable for deterministic tests.
+ */
+export declare const PERIODS: readonly ["15m", "1h", "24h", "7d", "30d"];
+export type Period = (typeof PERIODS)[number];
+export interface PeriodRange {
+    from: number;
+    to: number;
+    label: string;
+}
+export declare function periodToRange(period: Period, now?: number): PeriodRange;

package/dist/runtime/shared/utils/period.js

@@ -0,0 +1,15 @@
+export const PERIODS = ["15m", "1h", "24h", "7d", "30d"];
+const MINUTE_MS = 6e4;
+const HOUR_MS = 36e5;
+const DAY_MS = 864e5;
+const PERIOD_WINDOWS = {
+  "15m": { ms: 15 * MINUTE_MS, label: "Last 15 minutes" },
+  "1h": { ms: HOUR_MS, label: "Last hour" },
+  "24h": { ms: 24 * HOUR_MS, label: "Last 24 hours" },
+  "7d": { ms: 7 * DAY_MS, label: "Last 7 days" },
+  "30d": { ms: 30 * DAY_MS, label: "Last 30 days" }
+};
+export function periodToRange(period, now = Date.now()) {
+  const { ms, label } = PERIOD_WINDOWS[period];
+  return { from: now - ms, to: now, label };
+}

package/dist/runtime/shared/utils/slug.d.ts

@@ -0,0 +1 @@
+export declare function slugify(input: string): string;

package/dist/runtime/shared/utils/slug.js

@@ -0,0 +1,5 @@
+const COMBINING_MARKS = /[\u0300-\u036F]/g;
+export function slugify(input) {
+  const base = input.normalize("NFKD").replace(COMBINING_MARKS, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return base || "service";
+}

package/dist/runtime/shared/utils/uuid.d.ts

@@ -0,0 +1,187 @@
+/**
+ * uuidv7: A JavaScript implementation of UUID version 7
+ *
+ * Copyright 2021-2024 LiosK
+ *
+ * @license Apache-2.0
+ * @packageDocumentation
+ */
+/** Represents a UUID as a 16-byte byte array. */
+export declare class UUID {
+    readonly bytes: Readonly<Uint8Array>;
+    /** @param bytes - The 16-byte byte array representation. */
+    private constructor();
+    /**
+     * Creates an object from the internal representation, a 16-byte byte array
+     * containing the binary UUID representation in the big-endian byte order.
+     *
+     * This method does NOT shallow-copy the argument, and thus the created object
+     * holds the reference to the underlying buffer.
+     *
+     * @throws TypeError if the length of the argument is not 16.
+     */
+    static ofInner(bytes: Readonly<Uint8Array>): UUID;
+    /**
+     * Builds a byte array from UUIDv7 field values.
+     *
+     * @param unixTsMs - A 48-bit `unix_ts_ms` field value.
+     * @param randA - A 12-bit `rand_a` field value.
+     * @param randBHi - The higher 30 bits of 62-bit `rand_b` field value.
+     * @param randBLo - The lower 32 bits of 62-bit `rand_b` field value.
+     * @throws RangeError if any field value is out of the specified range.
+     */
+    static fromFieldsV7(unixTsMs: number, randA: number, randBHi: number, randBLo: number): UUID;
+    /**
+     * Builds a byte array from a string representation.
+     *
+     * This method accepts the following formats:
+     *
+     * - 32-digit hexadecimal format without hyphens: `0189dcd553117d408db09496a2eef37b`
+     * - 8-4-4-4-12 hyphenated format: `0189dcd5-5311-7d40-8db0-9496a2eef37b`
+     * - Hyphenated format with surrounding braces: `{0189dcd5-5311-7d40-8db0-9496a2eef37b}`
+     * - RFC 9562 URN format: `urn:uuid:0189dcd5-5311-7d40-8db0-9496a2eef37b`
+     *
+     * Leading and trailing whitespaces represents an error.
+     *
+     * @throws SyntaxError if the argument could not parse as a valid UUID string.
+     */
+    static parse(uuid: string): UUID;
+    /**
+     * @returns The 8-4-4-4-12 canonical hexadecimal string representation
+     * (`0189dcd5-5311-7d40-8db0-9496a2eef37b`).
+     */
+    toString(): string;
+    /**
+     * @returns The 32-digit hexadecimal representation without hyphens
+     * (`0189dcd553117d408db09496a2eef37b`).
+     */
+    toHex(): string;
+    /** @returns The 8-4-4-4-12 canonical hexadecimal string representation. */
+    toJSON(): string;
+    /**
+     * Reports the variant field value of the UUID or, if appropriate, "NIL" or
+     * "MAX".
+     *
+     * For convenience, this method reports "NIL" or "MAX" if `this` represents
+     * the Nil or Max UUID, although the Nil and Max UUIDs are technically
+     * subsumed under the variants `0b0` and `0b111`, respectively.
+     */
+    getVariant(): "VAR_0" | "VAR_10" | "VAR_110" | "VAR_RESERVED" | "NIL" | "MAX";
+    /**
+     * Returns the version field value of the UUID or `undefined` if the UUID does
+     * not have the variant field value of `0b10`.
+     */
+    getVersion(): number | undefined;
+    /** Creates an object from `this`. */
+    clone(): UUID;
+    /** Returns true if `this` is equivalent to `other`. */
+    equals(other: UUID): boolean;
+    /**
+     * Returns a negative integer, zero, or positive integer if `this` is less
+     * than, equal to, or greater than `other`, respectively.
+     */
+    compareTo(other: UUID): number;
+}
+/**
+ * Encapsulates the monotonic counter state.
+ *
+ * This class provides APIs to utilize a separate counter state from that of the
+ * global generator used by {@link uuidv7} and {@link uuidv7obj}. In addition to
+ * the default {@link generate} method, this class has {@link generateOrAbort}
+ * that is useful to absolutely guarantee the monotonically increasing order of
+ * generated UUIDs. See their respective documentation for details.
+ */
+export declare class V7Generator {
+    private timestamp;
+    private counter;
+    /** The random number generator used by the generator. */
+    private readonly random;
+    /**
+     * Creates a generator object with the default random number generator, or
+     * with the specified one if passed as an argument. The specified random
+     * number generator should be cryptographically strong and securely seeded.
+     */
+    constructor(randomNumberGenerator?: {
+        /** Returns a 32-bit random unsigned integer. */
+        nextUint32(): number;
+    });
+    /**
+     * Generates a new UUIDv7 object from the current timestamp, or resets the
+     * generator upon significant timestamp rollback.
+     *
+     * This method returns a monotonically increasing UUID by reusing the previous
+     * timestamp even if the up-to-date timestamp is smaller than the immediately
+     * preceding UUID's. However, when such a clock rollback is considered
+     * significant (i.e., by more than ten seconds), this method resets the
+     * generator and returns a new UUID based on the given timestamp, breaking the
+     * increasing order of UUIDs.
+     *
+     * See {@link generateOrAbort} for the other mode of generation and
+     * {@link generateOrResetCore} for the low-level primitive.
+     */
+    generate(): UUID;
+    /**
+     * Generates a new UUIDv7 object from the current timestamp, or returns
+     * `undefined` upon significant timestamp rollback.
+     *
+     * This method returns a monotonically increasing UUID by reusing the previous
+     * timestamp even if the up-to-date timestamp is smaller than the immediately
+     * preceding UUID's. However, when such a clock rollback is considered
+     * significant (i.e., by more than ten seconds), this method aborts and
+     * returns `undefined` immediately.
+     *
+     * See {@link generate} for the other mode of generation and
+     * {@link generateOrAbortCore} for the low-level primitive.
+     */
+    generateOrAbort(): UUID | undefined;
+    /**
+     * Generates a new UUIDv7 object from the `unixTsMs` passed, or resets the
+     * generator upon significant timestamp rollback.
+     *
+     * This method is equivalent to {@link generate} except that it takes a custom
+     * timestamp and clock rollback allowance.
+     *
+     * @param rollbackAllowance - The amount of `unixTsMs` rollback that is
+     * considered significant. A suggested value is `10_000` (milliseconds).
+     * @throws RangeError if `unixTsMs` is not a 48-bit positive integer.
+     */
+    generateOrResetCore(unixTsMs: number, rollbackAllowance: number): UUID;
+    /**
+     * Generates a new UUIDv7 object from the `unixTsMs` passed, or returns
+     * `undefined` upon significant timestamp rollback.
+     *
+     * This method is equivalent to {@link generateOrAbort} except that it takes a
+     * custom timestamp and clock rollback allowance.
+     *
+     * @param rollbackAllowance - The amount of `unixTsMs` rollback that is
+     * considered significant. A suggested value is `10_000` (milliseconds).
+     * @throws RangeError if `unixTsMs` is not a 48-bit positive integer.
+     */
+    generateOrAbortCore(unixTsMs: number, rollbackAllowance: number): UUID | undefined;
+    /** Initializes the counter at a 42-bit random integer. */
+    private resetCounter;
+    /**
+     * Generates a new UUIDv4 object utilizing the random number generator inside.
+     *
+     * @internal
+     */
+    generateV4(): UUID;
+}
+/**
+ * Generates a UUIDv7 string.
+ *
+ * @returns The 8-4-4-4-12 canonical hexadecimal string representation
+ * ("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").
+ */
+export declare const uuidv7: () => string;
+/** Generates a UUIDv7 object. */
+export declare const uuidv7obj: () => UUID;
+/**
+ * Generates a UUIDv4 string.
+ *
+ * @returns The 8-4-4-4-12 canonical hexadecimal string representation
+ * ("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").
+ */
+export declare const uuidv4: () => string;
+/** Generates a UUIDv4 object. */
+export declare const uuidv4obj: () => UUID;