@molecule/api-error-tracking 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-error-tracking` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-error-tracking is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/error-tracking.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Error tracking convenience functions.
+ *
+ * Unlike most core convenience modules, these NEVER throw:
+ *
+ * - When no provider is bonded they are a silent, documented no-op (returning
+ *   `undefined` / `true`). Error tracking is a diagnostic side-channel — an
+ *   app that hasn't wired a tracker must behave exactly as if the calls
+ *   weren't there.
+ * - When the bonded provider itself throws, the failure is logged (warn) and
+ *   swallowed for the same reason: a broken reporter must never take down the
+ *   request or process it is reporting on.
+ *
+ * @module
+ */
+import type { ErrorTrackingContext, ErrorTrackingLevel, ErrorTrackingUser } from './types.js';
+/**
+ * Reports an exception (or any thrown value) to the bonded error tracking
+ * provider. Silent no-op when no provider is bonded; never throws.
+ *
+ * @param error - The thrown value to report.
+ * @param context - Optional normalized context (tags/user/extra/request).
+ * @returns The backend's event id when available, otherwise `undefined`.
+ */
+export declare const captureException: (error: unknown, context?: ErrorTrackingContext) => string | undefined;
+/**
+ * Reports a standalone message to the bonded error tracking provider.
+ * Silent no-op when no provider is bonded; never throws.
+ *
+ * @param message - The message to report.
+ * @param level - Severity level (providers default to `'info'` when omitted).
+ * @param context - Optional normalized context (tags/user/extra/request).
+ * @returns The backend's event id when available, otherwise `undefined`.
+ */
+export declare const captureMessage: (message: string, level?: ErrorTrackingLevel, context?: ErrorTrackingContext) => string | undefined;
+/**
+ * Associates subsequent captures with a user (`null` clears it). Silent
+ * no-op when no provider is bonded or the provider has no user scoping;
+ * never throws.
+ *
+ * @param user - The user to associate, or `null` to clear.
+ */
+export declare const setUser: (user: ErrorTrackingUser | null) => void;
+/**
+ * Flushes buffered events to the backend — call before process exit so
+ * queued reports aren't lost. Resolves `true` when no provider is bonded or
+ * the provider delivers synchronously (nothing to flush); never rejects.
+ *
+ * @param timeoutMs - Maximum time to wait for delivery.
+ * @returns `true` when everything flushed within the timeout.
+ */
+export declare const flush: (timeoutMs?: number) => Promise<boolean>;
+//# sourceMappingURL=error-tracking.d.ts.map

package/dist/error-tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-tracking.d.ts","sourceRoot":"","sources":["../src/error-tracking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAI7F;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,OAAO,EACd,UAAU,oBAAoB,KAC7B,MAAM,GAAG,SAaX,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,MAAM,EACf,QAAQ,kBAAkB,EAC1B,UAAU,oBAAoB,KAC7B,MAAM,GAAG,SAYX,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,iBAAiB,GAAG,IAAI,KAAG,IAYxD,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAAU,YAAY,MAAM,KAAG,OAAO,CAAC,OAAO,CAa/D,CAAA"}

package/dist/error-tracking.js

@@ -0,0 +1,112 @@
+/**
+ * Error tracking convenience functions.
+ *
+ * Unlike most core convenience modules, these NEVER throw:
+ *
+ * - When no provider is bonded they are a silent, documented no-op (returning
+ *   `undefined` / `true`). Error tracking is a diagnostic side-channel — an
+ *   app that hasn't wired a tracker must behave exactly as if the calls
+ *   weren't there.
+ * - When the bonded provider itself throws, the failure is logged (warn) and
+ *   swallowed for the same reason: a broken reporter must never take down the
+ *   request or process it is reporting on.
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+import { getOptionalProvider } from './provider.js';
+const logger = getLogger();
+/**
+ * Reports an exception (or any thrown value) to the bonded error tracking
+ * provider. Silent no-op when no provider is bonded; never throws.
+ *
+ * @param error - The thrown value to report.
+ * @param context - Optional normalized context (tags/user/extra/request).
+ * @returns The backend's event id when available, otherwise `undefined`.
+ */
+export const captureException = (error, context) => {
+    const provider = getOptionalProvider();
+    // Documented no-op: no provider bonded means error tracking is not enabled
+    // for this app — behave as if the call weren't there.
+    if (!provider)
+        return undefined;
+    try {
+        return provider.captureException(error, context) ?? undefined;
+    }
+    catch (captureError) {
+        logger.warn('error-tracking: captureException failed — the report was not delivered', {
+            error: captureError,
+        });
+        return undefined;
+    }
+};
+/**
+ * Reports a standalone message to the bonded error tracking provider.
+ * Silent no-op when no provider is bonded; never throws.
+ *
+ * @param message - The message to report.
+ * @param level - Severity level (providers default to `'info'` when omitted).
+ * @param context - Optional normalized context (tags/user/extra/request).
+ * @returns The backend's event id when available, otherwise `undefined`.
+ */
+export const captureMessage = (message, level, context) => {
+    const provider = getOptionalProvider();
+    // Documented no-op: see captureException.
+    if (!provider)
+        return undefined;
+    try {
+        return provider.captureMessage(message, level, context) ?? undefined;
+    }
+    catch (captureError) {
+        logger.warn('error-tracking: captureMessage failed — the report was not delivered', {
+            error: captureError,
+        });
+        return undefined;
+    }
+};
+/**
+ * Associates subsequent captures with a user (`null` clears it). Silent
+ * no-op when no provider is bonded or the provider has no user scoping;
+ * never throws.
+ *
+ * @param user - The user to associate, or `null` to clear.
+ */
+export const setUser = (user) => {
+    const provider = getOptionalProvider();
+    // Documented no-op: see captureException. Also a no-op when the bonded
+    // provider doesn't implement optional user scoping.
+    if (!provider?.setUser)
+        return;
+    try {
+        provider.setUser(user);
+    }
+    catch (setUserError) {
+        logger.warn('error-tracking: setUser failed — user scoping was not applied', {
+            error: setUserError,
+        });
+    }
+};
+/**
+ * Flushes buffered events to the backend — call before process exit so
+ * queued reports aren't lost. Resolves `true` when no provider is bonded or
+ * the provider delivers synchronously (nothing to flush); never rejects.
+ *
+ * @param timeoutMs - Maximum time to wait for delivery.
+ * @returns `true` when everything flushed within the timeout.
+ */
+export const flush = async (timeoutMs) => {
+    const provider = getOptionalProvider();
+    // Documented no-op: nothing bonded (or nothing buffered) means there is
+    // nothing to flush — report success.
+    if (!provider?.flush)
+        return true;
+    try {
+        return await provider.flush(timeoutMs);
+    }
+    catch (flushError) {
+        logger.warn('error-tracking: flush failed — buffered reports may be lost', {
+            error: flushError,
+        });
+        return false;
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Error tracking core interface for molecule.dev.
+ *
+ * Defines the standard interface for error tracking / crash reporting
+ * providers (Sentry, console, etc.) plus never-throwing convenience
+ * functions (`captureException`, `captureMessage`, `setUser`, `flush`)
+ * that delegate to the bonded provider.
+ *
+ * This is distinct from `@molecule/api-monitoring`, which is health checks
+ * (is the database up?). Error tracking captures individual unexpected
+ * exceptions with context so they can be aggregated and triaged.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * import { setProvider, captureException, captureMessage } from '@molecule/api-error-tracking'
+ * import { provider } from '@molecule/api-error-tracking-sentry'
+ *
+ * // Bond a provider at startup (skip this and every capture is a no-op)
+ * setProvider(provider)
+ *
+ * // Report an unexpected exception with normalized context
+ * try {
+ *   await chargeCustomer(order)
+ * } catch (error) {
+ *   captureException(error, {
+ *     tags: { source: 'billing' },
+ *     user: { id: order.userId },
+ *     extra: { orderId: order.id },
+ *   })
+ *   throw error
+ * }
+ *
+ * // Report a standalone message
+ * captureMessage('Payment retry queue is backing up', 'warning')
+ * ```
+ * @remarks
+ * - **The convenience functions NEVER throw and no-op when unbonded.** Error
+ *   tracking is a diagnostic side-channel: an app without a bonded tracker
+ *   (or with a broken one) must behave exactly as if the calls weren't
+ *   there. Do NOT wrap `captureException` in defensive try/catch — it is
+ *   already safe to call anywhere, including inside error middleware.
+ * - The default Express error path (`@molecule/api-server-default-express`)
+ *   already calls `captureException` for genuine unexpected errors (untagged
+ *   500s, uncaught exceptions, unhandled rejections). Tagged config-missing
+ *   503s and 4xx responses are deliberately NOT captured — they are expected,
+ *   user-actionable conditions, not defects.
+ * - `getProvider()` throws when unbonded (like other cores); prefer the
+ *   convenience functions or `getOptionalProvider()` in reporting paths.
+ * - Context is normalized (`tags`/`user`/`extra`/`request`) — never pass
+ *   provider-specific (e.g. Sentry) scope objects through this interface.
+ */
+export * from './browser-guard.js';
+export * from './error-tracking.js';
+export * from './provider.js';
+export * from './types.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,56 @@
+/**
+ * Error tracking core interface for molecule.dev.
+ *
+ * Defines the standard interface for error tracking / crash reporting
+ * providers (Sentry, console, etc.) plus never-throwing convenience
+ * functions (`captureException`, `captureMessage`, `setUser`, `flush`)
+ * that delegate to the bonded provider.
+ *
+ * This is distinct from `@molecule/api-monitoring`, which is health checks
+ * (is the database up?). Error tracking captures individual unexpected
+ * exceptions with context so they can be aggregated and triaged.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * import { setProvider, captureException, captureMessage } from '@molecule/api-error-tracking'
+ * import { provider } from '@molecule/api-error-tracking-sentry'
+ *
+ * // Bond a provider at startup (skip this and every capture is a no-op)
+ * setProvider(provider)
+ *
+ * // Report an unexpected exception with normalized context
+ * try {
+ *   await chargeCustomer(order)
+ * } catch (error) {
+ *   captureException(error, {
+ *     tags: { source: 'billing' },
+ *     user: { id: order.userId },
+ *     extra: { orderId: order.id },
+ *   })
+ *   throw error
+ * }
+ *
+ * // Report a standalone message
+ * captureMessage('Payment retry queue is backing up', 'warning')
+ * ```
+ * @remarks
+ * - **The convenience functions NEVER throw and no-op when unbonded.** Error
+ *   tracking is a diagnostic side-channel: an app without a bonded tracker
+ *   (or with a broken one) must behave exactly as if the calls weren't
+ *   there. Do NOT wrap `captureException` in defensive try/catch — it is
+ *   already safe to call anywhere, including inside error middleware.
+ * - The default Express error path (`@molecule/api-server-default-express`)
+ *   already calls `captureException` for genuine unexpected errors (untagged
+ *   500s, uncaught exceptions, unhandled rejections). Tagged config-missing
+ *   503s and 4xx responses are deliberately NOT captured — they are expected,
+ *   user-actionable conditions, not defects.
+ * - `getProvider()` throws when unbonded (like other cores); prefer the
+ *   convenience functions or `getOptionalProvider()` in reporting paths.
+ * - Context is normalized (`tags`/`user`/`extra`/`request`) — never pass
+ *   provider-specific (e.g. Sentry) scope objects through this interface.
+ */
+export * from './browser-guard.js';
+export * from './error-tracking.js';
+export * from './provider.js';
+export * from './types.js';

