@axonflow/sdk 9.2.0 → 9.3.0

package/dist/cjs/read-identity.js

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * Read-path per-user identity and the platform's read-scope contract.
+ *
+ * Since platform #2922 the role-scoped read routes (audit / decisions /
+ * overrides) answer from the identity the CALLER presents, not from the tenant
+ * credential alone. The tenant credential in `Authorization` says which
+ * organization is asking; it does not say WHO. A caller that presents no
+ * per-user identity to an enterprise stack is not "a caller who sees
+ * everything" and is not "a caller who sees nothing by coincidence" — it is a
+ * caller the platform cannot scope, and every scoped read it makes returns
+ * zero rows by construction.
+ *
+ * This module carries the whole surface:
+ *
+ * - the per-user identity itself (`userToken` on the config for a client-wide
+ *   identity, the per-call `{ userToken }` option on a read, and
+ *   `client.asUser(token)` for a process acting on behalf of several people),
+ *   stamped as the `X-User-Token` header from exactly ONE site — the client's
+ *   `_fetch` wrapper, which every request goes through. There is no per-method
+ *   header plumbing, deliberately: the platform reads the header once in its
+ *   own proxy middleware (`platform/agent/proxy.go` `proxyAuthMiddleware`),
+ *   not per route, so a per-method sprinkle here would be a second, drifting
+ *   copy of a decision the platform makes in one place.
+ *
+ * - the response side of the same contract: `X-Axonflow-Read-Scope`, which the
+ *   platform stamps on every scoped read (`platform/orchestrator/read_scope.go`
+ *   `applyReadScopeHeader`) to say which of the three scopes the answer was
+ *   computed under. Without it, a 404 from explain and an empty list from
+ *   `listDecisions` are indistinguishable from "the row is not there", which is
+ *   how a governed read comes to report a confident, vacuous nothing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadScopeError = exports.ReadScope = exports.HEADER_READ_SCOPE = exports.HEADER_USER_TOKEN = void 0;
+exports.readScopeOf = readScopeOf;
+exports.readScopeErrorFor = readScopeErrorFor;
+exports.refuseVacuousScopedPage = refuseVacuousScopedPage;
+exports.stripCredentialsOffOrigin = stripCredentialsOffOrigin;
+exports.applyReadIdentity = applyReadIdentity;
+/**
+ * The request header carrying the per-user identity.
+ *
+ * This constant is the SDK's only spelling of it. The header is set in exactly
+ * one place (`applyReadIdentity`, called from the client's `_fetch`); if you
+ * find yourself setting it in a method, the method is the wrong altitude.
+ */
+exports.HEADER_USER_TOKEN = 'X-User-Token';
+/** The response header the platform stamps on scoped reads. */
+exports.HEADER_READ_SCOPE = 'X-Axonflow-Read-Scope';
+exports.ReadScope = {
+    /** No `X-Axonflow-Read-Scope` header at all. Distinct from `None`. */
+    Absent: '',
+    /**
+     * Tenant-wide: a tenant-wide role (admin / owner / policy_admin), or a
+     * Community / Community-SaaS deployment where the whole tenant is the one
+     * operator.
+     */
+    Tenant: 'tenant',
+    /**
+     * Narrowed to the rows attributed to the identity presented. A miss under
+     * this scope means "not among yours", which is NOT the same statement as
+     * "not there" — see `ReadScopeError`.
+     */
+    OwnRows: 'own-rows',
+    /**
+     * The platform RESOLVED no per-user identity and the caller holds no
+     * tenant-wide authority, so it returned zero rows by construction. Under this
+     * scope a read CANNOT have returned data, so its empty answer says nothing
+     * about what exists.
+     *
+     * "Resolved none" is wider than "presented none", and the difference is worth
+     * knowing before you go looking in the wrong place. A token that validates
+     * perfectly still resolves to no identity when its address is one the
+     * platform reserves for SHARED, non-personal identities — the whole of
+     * `@axonflow.local` and `@axonflow.internal`, plus the community and
+     * evaluator addresses. Those name a pool of callers rather than a person, and
+     * scoping a read to one would return the pool, so the platform deliberately
+     * censuses them to nothing. A per-user token minted with an address in one of
+     * those domains therefore reads exactly like no token at all. (Easy to hit:
+     * the platform's own `generate-jwt.sh` defaults to
+     * `demo-user@axonflow.local`.)
+     */
+    None: 'none',
+};
+/**
+ * The scope the platform reported on `response`.
+ *
+ * Trimmed and lower-cased, for the same reason the platform's own header
+ * helpers are: a proxy that normalises header casing or appends whitespace must
+ * not silently change the answer. The cost of getting that wrong is one-sided
+ * and quiet — a scope spelled `None` would fall to the unrecognised branch and
+ * the vacuous empty page it describes would come back as data again. An
+ * unrecognised value is otherwise unchanged, so it still round-trips.
+ */
+function readScopeOf(response) {
+    // A response with no readable header bag states no scope. That is the same
+    // answer as a pre-#2922 platform's, and it is the SAFE one: the alternative
+    // is throwing from inside a read, or — worse — inventing `none` and refusing
+    // a page that was perfectly good.
+    const headers = response?.headers;
+    if (!headers || typeof headers.get !== 'function')
+        return exports.ReadScope.Absent;
+    return (headers.get(exports.HEADER_READ_SCOPE) ?? '').trim().toLowerCase();
+}
+/**
+ * A role-scoped read whose answer was decided by the caller's identity scope
+ * rather than by the data.
+ *
+ * It exists because "no rows" and "no identity" are the same bytes on the wire.
+ * The platform distinguishes them in the `X-Axonflow-Read-Scope` header; this
+ * error is that distinction made visible, so a read that could not have
+ * succeeded reports a cause instead of a confident nothing.
+ *
+ * Two shapes, told apart by `identityMissing`:
+ *
+ * - `ReadScope.None` — no identity was RESOLVED; the read returned zero rows by
+ *   construction and says nothing about what exists. Remedy: present an
+ *   identity whose address is a real person's — see `ReadScope.None` for why a
+ *   valid token can still resolve to nothing.
+ * - `ReadScope.OwnRows` — an identity WAS resolved, and the row is not among
+ *   the ones attributed to it. That does NOT mean the row exists and belongs to
+ *   somebody else: the platform answers "not attributed to you" and "not there
+ *   at all" with the identical 404, deliberately, so that a miss cannot be used
+ *   to probe for another user's rows. This error therefore reports the scope,
+ *   not a claim about what exists.
+ *
+ * The presented token is never included in the message: it is safe to log,
+ * which is the point of putting the diagnosis in a type rather than in a string
+ * the caller assembles from the credential.
+ */
+class ReadScopeError extends Error {
+    constructor(args) {
+        const resource = args.resource ?? 'read';
+        const subject = args.identifier ? `${resource} "${args.identifier}"` : resource;
+        const identityMissing = args.scope === exports.ReadScope.None;
+        super(identityMissing
+            ? `HTTP ${args.statusCode}: ${subject}: the platform resolved no per-user identity for ` +
+                `this read (${exports.HEADER_READ_SCOPE}: ${args.scope}), so it returned zero rows by ` +
+                `construction and the empty answer says nothing about what exists. Either no ` +
+                `identity was presented — set userToken on the client, pass it to this call, or use ` +
+                `client.asUser(...) — or the one presented carries an address the platform reserves ` +
+                `for shared identities (@axonflow.local, @axonflow.internal), which resolves to ` +
+                `nobody. (platform #2922)`
+            : `HTTP ${args.statusCode}: ${subject} was not found among the rows this identity can ` +
+                `see: the platform reports ${exports.HEADER_READ_SCOPE}: ${args.scope}, so the read was ` +
+                `narrowed to the identity's own rows. It is either not attributed to this identity ` +
+                `or not there at all — the platform answers both the same way ON PURPOSE, so that a ` +
+                `miss cannot be used to probe for the existence of another user's rows, and this SDK ` +
+                `cannot tell them apart either. A tenant-wide role (admin, owner or policy_admin) ` +
+                `reads the whole tenant. (platform #2922)`);
+        this.name = 'ReadScopeError';
+        this.scope = args.scope;
+        this.statusCode = args.statusCode;
+        this.resource = resource;
+        this.identifier = args.identifier;
+        Object.setPrototypeOf(this, ReadScopeError.prototype);
+    }
+    /**
+     * Whether the read failed because no per-user identity was resolved, as
+     * opposed to one being resolved and not matching.
+     */
+    get identityMissing() {
+        return this.scope === exports.ReadScope.None;
+    }
+}
+exports.ReadScopeError = ReadScopeError;
+/**
+ * The typed refusal for a scoped read that came back with nothing, or
+ * `undefined` when the scope does not explain the result.
+ *
+ * `undefined` for `ReadScope.Tenant` (the caller could see the whole tenant and
+ * it still was not there — a genuine miss), for `ReadScope.Absent` (the
+ * platform did not state a scope; see `ReadScope` for why absent is not none),
+ * and for any scope value this build does not recognise (a newer platform's;
+ * reporting a cause we cannot actually read would be a confident wrong
+ * diagnosis).
+ */
+function readScopeErrorFor(args) {
+    if (args.scope === exports.ReadScope.None || args.scope === exports.ReadScope.OwnRows) {
+        return new ReadScopeError(args);
+    }
+    return undefined;
+}
+/**
+ * The typed refusal for a scoped read that came back EMPTY under a scope that
+ * could not have returned a row; `undefined` in every other case.
+ *
+ * One helper rather than a check at each read, because "the page is empty and
+ * the scope is none" is one rule and the reads that need it decode their body
+ * on more than one path each. A rule copied per return site is a rule that ends
+ * up applied on some of them.
+ *
+ * The emptiness guard is as load-bearing as the scope guard: a non-empty page
+ * is never turned into an error, whatever the header says. And only
+ * `ReadScope.None` refuses — an own-rows or tenant-wide read that legitimately
+ * found nothing is a real answer, and replacing it with an error would swap one
+ * wrong report for another.
+ */
+function refuseVacuousScopedPage(response, resource, rows) {
+    if (rows > 0)
+        return undefined;
+    if (readScopeOf(response) !== exports.ReadScope.None)
+        return undefined;
+    return new ReadScopeError({
+        scope: exports.ReadScope.None,
+        statusCode: response?.status ?? 0,
+        resource,
+    });
+}
+/** Whether two URLs are the same origin: scheme, host AND port. */
+function sameOrigin(a, b) {
+    return a.origin === b.origin;
+}
+/**
+ * Every credential this SDK sends, so an off-origin hop can drop ALL of them.
+ *
+ * Not just the new one. `fetch`'s own redirect follower strips `Authorization`
+ * on a cross-origin hop; the moment this SDK follows redirects by hand — which
+ * it does whenever an identity is attached — that stripping stops happening and
+ * becomes this code's job. Getting it wrong makes setting `userToken` LEAK
+ * `clientSecret` to a host the caller never named, on a client that did not
+ * leak it before: a fix for one credential that exports another.
+ *
+ * `X-Client-ID` and `X-Axonflow-Client` are not secrets, but they name the
+ * caller to whoever receives them and there is no reason for a host the caller
+ * never chose to learn it.
+ */
+const CREDENTIAL_HEADERS = [
+    'authorization',
+    exports.HEADER_USER_TOKEN.toLowerCase(),
+    'x-client-id',
+    'x-axonflow-client',
+];
+/**
+ * Drop every credential from `headers` because the request is leaving the
+ * origin they were issued for.
+ *
+ * Case-insensitive on the way in: a caller may have spelled a header
+ * differently, and two spellings of one header is one credential that survives.
+ */
+function stripCredentialsOffOrigin(headers) {
+    for (const key of Object.keys(headers)) {
+        if (CREDENTIAL_HEADERS.includes(key.toLowerCase())) {
+            delete headers[key];
+        }
+    }
+}
+/**
+ * Stamp the per-user identity on `headers`, if there is one, for a request to
+ * `target` from a client configured for `endpoint`.
+ *
+ * Called from the client's `_fetch` — the one site every request goes through —
+ * so the identity travels on every request without any method knowing about it.
+ * That is on purpose and mirrors the platform: the agent reads `X-User-Token`
+ * once, in the middleware in front of every proxied route, and the routes
+ * themselves never look at it.
+ *
+ * **The header is NOT inert on the routes that are not reads.** It is validated
+ * on every route the agent proxies: `proxyAuthMiddleware` resolves it before
+ * dispatch and answers `401 invalid user token` for a present-but-INVALID one —
+ * on `/api/v1/plans`, `/api/v1/policies`, `/api/v1/connectors`,
+ * `/api/v1/process`, `/api/v1/budgets`, `/api/v1/cost`, `/api/v1/executions`
+ * and the rest. So a stale or rotated token does not degrade to "unscoped
+ * reads"; it turns `listConnectors`, `installConnector` and policy CRUD into
+ * 401s. Fail-closed is the right direction, but it puts the value in the same
+ * rotation story as `clientSecret`.
+ *
+ * Genuinely inert only on the routes the agent SERVES ITSELF — only `proxy.go`
+ * and `mcp_identity.go` read the header at all: `/api/request`,
+ * `/api/v1/decide` (whose identity comes from the request BODY's `user_token`,
+ * which is the whole reason the read path needed a surface of its own),
+ * `/api/v1/access/evaluation`, `/api/v1/static-policies/*`,
+ * `/api/v1/circuit-breaker/*`, `/api/v1/hitl/*`, `/api/v1/mcp/check-input`,
+ * `/api/v1/mcp/check-output`, `/api/v1/register`, `/api/policy/pre-check`,
+ * `/api/audit/llm-call` and `/health`.
+ *
+ * **It is never sent anywhere but the configured endpoint.** `target` is
+ * compared against `endpoint` and the header is removed when they differ. That
+ * guard exists because of redirects: the fetch spec strips `Authorization` on a
+ * cross-origin redirect, but its list is fixed and `X-User-Token` is not on it.
+ * Measured on Node 25: the redirect target received `authorization: undefined`
+ * and `x-user-token: SENTINEL`. The client follows redirects manually while an
+ * identity is attached, re-entering this function on each hop, so the identity
+ * is dropped the moment the origin changes.
+ *
+ * The token is a CREDENTIAL. It is written to the header and nowhere else: it
+ * is never logged, never carried in an error message, and never reaches
+ * telemetry — the heartbeat uses raw `fetch`, deliberately not the wrapper this
+ * is called from.
+ */
+/**
+ * @param headers the request's header bag, MUTATED in place.
+ *
+ * A plain record rather than a `Headers` instance, deliberately: this SDK
+ * builds its requests with plain objects, and converting them here would change
+ * the shape every existing caller and test observes on `fetch`. Widening the
+ * blast radius of an identity fix to "every request's header representation"
+ * is how a small change acquires a long tail of unrelated failures.
+ */
+function applyReadIdentity(headers, target, endpoint, token) {
+    // Case-insensitively, because a caller may have spelled it differently and
+    // two spellings of one header is two identities.
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === exports.HEADER_USER_TOKEN.toLowerCase())
+            delete headers[key];
+    }
+    const trimmed = (token ?? '').trim();
+    if (!trimmed) {
+        // Never send an empty header. To the platform a present-but-empty
+        // X-User-Token is still an absent one, but sending it advertises an
+        // identity mechanism the caller is not using, and it is one refactor away
+        // from a present-but-invalid token, which is a hard 401. The delete above
+        // also makes an explicit per-call clearing actually clear.
+        return;
+    }
+    if (endpoint) {
+        try {
+            if (!sameOrigin(target, new URL(endpoint)))
+                return;
+        }
+        catch {
+            // An unparseable configured endpoint is not a licence to send the
+            // credential anyway.
+            return;
+        }
+    }
+    headers[exports.HEADER_USER_TOKEN] = trimmed;
+}
+//# sourceMappingURL=read-identity.js.map

