kensa-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Borgware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# kensa-sdk
+
+Send your agent's OpenTelemetry traces to [Kensa](https://kensa.sh).
+
+```bash
+npm install kensa-sdk
+```
+
+## Quick start
+
+```ts
+import { kensa } from "kensa-sdk";
+
+kensa.init({ apiKey: process.env.KENSA_API_KEY });
+```
+
+Spans are sent in the background and flushed when the process exits normally (not on
+`process.exit()`). In a serverless
+function, flush before the response ends:
+
+```ts
+await kensa.flush();
+```
+
+`kensa.init()` sends spans; your existing instrumentation, such as the AI SDK's
+OpenTelemetry integration, produces them. Without an API key it does nothing and logs
+a warning, and nothing the SDK does can throw into your application.
+
+## Already using OpenTelemetry?
+
+If your app registers its own tracer provider, for example with `@vercel/otel`, add
+Kensa's span processor to it instead of calling `kensa.init()`:
+
+```ts
+import { registerOTel } from "@vercel/otel";
+import { kensa } from "kensa-sdk";
+
+registerOTel({
+  serviceName: "support-agent",
+  // @vercel/otel sets service.version to the deployment ID; Kensa matches fixes on the commit.
+  attributes: { "service.version": process.env.VERCEL_GIT_COMMIT_SHA },
+  spanProcessors: [kensa.spanProcessor({ apiKey: process.env.KENSA_API_KEY })],
+});
+```
+
+`@vercel/otel` already sets `deployment.environment.name` from `VERCEL_ENV`. Deployment
+detection only runs in `kensa.init()`, so with any other provider set `service.version`
+and `deployment.environment.name` on its resource from your platform's variables
+(table below).
+
+If you do call `kensa.init()`, call it after any code that registers a tracer provider:
+once Kensa's provider is registered, OpenTelemetry refuses to replace it.
+
+## Configuration
+
+| Setting      | Set with                                         | Default                           |
+| ------------ | ------------------------------------------------ | --------------------------------- |
+| API key      | `init({ apiKey })` or `KENSA_API_KEY`            | Required                          |
+| Service name | `init({ serviceName })` or `OTEL_SERVICE_NAME`   | Package name under npm scripts, else `unknown_service:node` |
+| Deployment   | `OTEL_RESOURCE_ATTRIBUTES`                       | Detected from your platform       |
+
+Kensa checks a fix against the traces from the deployment that shipped it, so it needs
+the deployed commit and the environment. `kensa.init()` detects them:
+
+| Platform         | Commit                   | Environment                |
+| ---------------- | ------------------------ | -------------------------- |
+| Vercel           | `VERCEL_GIT_COMMIT_SHA`  | `VERCEL_ENV`               |
+| Railway          | `RAILWAY_GIT_COMMIT_SHA` | `RAILWAY_ENVIRONMENT_NAME` |
+| Render           | `RENDER_GIT_COMMIT`      |                            |
+
+On Render, set the environment yourself (below). CI and local runs are never detected
+as a deployment.
+
+Anywhere else, or to override detection, set the standard OpenTelemetry variable:
+
+```bash
+OTEL_RESOURCE_ATTRIBUTES="service.version=<commit sha>,deployment.environment.name=production"
+```
+
+Requires Node.js 20 or later.

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { type SpanProcessor } from "@opentelemetry/sdk-trace-node";
+export type InitOptions = {
+    /** Defaults to `KENSA_API_KEY`. */
+    apiKey?: string | undefined;
+    /** Defaults to `OTEL_SERVICE_NAME`, then the package name. */
+    serviceName?: string | undefined;
+};
+export type SpanProcessorOptions = {
+    /** Defaults to `KENSA_API_KEY`. */
+    apiKey?: string | undefined;
+};
+/**
+ * A span processor that sends spans to Kensa, for applications that set up their own
+ * tracer provider, for example with `registerOTel()` from `@vercel/otel`.
+ */
+declare function spanProcessor(options?: SpanProcessorOptions): SpanProcessor;
+/**
+ * Start sending this process's traces to Kensa. Only the first call with an API key
+ * takes effect. Call it after any code that registers a tracer provider: if one is
+ * already registered, this logs how to add `kensa.spanProcessor()` to it instead.
+ */
+declare function init(options?: InitOptions): void;
+/**
+ * Send any buffered spans now. Pending spans are flushed automatically when the process
+ * exits normally; call this at the end of a serverless request. Never throws: a failed
+ * send is logged, so Kensa being unreachable cannot break the application.
+ */
+declare function flush(): Promise<void>;
+export declare const kensa: {
+    init: typeof init;
+    flush: typeof flush;
+    spanProcessor: typeof spanProcessor;
+};
+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":"AAEA,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AASvC,MAAM,MAAM,WAAW,GAAG;IACxB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AA4CF;;;GAGG;AACH,iBAAS,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CA4BxE;AAED;;;;GAIG;AACH,iBAAS,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,IAAI,CA4B7C;AAED;;;;GAIG;AACH,iBAAe,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAOpC;AAED,eAAO,MAAM,KAAK;;;;CAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,123 @@
+import { ProxyTracerProvider, trace } from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import { BatchSpanProcessor, NodeTracerProvider, NoopSpanProcessor, } from "@opentelemetry/sdk-trace-node";
+import { resourceFor } from "./resource.js";
+const DEFAULT_ENDPOINT = "https://ingest.kensa.sh/v1/traces";
+// Ingest accepts at most 4 MiB per request and GenAI spans carry whole prompts, so
+// batches stay far below the exporter's default of 512 spans.
+const MAX_EXPORT_BATCH_SIZE = 24;
+const processors = new Set();
+let initialized = false;
+let warnedMissingKey = false;
+function warnMissingKey() {
+    if (warnedMissingKey)
+        return;
+    warnedMissingKey = true;
+    console.warn("[kensa] KENSA_API_KEY is not set, so no traces are sent to Kensa.");
+}
+// The OTLP exporter reads OTEL_EXPORTER_OTLP_* (headers, certificates) when it is
+// constructed and merges them under explicit options. Those belong to whatever other
+// backend the application exports to, so hide them while Kensa's exporter is built.
+// Construction is synchronous, so nothing else can observe the change.
+function withoutOtlpEnvironment(build) {
+    const hidden = Object.entries(process.env).filter(([name]) => name.startsWith("OTEL_EXPORTER_OTLP_"));
+    for (const [name] of hidden)
+        delete process.env[name];
+    try {
+        return build();
+    }
+    finally {
+        for (const [name, value] of hidden)
+            process.env[name] = value;
+    }
+}
+const PROVIDER_CONFLICT = "[kensa] A tracer provider is already registered, so kensa.init() cannot add its " +
+    "own. Pass kensa.spanProcessor() to that provider's spanProcessors instead.";
+function globalProvider() {
+    const current = trace.getTracerProvider();
+    return current instanceof ProxyTracerProvider ? current.getDelegate() : current;
+}
+// An SDK provider can flush; the API's default no-op provider cannot.
+function hasRegisteredProvider() {
+    return (typeof globalProvider().forceFlush === "function");
+}
+/**
+ * A span processor that sends spans to Kensa, for applications that set up their own
+ * tracer provider, for example with `registerOTel()` from `@vercel/otel`.
+ */
+function spanProcessor(options = {}) {
+    const apiKey = options.apiKey || process.env.KENSA_API_KEY;
+    if (!apiKey) {
+        warnMissingKey();
+        return new NoopSpanProcessor();
+    }
+    let processor;
+    try {
+        const exporter = withoutOtlpEnvironment(() => new OTLPTraceExporter({
+            url: process.env.KENSA_ENDPOINT || DEFAULT_ENDPOINT,
+            headers: { authorization: `Bearer ${apiKey}` },
+            // Ingest redacts prompt-rich batches before acknowledging them.
+            timeoutMillis: 120_000,
+        }));
+        processor = new BatchSpanProcessor(exporter, {
+            maxExportBatchSize: MAX_EXPORT_BATCH_SIZE,
+            exportTimeoutMillis: 120_000,
+        });
+    }
+    catch (error) {
+        console.warn(`[kensa] Not sending traces: ${String(error)}`);
+        return new NoopSpanProcessor();
+    }
+    if (processors.size === 0)
+        process.once("beforeExit", () => void flush());
+    processors.add(processor);
+    return processor;
+}
+/**
+ * Start sending this process's traces to Kensa. Only the first call with an API key
+ * takes effect. Call it after any code that registers a tracer provider: if one is
+ * already registered, this logs how to add `kensa.spanProcessor()` to it instead.
+ */
+function init(options = {}) {
+    if (initialized)
+        return;
+    const apiKey = options.apiKey || process.env.KENSA_API_KEY;
+    if (!apiKey) {
+        warnMissingKey();
+        return;
+    }
+    initialized = true;
+    if (hasRegisteredProvider()) {
+        console.error(PROVIDER_CONFLICT);
+        return;
+    }
+    try {
+        const provider = new NodeTracerProvider({
+            resource: resourceFor(options.serviceName, process.env),
+            spanProcessors: [spanProcessor({ apiKey })],
+        });
+        provider.register();
+        // A provider without forceFlush (another vendor's) still holds the global slot.
+        if (globalProvider() !== provider) {
+            initialized = false;
+            void provider.shutdown();
+            console.error(PROVIDER_CONFLICT);
+        }
+    }
+    catch (error) {
+        console.warn(`[kensa] Not sending traces: ${String(error)}`);
+    }
+}
+/**
+ * Send any buffered spans now. Pending spans are flushed automatically when the process
+ * exits normally; call this at the end of a serverless request. Never throws: a failed
+ * send is logged, so Kensa being unreachable cannot break the application.
+ */
+async function flush() {
+    const results = await Promise.allSettled([...processors].map((processor) => processor.forceFlush()));
+    if (results.some((result) => result.status === "rejected")) {
+        console.warn("[kensa] Some spans could not be sent to Kensa.");
+    }
+}
+export const kensa = { init, flush, spanProcessor };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/resource.d.ts

