@thspian/circuul-core

Framework-agnostic Circuul HTTP client for Thspian UGC CPA attribution (app install + web visit).

Used by @thspian/circuul-react and @thspian/circuul-react-native. You can also call it directly from Node or plain browser JS.

Before you install

1. On thspian.com, create a UGC campaign with app install (or web visit) CPA enabled.
2. Sync / open Circuul settings for that campaign and copy your app token (cat_…).
3. Pass that token into createClient({ appToken: 'cat_…' }).

Without a campaign and cat_… token, attribution will not work.

Install

npm install @thspian/circuul-core

Requires Node 18+ (uses global fetch).

Quick start

import { createClient, extractCodeFromSearch } from '@thspian/circuul-core';

const circuul = createClient({
  appToken: 'cat_…', // from your Thspian campaign — only required field
});

// Web visit (landing page)
const visit = await circuul.visitConfirm({
  code: extractCodeFromSearch(window.location.search),
});

// App install (native / RN first open)
const match = await circuul.match({
  platform: 'ios',
  install_id: 'persistent-device-uuid',
});

Both match and visitConfirm always resolve — they never throw. Check result.attributed.

API

createClient({ appToken, env?, apiBase? })

| Option | Required | Description | |--------|----------|-------------| | appToken | yes | Campaign token from Thspian (cat_…) | | env | no | 'prod' (default) or 'dev' | | apiBase | no | Explicit override — wins over env. Local/custom only. |

Returns:

| Method | Use | |--------|-----| | match(payload) | First open after install — credits install CPA | | visitConfirm(payload) | Landing page load — credits web-visit CPA (sends app_token) | | recordClick(payload) | Optional explicit click record |

DEFAULT_API_BASE / API_BASES / resolveApiBase()

Production default, known env hosts, and helper to resolve the API URL.

extractCodeFromSearch(search)

Reads circuul_ref, ref, circuul, code, or utm_content from a query string.

shouldPersistMatched(result)

Helper for SDKs: whether a result is terminal (safe to mark “already tried”).

Environment

// Production (default)
createClient({ appToken: 'cat_…' });

// Dev
createClient({ appToken: 'cat_…', env: 'dev' });

| env | API base | |-------|----------| | 'prod' | https://dashboard.thspian.com/api/v1 | | 'dev' | https://dev-api.thspian.com/api/v1 |

Custom / local override

createClient({
  appToken: 'cat_…',
  apiBase: 'http://localhost:3000/api/v1',
});

apiBase overrides env when both are set.

Production apps should omit both unless you need dev or local testing.

Related packages

• @thspian/circuul-react
• @thspian/circuul-react-native

Docs: thspian.com · GitHub