@xray-analytics/analytics-server 0.0.2

package/dist/index.d.mts

@@ -0,0 +1,177 @@
+import { ZodType } from 'zod';
+
+type AnalyticsEventProps = Record<string, unknown>;
+type AnalyticsEventInput = {
+    name: string;
+    ts?: number;
+    appId: string;
+    sessionId?: string;
+    url?: string;
+    path?: string;
+    ref?: string;
+    environment?: string;
+    props?: AnalyticsEventProps;
+    tags?: string[];
+    clientMeta?: {
+        ip?: string;
+        userAgent?: string;
+        isMobile?: boolean;
+        os?: string;
+        platform?: string;
+        language?: string;
+        screen?: {
+            width: number;
+            height: number;
+        };
+    };
+    writeKey?: string;
+};
+type IngestContext = {
+    ip?: string;
+    userAgent?: string;
+    headers?: Record<string, string | undefined>;
+    requestId?: string;
+};
+type StoredAnalyticsEvent = AnalyticsEventInput & {
+    ts: number;
+    receivedAt: number;
+    props: AnalyticsEventProps;
+    meta?: {
+        ip?: string;
+        userAgent?: string;
+        requestId?: string;
+    };
+};
+interface AnalyticsStorageAdapter {
+    save: (event: StoredAnalyticsEvent) => Promise<void>;
+    getAll: (dateInit?: number, dateEnd?: number) => Promise<StoredAnalyticsEvent[]>;
+    clear: (dateInit?: number, dateEnd?: number) => Promise<number>;
+}
+type MaskFieldArgs = {
+    path: string;
+    key: string;
+    value: unknown;
+    event: StoredAnalyticsEvent;
+};
+type MaskConfig = {
+    paths?: string[];
+    keyPatterns?: RegExp[];
+    maskValue?: string;
+    maskField?: (args: MaskFieldArgs) => unknown;
+};
+type AcceptedTrack = {
+    trackName: string;
+    schema: ZodType;
+    validateOn?: 'props' | 'event';
+    version?: number;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    catalogSchema?: Record<string, unknown>;
+};
+type AnalyticsTrackCatalogItem = {
+    trackName: string;
+    validateOn: 'props' | 'event';
+    version: number;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    schema?: Record<string, unknown>;
+};
+type AnalyticsTrackCatalog = {
+    generatedAt: number;
+    tracks: AnalyticsTrackCatalogItem[];
+};
+type AnalyticsServerConfig = {
+    storage: AnalyticsStorageAdapter;
+    acceptedTracks?: AcceptedTrack[];
+    rejectUnknownTracks?: boolean;
+    masking?: MaskConfig;
+};
+type IngestErrorCode = 'invalid_payload' | 'track_not_allowed' | 'schema_mismatch' | 'storage_error';
+type IngestResult = {
+    ok: true;
+    event: StoredAnalyticsEvent;
+} | {
+    ok: false;
+    error: {
+        code: IngestErrorCode;
+        message: string;
+        details?: unknown;
+    };
+};
+
+declare function createAnalyticsServer(config: AnalyticsServerConfig): {
+    ingest: (input: unknown, context?: IngestContext) => Promise<IngestResult>;
+    getCatalog: () => AnalyticsTrackCatalog;
+};
+
+declare function createMemoryAdapter(initialEvents?: StoredAnalyticsEvent[]): AnalyticsStorageAdapter;
+
+type PostgresQueryable = {
+    query: (text: string, values?: unknown[]) => Promise<unknown>;
+};
+type PostgresAdapterOptions = {
+    db: PostgresQueryable;
+    tableName?: string;
+    schemaName?: string;
+};
+declare function createPostgresAdapter({ db, tableName, schemaName, }: PostgresAdapterOptions): AnalyticsStorageAdapter;
+
+type Server$5 = ReturnType<typeof createAnalyticsServer>;
+type HeaderValue = string | string[] | undefined;
+type ExpressLikeRequest = {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, HeaderValue>;
+    ip?: string;
+    get?: (name: string) => string | undefined;
+    header?: (name: string) => string | undefined;
+};
+type ExpressLikeResponse = {
+    status: (code: number) => ExpressLikeResponse;
+    json: (body: unknown) => unknown;
+};
+type ExpressIngestHandlerOptions = {
+    getContext?: (req: ExpressLikeRequest) => IngestContext;
+};
+declare function createExpressIngestHandler(server: Server$5, options?: ExpressIngestHandlerOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<unknown>;
+
+type Server$4 = ReturnType<typeof createAnalyticsServer>;
+declare function createExpressCatalogHandler(server: Server$4): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<unknown>;
+
+type Server$3 = ReturnType<typeof createAnalyticsServer>;
+declare function createFetchCatalogHandler(server: Server$3): (request: Request) => Promise<Response>;
+
+type Server$2 = ReturnType<typeof createAnalyticsServer>;
+declare function createFetchIngestHandler(server: Server$2): (request: Request) => Promise<Response>;
+
+type Server$1 = ReturnType<typeof createAnalyticsServer>;
+type CreateCatalogHandlerConfig = {
+    adapter?: 'fetch';
+} | {
+    adapter: 'express';
+};
+declare function createCatalogHandler(server: Server$1, config?: {
+    adapter?: 'fetch';
+}): (request: Request) => Promise<Response>;
+declare function createCatalogHandler(server: Server$1, config: {
+    adapter: 'express';
+}): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<unknown>;
+
+type Server = ReturnType<typeof createAnalyticsServer>;
+type CreateIngestHandlerConfig = {
+    adapter?: 'fetch';
+} | {
+    adapter: 'express';
+    express?: ExpressIngestHandlerOptions;
+};
+declare function createIngestHandler(server: Server, config?: {
+    adapter?: 'fetch';
+}): (request: Request) => Promise<Response>;
+declare function createIngestHandler(server: Server, config: {
+    adapter: 'express';
+    express?: ExpressIngestHandlerOptions;
+}): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<unknown>;
+
+export { type AcceptedTrack, type AnalyticsEventInput, type AnalyticsServerConfig, type AnalyticsStorageAdapter, type AnalyticsTrackCatalog, type AnalyticsTrackCatalogItem, type CreateCatalogHandlerConfig, type CreateIngestHandlerConfig, type ExpressIngestHandlerOptions, type ExpressLikeRequest, type ExpressLikeResponse, type IngestContext, type IngestResult, type MaskConfig, type PostgresAdapterOptions, type PostgresQueryable, type StoredAnalyticsEvent, createAnalyticsServer, createCatalogHandler, createExpressCatalogHandler, createExpressIngestHandler, createFetchCatalogHandler, createFetchIngestHandler, createIngestHandler, createMemoryAdapter, createPostgresAdapter };

package/dist/index.d.ts

@@ -0,0 +1,177 @@
+import { ZodType } from 'zod';
+
+type AnalyticsEventProps = Record<string, unknown>;
+type AnalyticsEventInput = {
+    name: string;
+    ts?: number;
+    appId: string;
+    sessionId?: string;
+    url?: string;
+    path?: string;
+    ref?: string;
+    environment?: string;
+    props?: AnalyticsEventProps;
+    tags?: string[];
+    clientMeta?: {
+        ip?: string;
+        userAgent?: string;
+        isMobile?: boolean;
+        os?: string;
+        platform?: string;
+        language?: string;
+        screen?: {
+            width: number;
+            height: number;
+        };
+    };
+    writeKey?: string;
+};
+type IngestContext = {
+    ip?: string;
+    userAgent?: string;
+    headers?: Record<string, string | undefined>;
+    requestId?: string;
+};
+type StoredAnalyticsEvent = AnalyticsEventInput & {
+    ts: number;
+    receivedAt: number;
+    props: AnalyticsEventProps;
+    meta?: {
+        ip?: string;
+        userAgent?: string;
+        requestId?: string;
+    };
+};
+interface AnalyticsStorageAdapter {
+    save: (event: StoredAnalyticsEvent) => Promise<void>;
+    getAll: (dateInit?: number, dateEnd?: number) => Promise<StoredAnalyticsEvent[]>;
+    clear: (dateInit?: number, dateEnd?: number) => Promise<number>;
+}
+type MaskFieldArgs = {
+    path: string;
+    key: string;
+    value: unknown;
+    event: StoredAnalyticsEvent;
+};
+type MaskConfig = {
+    paths?: string[];
+    keyPatterns?: RegExp[];
+    maskValue?: string;
+    maskField?: (args: MaskFieldArgs) => unknown;
+};
+type AcceptedTrack = {
+    trackName: string;
+    schema: ZodType;
+    validateOn?: 'props' | 'event';
+    version?: number;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    catalogSchema?: Record<string, unknown>;
+};
+type AnalyticsTrackCatalogItem = {
+    trackName: string;
+    validateOn: 'props' | 'event';
+    version: number;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    schema?: Record<string, unknown>;
+};
+type AnalyticsTrackCatalog = {
+    generatedAt: number;
+    tracks: AnalyticsTrackCatalogItem[];
+};
+type AnalyticsServerConfig = {
+    storage: AnalyticsStorageAdapter;
+    acceptedTracks?: AcceptedTrack[];
+    rejectUnknownTracks?: boolean;
+    masking?: MaskConfig;
+};
+type IngestErrorCode = 'invalid_payload' | 'track_not_allowed' | 'schema_mismatch' | 'storage_error';
+type IngestResult = {
+    ok: true;
+    event: StoredAnalyticsEvent;
+} | {
+    ok: false;
+    error: {
+        code: IngestErrorCode;
+        message: string;
+        details?: unknown;
+    };
+};
+
+declare function createAnalyticsServer(config: AnalyticsServerConfig): {
+    ingest: (input: unknown, context?: IngestContext) => Promise<IngestResult>;
+    getCatalog: () => AnalyticsTrackCatalog;
+};
+
+declare function createMemoryAdapter(initialEvents?: StoredAnalyticsEvent[]): AnalyticsStorageAdapter;
+
+type PostgresQueryable = {
+    query: (text: string, values?: unknown[]) => Promise<unknown>;
+};
+type PostgresAdapterOptions = {
+    db: PostgresQueryable;
+    tableName?: string;
+    schemaName?: string;
+};
+declare function createPostgresAdapter({ db, tableName, schemaName, }: PostgresAdapterOptions): AnalyticsStorageAdapter;
+
+type Server$5 = ReturnType<typeof createAnalyticsServer>;
+type HeaderValue = string | string[] | undefined;
+type ExpressLikeRequest = {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, HeaderValue>;
+    ip?: string;
+    get?: (name: string) => string | undefined;
+    header?: (name: string) => string | undefined;
+};
+type ExpressLikeResponse = {
+    status: (code: number) => ExpressLikeResponse;
+    json: (body: unknown) => unknown;
+};
+type ExpressIngestHandlerOptions = {
+    getContext?: (req: ExpressLikeRequest) => IngestContext;
+};
+declare function createExpressIngestHandler(server: Server$5, options?: ExpressIngestHandlerOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<unknown>;
+
+type Server$4 = ReturnType<typeof createAnalyticsServer>;
+declare function createExpressCatalogHandler(server: Server$4): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<unknown>;
+
+type Server$3 = ReturnType<typeof createAnalyticsServer>;
+declare function createFetchCatalogHandler(server: Server$3): (request: Request) => Promise<Response>;
+
+type Server$2 = ReturnType<typeof createAnalyticsServer>;
+declare function createFetchIngestHandler(server: Server$2): (request: Request) => Promise<Response>;
+
+type Server$1 = ReturnType<typeof createAnalyticsServer>;
+type CreateCatalogHandlerConfig = {
+    adapter?: 'fetch';
+} | {
+    adapter: 'express';
+};
+declare function createCatalogHandler(server: Server$1, config?: {
+    adapter?: 'fetch';
+}): (request: Request) => Promise<Response>;
+declare function createCatalogHandler(server: Server$1, config: {
+    adapter: 'express';
+}): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<unknown>;
+
+type Server = ReturnType<typeof createAnalyticsServer>;
+type CreateIngestHandlerConfig = {
+    adapter?: 'fetch';
+} | {
+    adapter: 'express';
+    express?: ExpressIngestHandlerOptions;
+};
+declare function createIngestHandler(server: Server, config?: {
+    adapter?: 'fetch';
+}): (request: Request) => Promise<Response>;
+declare function createIngestHandler(server: Server, config: {
+    adapter: 'express';
+    express?: ExpressIngestHandlerOptions;
+}): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<unknown>;
+
+export { type AcceptedTrack, type AnalyticsEventInput, type AnalyticsServerConfig, type AnalyticsStorageAdapter, type AnalyticsTrackCatalog, type AnalyticsTrackCatalogItem, type CreateCatalogHandlerConfig, type CreateIngestHandlerConfig, type ExpressIngestHandlerOptions, type ExpressLikeRequest, type ExpressLikeResponse, type IngestContext, type IngestResult, type MaskConfig, type PostgresAdapterOptions, type PostgresQueryable, type StoredAnalyticsEvent, createAnalyticsServer, createCatalogHandler, createExpressCatalogHandler, createExpressIngestHandler, createFetchCatalogHandler, createFetchIngestHandler, createIngestHandler, createMemoryAdapter, createPostgresAdapter };

package/dist/index.js

@@ -0,0 +1,475 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createAnalyticsServer: () => createAnalyticsServer,
+  createCatalogHandler: () => createCatalogHandler,
+  createExpressCatalogHandler: () => createExpressCatalogHandler,
+  createExpressIngestHandler: () => createExpressIngestHandler,
+  createFetchCatalogHandler: () => createFetchCatalogHandler,
+  createFetchIngestHandler: () => createFetchIngestHandler,
+  createIngestHandler: () => createIngestHandler,
+  createMemoryAdapter: () => createMemoryAdapter,
+  createPostgresAdapter: () => createPostgresAdapter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/masking.ts
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+function shouldMask(path, key, config) {
+  if (config.paths?.includes(path)) return true;
+  if (config.keyPatterns?.some((pattern) => pattern.test(key))) return true;
+  return false;
+}
+function maskRecursive(input, config, event, parentPath = "") {
+  if (Array.isArray(input)) {
+    return input.map(
+      (item, index) => maskRecursive(item, config, event, parentPath ? `${parentPath}.${index}` : String(index))
+    );
+  }
+  if (!isPlainObject(input)) return input;
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    const path = parentPath ? `${parentPath}.${key}` : key;
+    if (shouldMask(path, key, config)) {
+      out[key] = config.maskField ? config.maskField({ path, key, value, event }) : config.maskValue ?? "***";
+      continue;
+    }
+    out[key] = maskRecursive(value, config, event, path);
+  }
+  return out;
+}
+function applyMasking(event, config) {
+  if (!config) return event;
+  return {
+    ...event,
+    props: maskRecursive(event.props, config, event) ?? {}
+  };
+}
+
+// src/validation.ts
+var import_zod = require("zod");
+var baseEventSchema = import_zod.z.object({
+  name: import_zod.z.string().min(1),
+  ts: import_zod.z.number().optional(),
+  appId: import_zod.z.string().min(1),
+  sessionId: import_zod.z.string().optional(),
+  url: import_zod.z.string().optional(),
+  path: import_zod.z.string().optional(),
+  ref: import_zod.z.string().optional(),
+  environment: import_zod.z.string().optional(),
+  props: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
+  tags: import_zod.z.array(import_zod.z.string()).optional(),
+  clientMeta: import_zod.z.object({
+    ip: import_zod.z.string().optional(),
+    userAgent: import_zod.z.string().optional(),
+    isMobile: import_zod.z.boolean().optional(),
+    os: import_zod.z.string().optional(),
+    platform: import_zod.z.string().optional(),
+    language: import_zod.z.string().optional(),
+    screen: import_zod.z.object({
+      width: import_zod.z.number(),
+      height: import_zod.z.number()
+    }).optional()
+  }).optional(),
+  writeKey: import_zod.z.string().optional()
+});
+function validateBasePayload(input) {
+  const parsed = baseEventSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        code: "invalid_payload",
+        message: "Invalid track payload",
+        details: parsed.error.issues
+      }
+    };
+  }
+  return { ok: true, data: parsed.data };
+}
+function validateAgainstAcceptedTracks(event, acceptedTracks, rejectUnknownTracks) {
+  if (!acceptedTracks || acceptedTracks.length === 0) return null;
+  const trackConfig = acceptedTracks.find((item) => item.trackName === event.name);
+  if (!trackConfig) {
+    if (!rejectUnknownTracks) return null;
+    return {
+      ok: false,
+      error: {
+        code: "track_not_allowed",
+        message: `Track '${event.name}' is not in the allowed track list`
+      }
+    };
+  }
+  const target = trackConfig.validateOn === "event" ? event : event.props;
+  const parsed = trackConfig.schema.safeParse(target);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        code: "schema_mismatch",
+        message: `Track '${event.name}' does not match the configured schema`,
+        details: parsed.error.issues
+      }
+    };
+  }
+  return null;
+}
+
+// src/create-analytics-server.ts
+function buildStoredEvent(input, context) {
+  return {
+    ...input,
+    ts: input.ts ?? Date.now(),
+    receivedAt: Date.now(),
+    props: input.props ?? {},
+    meta: {
+      ip: context?.ip,
+      userAgent: context?.userAgent,
+      requestId: context?.requestId
+    }
+  };
+}
+function createAnalyticsServer(config) {
+  const rejectUnknownTracks = config.rejectUnknownTracks ?? true;
+  const generatedAt = Date.now();
+  const trackCatalog = (config.acceptedTracks ?? []).map((track) => ({
+    trackName: track.trackName,
+    validateOn: track.validateOn ?? "props",
+    version: track.version ?? 1,
+    description: track.description,
+    tags: track.tags,
+    deprecated: track.deprecated,
+    schema: track.catalogSchema
+  }));
+  async function ingest(input, context) {
+    const payloadValidation = validateBasePayload(input);
+    if (!payloadValidation.ok) return payloadValidation;
+    const event = buildStoredEvent(payloadValidation.data, context);
+    const trackValidation = validateAgainstAcceptedTracks(
+      event,
+      config.acceptedTracks,
+      rejectUnknownTracks
+    );
+    if (trackValidation) return trackValidation;
+    const maskedEvent = applyMasking(event, config.masking);
+    try {
+      await config.storage.save(maskedEvent);
+      return {
+        ok: true,
+        event: maskedEvent
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: {
+          code: "storage_error",
+          message: "Failed to persist track",
+          details: error instanceof Error ? error.message : error
+        }
+      };
+    }
+  }
+  function getCatalog() {
+    return {
+      generatedAt,
+      tracks: [...trackCatalog]
+    };
+  }
+  return {
+    ingest,
+    getCatalog
+  };
+}
+
+// src/adapters/memory-adapter.ts
+function createMemoryAdapter(initialEvents = []) {
+  const events = [...initialEvents];
+  const adapter = {
+    async save(event) {
+      events.push(event);
+    },
+    async getAll(dateInit, dateEnd) {
+      if (dateInit === void 0 && dateEnd === void 0) return [...events];
+      return events.filter((event) => {
+        if (dateInit !== void 0 && event.ts < dateInit) return false;
+        if (dateEnd !== void 0 && event.ts > dateEnd) return false;
+        return true;
+      });
+    },
+    async clear(dateInit, dateEnd) {
+      const before = events.length;
+      if (dateInit === void 0 && dateEnd === void 0) {
+        events.length = 0;
+        return before;
+      }
+      const kept = events.filter((event) => {
+        if (dateInit !== void 0 && event.ts < dateInit) return true;
+        if (dateEnd !== void 0 && event.ts > dateEnd) return true;
+        if (dateInit === void 0 && dateEnd !== void 0) return event.ts > dateEnd;
+        return false;
+      });
+      events.length = 0;
+      events.push(...kept);
+      return before - events.length;
+    }
+  };
+  return adapter;
+}
+
+// src/adapters/postgres-adapter.ts
+function quoteIdentifier(identifier) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(identifier)) {
+    throw new Error(`Invalid SQL identifier: '${identifier}'`);
+  }
+  return `"${identifier}"`;
+}
+function buildDateRangeWhereClause(dateInit, dateEnd) {
+  const conditions = [];
+  const values = [];
+  if (dateInit !== void 0) {
+    conditions.push(`ts >= $${values.length + 1}`);
+    values.push(dateInit);
+  }
+  if (dateEnd !== void 0) {
+    conditions.push(`ts <= $${values.length + 1}`);
+    values.push(dateEnd);
+  }
+  if (conditions.length === 0) {
+    return { whereClause: "", values };
+  }
+  return {
+    whereClause: ` where ${conditions.join(" and ")}`,
+    values
+  };
+}
+function mapRowToStoredEvent(row) {
+  return {
+    name: row.name,
+    ts: row.ts,
+    appId: row.app_id,
+    sessionId: row.session_id ?? void 0,
+    url: row.url ?? void 0,
+    path: row.path ?? void 0,
+    ref: row.ref ?? void 0,
+    environment: row.environment ?? void 0,
+    props: row.props ?? {},
+    tags: row.tags ?? void 0,
+    clientMeta: row.client_meta ?? void 0,
+    writeKey: row.write_key ?? void 0,
+    receivedAt: row.received_at,
+    meta: row.meta ?? void 0
+  };
+}
+function extractQueryResultData(result) {
+  if (typeof result === "object" && result !== null) {
+    return result;
+  }
+  return {};
+}
+function createPostgresAdapter({
+  db,
+  tableName = "analytics_events",
+  schemaName
+}) {
+  const tableRef = schemaName ? `${quoteIdentifier(schemaName)}.${quoteIdentifier(tableName)}` : quoteIdentifier(tableName);
+  return {
+    async save(event) {
+      await db.query(
+        `
+          insert into ${tableRef}
+            (name, ts, app_id, session_id, url, path, ref, environment, props, tags, client_meta, write_key, received_at, meta)
+          values
+            ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10::text[], $11::jsonb, $12, $13, $14::jsonb)
+        `,
+        [
+          event.name,
+          event.ts,
+          event.appId,
+          event.sessionId ?? null,
+          event.url ?? null,
+          event.path ?? null,
+          event.ref ?? null,
+          event.environment ?? null,
+          event.props,
+          event.tags ?? null,
+          event.clientMeta ?? null,
+          event.writeKey ?? null,
+          event.receivedAt,
+          event.meta ?? null
+        ]
+      );
+    },
+    async getAll(dateInit, dateEnd) {
+      const { whereClause, values } = buildDateRangeWhereClause(dateInit, dateEnd);
+      const result = await db.query(
+        `
+          select
+            name,
+            ts,
+            app_id,
+            session_id,
+            url,
+            path,
+            ref,
+            environment,
+            props,
+            tags,
+            client_meta,
+            write_key,
+            received_at,
+            meta
+          from ${tableRef}${whereClause}
+          order by ts asc
+        `,
+        values
+      );
+      const rows = extractQueryResultData(result).rows ?? [];
+      return rows.map((row) => mapRowToStoredEvent(row));
+    },
+    async clear(dateInit, dateEnd) {
+      const { whereClause, values } = buildDateRangeWhereClause(dateInit, dateEnd);
+      const result = await db.query(`delete from ${tableRef}${whereClause}`, values);
+      return extractQueryResultData(result).rowCount ?? 0;
+    }
+  };
+}
+
+// src/http/create-express-catalog-handler.ts
+function createExpressCatalogHandler(server) {
+  return async function handle(req, res) {
+    if ((req.method ?? "GET").toUpperCase() !== "GET") {
+      return res.status(405).json({ ok: false, error: "method_not_allowed" });
+    }
+    return res.status(200).json({ ok: true, data: server.getCatalog() });
+  };
+}
+
+// src/http/create-express-handler.ts
+function getHeader(req, name) {
+  const lower = name.toLowerCase();
+  if (typeof req.get === "function") return req.get(lower) ?? req.get(name) ?? void 0;
+  if (typeof req.header === "function") return req.header(lower) ?? req.header(name) ?? void 0;
+  const raw = req.headers?.[lower] ?? req.headers?.[name];
+  if (Array.isArray(raw)) return raw[0];
+  return raw;
+}
+function extractContextFromExpress(req) {
+  return {
+    ip: req.ip ?? getHeader(req, "x-forwarded-for"),
+    userAgent: getHeader(req, "user-agent"),
+    requestId: getHeader(req, "x-request-id")
+  };
+}
+function resolveBody(body) {
+  if (typeof body === "string") {
+    return JSON.parse(body);
+  }
+  return body;
+}
+function createExpressIngestHandler(server, options = {}) {
+  return async function handle(req, res) {
+    if ((req.method ?? "GET").toUpperCase() !== "POST") {
+      return res.status(405).json({ ok: false, error: "method_not_allowed" });
+    }
+    let body;
+    try {
+      body = resolveBody(req.body);
+    } catch {
+      return res.status(400).json({ ok: false, error: "invalid_json" });
+    }
+    const context = options.getContext?.(req) ?? extractContextFromExpress(req);
+    const result = await server.ingest(body, context);
+    if (!result.ok) {
+      const status = result.error.code === "storage_error" ? 500 : result.error.code === "invalid_payload" || result.error.code === "schema_mismatch" ? 422 : 403;
+      return res.status(status).json({ ok: false, error: result.error });
+    }
+    return res.status(202).json({ ok: true });
+  };
+}
+
+// src/http/create-fetch-catalog-handler.ts
+function createFetchCatalogHandler(server) {
+  return async function handle(request) {
+    if (request.method !== "GET") {
+      return Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 });
+    }
+    return Response.json({ ok: true, data: server.getCatalog() }, { status: 200 });
+  };
+}
+
+// src/http/create-fetch-handler.ts
+function extractContext(request) {
+  return {
+    ip: request.headers.get("x-forwarded-for") ?? void 0,
+    userAgent: request.headers.get("user-agent") ?? void 0,
+    requestId: request.headers.get("x-request-id") ?? void 0
+  };
+}
+function createFetchIngestHandler(server) {
+  return async function handle(request) {
+    if (request.method !== "POST") {
+      return Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 });
+    }
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
+    }
+    const result = await server.ingest(body, extractContext(request));
+    if (!result.ok) {
+      const status = result.error.code === "storage_error" ? 500 : result.error.code === "invalid_payload" || result.error.code === "schema_mismatch" ? 422 : 403;
+      return Response.json({ ok: false, error: result.error }, { status });
+    }
+    return Response.json({ ok: true }, { status: 202 });
+  };
+}
+
+// src/http/create-catalog-handler.ts
+function createCatalogHandler(server, config = {}) {
+  if (config.adapter === "express") {
+    return createExpressCatalogHandler(server);
+  }
+  return createFetchCatalogHandler(server);
+}
+
+// src/http/create-ingest-handler.ts
+function createIngestHandler(server, config = {}) {
+  if (config.adapter === "express") {
+    return createExpressIngestHandler(server, config.express);
+  }
+  return createFetchIngestHandler(server);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAnalyticsServer,
+  createCatalogHandler,
+  createExpressCatalogHandler,
+  createExpressIngestHandler,
+  createFetchCatalogHandler,
+  createFetchIngestHandler,
+  createIngestHandler,
+  createMemoryAdapter,
+  createPostgresAdapter
+});

