@xrayradar/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,146 @@
+/**
+ * Event severity levels (aligned with server and Python SDK).
+ */
+type Level = "fatal" | "error" | "warning" | "info" | "debug";
+/**
+ * Breadcrumb type hint.
+ */
+type BreadcrumbType = "default" | "http" | "navigation" | "ui" | "console" | "error" | "query" | "user";
+interface BreadcrumbData {
+    timestamp: string;
+    message: string;
+    category?: string;
+    level?: Level;
+    data?: Record<string, unknown>;
+    type?: BreadcrumbType;
+}
+interface UserContext {
+    id?: string;
+    username?: string;
+    email?: string;
+    ip_address?: string;
+    data?: Record<string, unknown>;
+}
+interface RequestContext {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    query_string?: string;
+    data?: string;
+    env?: Record<string, string>;
+}
+interface EventContexts {
+    user?: UserContext | null;
+    request?: RequestContext | null;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    server_name?: string;
+    release?: string;
+    environment?: string;
+}
+interface StackFrame {
+    filename: string;
+    function: string;
+    lineno: number;
+    colno?: number;
+    abs_path?: string;
+    context_line?: string;
+    pre_context?: string[];
+    post_context?: string[];
+    in_app?: boolean;
+}
+interface ExceptionValue {
+    type: string;
+    value: string;
+    module?: string;
+    stacktrace?: {
+        frames: StackFrame[];
+    };
+}
+interface EventException {
+    values: ExceptionValue[];
+}
+/**
+ * Event payload sent to POST /api/{project_id}/store/
+ */
+interface EventPayload {
+    event_id: string;
+    timestamp: string;
+    level: Level;
+    message: string;
+    platform: string;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    contexts: EventContexts;
+    breadcrumbs: BreadcrumbData[];
+    fingerprint?: string[];
+    exception?: EventException;
+    modules?: Record<string, string>;
+}
+interface Transport {
+    sendEvent(event: EventPayload): void | Promise<void>;
+    flush?(timeout?: number): void | Promise<void>;
+    close?(): void | Promise<void>;
+}
+interface ClientOptions {
+    dsn?: string;
+    authToken?: string;
+    debug?: boolean;
+    environment?: string;
+    release?: string;
+    serverName?: string;
+    sampleRate?: number;
+    maxBreadcrumbs?: number;
+    beforeSend?: (event: EventPayload) => EventPayload | null | Promise<EventPayload | null>;
+    transport?: Transport;
+}
+
+declare class Scope {
+    private _breadcrumbs;
+    private _context;
+    maxBreadcrumbs: number;
+    addBreadcrumb(message: string, options?: {
+        category?: string;
+        level?: Level;
+        data?: Record<string, unknown>;
+        type?: string;
+        timestamp?: string;
+    }): void;
+    clearBreadcrumbs(): void;
+    getBreadcrumbs(): BreadcrumbData[];
+    setUser(user: UserContext | null): void;
+    setTag(key: string, value: string): void;
+    setExtra(key: string, value: unknown): void;
+    setRequest(request: RequestContext | null): void;
+    setContext(key: string, data: Record<string, unknown>): void;
+    getContext(): EventContexts;
+    applyToContext(overrides: Partial<EventContexts>): void;
+}
+
+/**
+ * Build event payload from an Error. Server can compute fingerprint if not provided.
+ */
+declare function eventFromException(error: Error, level: Level, message?: string, scope?: Scope): EventPayload;
+/**
+ * Build event payload from a message (no exception).
+ */
+declare function eventFromMessage(message: string, level: Level, scope?: Scope): EventPayload;
+/**
+ * Check if level string is valid.
+ */
+declare function normalizeLevel(level: string): Level;
+/**
+ * Apply sampleRate: return true if event should be sent (random < sampleRate).
+ */
+declare function shouldSample(sampleRate: number): boolean;
+
+declare const SDK_NAME = "xrayradar.javascript";
+declare const SDK_VERSION = "0.1.0";
+declare function getSdkInfo(): {
+    name: string;
+    version: string;
+};
+
+export { type BreadcrumbData, type BreadcrumbType, type ClientOptions, type EventContexts, type EventException, type EventPayload, type ExceptionValue, type Level, type RequestContext, SDK_NAME, SDK_VERSION, Scope, type StackFrame, type Transport, type UserContext, eventFromException, eventFromMessage, getSdkInfo, normalizeLevel, shouldSample };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Event severity levels (aligned with server and Python SDK).
+ */
+type Level = "fatal" | "error" | "warning" | "info" | "debug";
+/**
+ * Breadcrumb type hint.
+ */
+type BreadcrumbType = "default" | "http" | "navigation" | "ui" | "console" | "error" | "query" | "user";
+interface BreadcrumbData {
+    timestamp: string;
+    message: string;
+    category?: string;
+    level?: Level;
+    data?: Record<string, unknown>;
+    type?: BreadcrumbType;
+}
+interface UserContext {
+    id?: string;
+    username?: string;
+    email?: string;
+    ip_address?: string;
+    data?: Record<string, unknown>;
+}
+interface RequestContext {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string>;
+    query_string?: string;
+    data?: string;
+    env?: Record<string, string>;
+}
+interface EventContexts {
+    user?: UserContext | null;
+    request?: RequestContext | null;
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+    server_name?: string;
+    release?: string;
+    environment?: string;
+}
+interface StackFrame {
+    filename: string;
+    function: string;
+    lineno: number;
+    colno?: number;
+    abs_path?: string;
+    context_line?: string;
+    pre_context?: string[];
+    post_context?: string[];
+    in_app?: boolean;
+}
+interface ExceptionValue {
+    type: string;
+    value: string;
+    module?: string;
+    stacktrace?: {
+        frames: StackFrame[];
+    };
+}
+interface EventException {
+    values: ExceptionValue[];
+}
+/**
+ * Event payload sent to POST /api/{project_id}/store/
+ */
+interface EventPayload {
+    event_id: string;
+    timestamp: string;
+    level: Level;
+    message: string;
+    platform: string;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    contexts: EventContexts;
+    breadcrumbs: BreadcrumbData[];
+    fingerprint?: string[];
+    exception?: EventException;
+    modules?: Record<string, string>;
+}
+interface Transport {
+    sendEvent(event: EventPayload): void | Promise<void>;
+    flush?(timeout?: number): void | Promise<void>;
+    close?(): void | Promise<void>;
+}
+interface ClientOptions {
+    dsn?: string;
+    authToken?: string;
+    debug?: boolean;
+    environment?: string;
+    release?: string;
+    serverName?: string;
+    sampleRate?: number;
+    maxBreadcrumbs?: number;
+    beforeSend?: (event: EventPayload) => EventPayload | null | Promise<EventPayload | null>;
+    transport?: Transport;
+}
+
+declare class Scope {
+    private _breadcrumbs;
+    private _context;
+    maxBreadcrumbs: number;
+    addBreadcrumb(message: string, options?: {
+        category?: string;
+        level?: Level;
+        data?: Record<string, unknown>;
+        type?: string;
+        timestamp?: string;
+    }): void;
+    clearBreadcrumbs(): void;
+    getBreadcrumbs(): BreadcrumbData[];
+    setUser(user: UserContext | null): void;
+    setTag(key: string, value: string): void;
+    setExtra(key: string, value: unknown): void;
+    setRequest(request: RequestContext | null): void;
+    setContext(key: string, data: Record<string, unknown>): void;
+    getContext(): EventContexts;
+    applyToContext(overrides: Partial<EventContexts>): void;
+}
+
+/**
+ * Build event payload from an Error. Server can compute fingerprint if not provided.
+ */
+declare function eventFromException(error: Error, level: Level, message?: string, scope?: Scope): EventPayload;
+/**
+ * Build event payload from a message (no exception).
+ */
+declare function eventFromMessage(message: string, level: Level, scope?: Scope): EventPayload;
+/**
+ * Check if level string is valid.
+ */
+declare function normalizeLevel(level: string): Level;
+/**
+ * Apply sampleRate: return true if event should be sent (random < sampleRate).
+ */
+declare function shouldSample(sampleRate: number): boolean;
+
+declare const SDK_NAME = "xrayradar.javascript";
+declare const SDK_VERSION = "0.1.0";
+declare function getSdkInfo(): {
+    name: string;
+    version: string;
+};
+
+export { type BreadcrumbData, type BreadcrumbType, type ClientOptions, type EventContexts, type EventException, type EventPayload, type ExceptionValue, type Level, type RequestContext, SDK_NAME, SDK_VERSION, Scope, type StackFrame, type Transport, type UserContext, eventFromException, eventFromMessage, getSdkInfo, normalizeLevel, shouldSample };

