@edraj/sauron-node 1.0.0 → 1.4.0

package/dist/types.d.ts

@@ -68,6 +68,30 @@ export interface ScopeData {
     contexts: Record<string, unknown>;
     extra: Record<string, unknown>;
     breadcrumbs: Breadcrumb[];
+    /**
+     * The workflow bounded by `startWorkflow`/`endWorkflow`/`cancelWorkflow` on
+     * THIS scope, or `null` if none. Request-isolated: the async-local child
+     * scope created by `withScope`/`runWithAsyncScope` gets its own copy, so
+     * concurrent requests never observe each other's workflow.
+     */
+    workflow: ActiveWorkflow | null;
+}
+/** Exactly six reachable outcomes for a workflow lifecycle call. No seventh. */
+export type WorkflowStatus = 'ok' | 'already_active' | 'not_active' | 'name_mismatch' | 'invalid_name' | 'disabled';
+/** Return value of `startWorkflow` / `endWorkflow` / `cancelWorkflow`. */
+export interface WorkflowResult {
+    status: WorkflowStatus;
+    /** Present when `status` is `'ok'`. */
+    workflowId?: string;
+}
+/** The workflow currently bounded on a scope. */
+export interface ActiveWorkflow {
+    /** Fresh client-generated UUID v4, minted by `startWorkflow`. */
+    workflowId: string;
+    /** Trimmed, caller-supplied name (see `normalizeWorkflowName`). */
+    name: string;
+    /** ISO-8601 timestamp of when the workflow started. */
+    startedAt: string;
 }
 /** An error item (manual `captureException` / `captureMessage`). */
 export interface ErrorItem {
@@ -84,6 +108,14 @@ export interface ErrorItem {
     fingerprint: string[] | null;
     user: ErrorUser | null;
     session_id: string | null;
+    /**
+     * Id/name of the workflow this error occurred within, if the SDK bounded
+     * one via `startWorkflow`. Optional-not-nullable: apps that never use
+     * workflows must be byte-identical to before this field existed, so an
+     * absent workflow means the key is OMITTED from the item, never `null`.
+     */
+    workflow_id?: string;
+    workflow_name?: string;
     screen: string | null;
 }
 /** A product-analytics event (PostHog-style `track`). */
@@ -94,6 +126,9 @@ export interface EventItem {
     properties: Record<string, unknown>;
     timestamp: string;
     session_id: string | null;
+    /** See {@link ErrorItem.workflow_id} — same omit-not-null convention. */
+    workflow_id?: string;
+    workflow_name?: string;
     screen: string | null;
     tags?: Record<string, string>;
     contexts?: Record<string, unknown>;
@@ -122,6 +157,9 @@ export interface TransactionItem {
     http_status?: number;
     url?: string;
     distinct_id?: string;
+    /** See {@link ErrorItem.workflow_id} — same omit-not-null convention. */
+    workflow_id?: string;
+    workflow_name?: string;
     timestamp: string;
 }
 /** Caller input for {@link TransactionItem} via `trackTransaction`. */
@@ -129,7 +167,20 @@ export interface TransactionInput {
     name: string;
     /** Operation class: `navigation | http | resource | screen_load | custom`. Default `custom`. */
     op?: string;
-    duration_ms: number;
+    duration_ms?: number;
+    /**
+     * Accepted alias for {@link duration_ms}.
+     *
+     * The browser SDK's equivalent input takes `durationMs` (`sdks/js`), so a
+     * snippet moved between the two — or any plain-JavaScript caller, where the
+     * type checker is not there to object — used to produce a transaction with no
+     * duration at all. The item still validated and still shipped, just without
+     * the one field it exists to carry, which is the worst possible outcome: no
+     * error anywhere and a silently useless performance record.
+     *
+     * Supply exactly one. `duration_ms` wins if both are present.
+     */
+    durationMs?: number;
     status?: string;
     http_method?: string;
     http_status?: number;
@@ -169,7 +220,6 @@ export interface EnvelopeHeader {
     dsn: string;
     sdk: SdkInfo;
     sent_at: string;
-    environment: string;
     release: string | null;
 }
 /** The complete, serializable envelope posted to the ingest gateway. */
@@ -223,7 +273,6 @@ export interface TransportOptions {
 export interface InitOptions {
     /** `https://<public_key>@<host>/<project_id>` */
     dsn: string;
-    environment?: string;
     release?: string | null;
     /** Default tags seeded into the global scope at init. */
     tags?: Record<string, string>;
@@ -269,7 +318,6 @@ export interface InitOptions {
 /** Fully-resolved options with all defaults applied. */
 export interface ResolvedOptions {
     dsn: string;
-    environment: string;
     release: string | null;
     tags: Record<string, string>;
     contexts: Record<string, unknown>;

package/dist/workflow.d.ts

@@ -0,0 +1,26 @@
+import type { ActiveWorkflow } from './types.js';
+/** Cap on a workflow name, after trimming. */
+export declare const WORKFLOW_NAME_MAX = 120;
+/** Cap on a cancel reason. */
+export declare const WORKFLOW_REASON_MAX = 120;
+/**
+ * Returns the trimmed name, or `null` when invalid (not a string, empty after
+ * trimming, or over {@link WORKFLOW_NAME_MAX} characters). Trims BEFORE
+ * checking length/emptiness so an all-whitespace or over-long-but-padded name
+ * is rejected rather than silently truncated.
+ */
+export declare function normalizeWorkflowName(name: unknown): string | null;
+/**
+ * Normalize a cancel reason: default to `'user'` for a non-string or
+ * all-whitespace value, else trim and cap at {@link WORKFLOW_REASON_MAX}.
+ * The internal `force`-supersede path also routes its literal `'superseded'`
+ * reason through this, so every reason on the wire is consistently shaped.
+ */
+export declare function normalizeReason(reason: unknown): string;
+/**
+ * The active workflow on the CURRENT scope — the `AsyncLocalStorage` child
+ * inside `withScope`/`runWithAsyncScope`, else the process-wide global scope —
+ * or `null` if none. Client-agnostic: reflects scope state regardless of
+ * whether an SDK client is initialized, same as `getCurrentScope()` itself.
+ */
+export declare function getWorkflow(): ActiveWorkflow | null;

package/dist/workflow.js

@@ -0,0 +1,51 @@
+/**
+ * Workflow name/reason normalization — pure helpers, no state of their own.
+ *
+ * Unlike the browser SDK (`sdks/js/src/workflow.ts`), the active workflow is
+ * NOT held in a module-level variable here: a module global would leak one
+ * HTTP request's workflow into every other concurrent request's telemetry.
+ * Instead it lives on the per-request {@link Scope} (`scope.data.workflow`),
+ * isolated by `AsyncLocalStorage` exactly like `user`/`tags`/`breadcrumbs`
+ * already are (see `scope.ts`). `getWorkflow()` below is a bare read of that
+ * scope field — it takes no client and never throws, mirroring the existing
+ * `getCurrentScope()`/`getGlobalScope()` getters.
+ */
+import { getCurrentScope } from './scope.js';
+/** Cap on a workflow name, after trimming. */
+export const WORKFLOW_NAME_MAX = 120;
+/** Cap on a cancel reason. */
+export const WORKFLOW_REASON_MAX = 120;
+/**
+ * Returns the trimmed name, or `null` when invalid (not a string, empty after
+ * trimming, or over {@link WORKFLOW_NAME_MAX} characters). Trims BEFORE
+ * checking length/emptiness so an all-whitespace or over-long-but-padded name
+ * is rejected rather than silently truncated.
+ */
+export function normalizeWorkflowName(name) {
+    if (typeof name !== 'string')
+        return null;
+    const trimmed = name.trim();
+    if (trimmed.length === 0 || trimmed.length > WORKFLOW_NAME_MAX)
+        return null;
+    return trimmed;
+}
+/**
+ * Normalize a cancel reason: default to `'user'` for a non-string or
+ * all-whitespace value, else trim and cap at {@link WORKFLOW_REASON_MAX}.
+ * The internal `force`-supersede path also routes its literal `'superseded'`
+ * reason through this, so every reason on the wire is consistently shaped.
+ */
+export function normalizeReason(reason) {
+    if (typeof reason !== 'string' || reason.trim().length === 0)
+        return 'user';
+    return reason.trim().slice(0, WORKFLOW_REASON_MAX);
+}
+/**
+ * The active workflow on the CURRENT scope — the `AsyncLocalStorage` child
+ * inside `withScope`/`runWithAsyncScope`, else the process-wide global scope —
+ * or `null` if none. Client-agnostic: reflects scope state regardless of
+ * whether an SDK client is initialized, same as `getCurrentScope()` itself.
+ */
+export function getWorkflow() {
+    return getCurrentScope().data.workflow;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edraj/sauron-node",
-  "version": "1.0.0",
+  "version": "1.4.0",
   "description": "Sauron server-side Node/TypeScript SDK: product-analytics events + exception capture for Node backends.",
   "homepage": "https://github.com/edraj/sauron/tree/main/sdks/node#readme",
   "repository": {