@strada.sh/light 0.1.0

package/dist/attrs.d.ts

@@ -0,0 +1,26 @@
+/** Subset of the full SDK attribute keys. Values must match `@strada.sh/sdk` ATTR. */
+export declare const ATTR: {
+    readonly "service.name": "service.name";
+    readonly "service.version": "service.version";
+    readonly "deployment.environment.name": "deployment.environment.name";
+    readonly "deployment.id": "deployment.id";
+    readonly "vcs.ref.head.revision": "vcs.ref.head.revision";
+    readonly "vcs.ref.head.name": "vcs.ref.head.name";
+    readonly "event.name": "event.name";
+    readonly "user.id": "user.id";
+    readonly "user.email": "user.email";
+    readonly "user.name": "user.name";
+    readonly "user.full_name": "user.full_name";
+    readonly "user.hash": "user.hash";
+    readonly "user.image": "user.image";
+    readonly "organization.id": "organization.id";
+    readonly "organization.name": "organization.name";
+    readonly "strada.user.identify": "strada.user.identify";
+    readonly "exception.type": "exception.type";
+    readonly "exception.message": "exception.message";
+    readonly "exception.stacktrace": "exception.stacktrace";
+    readonly "exception.mechanism.type": "exception.mechanism.type";
+    readonly "exception.mechanism.handled": "exception.mechanism.handled";
+    readonly "exception.fingerprint": "exception.fingerprint";
+};
+//# sourceMappingURL=attrs.d.ts.map

package/dist/attrs.d.ts.map

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

package/dist/attrs.js

