@vigilly/core 0.1.0

package/dist/dsn.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Vigilly DSN parsing.
+ *
+ * A Vigilly DSN is a standard Sentry-shaped DSN:
+ *
+ *     https://<publicKey>@<host>/<projectId>
+ *
+ * e.g. `https://<publicKey>@vigilly.dev/<projectId>`. The host is the Vigilly
+ * Observe ingest host (`vigilly.dev` in prod, `staging.vigilly.dev` /
+ * `local.vigilly.dev` for other envs) and is used AS-IS. The public key
+ * identifies the service to Vigilly ingest; the projectId is the DSN path
+ * segment (present for Sentry-DSN-format compatibility, not used for auth).
+ *
+ * Vigilly's ingest route is `<host>/api/observe/<projectId>/envelope/`, which is
+ * NOT the path a stock Sentry DSN derives (`<host>/api/<projectId>/envelope/`).
+ * The wrapper bridges that gap with the SDK's `tunnel` option — see `options.ts`.
+ */
+export interface VigillyDsnComponents {
+    /** DSN public key — identifies the service to Vigilly ingest (auth). */
+    publicKey: string;
+    /** URL protocol, e.g. `https`. */
+    protocol: string;
+    /** Ingest host, used as-is, e.g. `vigilly.dev`. */
+    host: string;
+    /** Project identifier from the DSN path; used in the ingest path. */
+    projectId: string;
+}
+export declare class InvalidVigillyDsnError extends Error {
+    constructor(dsn: string, reason: string);
+}
+/**
+ * Parse a Vigilly DSN into its components.
+ *
+ * @throws {InvalidVigillyDsnError} when the DSN is missing, malformed, or lacks a
+ *   public key / host.
+ */
+export declare function parseVigillyDsn(dsn: string): VigillyDsnComponents;
+/**
+ * The Vigilly envelope ingest URL for a parsed DSN. Used as the Sentry SDK's
+ * `tunnel` so envelopes land on Vigilly's route shape rather than the path a
+ * stock Sentry DSN would derive.
+ */
+export declare function envelopeTunnelUrl(c: VigillyDsnComponents): string;
+/**
+ * A Sentry-valid DSN (`<protocol>://<publicKey>@<host>/0`) synthesised from a
+ * Vigilly DSN. The underlying Sentry SDK requires a (numeric) project id in the
+ * DSN path even when a `tunnel` overrides the transport URL; this DSN also seeds
+ * the `dsn` field of the envelope header that Vigilly ingest reads for the public
+ * key. The real Vigilly project id lives in the tunnel path, not here.
+ */
+export declare function toSentryDsn(c: VigillyDsnComponents): string;
+//# sourceMappingURL=dsn.d.ts.map

package/dist/dsn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsn.d.ts","sourceRoot":"","sources":["../src/dsn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAIxC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAyCjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAEjE;AAYD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAE3D"}

