@safaricom-mxl/effect-sdk 0.0.22 → 0.0.24

package/README.md

@@ -13,12 +13,12 @@ pnpm add @safaricom-mxl/effect-sdk effect @effect/opentelemetry
 Use `@safaricom-mxl/effect-sdk/server` (or the package root in Node / SSR, which resolves to the server build):
 
 ```typescript
-import { Mxl } from "@safaricom-mxl/effect-sdk/server";
-import { Effect } from "effect";
+import { Mxl } from '@safaricom-mxl/effect-sdk/server';
+import { Effect } from 'effect';
 
-const ObservabilityLive = Mxl.layer({ serviceName: "mxl-basket" });
+const ObservabilityLive = Mxl.layer({ serviceName: 'mxl-basket' });
 
-const program = Effect.log("Hello!").pipe(Effect.withSpan("hello"));
+const program = Effect.log('Hello!').pipe(Effect.withSpan('hello'));
 
 Effect.runPromise(program.pipe(Effect.provide(ObservabilityLive)));
 ```
@@ -28,35 +28,56 @@ Effect.runPromise(program.pipe(Effect.provide(ObservabilityLive)));
 Server `MxlEvents.track` buffers product events and flushes NDJSON to Basket `POST /events` (or `POST /v1/events` when `eventsPath` is set). Send `mxl-client-id`. Send `mxl-api-key` when configured.
 
 ```typescript
-import { MxlEvents, MxlFlush } from "@safaricom-mxl/effect-sdk/server";
+import { MxlEvents, MxlFlush } from '@safaricom-mxl/effect-sdk/server';
 
 const telemetry = MxlFlush.make({
   clientId: process.env.MXL_CLIENT_ID,
   ingestUrl: process.env.MXL_BASKET_URL,
-  serviceName: "billing",
+  serviceName: 'billing',
 });
 
-telemetry.track("plan_started", { userId: "user_1" });
+telemetry.track('plan_started', { userId: 'user_1' });
 await telemetry.flush();
 ```
 
 Browser `track` dual-writes a product line to `/events` and a session row to `/sessionEvents` with `type: "custom"`. `identify` / increment / decrement go through `POST /track`. `@safaricom-mxl/effect-sdk/client` is an alias of `./browser`.
 
 ```typescript
-import { identify, MxlFlush, track } from "@safaricom-mxl/effect-sdk/browser";
+import { identify, MxlFlush, track } from '@safaricom-mxl/effect-sdk/browser';
 
 const telemetry = MxlFlush.make({
-  clientId: "client_1",
-  ingestUrl: "https://basket.example",
-  serviceName: "web",
+  clientId: 'client_1',
+  ingestUrl: 'https://basket.example',
+  serviceName: 'web',
 });
 
-identify({ id: "user_1", email: "a@b.com" });
-track("checkout_completed", { plan: "pro" });
+identify({ id: 'user_1', email: 'a@b.com' });
+track('checkout_completed', { plan: 'pro' });
 ```
 
 Cloudflare workers use `./cloudflare`. `make()` is module-scope; `flush(env)` resolves `MXL_CLIENT_ID` / `MXL_API_KEY` lazily and is safe inside `waitUntil`. Replay posts `/sessionReplays/meta` and `/sessionReplays/blob`, and stands down when `@safaricom-mxl/web-sdk` already owns the page.
 
+## Foldkit
+
+`@safaricom-mxl/effect-sdk/foldkit` instruments a Foldkit app: Command spans parented under a navigation, scrubbed command args, crash reports, and slow `update`/`view`/`patch` phases. It sits on the browser flushable tracer.
+
+```typescript
+import { MxlFoldkit } from '@safaricom-mxl/effect-sdk/foldkit';
+
+const telemetry = MxlFoldkit.make({
+  endpoint: 'http://127.0.0.1:4318',
+  serviceName: 'acme-web',
+});
+
+Runtime.run(
+  Runtime.makeApplication(
+    telemetry.instrument({ Model, init, update, view, resources, routing }),
+  ),
+);
+```
+
+`MapleFoldkit` is a type and namespace alias of `MxlFoldkit`.
+
 Do not import `@safaricom-mxl/effect-sdk/server` from browser code. The package root (`"."`) resolves to the server build under Node/default conditions.
 
 ### Environment variables