package/dist/cjs/read-identity.js.map

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

package/dist/cjs/telemetry.d.ts

@@ -1,3 +1,77 @@
+/**
+ * Declare that a framework adapter is driving this SDK, so the next telemetry
+ * heartbeat carries `adapter:<name>` in its `features` array.
+ *
+ * A framework adapter (LangChain, LangGraph, LiteLLM, …) wrapping this SDK is
+ * indistinguishable from bare SDK use on every other telemetry dimension —
+ * same `sdk`, same `sdk_version`, same endpoint. This is the one call that
+ * makes the difference visible, and it is adoption signal only.
+ *
+ * IT ADDS NO REQUEST. The name rides the `features` array of the heartbeat
+ * that already fires; there is no second ping, no second endpoint and no new
+ * configuration surface. Calling it does not itself send anything.
+ *
+ * CALL IT BEFORE YOUR FIRST API CALL for day-one attribution. The heartbeat
+ * fires on the client's FIRST OUTBOUND REQUEST, not at construction, so
+ * anything registered before that request is on the very first ping and a name
+ * registered afterwards rides the next heartbeat.
+ *
+ * The SDK's own `AxonFlowLangGraphAdapter` registers from its constructor, so
+ * simply using it is enough — an adapter is necessarily built after the client
+ * and before any call through it.
+ *
+ * Idempotent. Repeat registrations of the same name collapse to one entry.
+ *
+ * THE NAME IS NOT VALIDATED AGAINST A LIST, DELIBERATELY. The canonical
+ * vocabulary lives on the receiver (checkpoint-service
+ * `NormalizeAdapterFeature`, which folds an unrecognised name into
+ * `adapter:unknown` at READ time while keeping the raw name on the row). An
+ * allowlist here would be a second vocabulary that drifts from the first: a
+ * name this SDK build predates would be dropped at the client instead of
+ * arriving and rendering as "someone is using an adapter we do not know
+ * about" — precisely the signal the unknown bucket exists to preserve.
+ *
+ * So the only transformations are the two the receiver also applies before
+ * matching: trim surrounding whitespace, and lowercase. What is refused is
+ * refused for a reason that is not about vocabulary: a name empty after
+ * trimming (there is nothing to declare, and `adapter:` alone is not an
+ * identifier), and a name longer than `MAX_RELAYED_VALUE_BYTES` (dropped
+ * WHOLE, never truncated). A non-string is refused the same way rather than
+ * coerced — `String(undefined)` would put the literal text `undefined` on the
+ * wire as an adapter name.
+ *
+ * Both refusals are silent: this is a telemetry declaration on a
+ * fire-and-forget path, and throwing would invite a caller to fail their own
+ * startup over an analytics detail.
+ */
+export declare function registerAdapter(name: string): void;
+/**
+ * Apply the receiver's array bounds: at most `MAX_FEATURES` entries, none over
+ * `MAX_FEATURE_BYTES` bytes.
+ *
+ * An over-long entry is DROPPED rather than truncated, which is where this
+ * deliberately differs from the receiver's own `BoundFeatures`. The receiver
+ * truncates because it is defending storage against arbitrary clients and a
+ * truncated entry harmlessly folds into its unknown bucket. Here the entry is
+ * something this process declared about itself, and a truncated adapter name
+ * is a name nothing is running.
+ */
+export declare function boundFeatures(features: string[]): string[];
+/**
+ * Render the registry as the `features` array for one ping.
+ *
+ * Sorted so the wire is deterministic — two processes that registered the same
+ * adapters in a different order produce the same array, which is what lets a
+ * test assert on the whole field, and what makes "which 32 survive" a defined
+ * answer rather than a Set-iteration accident.
+ */
+export declare function registeredFeatures(): string[];
+/** Test-only: empty the registry and return what was there, so the caller can
+ * restore it. The registry is module-global by design, so a test that
+ * registers an adapter would otherwise leak it into every later test's ping. */
+export declare function _resetAdapterRegistryForTest(): string[];
+/** Test-only: restore a registry saved by `_resetAdapterRegistryForTest`. */
+export declare function _restoreAdapterRegistryForTest(previous: string[]): void;
 export interface TelemetryPayload {
     /**
      * v1 telemetry-schema discriminator (axonflow-enterprise#2008). Always
@@ -83,6 +157,36 @@ export interface TelemetryPayload {
      * reads as "unknown", not as any particular tier.
      */
     license_tier?: string;
+    /**
+     * The BUILD the connected platform reported on its own `/health`:
+     * `community` or `enterprise`. Relayed verbatim, and it rides the SAME
+     * `/health` response the version and the tier already come from — no new
+     * request. Issue axonflow-enterprise#3660.
+     *
+     * NOT an entitlement fact, on the same terms as `license_tier` above:
+     * whoever operates the configured endpoint controls the value completely and
+     * this SDK relays it unverified.
+     *
+     * NOT derivable from anything else here either — the Community-SaaS fleet
+     * runs the ENTERPRISE build against the community-saas schema, so neither
+     * `deployment_mode` nor `license_tier` implies it.
+     *
+     * ABSENT (property omitted) means NOT LEARNED.
+     */
+    edition?: string;
+    /**
+     * The connected platform's OWN deployment mode, as it reported it on
+     * `/health` under the member name `deployment_mode`.
+     *
+     * READ THE FIELD NAMES CAREFULLY — THIS IS THE TRAP THIS CONTRACT IS MOST
+     * LIKELY TO BE GOT WRONG ON. The `/health` member is called
+     * `deployment_mode` because there the platform is describing ITSELF. On this
+     * ping, `deployment_mode` already means something else entirely: the
+     * TOPOLOGY bucket this SDK derives from the endpoint URL it was configured
+     * with. They are different dimensions, and mapping `/health`'s member onto
+     * the topology field would overwrite a value every existing dashboard reads.
+     */
+    platform_deployment_mode?: string;
 }
 /**
  * Sentinel emitted on the telemetry wire when `ORG_ID` is unset — the
@@ -165,6 +269,10 @@ export declare function sendTelemetryPing(options: {
 export interface PlatformHealthProbe {
     platformVersion: string | null;
     licenseTier: string | null;
+    /** `/health` → `edition`. */
+    edition: string | null;
+    /** `/health` → `deployment_mode`, relayed as `platform_deployment_mode`. */
+    platformDeploymentMode: string | null;
 }
 /**
  * Probe the agent's `/health` endpoint ONCE and extract every telemetry

package/dist/cjs/telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry.ts"],"names":[],"mappings":"AAmGA,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,eAAe,EAAE,cAAc,CAAC;IAChC;;;;OAIG;IACH,aAAa,EAAE,YAAY,CAAC;IAC5B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElF,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE1E;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,CAgBrF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAmF7E;AA0FD,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,OAAO,CAAC,CAiEnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,IAAI,CA8FP;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,CAAC,CAmD9B"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry.ts"],"names":[],"mappings":"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"}