@edraj/sauron-node 1.4.0 → 1.6.0

package/README.md

@@ -56,13 +56,13 @@ adding `Content-Encoding: gzip` once the body crosses the gzip threshold.
 
 ## Configuration
 
-`init(options)` takes a single `InitOptions` object. Every field except `dsn` is
-optional.
+`init(options)` takes a single `InitOptions` object. Every field except `dsn`
+and `release` is optional.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `dsn` | `string` | — (**required**) | `https://<public_key>@<host>/<environment_id>`. A non-string throws `Error`; a malformed value throws `DsnError`. |
-| `release` | `string \| null` | `null` | Written to `header.release`. |
+| `dsn` | `string` | — (**required**) | `https://<public_key>@<host>/<environment_id>`. A non-string or empty value throws `Error`; a malformed value throws `DsnError`. |
+| `release` | `string` | — (**required**) | The app version this build reports as, written to `header.release`. Missing or whitespace-only throws `Error`. Trimmed before it is sent. |
 | `tags` | `Record<string, string>` | `{}` | Default tags seeded into the global scope at init. |
 | `contexts` | `Record<string, unknown>` | `{}` | Default named dev context blocks seeded into the global scope. Distinct from the machine `context` (device/os/app/runtime). |
 | `extra` | `Record<string, unknown>` | `{}` | Default free-form extra values seeded into the global scope. |