package/dist/index.js

@@ -0,0 +1,213 @@
+"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, {
+  SDK_NAME: () => SDK_NAME,
+  SDK_VERSION: () => SDK_VERSION,
+  Scope: () => Scope,
+  eventFromException: () => eventFromException,
+  eventFromMessage: () => eventFromMessage,
+  getSdkInfo: () => getSdkInfo,
+  normalizeLevel: () => normalizeLevel,
+  shouldSample: () => shouldSample
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/scope.ts
+var DEFAULT_MAX_BREADCRUMBS = 100;
+var Scope = class {
+  constructor() {
+    this._breadcrumbs = [];
+    this._context = {
+      tags: {},
+      extra: {}
+    };
+    this.maxBreadcrumbs = DEFAULT_MAX_BREADCRUMBS;
+  }
+  addBreadcrumb(message, options) {
+    const crumb = {
+      timestamp: options?.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+      message,
+      category: options?.category,
+      level: options?.level,
+      data: options?.data ?? {},
+      type: options?.type ?? "default"
+    };
+    this._breadcrumbs.push(crumb);
+    if (this._breadcrumbs.length > this.maxBreadcrumbs) {
+      this._breadcrumbs = this._breadcrumbs.slice(-this.maxBreadcrumbs);
+    }
+  }
+  clearBreadcrumbs() {
+    this._breadcrumbs = [];
+  }
+  getBreadcrumbs() {
+    return [...this._breadcrumbs];
+  }
+  setUser(user) {
+    this._context.user = user ?? void 0;
+  }
+  setTag(key, value) {
+    if (!this._context.tags) this._context.tags = {};
+    this._context.tags[key] = value;
+  }
+  setExtra(key, value) {
+    if (!this._context.extra) this._context.extra = {};
+    this._context.extra[key] = value;
+  }
+  setRequest(request) {
+    this._context.request = request ?? void 0;
+  }
+  setContext(key, data) {
+    if (key === "user") {
+      this._context.user = data;
+    } else if (key === "request") {
+      this._context.request = data;
+    } else {
+      if (!this._context.extra) this._context.extra = {};
+      this._context.extra[key] = data;
+    }
+  }
+  getContext() {
+    return { ...this._context };
+  }
+  applyToContext(overrides) {
+    if (overrides.user !== void 0) this._context.user = overrides.user;
+    if (overrides.request !== void 0) this._context.request = overrides.request;
+    if (overrides.tags) this._context.tags = { ...this._context.tags, ...overrides.tags };
+    if (overrides.extra) this._context.extra = { ...this._context.extra, ...overrides.extra };
+    if (overrides.server_name !== void 0) this._context.server_name = overrides.server_name;
+    if (overrides.release !== void 0) this._context.release = overrides.release;
+    if (overrides.environment !== void 0) this._context.environment = overrides.environment;
+  }
+};
+
+// src/sdk.ts
+var SDK_NAME = "xrayradar.javascript";
+var SDK_VERSION = "0.1.0";
+function getSdkInfo() {
+  return { name: SDK_NAME, version: SDK_VERSION };
+}
+
+// src/event.ts
+var LEVELS = ["fatal", "error", "warning", "info", "debug"];
+function parseStack(err) {
+  const stack = err.stack;
+  if (!stack) return [];
+  const lines = stack.split("\n").slice(1);
+  const frames = [];
+  const re = new RegExp(
+    "^\\s*at (?:(.+?) \\()?(?:(.+?):(\\d+):(\\d+))\\)?$|^\\s*at (.+?):(\\d+):(\\d+)$"
+  );
+  for (const line of lines) {
+    const m = line.match(re);
+    if (!m) continue;
+    let functionName = "?";
+    let filename = "";
+    let lineno = 0;
+    let colno;
+    if (m[1] !== void 0 && m[2] !== void 0) {
+      functionName = m[1].trim();
+      filename = m[2];
+      lineno = parseInt(m[3] ?? "0", 10) || 0;
+      colno = parseInt(m[4] ?? "0", 10) || void 0;
+    } else if (m[5] !== void 0) {
+      filename = m[5];
+      lineno = parseInt(m[6] ?? "0", 10) || 0;
+      colno = parseInt(m[7] ?? "0", 10) || void 0;
+    }
+    const isInApp = !filename.includes("node_modules") && !filename.includes("<anonymous>") && !/^internal\//.test(filename);
+    frames.push({
+      filename,
+      function: functionName,
+      lineno,
+      colno,
+      abs_path: filename,
+      in_app: isInApp
+    });
+  }
+  return frames.reverse();
+}
+function eventFromException(error, level, message, scope) {
+  const frames = parseStack(error);
+  const exception = {
+    values: [
+      {
+        type: error.name,
+        value: error.message,
+        stacktrace: { frames }
+      }
+    ]
+  };
+  const contexts = scope?.getContext() ?? { tags: {}, extra: {} };
+  const breadcrumbs = scope?.getBreadcrumbs() ?? [];
+  const payload = {
+    event_id: crypto.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    message: message ?? `${error.name}: ${error.message}`,
+    platform: "javascript",
+    sdk: getSdkInfo(),
+    contexts,
+    breadcrumbs,
+    exception,
+    fingerprint: [error.name, error.message, frames[0]?.function].filter(
+      (x) => typeof x === "string" && x.length > 0
+    )
+  };
+  return payload;
+}
+function eventFromMessage(message, level, scope) {
+  const contexts = scope?.getContext() ?? { tags: {}, extra: {} };
+  const breadcrumbs = scope?.getBreadcrumbs() ?? [];
+  return {
+    event_id: crypto.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    message,
+    platform: "javascript",
+    sdk: getSdkInfo(),
+    contexts,
+    breadcrumbs,
+    fingerprint: [message]
+  };
+}
+function normalizeLevel(level) {
+  const lower = level.toLowerCase();
+  if (LEVELS.includes(lower)) return lower;
+  return "error";
+}
+function shouldSample(sampleRate) {
+  if (sampleRate >= 1) return true;
+  if (sampleRate <= 0) return false;
+  return Math.random() < sampleRate;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SDK_NAME,
+  SDK_VERSION,
+  Scope,
+  eventFromException,
+  eventFromMessage,
+  getSdkInfo,
+  normalizeLevel,
+  shouldSample
+});

