@tiun/sdk

# tiun SDK The tiun SDK provides a simple API for integrating payments, subscriptions, and authentication into any website or app. --- ## Installation ```bash npm install @tiun/sdk ``` --- ## Quick Start ```typescript import { tiun } from '@tiun/sdk'; tiun.init({ snippetId: 'your-snippet-id', language: 'en', // set to your site's language }); // Subscription checkout for a specific product tiun.checkout({ productId: 'prod_monthly' }); // Time-based connect flow tiun.start(); ``` > **Set `language` to match your site.** If omitted, the snippet UI defaults to `'en'`. See all supported codes in the [Init options](#init-options) table below. The snippet is loaded automatically from the backend when you call `tiun.init()` with a `snippetId`. No script tags or extra HTML are required. --- ## Configuration ### `tiun.init(config)` Initialize the SDK. Call once at app startup. ```typescript tiun.init({ snippetId: 'your-snippet-id', language: 'en', // set to your site's language tone: 'formal', debug: false, sandbox: false, // Lifecycle callbacks onReady: () => {}, onPaywallShow: (data) => {}, onPaywallHide: (data) => {}, onError: (error) => {}, // Auth callbacks onUserChange: (event) => {}, onLogin: (event) => {}, onLogout: () => {} }); ``` ### Init options | Option | Type | Default | Description | | --------------- | ---------------------------------- | ---------- | ------------------------------------------------------------------ | | `snippetId` | `string` | — | **Required.** Your unique tiun snippet ID from the dashboard. | | `language` | `string` | `'en'` | Language for the snippet UI (e.g. `'en'`, `'de'`, `'fr'`). Set this to match your site; falls back to `'en'` if omitted. | | `tone` | `'formal' \| 'informal'` | `'formal'` | UI tone/style. | | `debug` | `boolean` | `false` | Enable console logging. | | `sandbox` | `boolean` | `false` | Use sandbox base URL instead of production. | | `onReady` | `() => void` | — | Called when snippet is ready. | | `onPaywallShow` | `(data: PaywallShowEvent) => void` | — | Called when paywall should be shown. | | `onPaywallHide` | `(data: PaywallHideEvent) => void` | — | Called when user has access. | | `onUserChange` | `(data: UserChangeEvent) => void` | — | Called on every user state change (init, login, logout, checkout). | | `onLogin` | `(data: LoginEvent) => void` | — | Called when user logs in. | | `onLogout` | `() => void` | — | Called when user logs out. | | `onError` | `(error: TiunError) => void` | — | Called on errors. | --- ## Authentication tiun provides built-in passwordless authentication (OTP via SMS/email). Users authenticate once during checkout, and their session persists across visits. ### `tiun.login()` Open the login modal for returning subscribers. ```typescript tiun.login(); ``` ### `tiun.logout()` Log the user out and clear the session. ```typescript tiun.logout(); ``` ### `tiun.getUser()` Returns the cached user state synchronously. ```typescript const { isAuthenticated, user } = tiun.getUser(); if (isAuthenticated) { console.log('Logged in as', user.email); console.log('Product access:', user.productAccess); } ``` Returns `GetUserResponse`: | Property | Type | Description | | ----------------- | ------------------ | ----------------------------------------- | | `isAuthenticated` | `boolean` | Whether the user has an active session. | | `user` | `UserInfo \| null` | User details, or `null` if not logged in. | ### `UserInfo` | Property | Type | Description | | --------------- | ---------- | ------------------------------------------- | | `userId` | `string` | Unique user identifier. | | `email` | `string` | User's email address. | | `productAccess` | `string[]` | List of product IDs the user has access to. | ### `tiun.getUserVerificationToken()` Returns a secure token that can be used for server-to-server user verification. The token is valid for 5 minutes. Returns `null` if the user is not authenticated. ```typescript const token = await tiun.getUserVerificationToken(); ``` Your backend can verify the token using your tiun API key from the business dashboard. --- ## Start & Checkout tiun supports two flows: - **Subscription checkout** (`checkout`) -- Opens the checkout flow for a specific product. Requires a `productId`. - **Time-based connect** (`start`) -- Opens the connect flow without a specific product. Used for time-based access models. ### `tiun.checkout(options)` Open the subscription checkout flow for a specific product. ```typescript tiun.checkout({ productId: 'prod_monthly' }); ``` | Option | Type | Description | | ----------- | -------- | ----------------------------------------------------- | | `productId` | `string` | The product ID to checkout. From your tiun dashboard. | --- ### `tiun.start()` Open the time-based connect flow. ```typescript tiun.start(); ``` ## Events Subscribe with `tiun.on()`. Returns an unsubscribe function. ### `ready` Fired when the snippet has initialized and is ready to use. ```typescript tiun.on('ready', () => { console.log('tiun is ready'); }); ``` ### `userChange` Fired on every user state change -- initialization, login, logout, and checkout. This is the single event to track all user state transitions. ```typescript tiun.on('userChange', (event) => { console.log('Event:', event.event); console.log('Authenticated:', event.isAuthenticated); console.log('User:', event.user); }); ``` | Property | Type | Description | | ----------------- | ------------------ | ---------------------------------------------------------------------------------------- | | `event` | `string` | What triggered the change: `'init'`, `'login'`, `'logout'`, `'checkout'`, or `'update'`. | | `isAuthenticated` | `boolean` | Whether the user is currently authenticated. | | `user` | `UserInfo \| null` | User details, or `null`. | ### `login` Fired specifically when a user logs in. Convenience event -- the same data is also available via `userChange`. ```typescript tiun.on('login', (event) => { console.log('Welcome back,', event.user.email); }); ``` | Property | Type | Description | | -------- | ---------- | ------------- | | `user` | `UserInfo` | User details. | ### `logout` Fired when the user logs out. ```typescript tiun.on('logout', () => { console.log('User logged out'); }); ``` ### `error` Fired when an error occurs. ```typescript tiun.on('error', (error) => { console.error('tiun error:', error.code, error.message); }); ``` | Property | Type | Description | | --------- | --------- | ------------------------- | | `code` | `string` | Error code. | | `message` | `string` | Error message. | | `details` | `unknown` | Additional error details. | ### All events | Event | Description | | ------------- | --------------------------------------------------------------------------------------------------- | | `ready` | Snippet has initialized and is ready. | | `userChange` | User state changed. Payload: `UserChangeEvent`. | | `login` | User logged in. Payload: `LoginEvent`. | | `logout` | User logged out. No payload. | | `paywallShow` | Paywall should be shown (user doesn't have access). Payload: `{ isConnected: boolean }`. | | `paywallHide` | Paywall should be hidden (user has access). Payload: `{ sessionId: string, isConnected: boolean }`. | | `error` | An error occurred. Payload: `TiunError`. | ### Paywall events (payloads) **paywallShow:** `{ isConnected: boolean }` **paywallHide:** `{ sessionId: string, isConnected: boolean }` ### One-time and unsubscribe ```typescript tiun.once('login', (event) => console.log('First login:', event.user.email)); const unsubscribe = tiun.on('userChange', () => {}); unsubscribe(); ``` --- ## Properties | Property | Type | Description | | ---------------------- | ------------------ | ---------------------------------------------- | | `tiun.version` | `string` | SDK version. | | `tiun.isInitialized` | `boolean` | Whether `init()` has been called. | | `tiun.isReady` | `boolean` | Whether the snippet is ready. | | `tiun.isAuthenticated` | `boolean` | Whether the user has a valid session. | | `tiun.user` | `UserInfo \| null` | Current user info, or `null` if not logged in. | --- ## Methods | Method | Description | | --------------------------------- | ----------------------------------------------------------- | | `tiun.init(config)` | Initialize the SDK. Call once at startup. | | `tiun.start()` | Open the time-based connect flow. | | `tiun.checkout(options)` | Open the subscription checkout flow for a specific product. | | `tiun.login()` | Open the login modal for returning subscribers. | | `tiun.logout()` | Log the user out and clear the session. | | `tiun.getUser()` | Get cached user state (synchronous). | | `tiun.getUserVerificationToken()` | Get a secure token for server-to-server verification. | | `tiun.setContent(options)` | Update the current content context. | | `tiun.on(event, callback)` | Subscribe to an event. Returns unsubscribe function. | | `tiun.once(event, callback)` | Subscribe to an event once. Returns unsubscribe function. | | `tiun.destroy()` | Destroy the SDK and clean up listeners. | | `tiun.waitForReady()` | Wait for the SDK to be ready. Returns a Promise. | ### `tiun.setContent(options)` Tell tiun what content the user is viewing. ```typescript tiun.setContent({ type: 'active', contentId: 'episode-123', mediaType: 'audio' }); ``` | Option | Type | Description | | ----------- | ------------------------------------ | ---------------------------------- | | `type` | `'active' \| 'inactive' \| 'paused'` | **Required.** Content state. | | `contentId` | `string` | Unique identifier for the content. | | `mediaType` | `'text' \| 'audio' \| 'video'` | Type of media. Default: `'text'`. | --- ## Framework examples ### Vue ```vue <script setup lang="ts"> import { tiun } from '@tiun/sdk'; import { onMounted, onUnmounted } from 'vue'; onMounted(() => { tiun.init({ snippetId: 'your-snippet-id', language: 'en' }); }); onUnmounted(() => { tiun.destroy(); }); </script> <template> <button @click="tiun.checkout({ productId: 'prod_monthly' })"> Subscribe </button> </template> ``` ### React ```tsx import { tiun } from '@tiun/sdk'; import { useEffect } from 'react'; function App() { useEffect(() => { tiun.init({ snippetId: 'your-snippet-id', language: 'en' }); return () => tiun.destroy(); }, []); return ( <div> <button onClick={() => tiun.checkout({ productId: 'prod_monthly' })}> Subscribe </button> </div> ); } ``` ### Vanilla JS ```html <script src="https://cdn.tiun.io/sdk.js"></script> <script> tiun.init({ snippetId: 'your-snippet-id', language: 'en' }); </script> <button onclick="tiun.checkout({ productId: 'prod_monthly' })"> Subscribe </button> ```