@edraj/sauron-node 1.0.0 → 1.4.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BreadcrumbInput, CaptureExceptionOptions, InitOptions, Level, MetadataOptions, TransactionInput } from './types.js';
+import type { BreadcrumbInput, CaptureExceptionOptions, InitOptions, Level, MetadataOptions, TransactionInput, WorkflowResult } from './types.js';
 /**
  * The Sauron server-side client. Buffers events/errors and dispatches them via
  * a background transport. Constructed by {@link init}.
@@ -10,9 +10,21 @@ export declare class SauronClient {
     private readonly hookUninstallers;
     constructor(options: InitOptions);
     /**
-     * The single enqueue chokepoint. Runs `beforeSend` on every item; a `null`
-     * return drops it, a returned item replaces it, then it is handed to the
-     * transport.
+     * The single enqueue chokepoint — every error/event/transaction (however
+     * constructed, including `captureMessage`'s inline-built item) passes
+     * through here before reaching the transport. Stamping the active
+     * workflow ONCE, right here, means a future capture path can't forget it
+     * the way a per-construction-site stamp could. `identify` items are
+     * excluded: the server has no workflow columns for them.
+     *
+     * Runs `beforeSend` on every item; a `null` return drops it, a returned
+     * item replaces it, then it is handed to the transport.
+     *
+     * `beforeSend` is user-supplied, so it is guarded: a throwing hook must
+     * never propagate into the caller's `track`/`captureException`/etc — that
+     * would break the SDK's no-throw guarantee. On throw, the item is treated
+     * as UNMODIFIED and still sent (never silently dropped); the failure is
+     * only surfaced via the debug logger.
      */
     private dispatch;
     /**
@@ -24,12 +36,109 @@ export declare class SauronClient {
     trackTransaction(input: TransactionInput): void;
     /** Capture a product-analytics event. `distinctId` is required. */
     track(event: string, distinctId: string, properties?: Record<string, unknown>, options?: MetadataOptions): void;
+    /**
+     * Build and dispatch an event item. Shared by the public {@link track} (which
+     * validates first) and the reserved workflow lifecycle emits (which must be
+     * able to send an intentionally empty `distinct_id`).
+     */
+    private emitEvent;
     /** Capture a native `Error` (or error-like value) as an error item. */
     captureException(error: unknown, options?: CaptureExceptionOptions): void;
     /** Capture a bare message as an error item (no exception payload). */
     captureMessage(message: string, level?: Level, options?: MetadataOptions): void;
     /** Associate traits with a distinct id. */
     identify(distinctId: string, traits?: Record<string, unknown>): void;