package/dist/provider.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Error tracking provider bond accessor.
+ *
+ * Bond packages (e.g. `@molecule/api-error-tracking-sentry`,
+ * `@molecule/api-error-tracking-console`) call `setProvider()` during setup.
+ * Application code uses the convenience functions from `error-tracking.ts`,
+ * which silently no-op when no provider is bonded — error tracking is an
+ * optional capability and reporting must never throw into the app.
+ *
+ * @module
+ */
+import type { ErrorTrackingProvider } from './types.js';
+/**
+ * Registers an error tracking provider as the active singleton. Called by
+ * bond packages during application startup.
+ *
+ * @param provider - The error tracking provider implementation to bond.
+ */
+export declare const setProvider: (provider: ErrorTrackingProvider) => void;
+/**
+ * Retrieves the bonded error tracking provider, throwing if none is
+ * configured. Application code should normally use the never-throwing
+ * convenience functions (`captureException`/`captureMessage`) or
+ * `getOptionalProvider()` instead.
+ *
+ * @returns The bonded error tracking provider.
+ * @throws {Error} If no error tracking provider has been bonded.
+ */
+export declare const getProvider: () => ErrorTrackingProvider;
+/**
+ * Checks whether an error tracking provider is currently bonded.
+ *
+ * @returns `true` if an error tracking provider is bonded.
+ */
+export declare const hasProvider: () => boolean;
+/**
+ * Retrieves the bonded error tracking provider, returning `null` if none is
+ * bonded. Prefer this over `getProvider()` in optional reporting code paths.
+ *
+ * @returns The bonded error tracking provider, or `null`.
+ */
+export declare const getOptionalProvider: () => ErrorTrackingProvider | null;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAUvD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,qBAAqB,KAAG,IAE7D,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,QAAO,qBAW9B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAO,OAE9B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAO,qBAAqB,GAAG,IAE9D,CAAA"}