@@ -140,11 +140,12 @@ function init(options: InitOptions): SauronClient
 | `options` | `InitOptions` | — (required) | See [Configuration](#configuration). |
 
 Returns the `SauronClient` it created, and installs it as the active client.
-Throws `Error` when `options.dsn` is not a string, and `DsnError` when the DSN
-is malformed.
+Throws `Error` when `options.dsn` is missing/empty/not a string, when
+`options.release` is missing or blank (**required as of v1.6.0**), and
+`DsnError` when the DSN is malformed.
 
 ```ts
-const client = init({ dsn: 'https://pk@ingest.example.com/42' });
+const client = init({ dsn: 'https://pk@ingest.example.com/42', release: 'api@1.4.2' });
 ```
 
 ### `getClient()`
@@ -275,10 +276,28 @@ function trackTransaction(input: TransactionInput): void
 | `input.http_status` | `number` | omitted | e.g. `200`. |
 | `input.url` | `string` | omitted | Request URL/path. |
 | `input.distinct_id` | `string` | scope user's `id`, else omitted | Explicit value wins over the scope. |
+| `input.tags` | `Record<string, string>` | omitted | Indexed string→string labels. Filter with `@tag.key:value` on the Transactions page. |
+| `input.extra` | `Record<string, unknown>` | omitted | Freeform JSON — request body, response body, SQL text, row counts. Searchable with `extra.key:value`. |
 
 Emits a `transaction` item. Absent optional fields are omitted from the wire JSON
 rather than serialized as `null`. Returns `void`.
 
+**`tags` and `extra` are per-call only.** Unlike `track()` and
+`captureException()`, a transaction does **not** inherit the scope:
+`setTag()` / `setExtra()` defaults are not merged in. Transactions are the
+highest-volume signal a service emits — one per request and per query — so
+inheriting a global blob would write it onto every row.
+
+`extra` is serialized and capped at **16 KB**
+(`MAX_TRANSACTION_EXTRA_BYTES`, exported from `transaction-extra`). Past that
+the whole map is replaced with `{ _truncated: true, _bytes: N }` and the
+dashboard says so on the row. The cap is not cosmetic: envelopes are batched,
+and one oversized body would push the whole envelope past the ingest limit and
+drop every unrelated span sent with it.
+
+Nothing in `extra` is scrubbed. Use `beforeSend` for redaction, and think twice
+before attaching a body that can carry tokens, passwords or personal data.
+
 ```ts
 const started = Date.now();
 await handler(req, res);
@@ -293,6 +312,128 @@ trackTransaction({
 });
 ```
 
+#### Example: an Express route, with request and response bodies
+
+`res.json` is wrapped rather than read afterwards, because by the time the
+`finish` event fires the payload is already on the wire and gone.
+
+```ts
+import express from 'express';
+import { trackTransaction } from '@edraj/sauron-node';
+
+export function tracedRoute(routeLabel: string, handler: express.RequestHandler) {
+  return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const started = Date.now();
+    let responseBody: unknown;
+
+    // Capture on the way out. Reading it in `finish` is too late — the body
+    // has already been serialized and released by then.
+    const json = res.json.bind(res);
+    res.json = (body: unknown) => {
+      responseBody = body;
+      return json(body);
+    };
+
+    res.on('finish', () => {
+      trackTransaction({
+        name: routeLabel,              // 'POST /orders', NOT '/orders/8412'
+        op: 'http',
+        duration_ms: Date.now() - started,
+        http_method: req.method,
+        http_status: res.statusCode,
+        url: req.originalUrl,
+        status: res.statusCode < 400 ? 'ok' : 'error',
+        distinct_id: (req as { userId?: string }).userId,
+        tags: { route: routeLabel, tier: (req as { plan?: string }).plan ?? 'free' },
+        extra: {
+          request: req.body,
+          response: responseBody,
+          query: req.query,
+          // Header VALUES are omitted on purpose — `authorization` and
+          // `cookie` live there.
+          request_headers: Object.keys(req.headers),
+        },
+      });
+    });
+
+    try {
+      await handler(req, res, next);
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+const app = express();
+app.post('/orders', tracedRoute('POST /orders', createOrder));
+```
+
+On the dashboard: **Transactions → the row → expand**. Both bodies render as a
+JSON tree, and every one of these finds it:
+
+```text
+extra.response:~9001        # substring, inside the stored response body
+@tag.route:"POST /orders"   # indexed tag
+op:http http.status:>=500   # the failures
+duration:>2s                # the slow ones
+```
+
+#### Example: a SQL query (`pg`)
+
+Put the **statement** in `extra` and keep `name` a stable label — a query with
+literals baked in would mint a new dashboard row per execution.
+
+```ts
+import { Pool } from 'pg';
+import { trackTransaction } from '@edraj/sauron-node';
+
+const pool = new Pool();
+
+export async function tracedQuery<T>(label: string, sql: string, params: unknown[] = []) {
+  const started = Date.now();
+  try {
+    const result = await pool.query<T>(sql, params);
+    trackTransaction({
+      // The LABEL, not the statement. `op` is free-form on this SDK, so a
+      // 'db' op is stored as-is — but note the browser SDK coerces anything
+      // outside navigation|http|resource|screen_load|custom to 'custom', so
+      // use a tag if you need the two to agree.
+      name: label,
+      op: 'db',
+      duration_ms: Date.now() - started,
+      status: 'ok',
+      tags: { db: 'postgres', table: 'orders' },
+      extra: {
+        statement: sql,
+        row_count: result.rowCount,
+        // Bind PARAMETERS are user data. Log them only if you have decided
+        // that is acceptable, or log their shape instead.
+        params,
+      },
+    });
+    return result;
+  } catch (err) {
+    trackTransaction({
+      name: label,
+      op: 'db',
+      duration_ms: Date.now() - started,
+      status: 'error',
+      tags: { db: 'postgres', table: 'orders' },
+      extra: { statement: sql, error: String(err) },
+    });
+    throw err;
+  }
+}
+
+await tracedQuery(
+  'SELECT orders',
+  'SELECT id, total FROM orders WHERE user_id = $1 ORDER BY created_at DESC LIMIT 20',
+  [userId],
+);
+```
+
+Then `@tag.table:orders duration:>500ms` is your slow-query list.
+
 ### `addBreadcrumb(crumb)`
 
 ```ts
@@ -683,7 +824,7 @@ Re-entrancy is guarded, so a throw inside the capture path cannot loop. Prefer
 down on `close()`.
 
 ```ts
-const client = init({ dsn: DSN });
+const client = init({ dsn: DSN, release: 'api@1.4.2' });
 const uninstall = installAutoCapture(client);
 // later
 uninstall();
@@ -715,7 +856,7 @@ signal fires — if you need to drain HTTP connections first, leave `autoShutdow
 off and call `close()` yourself from your own handler.
 
 ```ts
-const client = init({ dsn: DSN });
+const client = init({ dsn: DSN, release: 'api@1.4.2' });
 const uninstall = installShutdownHooks(client);
 ```
 
@@ -948,7 +1089,7 @@ Emit conventions on the wire:
   `distinct_id` fallback from the scope's user id.
 
 ```ts
-init({ dsn: DSN, tags: { service: 'checkout' } });   // layer 1
+init({ dsn: DSN, release: 'api@1.4.2', tags: { service: 'checkout' } });   // layer 1
 
 setTag('region', 'eu-west-1');                        // layer 2 (global)
 
@@ -1054,7 +1195,7 @@ import {
   init, withScope, addBreadcrumb, captureException, trackTransaction, close,
 } from '@edraj/sauron-node';
 
-init({ dsn: process.env.SAURON_DSN!, autoCaptureUnhandled: true });
+init({ dsn: process.env.SAURON_DSN!, release: process.env.GIT_SHA, autoCaptureUnhandled: true });
 
 const fastify = Fastify();
 const startedAt = new WeakMap<object, number>();
@@ -1195,4 +1336,5 @@ npm run typecheck   # tsc --noEmit
 
 ## License
 
-AGPL-3.0-only — GNU Affero General Public License v3.0.
+LGPL-3.0-only — GNU Lesser General Public License v3.0. LGPLv3 applies on top of
+the GNU GPL v3, whose text ships alongside it in `COPYING`.

package/dist/client.js

@@ -6,8 +6,8 @@ import { parseError } from './stacktrace.js';
 import { installAutoCapture, installShutdownHooks } from './autocapture.js';
 import { getCurrentScope, getGlobalScope, normalizeBreadcrumb, } from './scope.js';
 import { normalizeReason, normalizeWorkflowName } from './workflow.js';
+import { capTransactionExtra } from './transaction-extra.js';
 const DEFAULTS = {
-    release: null,
     sampleRate: 1,
     flushInterval: 5000,
     maxBatch: 30,
@@ -18,13 +18,16 @@ const DEFAULTS = {
     debug: false,
 };
 function resolveOptions(options) {
-    if (!options || typeof options.dsn !== 'string') {
+    if (!options || typeof options.dsn !== 'string' || options.dsn.length === 0) {
         throw new Error('[sauron] init requires a { dsn } option');
     }
+    if (typeof options.release !== 'string' || options.release.trim().length === 0) {
+        throw new Error('[sauron] init requires a { release } option (the app version this build reports as)');
+    }
     const sampleRate = typeof options.sampleRate === 'number' ? options.sampleRate : DEFAULTS.sampleRate;
     return {
         dsn: options.dsn,
-        release: options.release ?? DEFAULTS.release,
+        release: options.release.trim(),
         tags: options.tags ?? {},
         contexts: options.contexts ?? {},
         extra: options.extra ?? {},
@@ -210,6 +213,15 @@ export class SauronClient {
             item.url = input.url;
         if (distinctId != null)
             item.distinct_id = distinctId;
+        // Per-call only — deliberately no `globalScope.tags`/`.extra` merge here,
+        // unlike `track()` and `captureException` below. See TransactionInput.
+        // Omitted when empty so an app that never sets them is byte-identical on
+        // the wire to before these fields existed.
+        if (input.tags && Object.keys(input.tags).length > 0)
+            item.tags = { ...input.tags };
+        if (input.extra && Object.keys(input.extra).length > 0) {
+            item.extra = capTransactionExtra({ ...input.extra });
+        }
         this.dispatch(item);
     }
     /** Capture a product-analytics event. `distinctId` is required. */

package/dist/index.d.ts

@@ -77,3 +77,4 @@ export declare function setExtra(key: string, value: unknown): void;
 export declare function flush(): Promise<void>;
 /** Flush and stop the background timer, then clear the active client. */
 export declare function close(): Promise<void>;
+export { MAX_TRANSACTION_EXTRA_BYTES, capTransactionExtra, } from './transaction-extra.js';

package/dist/index.js

@@ -112,3 +112,6 @@ export async function close() {
     activeClient = null;
     await client.close();
 }
+// Exported so a caller can size a payload BEFORE attaching it — the cap is
+// otherwise invisible until the dashboard shows a truncation marker.
+export { MAX_TRANSACTION_EXTRA_BYTES, capTransactionExtra, } from './transaction-extra.js';

package/dist/transaction-extra.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The size cap on a transaction's developer-supplied `extra`.
+ *
+ * Its own module rather than a private helper inside `client.ts` so the limit
+ * and its behaviour are directly testable — the failure this guards against
+ * (an oversized payload taking a whole batched envelope down with it) is not
+ * visible from the outside once it happens.
+ */
+/**
+ * Largest serialized `extra` a single transaction may carry, in bytes.
+ *
+ * Transactions are the highest-volume signal and they ship in BATCHED
+ * envelopes, so one oversized payload does not fail alone — ingest rejects the
+ * whole envelope past `INGEST_MAX_BODY_BYTES` (1 MiB by default) and every
+ * unrelated span batched with it is lost. Since the motivating use of
+ * transaction `extra` is request and response bodies, that is not a remote
+ * hazard.
+ *
+ * Kept identical across all five SDKs. If it moves, it moves everywhere.
+ */
+export declare const MAX_TRANSACTION_EXTRA_BYTES: number;
+/**
+ * Cap a transaction's `extra`, substituting a marker when it is too large.
+ *
+ * Replaces the WHOLE map rather than trimming keys: a half-written JSON value
+ * is worse than an honest marker, and per-key trimming would make the result
+ * depend on key iteration order, which differs across the five SDKs. The marker
+ * is deliberately readable on the dashboard — `_truncated` says data was
+ * dropped rather than silently serving a short object that looks complete.
+ *
+ * A value that cannot be serialized at all (a cycle, a BigInt) becomes the same
+ * marker with `_bytes: -1`, because the alternative is throwing from inside
+ * `trackTransaction` — and an SDK that crashes the app it is measuring is worse
+ * than one that drops a payload.
+ */
+export declare function capTransactionExtra(extra: Record<string, unknown>, maxBytes?: number): Record<string, unknown>;

package/dist/transaction-extra.js

@@ -0,0 +1,53 @@
+/**
+ * The size cap on a transaction's developer-supplied `extra`.
+ *
+ * Its own module rather than a private helper inside `client.ts` so the limit
+ * and its behaviour are directly testable — the failure this guards against
+ * (an oversized payload taking a whole batched envelope down with it) is not
+ * visible from the outside once it happens.
+ */
+/**
+ * Largest serialized `extra` a single transaction may carry, in bytes.
+ *
+ * Transactions are the highest-volume signal and they ship in BATCHED
+ * envelopes, so one oversized payload does not fail alone — ingest rejects the
+ * whole envelope past `INGEST_MAX_BODY_BYTES` (1 MiB by default) and every
+ * unrelated span batched with it is lost. Since the motivating use of
+ * transaction `extra` is request and response bodies, that is not a remote
+ * hazard.
+ *
+ * Kept identical across all five SDKs. If it moves, it moves everywhere.
+ */
+export const MAX_TRANSACTION_EXTRA_BYTES = 16 * 1024;
+/**
+ * Cap a transaction's `extra`, substituting a marker when it is too large.
+ *
+ * Replaces the WHOLE map rather than trimming keys: a half-written JSON value
+ * is worse than an honest marker, and per-key trimming would make the result
+ * depend on key iteration order, which differs across the five SDKs. The marker
+ * is deliberately readable on the dashboard — `_truncated` says data was
+ * dropped rather than silently serving a short object that looks complete.
+ *
+ * A value that cannot be serialized at all (a cycle, a BigInt) becomes the same
+ * marker with `_bytes: -1`, because the alternative is throwing from inside
+ * `trackTransaction` — and an SDK that crashes the app it is measuring is worse
+ * than one that drops a payload.
+ */
+export function capTransactionExtra(extra, maxBytes = MAX_TRANSACTION_EXTRA_BYTES) {
+    let bytes;
+    try {
+        const json = JSON.stringify(extra);
+        if (json === undefined)
+            return { _truncated: true, _bytes: -1 };
+        // UTF-8 byte length, not `json.length`: the latter undercounts every
+        // non-ASCII byte, which is exactly what a response body full of user text
+        // is made of.
+        bytes = Buffer.byteLength(json, 'utf8');
+    }
+    catch {
+        return { _truncated: true, _bytes: -1 };
+    }
+    if (bytes <= maxBytes)
+        return extra;
+    return { _truncated: true, _bytes: bytes };
+}

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.4.0';
+const SDK_VERSION = '1.6.0';
 /** Default exponential-backoff base (ms) for the first retry. */
 const DEFAULT_RETRY_BASE_MS = 200;
 /** Hard cap on any single backoff delay (ms). */

package/dist/types.d.ts

@@ -161,6 +161,17 @@ export interface TransactionItem {
     workflow_id?: string;
     workflow_name?: string;
     timestamp: string;
+    /**
+     * Developer-supplied flat string tags for THIS transaction. NOT merged with
+     * the scope — see {@link TransactionInput.tags}. Omitted when empty.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Developer-supplied freeform JSON for THIS transaction. Capped and replaced
+     * with a truncation marker past `MAX_TRANSACTION_EXTRA_BYTES`. Omitted when
+     * empty.
+     */
+    extra?: Record<string, unknown>;
 }
 /** Caller input for {@link TransactionItem} via `trackTransaction`. */
 export interface TransactionInput {
@@ -187,6 +198,29 @@ export interface TransactionInput {
     url?: string;
     /** Falls back to the scoped user's id when omitted. */
     distinct_id?: string;
+    /**
+     * Flat string tags for this transaction.
+     *
+     * **Per-call only — the scope is NOT merged in**, which is the one place
+     * transactions differ from `track()` and `captureException()`. Those two
+     * merge `setTag`/`setExtra` defaults; a transaction carries only what its own
+     * call site attached. Transactions are the highest-volume signal (one per
+     * navigation and per HTTP call), so inheriting a global blob would write it
+     * onto every row.
+     */
+    tags?: Record<string, string>;
+    /**
+     * Freeform JSON for this transaction — the request body, the response body,
+     * an order id, a retry count.
+     *
+     * Per-call only, for the reason on {@link TransactionInput.tags}. Serialized
+     * and capped at `MAX_TRANSACTION_EXTRA_BYTES`; past that the whole map is
+     * replaced with `{ _truncated: true, _bytes: N }` so one large body cannot
+     * take a batched envelope over the ingest limit and drop every span in it.
+     *
+     * Nothing here is scrubbed. `beforeSend` is the redaction seam.
+     */
+    extra?: Record<string, unknown>;
 }
 /** Any item that can appear in an envelope's `items` array. */
 export type EnvelopeItem = ErrorItem | EventItem | IdentifyItem | TransactionItem;
@@ -273,7 +307,8 @@ export interface TransportOptions {
 export interface InitOptions {
     /** `https://<public_key>@<host>/<project_id>` */
     dsn: string;
-    release?: string | null;
+    /** Required. The app version every event is attributed to. */
+    release: string;
     /** Default tags seeded into the global scope at init. */
     tags?: Record<string, string>;
     /** Default named dev context blocks seeded into the global scope at init. Distinct from the machine `context`. */
@@ -318,7 +353,7 @@ export interface InitOptions {
 /** Fully-resolved options with all defaults applied. */
 export interface ResolvedOptions {
     dsn: string;
-    release: string | null;
+    release: string;
     tags: Record<string, string>;
     contexts: Record<string, unknown>;
     extra: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edraj/sauron-node",
-  "version": "1.4.0",
+  "version": "1.6.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": {
@@ -25,7 +25,8 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "COPYING"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -52,7 +53,7 @@
     "node",
     "server"
   ],
-  "license": "AGPL-3.0-only",
+  "license": "LGPL-3.0-only",
   "publishConfig": {
     "access": "public"
   }