@atlasent/sdk 1.5.0 → 2.10.0

package/dist/state.cjs

@@ -0,0 +1,46 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/state.ts
+var state_exports = {};
+__export(state_exports, {
+  STATE_SOURCES: () => STATE_SOURCES
+});
+module.exports = __toCommonJS(state_exports);
+var STATE_SOURCES = [
+  "hiCoach",
+  // bettyc925/hicoach            (consumer regulation app)
+  "CalmState",
+  // atlasent/calm-state          (org-side regulation app)
+  "Echobloom",
+  // bettyc925/echobloom          (observability — emits from sessions)
+  "FutureBloom",
+  // atlasent/future-bloom-planner (planner — state inferred from plan execution)
+  "LedgersMe",
+  // bettyc925/ledgers-me         (financial outcomes inform state proxy)
+  "AtlaSent",
+  // atlasent/atlasent-api        (control-plane derived events)
+  "manual"
+  // operator-entered, no emitter
+];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  STATE_SOURCES
+});
+//# sourceMappingURL=state.cjs.map

package/dist/state.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/state.ts"],"sourcesContent":["/**\n * Canonical cross-product behavioral state contract.\n *\n * Imported as a sub-export of @atlasent/sdk:\n *\n * ```ts\n * import type { State, StateEvent, StateSource } from \"@atlasent/sdk/state\";\n * ```\n *\n * Defined in `atlasent-docs/docs/STATE_CONTRACT_PROPOSAL.md` (decisions\n * confirmed 2026-05-02). Replaces the ad-hoc per-app definitions\n * previously drifting between hicoach, calm-state, behavior-insights,\n * and ledgers-me.\n *\n * - `State` is the canonical normalized cross-product model.\n * - `StateSnapshot` is the derived latest state at a point in time.\n * - `StateEvent` is what hits the wire.\n * - `StateSource` is a closed enum; new emitters require a contract change.\n */\n\n// ──────────────────────────────────────────────────────────────────\n// 1. StateSource — closed enum, one literal per emitter\n// ──────────────────────────────────────────────────────────────────\nexport const STATE_SOURCES = [\n  \"hiCoach\",     // bettyc925/hicoach            (consumer regulation app)\n  \"CalmState\",   // atlasent/calm-state          (org-side regulation app)\n  \"Echobloom\",   // bettyc925/echobloom          (observability — emits from sessions)\n  \"FutureBloom\", // atlasent/future-bloom-planner (planner — state inferred from plan execution)\n  \"LedgersMe\",   // bettyc925/ledgers-me         (financial outcomes inform state proxy)\n  \"AtlaSent\",    // atlasent/atlasent-api        (control-plane derived events)\n  \"manual\",      // operator-entered, no emitter\n] as const;\n\nexport type StateSource = (typeof STATE_SOURCES)[number];\n\n// ──────────────────────────────────────────────────────────────────\n// 2. State — canonical normalized model\n//    Every dimension is OPTIONAL at the type level so partial\n//    observations are valid; each axis has a fixed vocabulary.\n// ──────────────────────────────────────────────────────────────────\n\n/** Canonical emotional axis. Superset of calm-state's 8 + hicoach's 5. */\nexport type EmotionalAxis =\n  | \"tense\"\n  | \"anxious\"\n  | \"overwhelmed\"\n  | \"flat\"\n  | \"frustrated\"\n  | \"uncertain\"\n  | \"tired\"\n  | \"okay\"\n  | \"open\"\n  | \"grounded\";\n\n/** Canonical body axis. Superset of calm-state's 6 + hicoach's 4. */\nexport type BodyAxis =\n  | \"tight\"\n  | \"heavy\"\n  | \"restless\"\n  | \"numb\"\n  | \"buzzing\"\n  | \"settled\"\n  | \"relaxed\"\n  | \"exhausted\";\n\nexport type ReadinessLevel = \"low\" | \"medium\" | \"high\";\n\n/**\n * Canonical normalized state. Every dimension is optional; emitters\n * record what they actually captured. Continuous axes are 0..1 normalized\n * — UI layers translate to/from their native scale (e.g. calm-state's\n * 0..10 sliders).\n */\nexport interface State {\n  emotional?: EmotionalAxis;\n  body?: BodyAxis;\n  readiness?: ReadinessLevel;\n\n  /** 0..1, 0=baseline, 1=overwhelming. */\n  intensity?: number;\n  /** 0..1. */\n  stress?: number;\n  /** 0..1. */\n  pressure?: number;\n  /** 0..1. */\n  cognitive_load?: number;\n  /** 0..1, self-rated certainty in the rating itself. */\n  confidence?: number;\n}\n\n// ──────────────────────────────────────────────────────────────────\n// 3. StateSnapshot — derived \"what is the latest state right now\"\n//    Built by consumers from the StateEvent stream. Never emitted.\n// ──────────────────────────────────────────────────────────────────\nexport interface StateSnapshot {\n  /** UUID of the user / actor. */\n  subject_id: string;\n  /** Best-known current state. */\n  state: State;\n  /** ISO-8601 timestamp of derivation. */\n  derived_at: string;\n  /** StateEvent ids this snapshot folds in. */\n  contributing_event_ids: string[];\n  /** Age of the newest contributing event, in seconds. */\n  freshness_seconds: number;\n  /** 0..1, derived from contributing-event confidences. */\n  confidence: number;\n}\n\n// ──────────────────────────────────────────────────────────────────\n// 4. StateEvent — what hits the wire\n// ──────────────────────────────────────────────────────────────────\n\nexport type StateEventKind =\n  /** A single point-in-time State capture. */\n  | \"observation\"\n  /** State before/after a regulation technique, plan step, etc. */\n  | \"transition\"\n  /** An external outcome (financial, behavioral) bearing on state. */\n  | \"outcome\";\n\n/** Envelope shared by every StateEvent variant. */\nexport interface StateEventBase {\n  /** UUID. Emitter-generated. Idempotent. */\n  event_id: string;\n  /** UUID. */\n  subject_id: string;\n  source: StateSource;\n  kind: StateEventKind;\n  /** ISO-8601. */\n  emitted_at: string;\n\n  /** 0..1. */\n  confidence: number;\n  /** Opaque; validated by behavior-insights. */\n  consent_token?: string;\n}\n\nexport interface StateObservationEvent extends StateEventBase {\n  kind: \"observation\";\n  /** Partial allowed — record what was actually captured. */\n  state: State;\n}\n\nexport interface StateTransitionEvent extends StateEventBase {\n  kind: \"transition\";\n  entry_state: State;\n  exit_state: State;\n  delta: {\n    /** 0..1, magnitude of perceived improvement. */\n    relief?: number;\n    /** -1..1. */\n    intensity_change?: number;\n  };\n  /** Emitter-side identifier; not constrained by this contract. */\n  technique?: string;\n}\n\n/**\n * Per-source `extra` shape on outcome events. Keys must be members\n * of {@link StateSource}. Sources not present in this map carry no\n * `extra` payload. Adding a new emitter adds a new key here.\n */\nexport interface SourceOutcomeExtraMap {\n  LedgersMe: {\n    transaction_id: string;\n    transaction_amount: number | null;\n    transaction_currency: string | null;\n    /** ISO-8601 — when the transaction cleared. */\n    cleared_at: string;\n  };\n  AtlaSent: {\n    permit_id: string;\n    execution_status: string;\n  };\n  Echobloom: {\n    session_id: string;\n  };\n}\n\n/** Outcome event body, shared across sources. */\ninterface StateOutcomeEventBase extends StateEventBase {\n  kind: \"outcome\";\n  outcome_description: string;\n  linking_mode: \"manual\" | \"time_window\";\n  /** Manual mode: explicit StateEvent id to link to. */\n  linked_event_id?: string;\n  /** time_window mode: ISO-8601. */\n  window_start?: string;\n  /** time_window mode: ISO-8601. */\n  window_end?: string;\n}\n\n/**\n * Outcome event. `extra` is determined by `source` via a mapped type,\n * so the two cannot disagree by construction. Sources without an\n * entry in {@link SourceOutcomeExtraMap} carry `extra?: never`.\n *\n * (An earlier draft used a self-discriminated `extra` union with its\n * own `source` field independent of the outer `source`; TypeScript\n * accepted contradictory pairs. Fixed per Codex P2 review.)\n */\nexport type StateOutcomeEvent = {\n  [S in StateSource]: StateOutcomeEventBase & {\n    source: S;\n    extra?: S extends keyof SourceOutcomeExtraMap\n      ? SourceOutcomeExtraMap[S]\n      : never;\n  };\n}[StateSource];\n\nexport type StateEvent =\n  | StateObservationEvent\n  | StateTransitionEvent\n  | StateOutcomeEvent;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBO,IAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;","names":[]}