+    /**
+     * Whether this client can still deliver telemetry — false once the
+     * transport has auto-disabled itself on a 401/403. Gated on this (not just
+     * "does a client object exist") so `startWorkflow` can't mutate local scope
+     * state and emit an event the transport would silently drop underneath it.
+     */
+    isEnabled(): boolean;
+    /** Debug-gated warning log, matching the transport's own `[sauron]`-prefixed convention. */
+    private debugLog;
+    /**
+     * Emit the closing lifecycle event (`$workflow_end`/`$workflow_cancel`) for
+     * `active` while it is STILL the current scope's workflow (so the item-level
+     * `workflow_id`/`workflow_name` stamped by `dispatch()` are its own, not
+     * `null`/absent), through `track()` so scope tags/contexts/extra apply.
+     * Never mutates scope state itself — callers own clearing it, in a `finally`
+     * relative to this call, so a throw here can't leave state half-mutated.
+     *
+     * The `distinctId` comes from {@link SauronClient.workflowDistinctId} — read
+     * its note on the `'system'` fallback's effect on unique-user counts.
+     */
+    private emitWorkflowClose;
+    /**
+     * The `distinct_id` to attribute a workflow lifecycle event to: the scope's
+     * user id, else **the empty string**.
+     *
+     * Empty is deliberate and correct — do NOT "fix" this to a sentinel like
+     * `'system'`, an anonymous/device id, or anything derived from the workflow
+     * id. The server was built for exactly this case:
+     *
+     *   - `backend/crates/sauron-pipeline/src/process.rs` — both `bump_workflow`
+     *     call sites pass `Some(distinct_id.as_str()).filter(|s| !s.is_empty())`,
+     *     so an empty id is stored as SQL `NULL` on the `workflows` row.
+     *   - `backend/crates/sauron-db/src/repo.rs` — the per-workflow rollup
+     *     computes `COUNT(DISTINCT w.distinct_id) AS unique_users`, and
+     *     `COUNT(DISTINCT ...)` skips NULLs.
+     *
+     * So an anonymous workflow run contributes *nothing* to `unique_users`,
+     * which is honest. Any non-empty sentinel would instead collapse every
+     * anonymous run of a workflow (`password_reset`, `guest_checkout`, …) into
+     * one fake bucket, silently reporting ~1 unique user no matter how many
+     * distinct invocations occurred.
+     *
+     * `EventItem.distinct_id` is a required string on the wire
+     * (`backend/crates/sauron-core/src/envelope.rs`), so the field is still
+     * always sent — it is just `""`. This is why the lifecycle emits route
+     * through {@link emitEvent} rather than the public {@link track}, whose
+     * empty-`distinctId` guard would otherwise drop them entirely.
+     */
+    private workflowDistinctId;
+    /**
+     * Start a named workflow on the current scope (the `AsyncLocalStorage`
+     * child inside `withScope`/`runWithAsyncScope`, else the process-wide
+     * global scope) — request-isolated, so concurrent requests never observe
+     * or clobber each other's workflow. `force: true` supersedes an
+     * already-active workflow (emitting `$workflow_cancel` with
+     * `reason: 'superseded'` for it first); otherwise an active workflow makes
+     * this a no-op returning `already_active`.
+     *
+     * The workflow id is a fresh `randomUUID()`, minted here — never derived
+     * from anything deterministic. The server's rollup key is
+     * `(app_id, workflow_id)` app-wide, so a reused/derived id would merge
+     * counters from unrelated requests/environments into one row.
+     *
+     * Never throws: an unexpected failure before any side effect is reported as
+     * `disabled`, and `disabled` always means literally nothing happened — no
+     * event on the wire, no state change. A failure emitting `$workflow_start`
+     * AFTER the scope's workflow field was set is still reported as `ok` — the
+     * workflow IS live locally, and a lost start event is recoverable
+     * server-side (the row materializes from the next stamped item via the same
+     * upsert); a lost local id would not be.
+     */
+    startWorkflow(name: string, options?: {
+        force?: boolean;
+    }): WorkflowResult;
+    /** Shared precondition + close logic for `endWorkflow`/`cancelWorkflow`. */
+    private closeWorkflow;
+    /**
+     * End the active workflow (or the one named `name`, if given). Emits
+     * `$workflow_end` with `duration_ms` and clears the scope's workflow field.
+     * A no-op returning `not_active` (nothing active) or `name_mismatch` (`name`
+     * given but does not match, including a `name` that fails normalization).
+     */
+    endWorkflow(name?: string): WorkflowResult;
+    /**
+     * Cancel the active workflow (or the one named `name`, if given). Emits
+     * `$workflow_cancel` with `duration_ms` and `reason` (default `'user'`,
+     * trimmed and capped at 120 chars) and clears the scope's workflow field.
+     */
+    cancelWorkflow(name?: string, options?: {
+        reason?: string;
+    }): WorkflowResult;
     /** Send any buffered items immediately. */
     flush(): Promise<void>;
     /** Flush then stop the background timer, and remove any opt-in process hooks. */

package/dist/client.js

@@ -5,8 +5,8 @@ import { Transport } from './transport.js';
 import { parseError } from './stacktrace.js';
 import { installAutoCapture, installShutdownHooks } from './autocapture.js';
 import { getCurrentScope, getGlobalScope, normalizeBreadcrumb, } from './scope.js';