package/dist/provider.js

@@ -0,0 +1,65 @@
+/**
+ * Error tracking provider bond accessor.
+ *
+ * Bond packages (e.g. `@molecule/api-error-tracking-sentry`,
+ * `@molecule/api-error-tracking-console`) call `setProvider()` during setup.
+ * Application code uses the convenience functions from `error-tracking.ts`,
+ * which silently no-op when no provider is bonded — error tracking is an
+ * optional capability and reporting must never throw into the app.
+ *
+ * @module
+ */
+import { bond, get as bondGet, isBonded, require as bondRequire } from '@molecule/api-bond';
+import { t } from '@molecule/api-i18n';
+const BOND_TYPE = 'error-tracking';
+// Deliberately NOT `expectBond(BOND_TYPE)`: error tracking is optional by
+// design. The default Express server imports this core unconditionally (its
+// error middleware reports through `captureException`), so marking the bond
+// as expected would make `validateBonds()` fail every app that hasn't wired
+// an error tracker. Unbonded apps must keep booting; the convenience
+// functions in `error-tracking.ts` no-op instead.
+/**
+ * Registers an error tracking provider as the active singleton. Called by
+ * bond packages during application startup.
+ *
+ * @param provider - The error tracking provider implementation to bond.
+ */
+export const setProvider = (provider) => {
+    bond(BOND_TYPE, provider);
+};
+/**
+ * Retrieves the bonded error tracking provider, throwing if none is
+ * configured. Application code should normally use the never-throwing
+ * convenience functions (`captureException`/`captureMessage`) or
+ * `getOptionalProvider()` instead.
+ *
+ * @returns The bonded error tracking provider.
+ * @throws {Error} If no error tracking provider has been bonded.
+ */
+export const getProvider = () => {
+    try {
+        return bondRequire(BOND_TYPE);
+    }
+    catch (error) {
+        throw new Error(t('errorTracking.error.noProvider', undefined, {
+            defaultValue: 'Error tracking provider not configured. Call setProvider() first.',
+        }), { cause: error });
+    }
+};
+/**
+ * Checks whether an error tracking provider is currently bonded.
+ *
+ * @returns `true` if an error tracking provider is bonded.
+ */
+export const hasProvider = () => {
+    return isBonded(BOND_TYPE);
+};
+/**
+ * Retrieves the bonded error tracking provider, returning `null` if none is
+ * bonded. Prefer this over `getProvider()` in optional reporting code paths.
+ *
+ * @returns The bonded error tracking provider, or `null`.
+ */
+export const getOptionalProvider = () => {
+    return bondGet(BOND_TYPE) ?? null;
+};

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Error tracking core types for molecule.dev.
+ *
+ * Defines the standard, provider-agnostic interfaces for error tracking /
+ * crash reporting providers (Sentry, console, etc.). Every field here is
+ * normalized — no provider-specific types (e.g. Sentry's) leak into this
+ * contract, so swapping the bonded provider never changes consumer code.
+ *
+ * @module
+ */
+/**
+ * Severity level for a captured message or exception.
+ */
+export type ErrorTrackingLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+/**
+ * Normalized description of the user an event occurred for.
+ */
+export interface ErrorTrackingUser {
+    /** Application-level user id. */
+    id?: string;
+    /** The user's email address. */
+    email?: string;
+    /** The user's username / display handle. */
+    username?: string;
+    /** The user's IP address. */
+    ipAddress?: string;
+}
+/**
+ * Normalized, provider-agnostic description of the HTTP request (or
+ * request-like operation) an event occurred in.
+ */
+export interface ErrorTrackingRequestContext {
+    /** HTTP method (e.g. `GET`). */
+    method?: string;
+    /** Request URL or path, including the query string (e.g. `/api/users/123?full=true`). */
+    url?: string;
+    /**
+     * Selected request headers. Callers must NOT include credential-bearing
+     * headers (`cookie`, `authorization`) — error trackers are third-party
+     * sinks and must never receive session material.
+     */
+    headers?: Record<string, string | string[] | undefined>;
+    /** Parsed query parameters. */
+    query?: Record<string, unknown>;
+}
+/**
+ * Normalized context attached to a captured exception or message.
+ */
+export interface ErrorTrackingContext {
+    /** Short, indexable key/value pairs (e.g. `{ source: 'express' }`). */
+    tags?: Record<string, string | number | boolean>;
+    /** The user the event occurred for. */
+    user?: ErrorTrackingUser;
+    /** Arbitrary additional (non-indexed) structured data. */
+    extra?: Record<string, unknown>;
+    /** The request the event occurred in. */
+    request?: ErrorTrackingRequestContext;
+}
+/**
+ * Error tracking provider interface.
+ *
+ * All error tracking providers must implement this interface. Providers
+ * receive the normalized {@link ErrorTrackingContext} and map it to their
+ * own event model (tags/user/extra scopes, etc.).
+ */
+export interface ErrorTrackingProvider {
+    /**
+     * Reports an exception (or any thrown value) to the tracking backend.
+     *
+     * @param error - The thrown value to report.
+     * @param context - Optional normalized context (tags/user/extra/request).
+     * @returns The backend's event id when available, otherwise `undefined`.
+     */
+    captureException(error: unknown, context?: ErrorTrackingContext): string | void;
+    /**
+     * Reports a standalone message (no exception object) to the tracking backend.
+     *
+     * @param message - The message to report.
+     * @param level - Severity level (providers default to `'info'` when omitted).
+     * @param context - Optional normalized context (tags/user/extra/request).
+     * @returns The backend's event id when available, otherwise `undefined`.
+     */
+    captureMessage(message: string, level?: ErrorTrackingLevel, context?: ErrorTrackingContext): string | void;
+    /**
+     * Optionally associates subsequent captures with a user (`null` clears it).
+     * Providers whose backend has no user scoping may leave this undefined.
+     *
+     * @param user - The user to associate, or `null` to clear.
+     */
+    setUser?(user: ErrorTrackingUser | null): void;
+    /**
+     * Optionally flushes buffered events to the backend — call before process
+     * exit so queued reports aren't lost. Providers that deliver synchronously
+     * may leave this undefined.
+     *
+     * @param timeoutMs - Maximum time to wait for delivery.
+     * @returns `true` when everything flushed within the timeout.
+     */
+    flush?(timeoutMs?: number): Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;AAEjF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAA;IAEX,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,yFAAyF;IACzF,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;IAEvD,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;IAEhD,uCAAuC;IACvC,IAAI,CAAC,EAAE,iBAAiB,CAAA;IAExB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAE/B,yCAAyC;IACzC,OAAO,CAAC,EAAE,2BAA2B,CAAA;CACtC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,GAAG,IAAI,CAAA;IAE/E;;;;;;;OAOG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,MAAM,GAAG,IAAI,CAAA;IAEhB;;;;;OAKG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAA;IAE9C;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC7C"}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Error tracking core types for molecule.dev.
+ *
+ * Defines the standard, provider-agnostic interfaces for error tracking /
+ * crash reporting providers (Sentry, console, etc.). Every field here is
+ * normalized — no provider-specific types (e.g. Sentry's) leak into this
+ * contract, so swapping the bonded provider never changes consumer code.
+ *
+ * @module
+ */
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@molecule/api-error-tracking",
+  "version": "1.0.0",
+  "description": "Error tracking core interface for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "error-tracking",
+    "errors",
+    "crash-reporting",
+    "monitoring"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.0",
+    "@molecule/api-i18n": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.0",
+    "@molecule/api-i18n": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/core/error-tracking"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/core/error-tracking",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}