@edraj/sauron-node 1.5.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()`
@@ -823,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();
@@ -855,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);
 ```
 
@@ -1088,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)
 
@@ -1194,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>();
@@ -1335,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

@@ -8,7 +8,6 @@ import { getCurrentScope, getGlobalScope, normalizeBreadcrumb, } from './scope.j
 import { normalizeReason, normalizeWorkflowName } from './workflow.js';
 import { capTransactionExtra } from './transaction-extra.js';
 const DEFAULTS = {
-    release: null,
     sampleRate: 1,
     flushInterval: 5000,
     maxBatch: 30,
@@ -19,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 ?? {},

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.5.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

@@ -307,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`. */
@@ -352,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.5.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"
   }