@stillkinetic/web-sdk 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @stillkinetic/web-sdk
+
+Behavioral tracking + threshold-triggered Stripe billing for web apps and JS desktop apps (Electron, Tauri).
+
+## Install
+
+```bash
+npm install @stillkinetic/web-sdk @stripe/stripe-js
+```
+
+`@stripe/stripe-js` is a peer dependency — install it alongside.
+
+## Usage
+
+```ts
+import { StillKinetic } from '@stillkinetic/web-sdk';
+
+const tp = new TrackPay({
+  appId: 'app_123',
+  apiKey: 'pk_app_abc',              // issued by the platform dashboard
+  apiBaseUrl: 'https://api.yourplatform.com',
+  stripePublishableKey: 'pk_live_...',
+  endUserId: currentUser.id,
+  trackedMetrics: ['stay_duration', 'scroll_length'], // pick any subset of the 5
+});
+
+tp.start();
+
+// ... later, e.g. when a "you're nearing your free usage" banner shows:
+const result = await tp.setupBilling('#card-container', {
+  amountCents: 5000,   // $50.00
+  period: 'monthly',
+});
+
+if (!result.success) {
+  console.error(result.error);
+}
+
+// On unmount / route change:
+tp.stop();
+```
+
+`setupBilling` must be called once per end user before the backend will fire any charge for them — this is the single consent screen in the whole flow. It mounts a Stripe Card Element into the DOM node matching `containerSelector`, so make sure that element exists first, e.g.:
+
+```html
+<div id="card-container"></div>
+```
+
+## Notes
+
+- All five metrics (`press_count`, `scroll_length`, `scroll_speed`, `type_speed`, `stay_duration`) are tracked passively; only the ones listed in `trackedMetrics` are enabled.
+- The backend re-validates `trackedMetrics` against the app's subscription tier and will ignore any metric the tier doesn't allow — the SDK does not enforce this client-side.
+- Charges never fire from this package directly. It only reports metrics and handles the one-time card bind; the threshold engine and all Stripe charge calls live server-side (see the `platform` app).

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+type Metric = 'press_count' | 'scroll_length' | 'scroll_speed' | 'type_speed' | 'stay_duration' | 'swipe_count' | 'pinch_zoom_count' | 'long_press_count' | 'form_submit_count' | 'tab_switch_count' | 'search_count' | 'video_play_count' | 'video_watch_duration' | 'file_download_count' | 'share_count' | 'mouse_distance';
+declare const ALL_METRICS: Metric[];
+interface TrackEvent {
+    appId: string;
+    endUserId: string;
+    pageId: string;
+    metric: Metric;
+    value: number;
+    timestamp: number;
+}
+interface StillKineticConfig {
+    /** App ID issued by the platform dashboard */
+    appId: string;
+    /** Public API key issued by the platform dashboard (safe for client use) */
+    apiKey: string;
+    /** Base URL of the platform API, e.g. https://api.yourplatform.com */
+    apiBaseUrl: string;
+    /** Stripe publishable key (safe for client use) */
+    stripePublishableKey: string;
+    /** Stable identifier for the current end user (your own user id, or an anonymous id you generate/store) */
+    endUserId: string;
+    /** Which metrics this app has opted to track. Must be a subset of what the app's subscription tier allows; the backend re-validates and will silently drop disallowed metrics. */
+    trackedMetrics: Metric[];
+    /** How often to flush the local event buffer, in ms. Default 5000. */
+    batchIntervalMs?: number;
+    /** Identifier for the current page/screen. Defaults to location.pathname on web. */
+    pageId?: string;
+}
+interface SpendingCapInput {
+    amountCents: number;
+    period: 'weekly' | 'monthly';
+}
+interface CardBindResult {
+    success: boolean;
+    error?: string;
+}
+
+/**
+ * StillKinetic web SDK.
+ *
+ * const sk = new StillKinetic({
+ *   appId: 'app_123',
+ *   apiKey: 'pk_app_...',
+ *   apiBaseUrl: 'https://api.yourplatform.com',
+ *   stripePublishableKey: 'pk_live_...',
+ *   endUserId: currentUser.id,
+ *   trackedMetrics: ['stay_duration', 'scroll_length'],
+ * });
+ * sk.start();
+ *
+ * // Later, when the host app wants to prompt the end user to bind a card
+ * // and set a spending limit (required once before any charge can fire):
+ * await sk.setupBilling('#card-container', { amountCents: 5000, period: 'monthly' });
+ */
+declare class StillKinetic {
+    private config;
+    private sender;
+    private detachFns;
+    private started;
+    constructor(config: StillKineticConfig);
+    private getPageId;
+    /** Begin tracking the metrics the host app selected in trackedMetrics. */
+    start(): void;
+    /** Stop all tracking and flush any buffered events. */
+    stop(): void;
+    /**
+     * One-time UI flow: mounts a Stripe card element into the given container,
+     * binds the end user's card, and sets their spending cap. Must succeed
+     * before the backend will fire any threshold-triggered charge for this
+     * end user. Call this once (e.g. on first threshold-nearing warning, or
+     * at signup) — never on every action.
+     */
+    setupBilling(containerSelector: string, cap: SpendingCapInput): Promise<CardBindResult>;
+}
+
+export { ALL_METRICS, type CardBindResult, type Metric, type SpendingCapInput, StillKinetic, type StillKineticConfig, type TrackEvent, StillKinetic as default };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+type Metric = 'press_count' | 'scroll_length' | 'scroll_speed' | 'type_speed' | 'stay_duration' | 'swipe_count' | 'pinch_zoom_count' | 'long_press_count' | 'form_submit_count' | 'tab_switch_count' | 'search_count' | 'video_play_count' | 'video_watch_duration' | 'file_download_count' | 'share_count' | 'mouse_distance';
+declare const ALL_METRICS: Metric[];
+interface TrackEvent {
+    appId: string;
+    endUserId: string;
+    pageId: string;
+    metric: Metric;
+    value: number;
+    timestamp: number;
+}
+interface StillKineticConfig {
+    /** App ID issued by the platform dashboard */
+    appId: string;
+    /** Public API key issued by the platform dashboard (safe for client use) */
+    apiKey: string;
+    /** Base URL of the platform API, e.g. https://api.yourplatform.com */
+    apiBaseUrl: string;
+    /** Stripe publishable key (safe for client use) */
+    stripePublishableKey: string;
+    /** Stable identifier for the current end user (your own user id, or an anonymous id you generate/store) */
+    endUserId: string;
+    /** Which metrics this app has opted to track. Must be a subset of what the app's subscription tier allows; the backend re-validates and will silently drop disallowed metrics. */
+    trackedMetrics: Metric[];
+    /** How often to flush the local event buffer, in ms. Default 5000. */
+    batchIntervalMs?: number;
+    /** Identifier for the current page/screen. Defaults to location.pathname on web. */
+    pageId?: string;
+}
+interface SpendingCapInput {
+    amountCents: number;
+    period: 'weekly' | 'monthly';
+}
+interface CardBindResult {
+    success: boolean;
+    error?: string;
+}
+
+/**
+ * StillKinetic web SDK.
+ *
+ * const sk = new StillKinetic({
+ *   appId: 'app_123',
+ *   apiKey: 'pk_app_...',
+ *   apiBaseUrl: 'https://api.yourplatform.com',
+ *   stripePublishableKey: 'pk_live_...',
+ *   endUserId: currentUser.id,
+ *   trackedMetrics: ['stay_duration', 'scroll_length'],
+ * });
+ * sk.start();
+ *
+ * // Later, when the host app wants to prompt the end user to bind a card
+ * // and set a spending limit (required once before any charge can fire):
+ * await sk.setupBilling('#card-container', { amountCents: 5000, period: 'monthly' });
+ */
+declare class StillKinetic {
+    private config;
+    private sender;
+    private detachFns;
+    private started;
+    constructor(config: StillKineticConfig);
+    private getPageId;
+    /** Begin tracking the metrics the host app selected in trackedMetrics. */
+    start(): void;
+    /** Stop all tracking and flush any buffered events. */
+    stop(): void;
+    /**
+     * One-time UI flow: mounts a Stripe card element into the given container,
+     * binds the end user's card, and sets their spending cap. Must succeed
+     * before the backend will fire any threshold-triggered charge for this
+     * end user. Call this once (e.g. on first threshold-nearing warning, or
+     * at signup) — never on every action.
+     */
+    setupBilling(containerSelector: string, cap: SpendingCapInput): Promise<CardBindResult>;
+}
+
+export { ALL_METRICS, type CardBindResult, type Metric, type SpendingCapInput, StillKinetic, type StillKineticConfig, type TrackEvent, StillKinetic as default };

