@strada.sh/light 0.1.0 → 0.2.0

package/dist/attrs.d.ts

@@ -22,5 +22,11 @@ export declare const ATTR: {
     readonly "exception.mechanism.type": "exception.mechanism.type";
     readonly "exception.mechanism.handled": "exception.mechanism.handled";
     readonly "exception.fingerprint": "exception.fingerprint";
+    readonly "session.id": "session.id";
+    readonly "url.path": "url.path";
+    readonly "url.query": "url.query";
+    readonly "url.full": "url.full";
+    readonly "http.request.header.referer": "http.request.header.referer";
+    readonly "pageview.source": "pageview.source";
 };
 //# sourceMappingURL=attrs.d.ts.map

package/dist/attrs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attrs.d.ts","sourceRoot":"","sources":["../src/attrs.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;CAuBP,CAAC"}
+{"version":3,"file":"attrs.d.ts","sourceRoot":"","sources":["../src/attrs.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BP,CAAC"}

package/dist/attrs.js

@@ -22,4 +22,10 @@ export const ATTR = {
     "exception.mechanism.type": "exception.mechanism.type",
     "exception.mechanism.handled": "exception.mechanism.handled",
     "exception.fingerprint": "exception.fingerprint",
+    "session.id": "session.id",
+    "url.path": "url.path",
+    "url.query": "url.query",
+    "url.full": "url.full",
+    "http.request.header.referer": "http.request.header.referer",
+    "pageview.source": "pageview.source",
 };

package/dist/index.d.ts

@@ -1,23 +1,32 @@
 /**
- * `@strada.sh/light`: a zero-dependency, drop-in subset of `@strada.sh/sdk`.
+ * `@strada.sh/light`: a zero-dependency, explicit-only subset of `@strada.sh/sdk`.
  *
  * Switch by changing the import path. Same function names, same option
- * names, same `otel_logs` rows (`event.name`, `custom.*`, `exception.*`,
- * `strada.user.identify`), so every Strada query works unchanged. What the
- * light build does not support is not exported or not accepted, so a switch
- * that relies on it fails at compile time instead of silently dropping data.
- * `index.test.ts` type-checks this file against the full SDK to keep both in
- * sync.
+ * names, same rows in `otel_logs` / `otel_traces` (`event.name`, `custom.*`,
+ * `exception.*`, `strada.user.identify`, `pageview`), so every Strada query
+ * works unchanged. What the light build does not support is not exported or
+ * not accepted, so a switch that relies on it fails at compile time instead
+ * of silently dropping data. `index.test.ts` type-checks every export against
+ * the full SDK to keep both in sync.
  *
- * It builds OTLP JSON log records by hand and POSTs them with `fetch` to
- * `/v1/logs`. `initStrada()` installs nothing global: no OTel providers, no
- * process handlers, no resource detectors (no hostname, OS username, or
- * command args). Only what you pass is sent. The flush timer is unref'd, so
- * call `flush()` before a short-lived process exits.
+ * Explicit only: nothing is captured unless you call it. `initStrada()`
+ * installs nothing global: no OTel providers, no process or window error
+ * handlers, no fetch patching, no resource detectors (no hostname, OS
+ * username, or command args). Records are built as OTLP JSON by hand and
+ * POSTed with `fetch` to `/v1/logs` and `/v1/traces`. The flush timer is
+ * unref'd, so call `flush()` before a short-lived process exits.
+ *
+ * Span parenting across `await` uses AsyncLocalStorage when the runtime
+ * exposes `process.getBuiltinModule` (Node 20.16+, Bun, Workers with
+ * nodejs_compat). Elsewhere (browsers) only synchronous nesting works, the
+ * same limitation as the full browser SDK.
  *
  * Every function follows "telemetry never throws": failures are returned as
- * values and logged once with console.warn.
+ * values and logged once with console.warn. `startSpan()` rethrows the
+ * callback's own error, like the full SDK.
  */
+export type AttributeValue = string | number | boolean;
+export type Attributes = Record<string, AttributeValue>;
 export interface StradaOptions {
     /** Strada project identifier. Blank disables sending. */
     projectId: string;
@@ -39,10 +48,20 @@ export interface StradaOptions {
     releaseBranch?: string;
     /** deployment.id resource attribute. Defaults to releaseCommit. */
     deploymentId?: string;
-    /** Current user id, sent as user.id on every event and error. */
+    /** Drop errors whose message matches any of these patterns */
+    ignoreErrors?: Array<string | RegExp>;
+    /** Drop errors whose stack trace matches any of these patterns */
+    denyUrls?: Array<string | RegExp>;
+    /** Return null to drop an error before it is sent */
+    beforeSend?: (error: Error) => Error | null;
+    /** Current user id, sent as user.id on every event, log, error, and span. */
     userId?: string | (() => string | undefined);
-    /** Same shape as the full SDK. Only log batching applies here. */
+    /** Same shape as the full SDK. Only batching delay and size apply here. */
     telemetry?: {
+        traces?: {
+            scheduledDelayMillis?: number;
+            maxExportBatchSize?: number;
+        };
         logs?: {
             scheduledDelayMillis?: number;
             maxExportBatchSize?: number;
@@ -79,20 +98,83 @@ export interface CaptureExceptionOptions {
     /** Custom fingerprint override for issue grouping. */
     fingerprint?: string[];
 }
-type AttributeValue = string | number | boolean;
+export interface TrackPageviewOptions {
+    /** Page pathname, e.g. "/pricing". Required. */
+    path: string;
+    /** Full page URL, e.g. "https://acme.com/pricing?plan=pro". */
+    url?: string;
+    /** Query string, e.g. "?plan=pro". Derived from url if not set. */
+    query?: string;
+    /** Referrer URL or domain. */
+    referrer?: string;
+    /** Session ID. Falls back to an ephemeral server id. */
+    sessionId?: string;
+    /** User ID. Falls back to the userId init option. */
+    userId?: string;
+    /** Extra span attributes to set on the pageview span. */
+    attributes?: Record<string, string>;
+}
+export interface StartSpanOptions {
+    name: string;
+    attributes?: Attributes;
+}
+/** Same values as OTel SpanStatusCode. */
+export declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+/** Subset of the OTel Span interface, so full SDK spans fit wherever a light span is expected. */
+export interface Span {
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+        traceFlags: number;
+    };
+    setAttribute(key: string, value: AttributeValue): this;
+    setAttributes(attributes: Attributes): this;
+    addEvent(name: string, attributes?: Attributes): this;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): this;
+    updateName(name: string): this;
+    recordException(exception: Error | string): void;
+    isRecording(): boolean;
+    end(): void;
+}
+export type DisposableSpan = Span & Disposable;
+type LogMethod = (...args: unknown[]) => void;
+/** Console-style logger. The full SDK logger also has OTel `emit()`, light does not. */
+export interface StradaLogger {
+    trace: LogMethod;
+    debug: LogMethod;
+    info: LogMethod;
+    warn: LogMethod;
+    error: LogMethod;
+    fatal: LogMethod;
+}
 export declare function initStrada(options: StradaOptions): Error | undefined;
 /** Product analytics event. Properties are stored as `custom.*` attributes. */
-export declare function track(name: string, properties?: Record<string, AttributeValue>): Error | undefined;
+export declare function track(name: string, properties?: Attributes): Error | undefined;
 /** Full profile snapshot for `otel_users`. Call from trusted code with every field you want to keep. */
 export declare function identifyUser(user: StradaUserIdentity): Error | undefined;
 /** Tags merged into every captureException() call. */
 export declare function setTags(next: Record<string, string>): void;
+/** Report an error as an issue. Applies KnownError, ignoreErrors, denyUrls, and beforeSend. */
+export declare function captureException(error: unknown, opts?: CaptureExceptionOptions): Error | undefined;
+/** Console-style logger that sends to `otel_logs`. Not exception capture: use captureException() for issues. */
+export declare function getLogger(name?: string): StradaLogger;
+/** Create a detached span. Call `span.end()` or use `using`. It does not parent later spans. */
+export declare function startInactiveSpan(options: StartSpanOptions): DisposableSpan;
 /**
- * Report a handled error as an issue. No ignoreErrors, denyUrls, or
- * beforeSend in the light build; KnownError instances are skipped like in
- * the full SDK.
+ * Run `callback` inside an active span that auto-ends. Spans, logs, events,
+ * and errors created inside are parented to it. A thrown error is recorded on
+ * the span and rethrown.
  */
-export declare function captureException(error: unknown, opts?: CaptureExceptionOptions): Error | undefined;
+export declare function startSpan<T>(options: StartSpanOptions, callback: (span: Span) => T): T;
+/** Server-side pageview span. Feeds the same analytics views as browser pageviews. */
+export declare function trackPageview(opts: TrackPageviewOptions): Error | undefined;
 export declare function flush(): Promise<Error | undefined>;
 export declare function shutdown(): Promise<Error | undefined>;
 export {};

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}