@bunizao/contracts 0.23.0 → 0.26.0

package/README.md

@@ -16,5 +16,11 @@ npm install @bunizao/contracts@0.1.0
 The package exports the complete contract from `@bunizao/contracts` and the
 feature modules from `@bunizao/contracts/{analytics,admin,content,listening,mood,notify,routes,telegram-ops}`.
 
+`@bunizao/contracts/runtime` is the one subpath that ships code rather than
+types: the env readers (`createEnvReaders`, `readRuntimeValue`,
+`setRuntimeEnvSource`), the JSON response helpers and the query parsers both
+Workers run. Bind the env readers to the bundle's own `import.meta.env` once,
+in a local module, since bundlers only replace it in application source.
+
 The package is source-available but not licensed for redistribution. See
 [`LICENSE`](LICENSE) for the applicable terms.

package/dist/analytics.d.ts

@@ -359,3 +359,106 @@ export interface SiteAnalyticsReportResult {
     }> | null;
     notices: string[];
 }
+export declare const SITE_EXPLORE_ENDPOINT: '/api/analytics/explore';
+export declare const SITE_EXPLORE_VIEWS: readonly ['traffic', 'decoy'];
+export type SiteExploreView = typeof SITE_EXPLORE_VIEWS[number];
+export declare const SITE_EXPLORE_RANGES: readonly ['24h', '7d', '30d', '90d'];
+export type SiteExploreRange = typeof SITE_EXPLORE_RANGES[number];
+export declare const SITE_EXPLORE_CLASSES: readonly ['human', 'bot', 'owner', 'all'];
+export type SiteExploreClass = typeof SITE_EXPLORE_CLASSES[number];
+export declare const SITE_EXPLORE_PARTS: readonly ['summary', 'panel', 'clicks', 'log'];
+export type SiteExplorePart = typeof SITE_EXPLORE_PARTS[number];
+export declare const SITE_EXPLORE_DIMS: {
+    readonly traffic: readonly ['page', 'section', 'referrer', 'channel', 'utm', 'country', 'city', 'device', 'browser', 'os', 'visitor'];
+    readonly decoy: readonly ['client', 'kind', 'reason', 'ua', 'path', 'network', 'country'];
+};
+export type SiteExploreDim<V extends SiteExploreView = SiteExploreView> = typeof SITE_EXPLORE_DIMS[V][number];
+export declare const SITE_EXPLORE_METRICS: {
+    readonly traffic: readonly ['visitors', 'views', 'engagement', 'dwell'];
+    readonly decoy: readonly ['hits', 'clients', 'networks', 'named'];
+};
+export type SiteExploreMetric<V extends SiteExploreView = SiteExploreView> = typeof SITE_EXPLORE_METRICS[V][number];
+export declare const SITE_EXPLORE_PANEL_LIMIT = 100;
+export declare const SITE_EXPLORE_EMPTY = "(none)";
+export interface SiteExploreSeries {
+    totals: Record<string, number>;
+    points: Record<string, number[]>;
+}
+export interface SiteExploreSummary {
+    view: SiteExploreView;
+    range: SiteExploreRange;
+    timezone: 'Australia/Melbourne';
+    bucket: 'hour' | 'day';
+    buckets: string[];
+    from: string;
+    to: string;
+    previousFrom: string | null;
+    current: SiteExploreSeries;
+    previous: SiteExploreSeries | null;
+    notices: Array<'compare_beyond_retention'>;
+}
+export interface SiteExploreRow {
+    key: string;
+    label: string;
+    count: number;
+    visitors: number;
+}
+export interface SiteExplorePanel {
+    dim: SiteExploreDim;
+    rows: SiteExploreRow[];
+    more: boolean;
+}
+export interface SiteExploreClickRow {
+    name: string;
+    label: string;
+    href: string;
+    clicks: number;
+    visitors: number;
+}
+export interface SiteExploreClicks {
+    rows: SiteExploreClickRow[];
+    more: boolean;
+    ignored: SiteExploreDim<'traffic'>[];
+}
+export interface SiteExploreVisit {
+    at: string;
+    until: string;
+    visitor: string;
+    session: string;
+    class: SiteAnalyticsTrafficClass;
+    country: string;
+    city: string;
+    network: string;
+    org: string;
+    device: string;
+    browser: string;
+    os: string;
+    entry: string;
+    referrer: string;
+    channel: string;
+    pages: number;
+    dwellMs: number;
+    interactions: number;
+}
+export interface SiteExploreDecoyHit {
+    at: string;
+    reason: string;
+    kind: string;
+    client: string;
+    ua: string;
+    path: string;
+    network: string;
+    org: string;
+    country: string;
+    method: string;
+}
+export type SiteExploreLog = {
+    view: 'traffic';
+    rows: SiteExploreVisit[];
+    more: boolean;
+    next: string | null;
+} | {
+    view: 'decoy';
+    rows: SiteExploreDecoyHit[];
+    more: boolean;
+};