package/dist/index.mjs

@@ -0,0 +1,179 @@
+// src/scope.ts
+var DEFAULT_MAX_BREADCRUMBS = 100;
+var Scope = class {
+  constructor() {
+    this._breadcrumbs = [];
+    this._context = {
+      tags: {},
+      extra: {}
+    };
+    this.maxBreadcrumbs = DEFAULT_MAX_BREADCRUMBS;
+  }
+  addBreadcrumb(message, options) {
+    const crumb = {
+      timestamp: options?.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+      message,
+      category: options?.category,
+      level: options?.level,
+      data: options?.data ?? {},
+      type: options?.type ?? "default"
+    };
+    this._breadcrumbs.push(crumb);
+    if (this._breadcrumbs.length > this.maxBreadcrumbs) {
+      this._breadcrumbs = this._breadcrumbs.slice(-this.maxBreadcrumbs);
+    }
+  }
+  clearBreadcrumbs() {
+    this._breadcrumbs = [];
+  }
+  getBreadcrumbs() {
+    return [...this._breadcrumbs];
+  }
+  setUser(user) {
+    this._context.user = user ?? void 0;
+  }
+  setTag(key, value) {
+    if (!this._context.tags) this._context.tags = {};
+    this._context.tags[key] = value;
+  }
+  setExtra(key, value) {
+    if (!this._context.extra) this._context.extra = {};
+    this._context.extra[key] = value;
+  }
+  setRequest(request) {
+    this._context.request = request ?? void 0;
+  }
+  setContext(key, data) {
+    if (key === "user") {
+      this._context.user = data;
+    } else if (key === "request") {
+      this._context.request = data;
+    } else {
+      if (!this._context.extra) this._context.extra = {};
+      this._context.extra[key] = data;
+    }
+  }
+  getContext() {
+    return { ...this._context };
+  }
+  applyToContext(overrides) {
+    if (overrides.user !== void 0) this._context.user = overrides.user;
+    if (overrides.request !== void 0) this._context.request = overrides.request;
+    if (overrides.tags) this._context.tags = { ...this._context.tags, ...overrides.tags };
+    if (overrides.extra) this._context.extra = { ...this._context.extra, ...overrides.extra };
+    if (overrides.server_name !== void 0) this._context.server_name = overrides.server_name;
+    if (overrides.release !== void 0) this._context.release = overrides.release;
+    if (overrides.environment !== void 0) this._context.environment = overrides.environment;
+  }
+};
+
+// src/sdk.ts
+var SDK_NAME = "xrayradar.javascript";
+var SDK_VERSION = "0.1.0";
+function getSdkInfo() {
+  return { name: SDK_NAME, version: SDK_VERSION };
+}
+
+// src/event.ts
+var LEVELS = ["fatal", "error", "warning", "info", "debug"];
+function parseStack(err) {
+  const stack = err.stack;
+  if (!stack) return [];
+  const lines = stack.split("\n").slice(1);
+  const frames = [];
+  const re = new RegExp(
+    "^\\s*at (?:(.+?) \\()?(?:(.+?):(\\d+):(\\d+))\\)?$|^\\s*at (.+?):(\\d+):(\\d+)$"
+  );
+  for (const line of lines) {
+    const m = line.match(re);
+    if (!m) continue;
+    let functionName = "?";
+    let filename = "";
+    let lineno = 0;
+    let colno;
+    if (m[1] !== void 0 && m[2] !== void 0) {
+      functionName = m[1].trim();
+      filename = m[2];
+      lineno = parseInt(m[3] ?? "0", 10) || 0;
+      colno = parseInt(m[4] ?? "0", 10) || void 0;
+    } else if (m[5] !== void 0) {
+      filename = m[5];
+      lineno = parseInt(m[6] ?? "0", 10) || 0;
+      colno = parseInt(m[7] ?? "0", 10) || void 0;
+    }
+    const isInApp = !filename.includes("node_modules") && !filename.includes("<anonymous>") && !/^internal\//.test(filename);
+    frames.push({
+      filename,
+      function: functionName,
+      lineno,
+      colno,
+      abs_path: filename,
+      in_app: isInApp
+    });
+  }
+  return frames.reverse();
+}
+function eventFromException(error, level, message, scope) {
+  const frames = parseStack(error);
+  const exception = {
+    values: [
+      {
+        type: error.name,
+        value: error.message,
+        stacktrace: { frames }
+      }
+    ]
+  };
+  const contexts = scope?.getContext() ?? { tags: {}, extra: {} };
+  const breadcrumbs = scope?.getBreadcrumbs() ?? [];
+  const payload = {
+    event_id: crypto.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    message: message ?? `${error.name}: ${error.message}`,
+    platform: "javascript",
+    sdk: getSdkInfo(),
+    contexts,
+    breadcrumbs,
+    exception,
+    fingerprint: [error.name, error.message, frames[0]?.function].filter(
+      (x) => typeof x === "string" && x.length > 0
+    )
+  };
+  return payload;
+}
+function eventFromMessage(message, level, scope) {
+  const contexts = scope?.getContext() ?? { tags: {}, extra: {} };
+  const breadcrumbs = scope?.getBreadcrumbs() ?? [];
+  return {
+    event_id: crypto.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    message,
+    platform: "javascript",
+    sdk: getSdkInfo(),
+    contexts,
+    breadcrumbs,
+    fingerprint: [message]
+  };
+}
+function normalizeLevel(level) {
+  const lower = level.toLowerCase();
+  if (LEVELS.includes(lower)) return lower;
+  return "error";
+}
+function shouldSample(sampleRate) {
+  if (sampleRate >= 1) return true;
+  if (sampleRate <= 0) return false;
+  return Math.random() < sampleRate;
+}
+export {
+  SDK_NAME,
+  SDK_VERSION,
+  Scope,
+  eventFromException,
+  eventFromMessage,
+  getSdkInfo,
+  normalizeLevel,
+  shouldSample
+};

package/package.json

@@ -0,0 +1 @@
+{"name":"@xrayradar/core","version":"0.1.0","description":"XrayRadar SDK core – types, scope, breadcrumbs, transport interface","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"files":["dist"],"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean","test":"vitest run","lint":"eslint src","clean":"rm -rf dist"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.3.3","vitest":"^4.0.0"}}