package/dist/index.mjs

@@ -0,0 +1,440 @@
+// src/masking.ts
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+function shouldMask(path, key, config) {
+  if (config.paths?.includes(path)) return true;
+  if (config.keyPatterns?.some((pattern) => pattern.test(key))) return true;
+  return false;
+}
+function maskRecursive(input, config, event, parentPath = "") {
+  if (Array.isArray(input)) {
+    return input.map(
+      (item, index) => maskRecursive(item, config, event, parentPath ? `${parentPath}.${index}` : String(index))
+    );
+  }
+  if (!isPlainObject(input)) return input;
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    const path = parentPath ? `${parentPath}.${key}` : key;
+    if (shouldMask(path, key, config)) {
+      out[key] = config.maskField ? config.maskField({ path, key, value, event }) : config.maskValue ?? "***";
+      continue;
+    }
+    out[key] = maskRecursive(value, config, event, path);
+  }
+  return out;
+}
+function applyMasking(event, config) {
+  if (!config) return event;
+  return {
+    ...event,
+    props: maskRecursive(event.props, config, event) ?? {}
+  };
+}
+
+// src/validation.ts
+import { z } from "zod";
+var baseEventSchema = z.object({
+  name: z.string().min(1),
+  ts: z.number().optional(),
+  appId: z.string().min(1),
+  sessionId: z.string().optional(),
+  url: z.string().optional(),
+  path: z.string().optional(),
+  ref: z.string().optional(),
+  environment: z.string().optional(),
+  props: z.record(z.string(), z.unknown()).optional(),
+  tags: z.array(z.string()).optional(),
+  clientMeta: z.object({
+    ip: z.string().optional(),
+    userAgent: z.string().optional(),
+    isMobile: z.boolean().optional(),
+    os: z.string().optional(),
+    platform: z.string().optional(),
+    language: z.string().optional(),
+    screen: z.object({
+      width: z.number(),
+      height: z.number()
+    }).optional()
+  }).optional(),
+  writeKey: z.string().optional()
+});
+function validateBasePayload(input) {
+  const parsed = baseEventSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        code: "invalid_payload",
+        message: "Invalid track payload",
+        details: parsed.error.issues
+      }
+    };
+  }
+  return { ok: true, data: parsed.data };
+}
+function validateAgainstAcceptedTracks(event, acceptedTracks, rejectUnknownTracks) {
+  if (!acceptedTracks || acceptedTracks.length === 0) return null;
+  const trackConfig = acceptedTracks.find((item) => item.trackName === event.name);
+  if (!trackConfig) {
+    if (!rejectUnknownTracks) return null;
+    return {
+      ok: false,
+      error: {
+        code: "track_not_allowed",
+        message: `Track '${event.name}' is not in the allowed track list`
+      }
+    };
+  }
+  const target = trackConfig.validateOn === "event" ? event : event.props;
+  const parsed = trackConfig.schema.safeParse(target);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        code: "schema_mismatch",
+        message: `Track '${event.name}' does not match the configured schema`,
+        details: parsed.error.issues
+      }
+    };
+  }
+  return null;
+}
+
+// src/create-analytics-server.ts
+function buildStoredEvent(input, context) {
+  return {
+    ...input,
+    ts: input.ts ?? Date.now(),
+    receivedAt: Date.now(),
+    props: input.props ?? {},
+    meta: {
+      ip: context?.ip,
+      userAgent: context?.userAgent,
+      requestId: context?.requestId
+    }
+  };
+}
+function createAnalyticsServer(config) {
+  const rejectUnknownTracks = config.rejectUnknownTracks ?? true;
+  const generatedAt = Date.now();
+  const trackCatalog = (config.acceptedTracks ?? []).map((track) => ({
+    trackName: track.trackName,
+    validateOn: track.validateOn ?? "props",
+    version: track.version ?? 1,
+    description: track.description,
+    tags: track.tags,
+    deprecated: track.deprecated,
+    schema: track.catalogSchema
+  }));
+  async function ingest(input, context) {
+    const payloadValidation = validateBasePayload(input);
+    if (!payloadValidation.ok) return payloadValidation;
+    const event = buildStoredEvent(payloadValidation.data, context);
+    const trackValidation = validateAgainstAcceptedTracks(
+      event,
+      config.acceptedTracks,
+      rejectUnknownTracks
+    );
+    if (trackValidation) return trackValidation;
+    const maskedEvent = applyMasking(event, config.masking);
+    try {
+      await config.storage.save(maskedEvent);
+      return {
+        ok: true,
+        event: maskedEvent
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: {
+          code: "storage_error",
+          message: "Failed to persist track",
+          details: error instanceof Error ? error.message : error
+        }
+      };
+    }
+  }
+  function getCatalog() {
+    return {
+      generatedAt,
+      tracks: [...trackCatalog]
+    };
+  }
+  return {
+    ingest,
+    getCatalog
+  };
+}
+
+// src/adapters/memory-adapter.ts
+function createMemoryAdapter(initialEvents = []) {
+  const events = [...initialEvents];
+  const adapter = {
+    async save(event) {
+      events.push(event);
+    },
+    async getAll(dateInit, dateEnd) {
+      if (dateInit === void 0 && dateEnd === void 0) return [...events];
+      return events.filter((event) => {
+        if (dateInit !== void 0 && event.ts < dateInit) return false;
+        if (dateEnd !== void 0 && event.ts > dateEnd) return false;
+        return true;
+      });
+    },
+    async clear(dateInit, dateEnd) {
+      const before = events.length;
+      if (dateInit === void 0 && dateEnd === void 0) {
+        events.length = 0;
+        return before;
+      }
+      const kept = events.filter((event) => {
+        if (dateInit !== void 0 && event.ts < dateInit) return true;
+        if (dateEnd !== void 0 && event.ts > dateEnd) return true;
+        if (dateInit === void 0 && dateEnd !== void 0) return event.ts > dateEnd;
+        return false;
+      });
+      events.length = 0;
+      events.push(...kept);
+      return before - events.length;
+    }
+  };
+  return adapter;
+}
+
+// src/adapters/postgres-adapter.ts
+function quoteIdentifier(identifier) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(identifier)) {
+    throw new Error(`Invalid SQL identifier: '${identifier}'`);
+  }
+  return `"${identifier}"`;
+}
+function buildDateRangeWhereClause(dateInit, dateEnd) {
+  const conditions = [];
+  const values = [];
+  if (dateInit !== void 0) {
+    conditions.push(`ts >= $${values.length + 1}`);
+    values.push(dateInit);
+  }
+  if (dateEnd !== void 0) {
+    conditions.push(`ts <= $${values.length + 1}`);
+    values.push(dateEnd);
+  }
+  if (conditions.length === 0) {
+    return { whereClause: "", values };
+  }
+  return {
+    whereClause: ` where ${conditions.join(" and ")}`,
+    values
+  };
+}
+function mapRowToStoredEvent(row) {
+  return {
+    name: row.name,
+    ts: row.ts,
+    appId: row.app_id,
+    sessionId: row.session_id ?? void 0,
+    url: row.url ?? void 0,
+    path: row.path ?? void 0,
+    ref: row.ref ?? void 0,
+    environment: row.environment ?? void 0,
+    props: row.props ?? {},
+    tags: row.tags ?? void 0,
+    clientMeta: row.client_meta ?? void 0,
+    writeKey: row.write_key ?? void 0,
+    receivedAt: row.received_at,
+    meta: row.meta ?? void 0
+  };
+}
+function extractQueryResultData(result) {
+  if (typeof result === "object" && result !== null) {
+    return result;
+  }
+  return {};
+}
+function createPostgresAdapter({
+  db,
+  tableName = "analytics_events",
+  schemaName
+}) {
+  const tableRef = schemaName ? `${quoteIdentifier(schemaName)}.${quoteIdentifier(tableName)}` : quoteIdentifier(tableName);
+  return {
+    async save(event) {
+      await db.query(
+        `
+          insert into ${tableRef}
+            (name, ts, app_id, session_id, url, path, ref, environment, props, tags, client_meta, write_key, received_at, meta)
+          values
+            ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10::text[], $11::jsonb, $12, $13, $14::jsonb)
+        `,
+        [
+          event.name,
+          event.ts,
+          event.appId,
+          event.sessionId ?? null,
+          event.url ?? null,
+          event.path ?? null,
+          event.ref ?? null,
+          event.environment ?? null,
+          event.props,
+          event.tags ?? null,
+          event.clientMeta ?? null,
+          event.writeKey ?? null,
+          event.receivedAt,
+          event.meta ?? null
+        ]
+      );
+    },
+    async getAll(dateInit, dateEnd) {
+      const { whereClause, values } = buildDateRangeWhereClause(dateInit, dateEnd);
+      const result = await db.query(
+        `
+          select
+            name,
+            ts,
+            app_id,
+            session_id,
+            url,
+            path,
+            ref,
+            environment,
+            props,
+            tags,
+            client_meta,
+            write_key,
+            received_at,
+            meta
+          from ${tableRef}${whereClause}
+          order by ts asc
+        `,
+        values
+      );
+      const rows = extractQueryResultData(result).rows ?? [];
+      return rows.map((row) => mapRowToStoredEvent(row));
+    },
+    async clear(dateInit, dateEnd) {
+      const { whereClause, values } = buildDateRangeWhereClause(dateInit, dateEnd);
+      const result = await db.query(`delete from ${tableRef}${whereClause}`, values);
+      return extractQueryResultData(result).rowCount ?? 0;
+    }
+  };
+}
+
+// src/http/create-express-catalog-handler.ts
+function createExpressCatalogHandler(server) {
+  return async function handle(req, res) {
+    if ((req.method ?? "GET").toUpperCase() !== "GET") {
+      return res.status(405).json({ ok: false, error: "method_not_allowed" });
+    }
+    return res.status(200).json({ ok: true, data: server.getCatalog() });
+  };
+}
+
+// src/http/create-express-handler.ts
+function getHeader(req, name) {
+  const lower = name.toLowerCase();
+  if (typeof req.get === "function") return req.get(lower) ?? req.get(name) ?? void 0;
+  if (typeof req.header === "function") return req.header(lower) ?? req.header(name) ?? void 0;
+  const raw = req.headers?.[lower] ?? req.headers?.[name];
+  if (Array.isArray(raw)) return raw[0];
+  return raw;
+}
+function extractContextFromExpress(req) {
+  return {
+    ip: req.ip ?? getHeader(req, "x-forwarded-for"),
+    userAgent: getHeader(req, "user-agent"),
+    requestId: getHeader(req, "x-request-id")
+  };
+}
+function resolveBody(body) {
+  if (typeof body === "string") {
+    return JSON.parse(body);
+  }
+  return body;
+}
+function createExpressIngestHandler(server, options = {}) {
+  return async function handle(req, res) {
+    if ((req.method ?? "GET").toUpperCase() !== "POST") {
+      return res.status(405).json({ ok: false, error: "method_not_allowed" });
+    }
+    let body;
+    try {
+      body = resolveBody(req.body);
+    } catch {
+      return res.status(400).json({ ok: false, error: "invalid_json" });
+    }
+    const context = options.getContext?.(req) ?? extractContextFromExpress(req);
+    const result = await server.ingest(body, context);
+    if (!result.ok) {
+      const status = result.error.code === "storage_error" ? 500 : result.error.code === "invalid_payload" || result.error.code === "schema_mismatch" ? 422 : 403;
+      return res.status(status).json({ ok: false, error: result.error });
+    }
+    return res.status(202).json({ ok: true });
+  };
+}
+
+// src/http/create-fetch-catalog-handler.ts
+function createFetchCatalogHandler(server) {
+  return async function handle(request) {
+    if (request.method !== "GET") {
+      return Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 });
+    }
+    return Response.json({ ok: true, data: server.getCatalog() }, { status: 200 });
+  };
+}
+
+// src/http/create-fetch-handler.ts
+function extractContext(request) {
+  return {
+    ip: request.headers.get("x-forwarded-for") ?? void 0,
+    userAgent: request.headers.get("user-agent") ?? void 0,
+    requestId: request.headers.get("x-request-id") ?? void 0
+  };
+}
+function createFetchIngestHandler(server) {
+  return async function handle(request) {
+    if (request.method !== "POST") {
+      return Response.json({ ok: false, error: "method_not_allowed" }, { status: 405 });
+    }
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      return Response.json({ ok: false, error: "invalid_json" }, { status: 400 });
+    }
+    const result = await server.ingest(body, extractContext(request));
+    if (!result.ok) {
+      const status = result.error.code === "storage_error" ? 500 : result.error.code === "invalid_payload" || result.error.code === "schema_mismatch" ? 422 : 403;
+      return Response.json({ ok: false, error: result.error }, { status });
+    }
+    return Response.json({ ok: true }, { status: 202 });
+  };
+}
+
+// src/http/create-catalog-handler.ts
+function createCatalogHandler(server, config = {}) {
+  if (config.adapter === "express") {
+    return createExpressCatalogHandler(server);
+  }
+  return createFetchCatalogHandler(server);
+}
+
+// src/http/create-ingest-handler.ts
+function createIngestHandler(server, config = {}) {
+  if (config.adapter === "express") {
+    return createExpressIngestHandler(server, config.express);
+  }
+  return createFetchIngestHandler(server);
+}
+export {
+  createAnalyticsServer,
+  createCatalogHandler,
+  createExpressCatalogHandler,
+  createExpressIngestHandler,
+  createFetchCatalogHandler,
+  createFetchIngestHandler,
+  createIngestHandler,
+  createMemoryAdapter,
+  createPostgresAdapter
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@xray-analytics/analytics-server",
+  "version": "0.0.2",
+  "private": false,
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3"
+  }
+}