package/dist/state.d.cts

@@ -0,0 +1,152 @@
+/**
+ * Canonical cross-product behavioral state contract.
+ *
+ * Imported as a sub-export of @atlasent/sdk:
+ *
+ * ```ts
+ * import type { State, StateEvent, StateSource } from "@atlasent/sdk/state";
+ * ```
+ *
+ * Defined in `atlasent-docs/docs/STATE_CONTRACT_PROPOSAL.md` (decisions
+ * confirmed 2026-05-02). Replaces the ad-hoc per-app definitions
+ * previously drifting between hicoach, calm-state, behavior-insights,
+ * and ledgers-me.
+ *
+ * - `State` is the canonical normalized cross-product model.
+ * - `StateSnapshot` is the derived latest state at a point in time.
+ * - `StateEvent` is what hits the wire.
+ * - `StateSource` is a closed enum; new emitters require a contract change.
+ */
+declare const STATE_SOURCES: readonly ["hiCoach", "CalmState", "Echobloom", "FutureBloom", "LedgersMe", "AtlaSent", "manual"];
+type StateSource = (typeof STATE_SOURCES)[number];
+/** Canonical emotional axis. Superset of calm-state's 8 + hicoach's 5. */
+type EmotionalAxis = "tense" | "anxious" | "overwhelmed" | "flat" | "frustrated" | "uncertain" | "tired" | "okay" | "open" | "grounded";
+/** Canonical body axis. Superset of calm-state's 6 + hicoach's 4. */
+type BodyAxis = "tight" | "heavy" | "restless" | "numb" | "buzzing" | "settled" | "relaxed" | "exhausted";
+type ReadinessLevel = "low" | "medium" | "high";
+/**
+ * Canonical normalized state. Every dimension is optional; emitters
+ * record what they actually captured. Continuous axes are 0..1 normalized
+ * — UI layers translate to/from their native scale (e.g. calm-state's
+ * 0..10 sliders).
+ */
+interface State {
+    emotional?: EmotionalAxis;
+    body?: BodyAxis;
+    readiness?: ReadinessLevel;
+    /** 0..1, 0=baseline, 1=overwhelming. */
+    intensity?: number;
+    /** 0..1. */
+    stress?: number;
+    /** 0..1. */
+    pressure?: number;
+    /** 0..1. */
+    cognitive_load?: number;
+    /** 0..1, self-rated certainty in the rating itself. */
+    confidence?: number;
+}
+interface StateSnapshot {
+    /** UUID of the user / actor. */
+    subject_id: string;
+    /** Best-known current state. */
+    state: State;
+    /** ISO-8601 timestamp of derivation. */
+    derived_at: string;
+    /** StateEvent ids this snapshot folds in. */
+    contributing_event_ids: string[];
+    /** Age of the newest contributing event, in seconds. */
+    freshness_seconds: number;
+    /** 0..1, derived from contributing-event confidences. */
+    confidence: number;
+}
+type StateEventKind = 
+/** A single point-in-time State capture. */
+"observation"
+/** State before/after a regulation technique, plan step, etc. */
+ | "transition"
+/** An external outcome (financial, behavioral) bearing on state. */
+ | "outcome";
+/** Envelope shared by every StateEvent variant. */
+interface StateEventBase {
+    /** UUID. Emitter-generated. Idempotent. */
+    event_id: string;
+    /** UUID. */
+    subject_id: string;
+    source: StateSource;
+    kind: StateEventKind;
+    /** ISO-8601. */
+    emitted_at: string;
+    /** 0..1. */
+    confidence: number;
+    /** Opaque; validated by behavior-insights. */
+    consent_token?: string;
+}
+interface StateObservationEvent extends StateEventBase {
+    kind: "observation";
+    /** Partial allowed — record what was actually captured. */
+    state: State;
+}
+interface StateTransitionEvent extends StateEventBase {
+    kind: "transition";
+    entry_state: State;
+    exit_state: State;
+    delta: {
+        /** 0..1, magnitude of perceived improvement. */
+        relief?: number;
+        /** -1..1. */
+        intensity_change?: number;
+    };
+    /** Emitter-side identifier; not constrained by this contract. */
+    technique?: string;
+}
+/**
+ * Per-source `extra` shape on outcome events. Keys must be members
+ * of {@link StateSource}. Sources not present in this map carry no
+ * `extra` payload. Adding a new emitter adds a new key here.
+ */
+interface SourceOutcomeExtraMap {
+    LedgersMe: {
+        transaction_id: string;
+        transaction_amount: number | null;
+        transaction_currency: string | null;
+        /** ISO-8601 — when the transaction cleared. */
+        cleared_at: string;
+    };
+    AtlaSent: {
+        permit_id: string;
+        execution_status: string;
+    };
+    Echobloom: {
+        session_id: string;
+    };
+}
+/** Outcome event body, shared across sources. */
+interface StateOutcomeEventBase extends StateEventBase {
+    kind: "outcome";
+    outcome_description: string;
+    linking_mode: "manual" | "time_window";
+    /** Manual mode: explicit StateEvent id to link to. */
+    linked_event_id?: string;
+    /** time_window mode: ISO-8601. */
+    window_start?: string;
+    /** time_window mode: ISO-8601. */
+    window_end?: string;
+}
+/**
+ * Outcome event. `extra` is determined by `source` via a mapped type,
+ * so the two cannot disagree by construction. Sources without an
+ * entry in {@link SourceOutcomeExtraMap} carry `extra?: never`.
+ *
+ * (An earlier draft used a self-discriminated `extra` union with its
+ * own `source` field independent of the outer `source`; TypeScript
+ * accepted contradictory pairs. Fixed per Codex P2 review.)
+ */
+type StateOutcomeEvent = {
+    [S in StateSource]: StateOutcomeEventBase & {
+        source: S;
+        extra?: S extends keyof SourceOutcomeExtraMap ? SourceOutcomeExtraMap[S] : never;
+    };
+}[StateSource];
+type StateEvent = StateObservationEvent | StateTransitionEvent | StateOutcomeEvent;
+
+export { type BodyAxis, type EmotionalAxis, type ReadinessLevel, STATE_SOURCES, type SourceOutcomeExtraMap, type State, type StateEvent, type StateEventBase, type StateEventKind, type StateObservationEvent, type StateOutcomeEvent, type StateSnapshot, type StateSource, type StateTransitionEvent };

