@axonflow/sdk 9.1.0 → 9.3.0

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
@@ -43,6 +117,76 @@ export interface TelemetryPayload {
      * commitment that covers this field.
      */
     org_id: string;
+    /**
+     * Licence tier the connected platform reported on its own `/health`
+     * response — `"community"`, `"evaluation"`, `"Enterprise"`, the csaas
+     * `"Plus"` alias for EnterprisePlus, or the transient `"starting"`.
+     * Coarse adoption signal only: no licence key, no expiry, no seat count,
+     * no customer name. Issue #3619.
+     *
+     * THREE SIMILARLY-NAMED CONCEPTS LIVE NEARBY. Do not merge them:
+     *
+     * 1. `deployment_mode` (this interface) — SDK-derived TOPOLOGY:
+     *    `self_hosted | community_saas | unknown`, classified from the
+     *    endpoint URL. Says WHERE the platform runs.
+     * 2. The platform's own `DEPLOYMENT_MODE` env var — a server-side
+     *    setting deciding which schema/tables the binary uses. Never read by
+     *    this SDK and never sent on this field.
+     * 3. `license_tier` (this field) — what the platform REPORTED about its
+     *    own licensing, for adoption analytics.
+     *
+     * ITEM 3 IS NOT AN ENTITLEMENT FACT. This SDK relays whatever `/health`
+     * returned, and the receiver cannot verify the relay: whoever operates
+     * the endpoint the client was pointed at controls the value completely.
+     * It must never gate entitlement, unlock a feature, or enter any
+     * authorization or billing decision. See axonflow-enterprise#3619.
+     *
+     * A community-mode binary can run on any topology and vice versa, so
+     * neither field is derivable from the other.
+     *
+     * Sent verbatim. Casing and alias folding is the receiver's job
+     * (checkpoint-service `NormalizeLicenseTier`) and is deliberately NOT
+     * duplicated here — a client that folded locally would silently mask a
+     * tier this SDK build predates.
+     *
+     * ABSENT (property omitted) means NOT LEARNED — `/health` unreachable,
+     * non-2xx, unparseable, or carrying no `tier` key. Absent must never
+     * become a known value: emitting `"community"` for a platform we could
+     * not reach would be a false claim about a customer's deployment. The
+     * receiver preserves omission for legacy pings, so an omitted field
+     * 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
@@ -94,19 +238,6 @@ export declare function classifyDeploymentMode(url: string | null | undefined):
  * `classifyDeploymentMode`) per the v1 schema (axonflow-enterprise#2008).
  */
 export declare function classifyEndpoint(url: string | null | undefined): EndpointType;
-/**
- * Send a telemetry ping and return whether it landed.
- *
- * Returns `true` only when the POST received a 2xx response. Network
- * failures, timeouts, and non-2xx responses all return `false`. Used by
- * the heartbeat orchestrator (see `heartbeat.ts`) where the boolean
- * drives stamp-on-DELIVERY semantics: only successful POSTs advance the
- * stamp file.
- *
- * The caller is responsible for the gating decision — this function does
- * NOT consult `AXONFLOW_TELEMETRY`, the stamp file, or any rate-limit
- * state.
- */
 export declare function sendTelemetryPingNow(options: {
     mode: string;
     endpoint: string;
@@ -129,4 +260,36 @@ export declare function sendTelemetryPing(options: {
     endpoint: string;
     debug?: boolean;
 }): void;
+/**
+ * What a single `/health` fetch established. Each field is INDEPENDENT: a
+ * response carrying one but not the other yields a partially-populated
+ * result rather than discarding both. `null` means "not learned" — it never
+ * degrades to a default (see `TelemetryPayload.license_tier`).
+ */
+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
+ * dimension it carries. Returns both fields null on any failure —
+ * unreachable endpoint, non-2xx, unparseable body, or a body that stalls
+ * past the supplied budget — so
+ * telemetry degrades to omitting the fields and never fails the ping or
+ * surfaces an error to the caller.
+ *
+ * This is the SDK's only `/health` fetch on the telemetry path; the licence
+ * tier rides along on the response already being fetched for the version.
+ * Adding a second request here would double the telemetry path's blocking
+ * budget and its failure surface — do not.
+ *
+ * @param timeoutMs — derived from the shared telemetry deadline so the health
+ * probe and the checkpoint POST don't stack into a larger combined budget.
+ * See enterprise#1707.
+ */
+export declare function probePlatformHealth(endpoint: string, timeoutMs: number): Promise<PlatformHealthProbe>;
 //# sourceMappingURL=telemetry.d.ts.map

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;CAChB;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;AAmCD;;;;;;;;;;;;GAYG;AACH,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"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry.ts"],"names":[],"mappings":"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"}