package/dist/index.js

@@ -0,0 +1,389 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ALL_METRICS: () => ALL_METRICS,
+  StillKinetic: () => StillKinetic,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/transport/batchSender.ts
+var BatchSender = class {
+  constructor(config) {
+    this.config = config;
+    this.buffer = [];
+    this.timer = null;
+    this.maxBufferSize = 200;
+    this.endpoint = `${config.apiBaseUrl.replace(/\/$/, "")}/api/events`;
+  }
+  start() {
+    const intervalMs = this.config.batchIntervalMs ?? 5e3;
+    this.timer = setInterval(() => this.flush(), intervalMs);
+    if (typeof window !== "undefined") {
+      window.addEventListener("beforeunload", () => this.flush(true));
+      document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") this.flush(true);
+      });
+    }
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.flush(true);
+  }
+  enqueue(event) {
+    this.buffer.push(event);
+    if (this.buffer.length >= this.maxBufferSize) this.flush();
+  }
+  flush(useBeacon = false) {
+    if (this.buffer.length === 0) return;
+    const payload = JSON.stringify({
+      appId: this.config.appId,
+      events: this.buffer
+    });
+    const events = this.buffer;
+    this.buffer = [];
+    if (useBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
+      const blob = new Blob([payload], { type: "application/json" });
+      navigator.sendBeacon(`${this.endpoint}?apiKey=${encodeURIComponent(this.config.apiKey)}`, blob);
+      return;
+    }
+    this.sendWithRetry(payload, events, 3);
+  }
+  sendWithRetry(payload, events, retriesLeft) {
+    fetch(this.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Api-Key": this.config.apiKey
+      },
+      body: payload,
+      keepalive: true
+    }).catch(() => {
+      if (retriesLeft > 0) {
+        const delay = Math.pow(2, 3 - retriesLeft) * 1e3;
+        setTimeout(() => this.sendWithRetry(payload, events, retriesLeft - 1), delay);
+      }
+    });
+  }
+};
+
+// src/trackers/pressTracker.ts
+function attachPressTracker(config, sender, getPageId) {
+  const handler = () => {
+    sender.enqueue({
+      appId: config.appId,
+      endUserId: config.endUserId,
+      pageId: getPageId(),
+      metric: "press_count",
+      value: 1,
+      timestamp: Date.now()
+    });
+  };
+  document.addEventListener("pointerdown", handler, { passive: true });
+  return () => document.removeEventListener("pointerdown", handler);
+}
+
+// src/trackers/scrollTracker.ts
+function attachScrollTracker(config, sender, getPageId, enabledMetrics) {
+  const wantsLength = enabledMetrics.includes("scroll_length");
+  const wantsSpeed = enabledMetrics.includes("scroll_speed");
+  if (!wantsLength && !wantsSpeed) return () => {
+  };
+  let lastY = window.scrollY;
+  let lastTimestamp = performance.now();
+  let throttleHandle = null;
+  const sample = () => {
+    const currentY = window.scrollY;
+    const now = performance.now();
+    const deltaY = Math.abs(currentY - lastY);
+    const deltaT = Math.max(now - lastTimestamp, 1);
+    if (wantsLength && deltaY > 0) {
+      sender.enqueue({
+        appId: config.appId,
+        endUserId: config.endUserId,
+        pageId: getPageId(),
+        metric: "scroll_length",
+        value: deltaY,
+        timestamp: Date.now()
+      });
+    }
+    if (wantsSpeed && deltaY > 0) {
+      const pxPerMs = deltaY / deltaT;
+      sender.enqueue({
+        appId: config.appId,
+        endUserId: config.endUserId,
+        pageId: getPageId(),
+        metric: "scroll_speed",
+        value: pxPerMs,
+        timestamp: Date.now()
+      });
+    }
+    lastY = currentY;
+    lastTimestamp = now;
+    throttleHandle = null;
+  };
+  const handler = () => {
+    if (throttleHandle !== null) return;
+    throttleHandle = window.requestAnimationFrame(sample);
+  };
+  window.addEventListener("scroll", handler, { passive: true });
+  return () => window.removeEventListener("scroll", handler);
+}
+
+// src/trackers/typeTracker.ts
+function attachTypeTracker(config, sender, getPageId) {
+  const timestamps = [];
+  const windowMs = 1e4;
+  const isCharacterKey = (e) => e.key.length === 1 || e.key === "Backspace" || e.key === "Enter";
+  const isTextEntryTarget = (target) => {
+    if (!(target instanceof HTMLElement)) return false;
+    const tag = target.tagName;
+    return tag === "INPUT" || tag === "TEXTAREA" || target.isContentEditable;
+  };
+  const handler = (e) => {
+    if (!isTextEntryTarget(e.target) || !isCharacterKey(e)) return;
+    const now = Date.now();
+    timestamps.push(now);
+    while (timestamps.length > 0 && now - timestamps[0] > windowMs) {
+      timestamps.shift();
+    }
+    if (timestamps.length < 2) return;
+    const elapsedMinutes = (now - timestamps[0]) / 6e4;
+    const charsPerMinute = elapsedMinutes > 0 ? timestamps.length / elapsedMinutes : 0;
+    sender.enqueue({
+      appId: config.appId,
+      endUserId: config.endUserId,
+      pageId: getPageId(),
+      metric: "type_speed",
+      value: Math.round(charsPerMinute),
+      timestamp: now
+    });
+  };
+  document.addEventListener("keydown", handler, { passive: true });
+  return () => document.removeEventListener("keydown", handler);
+}
+
+// src/trackers/stayTracker.ts
+function attachStayTracker(config, sender, getPageId) {
+  let activeMsSinceLastReport = 0;
+  let segmentStart = document.visibilityState === "visible" ? Date.now() : null;
+  let reportHandle = null;
+  const closeSegment = () => {
+    if (segmentStart !== null) {
+      activeMsSinceLastReport += Date.now() - segmentStart;
+      segmentStart = null;
+    }
+  };
+  const openSegment = () => {
+    if (segmentStart === null) segmentStart = Date.now();
+  };
+  const report = () => {
+    closeSegment();
+    const elapsed = activeMsSinceLastReport;
+    activeMsSinceLastReport = 0;
+    if (elapsed > 0) {
+      sender.enqueue({
+        appId: config.appId,
+        endUserId: config.endUserId,
+        pageId: getPageId(),
+        metric: "stay_duration",
+        value: elapsed,
+        timestamp: Date.now()
+      });
+    }
+    openSegment();
+  };
+  const visibilityHandler = () => {
+    if (document.visibilityState === "visible") openSegment();
+    else closeSegment();
+  };
+  document.addEventListener("visibilitychange", visibilityHandler);
+  window.addEventListener("blur", closeSegment);
+  window.addEventListener("focus", openSegment);
+  reportHandle = setInterval(report, 5e3);
+  return () => {
+    closeSegment();
+    const remaining = activeMsSinceLastReport;
+    if (remaining > 0) {
+      sender.enqueue({
+        appId: config.appId,
+        endUserId: config.endUserId,
+        pageId: getPageId(),
+        metric: "stay_duration",
+        value: remaining,
+        timestamp: Date.now()
+      });
+    }
+    document.removeEventListener("visibilitychange", visibilityHandler);
+    window.removeEventListener("blur", closeSegment);
+    window.removeEventListener("focus", openSegment);
+    if (reportHandle) clearInterval(reportHandle);
+  };
+}
+
+// src/billing/CardBind.ts
+var import_stripe_js = require("@stripe/stripe-js");
+var CardBind = class {
+  constructor(config) {
+    this.config = config;
+    this.stripe = null;
+    this.cardElement = null;
+  }
+  async mount(containerSelector) {
+    this.stripe = await (0, import_stripe_js.loadStripe)(this.config.stripePublishableKey);
+    if (!this.stripe) throw new Error("StillKinetic: Stripe.js failed to load.");
+    const elements = this.stripe.elements();
+    this.cardElement = elements.create("card");
+    const container = document.querySelector(containerSelector);
+    if (!container) throw new Error(`StillKinetic: container "${containerSelector}" not found.`);
+    this.cardElement.mount(container);
+  }
+  async submit(cap) {
+    if (!this.stripe || !this.cardElement) {
+      return { success: false, error: "Card element not mounted. Call mount() first." };
+    }
+    try {
+      const setupResp = await fetch(
+        `${this.config.apiBaseUrl.replace(/\/$/, "")}/api/billing/setup-intent`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "X-Api-Key": this.config.apiKey },
+          body: JSON.stringify({
+            appId: this.config.appId,
+            endUserId: this.config.endUserId
+          })
+        }
+      );
+      if (!setupResp.ok) {
+        return { success: false, error: `Failed to initialize card setup (${setupResp.status}).` };
+      }
+      const { clientSecret } = await setupResp.json();
+      const confirmResult = await this.stripe.confirmCardSetup(clientSecret, {
+        payment_method: { card: this.cardElement }
+      });
+      if (confirmResult.error) {
+        return { success: false, error: confirmResult.error.message };
+      }
+      const paymentMethodId = confirmResult.setupIntent?.payment_method;
+      if (!paymentMethodId || typeof paymentMethodId !== "string") {
+        return { success: false, error: "No payment method returned by Stripe." };
+      }
+      const capResp = await fetch(
+        `${this.config.apiBaseUrl.replace(/\/$/, "")}/api/billing/end-user-config`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "X-Api-Key": this.config.apiKey },
+          body: JSON.stringify({
+            appId: this.config.appId,
+            endUserId: this.config.endUserId,
+            paymentMethodId,
+            spendingCapCents: cap.amountCents,
+            spendingCapPeriod: cap.period
+          })
+        }
+      );
+      if (!capResp.ok) {
+        return { success: false, error: `Card saved, but spending cap could not be set (${capResp.status}).` };
+      }
+      return { success: true };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : "Unknown error during card bind." };
+    }
+  }
+};
+
+// src/core/types.ts
+var ALL_METRICS = [
+  "press_count",
+  "scroll_length",
+  "scroll_speed",
+  "type_speed",
+  "stay_duration",
+  "swipe_count",
+  "pinch_zoom_count",
+  "long_press_count",
+  "form_submit_count",
+  "tab_switch_count",
+  "search_count",
+  "video_play_count",
+  "video_watch_duration",
+  "file_download_count",
+  "share_count",
+  "mouse_distance"
+];
+
+// src/index.ts
+var StillKinetic = class {
+  constructor(config) {
+    this.config = config;
+    this.detachFns = [];
+    this.started = false;
+    this.getPageId = () => this.config.pageId ?? (typeof window !== "undefined" ? window.location.pathname : "unknown");
+    this.sender = new BatchSender(config);
+  }
+  /** Begin tracking the metrics the host app selected in trackedMetrics. */
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.sender.start();
+    const metrics = new Set(this.config.trackedMetrics);
+    if (metrics.has("press_count")) {
+      this.detachFns.push(attachPressTracker(this.config, this.sender, this.getPageId));
+    }
+    if (metrics.has("scroll_length") || metrics.has("scroll_speed")) {
+      this.detachFns.push(
+        attachScrollTracker(this.config, this.sender, this.getPageId, this.config.trackedMetrics)
+      );
+    }
+    if (metrics.has("type_speed")) {
+      this.detachFns.push(attachTypeTracker(this.config, this.sender, this.getPageId));
+    }
+    if (metrics.has("stay_duration")) {
+      this.detachFns.push(attachStayTracker(this.config, this.sender, this.getPageId));
+    }
+  }
+  /** Stop all tracking and flush any buffered events. */
+  stop() {
+    this.detachFns.forEach((fn) => fn());
+    this.detachFns = [];
+    this.sender.stop();
+    this.started = false;
+  }
+  /**
+   * One-time UI flow: mounts a Stripe card element into the given container,
+   * binds the end user's card, and sets their spending cap. Must succeed
+   * before the backend will fire any threshold-triggered charge for this
+   * end user. Call this once (e.g. on first threshold-nearing warning, or
+   * at signup) — never on every action.
+   */
+  async setupBilling(containerSelector, cap) {
+    const bind = new CardBind(this.config);
+    await bind.mount(containerSelector);
+    return bind.submit(cap);
+  }
+};
+var index_default = StillKinetic;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ALL_METRICS,
+  StillKinetic
+});