package/dist/analytics.js

@@ -36,6 +36,21 @@ var SITE_ANALYTICS_SURFACES = [
   "other"
 ];
 var SITE_ANALYTICS_REPORTS = ["overview", "pages", "clicks", "sources", "audience", "quality", "log", "visitor"];
+var SITE_EXPLORE_ENDPOINT = "/api/analytics/explore";
+var SITE_EXPLORE_VIEWS = ["traffic", "decoy"];
+var SITE_EXPLORE_RANGES = ["24h", "7d", "30d", "90d"];
+var SITE_EXPLORE_CLASSES = ["human", "bot", "owner", "all"];
+var SITE_EXPLORE_PARTS = ["summary", "panel", "clicks", "log"];
+var SITE_EXPLORE_DIMS = {
+  traffic: ["page", "section", "referrer", "channel", "utm", "country", "city", "device", "browser", "os", "visitor"],
+  decoy: ["client", "kind", "reason", "ua", "path", "network", "country"]
+};
+var SITE_EXPLORE_METRICS = {
+  traffic: ["visitors", "views", "engagement", "dwell"],
+  decoy: ["hits", "clients", "networks", "named"]
+};
+var SITE_EXPLORE_PANEL_LIMIT = 100;
+var SITE_EXPLORE_EMPTY = "(none)";
 export {
   BLOG_ANALYTICS_ARTICLE_ENDPOINT,
   BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH,
@@ -53,5 +68,14 @@ export {
   SITE_ANALYTICS_REPORTS,
   SITE_ANALYTICS_REPORT_ENDPOINT,
   SITE_ANALYTICS_SESSION_IDLE_MS,
-  SITE_ANALYTICS_SURFACES
+  SITE_ANALYTICS_SURFACES,
+  SITE_EXPLORE_CLASSES,
+  SITE_EXPLORE_DIMS,
+  SITE_EXPLORE_EMPTY,
+  SITE_EXPLORE_ENDPOINT,
+  SITE_EXPLORE_METRICS,
+  SITE_EXPLORE_PANEL_LIMIT,
+  SITE_EXPLORE_PARTS,
+  SITE_EXPLORE_RANGES,
+  SITE_EXPLORE_VIEWS
 };

package/dist/index.js

@@ -36,6 +36,21 @@ var SITE_ANALYTICS_SURFACES = [
   "other"
 ];
 var SITE_ANALYTICS_REPORTS = ["overview", "pages", "clicks", "sources", "audience", "quality", "log", "visitor"];
+var SITE_EXPLORE_ENDPOINT = "/api/analytics/explore";
+var SITE_EXPLORE_VIEWS = ["traffic", "decoy"];
+var SITE_EXPLORE_RANGES = ["24h", "7d", "30d", "90d"];
+var SITE_EXPLORE_CLASSES = ["human", "bot", "owner", "all"];
+var SITE_EXPLORE_PARTS = ["summary", "panel", "clicks", "log"];
+var SITE_EXPLORE_DIMS = {
+  traffic: ["page", "section", "referrer", "channel", "utm", "country", "city", "device", "browser", "os", "visitor"],
+  decoy: ["client", "kind", "reason", "ua", "path", "network", "country"]
+};
+var SITE_EXPLORE_METRICS = {
+  traffic: ["visitors", "views", "engagement", "dwell"],
+  decoy: ["hits", "clients", "networks", "named"]
+};
+var SITE_EXPLORE_PANEL_LIMIT = 100;
+var SITE_EXPLORE_EMPTY = "(none)";
 // src/admin.ts
 var ADMIN_COMMENT_REJECT_REASONS = ["spam", "promotional", "abuse", "off_topic", "personal_info"];
 var ADMIN_ACTIVITY_EVENTS = [
@@ -408,6 +423,15 @@ export {
   SITE_ANALYTICS_REPORT_ENDPOINT,
   SITE_ANALYTICS_SESSION_IDLE_MS,
   SITE_ANALYTICS_SURFACES,
+  SITE_EXPLORE_CLASSES,
+  SITE_EXPLORE_DIMS,
+  SITE_EXPLORE_EMPTY,
+  SITE_EXPLORE_ENDPOINT,
+  SITE_EXPLORE_METRICS,
+  SITE_EXPLORE_PANEL_LIMIT,
+  SITE_EXPLORE_PARTS,
+  SITE_EXPLORE_RANGES,
+  SITE_EXPLORE_VIEWS,
   SUBSCRIPTION_SOURCES,
   TELEGRAM_OPS_BASE_PATH,
   TELEGRAM_OPS_BROADCASTS_PATH,

package/dist/runtime/env.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime environment readers shared by the public site and the API Worker.
+ *
+ * A value is looked up in this order: `process.env` (local shells and tests),
+ * the build-time env the consumer binds through `createEnvReaders`, then the
+ * request-time Worker env: `locals.env`, `locals.runtime.env`, and finally the
+ * env a Worker entrypoint registered with `setRuntimeEnvSource` for code that
+ * runs without request locals (queues, crons, webhooks).
+ *
+ * This module never touches `import.meta.env` itself: bundlers only replace it
+ * in application source, so each consumer passes its own build env in.
+ */
+export type EnvSource = Record<string, unknown>;
+export interface RuntimeEnvLocals {
+    runtime?: {
+        env?: EnvSource;
+    };
+    env?: EnvSource;
+}
+export declare function setRuntimeEnvSource(env: EnvSource): void;
+export declare function readRuntimeEnvSource(locals: unknown): EnvSource | undefined;
+export declare function readRuntimeValue(locals: unknown, name: string): string | undefined;
+export interface EnvReaders {
+    readOptionalEnv(locals: unknown, name: string, buildEnv?: EnvSource): string | undefined;
+    readEnv(locals: unknown, name: string, buildEnv?: EnvSource): string;
+    readPublicEnv(locals: unknown, name: string, buildEnv?: EnvSource): string;
+}
+/**
+ * Binds the readers to a consumer's build-time env, usually `import.meta.env`.
+ */
+export declare function createEnvReaders(defaultBuildEnv: EnvSource): EnvReaders;

package/dist/runtime/json-response.d.ts

@@ -0,0 +1,5 @@
+export declare function json(status: number, data: unknown, headers?: HeadersInit): Response;
+export declare function jsonOk(data: unknown, headers?: HeadersInit): Response;
+export declare function jsonError(status: number, error: string, headers?: HeadersInit, extras?: Record<string, unknown>): Response;
+export declare function jsonBadRequest(error: string, headers?: HeadersInit, extras?: Record<string, unknown>): Response;
+export declare function jsonTooManyRequests(headers?: HeadersInit): Response;

package/dist/runtime/query.d.ts

@@ -0,0 +1,5 @@
+export declare function readCursorQuery(url: URL, name: string): string;
+export declare function isValidCursor(value: string): boolean;
+export declare function readIntQuery(url: URL, name: string): number | null;
+export declare function readEnumQuery<T extends string>(url: URL, name: string, allowedValues: readonly T[], defaultValue: T): T;
+export declare function readBooleanFlag(url: URL, name: string, defaultValue?: boolean): boolean;

package/dist/runtime.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Runtime helpers both Workers execute: env lookup, JSON responses and query
+ * parsing. Everything else in this package is types and constants.
+ */
+export { createEnvReaders, readRuntimeEnvSource, readRuntimeValue, setRuntimeEnvSource, type EnvReaders, type EnvSource, type RuntimeEnvLocals, } from './runtime/env';
+export { json, jsonBadRequest, jsonError, jsonOk, jsonTooManyRequests, } from './runtime/json-response';
+export { isValidCursor, readBooleanFlag, readCursorQuery, readEnumQuery, readIntQuery, } from './runtime/query';

package/dist/runtime.js

@@ -0,0 +1,138 @@
+// src/runtime/env.ts
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function readValue(source, name) {
+  const raw = source?.[name];
+  if (typeof raw !== "string") {
+    return;
+  }
+  const value = raw.trim();
+  return value ? value : undefined;
+}
+function readWorkerEnv() {
+  return record(globalThis.__BUXX_RUNTIME_ENV__);
+}
+function setRuntimeEnvSource(env) {
+  globalThis.__BUXX_RUNTIME_ENV__ = env;
+}
+function readRuntimeEnvSource(locals) {
+  const localRecord = record(locals);
+  const directEnv = record(localRecord.env);
+  if (Object.keys(directEnv).length > 0) {
+    return directEnv;
+  }
+  try {
+    const runtimeEnv = record(record(localRecord.runtime).env);
+    if (Object.keys(runtimeEnv).length > 0) {
+      return runtimeEnv;
+    }
+  } catch {}
+  const workerEnv = readWorkerEnv();
+  return Object.keys(workerEnv).length > 0 ? workerEnv : undefined;
+}
+function readRuntimeValue(locals, name) {
+  const localRecord = record(locals);
+  const directValue = readValue(record(localRecord.env), name);
+  if (directValue) {
+    return directValue;
+  }
+  try {
+    const runtimeValue = readValue(record(record(localRecord.runtime).env), name);
+    if (runtimeValue) {
+      return runtimeValue;
+    }
+  } catch {}
+  return readValue(readWorkerEnv(), name);
+}
+function readProcessEnv(name) {
+  const processEnv = globalThis.process?.env;
+  return readValue(processEnv, name);
+}
+function createEnvReaders(defaultBuildEnv) {
+  const readOptionalEnv = (locals, name, buildEnv = defaultBuildEnv) => {
+    return readProcessEnv(name) ?? readValue(buildEnv, name) ?? readRuntimeValue(locals, name);
+  };
+  const readEnv = (locals, name, buildEnv = defaultBuildEnv) => {
+    return readOptionalEnv(locals, name, buildEnv) ?? "";
+  };
+  const readPublicEnv = (locals, name, buildEnv = defaultBuildEnv) => {
+    const publicName = name.startsWith("PUBLIC_") ? name : `PUBLIC_${name}`;
+    return readEnv(locals, publicName, buildEnv);
+  };
+  return { readOptionalEnv, readEnv, readPublicEnv };
+}
+// src/runtime/json-response.ts
+function createJsonHeaders(headers) {
+  const next = new Headers(headers);
+  if (!next.has("Content-Type")) {
+    next.set("Content-Type", "application/json");
+  }
+  return next;
+}
+function json(status, data, headers) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: createJsonHeaders(headers)
+  });
+}
+function jsonOk(data, headers) {
+  return json(200, data, headers);
+}
+function jsonError(status, error, headers, extras) {
+  return json(status, { error, ...extras ?? {} }, headers);
+}
+function jsonBadRequest(error, headers, extras) {
+  return jsonError(400, error, headers, extras);
+}
+function jsonTooManyRequests(headers) {
+  return jsonError(429, "Too Many Requests", headers);
+}
+// src/runtime/query.ts
+var CURSOR_PATTERN = /^\d{1,20}$/;
+var INTEGER_PATTERN = /^-?\d+$/;
+function readCursorQuery(url, name) {
+  return (url.searchParams.get(name) ?? "").trim();
+}
+function isValidCursor(value) {
+  return value === "" || CURSOR_PATTERN.test(value);
+}
+function readIntQuery(url, name) {
+  const value = (url.searchParams.get(name) ?? "").trim();
+  if (!value || !INTEGER_PATTERN.test(value)) {
+    return null;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function readEnumQuery(url, name, allowedValues, defaultValue) {
+  const value = (url.searchParams.get(name) ?? "").trim();
+  return allowedValues.includes(value) ? value : defaultValue;
+}
+function readBooleanFlag(url, name, defaultValue = false) {
+  const value = url.searchParams.get(name);
+  if (value === null) {
+    return defaultValue;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) {
+    return defaultValue;
+  }
+  return normalized !== "0" && normalized !== "false" && normalized !== "no" && normalized !== "off";
+}
+export {
+  createEnvReaders,
+  isValidCursor,
+  json,
+  jsonBadRequest,
+  jsonError,
+  jsonOk,
+  jsonTooManyRequests,
+  readBooleanFlag,
+  readCursorQuery,
+  readEnumQuery,
+  readIntQuery,
+  readRuntimeEnvSource,
+  readRuntimeValue,
+  setRuntimeEnvSource
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/contracts",
-  "version": "0.23.0",
+  "version": "0.26.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,
@@ -83,6 +83,11 @@
       "import": "./dist/routes.js",
       "default": "./dist/routes.js"
     },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "default": "./dist/runtime.js"
+    },
     "./telegram-ops": {
       "types": "./dist/telegram-ops.d.ts",
       "import": "./dist/telegram-ops.js",