@sansavision/apphelm

Official Node.js, TypeScript, browser, React Native, and iOS SDK for the Apphelm API.

npm install @sansavision/apphelm

import { Apphelm } from "@sansavision/apphelm";

const apphelm = new Apphelm({ apiKey: process.env.APPHELM_API_KEY! });
const products = await apphelm.listProducts();
const product = await apphelm.getProduct(process.env.APPHELM_PRODUCT_ID!);
const usage = await apphelm.queryMetric(product.id, "eventsIngested");

Product responses contain receipt connectivity and usage with an explicit UTC usageRange, not an estimated business-metric object. Usage results declare their source, aggregation, inclusive month-to-date bounds and provisional state.

Business metrics return BusinessMetricResult: value can be null and status explains whether the result is measured, lacks data, needs configuration, has incomplete data, or contains multiple currencies. Activation uses the product's approved default outcome; retention measures observed returning customers; reliability measures completed-probe reachability, not an uptime SLA; monthly value normalizes explicit recurring account snapshots without mixing currencies or claiming collected revenue. Each result includes its actual window, source, calculation and limitations. Do not turn missing data into zero.

Version 0.2 changes the pre-1.0 product/metric types to match the deployed API. See the migration notes.

The browser entry is consent-gated. Replay records a masked schematic of layout and interaction—not raw text, form values, or secrets—and blocks authentication, billing, payment, and admin routes by default:

import { createBrowserSdk } from "@sansavision/apphelm/browser";

const analytics = createBrowserSdk({
  key: "ahl_pub_…",
  workspaceId: "org_…",
  productId: "prd_…",
  replay: { consentPolicyVersion: "consent_v3", sampleRate: 0.25 },
});
analytics.setConsent({ analytics: true, replay: true });
analytics.track({ name: "signup_completed" });

const offer = await analytics.surveys.eligible({
  externalUserId: currentUser.id,
  triggerType: "after_first_value",
  triggerSourceId: completedImport.id,
});
if (offer) {
  renderQuestion(offer.program.question, async (answer) => {
    await analytics.surveys.respond(offer.exposureId, answer);
  });
}

Survey delivery is decided server-side from an active versioned program, current purpose consent, behavioral eligibility, and workspace-wide frequency caps. A null offer means the customer should not be interrupted.

Feature flags are fail-closed everywhere. The browser evaluates its bootstrap payload, the server evaluates remotely or polls configs locally every 10 seconds, and evaluation never consumes event entitlement:

if (analytics.isEnabled("new-checkout")) renderNewCheckout();

const flags = await apphelm.localFlags({ productId: "prd_…" });
if (await flags.isEnabled("new-checkout", customer.id)) renderNewCheckout();
flags.stop();

React Native uses the pure-JS entry (no DOM, no native modules), and iOS ships as a Swift package in packages/ios:

import { createReactNativeSdk } from "@sansavision/apphelm/react-native";

const mobile = createReactNativeSdk({ apiKey, workspaceId: "org_…", productId: "prd_…", distinctId: user.id });
mobile.screen("Pricing");
if (await mobile.isEnabled("new-checkout")) renderNewCheckout();

The browser toolbar is development-only and never automatic — call analytics.toolbar() explicitly; it no-ops on auth pages. Rich replay (replay: { fidelity: "rich" }) adds quantized colors only, never text, values, or pixels.

Server integrations can preserve external feedback with an idempotent source receipt:

await apphelm.ingestFeedback({
  productId: "prd_…", externalUserId: "customer_…", sourceType: "support",
  sourceId: "ticket_123", text: "The import is finally fast.",
  occurredAt: new Date().toISOString(), permission: "attributed_internal",
}, { idempotencyKey: "support:ticket_123:v1" });

See https://apphelm.dev/docs and the repository docs/SDK.md for API, privacy and CLI guidance.