package/dist/state.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Canonical cross-product behavioral state contract.
+ *
+ * Imported as a sub-export of @atlasent/sdk:
+ *
+ * ```ts
+ * import type { State, StateEvent, StateSource } from "@atlasent/sdk/state";
+ * ```
+ *
+ * Defined in `atlasent-docs/docs/STATE_CONTRACT_PROPOSAL.md` (decisions
+ * confirmed 2026-05-02). Replaces the ad-hoc per-app definitions
+ * previously drifting between hicoach, calm-state, behavior-insights,
+ * and ledgers-me.
+ *
+ * - `State` is the canonical normalized cross-product model.
+ * - `StateSnapshot` is the derived latest state at a point in time.
+ * - `StateEvent` is what hits the wire.
+ * - `StateSource` is a closed enum; new emitters require a contract change.
+ */
+declare const STATE_SOURCES: readonly ["hiCoach", "CalmState", "Echobloom", "FutureBloom", "LedgersMe", "AtlaSent", "manual"];
+type StateSource = (typeof STATE_SOURCES)[number];
+/** Canonical emotional axis. Superset of calm-state's 8 + hicoach's 5. */
+type EmotionalAxis = "tense" | "anxious" | "overwhelmed" | "flat" | "frustrated" | "uncertain" | "tired" | "okay" | "open" | "grounded";
+/** Canonical body axis. Superset of calm-state's 6 + hicoach's 4. */
+type BodyAxis = "tight" | "heavy" | "restless" | "numb" | "buzzing" | "settled" | "relaxed" | "exhausted";
+type ReadinessLevel = "low" | "medium" | "high";
+/**
+ * Canonical normalized state. Every dimension is optional; emitters
+ * record what they actually captured. Continuous axes are 0..1 normalized
+ * — UI layers translate to/from their native scale (e.g. calm-state's
+ * 0..10 sliders).
+ */
+interface State {
+    emotional?: EmotionalAxis;
+    body?: BodyAxis;
+    readiness?: ReadinessLevel;
+    /** 0..1, 0=baseline, 1=overwhelming. */
+    intensity?: number;
+    /** 0..1. */
+    stress?: number;
+    /** 0..1. */
+    pressure?: number;
+    /** 0..1. */
+    cognitive_load?: number;
+    /** 0..1, self-rated certainty in the rating itself. */
+    confidence?: number;
+}
+interface StateSnapshot {
+    /** UUID of the user / actor. */
+    subject_id: string;
+    /** Best-known current state. */
+    state: State;
+    /** ISO-8601 timestamp of derivation. */
+    derived_at: string;
+    /** StateEvent ids this snapshot folds in. */
+    contributing_event_ids: string[];
+    /** Age of the newest contributing event, in seconds. */
+    freshness_seconds: number;
+    /** 0..1, derived from contributing-event confidences. */
+    confidence: number;
+}
+type StateEventKind = 
+/** A single point-in-time State capture. */
+"observation"
+/** State before/after a regulation technique, plan step, etc. */
+ | "transition"
+/** An external outcome (financial, behavioral) bearing on state. */
+ | "outcome";
+/** Envelope shared by every StateEvent variant. */
+interface StateEventBase {
+    /** UUID. Emitter-generated. Idempotent. */
+    event_id: string;
+    /** UUID. */
+    subject_id: string;
+    source: StateSource;
+    kind: StateEventKind;
+    /** ISO-8601. */
+    emitted_at: string;
+    /** 0..1. */
+    confidence: number;
+    /** Opaque; validated by behavior-insights. */
+    consent_token?: string;
+}
+interface StateObservationEvent extends StateEventBase {
+    kind: "observation";
+    /** Partial allowed — record what was actually captured. */
+    state: State;
+}
+interface StateTransitionEvent extends StateEventBase {
+    kind: "transition";
+    entry_state: State;
+    exit_state: State;
+    delta: {
+        /** 0..1, magnitude of perceived improvement. */
+        relief?: number;
+        /** -1..1. */
+        intensity_change?: number;
+    };
+    /** Emitter-side identifier; not constrained by this contract. */
+    technique?: string;
+}
+/**
+ * Per-source `extra` shape on outcome events. Keys must be members
+ * of {@link StateSource}. Sources not present in this map carry no
+ * `extra` payload. Adding a new emitter adds a new key here.
+ */
+interface SourceOutcomeExtraMap {
+    LedgersMe: {
+        transaction_id: string;
+        transaction_amount: number | null;
+        transaction_currency: string | null;
+        /** ISO-8601 — when the transaction cleared. */
+        cleared_at: string;
+    };
+    AtlaSent: {
+        permit_id: string;
+        execution_status: string;
+    };
+    Echobloom: {
+        session_id: string;
+    };
+}
+/** Outcome event body, shared across sources. */
+interface StateOutcomeEventBase extends StateEventBase {
+    kind: "outcome";
+    outcome_description: string;
+    linking_mode: "manual" | "time_window";
+    /** Manual mode: explicit StateEvent id to link to. */
+    linked_event_id?: string;
+    /** time_window mode: ISO-8601. */
+    window_start?: string;
+    /** time_window mode: ISO-8601. */
+    window_end?: string;
+}
+/**
+ * Outcome event. `extra` is determined by `source` via a mapped type,
+ * so the two cannot disagree by construction. Sources without an
+ * entry in {@link SourceOutcomeExtraMap} carry `extra?: never`.
+ *
+ * (An earlier draft used a self-discriminated `extra` union with its
+ * own `source` field independent of the outer `source`; TypeScript
+ * accepted contradictory pairs. Fixed per Codex P2 review.)
+ */
+type StateOutcomeEvent = {
+    [S in StateSource]: StateOutcomeEventBase & {
+        source: S;
+        extra?: S extends keyof SourceOutcomeExtraMap ? SourceOutcomeExtraMap[S] : never;
+    };
+}[StateSource];
+type StateEvent = StateObservationEvent | StateTransitionEvent | StateOutcomeEvent;
+
+export { type BodyAxis, type EmotionalAxis, type ReadinessLevel, STATE_SOURCES, type SourceOutcomeExtraMap, type State, type StateEvent, type StateEventBase, type StateEventKind, type StateObservationEvent, type StateOutcomeEvent, type StateSnapshot, type StateSource, type StateTransitionEvent };

package/dist/state.js

@@ -0,0 +1,21 @@
+// src/state.ts
+var STATE_SOURCES = [
+  "hiCoach",
+  // bettyc925/hicoach            (consumer regulation app)
+  "CalmState",
+  // atlasent/calm-state          (org-side regulation app)
+  "Echobloom",
+  // bettyc925/echobloom          (observability — emits from sessions)
+  "FutureBloom",
+  // atlasent/future-bloom-planner (planner — state inferred from plan execution)
+  "LedgersMe",
+  // bettyc925/ledgers-me         (financial outcomes inform state proxy)
+  "AtlaSent",
+  // atlasent/atlasent-api        (control-plane derived events)
+  "manual"
+  // operator-entered, no emitter
+];
+export {
+  STATE_SOURCES
+};
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/state.ts"],"sourcesContent":["/**\n * Canonical cross-product behavioral state contract.\n *\n * Imported as a sub-export of @atlasent/sdk:\n *\n * ```ts\n * import type { State, StateEvent, StateSource } from \"@atlasent/sdk/state\";\n * ```\n *\n * Defined in `atlasent-docs/docs/STATE_CONTRACT_PROPOSAL.md` (decisions\n * confirmed 2026-05-02). Replaces the ad-hoc per-app definitions\n * previously drifting between hicoach, calm-state, behavior-insights,\n * and ledgers-me.\n *\n * - `State` is the canonical normalized cross-product model.\n * - `StateSnapshot` is the derived latest state at a point in time.\n * - `StateEvent` is what hits the wire.\n * - `StateSource` is a closed enum; new emitters require a contract change.\n */\n\n// ──────────────────────────────────────────────────────────────────\n// 1. StateSource — closed enum, one literal per emitter\n// ──────────────────────────────────────────────────────────────────\nexport const STATE_SOURCES = [\n  \"hiCoach\",     // bettyc925/hicoach            (consumer regulation app)\n  \"CalmState\",   // atlasent/calm-state          (org-side regulation app)\n  \"Echobloom\",   // bettyc925/echobloom          (observability — emits from sessions)\n  \"FutureBloom\", // atlasent/future-bloom-planner (planner — state inferred from plan execution)\n  \"LedgersMe\",   // bettyc925/ledgers-me         (financial outcomes inform state proxy)\n  \"AtlaSent\",    // atlasent/atlasent-api        (control-plane derived events)\n  \"manual\",      // operator-entered, no emitter\n] as const;\n\nexport type StateSource = (typeof STATE_SOURCES)[number];\n\n// ──────────────────────────────────────────────────────────────────\n// 2. State — canonical normalized model\n//    Every dimension is OPTIONAL at the type level so partial\n//    observations are valid; each axis has a fixed vocabulary.\n// ──────────────────────────────────────────────────────────────────\n\n/** Canonical emotional axis. Superset of calm-state's 8 + hicoach's 5. */\nexport type EmotionalAxis =\n  | \"tense\"\n  | \"anxious\"\n  | \"overwhelmed\"\n  | \"flat\"\n  | \"frustrated\"\n  | \"uncertain\"\n  | \"tired\"\n  | \"okay\"\n  | \"open\"\n  | \"grounded\";\n\n/** Canonical body axis. Superset of calm-state's 6 + hicoach's 4. */\nexport type BodyAxis =\n  | \"tight\"\n  | \"heavy\"\n  | \"restless\"\n  | \"numb\"\n  | \"buzzing\"\n  | \"settled\"\n  | \"relaxed\"\n  | \"exhausted\";\n\nexport type ReadinessLevel = \"low\" | \"medium\" | \"high\";\n\n/**\n * Canonical normalized state. Every dimension is optional; emitters\n * record what they actually captured. Continuous axes are 0..1 normalized\n * — UI layers translate to/from their native scale (e.g. calm-state's\n * 0..10 sliders).\n */\nexport interface State {\n  emotional?: EmotionalAxis;\n  body?: BodyAxis;\n  readiness?: ReadinessLevel;\n\n  /** 0..1, 0=baseline, 1=overwhelming. */\n  intensity?: number;\n  /** 0..1. */\n  stress?: number;\n  /** 0..1. */\n  pressure?: number;\n  /** 0..1. */\n  cognitive_load?: number;\n  /** 0..1, self-rated certainty in the rating itself. */\n  confidence?: number;\n}\n\n// ──────────────────────────────────────────────────────────────────\n// 3. StateSnapshot — derived \"what is the latest state right now\"\n//    Built by consumers from the StateEvent stream. Never emitted.\n// ──────────────────────────────────────────────────────────────────\nexport interface StateSnapshot {\n  /** UUID of the user / actor. */\n  subject_id: string;\n  /** Best-known current state. */\n  state: State;\n  /** ISO-8601 timestamp of derivation. */\n  derived_at: string;\n  /** StateEvent ids this snapshot folds in. */\n  contributing_event_ids: string[];\n  /** Age of the newest contributing event, in seconds. */\n  freshness_seconds: number;\n  /** 0..1, derived from contributing-event confidences. */\n  confidence: number;\n}\n\n// ──────────────────────────────────────────────────────────────────\n// 4. StateEvent — what hits the wire\n// ──────────────────────────────────────────────────────────────────\n\nexport type StateEventKind =\n  /** A single point-in-time State capture. */\n  | \"observation\"\n  /** State before/after a regulation technique, plan step, etc. */\n  | \"transition\"\n  /** An external outcome (financial, behavioral) bearing on state. */\n  | \"outcome\";\n\n/** Envelope shared by every StateEvent variant. */\nexport interface StateEventBase {\n  /** UUID. Emitter-generated. Idempotent. */\n  event_id: string;\n  /** UUID. */\n  subject_id: string;\n  source: StateSource;\n  kind: StateEventKind;\n  /** ISO-8601. */\n  emitted_at: string;\n\n  /** 0..1. */\n  confidence: number;\n  /** Opaque; validated by behavior-insights. */\n  consent_token?: string;\n}\n\nexport interface StateObservationEvent extends StateEventBase {\n  kind: \"observation\";\n  /** Partial allowed — record what was actually captured. */\n  state: State;\n}\n\nexport interface StateTransitionEvent extends StateEventBase {\n  kind: \"transition\";\n  entry_state: State;\n  exit_state: State;\n  delta: {\n    /** 0..1, magnitude of perceived improvement. */\n    relief?: number;\n    /** -1..1. */\n    intensity_change?: number;\n  };\n  /** Emitter-side identifier; not constrained by this contract. */\n  technique?: string;\n}\n\n/**\n * Per-source `extra` shape on outcome events. Keys must be members\n * of {@link StateSource}. Sources not present in this map carry no\n * `extra` payload. Adding a new emitter adds a new key here.\n */\nexport interface SourceOutcomeExtraMap {\n  LedgersMe: {\n    transaction_id: string;\n    transaction_amount: number | null;\n    transaction_currency: string | null;\n    /** ISO-8601 — when the transaction cleared. */\n    cleared_at: string;\n  };\n  AtlaSent: {\n    permit_id: string;\n    execution_status: string;\n  };\n  Echobloom: {\n    session_id: string;\n  };\n}\n\n/** Outcome event body, shared across sources. */\ninterface StateOutcomeEventBase extends StateEventBase {\n  kind: \"outcome\";\n  outcome_description: string;\n  linking_mode: \"manual\" | \"time_window\";\n  /** Manual mode: explicit StateEvent id to link to. */\n  linked_event_id?: string;\n  /** time_window mode: ISO-8601. */\n  window_start?: string;\n  /** time_window mode: ISO-8601. */\n  window_end?: string;\n}\n\n/**\n * Outcome event. `extra` is determined by `source` via a mapped type,\n * so the two cannot disagree by construction. Sources without an\n * entry in {@link SourceOutcomeExtraMap} carry `extra?: never`.\n *\n * (An earlier draft used a self-discriminated `extra` union with its\n * own `source` field independent of the outer `source`; TypeScript\n * accepted contradictory pairs. Fixed per Codex P2 review.)\n */\nexport type StateOutcomeEvent = {\n  [S in StateSource]: StateOutcomeEventBase & {\n    source: S;\n    extra?: S extends keyof SourceOutcomeExtraMap\n      ? SourceOutcomeExtraMap[S]\n      : never;\n  };\n}[StateSource];\n\nexport type StateEvent =\n  | StateObservationEvent\n  | StateTransitionEvent\n  | StateOutcomeEvent;\n"],"mappings":";AAuBO,IAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlasent/sdk",
-  "version": "1.5.0",
+  "version": "2.10.0",
   "description": "TypeScript SDK for the AtlaSent authorization API",
   "license": "Apache-2.0",
   "type": "module",
@@ -38,6 +38,16 @@
         "default": "./dist/behavior.cjs"
       }
     },
+    "./state": {
+      "import": {
+        "types": "./dist/state.d.ts",
+        "default": "./dist/state.js"
+      },
+      "require": {
+        "types": "./dist/state.d.cts",
+        "default": "./dist/state.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -47,14 +57,21 @@
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=18"
   },
+  "browserslist": [
+    "Chrome >= 103",
+    "Firefox >= 100",
+    "Safari >= 16"
+  ],
   "scripts": {
     "build": "tsup",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run typecheck && npm test && npm run build",
+    "size": "size-limit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "test:integration": "vitest run --config vitest.integration.config.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
@@ -82,18 +99,28 @@
     "access": "public"
   },
   "devDependencies": {
+    "@size-limit/esbuild": "^12.1.0",
+    "@size-limit/file": "^12.1.0",
+    "@types/express": "^5.0.6",
+    "@types/jsdom": "^28.0.1",
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.5",
     "hono": "^4.12.15",
+    "jsdom": "^29.1.0",
+    "size-limit": "^12.1.0",
     "tsup": "^8.0.2",
     "tsx": "^4.7.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },
   "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0",
     "hono": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
     "hono": {
       "optional": true
     }

package/dist/protect-BKxcoR_2.d.cts

@@ -1,159 +0,0 @@
-/**
- * Error types for the AtlaSent TypeScript SDK.
- *
- * The SDK follows a fail-closed design: a clean policy DENY is
- * returned as `EvaluateResponse.decision === "DENY"` (not thrown),
- * but any failure to confirm authorization — network, timeout,
- * bad response, invalid key, rate limit — throws an
- * {@link AtlaSentError}.
- */
-/** Discriminator for {@link AtlaSentError.code}. */
-type AtlaSentErrorCode = "invalid_api_key" | "forbidden" | "rate_limited" | "timeout" | "network" | "bad_response" | "bad_request" | "server_error";
-/** Initialization options for {@link AtlaSentError}. */
-interface AtlaSentErrorInit {
-    status?: number;
-    code?: AtlaSentErrorCode;
-    requestId?: string;
-    retryAfterMs?: number;
-    cause?: unknown;
-}
-/**
- * The only error type this SDK throws.
- *
- * Flat top-level properties mirror the convention used by Stripe,
- * Octokit, and Supabase. `cause` is forwarded to the standard
- * ES2022 `Error` constructor.
- */
-declare class AtlaSentError extends Error {
-    name: string;
-    /** HTTP status code, when the error originated from an API response. */
-    readonly status: number | undefined;
-    /** Coarse category — useful for `switch` statements at call sites. */
-    readonly code: AtlaSentErrorCode | undefined;
-    /** Correlation ID echoed from the `X-Request-ID` header the SDK sent. */
-    readonly requestId: string | undefined;
-    /** Parsed `Retry-After` header value, in milliseconds. Only set for 429. */
-    readonly retryAfterMs: number | undefined;
-    constructor(message: string, init?: AtlaSentErrorInit);
-}
-/**
- * Outcome of a denied decision.
- *
- * `"deny"` is what the current `/v1-evaluate` API returns. `"hold"`
- * and `"escalate"` are reserved for forthcoming API decisions that
- * put a permit into a pending state requiring human review; the
- * union is declared now so call sites can `switch` exhaustively
- * from the start and adopt new decisions without a breaking change.
- */
-type AtlaSentDecision = "deny" | "hold" | "escalate";
-/** Initialization options for {@link AtlaSentDeniedError}. */
-interface AtlaSentDeniedErrorInit {
-    decision: AtlaSentDecision;
-    evaluationId: string;
-    reason?: string;
-    requestId?: string;
-    auditHash?: string;
-}
-/**
- * Thrown by {@link atlasent.protect} when the policy engine refuses
- * the action, or when a permit fails end-to-end verification.
- *
- * This is the **fail-closed boundary** of the SDK: every code path
- * that short-circuits an action because authorization was not
- * confirmed raises an `AtlaSentDeniedError`. Callers cannot silently
- * proceed on a denial by forgetting to branch on a return value.
- *
- * Extends {@link AtlaSentError} so `instanceof AtlaSentError`
- * catches denials as part of the SDK's single exception family;
- * use `instanceof AtlaSentDeniedError` to distinguish a policy
- * denial from a transport/auth error.
- */
-declare class AtlaSentDeniedError extends AtlaSentError {
-    name: string;
-    /** Policy decision — `"deny"` today; `"hold"` / `"escalate"` reserved. */
-    readonly decision: AtlaSentDecision;
-    /** Opaque permit/decision id from `/v1-evaluate`. */
-    readonly evaluationId: string;
-    /** Human-readable explanation from the policy engine, if provided. */
-    readonly reason: string | undefined;
-    /** Hash-chained audit-trail entry associated with the decision. */
-    readonly auditHash: string | undefined;
-    constructor(init: AtlaSentDeniedErrorInit);
-}
-
-/**
- * `atlasent.protect(...)` — the one-call, fail-closed execution-time
- * authorization boundary.
- *
- * ```ts
- * import atlasent from "@atlasent/sdk";
- *
- * const permit = await atlasent.protect({
- *   agent: "deploy-bot",
- *   action: "deploy_to_production",
- *   context: { commit, approver },
- * });
- * // …run the action. If we got here, AtlaSent authorized it
- * // end-to-end (evaluate + verifyPermit).
- * ```
- *
- * Unlike {@link AtlaSentClient.evaluate}, `protect` never returns a
- * denied decision. On deny, it throws {@link AtlaSentDeniedError};
- * on transport / auth / server failure it throws
- * {@link AtlaSentError}. The action cannot execute unless a valid
- * {@link Permit} is returned — this is the SDK's category boundary,
- * not a helper.
- */
-/** Input to {@link protect}. Same shape as `EvaluateRequest`. */
-interface ProtectRequest {
-    agent: string;
-    action: string;
-    context?: Record<string, unknown>;
-}
-/**
- * Success return from {@link protect}. The action is authorized
- * end-to-end — evaluation allowed AND the resulting permit verified.
- */
-interface Permit {
-    /** Opaque permit / decision identifier. */
-    permitId: string;
-    /** Verification hash bound to the permit. */
-    permitHash: string;
-    /** Audit-trail entry associated with the decision (hash-chained). */
-    auditHash: string;
-    /** Human-readable reason from the policy engine. */
-    reason: string;
-    /** ISO 8601 timestamp of the verification. */
-    timestamp: string;
-}
-/** Configuration for the process-wide singleton used by {@link protect}. */
-interface ConfigureOptions {
-    /** Overrides `ATLASENT_API_KEY` env var. */
-    apiKey?: string;
-    /** Overrides the default `https://api.atlasent.io`. */
-    baseUrl?: string;
-    /** Per-request timeout in ms. */
-    timeoutMs?: number;
-    /** Inject a custom fetch (primarily for tests). */
-    fetch?: typeof fetch;
-}
-/**
- * Configure the singleton client used by {@link protect}. Optional —
- * if `ATLASENT_API_KEY` is set in the environment, `protect` works
- * without any configuration. Calling `configure` again replaces the
- * singleton; subsequent `protect` calls use the new settings.
- */
-declare function configure(options: ConfigureOptions): void;
-/**
- * Authorize an action end-to-end. On allow, returns a verified
- * {@link Permit}. On anything else, throws:
- *
- * - {@link AtlaSentDeniedError} — policy denied, or the permit
- *   failed verification. Fail-closed: if this throws, the action
- *   MUST NOT proceed.
- * - {@link AtlaSentError} — transport, timeout, auth, rate-limit,
- *   or server error. Same fail-closed contract: do not proceed.
- */
-declare function protect(request: ProtectRequest): Promise<Permit>;
-
-export { AtlaSentDeniedError as A, type ConfigureOptions as C, type Permit as P, AtlaSentError as a, type ProtectRequest as b, configure as c, type AtlaSentDecision as d, type AtlaSentDeniedErrorInit as e, type AtlaSentErrorCode as f, type AtlaSentErrorInit as g, protect as p };