@@ -0,0 +1,13 @@
+import { type Resource } from "@opentelemetry/resources";
+type Environment = Record<string, string | undefined>;
+/** The deployment Kensa can infer from the platform: commit, environment, service name. */
+export declare function detectedAttributes(env: Environment): Record<string, string>;
+/**
+ * Detected values, overridden by the standard OTEL_SERVICE_NAME and
+ * OTEL_RESOURCE_ATTRIBUTES, overridden by an explicit service name. Starts from
+ * OpenTelemetry's defaults because a provider given a resource does not add them, and
+ * Kensa ignores the deployment of spans that have no service.name.
+ */
+export declare function resourceFor(serviceName: string | undefined, env: Environment): Resource;
+export {};
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,QAAQ,EACd,MAAM,0BAA0B,CAAC;AAIlC,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AA0BtD,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe3E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,GAAG,EAAE,WAAW,GACf,QAAQ,CAkBV"}

package/dist/resource.js

@@ -0,0 +1,65 @@
+import { defaultResource, detectResources, envDetector, resourceFromAttributes, } from "@opentelemetry/resources";
+import { packageVersion } from "./version.js";
+// Full commit SHAs that hosting platforms expose at runtime. Kensa matches a reported
+// fix's commit against the service.version of later traces. Deploy platforms only:
+// CI and local runs must never pass for production traffic.
+const COMMIT_VARIABLES = [
+    "VERCEL_GIT_COMMIT_SHA",
+    "RENDER_GIT_COMMIT",
+    "RAILWAY_GIT_COMMIT_SHA",
+];
+const ENVIRONMENT_VARIABLES = ["VERCEL_ENV", "RAILWAY_ENVIRONMENT_NAME"];
+const ENVIRONMENT_KEYS = [
+    "deployment.environment.name",
+    "deployment.environment",
+];
+function first(env, names) {
+    for (const name of names) {
+        const value = env[name]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** The deployment Kensa can infer from the platform: commit, environment, service name. */
+export function detectedAttributes(env) {
+    const commit = first(env, COMMIT_VARIABLES);
+    const environment = first(env, ENVIRONMENT_VARIABLES);
+    const name = env.npm_package_name?.trim();
+    return {
+        ...(name ? { "service.name": name } : {}),
+        ...(commit ? { "service.version": commit } : {}),
+        // Both spellings: semantic conventions renamed the attribute, and Kensa prefers the new one.
+        ...(environment
+            ? {
+                "deployment.environment.name": environment,
+                "deployment.environment": environment,
+            }
+            : {}),
+    };
+}
+/**
+ * Detected values, overridden by the standard OTEL_SERVICE_NAME and
+ * OTEL_RESOURCE_ATTRIBUTES, overridden by an explicit service name. Starts from
+ * OpenTelemetry's defaults because a provider given a resource does not add them, and
+ * Kensa ignores the deployment of spans that have no service.name.
+ */
+export function resourceFor(serviceName, env) {
+    const version = packageVersion();
+    const fromEnv = detectResources({ detectors: [envDetector] });
+    const detected = detectedAttributes(env);
+    // An environment set through OTEL_RESOURCE_ATTRIBUTES, in either spelling, replaces
+    // the detected one entirely rather than leaving the two spellings disagreeing.
+    if (ENVIRONMENT_KEYS.some((key) => fromEnv.attributes[key] !== undefined)) {
+        for (const key of ENVIRONMENT_KEYS)
+            delete detected[key];
+    }
+    return defaultResource()
+        .merge(resourceFromAttributes(detected))
+        .merge(fromEnv)
+        .merge(resourceFromAttributes({
+        ...(serviceName ? { "service.name": serviceName } : {}),
+        ...(version ? { "kensa.instrumentation.version": version } : {}),
+    }));
+}
+//# sourceMappingURL=resource.js.map

package/dist/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,eAAe,EACf,WAAW,EACX,sBAAsB,GAEvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAI9C,sFAAsF;AACtF,mFAAmF;AACnF,4DAA4D;AAC5D,MAAM,gBAAgB,GAAG;IACvB,uBAAuB;IACvB,mBAAmB;IACnB,wBAAwB;CAChB,CAAC;AAEX,MAAM,qBAAqB,GAAG,CAAC,YAAY,EAAE,0BAA0B,CAAU,CAAC;AAElF,MAAM,gBAAgB,GAAG;IACvB,6BAA6B;IAC7B,wBAAwB;CAChB,CAAC;AAEX,SAAS,KAAK,CAAC,GAAgB,EAAE,KAAwB;IACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;QAChC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,GAAgB;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,CAAC;IAC1C,OAAO;QACL,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,6FAA6F;QAC7F,GAAG,CAAC,WAAW;YACb,CAAC,CAAC;gBACE,6BAA6B,EAAE,WAAW;gBAC1C,wBAAwB,EAAE,WAAW;aACtC;YACH,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,WAA+B,EAC/B,GAAgB;IAEhB,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,eAAe,CAAC,EAAE,SAAS,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACzC,oFAAoF;IACpF,+EAA+E;IAC/E,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC;QAC1E,KAAK,MAAM,GAAG,IAAI,gBAAgB;YAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,eAAe,EAAE;SACrB,KAAK,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;SACvC,KAAK,CAAC,OAAO,CAAC;SACd,KAAK,CACJ,sBAAsB,CAAC;QACrB,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,+BAA+B,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC,CACH,CAAC;AACN,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * This package's version, read from its package.json so the manifest is the only place
+ * it is written. Undefined when a bundler dropped that file; the name check stops a
+ * bundle from picking up the host application's package.json instead.
+ */
+export declare function packageVersion(): string | undefined;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAiBnD"}

package/dist/version.js

@@ -0,0 +1,25 @@
+import { createRequire } from "node:module";
+const PACKAGE_NAME = "kensa-sdk";
+/**
+ * This package's version, read from its package.json so the manifest is the only place
+ * it is written. Undefined when a bundler dropped that file; the name check stops a
+ * bundle from picking up the host application's package.json instead.
+ */
+export function packageVersion() {
+    try {
+        const manifest = createRequire(import.meta.url)("../package.json");
+        if (typeof manifest === "object" &&
+            manifest !== null &&
+            "name" in manifest &&
+            manifest.name === PACKAGE_NAME &&
+            "version" in manifest &&
+            typeof manifest.version === "string") {
+            return manifest.version;
+        }
+    }
+    catch {
+        // Fall through: an unknown version must never stop instrumentation.
+    }
+    return undefined;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAY,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC;QAC5E,IACE,OAAO,QAAQ,KAAK,QAAQ;YAC5B,QAAQ,KAAK,IAAI;YACjB,MAAM,IAAI,QAAQ;YAClB,QAAQ,CAAC,IAAI,KAAK,YAAY;YAC9B,SAAS,IAAI,QAAQ;YACrB,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,EACpC,CAAC;YACD,OAAO,QAAQ,CAAC,OAAO,CAAC;QAC1B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;IACtE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "kensa-sdk",
+  "version": "0.1.0",
+  "description": "Thin OpenTelemetry wrapper that exports agent traces to Kensa",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://kensa.sh",
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.208.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-trace-node": "^2.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  }
+}