SDKs

​

@flokitai/subscriptions-sdk (shipping)

• Platform: React Native (TypeScript). Peer dependencies: react >= 18, react-native >= 0.70.
• No native dependency: the native store call (StoreKit 2 / Play Billing / expo-iap) is injected by your app, so the SDK stays pure TypeScript.
• Context-first: call initSubscriptionsSdk() once. Every other function resolves baseUrl, appId, the user reference, and credentials from that context — you never thread them through call sites.
• Tenant-safe by design: the SDK sends only the user reference (x-user-id) and your app’s publishable key (x-app-key); your workspace/tenant is always derived server-side. The context mints and refreshes a short-lived app-session token (x-app-token) automatically.
• Anonymous-first identity: a persisted anonymous_ref (a UUID) is the user reference until you call identify(userId) after login.

​

Install

@flokitai:registry=https://npm.pkg.github.com

npm install @flokitai/subscriptions-sdk

​

Initialize once

import AsyncStorage from '@react-native-async-storage/async-storage';
import { AppState, Linking, Platform } from 'react-native';
import { initSubscriptionsSdk } from '@flokitai/subscriptions-sdk';

await initSubscriptionsSdk({
  baseUrl: process.env.EXPO_PUBLIC_GATEWAY_URL!, // your FloKit gateway URL
  appId: process.env.EXPO_PUBLIC_APP_ID!,
  appKey: process.env.EXPO_PUBLIC_APP_KEY!,      // publishable pk_... key
  storage: AsyncStorage,        // persists the queue, identity, and entitlement cache
  purchaseNative,               // your native store adapter (see below)
  openUrl: Linking.openURL,     // for the Paddle web-checkout bridge
  platform: Platform.OS,
  appState: AppState,           // enables sessions, lifecycle events, background flush
  appVersion: '1.4.2',          // optional device/app context, stamped on every event
  buildNumber: '482',
  osVersion: '17.5',
  deviceModel: 'iPhone15,3',
  locale: 'en-US',
});

​

Remote paywalls are retired

​

Purchase and entitlement

import { purchase, getEntitlement, onEntitlementChange } from '@flokitai/subscriptions-sdk';

const entitlement = await purchase({ productId: 'com.yourapp.annual', placement: 'onboarding_complete' });
if (entitlement.active) {
  // unlock premium
}

// The entitlement gate (stale-while-revalidate, 5-min TTL):
const current = await getEntitlement();

// Live updates — purchase and restore both fire this:
const unsubscribe = onEntitlementChange((e) => setIsPro(e.active));

​

Identity, handoff, and web checkout

• Identity — identify(userId) links the persisted anonymous_ref to a known user (queues a user_alias event and posts the server-side alias edge); resetIdentity() severs it on logout.
• Web→app handoff — exchangeHandoffCode({ code }) redeems the single-use flokit_code (hc_…) from a FloKit web-funnel deep link (POST /api/paywall/handoff/exchange), adopts the web anonymous_ref, and enqueues an app_activation event; expired/used codes throw HandoffCodeError.
• Attribution — submitInstallReferrer() (Android Play Install Referrer) and submitAdServicesToken() (Apple Search Ads) feed install attribution.
• Web checkout — startWebCheckout() always throws CheckoutUnavailableError with code: 'WEB_CHECKOUT_MIGRATED'. It is retained only so old call sites fail loudly. Web checkout is created from a published Flow’s paywall and checkout configuration and driven same-origin by @flokitai/checkout-js on the Flow page.
• Restore — restore() re-mints the token and fetches a fresh entitlement, bypassing the cache.
• Diagnostics — getDiagnostics() returns { sdkVersion, queueDepth, lastFlushAt, lastFlushError, droppedEvents, sessionId, tokenExpiresAt, entitlementCacheAgeMs, anonymousRef }; setDebugLogger(fn) streams queue/token/checkout debug lines. droppedEvents counts events this process gave up on (queue overflow or a non-retriable reject) — both are silent by design, so a non-zero value is the only signal that telemetry is being lost.

​

Sessions, lifecycle, and general events

• track(eventName, properties?, opts?) — general-purpose funnel events beyond the paywall. Names come from a canonical vocabulary shared verbatim with the hosted FloKit web funnel (quiz_start, quiz_answered, offer_view, lead_captured, …), so a web session and an app session describe one journey in one language. Unknown names are refused on-device — the gateway answers an unknown name with a non-retriable 400 that discards the whole batch, so failing fast keeps one typo from costing up to 49 unrelated events.
• Sessions — every event carries a session_id. A session survives a background trip shorter than 30 minutes (sessionTimeoutMs to override).
• Lifecycle events — first_open (once per install), app_open, session_start, session_end, and day_active (once per local calendar day, on that day’s first foreground — the DAU spine).
• Entitlement transitions — entitlement_granted / entitlement_revoked fire when the cached entitlement flips. These are access events, not commercial ones: convert means they paid, entitlement_granted means they can use it, and a restore or a web checkout completing produces one without the other. The first observation carries first_observation: true. entitlement_revoked is the only on-device signal that a trial lapsed or a cancellation took effect — the entitlement is revalidated on foreground (60s TTL) to catch it.
• Revenue — purchase({ priceUsdCents, currency }) stamps revenue and currency on the terminal event only, never on purchase_start, so abandoned attempts are not booked as income.

​

Migrating to v2.0

1. Entitlement reads moved. GET /api/paywall/entitlement was deleted; the SDK now reads GET /api/entitlements/current. If you call the gateway directly, re-point it.
2. Receipts moved. POST /api/paywall/receipt became POST /api/iap/receipts. The body schema is unchanged.
3. product_id → entitlement_key on Entitlement, and it is now opaque — the store product id for native purchases, the Package key for web. Do not parse it. expires_at is now string | null, and state, source_event_id, and updated_at are new.
4. startWebCheckout() always throws CheckoutUnavailableError (code: 'WEB_CHECKOUT_MIGRATED'). Delete the call site and send the user to the app’s published FloKit Flow page instead.
5. previewOfferPrice() and PricePreview are gone. So is trackPaywallEvent({ offerId }).
6. Remote paywall config is gone. getPaywall() / RemotePaywall hit an endpoint that now returns 410 — render your paywall yourself or use a Flow page.

​

Migrating to v1.2

1. Re-pin to @flokitai/subscriptions-sdk with the .npmrc scope line above.
2. Delete any host-side purchase_start / trial_start / convert / cancel emission around purchase() — the SDK owns that funnel now. Hand-rolling them is what produced double-counted purchase_start, trial_start recorded against failed purchases, and every error filed as a user cancellation.
3. Pass appState: AppState (and ideally appVersion) to initSubscriptionsSdk().
4. Expect roughly three extra events per launch (first_open once, then session_start and app_open).

​

Reliable events

​

Export surface

​

Server SDKs (roadmap)

• @flokit/node — Node.js / TypeScript (planned)
• flokit-python — Python (planned)
• flokit-go — Go (planned)