Javascript SDK

BitEasy provides a thin, framework-agnostic JavaScript SDK.

Design Goals

• No state
• No storage
• No retries
• No side effects
• Fetch-only
• Works in browser, React Native, Expo, Node

Installation

npm install @biteasy/javascript-sdk
# or
pnpm add @biteasy/javascript-sdk

Creating a Client

import { createBitEasyClient } from "@biteasy/javascript-sdk";

const biteasy = createBitEasyClient({
  // optional overrides
  baseUrl: "https://api.biteasy.com/api",
  version: "v1",
  fetch, // optional custom fetch
});

Defaults:

• baseUrl: https://api.biteasy.com/api
• version: v1

API Reference

deferPreflight

Issue a referral claim code that the user can see and copy. Use this for explicit attribution only.

const res = await biteasy.deferPreflight({
  appId, // string (UUID)
  referrer, // string (slug)
});

Validation:

• referrer: lowercase alphanumeric with hyphens, 1-64 chars. Regex: ^[a-z0-9-]{1,64}$
• App must be in code attribution mode.

Returns:

• claimCode: string (e.g., “V1-ABCD1234”)
• expiresAt: number (timestamp, usually 24h)

defer

Record referral context (platform, path). Required for platform attribution.

await biteasy.defer({
  appId,
  referrer,
  platform: "ios" | "android",
  path: "/some/path", // optional
});

Validation:

• referrer: same regex as preflight.
• path: must start with / and cannot contain ://.

Notes:

• Safe to call multiple times.
• Does not generate claim codes.
• If app is in window mode, this creates a short-lived (10 min) intent.

claimAttribution

Attempt to claim attribution inside the app.

const result = await biteasy.claimAttribution({
  appId,
  installId,
  platform,
  claimCode, // optional
});

Can be called:

• automatically on first app open
• explicitly after user pastes a code

Claim Response

{
  status: "claimed" | "already_claimed" | "not_found" | "invalid_code",
  referrer: string | null,
  path: string | null,
  paywall: {
    id: string,
    source: "partner",
    partner: string,
    offerCode: {
      code: string,
      expiresAt: string, // YYYY-MM-DD
      platform: "ios" | "android",
      subscriptionDuration: "monthly" | "yearly"
    }
  } | null
}

The SDK does not throw based on status. Your app decides how to react.

Idempotency & Safety

All core endpoints are designed to be:

• retry-safe
• concurrency-safe
• deterministic

Key rules:

• Subscriber insertion is the atomic operation
• Duplicate claims for the same install return already_claimed
• Ambiguous attribution returns not_found