package/dist/dsn.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Vigilly DSN parsing.
+ *
+ * A Vigilly DSN is a standard Sentry-shaped DSN:
+ *
+ *     https://<publicKey>@<host>/<projectId>
+ *
+ * e.g. `https://<publicKey>@vigilly.dev/<projectId>`. The host is the Vigilly
+ * Observe ingest host (`vigilly.dev` in prod, `staging.vigilly.dev` /
+ * `local.vigilly.dev` for other envs) and is used AS-IS. The public key
+ * identifies the service to Vigilly ingest; the projectId is the DSN path
+ * segment (present for Sentry-DSN-format compatibility, not used for auth).
+ *
+ * Vigilly's ingest route is `<host>/api/observe/<projectId>/envelope/`, which is
+ * NOT the path a stock Sentry DSN derives (`<host>/api/<projectId>/envelope/`).
+ * The wrapper bridges that gap with the SDK's `tunnel` option — see `options.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidVigillyDsnError = void 0;
+exports.parseVigillyDsn = parseVigillyDsn;
+exports.envelopeTunnelUrl = envelopeTunnelUrl;
+exports.toSentryDsn = toSentryDsn;
+class InvalidVigillyDsnError extends Error {
+    constructor(dsn, reason) {
+        super(`Invalid Vigilly DSN "${dsn}": ${reason}`);
+        this.name = "InvalidVigillyDsnError";
+    }
+}
+exports.InvalidVigillyDsnError = InvalidVigillyDsnError;
+/**
+ * Parse a Vigilly DSN into its components.
+ *
+ * @throws {InvalidVigillyDsnError} when the DSN is missing, malformed, or lacks a
+ *   public key / host.
+ */
+function parseVigillyDsn(dsn) {
+    if (!dsn || typeof dsn !== "string") {
+        throw new InvalidVigillyDsnError(String(dsn), "a non-empty DSN string is required");
+    }
+    let url;
+    try {
+        url = new URL(dsn);
+    }
+    catch {
+        throw new InvalidVigillyDsnError(dsn, "not a valid URL");
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new InvalidVigillyDsnError(dsn, "protocol must be http or https");
+    }
+    const publicKey = url.username;
+    if (!publicKey) {
+        throw new InvalidVigillyDsnError(dsn, "missing public key (expected https://<publicKey>@<host>)");
+    }
+    if (url.password) {
+        throw new InvalidVigillyDsnError(dsn, "DSN must not contain a secret — only the public key");
+    }
+    const host = url.host; // used as-is; includes port if present
+    if (!host) {
+        throw new InvalidVigillyDsnError(dsn, "missing host");
+    }
+    const protocol = url.protocol.replace(":", "");
+    // Project id is the DSN path segment.
+    const projectId = url.pathname.split("/").filter(Boolean).pop() || "";
+    if (!projectId) {
+        throw new InvalidVigillyDsnError(dsn, "missing project id (expected https://<publicKey>@<host>/<projectId>)");
+    }
+    return { publicKey, protocol, host, projectId };
+}
+/**
+ * The Vigilly envelope ingest URL for a parsed DSN. Used as the Sentry SDK's
+ * `tunnel` so envelopes land on Vigilly's route shape rather than the path a
+ * stock Sentry DSN would derive.
+ */
+function envelopeTunnelUrl(c) {
+    return `${c.protocol}://${c.host}/api/observe/${c.projectId}/envelope/`;
+}
+/**
+ * Placeholder project id used in the synthesised Sentry DSN. The Sentry SDK
+ * validates that a DSN's project id is purely numeric, while a Vigilly project
+ * id may be a non-numeric slug. The synthesised DSN's project id is irrelevant
+ * to Vigilly — the transport URL is overridden by the `tunnel` and ingest auth
+ * uses only the public key — so a constant numeric value is always safe. The
+ * real project id is carried in the tunnel path (see `envelopeTunnelUrl`).
+ */
+const SENTRY_DSN_PROJECT_ID = "0";
+/**
+ * A Sentry-valid DSN (`<protocol>://<publicKey>@<host>/0`) synthesised from a
+ * Vigilly DSN. The underlying Sentry SDK requires a (numeric) project id in the
+ * DSN path even when a `tunnel` overrides the transport URL; this DSN also seeds
+ * the `dsn` field of the envelope header that Vigilly ingest reads for the public
+ * key. The real Vigilly project id lives in the tunnel path, not here.
+ */
+function toSentryDsn(c) {
+    return `${c.protocol}://${c.publicKey}@${c.host}/${SENTRY_DSN_PROJECT_ID}`;
+}
+//# sourceMappingURL=dsn.js.map

