@tiun/types 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @tiun/types
+
+TypeScript type definitions for the Tiun SDK.
+
+## When to Use
+
+| Installation Method      | Types Included? | Need This Package? |
+| ------------------------ | --------------- | ------------------ |
+| `npm install @tiun/sdk`  | ✅ Yes          | No                 |
+| `<script>` tags (legacy) | ❌ No           | **Yes**            |
+
+**NPM users:** Skip this package - types are bundled with `@tiun/sdk`.
+
+**Script tag users:** Install this for TypeScript support.
+
+## Installation
+
+```bash
+npm install @tiun/types --save-dev
+```
+
+## Setup
+
+Add to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@tiun/types"]
+  }
+}
+```
+
+Or add a reference directive to any `.d.ts` file:
+
+```typescript
+/// <reference types="@tiun/types" />
+```
+
+Restart your TypeScript server after setup.
+
+## Usage
+
+The global `Tiun` object is now typed:
+
+```typescript
+Tiun.init();
+Tiun.on('paywallShow', ({ isConnected }) => {});
+Tiun.checkout({ productId: 'prod_123' });
+```
+
+## Auto-generated
+
+This package is auto-generated from `src/sdk/types.ts`.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Tiun SDK Type Definitions
+ *
+ * Install: npm install @tiun/types --save-dev
+ *
+ * These types are for the global `Tiun` object exposed by the Tiun script.
+ * Load the script in your HTML, then use Tiun.* with full TypeScript support.
+ *
+ * @generated from src/sdk/types.ts - Do not edit directly.
+ * Run `npm run generate:types` to regenerate.
+ */
+
+// =============================================================================
+// Core Types
+// =============================================================================
+
+export type ContentType = 'active' | 'inactive' | 'paused';
+export type MediaType = 'text' | 'audio' | 'video';
+export type TiunEventType = 'ready' | 'paywallShow' | 'paywallHide' | 'error';
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+export interface TiunConfig {
+  /**
+   * Your unique Tiun snippet ID.
+   * Required for NPM package usage.
+   * For legacy script tag usage, this is provided via the backend.
+   */
+  snippetId?: string;
+
+  /**
+   * Language for the snippet UI.
+   * @default 'en'
+   */
+  language?: string;
+
+  /**
+   * UI tone/style.
+   * - 'formal': More professional tone
+   * - 'informal': More casual/friendly tone
+   * @default 'formal'
+   */
+  tone?: 'formal' | 'informal';
+
+  /**
+   * Corner style for UI elements.
+   * - 'rounded': Rounded corners
+   * - 'pointed': Sharp corners
+   * @default 'rounded'
+   */
+  corners?: 'rounded' | 'pointed';
+
+  /**
+   * Enable WebView mode (for mobile app WebViews).
+   * @default false
+   */
+  webView?: boolean;
+
+  /**
+   * API base URL. Only needed for custom deployments.
+   * @default 'https://api.tiun.live/live_api'
+   */
+  baseUrl?: string;
+
+  /**
+   * Enable debug logging to console.
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * Called when the snippet has finished initializing and is ready
+   */
+  onReady?: () => void;
+
+  /**
+   * Called when paywall should be shown to the user
+   */
+  onPaywallShow?: (data: PaywallShowEvent) => void;
+
+  /**
+   * Called when paywall should be hidden (user has access)
+   */
+  onPaywallHide?: (data: PaywallHideEvent) => void;
+
+  /**
+   * Called on any error
+   */
+  onError?: (error: TiunError) => void;
+}
+
+// =============================================================================
+// Event Payloads
+// =============================================================================
+
+export interface PaywallShowEvent {
+  /**
+   * Whether user has connected a payment method
+   */
+  isConnected: boolean;
+}
+
+export interface PaywallHideEvent {
+  /**
+   * Active session ID
+   */
+  sessionId: string;
+
+  /**
+   * Whether user is connected
+   */
+  isConnected: boolean;
+}
+
+export interface TiunError {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+// =============================================================================
+// Checkout Options
+// =============================================================================
+
+export interface CheckoutOptions {
+  /**
+   * Specific product ID to checkout (optional, for future use)
+   */
+  productId?: string;
+
+  /**
+   * Custom metadata to attach to this checkout
+   */
+  metadata?: Record<string, string>;
+}
+
+// =============================================================================
+// Content Options
+// =============================================================================
+
+export interface ContentOptions {
+  /**
+   * Type of content (affects session state)
+   */
+  type: ContentType;
+
+  /**
+   * Unique identifier for this content/route
+   */
+  contentId?: string;
+
+  /**
+   * Media type being consumed
+   * @default 'text'
+   */
+  mediaType?: MediaType;
+}
+
+// =============================================================================
+// SDK Interface (for global Tiun object)
+// =============================================================================
+
+export interface TiunSDK {
+  /**
+   * Initialize the SDK. Call once at app startup.
+   *
+   * For NPM package usage, snippetId is required:
+   * ```typescript
+   * Tiun.init({ snippetId: 'your-snippet-id' });
+   * ```
+   *
+   * For legacy script tag usage (backend-served), no config needed:
+   * ```typescript
+   * Tiun.init();
+   * ```
+   */
+  init(config?: TiunConfig): TiunSDK;
+
+  /**
+   * Open the checkout flow.
+   */
+  checkout(options?: CheckoutOptions): Promise<void>;
+
+  /**
+   * Update the current content context.
+   */
+  setContent(options: ContentOptions): Promise<void>;
+
+  /**
+   * Subscribe to an event. Returns unsubscribe function.
+   */
+  on(event: 'ready', callback: () => void): () => void;
+  on(event: 'paywallShow', callback: (data: PaywallShowEvent) => void): () => void;
+  on(event: 'paywallHide', callback: (data: PaywallHideEvent) => void): () => void;
+  on(event: 'error', callback: (error: TiunError) => void): () => void;
+
+  /**
+   * Subscribe to an event once (auto-unsubscribes after first fire).
+   */
+  once(event: 'ready', callback: () => void): () => void;
+  once(event: 'paywallShow', callback: (data: PaywallShowEvent) => void): () => void;
+  once(event: 'paywallHide', callback: (data: PaywallHideEvent) => void): () => void;
+  once(event: 'error', callback: (error: TiunError) => void): () => void;
+
+  /**
+   * Destroy the SDK and cleanup all listeners.
+   */
+  destroy(): void;
+
+  /**
+   * Wait for the SDK to be ready.
+   */
+  waitForReady(): Promise<void>;
+
+  /** SDK version */
+  readonly version: string;
+
+  /** Whether init() has been called */
+  readonly isInitialized: boolean;
+
+  /** Whether the snippet is ready */
+  readonly isReady: boolean;
+}
+
+// =============================================================================
+// Global Declaration
+// =============================================================================
+
+declare global {
+  /**
+   * Global Tiun SDK instance.
+   * Available after loading the Tiun script.
+   */
+  const Tiun: TiunSDK;
+
+  interface Window {
+    Tiun: TiunSDK;
+  }
+}
+
+export {};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tiun/types",
+  "version": "0.1.0",
+  "description": "TypeScript type definitions for Tiun SDK (for script tag users)",
+  "types": "./index.d.ts",
+  "files": [
+    "index.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "tiun",
+    "types",
+    "typescript",
+    "paywall",
+    "subscriptions"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tiun-app/tiun-snippet"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}