@chaja/sdk-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @chaja/sdk-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The runtime-independent client behind [`@chaja/sdk-browser`](https://www.npmjs.com/package/@chaja/sdk-browser) and
+[`@chaja/sdk-node`](https://www.npmjs.com/package/@chaja/sdk-node): stack parsing, cause chains, scrubbing, sampling,
+deduplication and a batching transport that honours `Retry-After`.
+
+Install one of those instead unless you are adding support for another JavaScript runtime with `createClient(options, platform)`.
+See [docs/sdk.md](https://github.com/emiliodominguez/chaja/blob/main/docs/sdk.md) and
+[docs/protocol.md](https://github.com/emiliodominguez/chaja/blob/main/docs/protocol.md).

package/dist/index.d.mts

@@ -0,0 +1,382 @@
+//#region ../protocol/src/wire.d.ts
+/**
+ * Plain wire types for SDKs. They carry no runtime code and no zod types, so published SDK declarations stay self-contained.
+ * `wire.check.ts` proves they match the server's schemas in both directions.
+ */
+type Level = "fatal" | "error" | "warning" | "info" | "debug";
+type AttributeScalar = string | number | boolean;
+type AttributeValue = AttributeScalar | AttributeScalar[];
+type Attributes = Record<string, AttributeValue>;
+interface Resource {
+  "service.name": string;
+  "service.version"?: string;
+  "deployment.environment"?: string;
+  attributes?: Attributes;
+}
+interface Frame {
+  function?: string;
+  module?: string;
+  filename?: string;
+  lineno?: number;
+  colno?: number;
+  inApp?: boolean;
+  contextLine?: string;
+  preContext?: string[];
+  postContext?: string[];
+}
+interface Mechanism {
+  type: string;
+  handled: boolean;
+}
+interface Exception {
+  type: string;
+  value: string;
+  frames: Frame[];
+  mechanism?: Mechanism;
+}
+interface Breadcrumb {
+  timestamp: number;
+  category: string;
+  level?: Level;
+  message?: string;
+  data?: Attributes;
+}
+interface User {
+  id?: string;
+  email?: string;
+  username?: string;
+  ipAddress?: string;
+}
+interface TraceContext {
+  traceId: string;
+  spanId: string;
+}
+interface RequestInfo {
+  url?: string;
+  method?: string;
+  headers?: Record<string, string>;
+}
+interface SdkInfo {
+  name: string;
+  version: string;
+}
+interface ErrorItemInput {
+  type: "error";
+  eventId: string;
+  timestamp: number;
+  level?: Level;
+  platform: string;
+  exceptions?: Exception[];
+  message?: string;
+  fingerprint?: string[];
+  release?: string;
+  environment?: string;
+  tags?: Record<string, string>;
+  attributes?: Attributes;
+  user?: User;
+  breadcrumbs?: Breadcrumb[];
+  trace?: TraceContext;
+  request?: RequestInfo;
+}
+interface EventItemInput {
+  type: "event";
+  eventId: string;
+  timestamp: number;
+  name: string;
+  distinctId: string;
+  anonymousId?: string;
+  sessionId?: string;
+  properties?: Attributes;
+  set?: Attributes;
+  setOnce?: Attributes;
+}
+type ItemInput = ErrorItemInput | EventItemInput;
+interface EnvelopeInput {
+  version: 1;
+  sentAt: number;
+  sdk: SdkInfo;
+  resource: Resource;
+  items: ItemInput[];
+}
+//#endregion
+//#region src/transport.d.ts
+/**
+ * What a platform transport reports back: the HTTP status (0 for network failures) and any `Retry-After` in seconds.
+ */
+interface TransportResult {
+  status: number;
+  retryAfterSeconds?: number;
+}
+interface Transport {
+  send: (body: string) => Promise<TransportResult>;
+  /**
+   * Best-effort send while the page or process is going away. Return false when unsupported.
+   */
+  sendFinal?: (body: string) => boolean;
+}
+interface QueueOptions {
+  transport: Transport;
+  envelope: (items: ItemInput[]) => EnvelopeInput;
+  maxQueue: number;
+  maxBatch: number;
+  flushDelayMs: number;
+  maxAttempts: number;
+  now: () => number;
+  schedule: (callback: () => void, delayMs: number) => unknown;
+  cancel: (handle: unknown) => void;
+  /**
+   * Called with envelopes that exhausted their retries on network failures (Node persists them to disk).
+   */
+  onUndeliverable?: (body: string) => void;
+  debug?: (event: string, fields: Record<string, unknown>) => void;
+}
+interface Queue {
+  /**
+   * Add an item; the oldest item is dropped when the queue is full.
+   */
+  push(item: ItemInput): void;
+  /**
+   * Send everything that can be sent now.
+   */
+  flush(): Promise<void>;
+  /**
+   * Wait for pending items to be sent, up to a timeout. Resolves to whether the queue drained.
+   */
+  drain(timeoutMs: number): Promise<boolean>;
+  /**
+   * Hand queued items to the transport's final send (page unload).
+   */
+  sendFinal(): boolean;
+  size(): number;
+}
+/**
+ * Batches items into envelopes, sends them and honours server back-pressure: 429/503 pause sending until `Retry-After`, network failures
+ * retry with exponential backoff, and permanent rejections (4xx) drop the batch.
+ *
+ * @param options - Transport, limits and clock.
+ * @returns Queue controls.
+ */
+export declare function createQueue(options: QueueOptions): Queue;
+//#endregion
+//#region src/client.d.ts
+interface ClientOptions {
+  /**
+   * Chajá server base URL, such as `https://chaja.example.com`.
+   */
+  endpoint: string;
+  /**
+   * Project ingest key.
+   */
+  key: string;
+  /**
+   * Logical service name (`service.name`).
+   */
+  service: string;
+  release?: string;
+  environment?: string;
+  /**
+   * Share of events to send, from 0 to 1. Default 1.
+   */
+  sampleRate?: number;
+  maxBreadcrumbs?: number;
+  /**
+   * Inspect or change an event before it is queued; return null to drop it.
+   */
+  beforeSend?: (item: ErrorItemInput) => ErrorItemInput | null;
+  /**
+   * Keys whose values are redacted in tags, attributes, headers, breadcrumb data and URL queries.
+   */
+  sensitiveKeys?: RegExp;
+  /**
+   * Identical errors within this window are sent once. Default 1000 ms.
+   */
+  dedupeWindowMs?: number;
+  enabled?: boolean;
+  resourceAttributes?: Attributes;
+  /**
+   * Send product analytics events (`capture`, `identify`, automatic page views). Default true.
+   */
+  analytics?: boolean;
+}
+/**
+ * Where a platform keeps who the current person is between page loads.
+ */
+interface IdentityState {
+  distinctId: string;
+  /**
+   * True once `identify` named the person; until then `distinctId` is an anonymous id.
+   */
+  identified: boolean;
+}
+interface CaptureOptions {
+  /**
+   * Send as this person instead of the current one (servers capturing for many users).
+   */
+  distinctId?: string;
+  /**
+   * Person properties to set.
+   */
+  set?: Attributes;
+  /**
+   * Person properties to set only when the person does not have them yet.
+   */
+  setOnce?: Attributes;
+}
+interface Platform {
+  sdk: SdkInfo;
+  platform: string;
+  transport: Transport;
+  eventId: () => string;
+  now: () => number;
+  random: () => number;
+  schedule: (callback: () => void, delayMs: number) => unknown;
+  cancel: (handle: unknown) => void;
+  /**
+   * Add platform context (request URL, user agent, source lines) to an item.
+   */
+  enrich?: (item: ErrorItemInput) => ErrorItemInput;
+  onUndeliverable?: (body: string) => void;
+  debug?: (event: string, fields: Record<string, unknown>) => void;
+  /**
+   * Load and save the current person (browsers persist it; servers keep it in memory).
+   */
+  identity?: {
+    load(): IdentityState | undefined;
+    save(state: IdentityState | undefined): void;
+  };
+  /**
+   * The current session id, renewed by the platform after inactivity.
+   */
+  session?: {
+    current(): string | undefined;
+    reset(): void;
+  };
+  /**
+   * Properties added to every analytics event, such as the page URL.
+   */
+  eventProperties?: () => Attributes;
+}
+interface CaptureContext {
+  level?: Level;
+  tags?: Record<string, string>;
+  attributes?: Attributes;
+  user?: User;
+  fingerprint?: string[];
+  mechanism?: Mechanism;
+  request?: RequestInfo;
+  trace?: TraceContext;
+}
+interface BreadcrumbInput {
+  category: string;
+  message?: string;
+  level?: Level;
+  data?: Attributes;
+  timestamp?: number;
+}
+interface Client {
+  readonly options: Readonly<ClientOptions>;
+  captureException(error: unknown, context?: CaptureContext): string | undefined;
+  captureMessage(message: string, level?: Level, context?: CaptureContext): string | undefined;
+  addBreadcrumb(breadcrumb: BreadcrumbInput): void;
+  setUser(user: User | null): void;
+  setTag(key: string, value: string): void;
+  setTags(tags: Record<string, string>): void;
+  setAttributes(attributes: Attributes): void;
+  /**
+   * Supply the active trace (for example from OpenTelemetry) so errors link to traces.
+   */
+  setTraceProvider(provider: (() => TraceContext | undefined) | undefined): void;
+  /**
+   * Record a product analytics event, such as `signed_up`, for the current person (or `options.distinctId`).
+   */
+  capture(name: string, properties?: Attributes, options?: CaptureOptions): string | undefined;
+  /**
+   * Name the current person with your app's user id. Events captured before, under an anonymous id, become theirs. Errors
+   * from now on carry the id as `user.id`, so a person's errors show next to their events.
+   */
+  identify(distinctId: string, set?: Attributes, setOnce?: Attributes): void;
+  /**
+   * Forget the current person and session (sign out): later events start a new anonymous person.
+   */
+  reset(): void;
+  /**
+   * The current person's id: the identified id, or the anonymous one.
+   */
+  getDistinctId(): string;
+  /**
+   * The current session id (renewed by the platform after inactivity), if the platform keeps sessions.
+   */
+  getSessionId(): string | undefined;
+  /**
+   * Send queued events, waiting at most `timeoutMs`. Resolves to whether everything was sent.
+   */
+  flush(timeoutMs?: number): Promise<boolean>;
+  /**
+   * Hand queued events to the transport's last-chance send (page hide).
+   */
+  sendFinal(): boolean;
+}
+/**
+ * Create an SDK client. Platform packages supply the transport, ids, clocks and enrichment.
+ *
+ * @param options - User options.
+ * @param platform - Platform hooks.
+ * @returns The client.
+ */
+export declare function createClient(options: ClientOptions, platform: Platform): Client;
+//#endregion
+//#region src/scrub.d.ts
+export declare const DEFAULT_SENSITIVE_KEYS: RegExp;
+export declare const REDACTED = "[redacted]";
+/**
+ * Replace values whose key looks sensitive. Tags, attributes, headers and breadcrumb data are all flat records.
+ *
+ * @param record - Flat record.
+ * @param pattern - Keys to redact.
+ * @returns A scrubbed copy.
+ */
+export declare function scrubRecord<V>(record: Record<string, V>, pattern?: RegExp): Record<string, V | string>;
+/**
+ * Redact query values in a URL whose parameter names look sensitive.
+ *
+ * @param url - Absolute or relative URL.
+ * @param pattern - Parameter names to redact.
+ * @returns URL with sensitive values redacted.
+ */
+export declare function scrubUrl(url: string, pattern?: RegExp): string;
+//#endregion
+//#region src/stack.d.ts
+/**
+ * Parse a JavaScript `error.stack` string from V8 (Chrome, Edge, Node, Deno, Bun), SpiderMonkey (Firefox) or JavaScriptCore (Safari).
+ *
+ * @param stack - Stack string.
+ * @returns Frames, oldest call first.
+ */
+export declare function parseStack(stack: string | undefined): Frame[];
+/**
+ * Convert a thrown value and its `cause` chain into protocol exceptions, outermost first.
+ *
+ * @param error - Anything that was thrown or rejected.
+ * @param mechanism - How it was captured.
+ * @returns Exceptions.
+ */
+export declare function exceptionsFrom(error: unknown, mechanism: Mechanism): Exception[];
+//#endregion
+//#region src/index.d.ts
+export declare const SDK_VERSION = "0.1.0";
+/**
+ * Parse a `Retry-After` header given in seconds or as an HTTP date.
+ *
+ * @param value - Header value.
+ * @param now - Current time in milliseconds.
+ * @returns Seconds to wait, if the header is usable.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/**
+ * A 32-character lowercase hex event id.
+ *
+ * @returns Event id.
+ */
+export declare function randomEventId(): string;
+//#endregion
+export type { BreadcrumbInput, CaptureContext, CaptureOptions, Client, ClientOptions, IdentityState, Platform, Queue, QueueOptions, Transport, TransportResult };

package/dist/index.mjs

@@ -0,0 +1,586 @@
+//#region src/scrub.ts
+const DEFAULT_SENSITIVE_KEYS = /pass(?:word|wd)?|secret|token|api[-_]?key|auth|cookie|session|credit|card|cvv|ssn|private/iu;
+const REDACTED = "[redacted]";
+/**
+* Replace values whose key looks sensitive. Tags, attributes, headers and breadcrumb data are all flat records.
+*
+* @param record - Flat record.
+* @param pattern - Keys to redact.
+* @returns A scrubbed copy.
+*/
+function scrubRecord(record, pattern = DEFAULT_SENSITIVE_KEYS) {
+	const result = {};
+	for (const [key, value] of Object.entries(record)) result[key] = pattern.test(key) ? REDACTED : value;
+	return result;
+}
+/**
+* Redact query values in a URL whose parameter names look sensitive.
+*
+* @param url - Absolute or relative URL.
+* @param pattern - Parameter names to redact.
+* @returns URL with sensitive values redacted.
+*/
+function scrubUrl(url, pattern = DEFAULT_SENSITIVE_KEYS) {
+	const queryStart = url.indexOf("?");
+	if (queryStart === -1) return url;
+	const hashStart = url.indexOf("#", queryStart);
+	const cleaned = url.slice(queryStart + 1, hashStart === -1 ? void 0 : hashStart).split("&").map(function redact(pair) {
+		const [name = ""] = pair.split("=");
+		let decoded = name;
+		try {
+			decoded = decodeURIComponent(name.replaceAll("+", " "));
+		} catch {
+			decoded = name;
+		}
+		return pattern.test(decoded) ? `${name}=${encodeURIComponent(REDACTED)}` : pair;
+	}).join("&");
+	return `${url.slice(0, queryStart)}?${cleaned}${hashStart === -1 ? "" : url.slice(hashStart)}`;
+}
+//#endregion
+//#region src/stack.ts
+const MAX_FRAMES = 100;
+const MAX_CAUSES = 10;
+const MAX_VALUE = 8192;
+const V8_WITH_POSITION = /^\s*at (?:async )?(.+?) \((.+):(\d+):(\d+)\)\s*$/u;
+const V8_ANONYMOUS = /^\s*at (?:async )?(.+):(\d+):(\d+)\s*$/u;
+const V8_NO_POSITION = /^\s*at (?:async )?(.+?) \((.+)\)\s*$/u;
+const GECKO = /^\s*(.*?)@(.+):(\d+):(\d+)\s*$/u;
+/**
+* Parse a JavaScript `error.stack` string from V8 (Chrome, Edge, Node, Deno, Bun), SpiderMonkey (Firefox) or JavaScriptCore (Safari).
+*
+* @param stack - Stack string.
+* @returns Frames, oldest call first.
+*/
+function parseStack(stack) {
+	if (!stack) return [];
+	const frames = [];
+	for (const line of stack.split("\n")) {
+		const positioned = V8_WITH_POSITION.exec(line);
+		if (positioned) {
+			frames.push(frame(positioned[1], positioned[2], positioned[3], positioned[4]));
+			continue;
+		}
+		const anonymous = V8_ANONYMOUS.exec(line);
+		if (anonymous) {
+			frames.push(frame(void 0, anonymous[1], anonymous[2], anonymous[3]));
+			continue;
+		}
+		const native = V8_NO_POSITION.exec(line);
+		if (native) {
+			frames.push(frame(native[1], native[2], void 0, void 0));
+			continue;
+		}
+		const gecko = GECKO.exec(line);
+		if (gecko) frames.push(frame(gecko[1] || void 0, gecko[2], gecko[3], gecko[4]));
+	}
+	return frames.slice(0, MAX_FRAMES).reverse();
+}
+/**
+* Build one frame from regex parts.
+*
+* @param fn - Function name.
+* @param filename - File or URL.
+* @param line - Line number text.
+* @param column - Column number text.
+* @returns Frame.
+*/
+function frame(fn, filename, line, column) {
+	const name = fn?.replace(/^Object\.|^Module\./u, "").trim();
+	return {
+		filename,
+		...name && name !== "<anonymous>" ? { function: name } : {},
+		...line ? { lineno: Number(line) } : {},
+		...column ? { colno: Number(column) } : {}
+	};
+}
+/**
+* Read a property from an unknown thrown value.
+*
+* @param value - Thrown value.
+* @param key - Property name.
+* @returns The property, if the value is an object.
+*/
+function property(value, key) {
+	return typeof value === "object" && value !== null ? Reflect.get(value, key) : void 0;
+}
+/**
+* Describe a non-Error thrown value.
+*
+* @param value - Thrown value.
+* @returns Readable text.
+*/
+function describe(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return Object.prototype.toString.call(value);
+	}
+}
+/**
+* Convert a thrown value and its `cause` chain into protocol exceptions, outermost first.
+*
+* @param error - Anything that was thrown or rejected.
+* @param mechanism - How it was captured.
+* @returns Exceptions.
+*/
+function exceptionsFrom(error, mechanism) {
+	const exceptions = [];
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	while (current !== void 0 && current !== null && exceptions.length < MAX_CAUSES && !seen.has(current)) {
+		seen.add(current);
+		const isError = current instanceof Error || typeof property(current, "message") === "string" && typeof property(current, "name") === "string";
+		const rawName = property(current, "name");
+		const name = isError ? typeof rawName === "string" && rawName ? rawName : "Error" : typeof current === "object" ? "NonError" : "Error";
+		const message = isError ? String(property(current, "message")) : describe(current);
+		const stack = property(current, "stack");
+		exceptions.push({
+			type: name.slice(0, 256),
+			value: message.slice(0, MAX_VALUE),
+			frames: typeof stack === "string" ? parseStack(stack) : [],
+			...exceptions.length === 0 ? { mechanism } : {}
+		});
+		current = property(current, "cause");
+	}
+	return exceptions;
+}
+//#endregion
+//#region src/transport.ts
+const MAX_BACKOFF_MS = 6e4;
+/**
+* Batches items into envelopes, sends them and honours server back-pressure: 429/503 pause sending until `Retry-After`, network failures
+* retry with exponential backoff, and permanent rejections (4xx) drop the batch.
+*
+* @param options - Transport, limits and clock.
+* @returns Queue controls.
+*/
+function createQueue(options) {
+	const pending = [];
+	let pausedUntil = 0;
+	let failures = 0;
+	let timer;
+	let inFlight;
+	/**
+	* Arrange the next flush.
+	*
+	* @param delayMs - Delay before flushing.
+	*/
+	function scheduleFlush(delayMs) {
+		if (timer !== void 0) return;
+		timer = options.schedule(function run() {
+			timer = void 0;
+			flush();
+		}, delayMs);
+	}
+	/**
+	* Send one batch.
+	*
+	* @param batch - Items.
+	*/
+	async function sendBatch(batch) {
+		const body = JSON.stringify(options.envelope(batch));
+		let result;
+		try {
+			result = await options.transport.send(body);
+		} catch {
+			result = { status: 0 };
+		}
+		if (result.status >= 200 && result.status < 300) {
+			failures = 0;
+			return;
+		}
+		if (result.status === 429 || result.status === 503 || result.status === 0 || result.status >= 500) {
+			failures += 1;
+			const backoff = Math.min(MAX_BACKOFF_MS, 1e3 * 2 ** (failures - 1));
+			const wait = result.retryAfterSeconds === void 0 ? backoff : result.retryAfterSeconds * 1e3;
+			pausedUntil = options.now() + wait;
+			if (failures >= options.maxAttempts) {
+				options.debug?.("transport.gave_up", {
+					status: result.status,
+					items: batch.length
+				});
+				failures = 0;
+				if (result.status === 0) options.onUndeliverable?.(body);
+				return;
+			}
+			pending.unshift(...batch);
+			pending.splice(options.maxQueue);
+			scheduleFlush(wait);
+			return;
+		}
+		options.debug?.("transport.rejected", {
+			status: result.status,
+			items: batch.length
+		});
+	}
+	/**
+	* Send everything that can be sent now.
+	*
+	* @returns Resolves when the current flush finishes.
+	*/
+	async function flush() {
+		if (inFlight) return inFlight;
+		inFlight = (async function drain() {
+			while (pending.length > 0) {
+				const wait = pausedUntil - options.now();
+				if (wait > 0) {
+					scheduleFlush(wait);
+					return;
+				}
+				const before = pending.length;
+				await sendBatch(pending.splice(0, options.maxBatch));
+				if (pending.length >= before) return;
+			}
+		})().finally(function done() {
+			inFlight = void 0;
+		});
+		return inFlight;
+	}
+	return {
+		/**
+		* Add an item; the oldest item is dropped when the queue is full.
+		*
+		* @param item - Envelope item.
+		*/
+		push(item) {
+			pending.push(item);
+			if (pending.length > options.maxQueue) pending.shift();
+			scheduleFlush(Math.max(options.flushDelayMs, pausedUntil - options.now()));
+		},
+		flush,
+		/**
+		* Wait for pending items to be sent, up to a timeout.
+		*
+		* @param timeoutMs - Maximum wait.
+		* @returns Whether the queue drained in time.
+		*/
+		async drain(timeoutMs) {
+			if (timer !== void 0) {
+				options.cancel(timer);
+				timer = void 0;
+			}
+			const deadline = options.now() + timeoutMs;
+			while (pending.length > 0 && options.now() < deadline && pausedUntil <= options.now()) await flush();
+			await inFlight;
+			return pending.length === 0;
+		},
+		/**
+		* Hand everything to the transport's final send (page unload).
+		*
+		* @returns Whether the transport accepted it.
+		*/
+		sendFinal() {
+			if (pending.length === 0 || !options.transport.sendFinal) return pending.length === 0;
+			const accepted = options.transport.sendFinal(JSON.stringify(options.envelope(pending.slice(0, options.maxBatch))));
+			if (accepted) pending.splice(0, options.maxBatch);
+			return accepted;
+		},
+		size() {
+			return pending.length;
+		}
+	};
+}
+//#endregion
+//#region src/client.ts
+const DEFAULT_MAX_BREADCRUMBS = 50;
+const MAX_TEXT = 8192;
+/**
+* Create an SDK client. Platform packages supply the transport, ids, clocks and enrichment.
+*
+* @param options - User options.
+* @param platform - Platform hooks.
+* @returns The client.
+*/
+function createClient(options, platform) {
+	const pattern = options.sensitiveKeys ?? DEFAULT_SENSITIVE_KEYS;
+	const maxBreadcrumbs = options.maxBreadcrumbs ?? DEFAULT_MAX_BREADCRUMBS;
+	const dedupeWindowMs = options.dedupeWindowMs ?? 1e3;
+	const breadcrumbs = [];
+	const tags = {};
+	const attributes = {};
+	const captured = /* @__PURE__ */ new WeakSet();
+	const recent = /* @__PURE__ */ new Map();
+	let user;
+	let traceProvider;
+	/**
+	* A new anonymous person, saved so the next page load keeps it.
+	*
+	* @returns Identity.
+	*/
+	function anonymous() {
+		const fresh = {
+			distinctId: platform.eventId(),
+			identified: false
+		};
+		platform.identity?.save(fresh);
+		return fresh;
+	}
+	let identity = platform.identity?.load() ?? anonymous();
+	if (identity.identified) user = { id: identity.distinctId };
+	const resource = {
+		"service.name": options.service,
+		...options.release ? { "service.version": options.release } : {},
+		...options.environment ? { "deployment.environment": options.environment } : {},
+		...options.resourceAttributes ? { attributes: options.resourceAttributes } : {}
+	};
+	const queue = createQueue({
+		transport: platform.transport,
+		envelope(items) {
+			return {
+				version: 1,
+				sentAt: platform.now(),
+				sdk: platform.sdk,
+				resource,
+				items
+			};
+		},
+		maxQueue: 100,
+		maxBatch: 20,
+		flushDelayMs: 500,
+		maxAttempts: 6,
+		now: platform.now,
+		schedule: platform.schedule,
+		cancel: platform.cancel,
+		...platform.onUndeliverable ? { onUndeliverable: platform.onUndeliverable } : {},
+		...platform.debug ? { debug: platform.debug } : {}
+	});
+	/**
+	* Whether this event repeats one sent moments ago.
+	*
+	* @param item - Candidate item.
+	* @returns True when it should be skipped.
+	*/
+	function isDuplicate(item) {
+		const exception = item.exceptions?.[0];
+		const top = exception?.frames.at(-1);
+		const key = exception ? `${exception.type}|${exception.value}|${top?.filename ?? ""}:${top?.lineno ?? ""}` : `message|${item.message ?? ""}`;
+		const now = platform.now();
+		const last = recent.get(key);
+		for (const [entry, time] of recent) if (now - time > dedupeWindowMs) recent.delete(entry);
+		recent.set(key, now);
+		return last !== void 0 && now - last <= dedupeWindowMs;
+	}
+	/**
+	* Apply scope, scrubbing, sampling and hooks, then queue.
+	*
+	* @param base - Item content.
+	* @param context - Per-call context.
+	* @returns Event id, or undefined when dropped.
+	*/
+	function capture(base, context = {}) {
+		if (options.enabled === false || platform.random() >= (options.sampleRate ?? 1)) return;
+		const trace = context.trace ?? traceProvider?.();
+		const mergedUser = context.user ?? user;
+		let item = {
+			type: "error",
+			eventId: platform.eventId(),
+			timestamp: platform.now(),
+			platform: platform.platform,
+			...base,
+			...options.release ? { release: options.release } : {},
+			...options.environment ? { environment: options.environment } : {},
+			tags: scrubRecord({
+				...tags,
+				...context.tags
+			}, pattern),
+			attributes: {
+				...scrubRecord({
+					...attributes,
+					...context.attributes
+				}, pattern),
+				...sessionAttributes()
+			},
+			breadcrumbs: [...breadcrumbs],
+			...mergedUser ? { user: mergedUser } : {},
+			...context.fingerprint ? { fingerprint: context.fingerprint } : {},
+			...trace ? { trace } : {},
+			...context.request ? { request: context.request } : {}
+		};
+		if (platform.enrich) item = platform.enrich(item);
+		if (item.request) item = {
+			...item,
+			request: {
+				...item.request,
+				...item.request.url ? { url: scrubUrl(item.request.url, pattern) } : {},
+				...item.request.headers ? { headers: scrubRecord(item.request.headers, pattern) } : {}
+			}
+		};
+		if (isDuplicate(item)) return;
+		const final = options.beforeSend ? options.beforeSend(item) : item;
+		if (!final) return;
+		queue.push(final);
+		return final.eventId;
+	}
+	/**
+	* The session id as an error attribute, so an error links to the session it happened in.
+	*
+	* @returns Attributes.
+	*/
+	function sessionAttributes() {
+		const session = platform.session?.current();
+		return session ? { "session.id": session } : {};
+	}
+	/**
+	* Queue one analytics event.
+	*
+	* @param name - Event name.
+	* @param properties - Event properties.
+	* @param fields - Person, identify and person-property fields.
+	* @returns Event id, if queued.
+	*/
+	function sendEvent(name, properties, fields) {
+		if (options.enabled === false || options.analytics === false) return;
+		const session = platform.session?.current();
+		const item = {
+			type: "event",
+			eventId: platform.eventId(),
+			timestamp: platform.now(),
+			name: name.slice(0, 256),
+			...fields,
+			...session ? { sessionId: session } : {},
+			properties: scrubRecord({
+				...platform.eventProperties?.(),
+				...properties
+			}, pattern)
+		};
+		queue.push(item);
+		return item.eventId;
+	}
+	/**
+	* Remember who the current person is.
+	*
+	* @param next - New identity.
+	*/
+	function remember(next) {
+		identity = next;
+		platform.identity?.save(next);
+	}
+	return {
+		options,
+		captureException(error, context = {}) {
+			if (typeof error === "object" && error !== null) {
+				if (captured.has(error)) return;
+				captured.add(error);
+			}
+			return capture({
+				exceptions: exceptionsFrom(error, context.mechanism ?? {
+					type: "manual",
+					handled: true
+				}),
+				level: context.level ?? "error"
+			}, context);
+		},
+		captureMessage(message, level = "info", context = {}) {
+			return capture({
+				message: message.slice(0, MAX_TEXT),
+				level
+			}, context);
+		},
+		addBreadcrumb(breadcrumb) {
+			breadcrumbs.push({
+				timestamp: breadcrumb.timestamp ?? platform.now(),
+				category: breadcrumb.category.slice(0, 256),
+				level: breadcrumb.level ?? "info",
+				...breadcrumb.message === void 0 ? {} : { message: scrubUrl(breadcrumb.message.slice(0, MAX_TEXT), pattern) },
+				...breadcrumb.data === void 0 ? {} : { data: scrubRecord(breadcrumb.data, pattern) }
+			});
+			if (breadcrumbs.length > maxBreadcrumbs) breadcrumbs.shift();
+		},
+		setUser(next) {
+			user = next ?? void 0;
+		},
+		setTag(key, value) {
+			tags[key] = value;
+		},
+		setTags(next) {
+			Object.assign(tags, next);
+		},
+		setAttributes(next) {
+			Object.assign(attributes, next);
+		},
+		setTraceProvider(provider) {
+			traceProvider = provider;
+		},
+		capture(name, properties = {}, captureOptions = {}) {
+			return sendEvent(name, properties, {
+				distinctId: captureOptions.distinctId ?? identity.distinctId,
+				...captureOptions.set ? { set: captureOptions.set } : {},
+				...captureOptions.setOnce ? { setOnce: captureOptions.setOnce } : {}
+			});
+		},
+		identify(distinctId, set, setOnce) {
+			const id = distinctId.trim().slice(0, 256);
+			if (!id) return;
+			const people = {
+				...set ? { set } : {},
+				...setOnce ? { setOnce } : {}
+			};
+			if (identity.identified && identity.distinctId === id) {
+				if (set || setOnce) sendEvent("$set", {}, {
+					distinctId: id,
+					...people
+				});
+				return;
+			}
+			const previous = identity.identified ? void 0 : identity.distinctId;
+			remember({
+				distinctId: id,
+				identified: true
+			});
+			user = {
+				...user,
+				id
+			};
+			sendEvent("$identify", {}, {
+				distinctId: id,
+				...previous ? { anonymousId: previous } : {},
+				...people
+			});
+		},
+		reset() {
+			identity = anonymous();
+			user = void 0;
+			platform.session?.reset();
+		},
+		getDistinctId() {
+			return identity.distinctId;
+		},
+		getSessionId() {
+			return platform.session?.current();
+		},
+		flush(timeoutMs = 2e3) {
+			return queue.drain(timeoutMs);
+		},
+		sendFinal() {
+			return queue.sendFinal();
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+const SDK_VERSION = "0.1.0";
+/**
+* Parse a `Retry-After` header given in seconds or as an HTTP date.
+*
+* @param value - Header value.
+* @param now - Current time in milliseconds.
+* @returns Seconds to wait, if the header is usable.
+*/
+function parseRetryAfter(value, now = Date.now()) {
+	if (!value) return;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds) && seconds >= 0) return seconds;
+	const date = Date.parse(value);
+	return Number.isNaN(date) ? void 0 : Math.max(0, Math.ceil((date - now) / 1e3));
+}
+/**
+* A 32-character lowercase hex event id.
+*
+* @returns Event id.
+*/
+function randomEventId() {
+	return globalThis.crypto.randomUUID().replaceAll("-", "");
+}
+//#endregion
+export { DEFAULT_SENSITIVE_KEYS, REDACTED, SDK_VERSION, createClient, createQueue, exceptionsFrom, parseRetryAfter, parseStack, randomEventId, scrubRecord, scrubUrl };

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@chaja/sdk-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Shared client for the Chajá JavaScript SDKs: capture, scrubbing, sampling, batching and retries.",
+  "keywords": [
+    "chaja",
+    "error-tracking",
+    "observability",
+    "sdk"
+  ],
+  "homepage": "https://github.com/emiliodominguez/chaja#readme",
+  "bugs": "https://github.com/emiliodominguez/chaja/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emiliodominguez/chaja.git",
+    "directory": "packages/sdk-core"
+  },
+  "type": "module",
+  "nx": {
+    "tags": [
+      "scope:sdk",
+      "type:sdk"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@chaja/protocol": "0.0.0",
+    "tsdown": "0.23.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --clean --out-dir dist",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }