usehuma 1.0.0

package/dist/index.mjs

@@ -0,0 +1,148 @@
+// src/core.ts
+function cv(arr) {
+  if (arr.length < 2) return 0;
+  const mean = arr.reduce((a, b) => a + b, 0) / arr.length;
+  if (mean === 0) return 0;
+  const variance = arr.reduce((a, b) => a + Math.pow(b - mean, 2), 0) / arr.length;
+  return Math.sqrt(variance) / mean;
+}
+function mouseFeatures(pts) {
+  if (pts.length < 5) return { speed_cv: 0, direction_changes: 0, sample_count: 0 };
+  const speeds = [];
+  const directions = [];
+  for (let i = 1; i < pts.length; i++) {
+    const dx = pts[i].x - pts[i - 1].x;
+    const dy = pts[i].y - pts[i - 1].y;
+    const dt = Math.max(pts[i].t - pts[i - 1].t, 1);
+    speeds.push(Math.sqrt(dx * dx + dy * dy) / dt);
+    directions.push(Math.atan2(dy, dx));
+  }
+  let dirChanges = 0;
+  for (let j = 1; j < directions.length; j++) {
+    if (Math.abs(directions[j] - directions[j - 1]) > 0.3) dirChanges++;
+  }
+  return { speed_cv: cv(speeds), direction_changes: dirChanges, sample_count: pts.length };
+}
+var HumaCollector = class {
+  constructor() {
+    this.signals = {
+      mouse: [],
+      keys: [],
+      scrolls: [],
+      clicks: [],
+      focusEvents: [],
+      startTime: Date.now(),
+      lastKeyTime: null,
+      lastScrollTime: null
+    };
+    this.listening = false;
+    this.onMouseMove = (e) => {
+      if (this.signals.mouse.length < 200)
+        this.signals.mouse.push({ x: e.clientX, y: e.clientY, t: Date.now() });
+    };
+    this.onKeyDown = () => {
+      const now = Date.now();
+      if (this.signals.lastKeyTime !== null && this.signals.keys.length < 100)
+        this.signals.keys.push({ interval: now - this.signals.lastKeyTime });
+      this.signals.lastKeyTime = now;
+    };
+    this.onScroll = () => {
+      const now = Date.now();
+      if (this.signals.lastScrollTime !== null && this.signals.scrolls.length < 50)
+        this.signals.scrolls.push({ interval: now - this.signals.lastScrollTime });
+      this.signals.lastScrollTime = now;
+    };
+    this.onClick = () => {
+      if (this.signals.clicks.length < 50)
+        this.signals.clicks.push({ t: Date.now() });
+    };
+    this.onFocus = () => this.signals.focusEvents.push({ type: "focus", t: Date.now() });
+    this.onBlur = () => this.signals.focusEvents.push({ type: "blur", t: Date.now() });
+  }
+  start() {
+    if (this.listening || typeof window === "undefined") return;
+    this.listening = true;
+    document.addEventListener("mousemove", this.onMouseMove, { passive: true });
+    document.addEventListener("keydown", this.onKeyDown, { passive: true });
+    document.addEventListener("scroll", this.onScroll, { passive: true });
+    document.addEventListener("click", this.onClick, { passive: true });
+    window.addEventListener("focus", this.onFocus, { passive: true });
+    window.addEventListener("blur", this.onBlur, { passive: true });
+  }
+  stop() {
+    if (!this.listening) return;
+    this.listening = false;
+    document.removeEventListener("mousemove", this.onMouseMove);
+    document.removeEventListener("keydown", this.onKeyDown);
+    document.removeEventListener("scroll", this.onScroll);
+    document.removeEventListener("click", this.onClick);
+    window.removeEventListener("focus", this.onFocus);
+    window.removeEventListener("blur", this.onBlur);
+  }
+  extract() {
+    const { keys, scrolls, clicks, focusEvents, startTime, mouse } = this.signals;
+    const m = mouseFeatures(mouse);
+    const clickIntervals = [];
+    for (let i = 1; i < clicks.length; i++)
+      clickIntervals.push(clicks[i].t - clicks[i - 1].t);
+    return {
+      time_on_page_ms: Date.now() - startTime,
+      key_interval_cv: cv(keys.map((k) => k.interval)),
+      key_count: keys.length,
+      scroll_interval_cv: cv(scrolls.map((s) => s.interval)),
+      scroll_count: scrolls.length,
+      mouse_speed_cv: m.speed_cv,
+      mouse_direction_changes: m.direction_changes,
+      mouse_sample_count: m.sample_count,
+      click_interval_cv: cv(clickIntervals),
+      click_count: clicks.length,
+      tab_switches: focusEvents.length
+    };
+  }
+  debug() {
+    return { signals: this.signals, features: this.extract() };
+  }
+};
+async function callHumaApi(opts, sessionData) {
+  var _a;
+  const endpoint = (_a = opts.endpoint) != null ? _a : "https://humaverify.com/api/v1/verify";
+  const res = await fetch(endpoint, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${opts.apiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ userId: opts.userId, sessionData })
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: "Unknown error" }));
+    throw err;
+  }
+  return res.json();
+}
+
+// src/index.ts
+var _globalCollector = null;
+function init() {
+  if (typeof window === "undefined") return;
+  if (_globalCollector) return;
+  _globalCollector = new HumaCollector();
+  _globalCollector.start();
+}
+async function verify(opts) {
+  if (!_globalCollector) init();
+  const sessionData = _globalCollector.extract();
+  return callHumaApi(opts, sessionData);
+}
+function debug() {
+  var _a;
+  return (_a = _globalCollector == null ? void 0 : _globalCollector.debug()) != null ? _a : null;
+}
+export {
+  HumaCollector,
+  callHumaApi,
+  debug,
+  init,
+  verify
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts","../src/index.ts"],"sourcesContent":["/**\n * useHUMA — Core Signal Collector\n * Invisible behavioral biometrics — no PII collected.\n */\n\nimport type { SessionData, HumaVerifyResult, HumaError, HumaOptions } from \"./types\";\n\ntype MousePoint  = { x: number; y: number; t: number };\ntype KeyEntry    = { interval: number };\ntype ScrollEntry = { interval: number };\ntype ClickEntry  = { t: number };\ntype FocusEvent  = { type: \"focus\" | \"blur\"; t: number };\n\ninterface Signals {\n  mouse:       MousePoint[];\n  keys:        KeyEntry[];\n  scrolls:     ScrollEntry[];\n  clicks:      ClickEntry[];\n  focusEvents: FocusEvent[];\n  startTime:   number;\n  lastKeyTime:    number | null;\n  lastScrollTime: number | null;\n}\n\nfunction cv(arr: number[]): number {\n  if (arr.length < 2) return 0;\n  const mean = arr.reduce((a, b) => a + b, 0) / arr.length;\n  if (mean === 0) return 0;\n  const variance = arr.reduce((a, b) => a + Math.pow(b - mean, 2), 0) / arr.length;\n  return Math.sqrt(variance) / mean;\n}\n\nfunction mouseFeatures(pts: MousePoint[]) {\n  if (pts.length < 5) return { speed_cv: 0, direction_changes: 0, sample_count: 0 };\n  const speeds: number[] = [];\n  const directions: number[] = [];\n  for (let i = 1; i < pts.length; i++) {\n    const dx = pts[i].x - pts[i - 1].x;\n    const dy = pts[i].y - pts[i - 1].y;\n    const dt = Math.max(pts[i].t - pts[i - 1].t, 1);\n    speeds.push(Math.sqrt(dx * dx + dy * dy) / dt);\n    directions.push(Math.atan2(dy, dx));\n  }\n  let dirChanges = 0;\n  for (let j = 1; j < directions.length; j++) {\n    if (Math.abs(directions[j] - directions[j - 1]) > 0.3) dirChanges++;\n  }\n  return { speed_cv: cv(speeds), direction_changes: dirChanges, sample_count: pts.length };\n}\n\nexport class HumaCollector {\n  private signals: Signals = {\n    mouse: [], keys: [], scrolls: [], clicks: [], focusEvents: [],\n    startTime: Date.now(), lastKeyTime: null, lastScrollTime: null,\n  };\n  private listening = false;\n\n  private onMouseMove = (e: MouseEvent) => {\n    if (this.signals.mouse.length < 200)\n      this.signals.mouse.push({ x: e.clientX, y: e.clientY, t: Date.now() });\n  };\n  private onKeyDown = () => {\n    const now = Date.now();\n    if (this.signals.lastKeyTime !== null && this.signals.keys.length < 100)\n      this.signals.keys.push({ interval: now - this.signals.lastKeyTime });\n    this.signals.lastKeyTime = now;\n  };\n  private onScroll = () => {\n    const now = Date.now();\n    if (this.signals.lastScrollTime !== null && this.signals.scrolls.length < 50)\n      this.signals.scrolls.push({ interval: now - this.signals.lastScrollTime });\n    this.signals.lastScrollTime = now;\n  };\n  private onClick = () => {\n    if (this.signals.clicks.length < 50)\n      this.signals.clicks.push({ t: Date.now() });\n  };\n  private onFocus = () => this.signals.focusEvents.push({ type: \"focus\", t: Date.now() });\n  private onBlur  = () => this.signals.focusEvents.push({ type: \"blur\",  t: Date.now() });\n\n  start() {\n    if (this.listening || typeof window === \"undefined\") return;\n    this.listening = true;\n    document.addEventListener(\"mousemove\", this.onMouseMove, { passive: true });\n    document.addEventListener(\"keydown\",   this.onKeyDown,   { passive: true });\n    document.addEventListener(\"scroll\",    this.onScroll,    { passive: true });\n    document.addEventListener(\"click\",     this.onClick,     { passive: true });\n    window.addEventListener(\"focus\",       this.onFocus,     { passive: true });\n    window.addEventListener(\"blur\",        this.onBlur,      { passive: true });\n  }\n\n  stop() {\n    if (!this.listening) return;\n    this.listening = false;\n    document.removeEventListener(\"mousemove\", this.onMouseMove);\n    document.removeEventListener(\"keydown\",   this.onKeyDown);\n    document.removeEventListener(\"scroll\",    this.onScroll);\n    document.removeEventListener(\"click\",     this.onClick);\n    window.removeEventListener(\"focus\",       this.onFocus);\n    window.removeEventListener(\"blur\",        this.onBlur);\n  }\n\n  extract(): SessionData {\n    const { keys, scrolls, clicks, focusEvents, startTime, mouse } = this.signals;\n    const m = mouseFeatures(mouse);\n    const clickIntervals: number[] = [];\n    for (let i = 1; i < clicks.length; i++)\n      clickIntervals.push(clicks[i].t - clicks[i - 1].t);\n    return {\n      time_on_page_ms:      Date.now() - startTime,\n      key_interval_cv:      cv(keys.map(k => k.interval)),\n      key_count:            keys.length,\n      scroll_interval_cv:   cv(scrolls.map(s => s.interval)),\n      scroll_count:         scrolls.length,\n      mouse_speed_cv:       m.speed_cv,\n      mouse_direction_changes: m.direction_changes,\n      mouse_sample_count:   m.sample_count,\n      click_interval_cv:    cv(clickIntervals),\n      click_count:          clicks.length,\n      tab_switches:         focusEvents.length,\n    };\n  }\n\n  debug(): Record<string, unknown> {\n    return { signals: this.signals as unknown, features: this.extract() };\n  }\n}\n\n/** Send extracted signals to the HUMA API and return a result. */\nexport async function callHumaApi(\n  opts: HumaOptions,\n  sessionData: SessionData\n): Promise<HumaVerifyResult> {\n  const endpoint = opts.endpoint ?? \"https://humaverify.com/api/v1/verify\";\n  const res = await fetch(endpoint, {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${opts.apiKey}`,\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({ userId: opts.userId, sessionData }),\n  });\n  if (!res.ok) {\n    const err: HumaError = await res.json().catch(() => ({ error: \"Unknown error\" }));\n    throw err;\n  }\n  return res.json() as Promise<HumaVerifyResult>;\n}\n","/**\n * useHUMA JavaScript SDK\n * Privacy-first human verification — no PII, no Cloudflare dependency.\n * https://humaverify.com\n */\n\nexport { HumaCollector, callHumaApi } from \"./core\";\nexport type {\n  SessionData,\n  HumaVerifyResult,\n  HumaError,\n  HumaOptions,\n  HumaState,\n} from \"./types\";\n\n/**\n * Vanilla JS verify — for non-React apps.\n *\n * @example\n * import { verify } from 'usehuma';\n *\n * const result = await verify({\n *   apiKey: 'huma_live_...',\n *   userId: 'user_123',\n * });\n * if (result.human) { ... }\n */\nimport { HumaCollector, callHumaApi } from \"./core\";\nimport type { HumaOptions, HumaVerifyResult } from \"./types\";\n\nlet _globalCollector: HumaCollector | null = null;\n\n/** Auto-start signal collection (call once, early in your app). */\nexport function init() {\n  if (typeof window === \"undefined\") return;\n  if (_globalCollector) return;\n  _globalCollector = new HumaCollector();\n  _globalCollector.start();\n}\n\n/**\n * Verify the current user as human using collected behavioral signals.\n * Calls init() automatically if not already started.\n */\nexport async function verify(opts: HumaOptions): Promise<HumaVerifyResult> {\n  if (!_globalCollector) init();\n  const sessionData = _globalCollector!.extract();\n  return callHumaApi(opts, sessionData);\n}\n\n/** Get raw collected signals — useful for debugging. */\nexport function debug(): Record<string, unknown> | null {\n  return _globalCollector?.debug() as Record<string, unknown> | null ?? null;\n}\n"],"mappings":"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","names":[]}