@@ -0,0 +1,25 @@
+/** Subset of the full SDK attribute keys. Values must match `@strada.sh/sdk` ATTR. */
+export const ATTR = {
+    "service.name": "service.name",
+    "service.version": "service.version",
+    "deployment.environment.name": "deployment.environment.name",
+    "deployment.id": "deployment.id",
+    "vcs.ref.head.revision": "vcs.ref.head.revision",
+    "vcs.ref.head.name": "vcs.ref.head.name",
+    "event.name": "event.name",
+    "user.id": "user.id",
+    "user.email": "user.email",
+    "user.name": "user.name",
+    "user.full_name": "user.full_name",
+    "user.hash": "user.hash",
+    "user.image": "user.image",
+    "organization.id": "organization.id",
+    "organization.name": "organization.name",
+    "strada.user.identify": "strada.user.identify",
+    "exception.type": "exception.type",
+    "exception.message": "exception.message",
+    "exception.stacktrace": "exception.stacktrace",
+    "exception.mechanism.type": "exception.mechanism.type",
+    "exception.mechanism.handled": "exception.mechanism.handled",
+    "exception.fingerprint": "exception.fingerprint",
+};

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `@strada.sh/light`: a zero-dependency, drop-in 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.
+ *
+ * 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.
+ *
+ * Every function follows "telemetry never throws": failures are returned as
+ * values and logged once with console.warn.
+ */
+export interface StradaOptions {
+    /** Strada project identifier. Blank disables sending. */
+    projectId: string;
+    /** service.name resource attribute */
+    service: string;
+    /** Kill switch. `false` makes every call a no-op. Defaults to true, false when import.meta.hot is set. */
+    enabled?: boolean;
+    /** Override the ingest endpoint. Defaults to https://{projectId}-ingest.strada.sh */
+    endpoint?: string;
+    /** Server-side ingest token. Omit in code shipped to users (npm CLIs, browsers). */
+    token?: string;
+    /** service.version resource attribute */
+    version?: string;
+    /** deployment.environment.name resource attribute */
+    environment?: string;
+    /** vcs.ref.head.revision resource attribute */
+    releaseCommit?: string;
+    /** vcs.ref.head.name resource attribute */
+    releaseBranch?: string;
+    /** deployment.id resource attribute. Defaults to releaseCommit. */
+    deploymentId?: string;
+    /** Current user id, sent as user.id on every event and error. */
+    userId?: string | (() => string | undefined);
+    /** Same shape as the full SDK. Only log batching applies here. */
+    telemetry?: {
+        logs?: {
+            scheduledDelayMillis?: number;
+            maxExportBatchSize?: number;
+        };
+    };
+}
+export interface StradaUserIdentity {
+    /** Stable application user id. */
+    id: string;
+    /** User email. PII, sent only through identifyUser profile events. */
+    email?: string;
+    /** Display name or username. */
+    name?: string;
+    /** Full human-readable name. */
+    fullName?: string;
+    /** Stable anonymized user hash when raw ids are sensitive. */
+    hash?: string;
+    /** Profile image URL. */
+    image?: string;
+    /** Product/account organization id for this user profile. */
+    organizationId?: string;
+    /** Product/account organization name for this user profile. */
+    organizationName?: string;
+    /** Additional low-cardinality profile attributes. */
+    attributes?: Record<string, string>;
+}
+export interface CaptureExceptionOptions {
+    /** Was this error caught by user code (true) or a global handler (false)? */
+    handled?: boolean;
+    /** How the exception was captured, e.g. onerror or unhandledrejection */
+    mechanism?: string;
+    /** Extra tags attached to the error */
+    tags?: Record<string, string>;
+    /** Custom fingerprint override for issue grouping. */
+    fingerprint?: string[];
+}
+type AttributeValue = string | number | boolean;
+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;
+/** 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 a handled error as an issue. No ignoreErrors, denyUrls, or
+ * beforeSend in the light build; KnownError instances are skipped like in
+ * the full SDK.
+ */
+export declare function captureException(error: unknown, opts?: CaptureExceptionOptions): Error | undefined;
+export declare function flush(): Promise<Error | undefined>;
+export declare function shutdown(): Promise<Error | undefined>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,279 @@
+/**
+ * `@strada.sh/light`: a zero-dependency, drop-in 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.
+ *
+ * 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.
+ *
+ * Every function follows "telemetry never throws": failures are returned as
+ * values and logged once with console.warn.
+ */
+import { ATTR } from "./attrs.js";
+// OTel SeverityNumber values, inlined to avoid importing @opentelemetry/api-logs.
+const INFO_SEVERITY = 9;
+const ERROR_SEVERITY = 17;
+const MAX_QUEUE_SIZE = 2048;
+let state;
+let tags = {};
+const warned = new Set();
+function warnOnce(message) {
+    if (warned.has(message))
+        return;
+    warned.add(message);
+    console.warn(`[@strada.sh/light] ${message}`);
+}
+function failure(message, cause) {
+    warnOnce(message);
+    return new Error(message, { cause });
+}
+function isDevMode() {
+    try {
+        return Boolean(import.meta.hot);
+    }
+    catch {
+        return false;
+    }
+}
+function toAnyValue(value) {
+    if (typeof value === "string")
+        return { stringValue: value };
+    if (typeof value === "boolean")
+        return { boolValue: value };
+    if (Number.isInteger(value))
+        return { intValue: value };
+    return { doubleValue: value };
+}
+function toKeyValues(record) {
+    return Object.entries(record).flatMap(([key, value]) => {
+        if (value === undefined || value === "")
+            return [];
+        return [{ key, value: toAnyValue(value) }];
+    });
+}
+function normalizeError(value) {
+    if (value instanceof Error)
+        return value;
+    if (typeof value === "string")
+        return new Error(value);
+    try {
+        const message = typeof value === "object" && value !== null ? Reflect.get(value, "message") : undefined;
+        return new Error(typeof message === "string" ? message : String(value));
+    }
+    catch {
+        return new Error("Unknown error");
+    }
+}
+async function send(current, records) {
+    try {
+        const response = await fetch(`${current.endpoint}/v1/logs`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...(current.options.token ? { authorization: `Bearer ${current.options.token}` } : {}),
+            },
+            body: JSON.stringify({
+                resourceLogs: [
+                    {
+                        resource: { attributes: current.resource },
+                        scopeLogs: [{ scope: { name: "strada" }, logRecords: records }],
+                    },
+                ],
+            }),
+        });
+        if (!response.ok)
+            return failure(`Strada ingest responded ${response.status}`);
+        return undefined;
+    }
+    catch (cause) {
+        return failure("Strada ingest request failed", cause);
+    }
+}
+/** Queue one log record. Shared by track, identifyUser, and captureException. */
+function emit({ operation, name, body, severity, attributes, }) {
+    if (!state) {
+        warnOnce(`${operation} called before initStrada(). Nothing was sent.`);
+        return undefined;
+    }
+    const current = state;
+    if (!current.exporting)
+        return undefined;
+    if (current.queue.length >= MAX_QUEUE_SIZE)
+        return failure("Queue full, dropping telemetry");
+    const userId = typeof current.options.userId === "function" ? current.options.userId() : current.options.userId;
+    const time = `${BigInt(Date.now()) * 1000000n}`;
+    current.queue.push({
+        timeUnixNano: time,
+        observedTimeUnixNano: time,
+        severityNumber: severity,
+        severityText: severity === ERROR_SEVERITY ? "ERROR" : "INFO",
+        body: { stringValue: body },
+        eventName: name,
+        attributes: toKeyValues({ [ATTR["user.id"]]: userId, ...attributes }),
+    });
+    if (!current.timer) {
+        current.timer = setInterval(() => {
+            void flush();
+        }, current.options.telemetry?.logs?.scheduledDelayMillis ?? 5000);
+        // Never keep a CLI or daemon alive just to send telemetry.
+        if (typeof current.timer === "object" && typeof current.timer.unref === "function") {
+            current.timer.unref();
+        }
+    }
+    if (current.queue.length >= (current.options.telemetry?.logs?.maxExportBatchSize ?? 512)) {
+        void flush();
+    }
+    return undefined;
+}
+export function initStrada(options) {
+    try {
+        if (state) {
+            warnOnce("initStrada() was already called. Ignoring duplicate init.");
+            return undefined;
+        }
+        const endpoint = options.endpoint?.trim()
+            ? options.endpoint.replace(/\/+$/, "").toLowerCase()
+            : options.projectId?.trim()
+                ? `https://${options.projectId}-ingest.strada.sh`.toLowerCase()
+                : "";
+        if (!endpoint && options.enabled !== false) {
+            warnOnce("initStrada() called without a projectId. Telemetry is disabled and all SDK calls are no-ops.");
+        }
+        state = {
+            options,
+            endpoint,
+            exporting: Boolean(endpoint) && (options.enabled ?? !isDevMode()),
+            resource: toKeyValues({
+                [ATTR["service.name"]]: options.service,
+                [ATTR["service.version"]]: options.version,
+                [ATTR["deployment.environment.name"]]: options.environment,
+                [ATTR["vcs.ref.head.revision"]]: options.releaseCommit,
+                [ATTR["vcs.ref.head.name"]]: options.releaseBranch,
+                [ATTR["deployment.id"]]: options.deploymentId ?? options.releaseCommit,
+            }),
+            queue: [],
+            inflight: Promise.resolve(undefined),
+            timer: undefined,
+        };
+        return undefined;
+    }
+    catch (cause) {
+        return failure("initStrada() failed", cause);
+    }
+}
+/** Product analytics event. Properties are stored as `custom.*` attributes. */
+export function track(name, properties) {
+    try {
+        const custom = Object.fromEntries(Object.entries(properties ?? {}).map(([key, value]) => {
+            return [`custom.${key}`, value];
+        }));
+        return emit({
+            operation: "track()",
+            name,
+            body: name,
+            severity: INFO_SEVERITY,
+            attributes: { [ATTR["event.name"]]: name, ...custom },
+        });
+    }
+    catch (cause) {
+        return failure("track() failed", cause);
+    }
+}
+/** Full profile snapshot for `otel_users`. Call from trusted code with every field you want to keep. */
+export function identifyUser(user) {
+    try {
+        const name = ATTR["strada.user.identify"];
+        return emit({
+            operation: "identifyUser()",
+            name,
+            body: name,
+            severity: INFO_SEVERITY,
+            attributes: {
+                [ATTR["event.name"]]: name,
+                [ATTR["user.id"]]: user.id,
+                [ATTR["user.email"]]: user.email,
+                [ATTR["user.name"]]: user.name,
+                [ATTR["user.full_name"]]: user.fullName,
+                [ATTR["user.hash"]]: user.hash,
+                [ATTR["user.image"]]: user.image,
+                [ATTR["organization.id"]]: user.organizationId,
+                [ATTR["organization.name"]]: user.organizationName,
+                ...Object.fromEntries(Object.entries(user.attributes ?? {}).map(([key, value]) => {
+                    return [`strada.user.attributes.${key}`, value];
+                })),
+            },
+        });
+    }
+    catch (cause) {
+        return failure("identifyUser() failed", cause);
+    }
+}
+/** Tags merged into every captureException() call. */
+export function setTags(next) {
+    tags = { ...tags, ...next };
+}
+/**
+ * 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.
+ */
+export function captureException(error, opts) {
+    try {
+        const normalized = normalizeError(error);
+        if (normalized.name === "KnownError" || normalized.constructor?.name === "KnownError")
+            return undefined;
+        const fingerprintValue = Reflect.get(normalized, "fingerprint");
+        const fingerprint = opts?.fingerprint ?? (Array.isArray(fingerprintValue) ? fingerprintValue : undefined);
+        return emit({
+            operation: "captureException()",
+            name: "exception",
+            body: normalized.message,
+            severity: ERROR_SEVERITY,
+            attributes: {
+                [ATTR["exception.type"]]: normalized.name || "Error",
+                [ATTR["exception.message"]]: normalized.message || "",
+                [ATTR["exception.stacktrace"]]: normalized.stack ?? "",
+                [ATTR["exception.mechanism.type"]]: opts?.mechanism ?? "generic",
+                [ATTR["exception.mechanism.handled"]]: String(opts?.handled ?? true),
+                [ATTR["exception.fingerprint"]]: fingerprint ? JSON.stringify(fingerprint) : undefined,
+                ...tags,
+                ...opts?.tags,
+            },
+        });
+    }
+    catch (cause) {
+        return failure("captureException() failed", cause);
+    }
+}
+export function flush() {
+    const current = state;
+    if (!current)
+        return Promise.resolve(undefined);
+    if (current.queue.length === 0)
+        return current.inflight;
+    const records = current.queue;
+    current.queue = [];
+    // Chain sends so flush() resolves only after every earlier batch is done.
+    current.inflight = current.inflight.then(() => {
+        return send(current, records);
+    });
+    return current.inflight;
+}
+export async function shutdown() {
+    const current = state;
+    if (!current)
+        return undefined;
+    clearInterval(current.timer);
+    const error = await flush();
+    state = undefined;
+    return error;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@strada.sh/light",
+  "version": "0.1.0",
+  "description": "Zero-dependency Strada SDK subset for product events, user profiles, and handled errors. Drop-in for @strada.sh/sdk: same names, same options, no OpenTelemetry.",
+  "keywords": [
+    "strada",
+    "analytics",
+    "product-analytics",
+    "telemetry",
+    "opentelemetry",
+    "otlp"
+  ],
+  "homepage": "https://github.com/remorses/strada",
+  "bugs": "https://github.com/remorses/strada/issues",
+  "license": "MIT",
+  "author": "remorses <beats.by.morse@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/remorses/strada",
+    "directory": "light"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./src": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "!**/*.test.*"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.9.6",
+    "rimraf": "^6.1.3",
+    "@strada.sh/sdk": "^0.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run src",
+    "typecheck": "tsc"
+  }
+}

package/src/attrs.ts

@@ -0,0 +1,25 @@
+/** Subset of the full SDK attribute keys. Values must match `@strada.sh/sdk` ATTR. */
+export const ATTR = {
+  "service.name": "service.name",
+  "service.version": "service.version",
+  "deployment.environment.name": "deployment.environment.name",
+  "deployment.id": "deployment.id",
+  "vcs.ref.head.revision": "vcs.ref.head.revision",
+  "vcs.ref.head.name": "vcs.ref.head.name",
+  "event.name": "event.name",
+  "user.id": "user.id",
+  "user.email": "user.email",
+  "user.name": "user.name",
+  "user.full_name": "user.full_name",
+  "user.hash": "user.hash",
+  "user.image": "user.image",
+  "organization.id": "organization.id",
+  "organization.name": "organization.name",
+  "strada.user.identify": "strada.user.identify",
+  "exception.type": "exception.type",
+  "exception.message": "exception.message",
+  "exception.stacktrace": "exception.stacktrace",
+  "exception.mechanism.type": "exception.mechanism.type",
+  "exception.mechanism.handled": "exception.mechanism.handled",
+  "exception.fingerprint": "exception.fingerprint",
+} as const;

package/src/index.ts

@@ -0,0 +1,385 @@
+/**
+ * `@strada.sh/light`: a zero-dependency, drop-in 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.
+ *
+ * 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.
+ *
+ * Every function follows "telemetry never throws": failures are returned as
+ * values and logged once with console.warn.
+ */
+
+import { ATTR } from "./attrs.ts";
+
+export interface StradaOptions {
+  /** Strada project identifier. Blank disables sending. */
+  projectId: string;
+  /** service.name resource attribute */
+  service: string;
+  /** Kill switch. `false` makes every call a no-op. Defaults to true, false when import.meta.hot is set. */
+  enabled?: boolean;
+  /** Override the ingest endpoint. Defaults to https://{projectId}-ingest.strada.sh */
+  endpoint?: string;
+  /** Server-side ingest token. Omit in code shipped to users (npm CLIs, browsers). */
+  token?: string;
+  /** service.version resource attribute */
+  version?: string;
+  /** deployment.environment.name resource attribute */
+  environment?: string;
+  /** vcs.ref.head.revision resource attribute */
+  releaseCommit?: string;
+  /** vcs.ref.head.name resource attribute */
+  releaseBranch?: string;
+  /** deployment.id resource attribute. Defaults to releaseCommit. */
+  deploymentId?: string;
+  /** Current user id, sent as user.id on every event and error. */
+  userId?: string | (() => string | undefined);
+  /** Same shape as the full SDK. Only log batching applies here. */
+  telemetry?: {
+    logs?: { scheduledDelayMillis?: number; maxExportBatchSize?: number };
+  };
+}
+
+export interface StradaUserIdentity {
+  /** Stable application user id. */
+  id: string;
+  /** User email. PII, sent only through identifyUser profile events. */
+  email?: string;
+  /** Display name or username. */
+  name?: string;
+  /** Full human-readable name. */
+  fullName?: string;
+  /** Stable anonymized user hash when raw ids are sensitive. */
+  hash?: string;
+  /** Profile image URL. */
+  image?: string;
+  /** Product/account organization id for this user profile. */
+  organizationId?: string;
+  /** Product/account organization name for this user profile. */
+  organizationName?: string;
+  /** Additional low-cardinality profile attributes. */
+  attributes?: Record<string, string>;
+}
+
+export interface CaptureExceptionOptions {
+  /** Was this error caught by user code (true) or a global handler (false)? */
+  handled?: boolean;
+  /** How the exception was captured, e.g. onerror or unhandledrejection */
+  mechanism?: string;
+  /** Extra tags attached to the error */
+  tags?: Record<string, string>;
+  /** Custom fingerprint override for issue grouping. */
+  fingerprint?: string[];
+}
+
+type AttributeValue = string | number | boolean;
+
+type OtlpAnyValue =
+  | { stringValue: string }
+  | { intValue: number }
+  | { doubleValue: number }
+  | { boolValue: boolean };
+
+type OtlpKeyValue = { key: string; value: OtlpAnyValue };
+
+type OtlpLogRecord = {
+  timeUnixNano: string;
+  observedTimeUnixNano: string;
+  severityNumber: number;
+  severityText: string;
+  body: { stringValue: string };
+  eventName: string;
+  attributes: OtlpKeyValue[];
+};
+
+type LightState = {
+  options: StradaOptions;
+  endpoint: string;
+  exporting: boolean;
+  resource: OtlpKeyValue[];
+  queue: OtlpLogRecord[];
+  inflight: Promise<Error | undefined>;
+  timer: ReturnType<typeof setInterval> | undefined;
+};
+
+// OTel SeverityNumber values, inlined to avoid importing @opentelemetry/api-logs.
+const INFO_SEVERITY = 9;
+const ERROR_SEVERITY = 17;
+const MAX_QUEUE_SIZE = 2048;
+
+let state: LightState | undefined;
+let tags: Record<string, string> = {};
+
+const warned = new Set<string>();
+function warnOnce(message: string): void {
+  if (warned.has(message)) return;
+  warned.add(message);
+  console.warn(`[@strada.sh/light] ${message}`);
+}
+
+function failure(message: string, cause?: unknown): Error {
+  warnOnce(message);
+  return new Error(message, { cause });
+}
+
+function isDevMode(): boolean {
+  try {
+    return Boolean((import.meta as { hot?: unknown }).hot);
+  } catch {
+    return false;
+  }
+}
+
+function toAnyValue(value: AttributeValue): OtlpAnyValue {
+  if (typeof value === "string") return { stringValue: value };
+  if (typeof value === "boolean") return { boolValue: value };
+  if (Number.isInteger(value)) return { intValue: value };
+  return { doubleValue: value };
+}
+
+function toKeyValues(record: Record<string, AttributeValue | undefined>): OtlpKeyValue[] {
+  return Object.entries(record).flatMap(([key, value]) => {
+    if (value === undefined || value === "") return [];
+    return [{ key, value: toAnyValue(value) }];
+  });
+}
+
+function normalizeError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  if (typeof value === "string") return new Error(value);
+  try {
+    const message = typeof value === "object" && value !== null ? Reflect.get(value, "message") : undefined;
+    return new Error(typeof message === "string" ? message : String(value));
+  } catch {
+    return new Error("Unknown error");
+  }
+}
+
+async function send(current: LightState, records: OtlpLogRecord[]): Promise<Error | undefined> {
+  try {
+    const response = await fetch(`${current.endpoint}/v1/logs`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...(current.options.token ? { authorization: `Bearer ${current.options.token}` } : {}),
+      },
+      body: JSON.stringify({
+        resourceLogs: [
+          {
+            resource: { attributes: current.resource },
+            scopeLogs: [{ scope: { name: "strada" }, logRecords: records }],
+          },
+        ],
+      }),
+    });
+    if (!response.ok) return failure(`Strada ingest responded ${response.status}`);
+    return undefined;
+  } catch (cause) {
+    return failure("Strada ingest request failed", cause);
+  }
+}
+
+/** Queue one log record. Shared by track, identifyUser, and captureException. */
+function emit({
+  operation,
+  name,
+  body,
+  severity,
+  attributes,
+}: {
+  operation: string;
+  name: string;
+  body: string;
+  severity: number;
+  attributes: Record<string, AttributeValue | undefined>;
+}): Error | undefined {
+  if (!state) {
+    warnOnce(`${operation} called before initStrada(). Nothing was sent.`);
+    return undefined;
+  }
+  const current = state;
+  if (!current.exporting) return undefined;
+  if (current.queue.length >= MAX_QUEUE_SIZE) return failure("Queue full, dropping telemetry");
+
+  const userId = typeof current.options.userId === "function" ? current.options.userId() : current.options.userId;
+  const time = `${BigInt(Date.now()) * 1_000_000n}`;
+  current.queue.push({
+    timeUnixNano: time,
+    observedTimeUnixNano: time,
+    severityNumber: severity,
+    severityText: severity === ERROR_SEVERITY ? "ERROR" : "INFO",
+    body: { stringValue: body },
+    eventName: name,
+    attributes: toKeyValues({ [ATTR["user.id"]]: userId, ...attributes }),
+  });
+
+  if (!current.timer) {
+    current.timer = setInterval(() => {
+      void flush();
+    }, current.options.telemetry?.logs?.scheduledDelayMillis ?? 5000);
+    // Never keep a CLI or daemon alive just to send telemetry.
+    if (typeof current.timer === "object" && typeof current.timer.unref === "function") {
+      current.timer.unref();
+    }
+  }
+  if (current.queue.length >= (current.options.telemetry?.logs?.maxExportBatchSize ?? 512)) {
+    void flush();
+  }
+  return undefined;
+}
+
+export function initStrada(options: StradaOptions): Error | undefined {
+  try {
+    if (state) {
+      warnOnce("initStrada() was already called. Ignoring duplicate init.");
+      return undefined;
+    }
+    const endpoint = options.endpoint?.trim()
+      ? options.endpoint.replace(/\/+$/, "").toLowerCase()
+      : options.projectId?.trim()
+        ? `https://${options.projectId}-ingest.strada.sh`.toLowerCase()
+        : "";
+    if (!endpoint && options.enabled !== false) {
+      warnOnce("initStrada() called without a projectId. Telemetry is disabled and all SDK calls are no-ops.");
+    }
+    state = {
+      options,
+      endpoint,
+      exporting: Boolean(endpoint) && (options.enabled ?? !isDevMode()),
+      resource: toKeyValues({
+        [ATTR["service.name"]]: options.service,
+        [ATTR["service.version"]]: options.version,
+        [ATTR["deployment.environment.name"]]: options.environment,
+        [ATTR["vcs.ref.head.revision"]]: options.releaseCommit,
+        [ATTR["vcs.ref.head.name"]]: options.releaseBranch,
+        [ATTR["deployment.id"]]: options.deploymentId ?? options.releaseCommit,
+      }),
+      queue: [],
+      inflight: Promise.resolve(undefined),
+      timer: undefined,
+    };
+    return undefined;
+  } catch (cause) {
+    return failure("initStrada() failed", cause);
+  }
+}
+
+/** Product analytics event. Properties are stored as `custom.*` attributes. */
+export function track(name: string, properties?: Record<string, AttributeValue>): Error | undefined {
+  try {
+    const custom = Object.fromEntries(
+      Object.entries(properties ?? {}).map(([key, value]) => {
+        return [`custom.${key}`, value];
+      }),
+    );
+    return emit({
+      operation: "track()",
+      name,
+      body: name,
+      severity: INFO_SEVERITY,
+      attributes: { [ATTR["event.name"]]: name, ...custom },
+    });
+  } catch (cause) {
+    return failure("track() failed", cause);
+  }
+}
+
+/** Full profile snapshot for `otel_users`. Call from trusted code with every field you want to keep. */
+export function identifyUser(user: StradaUserIdentity): Error | undefined {
+  try {
+    const name = ATTR["strada.user.identify"];
+    return emit({
+      operation: "identifyUser()",
+      name,
+      body: name,
+      severity: INFO_SEVERITY,
+      attributes: {
+        [ATTR["event.name"]]: name,
+        [ATTR["user.id"]]: user.id,
+        [ATTR["user.email"]]: user.email,
+        [ATTR["user.name"]]: user.name,
+        [ATTR["user.full_name"]]: user.fullName,
+        [ATTR["user.hash"]]: user.hash,
+        [ATTR["user.image"]]: user.image,
+        [ATTR["organization.id"]]: user.organizationId,
+        [ATTR["organization.name"]]: user.organizationName,
+        ...Object.fromEntries(
+          Object.entries(user.attributes ?? {}).map(([key, value]) => {
+            return [`strada.user.attributes.${key}`, value];
+          }),
+        ),
+      },
+    });
+  } catch (cause) {
+    return failure("identifyUser() failed", cause);
+  }
+}
+
+/** Tags merged into every captureException() call. */
+export function setTags(next: Record<string, string>): void {
+  tags = { ...tags, ...next };
+}
+
+/**
+ * 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.
+ */
+export function captureException(error: unknown, opts?: CaptureExceptionOptions): Error | undefined {
+  try {
+    const normalized = normalizeError(error);
+    if (normalized.name === "KnownError" || normalized.constructor?.name === "KnownError") return undefined;
+    const fingerprintValue = Reflect.get(normalized, "fingerprint");
+    const fingerprint = opts?.fingerprint ?? (Array.isArray(fingerprintValue) ? fingerprintValue : undefined);
+    return emit({
+      operation: "captureException()",
+      name: "exception",
+      body: normalized.message,
+      severity: ERROR_SEVERITY,
+      attributes: {
+        [ATTR["exception.type"]]: normalized.name || "Error",
+        [ATTR["exception.message"]]: normalized.message || "",
+        [ATTR["exception.stacktrace"]]: normalized.stack ?? "",
+        [ATTR["exception.mechanism.type"]]: opts?.mechanism ?? "generic",
+        [ATTR["exception.mechanism.handled"]]: String(opts?.handled ?? true),
+        [ATTR["exception.fingerprint"]]: fingerprint ? JSON.stringify(fingerprint) : undefined,
+        ...tags,
+        ...opts?.tags,
+      },
+    });
+  } catch (cause) {
+    return failure("captureException() failed", cause);
+  }
+}
+
+export function flush(): Promise<Error | undefined> {
+  const current = state;
+  if (!current) return Promise.resolve(undefined);
+  if (current.queue.length === 0) return current.inflight;
+  const records = current.queue;
+  current.queue = [];
+  // Chain sends so flush() resolves only after every earlier batch is done.
+  current.inflight = current.inflight.then(() => {
+    return send(current, records);
+  });
+  return current.inflight;
+}
+
+export async function shutdown(): Promise<Error | undefined> {
+  const current = state;
+  if (!current) return undefined;
+  clearInterval(current.timer);
+  const error = await flush();
+  state = undefined;
+  return error;
+}