package/dist/browser/index.d.ts

@@ -1,90 +1,7 @@
-import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { Effect, Layer } from "effect";
-//#region src/shared/product-event.d.ts
-interface TrackProps {
-  readonly [key: string]: unknown;
-}
-//#endregion
-//#region src/shared/identity.d.ts
-interface MapleIdentity {
-  readonly email?: string | undefined;
-  readonly groupId?: string | undefined;
-  readonly groupName?: string | undefined;
-  readonly id: string;
-  readonly traits?: Record<string, unknown> | undefined;
-}
-type IdentifyInput = string | MapleIdentity | null | undefined;
-//#endregion
-//#region src/browser/analytics.d.ts
-interface PrivacyOptions {
-  readonly requireConsent?: boolean | undefined;
-}
-export declare const setConsent: (granted: boolean) => void;
-export declare const identify: (input?: IdentifyInput) => void;
-export declare const clearIdentity: () => void;
-export declare const track: (name: string, props?: TrackProps) => void;
-export declare const increment: (property: string, value?: number) => void;
-export declare const decrement: (property: string, value?: number) => void;
-//#endregion
-//#region src/browser/replay.d.ts
-interface ClientReplayConfig {
-  readonly enabled?: boolean | undefined;
-  readonly maskAllInputs?: boolean | undefined;
-  readonly maskAllText?: boolean | undefined;
-  readonly sampleRate?: number | undefined;
-}
-declare namespace layer_d_exports {
-  export { MxlBrowserConfig, clearIdentity$1 as clearIdentity, identify$1 as identify, layer, stampUserIdOnSpan, track$1 as track };
-}
-interface MxlBrowserConfig {
-  readonly apiKey?: string | undefined;
-  readonly attributes?: Record<string, string> | undefined;
-  readonly clientId?: string | undefined;
-  readonly disabled?: boolean | undefined;
-  readonly endpoint?: string | undefined;
-  readonly environment?: string | undefined;
-  readonly headers?: Record<string, string> | undefined;
-  readonly ingestUrl?: string | undefined;
-  readonly privacy?: PrivacyOptions | undefined;
-  readonly replay?: ClientReplayConfig | undefined;
-  readonly serviceName?: string | undefined;
-  readonly serviceVersion?: string | undefined;
-}
-declare const stampUserIdOnSpan: (span: {
-  setAttribute: (key: string, value: string) => unknown;
-}) => void;
-/**
- * Browser Effect observability layer backed by OpenTelemetry WebSdk.
- *
- * Returns a no-op layer when `disabled` is true or no OTLP endpoint is configured.
- */
-declare const layer: (config?: MxlBrowserConfig) => Layer.Layer<never, never, never>;
-declare const identify$1: (input?: IdentifyInput) => Effect.Effect<void, never, never>;
-declare const clearIdentity$1: Effect.Effect<void, never, never>;
-declare const track$1: (name: string, props?: TrackProps) => Effect.Effect<void, never, never>;
-declare namespace flushable_d_exports {
-  export { FlushableTelemetry, MxlBrowserFlushableConfig, attachProcessor, make };
-}
-interface MxlBrowserFlushableConfig extends MxlBrowserConfig {
-  readonly autoFlushInterval?: number | false | undefined;
-  readonly captureGlobalErrors?: boolean | undefined;
-  readonly flushOnUnload?: boolean | undefined;
-}
-interface FlushableTelemetry {
-  readonly captureException: (error: unknown, options?: {
-    readonly attributes?: Record<string, string>;
-    readonly name?: string;
-  }) => void;
-  readonly dispose: () => Promise<void>;
-  readonly flush: () => Promise<void>;
-  readonly layer: Layer.Layer<never>;
-}
-declare const attachProcessor: (telemetry: FlushableTelemetry, processor: BatchSpanProcessor) => void;
-declare const make: (config?: MxlBrowserFlushableConfig) => FlushableTelemetry;
-//#endregion
-//#region src/shared/dependency-spans.d.ts
-type DbSystem = "clickhouse" | "postgresql" | "redis";
-type DependencySpanKind = "client" | "producer" | "consumer";
+import { _ as IdentifyInput, a as layer_d_exports, b as MapleSpanOptions, c as replayRecordOptions, d as decrement, f as identify, g as TrackProps, h as track, i as MxlBrowserConfig, l as PrivacyOptions, m as setConsent, n as MxlBrowserFlushableConfig, o as ClientReplayConfig, p as increment, r as flushable_d_exports, s as ReplayRecordOptions, t as FlushableTelemetry, u as clearIdentity, v as MapleIdentity, x as MxlSpanOptions, y as FinishedSpan } from "../flushable-SCVrRJX3.js";
+import { Effect } from "effect";
+type DbSystem = 'clickhouse' | 'postgresql' | 'redis';
+type DependencySpanKind = 'client' | 'producer' | 'consumer';
 interface QueueTraceContextCarrier {
   readonly traceparent?: string | undefined;
   readonly tracestate?: string | undefined;
@@ -105,6 +22,50 @@ export declare function withDependencySpan<A, E, R>(name: string, attributes: Re
 export declare function withDependencySpan<A, E, R>(name: string, options: WithDependencySpanOptions, program: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
 /** Promise-based dependency span for non-Effect code paths. */
 export declare function withPromiseDependencySpan<T>(name: string, attributes: Record<string, string>, operation: () => Promise<T>, kind?: DependencySpanKind): Promise<T>;
-//#endregion
-export { type ClientReplayConfig, type DbSystem, type DependencySpanKind, type FlushableTelemetry, type IdentifyInput, type MapleIdentity, layer_d_exports as Mxl, type MxlBrowserConfig, type MxlBrowserFlushableConfig, flushable_d_exports as MxlFlush, type PrivacyOptions, type QueueTraceContextCarrier, type TrackProps, type WithDependencySpanOptions };
+/**
+ * URL redaction for everything that leaves the page carrying a URL: session
+ * entry/exit URLs, event rows, network events, rrweb meta events and span
+ * attributes.
+ *
+ * Magic links, password resets and OAuth implicit flows put credentials in the
+ * query string or fragment, and a page view is captured on exactly those
+ * pages. Values of credential-shaped parameters are therefore replaced by
+ * default; the host app can add its own `sanitizeUrl` on top.
+ */
+type UrlSanitizer = (url: string) => string;
+/**
+ * Register a host-app sanitizer. Additive, like the consent gates: an SDK
+ * initialized without one must not remove the one another SDK was given.
+ */
+export declare function addUrlSanitizer(sanitizer: UrlSanitizer): void;
+/** Test seam. */
+export declare function resetUrlSanitizersForTests(): void;
+/** Redact credential-shaped query and fragment parameters, keeping the URL's form. */
+export declare function redactUrl(url: string): string;
+/**
+ * The URL as it may leave the page: default redaction, then every registered
+ * host sanitizer. A sanitizer that throws or returns a non-string yields the
+ * default-redacted URL rather than the raw one.
+ */
+export declare function scrubUrl(url: string): string;
+interface BrowserNavigator {
+  readonly userAgent?: string;
+  readonly language?: string;
+  readonly onLine?: boolean;
+}
+interface BrowserDocument {
+  readonly visibilityState?: string;
+}
+export declare const browserNavigator: () => BrowserNavigator | undefined;
+export declare const browserDocument: () => BrowserDocument | undefined;
+/** Resource attributes every browser preset sends: the SDK, the user agent, language and time zone. */
+export declare const browserResourceAttributes: () => {
+  'telemetry.sdk.name': string;
+  'telemetry.sdk.language': string;
+  'telemetry.sdk.version': string;
+  'user_agent.original'?: string | undefined;
+  'browser.language'?: string | undefined;
+  'mxl.browser.timezone'?: string | undefined;
+};
+export { type ClientReplayConfig, type DbSystem, type DependencySpanKind, type FinishedSpan, type FlushableTelemetry, type IdentifyInput, type MapleIdentity, type MapleSpanOptions, layer_d_exports as Mxl, type MxlBrowserConfig, type MxlBrowserFlushableConfig, flushable_d_exports as MxlFlush, type MxlSpanOptions, type PrivacyOptions, type QueueTraceContextCarrier, type ReplayRecordOptions, type TrackProps, type UrlSanitizer, type WithDependencySpanOptions, clearIdentity, decrement, identify, increment, replayRecordOptions, setConsent, track };
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/shared/product-event.ts","../../src/shared/identity.ts","../../src/browser/analytics.ts","../../src/browser/replay.ts","../../src/browser/layer.ts","../../src/browser/flushable.ts","../../src/shared/dependency-spans.ts"],"mappings":";;;UAoBiB;YACL;;;;UCrBK;WACN;WACA;WACA;WACA;WACA,SAAS;;KAGR,yBAAyB;;;UCMpB;WACN;;qBA4HE,aAAU;qBAOV,WAAQ,QAAY;qBA+BpB;qBAiDA,QAAK,cAAgB,QAAU;qBAiC/B,YAAS,kBAAoB;qBAI7B,YAAS,kBAAoB;;;UCpQzB;WACN;WACA;WACA;WACA;;;;;UCgBM;WACN;WACA,aAAa;WACb;WACA;WACA;WACA;WACA,UAAU;WACV;WACA,UAAU;WACV,SAAS;WACT;WACA;;cAGE,oBAAiB;EAC5B,eAAe,aAAa;;;;;;;cA+CjB,QAAK,SAAY,qBAAgB,MAAA;cAmDjC,aAAQ,QAAY,kBAAa,OAAA;cAGjC,iBAAa,OAAA;cAEb,UAAK,cAAgB,QAAU,eAAU,OAAA;;;;UCrIrC,kCAAkC;WACxC;WACA;WACA;;UAGM;WACN,mBACP,gBACA;aAAqB,aAAa;aAAiC;;WAE5D,eAAe;WACf,aAAa;WACb,OAAO,MAAM;;cAMX,kBAAe,WACf,oBAAkB,WAClB;cAKA,OAAI,SACP,8BACP;;;KC5BS;KAEA;UAIK;WACN;WACA;WACA;;wBAGK,uBACd,UAAU,UACV,qBACC;wBASa,4BACd,yBACA,uBACC;wBAQa,4BACd,0BACC;wBAOa,4BACd,eACA,uBACC;wBAQa,qBACd,oBACA,oBACC;wBAUa,qBAAqB;wBASrB,8BACd,mBAAmB;UAiCJ;WACN,aAAa;WACb,OAAO;;wBAGF,mBAAmB,GAAG,GAAG,GACvC,cACA,YAAY,wBACZ,SAAS,OAAO,OAAO,GAAG,GAAG,KAC5B,OAAO,OAAO,GAAG,GAAG;wBACP,mBAAmB,GAAG,GAAG,GACvC,cACA,SAAS,2BACT,SAAS,OAAO,OAAO,GAAG,GAAG,KAC5B,OAAO,OAAO,GAAG,GAAG;;wBA2BD,0BAA0B,GAC9C,cACA,YAAY,wBACZ,iBAAiB,QAAQ,IACzB,OAAM,qBACL,QAAQ"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/shared/dependency-spans.ts","../../src/shared/url-privacy.ts","../../src/browser/browser-globals.ts"],"mappings":";;KASY;KAEA;UAIK;WACN;WACA;WACA;;wBAGK,uBACd,UAAU,UACV,qBACC;wBASa,4BACd,yBACA,uBACC;wBAQa,4BACd,0BACC;wBAOa,4BACd,eACA,uBACC;wBAQa,qBACd,oBACA,oBACC;wBAUa,qBAAqB;wBASrB,8BACd,mBAAmB;UAiCJ;WACN,aAAa;WACb,OAAO;;wBAGF,mBAAmB,GAAG,GAAG,GACvC,cACA,YAAY,wBACZ,SAAS,OAAO,OAAO,GAAG,GAAG,KAC5B,OAAO,OAAO,GAAG,GAAG;wBACP,mBAAmB,GAAG,GAAG,GACvC,cACA,SAAS,2BACT,SAAS,OAAO,OAAO,GAAG,GAAG,KAC5B,OAAO,OAAO,GAAG,GAAG;;wBA2BD,0BAA0B,GAC9C,cACA,YAAY,wBACZ,iBAAiB,QAAQ,IACzB,OAAM,qBACL,QAAQ;;;;;;;;;;;KC3JC,gBAAgB;;;;;wBAuBZ,gBAAgB,WAAW;;wBAK3B;;wBAqCA,UAAU;;;;;;wBA6BV,SAAS;UClGf;WACC;WACA;WACA;;UAGD;WACC;;qBAGE,wBAAuB;qBAGvB,uBAAsB;;qBAItB"}