package/dist/react.d.mts

@@ -0,0 +1,157 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type HumaVerifyResult = {
+    human: boolean;
+    confidence: number;
+    threshold: number;
+    token: string;
+    pii_stored: false;
+};
+type HumaError = {
+    error: string;
+    code?: string;
+    upgrade_url?: string;
+    retry_after?: number;
+};
+type HumaOptions = {
+    /** Your HUMA API key (huma_live_...) */
+    apiKey: string;
+    /** Your internal user ID */
+    userId: string;
+    /** Override the API endpoint (default: https://humaverify.com/api/v1/verify) */
+    endpoint?: string;
+};
+type HumaState = {
+    loading: boolean;
+    result: HumaVerifyResult | null;
+    error: HumaError | null;
+    /** true = verified human, false = bot, null = not yet verified */
+    isHuman: boolean | null;
+    /** 0–100 confidence score */
+    score: number | null;
+    /** Call manually to trigger verification */
+    verify: () => Promise<HumaVerifyResult | null>;
+};
+
+/**
+ * Collect behavioral signals and verify a user as human.
+ *
+ * @example
+ * const { isHuman, score, loading, verify } = useHuma({
+ *   apiKey: 'huma_live_...',
+ *   userId: 'user_123',
+ * });
+ */
+declare function useHuma(opts: HumaOptions): HumaState;
+type HumaContextValue = HumaState & {
+    ready: boolean;
+};
+type HumaProviderProps = {
+    apiKey: string;
+    userId: string;
+    endpoint?: string;
+    /** Auto-verify on mount (default: false — call verify() manually) */
+    autoVerify?: boolean;
+    children: ReactNode;
+};
+/**
+ * Wrap your app (or a subtree) with HumaProvider so any child
+ * can call useHumaContext() without re-collecting signals.
+ *
+ * @example
+ * <HumaProvider apiKey="huma_live_..." userId={session.userId}>
+ *   <App />
+ * </HumaProvider>
+ */
+declare function HumaProvider({ apiKey, userId, endpoint, autoVerify, children }: HumaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the shared HUMA state inside a HumaProvider.
+ */
+declare function useHumaContext(): HumaContextValue;
+type HumaGateProps = {
+    apiKey: string;
+    userId: string;
+    endpoint?: string;
+    /** Content to show while verifying */
+    fallback?: ReactNode;
+    /** Content to show if verification fails (bot detected) */
+    blocked?: ReactNode;
+    /** Auto-verify on mount (default: true) */
+    autoVerify?: boolean;
+    children: ReactNode;
+};
+/**
+ * Only renders children when the user is verified as human.
+ * Shows fallback while loading, blocked if bot detected.
+ *
+ * @example
+ * <HumaGate apiKey="huma_live_..." userId={userId} fallback={<Spinner />}>
+ *   <SensitiveContent />
+ * </HumaGate>
+ */
+declare function HumaGate({ apiKey, userId, endpoint, fallback, blocked, autoVerify, children, }: HumaGateProps): react_jsx_runtime.JSX.Element;
+type SessionResult = {
+    score: number;
+    confidence: number;
+    baseline: number;
+    delta: number;
+    anomaly: boolean;
+    action: "allow" | "flag" | "block";
+    notes: string[];
+};
+type UseHumaSessionOptions = {
+    apiKey: string;
+    userId: string;
+    /** The token returned by verify() */
+    token: string;
+    /** Heartbeat interval in ms (default: 30000) */
+    intervalMs?: number;
+    /** Called when anomaly detected (score dropped or absolute bot) */
+    onAnomaly?: (result: SessionResult) => void;
+    endpoint?: string;
+};
+/**
+ * Continuously monitors an active session for bot behavior / account takeover.
+ * Start after a successful verify(). Sends heartbeats every 30s.
+ *
+ * @example
+ * const { lastResult, anomaly, stop } = useHumaSession({
+ *   apiKey: 'huma_live_...',
+ *   userId: 'user_123',
+ *   token: verifyResult.token,
+ *   onAnomaly: (r) => router.push('/logout'),
+ * });
+ */
+declare function useHumaSession(opts: UseHumaSessionOptions): {
+    lastResult: SessionResult | null;
+    anomaly: boolean;
+    stop: () => void;
+};
+type HumaVerifyButtonProps = {
+    apiKey: string;
+    userId: string;
+    endpoint?: string;
+    onVerified?: (result: HumaVerifyResult) => void;
+    onBlocked?: () => void;
+    children?: ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+};
+/**
+ * A button that triggers behavioral verification on click.
+ * Useful for form submissions, checkout flows, sensitive actions.
+ *
+ * @example
+ * <HumaVerifyButton
+ *   apiKey="huma_live_..."
+ *   userId={userId}
+ *   onVerified={(r) => console.log('Human!', r.confidence)}
+ *   onBlocked={() => console.log('Bot detected')}
+ * >
+ *   Submit
+ * </HumaVerifyButton>
+ */
+declare function HumaVerifyButton({ apiKey, userId, endpoint, onVerified, onBlocked, children, className, style, }: HumaVerifyButtonProps): react_jsx_runtime.JSX.Element;
+
+export { HumaGate, HumaProvider, HumaVerifyButton, useHuma, useHumaContext, useHumaSession };

package/dist/react.d.ts

@@ -0,0 +1,157 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+type HumaVerifyResult = {
+    human: boolean;
+    confidence: number;
+    threshold: number;
+    token: string;
+    pii_stored: false;
+};
+type HumaError = {
+    error: string;
+    code?: string;
+    upgrade_url?: string;
+    retry_after?: number;
+};
+type HumaOptions = {
+    /** Your HUMA API key (huma_live_...) */
+    apiKey: string;
+    /** Your internal user ID */
+    userId: string;
+    /** Override the API endpoint (default: https://humaverify.com/api/v1/verify) */
+    endpoint?: string;
+};
+type HumaState = {
+    loading: boolean;
+    result: HumaVerifyResult | null;
+    error: HumaError | null;
+    /** true = verified human, false = bot, null = not yet verified */
+    isHuman: boolean | null;
+    /** 0–100 confidence score */
+    score: number | null;
+    /** Call manually to trigger verification */
+    verify: () => Promise<HumaVerifyResult | null>;
+};
+
+/**
+ * Collect behavioral signals and verify a user as human.
+ *
+ * @example
+ * const { isHuman, score, loading, verify } = useHuma({
+ *   apiKey: 'huma_live_...',
+ *   userId: 'user_123',
+ * });
+ */
+declare function useHuma(opts: HumaOptions): HumaState;
+type HumaContextValue = HumaState & {
+    ready: boolean;
+};
+type HumaProviderProps = {
+    apiKey: string;
+    userId: string;
+    endpoint?: string;
+    /** Auto-verify on mount (default: false — call verify() manually) */
+    autoVerify?: boolean;
+    children: ReactNode;
+};
+/**
+ * Wrap your app (or a subtree) with HumaProvider so any child
+ * can call useHumaContext() without re-collecting signals.
+ *
+ * @example
+ * <HumaProvider apiKey="huma_live_..." userId={session.userId}>
+ *   <App />
+ * </HumaProvider>
+ */
+declare function HumaProvider({ apiKey, userId, endpoint, autoVerify, children }: HumaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the shared HUMA state inside a HumaProvider.
+ */
+declare function useHumaContext(): HumaContextValue;
+type HumaGateProps = {
+    apiKey: string;
+    userId: string;
+    endpoint?: string;
+    /** Content to show while verifying */
+    fallback?: ReactNode;
+    /** Content to show if verification fails (bot detected) */
+    blocked?: ReactNode;
+    /** Auto-verify on mount (default: true) */
+    autoVerify?: boolean;
+    children: ReactNode;
+};
+/**
+ * Only renders children when the user is verified as human.
+ * Shows fallback while loading, blocked if bot detected.
+ *
+ * @example
+ * <HumaGate apiKey="huma_live_..." userId={userId} fallback={<Spinner />}>
+ *   <SensitiveContent />
+ * </HumaGate>
+ */
+declare function HumaGate({ apiKey, userId, endpoint, fallback, blocked, autoVerify, children, }: HumaGateProps): react_jsx_runtime.JSX.Element;
+type SessionResult = {
+    score: number;
+    confidence: number;
+    baseline: number;
+    delta: number;
+    anomaly: boolean;
+    action: "allow" | "flag" | "block";
+    notes: string[];
+};
+type UseHumaSessionOptions = {
+    apiKey: string;
+    userId: string;
+    /** The token returned by verify() */
+    token: string;
+    /** Heartbeat interval in ms (default: 30000) */
+    intervalMs?: number;
+    /** Called when anomaly detected (score dropped or absolute bot) */
+    onAnomaly?: (result: SessionResult) => void;
+    endpoint?: string;
+};
+/**
+ * Continuously monitors an active session for bot behavior / account takeover.
+ * Start after a successful verify(). Sends heartbeats every 30s.
+ *
+ * @example
+ * const { lastResult, anomaly, stop } = useHumaSession({
+ *   apiKey: 'huma_live_...',
+ *   userId: 'user_123',
+ *   token: verifyResult.token,
+ *   onAnomaly: (r) => router.push('/logout'),
+ * });
+ */
+declare function useHumaSession(opts: UseHumaSessionOptions): {
+    lastResult: SessionResult | null;
+    anomaly: boolean;
+    stop: () => void;
+};
+type HumaVerifyButtonProps = {
+    apiKey: string;
+    userId: string;
+    endpoint?: string;
+    onVerified?: (result: HumaVerifyResult) => void;
+    onBlocked?: () => void;
+    children?: ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+};
+/**
+ * A button that triggers behavioral verification on click.
+ * Useful for form submissions, checkout flows, sensitive actions.
+ *
+ * @example
+ * <HumaVerifyButton
+ *   apiKey="huma_live_..."
+ *   userId={userId}
+ *   onVerified={(r) => console.log('Human!', r.confidence)}
+ *   onBlocked={() => console.log('Bot detected')}
+ * >
+ *   Submit
+ * </HumaVerifyButton>
+ */
+declare function HumaVerifyButton({ apiKey, userId, endpoint, onVerified, onBlocked, children, className, style, }: HumaVerifyButtonProps): react_jsx_runtime.JSX.Element;
+
+export { HumaGate, HumaProvider, HumaVerifyButton, useHuma, useHumaContext, useHumaSession };