package/dist/dsn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsn.js","sourceRoot":"","sources":["../src/dsn.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AA0BH,0CAyCC;AAOD,8CAEC;AAmBD,kCAEC;AApFD,MAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,GAAW,EAAE,MAAc;QACrC,KAAK,CAAC,wBAAwB,GAAG,MAAM,MAAM,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,GAAW;IACzC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,sBAAsB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,oCAAoC,CAAC,CAAC;IACtF,CAAC;IAED,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,sBAAsB,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,MAAM,IAAI,sBAAsB,CAAC,GAAG,EAAE,gCAAgC,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC/B,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,sBAAsB,CAAC,GAAG,EAAE,0DAA0D,CAAC,CAAC;IACpG,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,MAAM,IAAI,sBAAsB,CAAC,GAAG,EAAE,qDAAqD,CAAC,CAAC;IAC/F,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,uCAAuC;IAC9D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,sBAAsB,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAE/C,sCAAsC;IACtC,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IACtE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,sBAAsB,CAC9B,GAAG,EACH,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,CAAuB;IACvD,OAAO,GAAG,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,SAAS,YAAY,CAAC;AAC1E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAElC;;;;;;GAMG;AACH,SAAgB,WAAW,CAAC,CAAuB;IACjD,OAAO,GAAG,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,IAAI,IAAI,qBAAqB,EAAE,CAAC;AAC7E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { parseVigillyDsn, envelopeTunnelUrl, toSentryDsn, InvalidVigillyDsnError, } from "./dsn";
+export type { VigillyDsnComponents } from "./dsn";
+export { resolveVigillyOptions } from "./options";
+export type { VigillyOptions, ResolvedVigillyOptions, VigillyBreadcrumb, VigillyEvent, VigillyEventHint, } from "./options";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,sBAAsB,GACvB,MAAM,OAAO,CAAC;AACf,YAAY,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAElD,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,GACjB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVigillyOptions = exports.InvalidVigillyDsnError = exports.toSentryDsn = exports.envelopeTunnelUrl = exports.parseVigillyDsn = void 0;
+var dsn_1 = require("./dsn");
+Object.defineProperty(exports, "parseVigillyDsn", { enumerable: true, get: function () { return dsn_1.parseVigillyDsn; } });
+Object.defineProperty(exports, "envelopeTunnelUrl", { enumerable: true, get: function () { return dsn_1.envelopeTunnelUrl; } });
+Object.defineProperty(exports, "toSentryDsn", { enumerable: true, get: function () { return dsn_1.toSentryDsn; } });
+Object.defineProperty(exports, "InvalidVigillyDsnError", { enumerable: true, get: function () { return dsn_1.InvalidVigillyDsnError; } });
+var options_1 = require("./options");
+Object.defineProperty(exports, "resolveVigillyOptions", { enumerable: true, get: function () { return options_1.resolveVigillyOptions; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6BAKe;AAJb,sGAAA,eAAe,OAAA;AACf,wGAAA,iBAAiB,OAAA;AACjB,kGAAA,WAAW,OAAA;AACX,6GAAA,sBAAsB,OAAA;AAIxB,qCAAkD;AAAzC,gHAAA,qBAAqB,OAAA"}

package/dist/options.d.ts

@@ -0,0 +1,69 @@
+/** Curated, transport-agnostic shape of a captured breadcrumb. */
+export interface VigillyBreadcrumb {
+    type?: string;
+    level?: "fatal" | "error" | "warning" | "log" | "info" | "debug";
+    category?: string;
+    message?: string;
+    data?: Record<string, unknown>;
+    timestamp?: number;
+}
+/** Minimal event/hint typing — kept loose to stay SDK-version agnostic. */
+export type VigillyEvent = Record<string, any>;
+export type VigillyEventHint = Record<string, any>;
+/**
+ * The options accepted by `Vigilly.init`. A curated subset of the Sentry init
+ * options plus the Vigilly DSN. Unsupported Sentry options (tracing, replay,
+ * integrations, …) are deliberately absent.
+ */
+export interface VigillyOptions {
+    /** Vigilly DSN: `https://<publicKey>@<host>/<projectId>`, e.g. `https://<publicKey>@vigilly.dev/<projectId>`. */
+    dsn: string;
+    /** Release identifier (e.g. a version or git SHA). */
+    release?: string;
+    /** Deployment environment, e.g. `production`, `staging`. */
+    environment?: string;
+    /** Turn on SDK debug logging. */
+    debug?: boolean;
+    /** Master switch; when `false` the SDK is inert. Defaults to `true`. */
+    enabled?: boolean;
+    /** Error sampling rate in [0, 1]. Defaults to `1.0`. */
+    sampleRate?: number;
+    /** Max breadcrumbs retained per event. */
+    maxBreadcrumbs?: number;
+    /** Attach a synthetic stack trace to captured messages. */
+    attachStacktrace?: boolean;
+    /** Depth to which structured context is normalized. */
+    normalizeDepth?: number;
+    /** Patterns of error messages to drop before sending. */
+    ignoreErrors?: Array<string | RegExp>;
+    /** Server name reported with events (Node). */
+    serverName?: string;
+    /** Hook to mutate/drop an event before it is sent. Return `null` to drop. */
+    beforeSend?: (event: VigillyEvent, hint: VigillyEventHint) => VigillyEvent | null | PromiseLike<VigillyEvent | null>;
+    /** Hook to mutate/drop a breadcrumb before it is recorded. */
+    beforeBreadcrumb?: (breadcrumb: VigillyBreadcrumb, hint?: any) => VigillyBreadcrumb | null;
+    /** Initial scope (tags, user, extra, …) applied at init. */
+    initialScope?: Record<string, any> | ((scope: any) => any);
+    /**
+     * Advanced / testing escape hatch: a custom Sentry transport factory. Most
+     * users never set this — Vigilly presets the transport via `tunnel`.
+     */
+    transport?: (transportOptions: any) => any;
+}
+/**
+ * The resolved option object handed to `Sentry.init`. Includes the synthesised
+ * Sentry DSN and the `tunnel` pointing at Vigilly's `/api/observe/:projectId/`
+ * `envelope/` route. Typed loosely so each wrapper can cast to its SDK's exact
+ * option type.
+ */
+export type ResolvedVigillyOptions = Record<string, unknown> & {
+    dsn: string;
+    tunnel: string;
+};
+/**
+ * Translate `VigillyOptions` into the option object for the underlying Sentry
+ * SDK: parse the Vigilly DSN, synthesise a Sentry-valid DSN, and preset
+ * `tunnel` to Vigilly's ingest URL. Only curated, defined fields are forwarded.
+ */
+export declare function resolveVigillyOptions(options: VigillyOptions): ResolvedVigillyOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAYA,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC/C,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,iHAAiH;IACjH,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,YAAY,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACtC,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,gBAAgB,KAAK,YAAY,GAAG,IAAI,GAAG,WAAW,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACrH,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,iBAAiB,GAAG,IAAI,CAAC;IAC3F,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IAC3D;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,gBAAgB,EAAE,GAAG,KAAK,GAAG,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC7D,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,sBAAsB,CAoCrF"}

package/dist/options.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVigillyOptions = resolveVigillyOptions;
+/**
+ * Mapping from the curated `VigillyOptions` surface to the option object the
+ * underlying Sentry SDK consumes.
+ *
+ * The surface is intentionally small: it exposes the exception-reporting
+ * features Vigilly supports today and omits everything else (performance
+ * tracing, profiling, session replay, cron monitoring, custom integrations,
+ * …). Those are neither forwarded nor enabled, so a Vigilly client only ever
+ * sends error/message envelopes.
+ */
+const dsn_1 = require("./dsn");
+/**
+ * Translate `VigillyOptions` into the option object for the underlying Sentry
+ * SDK: parse the Vigilly DSN, synthesise a Sentry-valid DSN, and preset
+ * `tunnel` to Vigilly's ingest URL. Only curated, defined fields are forwarded.
+ */
+function resolveVigillyOptions(options) {
+    const components = (0, dsn_1.parseVigillyDsn)(options.dsn);
+    const resolved = {
+        dsn: (0, dsn_1.toSentryDsn)(components),
+        tunnel: (0, dsn_1.envelopeTunnelUrl)(components),
+        // Vigilly handles exceptions only — never opt the SDK into tracing.
+        tracesSampleRate: 0,
+        sampleRate: options.sampleRate ?? 1.0,
+    };
+    // Forward only the curated options that were actually provided.
+    const passthrough = [
+        "release",
+        "environment",
+        "debug",
+        "enabled",
+        "maxBreadcrumbs",
+        "attachStacktrace",
+        "normalizeDepth",
+        "ignoreErrors",
+        "serverName",
+        "beforeSend",
+        "beforeBreadcrumb",
+        "initialScope",
+        "transport",
+    ];
+    const sink = resolved;
+    for (const key of passthrough) {
+        const value = options[key];
+        if (value !== undefined) {
+            sink[key] = value;
+        }
+    }
+    return resolved;
+}
+//# sourceMappingURL=options.js.map

package/dist/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":";;AAmFA,sDAoCC;AAvHD;;;;;;;;;GASG;AACH,+BAAwE;AAoExE;;;;GAIG;AACH,SAAgB,qBAAqB,CAAC,OAAuB;IAC3D,MAAM,UAAU,GAAG,IAAA,qBAAe,EAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAEhD,MAAM,QAAQ,GAA2B;QACvC,GAAG,EAAE,IAAA,iBAAW,EAAC,UAAU,CAAC;QAC5B,MAAM,EAAE,IAAA,uBAAiB,EAAC,UAAU,CAAC;QACrC,oEAAoE;QACpE,gBAAgB,EAAE,CAAC;QACnB,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,GAAG;KACtC,CAAC;IAEF,gEAAgE;IAChE,MAAM,WAAW,GAAgC;QAC/C,SAAS;QACT,aAAa;QACb,OAAO;QACP,SAAS;QACT,gBAAgB;QAChB,kBAAkB;QAClB,gBAAgB;QAChB,cAAc;QACd,YAAY;QACZ,YAAY;QACZ,kBAAkB;QAClB,cAAc;QACd,WAAW;KACZ,CAAC;IACF,MAAM,IAAI,GAAG,QAAmC,CAAC;IACjD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@vigilly/core",
+  "version": "0.1.0",
+  "description": "Shared internals for the Vigilly exceptions clients: DSN parsing and Sentry option mapping.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vigilly/exceptions-js.git",
+    "directory": "packages/core"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "src", "!**/*.test.*"],
+  "scripts": {
+    "build": "tsc -b"
+  }
+}

package/src/dsn.ts

@@ -0,0 +1,114 @@
+/**
+ * Vigilly DSN parsing.
+ *
+ * A Vigilly DSN is a standard Sentry-shaped DSN:
+ *
+ *     https://<publicKey>@<host>/<projectId>
+ *
+ * e.g. `https://<publicKey>@vigilly.dev/<projectId>`. The host is the Vigilly
+ * Observe ingest host (`vigilly.dev` in prod, `staging.vigilly.dev` /
+ * `local.vigilly.dev` for other envs) and is used AS-IS. The public key
+ * identifies the service to Vigilly ingest; the projectId is the DSN path
+ * segment (present for Sentry-DSN-format compatibility, not used for auth).
+ *
+ * Vigilly's ingest route is `<host>/api/observe/<projectId>/envelope/`, which is
+ * NOT the path a stock Sentry DSN derives (`<host>/api/<projectId>/envelope/`).
+ * The wrapper bridges that gap with the SDK's `tunnel` option — see `options.ts`.
+ */
+
+export interface VigillyDsnComponents {
+  /** DSN public key — identifies the service to Vigilly ingest (auth). */
+  publicKey: string;
+  /** URL protocol, e.g. `https`. */
+  protocol: string;
+  /** Ingest host, used as-is, e.g. `vigilly.dev`. */
+  host: string;
+  /** Project identifier from the DSN path; used in the ingest path. */
+  projectId: string;
+}
+
+export class InvalidVigillyDsnError extends Error {
+  constructor(dsn: string, reason: string) {
+    super(`Invalid Vigilly DSN "${dsn}": ${reason}`);
+    this.name = "InvalidVigillyDsnError";
+  }
+}
+
+/**
+ * Parse a Vigilly DSN into its components.
+ *
+ * @throws {InvalidVigillyDsnError} when the DSN is missing, malformed, or lacks a
+ *   public key / host.
+ */
+export function parseVigillyDsn(dsn: string): VigillyDsnComponents {
+  if (!dsn || typeof dsn !== "string") {
+    throw new InvalidVigillyDsnError(String(dsn), "a non-empty DSN string is required");
+  }
+
+  let url: URL;
+  try {
+    url = new URL(dsn);
+  } catch {
+    throw new InvalidVigillyDsnError(dsn, "not a valid URL");
+  }
+
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new InvalidVigillyDsnError(dsn, "protocol must be http or https");
+  }
+
+  const publicKey = url.username;
+  if (!publicKey) {
+    throw new InvalidVigillyDsnError(dsn, "missing public key (expected https://<publicKey>@<host>)");
+  }
+  if (url.password) {
+    throw new InvalidVigillyDsnError(dsn, "DSN must not contain a secret — only the public key");
+  }
+
+  const host = url.host; // used as-is; includes port if present
+  if (!host) {
+    throw new InvalidVigillyDsnError(dsn, "missing host");
+  }
+
+  const protocol = url.protocol.replace(":", "");
+
+  // Project id is the DSN path segment.
+  const projectId = url.pathname.split("/").filter(Boolean).pop() || "";
+  if (!projectId) {
+    throw new InvalidVigillyDsnError(
+      dsn,
+      "missing project id (expected https://<publicKey>@<host>/<projectId>)",
+    );
+  }
+
+  return { publicKey, protocol, host, projectId };
+}
+
+/**
+ * The Vigilly envelope ingest URL for a parsed DSN. Used as the Sentry SDK's
+ * `tunnel` so envelopes land on Vigilly's route shape rather than the path a
+ * stock Sentry DSN would derive.
+ */
+export function envelopeTunnelUrl(c: VigillyDsnComponents): string {
+  return `${c.protocol}://${c.host}/api/observe/${c.projectId}/envelope/`;
+}
+
+/**
+ * Placeholder project id used in the synthesised Sentry DSN. The Sentry SDK
+ * validates that a DSN's project id is purely numeric, while a Vigilly project
+ * id may be a non-numeric slug. The synthesised DSN's project id is irrelevant
+ * to Vigilly — the transport URL is overridden by the `tunnel` and ingest auth
+ * uses only the public key — so a constant numeric value is always safe. The
+ * real project id is carried in the tunnel path (see `envelopeTunnelUrl`).
+ */
+const SENTRY_DSN_PROJECT_ID = "0";
+
+/**
+ * A Sentry-valid DSN (`<protocol>://<publicKey>@<host>/0`) synthesised from a
+ * Vigilly DSN. The underlying Sentry SDK requires a (numeric) project id in the
+ * DSN path even when a `tunnel` overrides the transport URL; this DSN also seeds
+ * the `dsn` field of the envelope header that Vigilly ingest reads for the public
+ * key. The real Vigilly project id lives in the tunnel path, not here.
+ */
+export function toSentryDsn(c: VigillyDsnComponents): string {
+  return `${c.protocol}://${c.publicKey}@${c.host}/${SENTRY_DSN_PROJECT_ID}`;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  parseVigillyDsn,
+  envelopeTunnelUrl,
+  toSentryDsn,
+  InvalidVigillyDsnError,
+} from "./dsn";
+export type { VigillyDsnComponents } from "./dsn";
+
+export { resolveVigillyOptions } from "./options";
+export type {
+  VigillyOptions,
+  ResolvedVigillyOptions,
+  VigillyBreadcrumb,
+  VigillyEvent,
+  VigillyEventHint,
+} from "./options";

