@safaricom-mxl/effect-sdk 0.0.15 → 0.0.17

package/README.md

@@ -5,7 +5,7 @@ OpenTelemetry traces, logs, and metrics for [Effect](https://effect.website) app
 ## Install
 
 ```bash
-pnpm add @safaricom-mxl/effect-sdk effect
+pnpm add @safaricom-mxl/effect-sdk effect @effect/opentelemetry
 ```
 
 ## Server
@@ -23,16 +23,40 @@ const program = Effect.log("Hello!").pipe(Effect.withSpan("hello"));
 Effect.runPromise(program.pipe(Effect.provide(ObservabilityLive)));
 ```
 
-## Browser
+## Product events
 
-Use `@safaricom-mxl/effect-sdk/browser` explicitly in browser bundles (Vite client, etc.):
+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 { Mxl } from "@safaricom-mxl/effect-sdk/browser";
+import { MxlEvents, MxlFlush } from "@safaricom-mxl/effect-sdk/server";
 
-const ObservabilityLive = Mxl.layer({ serviceName: "mxl-console" });
+const telemetry = MxlFlush.make({
+  clientId: process.env.MXL_CLIENT_ID,
+  ingestUrl: process.env.MXL_BASKET_URL,
+  serviceName: "billing",
+});
+
+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";
+
+const telemetry = MxlFlush.make({
+  clientId: "client_1",
+  ingestUrl: "https://basket.example",
+  serviceName: "web",
+});
+
+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.
+
 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
@@ -45,9 +69,12 @@ Do not import `@safaricom-mxl/effect-sdk/server` from browser code. The package
 | `OTEL_SERVICE_NAME`           | Service name                               |
 | `OTEL_RESOURCE_ATTRIBUTES`    | Extra resource attributes                  |
 | `OTEL_SDK_DISABLED`           | When `true`, installs a no-op layer        |
+| `MXL_BASKET_URL`              | Basket origin for product events           |
+| `MXL_CLIENT_ID`               | Required for product-event ingest          |
+| `MXL_API_KEY`                 | Sent as `mxl-api-key` when configured      |
 
 Default endpoint: `http://127.0.0.1:4318` (local `mxl-otel-collector`).
 
 ## License
 
-MIT
+Apache-2.0

package/dist/browser/index.d.ts

@@ -1,22 +1,86 @@
+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, layer };
+  export { MxlBrowserConfig, clearIdentity$1 as clearIdentity, identify$1 as identify, layer, stampUserIdOnSpan, track$1 as track };
 }
 interface MxlBrowserConfig {
-  readonly serviceName?: string | undefined;
-  readonly serviceVersion?: string | undefined;
-  readonly environment?: string | undefined;
-  readonly endpoint?: string | undefined;
-  readonly headers?: Record<string, string> | undefined;
+  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";
@@ -42,5 +106,5 @@ export declare function withDependencySpan<A, E, R>(name: string, options: WithD
 /** 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 DbSystem, type DependencySpanKind, layer_d_exports as Mxl, type MxlBrowserConfig, type QueueTraceContextCarrier, type WithDependencySpanOptions };
+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 };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/browser/layer.ts","../../src/shared/dependency-spans.ts"],"mappings":";;;;UASiB;WACN;WACA;WACA;WACA;WACA,UAAU;WACV,aAAa;WACb;;;;;;;cAkBE,QAAK,SAAY,qBAAgB,MAAA;;;KCzBlC;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/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"}