sellfolk 0.1.0

package/README.md

@@ -0,0 +1,195 @@
+# sellfolk
+
+Two-line tracking SDK for [Sellfolk](https://sellfolk.com). Attribute signups, trials and paid conversions back to the seller who sent the visitor.
+
+- ✅ **2 KB minified** browser bundle (sub-1 KB gzipped)
+- ✅ **Zero dependencies** on the server SDK (Node 20+ native fetch)
+- ✅ **`keepalive: true`** — fire-and-forget event delivery, survives page unload
+- ✅ **`localStorage`** with 60-day ref expiry
+- ✅ **Never throws** — silent failure path. Your SaaS keeps running.
+- ESM + CJS + minified CDN bundle
+
+---
+
+## Install
+
+```bash
+npm  install sellfolk
+pnpm add     sellfolk
+yarn add     sellfolk
+```
+
+Or drop the CDN bundle into your HTML (see [Plain HTML](#plain-html) below).
+
+---
+
+## Quickstart — browser
+
+```ts
+import sellfolk from 'sellfolk'
+
+// One-line init. Do this at the root of your app.
+sellfolk.init('sk_live_acme_a8e92f...')
+
+// Track any event. sellfolk auto-attaches the ref_id captured from ?ref= on init.
+sellfolk.track('signup', { email: 'jane@stripe.com' })
+
+// Fire when real money moves.
+sellfolk.conversion({ amount: 199.00, email: 'jane@stripe.com' })
+```
+
+The first time a visitor lands on your site via `https://yoursite.com?ref=jane123-acme`, sellfolk captures `jane123-acme` and stores it in `localStorage` for 60 days. Every subsequent `track()` or `conversion()` call automatically attaches that ref id — even on different pages, days later, after sign-in.
+
+---
+
+## Framework recipes
+
+### Vue 3 / Nuxt
+
+```ts
+// plugins/sellfolk.client.ts
+import sellfolk from 'sellfolk'
+
+export default defineNuxtPlugin(() => {
+  sellfolk.init('sk_live_acme_a8e92f...')
+})
+
+// Then anywhere in your components:
+import sellfolk from 'sellfolk'
+sellfolk.track('signup', { email: user.value.email })
+```
+
+### React / Next.js
+
+```tsx
+// app/providers.tsx (Next 13+) or a top-level layout
+'use client'
+import { useEffect } from 'react'
+import sellfolk from 'sellfolk'
+
+export function SaaSBoostProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    sellfolk.init('sk_live_acme_a8e92f...')
+  }, [])
+  return children
+}
+
+// In a component:
+import sellfolk from 'sellfolk'
+
+function SignupForm() {
+  async function onSubmit(email: string) {
+    await fetch('/api/signup', { method: 'POST', body: JSON.stringify({ email }) })
+    sellfolk.track('signup', { email })
+  }
+  ...
+}
+```
+
+### Plain HTML
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/sellfolk/dist/sellfolk.min.js"></script>
+<script>
+  sellfolk.init('sk_live_acme_a8e92f...')
+  sellfolk.track('signup', { email: 'jane@stripe.com' })
+</script>
+```
+
+The IIFE bundle exposes a global `sellfolk`.
+
+---
+
+## Server SDK
+
+Use the server SDK from inside your billing webhook so conversions are reported the moment money moves — they don't depend on a browser session.
+
+```ts
+import { SellfolkServer } from 'sellfolk/server'
+
+const sb = new SellfolkServer(process.env.SELLFOLK_KEY!)
+
+// Inside your Stripe / Polar / Lemonsqueezy webhook handler:
+export async function handleOrderPaid(order) {
+  await sb.conversion({
+    email: order.customer_email,
+    amount: order.amount_total / 100,
+    currency: order.currency,
+  })
+}
+```
+
+The server SDK uses Node 20+'s native fetch — **zero runtime deps**.
+
+By default it never throws. If you want errors to propagate (e.g. so your queue retries):
+
+```ts
+const sb = new SellfolkServer(key, { throwOnError: true })
+```
+
+---
+
+## API reference
+
+### Browser
+
+#### `sellfolk.init(apiKey, options?)`
+
+Initialize the SDK. Captures `?ref=` from the URL if present (otherwise reads the stored ref) and prepares the network client.
+
+| Option                | Type     | Default                          | Description                                       |
+| --------------------- | -------- | -------------------------------- | ------------------------------------------------- |
+| `apiBase`             | string   | `https://api.sellfolk.com`    | Override (testing / self-hosted backends).        |
+| `forceClearOnEmptyUrl`| boolean  | `false`                          | When true and URL has no `?ref=`, wipe stored ref.|
+| `now`                 | function | `Date.now`                       | Deterministic clock (mostly for tests).           |
+
+#### `sellfolk.track(event, payload?)`
+
+Send a non-conversion event. Common values: `'signup'`, `'trial'`, `'demo'`, `'newsletter'`. Custom names are allowed and recorded as `type='custom'` with `customName=<event>`.
+
+#### `sellfolk.conversion(payload)`
+
+Fire a conversion. `amount` is required. The backend attributes this to the stored ref id.
+
+| Field      | Type     | Required | Notes                                          |
+| ---------- | -------- | -------- | ---------------------------------------------- |
+| `amount`   | number   | ✅       | In your store's currency.                      |
+| `email`    | string   | optional | Privacy-truncated server-side before display.  |
+| `currency` | string   | optional | 3-letter ISO code. Defaults to USD server-side.|
+
+#### `sellfolk.getRef()` / `sellfolk.clearRef()`
+
+Read or clear the currently-stored ref id. Useful for "Was this user referred?" UI or to drop attribution on logout.
+
+### Server
+
+#### `new SellfolkServer(apiKey, options?)`
+
+| Option         | Type      | Default                       |
+| -------------- | --------- | ----------------------------- |
+| `apiBase`      | string    | `https://api.sellfolk.com` |
+| `throwOnError` | boolean   | `false`                       |
+| `fetch`        | function  | `globalThis.fetch`            |
+
+#### `sb.track(event, payload?)` / `sb.conversion(payload)`
+
+Same shape as the browser SDK. Both are async.
+
+---
+
+## How attribution works
+
+1. A seller shares `https://sellfolk.com/r/jane123-acme`
+2. The visitor clicks. Sellfolk logs the click and 302-redirects to `https://yoursite.com?ref=jane123-acme`
+3. Your site loads. `sellfolk.init()` captures `jane123-acme` and stores it in `localStorage` for 60 days.
+4. The visitor browses, signs up, starts a trial, eventually pays.
+5. Each event (`signup`, `trial`, `conversion`) is reported with the stored ref id.
+6. Sellfolk attributes the conversion to `jane` and pays her per your listing's terms.
+
+If the visitor returns from a different referral link later, the most recent click wins. If they wipe their browser storage, the chain is broken — that's by design (and matches every other attribution tool).
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,169 @@
+"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 src_exports = {};
+__export(src_exports, {
+  DEFAULT_API_BASE: () => DEFAULT_API_BASE,
+  REF_STORAGE_KEY: () => REF_STORAGE_KEY,
+  REF_TTL_MS: () => REF_TTL_MS,
+  clearStoredRef: () => clearStoredRef,
+  default: () => src_default,
+  extractRefFromUrl: () => extractRefFromUrl,
+  readStoredRef: () => readStoredRef,
+  writeStoredRef: () => writeStoredRef
+});
+module.exports = __toCommonJS(src_exports);
+var DEFAULT_API_BASE = "https://api.sellfolk.com";
+var REF_STORAGE_KEY = "sellfolk_ref";
+var REF_TTL_MS = 60 * 24 * 60 * 60 * 1e3;
+var state = {
+  apiKey: null,
+  apiBase: DEFAULT_API_BASE,
+  refId: null,
+  now: () => Date.now()
+};
+function readStoredRef(now = Date.now) {
+  try {
+    if (typeof localStorage === "undefined") return null;
+    const raw = localStorage.getItem(REF_STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed.refId !== "string" || typeof parsed.expiresAt !== "number") return null;
+    if (now() > parsed.expiresAt) {
+      try {
+        localStorage.removeItem(REF_STORAGE_KEY);
+      } catch {
+      }
+      return null;
+    }
+    return parsed.refId;
+  } catch {
+    return null;
+  }
+}
+function writeStoredRef(refId, now = Date.now) {
+  try {
+    if (typeof localStorage === "undefined") return;
+    const stored = { refId, expiresAt: now() + REF_TTL_MS };
+    localStorage.setItem(REF_STORAGE_KEY, JSON.stringify(stored));
+  } catch {
+  }
+}
+function clearStoredRef() {
+  try {
+    if (typeof localStorage === "undefined") return;
+    localStorage.removeItem(REF_STORAGE_KEY);
+  } catch {
+  }
+}
+function extractRefFromUrl(href) {
+  try {
+    const url = href ?? (typeof window !== "undefined" ? window.location.href : "");
+    if (!url) return null;
+    const u = new URL(url);
+    const ref = u.searchParams.get("ref");
+    return ref && ref.length > 0 && ref.length <= 80 ? ref : null;
+  } catch {
+    return null;
+  }
+}
+function dispatch(path, body) {
+  if (!state.apiKey) return;
+  try {
+    fetch(`${state.apiBase}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": state.apiKey
+      },
+      body: JSON.stringify({ ...body, refId: state.refId }),
+      keepalive: true
+    }).catch(() => {
+    });
+  } catch {
+  }
+}
+var sellfolk = {
+  /**
+   * Initialize the SDK with your public API key.
+   *
+   *   sellfolk.init('sk_live_acme_a8e92f...')
+   *
+   * On first call, captures `?ref=` from the URL (if present) and stores it
+   * with a 60-day expiry. Subsequent track() / conversion() calls automatically
+   * include the stored ref_id.
+   */
+  init(apiKey, options = {}) {
+    state.apiKey = apiKey;
+    state.apiBase = options.apiBase ?? DEFAULT_API_BASE;
+    if (options.now) state.now = options.now;
+    const urlRef = extractRefFromUrl();
+    if (urlRef) {
+      writeStoredRef(urlRef, state.now);
+      state.refId = urlRef;
+    } else if (options.forceClearOnEmptyUrl) {
+      clearStoredRef();
+      state.refId = null;
+    } else {
+      state.refId = readStoredRef(state.now);
+    }
+  },
+  /**
+   * Track an event. Common values: 'signup', 'trial', 'demo', 'newsletter'.
+   * Custom event names are allowed (they go in as type='custom' with
+   * customName=<event>).
+   */
+  track(event, payload = {}) {
+    dispatch("/api/v1/track", { event, ...payload });
+  },
+  /**
+   * Fire a conversion event — call this when real money moves.
+   * Example: inside your Stripe / Polar webhook handler.
+   */
+  conversion(payload) {
+    dispatch("/api/v1/conversion", payload);
+  },
+  /**
+   * Read the current stored ref_id (e.g. for logging or attribution debugging).
+   * Returns null if no ref has been captured yet.
+   */
+  getRef() {
+    return state.refId;
+  },
+  /** Programmatically clear the stored ref (e.g. on logout). */
+  clearRef() {
+    clearStoredRef();
+    state.refId = null;
+  },
+  // ── Testing handles (not part of public API) ──────────────────────────────
+  _state: state
+};
+var src_default = sellfolk;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_API_BASE,
+  REF_STORAGE_KEY,
+  REF_TTL_MS,
+  clearStoredRef,
+  extractRefFromUrl,
+  readStoredRef,
+  writeStoredRef
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * sellfolk — Browser SDK\n *\n * Two lines to install:\n *\n *   import sellfolk from 'sellfolk'\n *   sellfolk.init('sk_live_...')\n *\n * Then call:\n *   sellfolk.track('signup', { email })\n *   sellfolk.conversion({ amount: 49.99, email })\n *\n * Design rules:\n *   • Never throws. If anything fails, we swallow it. Your SaaS keeps running.\n *   • `keepalive: true` on every fetch so requests survive page unload.\n *   • Captures `?ref=` on init() and stores it in localStorage with 60-day expiry.\n *   • All subsequent event calls auto-attach the stored ref_id.\n */\n\nexport const DEFAULT_API_BASE = 'https://api.sellfolk.com'\n\nexport const REF_STORAGE_KEY = 'sellfolk_ref'\n\nexport const REF_TTL_MS = 60 * 24 * 60 * 60 * 1000 // 60 days\n\nexport interface InitOptions {\n  /** Override the API base URL (used for testing or self-hosted backends). */\n  apiBase?: string\n  /** Provide a deterministic clock — primarily for tests. */\n  now?: () => number\n  /**\n   * If true, *replace* the stored ref with the one in the URL even when the\n   * URL has none. Useful in tests; defaults to false (URL ref always wins,\n   * but missing URL ref leaves the stored value untouched).\n   */\n  forceClearOnEmptyUrl?: boolean\n}\n\nexport interface StoredRef {\n  refId: string\n  expiresAt: number\n}\n\nexport interface TrackPayload {\n  /** Optional email — privacy-truncated server-side before display. */\n  email?: string\n  /** Any extra metadata for the event. */\n  [key: string]: unknown\n}\n\nexport interface ConversionPayload {\n  amount: number\n  email?: string\n  currency?: string\n  /** Anything else you want to attach (order_id, plan, etc.). */\n  [key: string]: unknown\n}\n\n// ── Internal state ──────────────────────────────────────────────────────────\ninterface State {\n  apiKey: string | null\n  apiBase: string\n  refId: string | null\n  now: () => number\n}\n\nconst state: State = {\n  apiKey: null,\n  apiBase: DEFAULT_API_BASE,\n  refId: null,\n  now: () => Date.now(),\n}\n\n// ── Storage helpers (defensive — localStorage may be missing/disabled) ──────\nexport function readStoredRef(now: () => number = Date.now): string | null {\n  try {\n    if (typeof localStorage === 'undefined') return null\n    const raw = localStorage.getItem(REF_STORAGE_KEY)\n    if (!raw) return null\n    const parsed = JSON.parse(raw) as StoredRef\n    if (!parsed || typeof parsed.refId !== 'string' || typeof parsed.expiresAt !== 'number') return null\n    if (now() > parsed.expiresAt) {\n      try { localStorage.removeItem(REF_STORAGE_KEY) } catch { /* ignored */ }\n      return null\n    }\n    return parsed.refId\n  } catch {\n    return null\n  }\n}\n\nexport function writeStoredRef(refId: string, now: () => number = Date.now): void {\n  try {\n    if (typeof localStorage === 'undefined') return\n    const stored: StoredRef = { refId, expiresAt: now() + REF_TTL_MS }\n    localStorage.setItem(REF_STORAGE_KEY, JSON.stringify(stored))\n  } catch {\n    // ignored\n  }\n}\n\nexport function clearStoredRef(): void {\n  try {\n    if (typeof localStorage === 'undefined') return\n    localStorage.removeItem(REF_STORAGE_KEY)\n  } catch {\n    // ignored\n  }\n}\n\n// ── URL parsing ─────────────────────────────────────────────────────────────\nexport function extractRefFromUrl(href?: string): string | null {\n  try {\n    const url = href ?? (typeof window !== 'undefined' ? window.location.href : '')\n    if (!url) return null\n    const u = new URL(url)\n    const ref = u.searchParams.get('ref')\n    return ref && ref.length > 0 && ref.length <= 80 ? ref : null\n  } catch {\n    return null\n  }\n}\n\n// ── Network ─────────────────────────────────────────────────────────────────\nfunction dispatch(path: string, body: Record<string, unknown>): void {\n  if (!state.apiKey) return\n  try {\n    // We intentionally do not await — keepalive ensures the request finishes\n    // even if the page is unloading.\n    fetch(`${state.apiBase}${path}`, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        'X-API-Key': state.apiKey,\n      },\n      body: JSON.stringify({ ...body, refId: state.refId }),\n      keepalive: true,\n    }).catch(() => { /* never throw */ })\n  } catch {\n    // Browsers without fetch (or with extreme restrictions) — silent.\n  }\n}\n\n// ── Public API ──────────────────────────────────────────────────────────────\nconst sellfolk = {\n  /**\n   * Initialize the SDK with your public API key.\n   *\n   *   sellfolk.init('sk_live_acme_a8e92f...')\n   *\n   * On first call, captures `?ref=` from the URL (if present) and stores it\n   * with a 60-day expiry. Subsequent track() / conversion() calls automatically\n   * include the stored ref_id.\n   */\n  init(apiKey: string, options: InitOptions = {}): void {\n    state.apiKey = apiKey\n    state.apiBase = options.apiBase ?? DEFAULT_API_BASE\n    if (options.now) state.now = options.now\n\n    const urlRef = extractRefFromUrl()\n    if (urlRef) {\n      writeStoredRef(urlRef, state.now)\n      state.refId = urlRef\n    } else if (options.forceClearOnEmptyUrl) {\n      clearStoredRef()\n      state.refId = null\n    } else {\n      state.refId = readStoredRef(state.now)\n    }\n  },\n\n  /**\n   * Track an event. Common values: 'signup', 'trial', 'demo', 'newsletter'.\n   * Custom event names are allowed (they go in as type='custom' with\n   * customName=<event>).\n   */\n  track(event: string, payload: TrackPayload = {}): void {\n    dispatch('/api/v1/track', { event, ...payload })\n  },\n\n  /**\n   * Fire a conversion event — call this when real money moves.\n   * Example: inside your Stripe / Polar webhook handler.\n   */\n  conversion(payload: ConversionPayload): void {\n    dispatch('/api/v1/conversion', payload)\n  },\n\n  /**\n   * Read the current stored ref_id (e.g. for logging or attribution debugging).\n   * Returns null if no ref has been captured yet.\n   */\n  getRef(): string | null {\n    return state.refId\n  },\n\n  /** Programmatically clear the stored ref (e.g. on logout). */\n  clearRef(): void {\n    clearStoredRef()\n    state.refId = null\n  },\n\n  // ── Testing handles (not part of public API) ──────────────────────────────\n  _state: state,\n}\n\nexport default sellfolk\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,93 @@
+/**
+ * sellfolk — Browser SDK
+ *
+ * Two lines to install:
+ *
+ *   import sellfolk from 'sellfolk'
+ *   sellfolk.init('sk_live_...')
+ *
+ * Then call:
+ *   sellfolk.track('signup', { email })
+ *   sellfolk.conversion({ amount: 49.99, email })
+ *
+ * Design rules:
+ *   • Never throws. If anything fails, we swallow it. Your SaaS keeps running.
+ *   • `keepalive: true` on every fetch so requests survive page unload.
+ *   • Captures `?ref=` on init() and stores it in localStorage with 60-day expiry.
+ *   • All subsequent event calls auto-attach the stored ref_id.
+ */
+declare const DEFAULT_API_BASE = "https://api.sellfolk.com";
+declare const REF_STORAGE_KEY = "sellfolk_ref";
+declare const REF_TTL_MS: number;
+interface InitOptions {
+    /** Override the API base URL (used for testing or self-hosted backends). */
+    apiBase?: string;
+    /** Provide a deterministic clock — primarily for tests. */
+    now?: () => number;
+    /**
+     * If true, *replace* the stored ref with the one in the URL even when the
+     * URL has none. Useful in tests; defaults to false (URL ref always wins,
+     * but missing URL ref leaves the stored value untouched).
+     */
+    forceClearOnEmptyUrl?: boolean;
+}
+interface StoredRef {
+    refId: string;
+    expiresAt: number;
+}
+interface TrackPayload {
+    /** Optional email — privacy-truncated server-side before display. */
+    email?: string;
+    /** Any extra metadata for the event. */
+    [key: string]: unknown;
+}
+interface ConversionPayload {
+    amount: number;
+    email?: string;
+    currency?: string;
+    /** Anything else you want to attach (order_id, plan, etc.). */
+    [key: string]: unknown;
+}
+interface State {
+    apiKey: string | null;
+    apiBase: string;
+    refId: string | null;
+    now: () => number;
+}
+declare function readStoredRef(now?: () => number): string | null;
+declare function writeStoredRef(refId: string, now?: () => number): void;
+declare function clearStoredRef(): void;
+declare function extractRefFromUrl(href?: string): string | null;
+declare const sellfolk: {
+    /**
+     * Initialize the SDK with your public API key.
+     *
+     *   sellfolk.init('sk_live_acme_a8e92f...')
+     *
+     * On first call, captures `?ref=` from the URL (if present) and stores it
+     * with a 60-day expiry. Subsequent track() / conversion() calls automatically
+     * include the stored ref_id.
+     */
+    init(apiKey: string, options?: InitOptions): void;
+    /**
+     * Track an event. Common values: 'signup', 'trial', 'demo', 'newsletter'.
+     * Custom event names are allowed (they go in as type='custom' with
+     * customName=<event>).
+     */
+    track(event: string, payload?: TrackPayload): void;
+    /**
+     * Fire a conversion event — call this when real money moves.
+     * Example: inside your Stripe / Polar webhook handler.
+     */
+    conversion(payload: ConversionPayload): void;
+    /**
+     * Read the current stored ref_id (e.g. for logging or attribution debugging).
+     * Returns null if no ref has been captured yet.
+     */
+    getRef(): string | null;
+    /** Programmatically clear the stored ref (e.g. on logout). */
+    clearRef(): void;
+    _state: State;
+};
+
+export { type ConversionPayload, DEFAULT_API_BASE, type InitOptions, REF_STORAGE_KEY, REF_TTL_MS, type StoredRef, type TrackPayload, clearStoredRef, sellfolk as default, extractRefFromUrl, readStoredRef, writeStoredRef };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * sellfolk — Browser SDK
+ *
+ * Two lines to install:
+ *
+ *   import sellfolk from 'sellfolk'
+ *   sellfolk.init('sk_live_...')
+ *
+ * Then call:
+ *   sellfolk.track('signup', { email })
+ *   sellfolk.conversion({ amount: 49.99, email })
+ *
+ * Design rules:
+ *   • Never throws. If anything fails, we swallow it. Your SaaS keeps running.
+ *   • `keepalive: true` on every fetch so requests survive page unload.
+ *   • Captures `?ref=` on init() and stores it in localStorage with 60-day expiry.
+ *   • All subsequent event calls auto-attach the stored ref_id.
+ */
+declare const DEFAULT_API_BASE = "https://api.sellfolk.com";
+declare const REF_STORAGE_KEY = "sellfolk_ref";
+declare const REF_TTL_MS: number;
+interface InitOptions {
+    /** Override the API base URL (used for testing or self-hosted backends). */
+    apiBase?: string;
+    /** Provide a deterministic clock — primarily for tests. */
+    now?: () => number;
+    /**
+     * If true, *replace* the stored ref with the one in the URL even when the
+     * URL has none. Useful in tests; defaults to false (URL ref always wins,
+     * but missing URL ref leaves the stored value untouched).
+     */
+    forceClearOnEmptyUrl?: boolean;
+}
+interface StoredRef {
+    refId: string;
+    expiresAt: number;
+}
+interface TrackPayload {
+    /** Optional email — privacy-truncated server-side before display. */
+    email?: string;
+    /** Any extra metadata for the event. */
+    [key: string]: unknown;
+}
+interface ConversionPayload {
+    amount: number;
+    email?: string;
+    currency?: string;
+    /** Anything else you want to attach (order_id, plan, etc.). */
+    [key: string]: unknown;
+}
+interface State {
+    apiKey: string | null;
+    apiBase: string;
+    refId: string | null;
+    now: () => number;
+}
+declare function readStoredRef(now?: () => number): string | null;
+declare function writeStoredRef(refId: string, now?: () => number): void;
+declare function clearStoredRef(): void;
+declare function extractRefFromUrl(href?: string): string | null;
+declare const sellfolk: {
+    /**
+     * Initialize the SDK with your public API key.
+     *
+     *   sellfolk.init('sk_live_acme_a8e92f...')
+     *
+     * On first call, captures `?ref=` from the URL (if present) and stores it
+     * with a 60-day expiry. Subsequent track() / conversion() calls automatically
+     * include the stored ref_id.
+     */
+    init(apiKey: string, options?: InitOptions): void;
+    /**
+     * Track an event. Common values: 'signup', 'trial', 'demo', 'newsletter'.
+     * Custom event names are allowed (they go in as type='custom' with
+     * customName=<event>).
+     */
+    track(event: string, payload?: TrackPayload): void;
+    /**
+     * Fire a conversion event — call this when real money moves.
+     * Example: inside your Stripe / Polar webhook handler.
+     */
+    conversion(payload: ConversionPayload): void;
+    /**
+     * Read the current stored ref_id (e.g. for logging or attribution debugging).
+     * Returns null if no ref has been captured yet.
+     */
+    getRef(): string | null;
+    /** Programmatically clear the stored ref (e.g. on logout). */
+    clearRef(): void;
+    _state: State;
+};
+
+export { type ConversionPayload, DEFAULT_API_BASE, type InitOptions, REF_STORAGE_KEY, REF_TTL_MS, type StoredRef, type TrackPayload, clearStoredRef, sellfolk as default, extractRefFromUrl, readStoredRef, writeStoredRef };

package/dist/index.js

@@ -0,0 +1,138 @@
+// src/index.ts
+var DEFAULT_API_BASE = "https://api.sellfolk.com";
+var REF_STORAGE_KEY = "sellfolk_ref";
+var REF_TTL_MS = 60 * 24 * 60 * 60 * 1e3;
+var state = {
+  apiKey: null,
+  apiBase: DEFAULT_API_BASE,
+  refId: null,
+  now: () => Date.now()
+};
+function readStoredRef(now = Date.now) {
+  try {
+    if (typeof localStorage === "undefined") return null;
+    const raw = localStorage.getItem(REF_STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed.refId !== "string" || typeof parsed.expiresAt !== "number") return null;
+    if (now() > parsed.expiresAt) {
+      try {
+        localStorage.removeItem(REF_STORAGE_KEY);
+      } catch {
+      }
+      return null;
+    }
+    return parsed.refId;
+  } catch {
+    return null;
+  }
+}
+function writeStoredRef(refId, now = Date.now) {
+  try {
+    if (typeof localStorage === "undefined") return;
+    const stored = { refId, expiresAt: now() + REF_TTL_MS };
+    localStorage.setItem(REF_STORAGE_KEY, JSON.stringify(stored));
+  } catch {
+  }
+}
+function clearStoredRef() {
+  try {
+    if (typeof localStorage === "undefined") return;
+    localStorage.removeItem(REF_STORAGE_KEY);
+  } catch {
+  }
+}
+function extractRefFromUrl(href) {
+  try {
+    const url = href ?? (typeof window !== "undefined" ? window.location.href : "");
+    if (!url) return null;
+    const u = new URL(url);
+    const ref = u.searchParams.get("ref");
+    return ref && ref.length > 0 && ref.length <= 80 ? ref : null;
+  } catch {
+    return null;
+  }
+}
+function dispatch(path, body) {
+  if (!state.apiKey) return;
+  try {
+    fetch(`${state.apiBase}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": state.apiKey
+      },
+      body: JSON.stringify({ ...body, refId: state.refId }),
+      keepalive: true
+    }).catch(() => {
+    });
+  } catch {
+  }
+}
+var sellfolk = {
+  /**
+   * Initialize the SDK with your public API key.
+   *
+   *   sellfolk.init('sk_live_acme_a8e92f...')
+   *
+   * On first call, captures `?ref=` from the URL (if present) and stores it
+   * with a 60-day expiry. Subsequent track() / conversion() calls automatically
+   * include the stored ref_id.
+   */
+  init(apiKey, options = {}) {
+    state.apiKey = apiKey;
+    state.apiBase = options.apiBase ?? DEFAULT_API_BASE;
+    if (options.now) state.now = options.now;
+    const urlRef = extractRefFromUrl();
+    if (urlRef) {
+      writeStoredRef(urlRef, state.now);
+      state.refId = urlRef;
+    } else if (options.forceClearOnEmptyUrl) {
+      clearStoredRef();
+      state.refId = null;
+    } else {
+      state.refId = readStoredRef(state.now);
+    }
+  },
+  /**
+   * Track an event. Common values: 'signup', 'trial', 'demo', 'newsletter'.
+   * Custom event names are allowed (they go in as type='custom' with
+   * customName=<event>).
+   */
+  track(event, payload = {}) {
+    dispatch("/api/v1/track", { event, ...payload });
+  },
+  /**
+   * Fire a conversion event — call this when real money moves.
+   * Example: inside your Stripe / Polar webhook handler.
+   */
+  conversion(payload) {
+    dispatch("/api/v1/conversion", payload);
+  },
+  /**
+   * Read the current stored ref_id (e.g. for logging or attribution debugging).
+   * Returns null if no ref has been captured yet.
+   */
+  getRef() {
+    return state.refId;
+  },
+  /** Programmatically clear the stored ref (e.g. on logout). */
+  clearRef() {
+    clearStoredRef();
+    state.refId = null;
+  },
+  // ── Testing handles (not part of public API) ──────────────────────────────
+  _state: state
+};
+var src_default = sellfolk;
+export {
+  DEFAULT_API_BASE,
+  REF_STORAGE_KEY,
+  REF_TTL_MS,
+  clearStoredRef,
+  src_default as default,
+  extractRefFromUrl,
+  readStoredRef,
+  writeStoredRef
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * sellfolk — Browser SDK\n *\n * Two lines to install:\n *\n *   import sellfolk from 'sellfolk'\n *   sellfolk.init('sk_live_...')\n *\n * Then call:\n *   sellfolk.track('signup', { email })\n *   sellfolk.conversion({ amount: 49.99, email })\n *\n * Design rules:\n *   • Never throws. If anything fails, we swallow it. Your SaaS keeps running.\n *   • `keepalive: true` on every fetch so requests survive page unload.\n *   • Captures `?ref=` on init() and stores it in localStorage with 60-day expiry.\n *   • All subsequent event calls auto-attach the stored ref_id.\n */\n\nexport const DEFAULT_API_BASE = 'https://api.sellfolk.com'\n\nexport const REF_STORAGE_KEY = 'sellfolk_ref'\n\nexport const REF_TTL_MS = 60 * 24 * 60 * 60 * 1000 // 60 days\n\nexport interface InitOptions {\n  /** Override the API base URL (used for testing or self-hosted backends). */\n  apiBase?: string\n  /** Provide a deterministic clock — primarily for tests. */\n  now?: () => number\n  /**\n   * If true, *replace* the stored ref with the one in the URL even when the\n   * URL has none. Useful in tests; defaults to false (URL ref always wins,\n   * but missing URL ref leaves the stored value untouched).\n   */\n  forceClearOnEmptyUrl?: boolean\n}\n\nexport interface StoredRef {\n  refId: string\n  expiresAt: number\n}\n\nexport interface TrackPayload {\n  /** Optional email — privacy-truncated server-side before display. */\n  email?: string\n  /** Any extra metadata for the event. */\n  [key: string]: unknown\n}\n\nexport interface ConversionPayload {\n  amount: number\n  email?: string\n  currency?: string\n  /** Anything else you want to attach (order_id, plan, etc.). */\n  [key: string]: unknown\n}\n\n// ── Internal state ──────────────────────────────────────────────────────────\ninterface State {\n  apiKey: string | null\n  apiBase: string\n  refId: string | null\n  now: () => number\n}\n\nconst state: State = {\n  apiKey: null,\n  apiBase: DEFAULT_API_BASE,\n  refId: null,\n  now: () => Date.now(),\n}\n\n// ── Storage helpers (defensive — localStorage may be missing/disabled) ──────\nexport function readStoredRef(now: () => number = Date.now): string | null {\n  try {\n    if (typeof localStorage === 'undefined') return null\n    const raw = localStorage.getItem(REF_STORAGE_KEY)\n    if (!raw) return null\n    const parsed = JSON.parse(raw) as StoredRef\n    if (!parsed || typeof parsed.refId !== 'string' || typeof parsed.expiresAt !== 'number') return null\n    if (now() > parsed.expiresAt) {\n      try { localStorage.removeItem(REF_STORAGE_KEY) } catch { /* ignored */ }\n      return null\n    }\n    return parsed.refId\n  } catch {\n    return null\n  }\n}\n\nexport function writeStoredRef(refId: string, now: () => number = Date.now): void {\n  try {\n    if (typeof localStorage === 'undefined') return\n    const stored: StoredRef = { refId, expiresAt: now() + REF_TTL_MS }\n    localStorage.setItem(REF_STORAGE_KEY, JSON.stringify(stored))\n  } catch {\n    // ignored\n  }\n}\n\nexport function clearStoredRef(): void {\n  try {\n    if (typeof localStorage === 'undefined') return\n    localStorage.removeItem(REF_STORAGE_KEY)\n  } catch {\n    // ignored\n  }\n}\n\n// ── URL parsing ─────────────────────────────────────────────────────────────\nexport function extractRefFromUrl(href?: string): string | null {\n  try {\n    const url = href ?? (typeof window !== 'undefined' ? window.location.href : '')\n    if (!url) return null\n    const u = new URL(url)\n    const ref = u.searchParams.get('ref')\n    return ref && ref.length > 0 && ref.length <= 80 ? ref : null\n  } catch {\n    return null\n  }\n}\n\n// ── Network ─────────────────────────────────────────────────────────────────\nfunction dispatch(path: string, body: Record<string, unknown>): void {\n  if (!state.apiKey) return\n  try {\n    // We intentionally do not await — keepalive ensures the request finishes\n    // even if the page is unloading.\n    fetch(`${state.apiBase}${path}`, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        'X-API-Key': state.apiKey,\n      },\n      body: JSON.stringify({ ...body, refId: state.refId }),\n      keepalive: true,\n    }).catch(() => { /* never throw */ })\n  } catch {\n    // Browsers without fetch (or with extreme restrictions) — silent.\n  }\n}\n\n// ── Public API ──────────────────────────────────────────────────────────────\nconst sellfolk = {\n  /**\n   * Initialize the SDK with your public API key.\n   *\n   *   sellfolk.init('sk_live_acme_a8e92f...')\n   *\n   * On first call, captures `?ref=` from the URL (if present) and stores it\n   * with a 60-day expiry. Subsequent track() / conversion() calls automatically\n   * include the stored ref_id.\n   */\n  init(apiKey: string, options: InitOptions = {}): void {\n    state.apiKey = apiKey\n    state.apiBase = options.apiBase ?? DEFAULT_API_BASE\n    if (options.now) state.now = options.now\n\n    const urlRef = extractRefFromUrl()\n    if (urlRef) {\n      writeStoredRef(urlRef, state.now)\n      state.refId = urlRef\n    } else if (options.forceClearOnEmptyUrl) {\n      clearStoredRef()\n      state.refId = null\n    } else {\n      state.refId = readStoredRef(state.now)\n    }\n  },\n\n  /**\n   * Track an event. Common values: 'signup', 'trial', 'demo', 'newsletter'.\n   * Custom event names are allowed (they go in as type='custom' with\n   * customName=<event>).\n   */\n  track(event: string, payload: TrackPayload = {}): void {\n    dispatch('/api/v1/track', { event, ...payload })\n  },\n\n  /**\n   * Fire a conversion event — call this when real money moves.\n   * Example: inside your Stripe / Polar webhook handler.\n   */\n  conversion(payload: ConversionPayload): void {\n    dispatch('/api/v1/conversion', payload)\n  },\n\n  /**\n   * Read the current stored ref_id (e.g. for logging or attribution debugging).\n   * Returns null if no ref has been captured yet.\n   */\n  getRef(): string | null {\n    return state.refId\n  },\n\n  /** Programmatically clear the stored ref (e.g. on logout). */\n  clearRef(): void {\n    clearStoredRef()\n    state.refId = null\n  },\n\n  // ── Testing handles (not part of public API) ──────────────────────────────\n  _state: state,\n}\n\nexport default sellfolk\n"],"mappings":"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","names":[]}

package/dist/sellfolk.min.js

@@ -0,0 +1 @@
+"use strict";var sellfolk=(()=>{var l=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var S=Object.prototype.hasOwnProperty;var m=(t,e)=>{for(var r in e)l(t,r,{get:e[r],enumerable:!0})},w=(t,e,r,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of y(e))!S.call(t,i)&&i!==r&&l(t,i,{get:()=>e[i],enumerable:!(o=g(e,i))||o.enumerable});return t};var I=t=>w(l({},"__esModule",{value:!0}),t);var R={};m(R,{DEFAULT_API_BASE:()=>s,REF_STORAGE_KEY:()=>a,REF_TTL_MS:()=>x,clearStoredRef:()=>f,default:()=>v,extractRefFromUrl:()=>p,readStoredRef:()=>u,writeStoredRef:()=>d});var s="https://api.sellfolk.com",a="sellfolk_ref",x=5184e6,n={apiKey:null,apiBase:s,refId:null,now:()=>Date.now()};function u(t=Date.now){try{if(typeof localStorage>"u")return null;let e=localStorage.getItem(a);if(!e)return null;let r=JSON.parse(e);if(!r||typeof r.refId!="string"||typeof r.expiresAt!="number")return null;if(t()>r.expiresAt){try{localStorage.removeItem(a)}catch{}return null}return r.refId}catch{return null}}function d(t,e=Date.now){try{if(typeof localStorage>"u")return;let r={refId:t,expiresAt:e()+5184e6};localStorage.setItem(a,JSON.stringify(r))}catch{}}function f(){try{if(typeof localStorage>"u")return;localStorage.removeItem(a)}catch{}}function p(t){try{let e=t??(typeof window<"u"?window.location.href:"");if(!e)return null;let o=new URL(e).searchParams.get("ref");return o&&o.length>0&&o.length<=80?o:null}catch{return null}}function c(t,e){if(n.apiKey)try{fetch(`${n.apiBase}${t}`,{method:"POST",headers:{"Content-Type":"application/json","X-API-Key":n.apiKey},body:JSON.stringify({...e,refId:n.refId}),keepalive:!0}).catch(()=>{})}catch{}}var h={init(t,e={}){n.apiKey=t,n.apiBase=e.apiBase??s,e.now&&(n.now=e.now);let r=p();r?(d(r,n.now),n.refId=r):e.forceClearOnEmptyUrl?(f(),n.refId=null):n.refId=u(n.now)},track(t,e={}){c("/api/v1/track",{event:t,...e})},conversion(t){c("/api/v1/conversion",t)},getRef(){return n.refId},clearRef(){f(),n.refId=null},_state:n},v=h;return I(R);})();

package/dist/server.cjs

@@ -0,0 +1,73 @@
+"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/server.ts
+var server_exports = {};
+__export(server_exports, {
+  SellfolkError: () => SellfolkError,
+  SellfolkServer: () => SellfolkServer
+});
+module.exports = __toCommonJS(server_exports);
+var DEFAULT_API_BASE = "https://api.sellfolk.com";
+var SellfolkServer = class {
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.apiBase = options.apiBase ?? DEFAULT_API_BASE;
+    this.throwOnError = options.throwOnError ?? false;
+    this._fetch = options.fetch ?? globalThis.fetch;
+  }
+  /** Track a non-conversion event (signup, trial, demo, newsletter, custom). */
+  async track(event, payload = {}) {
+    await this._post("/api/v1/track", { event, ...payload });
+  }
+  /** Track a paid conversion. Call from your billing webhook. */
+  async conversion(payload) {
+    await this._post("/api/v1/conversion", payload);
+  }
+  async _post(path, body) {
+    try {
+      const res = await this._fetch(`${this.apiBase}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey
+        },
+        body: JSON.stringify(body)
+      });
+      if (!res.ok && this.throwOnError) {
+        throw new SellfolkError(`Sellfolk ${path} returned ${res.status}`, res.status);
+      }
+    } catch (err) {
+      if (this.throwOnError) throw err;
+    }
+  }
+};
+var SellfolkError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "SellfolkError";
+    this.status = status;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SellfolkError,
+  SellfolkServer
+});
+//# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * sellfolk/server — Server SDK\n *\n * Node 20+ (uses native fetch). Zero runtime dependencies.\n *\n *   import { SellfolkServer } from 'sellfolk/server'\n *   const sb = new SellfolkServer(process.env.SELLFOLK_KEY!)\n *   await sb.conversion({ email, amount, currency })\n *\n * Design rules:\n *   • Never throws unless you explicitly opt-in with `throwOnError: true`.\n *   • Methods are async — await them inside webhook handlers so retries work.\n */\n\nconst DEFAULT_API_BASE = 'https://api.sellfolk.com'\n\nexport interface ServerOptions {\n  apiBase?: string\n  /** When true, propagate fetch errors. Default: false (swallowed). */\n  throwOnError?: boolean\n  /** Custom fetch implementation (mostly for tests). */\n  fetch?: typeof fetch\n}\n\nexport interface ConversionPayload {\n  email: string\n  amount: number\n  currency?: string\n  /** If omitted, the backend can still attribute via signed cookies or other channels. */\n  refId?: string\n  /** Arbitrary metadata (order_id, plan, etc.). */\n  [key: string]: unknown\n}\n\nexport interface TrackPayload {\n  refId?: string\n  email?: string\n  [key: string]: unknown\n}\n\nexport class SellfolkServer {\n  private apiKey: string\n  private apiBase: string\n  private throwOnError: boolean\n  private _fetch: typeof fetch\n\n  constructor(apiKey: string, options: ServerOptions = {}) {\n    this.apiKey = apiKey\n    this.apiBase = options.apiBase ?? DEFAULT_API_BASE\n    this.throwOnError = options.throwOnError ?? false\n    this._fetch = options.fetch ?? globalThis.fetch\n  }\n\n  /** Track a non-conversion event (signup, trial, demo, newsletter, custom). */\n  async track(event: string, payload: TrackPayload = {}): Promise<void> {\n    await this._post('/api/v1/track', { event, ...payload })\n  }\n\n  /** Track a paid conversion. Call from your billing webhook. */\n  async conversion(payload: ConversionPayload): Promise<void> {\n    await this._post('/api/v1/conversion', payload)\n  }\n\n  private async _post(path: string, body: Record<string, unknown>): Promise<void> {\n    try {\n      const res = await this._fetch(`${this.apiBase}${path}`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          'X-API-Key': this.apiKey,\n        },\n        body: JSON.stringify(body),\n      })\n      if (!res.ok && this.throwOnError) {\n        throw new SellfolkError(`Sellfolk ${path} returned ${res.status}`, res.status)\n      }\n    } catch (err) {\n      if (this.throwOnError) throw err\n      // Silent failure — webhook handlers should never crash because our API\n      // hiccuped. The conversion will be reconciled later if needed.\n    }\n  }\n}\n\nexport class SellfolkError extends Error {\n  status?: number\n  constructor(message: string, status?: number) {\n    super(message)\n    this.name = 'SellfolkError'\n    this.status = status\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAcA,IAAM,mBAAmB;AA0BlB,IAAM,iBAAN,MAAqB;AAAA,EAM1B,YAAY,QAAgB,UAAyB,CAAC,GAAG;AACvD,SAAK,SAAS;AACd,SAAK,UAAU,QAAQ,WAAW;AAClC,SAAK,eAAe,QAAQ,gBAAgB;AAC5C,SAAK,SAAS,QAAQ,SAAS,WAAW;AAAA,EAC5C;AAAA;AAAA,EAGA,MAAM,MAAM,OAAe,UAAwB,CAAC,GAAkB;AACpE,UAAM,KAAK,MAAM,iBAAiB,EAAE,OAAO,GAAG,QAAQ,CAAC;AAAA,EACzD;AAAA;AAAA,EAGA,MAAM,WAAW,SAA2C;AAC1D,UAAM,KAAK,MAAM,sBAAsB,OAAO;AAAA,EAChD;AAAA,EAEA,MAAc,MAAM,MAAc,MAA8C;AAC9E,QAAI;AACF,YAAM,MAAM,MAAM,KAAK,OAAO,GAAG,KAAK,OAAO,GAAG,IAAI,IAAI;AAAA,QACtD,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,gBAAgB;AAAA,UAChB,aAAa,KAAK;AAAA,QACpB;AAAA,QACA,MAAM,KAAK,UAAU,IAAI;AAAA,MAC3B,CAAC;AACD,UAAI,CAAC,IAAI,MAAM,KAAK,cAAc;AAChC,cAAM,IAAI,cAAc,YAAY,IAAI,aAAa,IAAI,MAAM,IAAI,IAAI,MAAM;AAAA,MAC/E;AAAA,IACF,SAAS,KAAK;AACZ,UAAI,KAAK,aAAc,OAAM;AAAA,IAG/B;AAAA,EACF;AACF;AAEO,IAAM,gBAAN,cAA4B,MAAM;AAAA,EAEvC,YAAY,SAAiB,QAAiB;AAC5C,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AACF;","names":[]}

package/dist/server.d.cts

@@ -0,0 +1,52 @@
+/**
+ * sellfolk/server — Server SDK
+ *
+ * Node 20+ (uses native fetch). Zero runtime dependencies.
+ *
+ *   import { SellfolkServer } from 'sellfolk/server'
+ *   const sb = new SellfolkServer(process.env.SELLFOLK_KEY!)
+ *   await sb.conversion({ email, amount, currency })
+ *
+ * Design rules:
+ *   • Never throws unless you explicitly opt-in with `throwOnError: true`.
+ *   • Methods are async — await them inside webhook handlers so retries work.
+ */
+interface ServerOptions {
+    apiBase?: string;
+    /** When true, propagate fetch errors. Default: false (swallowed). */
+    throwOnError?: boolean;
+    /** Custom fetch implementation (mostly for tests). */
+    fetch?: typeof fetch;
+}
+interface ConversionPayload {
+    email: string;
+    amount: number;
+    currency?: string;
+    /** If omitted, the backend can still attribute via signed cookies or other channels. */
+    refId?: string;
+    /** Arbitrary metadata (order_id, plan, etc.). */
+    [key: string]: unknown;
+}
+interface TrackPayload {
+    refId?: string;
+    email?: string;
+    [key: string]: unknown;
+}
+declare class SellfolkServer {
+    private apiKey;
+    private apiBase;
+    private throwOnError;
+    private _fetch;
+    constructor(apiKey: string, options?: ServerOptions);
+    /** Track a non-conversion event (signup, trial, demo, newsletter, custom). */
+    track(event: string, payload?: TrackPayload): Promise<void>;
+    /** Track a paid conversion. Call from your billing webhook. */
+    conversion(payload: ConversionPayload): Promise<void>;
+    private _post;
+}
+declare class SellfolkError extends Error {
+    status?: number;
+    constructor(message: string, status?: number);
+}
+
+export { type ConversionPayload, SellfolkError, SellfolkServer, type ServerOptions, type TrackPayload };

package/dist/server.d.ts

@@ -0,0 +1,52 @@
+/**
+ * sellfolk/server — Server SDK
+ *
+ * Node 20+ (uses native fetch). Zero runtime dependencies.
+ *
+ *   import { SellfolkServer } from 'sellfolk/server'
+ *   const sb = new SellfolkServer(process.env.SELLFOLK_KEY!)
+ *   await sb.conversion({ email, amount, currency })
+ *
+ * Design rules:
+ *   • Never throws unless you explicitly opt-in with `throwOnError: true`.
+ *   • Methods are async — await them inside webhook handlers so retries work.
+ */
+interface ServerOptions {
+    apiBase?: string;
+    /** When true, propagate fetch errors. Default: false (swallowed). */
+    throwOnError?: boolean;
+    /** Custom fetch implementation (mostly for tests). */
+    fetch?: typeof fetch;
+}
+interface ConversionPayload {
+    email: string;
+    amount: number;
+    currency?: string;
+    /** If omitted, the backend can still attribute via signed cookies or other channels. */
+    refId?: string;
+    /** Arbitrary metadata (order_id, plan, etc.). */
+    [key: string]: unknown;
+}
+interface TrackPayload {
+    refId?: string;
+    email?: string;
+    [key: string]: unknown;
+}
+declare class SellfolkServer {
+    private apiKey;
+    private apiBase;
+    private throwOnError;
+    private _fetch;
+    constructor(apiKey: string, options?: ServerOptions);
+    /** Track a non-conversion event (signup, trial, demo, newsletter, custom). */
+    track(event: string, payload?: TrackPayload): Promise<void>;
+    /** Track a paid conversion. Call from your billing webhook. */
+    conversion(payload: ConversionPayload): Promise<void>;
+    private _post;
+}
+declare class SellfolkError extends Error {
+    status?: number;
+    constructor(message: string, status?: number);
+}
+
+export { type ConversionPayload, SellfolkError, SellfolkServer, type ServerOptions, type TrackPayload };

package/dist/server.js

@@ -0,0 +1,47 @@
+// src/server.ts
+var DEFAULT_API_BASE = "https://api.sellfolk.com";
+var SellfolkServer = class {
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.apiBase = options.apiBase ?? DEFAULT_API_BASE;
+    this.throwOnError = options.throwOnError ?? false;
+    this._fetch = options.fetch ?? globalThis.fetch;
+  }
+  /** Track a non-conversion event (signup, trial, demo, newsletter, custom). */
+  async track(event, payload = {}) {
+    await this._post("/api/v1/track", { event, ...payload });
+  }
+  /** Track a paid conversion. Call from your billing webhook. */
+  async conversion(payload) {
+    await this._post("/api/v1/conversion", payload);
+  }
+  async _post(path, body) {
+    try {
+      const res = await this._fetch(`${this.apiBase}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey
+        },
+        body: JSON.stringify(body)
+      });
+      if (!res.ok && this.throwOnError) {
+        throw new SellfolkError(`Sellfolk ${path} returned ${res.status}`, res.status);
+      }
+    } catch (err) {
+      if (this.throwOnError) throw err;
+    }
+  }
+};
+var SellfolkError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "SellfolkError";
+    this.status = status;
+  }
+};
+export {
+  SellfolkError,
+  SellfolkServer
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * sellfolk/server — Server SDK\n *\n * Node 20+ (uses native fetch). Zero runtime dependencies.\n *\n *   import { SellfolkServer } from 'sellfolk/server'\n *   const sb = new SellfolkServer(process.env.SELLFOLK_KEY!)\n *   await sb.conversion({ email, amount, currency })\n *\n * Design rules:\n *   • Never throws unless you explicitly opt-in with `throwOnError: true`.\n *   • Methods are async — await them inside webhook handlers so retries work.\n */\n\nconst DEFAULT_API_BASE = 'https://api.sellfolk.com'\n\nexport interface ServerOptions {\n  apiBase?: string\n  /** When true, propagate fetch errors. Default: false (swallowed). */\n  throwOnError?: boolean\n  /** Custom fetch implementation (mostly for tests). */\n  fetch?: typeof fetch\n}\n\nexport interface ConversionPayload {\n  email: string\n  amount: number\n  currency?: string\n  /** If omitted, the backend can still attribute via signed cookies or other channels. */\n  refId?: string\n  /** Arbitrary metadata (order_id, plan, etc.). */\n  [key: string]: unknown\n}\n\nexport interface TrackPayload {\n  refId?: string\n  email?: string\n  [key: string]: unknown\n}\n\nexport class SellfolkServer {\n  private apiKey: string\n  private apiBase: string\n  private throwOnError: boolean\n  private _fetch: typeof fetch\n\n  constructor(apiKey: string, options: ServerOptions = {}) {\n    this.apiKey = apiKey\n    this.apiBase = options.apiBase ?? DEFAULT_API_BASE\n    this.throwOnError = options.throwOnError ?? false\n    this._fetch = options.fetch ?? globalThis.fetch\n  }\n\n  /** Track a non-conversion event (signup, trial, demo, newsletter, custom). */\n  async track(event: string, payload: TrackPayload = {}): Promise<void> {\n    await this._post('/api/v1/track', { event, ...payload })\n  }\n\n  /** Track a paid conversion. Call from your billing webhook. */\n  async conversion(payload: ConversionPayload): Promise<void> {\n    await this._post('/api/v1/conversion', payload)\n  }\n\n  private async _post(path: string, body: Record<string, unknown>): Promise<void> {\n    try {\n      const res = await this._fetch(`${this.apiBase}${path}`, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          'X-API-Key': this.apiKey,\n        },\n        body: JSON.stringify(body),\n      })\n      if (!res.ok && this.throwOnError) {\n        throw new SellfolkError(`Sellfolk ${path} returned ${res.status}`, res.status)\n      }\n    } catch (err) {\n      if (this.throwOnError) throw err\n      // Silent failure — webhook handlers should never crash because our API\n      // hiccuped. The conversion will be reconciled later if needed.\n    }\n  }\n}\n\nexport class SellfolkError extends Error {\n  status?: number\n  constructor(message: string, status?: number) {\n    super(message)\n    this.name = 'SellfolkError'\n    this.status = status\n  }\n}\n"],"mappings":";AAcA,IAAM,mBAAmB;AA0BlB,IAAM,iBAAN,MAAqB;AAAA,EAM1B,YAAY,QAAgB,UAAyB,CAAC,GAAG;AACvD,SAAK,SAAS;AACd,SAAK,UAAU,QAAQ,WAAW;AAClC,SAAK,eAAe,QAAQ,gBAAgB;AAC5C,SAAK,SAAS,QAAQ,SAAS,WAAW;AAAA,EAC5C;AAAA;AAAA,EAGA,MAAM,MAAM,OAAe,UAAwB,CAAC,GAAkB;AACpE,UAAM,KAAK,MAAM,iBAAiB,EAAE,OAAO,GAAG,QAAQ,CAAC;AAAA,EACzD;AAAA;AAAA,EAGA,MAAM,WAAW,SAA2C;AAC1D,UAAM,KAAK,MAAM,sBAAsB,OAAO;AAAA,EAChD;AAAA,EAEA,MAAc,MAAM,MAAc,MAA8C;AAC9E,QAAI;AACF,YAAM,MAAM,MAAM,KAAK,OAAO,GAAG,KAAK,OAAO,GAAG,IAAI,IAAI;AAAA,QACtD,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,gBAAgB;AAAA,UAChB,aAAa,KAAK;AAAA,QACpB;AAAA,QACA,MAAM,KAAK,UAAU,IAAI;AAAA,MAC3B,CAAC;AACD,UAAI,CAAC,IAAI,MAAM,KAAK,cAAc;AAChC,cAAM,IAAI,cAAc,YAAY,IAAI,aAAa,IAAI,MAAM,IAAI,IAAI,MAAM;AAAA,MAC/E;AAAA,IACF,SAAS,KAAK;AACZ,UAAI,KAAK,aAAc,OAAM;AAAA,IAG/B;AAAA,EACF;AACF;AAEO,IAAM,gBAAN,cAA4B,MAAM;AAAA,EAEvC,YAAY,SAAiB,QAAiB;AAC5C,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AACF;","names":[]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "sellfolk",
+  "version": "0.1.0",
+  "description": "Sellfolk SDK — track signups, trials, and conversions from your referral sellers.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs",
+      "types": "./dist/server.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}