+import { normalizeReason, normalizeWorkflowName } from './workflow.js';
 const DEFAULTS = {
-    environment: 'production',
     release: null,
     sampleRate: 1,
     flushInterval: 5000,
@@ -24,7 +24,6 @@ function resolveOptions(options) {
     const sampleRate = typeof options.sampleRate === 'number' ? options.sampleRate : DEFAULTS.sampleRate;
     return {
         dsn: options.dsn,
-        environment: options.environment ?? DEFAULTS.environment,
         release: options.release ?? DEFAULTS.release,
         tags: options.tags ?? {},
         contexts: options.contexts ?? {},
@@ -98,7 +97,6 @@ export class SauronClient {
         }
         this.transport = new Transport({
             dsn,
-            environment: this.options.environment,
             release: this.options.release,
             context: buildContext(),
             flushInterval: this.options.flushInterval,
@@ -118,16 +116,44 @@ export class SauronClient {
         }
     }
     /**
-     * The single enqueue chokepoint. Runs `beforeSend` on every item; a `null`
-     * return drops it, a returned item replaces it, then it is handed to the
-     * transport.
+     * The single enqueue chokepoint — every error/event/transaction (however
+     * constructed, including `captureMessage`'s inline-built item) passes
+     * through here before reaching the transport. Stamping the active
+     * workflow ONCE, right here, means a future capture path can't forget it
+     * the way a per-construction-site stamp could. `identify` items are
+     * excluded: the server has no workflow columns for them.
+     *
+     * Runs `beforeSend` on every item; a `null` return drops it, a returned
+     * item replaces it, then it is handed to the transport.
+     *
+     * `beforeSend` is user-supplied, so it is guarded: a throwing hook must
+     * never propagate into the caller's `track`/`captureException`/etc — that
+     * would break the SDK's no-throw guarantee. On throw, the item is treated
+     * as UNMODIFIED and still sent (never silently dropped); the failure is
+     * only surfaced via the debug logger.
      */
     dispatch(item) {
+        if (item.type !== 'identify') {
+            const workflow = getCurrentScope().data.workflow;
+            if (workflow) {
+                item.workflow_id = workflow.workflowId;
+                item.workflow_name = workflow.name;
+            }
+        }
         const beforeSend = this.options.beforeSend;
         if (beforeSend) {
-            const result = beforeSend(item);
-            if (result == null)
+            let result = item;
+            try {
+                result = beforeSend(item);
+            }
+            catch (err) {
+                this.debugLog('beforeSend threw', err);
+                result = item;
+            }
+            if (result == null) {
+                this.debugLog('dropped by beforeSend');
                 return;
+            }
             this.transport.enqueue(result);
             return;
         }
@@ -153,12 +179,25 @@ export class SauronClient {
     trackTransaction(input) {
         if (typeof input?.name !== 'string' || input.name.length === 0)
             return;
+        // `durationMs` accepted as an alias — see TransactionInput. Without it, a
+        // caller using the browser SDK's spelling shipped a transaction with the
+        // duration field absent and no complaint from anywhere.
+        const duration = input.duration_ms ?? input.durationMs;
+        if (typeof duration !== 'number' || !Number.isFinite(duration)) {
+            // Refused loudly rather than sent. A transaction whose whole purpose is
+            // to record a duration is not worth persisting without one, and silence
+            // here is what let the mis-spelling survive: the item looked delivered.
+            this.debugLog(`dropped transaction "${input.name}": duration_ms must be a finite number ` +
+                `(got ${typeof duration === 'number' ? duration : typeof duration}). ` +
+                `Use duration_ms, or durationMs if you are porting from the browser SDK.`);
+            return;
+        }
         const distinctId = input.distinct_id ?? getCurrentScope().data.user?.id ?? undefined;
         const item = {
             type: 'transaction',
             name: input.name,
             op: input.op ?? 'custom',
-            duration_ms: input.duration_ms,
+            duration_ms: duration,
             timestamp: isoNow(),
         };
         if (input.status !== undefined)
@@ -177,8 +216,19 @@ export class SauronClient {
     track(event, distinctId, properties, options = {}) {
         if (typeof event !== 'string' || event.length === 0)
             return;
+        // An empty/absent distinct id drops a MANUAL track call: the caller should
+        // know who acted. The reserved workflow lifecycle events deliberately
+        // bypass this via emitEvent() — see workflowDistinctId().
         if (typeof distinctId !== 'string' || distinctId.length === 0)
             return;
+        this.emitEvent(event, distinctId, properties, options);
+    }
+    /**
+     * Build and dispatch an event item. Shared by the public {@link track} (which
+     * validates first) and the reserved workflow lifecycle emits (which must be
+     * able to send an intentionally empty `distinct_id`).
+     */
+    emitEvent(event, distinctId, properties, options = {}) {
         const item = {
             type: 'event',
             name: event,
@@ -260,6 +310,203 @@ export class SauronClient {
         };
         this.dispatch(item);
     }
+    /**
+     * Whether this client can still deliver telemetry — false once the
+     * transport has auto-disabled itself on a 401/403. Gated on this (not just
+     * "does a client object exist") so `startWorkflow` can't mutate local scope
+     * state and emit an event the transport would silently drop underneath it.
+     */
+    isEnabled() {
+        return this.transport.isEnabled();
+    }
+    /** Debug-gated warning log, matching the transport's own `[sauron]`-prefixed convention. */
+    debugLog(message, ...args) {
+        if (this.options.debug) {
+            // eslint-disable-next-line no-console
+            console.warn(`[sauron] ${message}`, ...args);
+        }
+    }
+    /**
+     * Emit the closing lifecycle event (`$workflow_end`/`$workflow_cancel`) for
+     * `active` while it is STILL the current scope's workflow (so the item-level
+     * `workflow_id`/`workflow_name` stamped by `dispatch()` are its own, not
+     * `null`/absent), through `track()` so scope tags/contexts/extra apply.
+     * Never mutates scope state itself — callers own clearing it, in a `finally`
+     * relative to this call, so a throw here can't leave state half-mutated.
+     *
+     * The `distinctId` comes from {@link SauronClient.workflowDistinctId} — read
+     * its note on the `'system'` fallback's effect on unique-user counts.
+     */
+    emitWorkflowClose(active, eventName, reason) {
+        const properties = {
+            workflow_id: active.workflowId,
+            workflow_name: active.name,
+            duration_ms: Math.max(0, Date.now() - Date.parse(active.startedAt)),
+        };
+        if (eventName === '$workflow_cancel') {
+            properties.reason = normalizeReason(reason);
+        }
+        this.emitEvent(eventName, this.workflowDistinctId(), properties);
+    }
+    /**
+     * The `distinct_id` to attribute a workflow lifecycle event to: the scope's
+     * user id, else **the empty string**.
+     *
+     * Empty is deliberate and correct — do NOT "fix" this to a sentinel like
+     * `'system'`, an anonymous/device id, or anything derived from the workflow
+     * id. The server was built for exactly this case:
+     *
+     *   - `backend/crates/sauron-pipeline/src/process.rs` — both `bump_workflow`
+     *     call sites pass `Some(distinct_id.as_str()).filter(|s| !s.is_empty())`,
+     *     so an empty id is stored as SQL `NULL` on the `workflows` row.
+     *   - `backend/crates/sauron-db/src/repo.rs` — the per-workflow rollup
+     *     computes `COUNT(DISTINCT w.distinct_id) AS unique_users`, and
+     *     `COUNT(DISTINCT ...)` skips NULLs.
+     *
+     * So an anonymous workflow run contributes *nothing* to `unique_users`,
+     * which is honest. Any non-empty sentinel would instead collapse every
+     * anonymous run of a workflow (`password_reset`, `guest_checkout`, …) into
+     * one fake bucket, silently reporting ~1 unique user no matter how many
+     * distinct invocations occurred.
+     *
+     * `EventItem.distinct_id` is a required string on the wire
+     * (`backend/crates/sauron-core/src/envelope.rs`), so the field is still
+     * always sent — it is just `""`. This is why the lifecycle emits route
+     * through {@link emitEvent} rather than the public {@link track}, whose
+     * empty-`distinctId` guard would otherwise drop them entirely.
+     */
+    workflowDistinctId() {
+        return getCurrentScope().data.user?.id ?? '';
+    }
+    /**
+     * Start a named workflow on the current scope (the `AsyncLocalStorage`
+     * child inside `withScope`/`runWithAsyncScope`, else the process-wide
+     * global scope) — request-isolated, so concurrent requests never observe
+     * or clobber each other's workflow. `force: true` supersedes an
+     * already-active workflow (emitting `$workflow_cancel` with
+     * `reason: 'superseded'` for it first); otherwise an active workflow makes
+     * this a no-op returning `already_active`.
+     *
+     * The workflow id is a fresh `randomUUID()`, minted here — never derived
+     * from anything deterministic. The server's rollup key is
+     * `(app_id, workflow_id)` app-wide, so a reused/derived id would merge
+     * counters from unrelated requests/environments into one row.
+     *
+     * Never throws: an unexpected failure before any side effect is reported as
+     * `disabled`, and `disabled` always means literally nothing happened — no
+     * event on the wire, no state change. A failure emitting `$workflow_start`
+     * AFTER the scope's workflow field was set is still reported as `ok` — the
+     * workflow IS live locally, and a lost start event is recoverable
+     * server-side (the row materializes from the next stamped item via the same
+     * upsert); a lost local id would not be.
+     */
+    startWorkflow(name, options) {
+        try {
+            if (!this.isEnabled())
+                return { status: 'disabled' };
+            const normalized = normalizeWorkflowName(name);
+            if (!normalized) {
+                this.debugLog('startWorkflow: invalid name', name);
+                return { status: 'invalid_name' };
+            }
+            const scope = getCurrentScope();
+            const active = scope.data.workflow;
+            if (active && !options?.force) {
+                this.debugLog(`startWorkflow("${normalized}"): "${active.name}" is already active; pass { force: true } to replace it`);
+                return { status: 'already_active' };
+            }
+            // Mint the replacement BEFORE superseding anything. If `randomUUID()` or
+            // `isoNow()` throws, the outer catch returns `disabled` — which promises
+            // the caller that nothing happened and their old workflow is still
+            // running. Minting after the supersede emit would break that promise:
+            // `$workflow_cancel` for the old workflow would already be on the wire
+            // while `scope.data.workflow` still held it, so the caller's eventual
+            // `endWorkflow()` would emit a SECOND terminal lifecycle event for a
+            // workflow row the server already recorded as cancelled.
+            const workflow = {
+                workflowId: randomUUID(),
+                name: normalized,
+                startedAt: isoNow(),
+            };
+            if (active) {
+                // force: supersede the old workflow. Emitted while it is still
+                // `scope.data.workflow`, so `dispatch()` stamps the cancel with it.
+                try {
+                    this.emitWorkflowClose(active, '$workflow_cancel', 'superseded');
+                }
+                catch (emitErr) {
+                    this.debugLog('startWorkflow: superseding $workflow_cancel emit threw', emitErr);
+                }
+            }
+            // Set state BEFORE emitting so $workflow_start is itself stamped with it.
+            scope.data.workflow = workflow;
+            try {
+                this.emitEvent('$workflow_start', this.workflowDistinctId(), {
+                    workflow_id: workflow.workflowId,
+                    workflow_name: workflow.name,
+                });
+            }
+            catch (emitErr) {
+                this.debugLog('startWorkflow: $workflow_start emit threw (workflow stays active)', emitErr);
+            }
+            return { status: 'ok', workflowId: workflow.workflowId };
+        }
+        catch (err) {
+            this.debugLog('startWorkflow threw', err);
+            return { status: 'disabled' };
+        }
+    }
+    /** Shared precondition + close logic for `endWorkflow`/`cancelWorkflow`. */
+    closeWorkflow(eventName, name, reason) {
+        try {
+            if (!this.isEnabled())
+                return { status: 'disabled' };
+            const scope = getCurrentScope();
+            const active = scope.data.workflow;
+            if (!active)
+                return { status: 'not_active' };
+            if (name !== undefined && normalizeWorkflowName(name) !== active.name) {
+                this.debugLog(`${eventName}: "${name}" does not match active workflow "${active.name}"`);
+                return { status: 'name_mismatch' };
+            }
+            const workflowId = active.workflowId;
+            try {
+                this.emitWorkflowClose(active, eventName, reason);
+            }
+            catch (emitErr) {
+                this.debugLog(`${eventName} emit threw`, emitErr);
+            }
+            finally {
+                // Clear AFTER emitting (so the closing event still carries the
+                // workflow it closes) but UNCONDITIONALLY — even if the emit above
+                // threw, endWorkflow/cancelWorkflow must still return `ok` below
+                // rather than leaving state half-mutated.
+                scope.data.workflow = null;
+            }
+            return { status: 'ok', workflowId };
+        }
+        catch (err) {
+            this.debugLog(`${eventName} threw`, err);
+            return { status: 'disabled' };
+        }
+    }
+    /**
+     * End the active workflow (or the one named `name`, if given). Emits
+     * `$workflow_end` with `duration_ms` and clears the scope's workflow field.
+     * A no-op returning `not_active` (nothing active) or `name_mismatch` (`name`
+     * given but does not match, including a `name` that fails normalization).
+     */
+    endWorkflow(name) {
+        return this.closeWorkflow('$workflow_end', name);
+    }
+    /**
+     * Cancel the active workflow (or the one named `name`, if given). Emits
+     * `$workflow_cancel` with `duration_ms` and `reason` (default `'user'`,
+     * trimmed and capped at 120 chars) and clears the scope's workflow field.
+     */
+    cancelWorkflow(name, options) {
+        return this.closeWorkflow('$workflow_cancel', name, options?.reason);
+    }
     /** Send any buffered items immediately. */
     flush() {
         return this.transport.flush();
@@ -268,6 +515,11 @@ export class SauronClient {
     close() {
         for (const uninstall of this.hookUninstallers.splice(0))
             uninstall();
+        // Clear (never auto-cancel — an abandoned workflow is a legitimate,
+        // server-derived 30-minute outcome) any workflow left on the shared
+        // global scope, so a later init() sharing the same process-wide scope
+        // doesn't inherit a stale one.
+        getGlobalScope().data.workflow = null;
         return this.transport.close();
     }
 }

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * HTTP transport over Node's global `fetch`.
  */
 import { SauronClient } from './client.js';
-import type { BreadcrumbInput, CaptureExceptionOptions, InitOptions, Level, MetadataOptions, TransactionInput, User } from './types.js';
+import type { BreadcrumbInput, CaptureExceptionOptions, InitOptions, Level, MetadataOptions, TransactionInput, User, WorkflowResult } from './types.js';
 export { SauronClient, describeError } from './client.js';
 export { parseDsn, DsnError } from './dsn.js';
 export type { Dsn } from './dsn.js';
@@ -15,6 +15,8 @@ export { Transport } from './transport.js';
 export { Scope, getGlobalScope, getCurrentScope, withScope, runWithAsyncScope, configureScope, } from './scope.js';
 export { installAutoCapture, installShutdownHooks } from './autocapture.js';
 export type { AutoCaptureOptions } from './autocapture.js';
+/** Bare read of the current scope's workflow — client-agnostic, never throws. */
+export { getWorkflow } from './workflow.js';
 export type * from './types.js';
 /**
  * Initialize the global Sauron client. Returns the client for direct use.
@@ -41,6 +43,26 @@ export declare function trackTransaction(input: TransactionInput): void;
  * SDK is not initialized.
  */
 export declare function addBreadcrumb(crumb: BreadcrumbInput): void;
+/**
+ * Start a named workflow on the current scope (request-isolated via
+ * `AsyncLocalStorage` — see `withScope`). No-op state-wise and returns
+ * `{ status: 'disabled' }` if the SDK is not initialized.
+ */
+export declare function startWorkflow(name: string, options?: {
+    force?: boolean;
+}): WorkflowResult;
+/**
+ * End the active workflow (or the one named `name`, if given). Returns
+ * `{ status: 'disabled' }` if the SDK is not initialized.
+ */
+export declare function endWorkflow(name?: string): WorkflowResult;
+/**
+ * Cancel the active workflow (or the one named `name`, if given). Returns
+ * `{ status: 'disabled' }` if the SDK is not initialized.
+ */
+export declare function cancelWorkflow(name?: string, options?: {
+    reason?: string;
+}): WorkflowResult;
 /** Set the user on the active scope (the global scope outside a `withScope`). */
 export declare function setUser(user: User | null): void;
 /** Set a single tag on the active scope. */

package/dist/index.js

@@ -13,6 +13,8 @@ export { parseStackString, parseError, isInAppFrame } from './stacktrace.js';
 export { Transport } from './transport.js';
 export { Scope, getGlobalScope, getCurrentScope, withScope, runWithAsyncScope, configureScope, } from './scope.js';
 export { installAutoCapture, installShutdownHooks } from './autocapture.js';
+/** Bare read of the current scope's workflow — client-agnostic, never throws. */
+export { getWorkflow } from './workflow.js';
 let activeClient = null;
 /**
  * Initialize the global Sauron client. Returns the client for direct use.
@@ -56,6 +58,28 @@ export function trackTransaction(input) {
 export function addBreadcrumb(crumb) {
     activeClient?.addBreadcrumb(crumb);
 }
+/**
+ * Start a named workflow on the current scope (request-isolated via
+ * `AsyncLocalStorage` — see `withScope`). No-op state-wise and returns
+ * `{ status: 'disabled' }` if the SDK is not initialized.
+ */
+export function startWorkflow(name, options) {
+    return activeClient?.startWorkflow(name, options) ?? { status: 'disabled' };
+}
+/**
+ * End the active workflow (or the one named `name`, if given). Returns
+ * `{ status: 'disabled' }` if the SDK is not initialized.
+ */
+export function endWorkflow(name) {
+    return activeClient?.endWorkflow(name) ?? { status: 'disabled' };
+}
+/**
+ * Cancel the active workflow (or the one named `name`, if given). Returns
+ * `{ status: 'disabled' }` if the SDK is not initialized.
+ */
+export function cancelWorkflow(name, options) {
+    return activeClient?.cancelWorkflow(name, options) ?? { status: 'disabled' };
+}
 /** Set the user on the active scope (the global scope outside a `withScope`). */
 export function setUser(user) {
     getCurrentScope().setUser(user);

package/dist/scope.js

@@ -39,6 +39,7 @@ export class Scope {
         contexts: {},
         extra: {},
         breadcrumbs: [],
+        workflow: null,
     };
     maxBreadcrumbs;
     constructor(maxBreadcrumbs = DEFAULT_MAX_BREADCRUMBS) {
@@ -87,6 +88,10 @@ export class Scope {
         copy.data.contexts = { ...this.data.contexts };
         copy.data.extra = { ...this.data.extra };
         copy.data.breadcrumbs = this.data.breadcrumbs.slice();
+        // ActiveWorkflow is never mutated in place (always replaced wholesale by
+        // startWorkflow/endWorkflow/cancelWorkflow), so sharing the reference is
+        // safe — no need to deep-copy it.
+        copy.data.workflow = this.data.workflow;
         return copy;
     }
     /**

package/dist/transport.d.ts

@@ -2,7 +2,6 @@ import type { Dsn } from './dsn.js';
 import type { Context, EnvelopeItem, FetchLike, SleepFn } from './types.js';
 export interface TransportConfig {
     dsn: Dsn;
-    environment: string;
     release: string | null;
     context: Context;
     flushInterval: number;
@@ -74,6 +73,8 @@ export declare class Transport {
     private flushChain;
     constructor(config: TransportConfig);
     private startTimer;
+    /** Whether the transport still accepts items (false once auth-disabled by a 401/403). */
+    isEnabled(): boolean;
     /** Enqueue an item; triggers an eager flush at `maxBatch`. */
     enqueue(item: EnvelopeItem): void;
     private buildEnvelope;

package/dist/transport.js

@@ -1,7 +1,7 @@
 import { maybeGzip } from './gzip.js';
 import { BoundedQueue } from './queue.js';
 const SDK_NAME = 'sauron-node';
-const SDK_VERSION = '1.0.0';
+const SDK_VERSION = '1.4.0';
 /** Default exponential-backoff base (ms) for the first retry. */
 const DEFAULT_RETRY_BASE_MS = 200;
 /** Hard cap on any single backoff delay (ms). */
@@ -99,6 +99,10 @@ export class Transport {
         if (typeof this.timer.unref === 'function')
             this.timer.unref();
     }
+    /** Whether the transport still accepts items (false once auth-disabled by a 401/403). */
+    isEnabled() {
+        return !this.disabled;
+    }
     /** Enqueue an item; triggers an eager flush at `maxBatch`. */
     enqueue(item) {
         if (this.disabled)
@@ -113,7 +117,6 @@ export class Transport {
             dsn: this.config.dsn.raw,
             sdk: { name: SDK_NAME, version: SDK_VERSION },
             sent_at: new Date().toISOString(),
-            environment: this.config.environment,
             release: this.config.release,
         };
         return { header, context: this.config.context, items };