package/src/options.ts

@@ -0,0 +1,120 @@
+/**
+ * Mapping from the curated `VigillyOptions` surface to the option object the
+ * underlying Sentry SDK consumes.
+ *
+ * The surface is intentionally small: it exposes the exception-reporting
+ * features Vigilly supports today and omits everything else (performance
+ * tracing, profiling, session replay, cron monitoring, custom integrations,
+ * …). Those are neither forwarded nor enabled, so a Vigilly client only ever
+ * sends error/message envelopes.
+ */
+import { envelopeTunnelUrl, parseVigillyDsn, toSentryDsn } from "./dsn";
+
+/** Curated, transport-agnostic shape of a captured breadcrumb. */
+export interface VigillyBreadcrumb {
+  type?: string;
+  level?: "fatal" | "error" | "warning" | "log" | "info" | "debug";
+  category?: string;
+  message?: string;
+  data?: Record<string, unknown>;
+  timestamp?: number;
+}
+
+/** Minimal event/hint typing — kept loose to stay SDK-version agnostic. */
+export type VigillyEvent = Record<string, any>;
+export type VigillyEventHint = Record<string, any>;
+
+/**
+ * The options accepted by `Vigilly.init`. A curated subset of the Sentry init
+ * options plus the Vigilly DSN. Unsupported Sentry options (tracing, replay,
+ * integrations, …) are deliberately absent.
+ */
+export interface VigillyOptions {
+  /** Vigilly DSN: `https://<publicKey>@<host>/<projectId>`, e.g. `https://<publicKey>@vigilly.dev/<projectId>`. */
+  dsn: string;
+  /** Release identifier (e.g. a version or git SHA). */
+  release?: string;
+  /** Deployment environment, e.g. `production`, `staging`. */
+  environment?: string;
+  /** Turn on SDK debug logging. */
+  debug?: boolean;
+  /** Master switch; when `false` the SDK is inert. Defaults to `true`. */
+  enabled?: boolean;
+  /** Error sampling rate in [0, 1]. Defaults to `1.0`. */
+  sampleRate?: number;
+  /** Max breadcrumbs retained per event. */
+  maxBreadcrumbs?: number;
+  /** Attach a synthetic stack trace to captured messages. */
+  attachStacktrace?: boolean;
+  /** Depth to which structured context is normalized. */
+  normalizeDepth?: number;
+  /** Patterns of error messages to drop before sending. */
+  ignoreErrors?: Array<string | RegExp>;
+  /** Server name reported with events (Node). */
+  serverName?: string;
+  /** Hook to mutate/drop an event before it is sent. Return `null` to drop. */
+  beforeSend?: (event: VigillyEvent, hint: VigillyEventHint) => VigillyEvent | null | PromiseLike<VigillyEvent | null>;
+  /** Hook to mutate/drop a breadcrumb before it is recorded. */
+  beforeBreadcrumb?: (breadcrumb: VigillyBreadcrumb, hint?: any) => VigillyBreadcrumb | null;
+  /** Initial scope (tags, user, extra, …) applied at init. */
+  initialScope?: Record<string, any> | ((scope: any) => any);
+  /**
+   * Advanced / testing escape hatch: a custom Sentry transport factory. Most
+   * users never set this — Vigilly presets the transport via `tunnel`.
+   */
+  transport?: (transportOptions: any) => any;
+}
+
+/**
+ * The resolved option object handed to `Sentry.init`. Includes the synthesised
+ * Sentry DSN and the `tunnel` pointing at Vigilly's `/api/observe/:projectId/`
+ * `envelope/` route. Typed loosely so each wrapper can cast to its SDK's exact
+ * option type.
+ */
+export type ResolvedVigillyOptions = Record<string, unknown> & {
+  dsn: string;
+  tunnel: string;
+};
+
+/**
+ * Translate `VigillyOptions` into the option object for the underlying Sentry
+ * SDK: parse the Vigilly DSN, synthesise a Sentry-valid DSN, and preset
+ * `tunnel` to Vigilly's ingest URL. Only curated, defined fields are forwarded.
+ */
+export function resolveVigillyOptions(options: VigillyOptions): ResolvedVigillyOptions {
+  const components = parseVigillyDsn(options.dsn);
+
+  const resolved: ResolvedVigillyOptions = {
+    dsn: toSentryDsn(components),
+    tunnel: envelopeTunnelUrl(components),
+    // Vigilly handles exceptions only — never opt the SDK into tracing.
+    tracesSampleRate: 0,
+    sampleRate: options.sampleRate ?? 1.0,
+  };
+
+  // Forward only the curated options that were actually provided.
+  const passthrough: Array<keyof VigillyOptions> = [
+    "release",
+    "environment",
+    "debug",
+    "enabled",
+    "maxBreadcrumbs",
+    "attachStacktrace",
+    "normalizeDepth",
+    "ignoreErrors",
+    "serverName",
+    "beforeSend",
+    "beforeBreadcrumb",
+    "initialScope",
+    "transport",
+  ];
+  const sink = resolved as Record<string, unknown>;
+  for (const key of passthrough) {
+    const value = options[key];
+    if (value !== undefined) {
+      sink[key] = value;
+    }
+  }
+
+  return resolved;
+}