package/dist/index.mjs

@@ -0,0 +1,361 @@
+// src/transport/batchSender.ts
+var BatchSender = class {
+  constructor(config) {
+    this.config = config;
+    this.buffer = [];
+    this.timer = null;
+    this.maxBufferSize = 200;
+    this.endpoint = `${config.apiBaseUrl.replace(/\/$/, "")}/api/events`;
+  }
+  start() {
+    const intervalMs = this.config.batchIntervalMs ?? 5e3;
+    this.timer = setInterval(() => this.flush(), intervalMs);
+    if (typeof window !== "undefined") {
+      window.addEventListener("beforeunload", () => this.flush(true));
+      document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden") this.flush(true);
+      });
+    }
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.flush(true);
+  }
+  enqueue(event) {
+    this.buffer.push(event);
+    if (this.buffer.length >= this.maxBufferSize) this.flush();
+  }
+  flush(useBeacon = false) {
+    if (this.buffer.length === 0) return;
+    const payload = JSON.stringify({
+      appId: this.config.appId,
+      events: this.buffer
+    });
+    const events = this.buffer;
+    this.buffer = [];
+    if (useBeacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
+      const blob = new Blob([payload], { type: "application/json" });
+      navigator.sendBeacon(`${this.endpoint}?apiKey=${encodeURIComponent(this.config.apiKey)}`, blob);
+      return;
+    }
+    this.sendWithRetry(payload, events, 3);
+  }
+  sendWithRetry(payload, events, retriesLeft) {
+    fetch(this.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Api-Key": this.config.apiKey
+      },
+      body: payload,
+      keepalive: true
+    }).catch(() => {
+      if (retriesLeft > 0) {
+        const delay = Math.pow(2, 3 - retriesLeft) * 1e3;
+        setTimeout(() => this.sendWithRetry(payload, events, retriesLeft - 1), delay);
+      }
+    });
+  }
+};
+
+// src/trackers/pressTracker.ts
+function attachPressTracker(config, sender, getPageId) {
+  const handler = () => {
+    sender.enqueue({
+      appId: config.appId,
+      endUserId: config.endUserId,
+      pageId: getPageId(),
+      metric: "press_count",
+      value: 1,
+      timestamp: Date.now()
+    });
+  };
+  document.addEventListener("pointerdown", handler, { passive: true });
+  return () => document.removeEventListener("pointerdown", handler);
+}
+
+// src/trackers/scrollTracker.ts
+function attachScrollTracker(config, sender, getPageId, enabledMetrics) {
+  const wantsLength = enabledMetrics.includes("scroll_length");
+  const wantsSpeed = enabledMetrics.includes("scroll_speed");
+  if (!wantsLength && !wantsSpeed) return () => {
+  };
+  let lastY = window.scrollY;
+  let lastTimestamp = performance.now();
+  let throttleHandle = null;
+  const sample = () => {
+    const currentY = window.scrollY;
+    const now = performance.now();
+    const deltaY = Math.abs(currentY - lastY);
+    const deltaT = Math.max(now - lastTimestamp, 1);
+    if (wantsLength && deltaY > 0) {
+      sender.enqueue({
+        appId: config.appId,
+        endUserId: config.endUserId,
+        pageId: getPageId(),
+        metric: "scroll_length",
+        value: deltaY,
+        timestamp: Date.now()
+      });
+    }
+    if (wantsSpeed && deltaY > 0) {
+      const pxPerMs = deltaY / deltaT;
+      sender.enqueue({
+        appId: config.appId,
+        endUserId: config.endUserId,
+        pageId: getPageId(),
+        metric: "scroll_speed",
+        value: pxPerMs,
+        timestamp: Date.now()
+      });
+    }
+    lastY = currentY;
+    lastTimestamp = now;
+    throttleHandle = null;
+  };
+  const handler = () => {
+    if (throttleHandle !== null) return;
+    throttleHandle = window.requestAnimationFrame(sample);
+  };
+  window.addEventListener("scroll", handler, { passive: true });
+  return () => window.removeEventListener("scroll", handler);
+}
+
+// src/trackers/typeTracker.ts
+function attachTypeTracker(config, sender, getPageId) {
+  const timestamps = [];
+  const windowMs = 1e4;
+  const isCharacterKey = (e) => e.key.length === 1 || e.key === "Backspace" || e.key === "Enter";
+  const isTextEntryTarget = (target) => {
+    if (!(target instanceof HTMLElement)) return false;
+    const tag = target.tagName;
+    return tag === "INPUT" || tag === "TEXTAREA" || target.isContentEditable;
+  };
+  const handler = (e) => {
+    if (!isTextEntryTarget(e.target) || !isCharacterKey(e)) return;
+    const now = Date.now();
+    timestamps.push(now);
+    while (timestamps.length > 0 && now - timestamps[0] > windowMs) {
+      timestamps.shift();
+    }
+    if (timestamps.length < 2) return;
+    const elapsedMinutes = (now - timestamps[0]) / 6e4;
+    const charsPerMinute = elapsedMinutes > 0 ? timestamps.length / elapsedMinutes : 0;
+    sender.enqueue({
+      appId: config.appId,
+      endUserId: config.endUserId,
+      pageId: getPageId(),
+      metric: "type_speed",
+      value: Math.round(charsPerMinute),
+      timestamp: now
+    });
+  };
+  document.addEventListener("keydown", handler, { passive: true });
+  return () => document.removeEventListener("keydown", handler);
+}
+
+// src/trackers/stayTracker.ts
+function attachStayTracker(config, sender, getPageId) {
+  let activeMsSinceLastReport = 0;
+  let segmentStart = document.visibilityState === "visible" ? Date.now() : null;
+  let reportHandle = null;
+  const closeSegment = () => {
+    if (segmentStart !== null) {
+      activeMsSinceLastReport += Date.now() - segmentStart;
+      segmentStart = null;
+    }
+  };
+  const openSegment = () => {
+    if (segmentStart === null) segmentStart = Date.now();
+  };
+  const report = () => {
+    closeSegment();
+    const elapsed = activeMsSinceLastReport;
+    activeMsSinceLastReport = 0;
+    if (elapsed > 0) {
+      sender.enqueue({
+        appId: config.appId,
+        endUserId: config.endUserId,
+        pageId: getPageId(),
+        metric: "stay_duration",
+        value: elapsed,
+        timestamp: Date.now()
+      });
+    }
+    openSegment();
+  };
+  const visibilityHandler = () => {
+    if (document.visibilityState === "visible") openSegment();
+    else closeSegment();
+  };
+  document.addEventListener("visibilitychange", visibilityHandler);
+  window.addEventListener("blur", closeSegment);
+  window.addEventListener("focus", openSegment);
+  reportHandle = setInterval(report, 5e3);
+  return () => {
+    closeSegment();
+    const remaining = activeMsSinceLastReport;
+    if (remaining > 0) {
+      sender.enqueue({
+        appId: config.appId,
+        endUserId: config.endUserId,
+        pageId: getPageId(),
+        metric: "stay_duration",
+        value: remaining,
+        timestamp: Date.now()
+      });
+    }
+    document.removeEventListener("visibilitychange", visibilityHandler);
+    window.removeEventListener("blur", closeSegment);
+    window.removeEventListener("focus", openSegment);
+    if (reportHandle) clearInterval(reportHandle);
+  };
+}
+
+// src/billing/CardBind.ts
+import { loadStripe } from "@stripe/stripe-js";
+var CardBind = class {
+  constructor(config) {
+    this.config = config;
+    this.stripe = null;
+    this.cardElement = null;
+  }
+  async mount(containerSelector) {
+    this.stripe = await loadStripe(this.config.stripePublishableKey);
+    if (!this.stripe) throw new Error("StillKinetic: Stripe.js failed to load.");
+    const elements = this.stripe.elements();
+    this.cardElement = elements.create("card");
+    const container = document.querySelector(containerSelector);
+    if (!container) throw new Error(`StillKinetic: container "${containerSelector}" not found.`);
+    this.cardElement.mount(container);
+  }
+  async submit(cap) {
+    if (!this.stripe || !this.cardElement) {
+      return { success: false, error: "Card element not mounted. Call mount() first." };
+    }
+    try {
+      const setupResp = await fetch(
+        `${this.config.apiBaseUrl.replace(/\/$/, "")}/api/billing/setup-intent`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "X-Api-Key": this.config.apiKey },
+          body: JSON.stringify({
+            appId: this.config.appId,
+            endUserId: this.config.endUserId
+          })
+        }
+      );
+      if (!setupResp.ok) {
+        return { success: false, error: `Failed to initialize card setup (${setupResp.status}).` };
+      }
+      const { clientSecret } = await setupResp.json();
+      const confirmResult = await this.stripe.confirmCardSetup(clientSecret, {
+        payment_method: { card: this.cardElement }
+      });
+      if (confirmResult.error) {
+        return { success: false, error: confirmResult.error.message };
+      }
+      const paymentMethodId = confirmResult.setupIntent?.payment_method;
+      if (!paymentMethodId || typeof paymentMethodId !== "string") {
+        return { success: false, error: "No payment method returned by Stripe." };
+      }
+      const capResp = await fetch(
+        `${this.config.apiBaseUrl.replace(/\/$/, "")}/api/billing/end-user-config`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "X-Api-Key": this.config.apiKey },
+          body: JSON.stringify({
+            appId: this.config.appId,
+            endUserId: this.config.endUserId,
+            paymentMethodId,
+            spendingCapCents: cap.amountCents,
+            spendingCapPeriod: cap.period
+          })
+        }
+      );
+      if (!capResp.ok) {
+        return { success: false, error: `Card saved, but spending cap could not be set (${capResp.status}).` };
+      }
+      return { success: true };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : "Unknown error during card bind." };
+    }
+  }
+};
+
+// src/core/types.ts
+var ALL_METRICS = [
+  "press_count",
+  "scroll_length",
+  "scroll_speed",
+  "type_speed",
+  "stay_duration",
+  "swipe_count",
+  "pinch_zoom_count",
+  "long_press_count",
+  "form_submit_count",
+  "tab_switch_count",
+  "search_count",
+  "video_play_count",
+  "video_watch_duration",
+  "file_download_count",
+  "share_count",
+  "mouse_distance"
+];
+
+// src/index.ts
+var StillKinetic = class {
+  constructor(config) {
+    this.config = config;
+    this.detachFns = [];
+    this.started = false;
+    this.getPageId = () => this.config.pageId ?? (typeof window !== "undefined" ? window.location.pathname : "unknown");
+    this.sender = new BatchSender(config);
+  }
+  /** Begin tracking the metrics the host app selected in trackedMetrics. */
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.sender.start();
+    const metrics = new Set(this.config.trackedMetrics);
+    if (metrics.has("press_count")) {
+      this.detachFns.push(attachPressTracker(this.config, this.sender, this.getPageId));
+    }
+    if (metrics.has("scroll_length") || metrics.has("scroll_speed")) {
+      this.detachFns.push(
+        attachScrollTracker(this.config, this.sender, this.getPageId, this.config.trackedMetrics)
+      );
+    }
+    if (metrics.has("type_speed")) {
+      this.detachFns.push(attachTypeTracker(this.config, this.sender, this.getPageId));
+    }
+    if (metrics.has("stay_duration")) {
+      this.detachFns.push(attachStayTracker(this.config, this.sender, this.getPageId));
+    }
+  }
+  /** Stop all tracking and flush any buffered events. */
+  stop() {
+    this.detachFns.forEach((fn) => fn());
+    this.detachFns = [];
+    this.sender.stop();
+    this.started = false;
+  }
+  /**
+   * One-time UI flow: mounts a Stripe card element into the given container,
+   * binds the end user's card, and sets their spending cap. Must succeed
+   * before the backend will fire any threshold-triggered charge for this
+   * end user. Call this once (e.g. on first threshold-nearing warning, or
+   * at signup) — never on every action.
+   */
+  async setupBilling(containerSelector, cap) {
+    const bind = new CardBind(this.config);
+    await bind.mount(containerSelector);
+    return bind.submit(cap);
+  }
+};
+var index_default = StillKinetic;
+export {
+  ALL_METRICS,
+  StillKinetic,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@stillkinetic/web-sdk",
+  "version": "0.1.0",
+  "description": "Selectable-metric behavioral tracking with threshold-triggered Stripe billing, for web apps.",
+  "license": "MIT",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --out-dir dist --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --out-dir dist --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@stripe/stripe-js": "^3.0.0"
+  },
+  "devDependencies": {
+    "@stripe/stripe-js": "^3.5.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}