@followgate/js 0.5.0 → 0.7.0

package/README.md

@@ -10,141 +10,336 @@ FollowGate is inspired by [Hypeddit](https://hypeddit.com) (for musicians), but
 npm install @followgate/js
 ```
 
-## Quick Start
+## Quick Start (Built-in Modal)
+
+Just 10 lines of code - no custom UI needed:
 
 ```typescript
 import { FollowGate } from '@followgate/js';
 
-// Initialize with your API credentials (get them at https://app.followgate.io)
+// Initialize once (e.g., in your app's entry point)
 FollowGate.init({
   appId: 'your-app-id',
   apiKey: 'fg_live_xxx',
+  twitter: {
+    handle: 'your_twitter_handle',
+    tweetId: '1234567890', // Optional: require repost
+  },
+  onComplete: () => {
+    // User completed all actions - redirect to your app
+    router.push('/dashboard');
+  },
 });
 
-// Require a Twitter follow before granting access
-FollowGate.open({
-  platform: 'twitter',
-  action: 'follow',
-  target: 'yourusername',
-  userId: 'user-123', // Optional: your app's user ID for tracking
-});
+// Show the modal (that's it!)
+FollowGate.show();
 ```
 
-## Supported Platforms
+The SDK renders a beautiful, fully-functional modal with:
 
-| Platform  | Actions                    |
-| --------- | -------------------------- |
-| Twitter/X | `follow`, `repost`, `like` |
-| Bluesky   | `follow`, `repost`, `like` |
-| LinkedIn  | `follow`                   |
+- Username input step
+- Follow action with intent URL
+- Repost action (optional)
+- Confirmation step
+- All styling included (no CSS needed)
 
-## API Reference
+## When to Show the Modal
 
-### `FollowGate.init(config)`
+```typescript
+// After sign-up (recommended)
+const handleSignUpSuccess = () => {
+  FollowGate.show();
+};
+
+// Or check if already unlocked
+if (!FollowGate.isUnlocked()) {
+  FollowGate.show();
+}
+```
+
+## Handling Success (Important!)
 
-Initialize the SDK with your credentials.
+**The `onComplete` callback is called ONLY after the user successfully completes all required actions.** This is the right place to:
+
+- Create the user account in your database
+- Grant access to premium features
+- Redirect to your app
 
 ```typescript
 FollowGate.init({
-  appId: 'your-app-id', // Required: Your app ID from dashboard
-  apiKey: 'fg_live_xxx', // Required: Your API key
-  apiUrl: 'https://...', // Optional: Custom API URL
-  debug: false, // Optional: Enable debug logging
+  appId: 'your-app-id',
+  apiKey: 'fg_live_xxx',
+  twitter: { handle: 'your_handle' },
+
+  onComplete: async () => {
+    // ✅ User completed all steps - NOW create the account!
+    const user = FollowGate.getUser();
+
+    await fetch('/api/create-account', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        xUsername: user?.username, // Their X/Twitter username
+        platform: user?.platform, // 'twitter'
+      }),
+    });
+
+    // Then redirect to your app
+    router.push('/dashboard');
+  },
 });
 ```
 
-### `FollowGate.open(options)`
+**Why this matters:** Don't create accounts before `onComplete` is called. Users might close the modal without completing the actions. Only when `onComplete` fires, you know they actually followed/reposted.
 
-Open a social action popup/intent.
+### Event Listeners for Fine-Grained Control
 
 ```typescript
-await FollowGate.open({
-  platform: 'twitter', // 'twitter' | 'bluesky' | 'linkedin'
-  action: 'follow', // 'follow' | 'repost' | 'like'
-  target: 'username', // Username or post ID
-  userId: 'user-123', // Optional: Your app's user ID
+// Fired when a SINGLE action is completed (follow OR repost)
+FollowGate.on('complete', (data) => {
+  console.log('Action completed:', data);
+  // { platform: 'twitter', action: 'follow', target: 'your_handle', username: 'their_username' }
+});
+
+// Fired when ALL actions are completed (same timing as onComplete)
+FollowGate.on('unlocked', (data) => {
+  console.log('Gate unlocked:', data);
+  // { username: 'their_username', actions: [{ platform, action, target }, ...] }
 });
 ```
 
-### `FollowGate.verify(options)`
+## Configuration Options
 
-Verify if a user completed the action (Pro/Business tiers with OAuth).
+```typescript
+FollowGate.init({
+  // Required
+  appId: 'your-app-id', // Your App ID from the dashboard
+  apiKey: 'fg_live_xxx', // Your API key (starts with fg_live_ or fg_test_)
+
+  // Twitter/X Configuration
+  twitter: {
+    handle: 'your_handle', // Your Twitter username (without @)
+    tweetId: '1234567890', // Tweet ID to repost (optional)
+  },
+
+  // Callback when user completes all actions
+  onComplete: () => {
+    // Called after the user finishes all steps and clicks "Got it"
+    // Typically used to redirect to your app
+    router.push('/dashboard');
+  },
+
+  // Optional
+  userId: 'clerk_user_123', // User ID for per-user unlock status (recommended with auth)
+  debug: false, // Enable console logging for debugging
+  accentColor: '#6366f1', // Customize primary button color (hex)
+  theme: 'dark', // 'dark' | 'light' - modal appearance
+  apiUrl: 'https://...', // Custom API URL (for self-hosted)
+});
+```
+
+### Handle & Target Formats
+
+The SDK automatically normalizes usernames - you can use `@username` or `username`, both work:
+
+| Platform     | Action | Target Format                       | Example                              |
+| ------------ | ------ | ----------------------------------- | ------------------------------------ |
+| **Twitter**  | follow | Username (without @)                | `lukasvanuden`                       |
+| **Twitter**  | repost | Tweet ID (numbers only)             | `1234567890123456789`                |
+| **Twitter**  | like   | Tweet ID (numbers only)             | `1234567890123456789`                |
+| **Bluesky**  | follow | Handle (with or without @)          | `user.bsky.social`                   |
+| **Bluesky**  | repost | AT URI or post path                 | `user.bsky.social/post/xyz`          |
+| **LinkedIn** | follow | Company name or prefixed identifier | `company:anthropic` or `in:username` |
+
+**Tip:** For Twitter, you can find the Tweet ID in the URL: `https://x.com/user/status/1234567890123456789`
+
+## API Reference
+
+### Modal Methods
 
 ```typescript
-const isVerified = await FollowGate.verify({
+// Show the FollowGate modal
+// If user is already unlocked, calls onComplete immediately
+FollowGate.show();
+
+// Hide the modal programmatically
+FollowGate.hide();
+
+// Check if user has completed all actions
+FollowGate.isUnlocked(); // true | false
+
+// Reset user's session (for testing)
+FollowGate.reset();
+```
+
+### Advanced Usage
+
+For custom UI implementations (when you don't want to use the built-in modal):
+
+```typescript
+// Set username manually (@ is automatically removed)
+FollowGate.setUsername('your_username'); // or '@your_username' - both work!
+
+// Check if username is set
+FollowGate.hasUsername(); // true | false
+
+// Open intent URLs directly (opens in new window)
+// For follow: target = username (without @)
+await FollowGate.openIntent({
   platform: 'twitter',
   action: 'follow',
-  target: 'yourusername',
-  userId: 'user-123',
+  target: 'lukasvanuden', // NOT @lukasvanuden
+});
+
+// For repost: target = tweet ID
+await FollowGate.openIntent({
+  platform: 'twitter',
+  action: 'repost',
+  target: '1234567890123456789', // Tweet ID from URL
 });
-```
 
-### `FollowGate.on(event, callback)`
+// Mark action as completed (tracks locally + sends to API)
+await FollowGate.complete({
+  platform: 'twitter',
+  action: 'follow',
+  target: 'lukasvanuden',
+});
+
+// Mark gate as unlocked (user has completed all required actions)
+await FollowGate.unlock();
+
+// Get current user info
+FollowGate.getUser();
+// Returns: { username: 'their_username', platform: 'twitter' } | null
+
+// Get completed actions
+FollowGate.getCompletedActions();
+// Returns: [{ platform: 'twitter', action: 'follow', target: 'lukasvanuden' }, ...]
+
+// Get full unlock status
+FollowGate.getUnlockStatus();
+// Returns: {
+//   unlocked: boolean,
+//   username?: string,
+//   completedActions?: CompleteOptions[]
+// }
+```
 
-Listen for events.
+### Event Listeners
 
 ```typescript
 FollowGate.on('complete', (data) => {
-  console.log('User completed action:', data);
-  // Grant access to your app
+  console.log('Action completed:', data);
+});
+
+FollowGate.on('unlocked', (data) => {
+  console.log('Gate unlocked:', data);
 });
 
 FollowGate.on('error', (error) => {
   console.error('Error:', error);
 });
+
+// Remove listener
+FollowGate.off('complete', handler);
 ```
 
-## Platform-Specific Notes
+## Supported Platforms
 
-### Twitter/X
+| Platform  | Actions                    |
+| --------- | -------------------------- |
+| Twitter/X | `follow`, `repost`, `like` |
+| Bluesky   | `follow`, `repost`, `like` |
+| LinkedIn  | `follow`                   |
 
-- `target` for `follow`: Twitter username (without @)
-- `target` for `repost`/`like`: Tweet ID
+## Framework Examples
+
+### Next.js (App Router)
 
 ```typescript
-// Follow
-FollowGate.open({ platform: 'twitter', action: 'follow', target: 'elonmusk' });
+// app/welcome/page.tsx
+'use client';
 
-// Repost a tweet
-FollowGate.open({
-  platform: 'twitter',
-  action: 'repost',
-  target: '1234567890',
-});
+import { FollowGate } from '@followgate/js';
+import { useRouter } from 'next/navigation';
+import { useEffect } from 'react';
+
+export default function WelcomePage() {
+  const router = useRouter();
+
+  useEffect(() => {
+    FollowGate.init({
+      appId: process.env.NEXT_PUBLIC_FOLLOWGATE_APP_ID!,
+      apiKey: process.env.NEXT_PUBLIC_FOLLOWGATE_API_KEY!,
+      twitter: { handle: 'your_handle' },
+      onComplete: () => router.push('/dashboard'),
+    });
+
+    // Show modal if not already unlocked
+    if (!FollowGate.isUnlocked()) {
+      FollowGate.show();
+    } else {
+      router.push('/dashboard');
+    }
+  }, [router]);
+
+  return <div>Loading...</div>;
+}
 ```
 
-### Bluesky
-
-- `target` for `follow`: Bluesky handle (e.g., `alice.bsky.social`)
-- `target` for `repost`/`like`: Post path (e.g., `alice.bsky.social/post/xxx`)
+### With Clerk Auth
 
 ```typescript
-// Follow
-FollowGate.open({
-  platform: 'bluesky',
-  action: 'follow',
-  target: 'alice.bsky.social',
-});
+// app/welcome/page.tsx
+'use client';
+
+import { FollowGate } from '@followgate/js';
+import { useRouter } from 'next/navigation';
+import { useUser } from '@clerk/nextjs';
+import { useEffect } from 'react';
+
+export default function WelcomePage() {
+  const router = useRouter();
+  const { user } = useUser();
+
+  useEffect(() => {
+    if (!user) return;
+
+    FollowGate.init({
+      appId: process.env.NEXT_PUBLIC_FOLLOWGATE_APP_ID!,
+      apiKey: process.env.NEXT_PUBLIC_FOLLOWGATE_API_KEY!,
+      userId: user.id, // Per-user unlock status (recommended!)
+      twitter: { handle: 'lukasvanuden' },
+      onComplete: () => router.push('/dashboard'),
+    });
+
+    if (!FollowGate.isUnlocked()) {
+      FollowGate.show();
+    } else {
+      router.push('/dashboard');
+    }
+  }, [user, router]);
+
+  return <div>Loading...</div>;
+}
 ```
 
-### LinkedIn
+**Why use `userId`?** Without it, unlock status is stored per-browser. If User A completes the gate on a shared computer, User B would also be "unlocked". With `userId`, each user has their own unlock status.
 
-- `target` for `follow`: Company name or `in:username` for personal profiles
+## TypeScript
 
-```typescript
-// Follow a company
-FollowGate.open({
-  platform: 'linkedin',
-  action: 'follow',
-  target: 'microsoft',
-});
+Full TypeScript support included:
 
-// Follow a personal profile
-FollowGate.open({
-  platform: 'linkedin',
-  action: 'follow',
-  target: 'in:satyanadella',
-});
+```typescript
+import type {
+  Platform,
+  SocialAction,
+  FollowGateConfig,
+  TwitterConfig,
+  CompleteOptions,
+  UserInfo,
+  UnlockStatus,
+} from '@followgate/js';
 ```
 
 ## Pricing
@@ -156,19 +351,12 @@ FollowGate.open({
 | Pro      | $49/mo | 2,000  | OAuth verification |
 | Business | $99/mo | 5,000+ | Daily verification |
 
-## TypeScript
-
-Full TypeScript support included. Types are exported:
-
-```typescript
-import type { Platform, SocialAction, FollowGateConfig } from '@followgate/js';
-```
-
 ## Links
 
-- [Dashboard](https://app.followgate.io)
-- [Documentation](https://followgate.io/docs)
+- [Dashboard](https://followgate.app)
+- [Documentation](https://docs.followgate.app)
 - [GitHub](https://github.com/JustFF5/FollowGate)
+- [Live Demo](https://follow-gate-web-demo.vercel.app)
 
 ## License
 

package/dist/index.d.mts

@@ -6,6 +6,13 @@ type Platform = 'twitter' | 'bluesky' | 'linkedin';
  * Supported social actions
  */
 type SocialAction = 'follow' | 'repost' | 'like';
+/**
+ * Twitter/X configuration
+ */
+interface TwitterConfig {
+    handle: string;
+    tweetId?: string;
+}
 /**
  * SDK Configuration
  */
@@ -14,6 +21,11 @@ interface FollowGateConfig {
     apiKey: string;
     apiUrl?: string;
     debug?: boolean;
+    userId?: string;
+    twitter?: TwitterConfig;
+    onComplete?: () => void;
+    theme?: 'dark' | 'light';
+    accentColor?: string;
 }
 /**
  * SDK Error class with helpful messages
@@ -56,28 +68,45 @@ interface UnlockStatus {
 }
 /**
  * FollowGate SDK Client
- *
- * Simple username-based flow:
- * 1. User enters username
- * 2. User clicks intent URLs to follow/repost
- * 3. User confirms they did it
- * 4. App is unlocked
- *
- * No OAuth required!
  */
 declare class FollowGateClient {
     private config;
     private listeners;
     private currentUser;
     private completedActions;
+    private modalElement;
+    private stylesInjected;
     /**
      * Initialize the SDK
-     * @throws {FollowGateError} If configuration is invalid
      */
     init(config: FollowGateConfig): void;
+    /**
+     * Show the FollowGate modal
+     * If user is already unlocked, calls onComplete immediately
+     */
+    show(): void;
+    /**
+     * Hide the modal
+     */
+    hide(): void;
+    private injectStyles;
+    private createModal;
+    private getContentElement;
+    private renderUsernameStep;
+    private handleUsernameSubmit;
+    private renderFollowStep;
+    private handleFollowClick;
+    private showFollowConfirmation;
+    private handleFollowConfirm;
+    private renderRepostStep;
+    private handleRepostClick;
+    private showRepostConfirmation;
+    private handleRepostConfirm;
+    private renderConfirmStep;
+    private handleFinish;
+    private renderStepIndicator;
     /**
      * Set the user's social username
-     * This is the main entry point - no OAuth needed!
      */
     setUsername(username: string, platform?: Platform): void;
     /**
@@ -92,73 +121,31 @@ declare class FollowGateClient {
      * Clear stored session
      */
     reset(): void;
-    /**
-     * Get follow intent URL for a platform
-     */
     getFollowUrl(platform: Platform, target: string): string;
-    /**
-     * Get repost/retweet intent URL for a platform
-     */
     getRepostUrl(platform: Platform, target: string): string;
-    /**
-     * Get like intent URL for a platform
-     */
     getLikeUrl(platform: Platform, target: string): string;
-    /**
-     * Open intent URL in new window
-     */
     openIntent(options: CompleteOptions): Promise<void>;
-    /**
-     * Mark an action as completed (trust-first)
-     * Call this when user confirms they did the action
-     */
     complete(options: CompleteOptions): Promise<void>;
-    /**
-     * Mark the gate as unlocked
-     * Call this when all required actions are done
-     */
     unlock(): Promise<void>;
-    /**
-     * Check if gate is unlocked
-     */
     isUnlocked(): boolean;
-    /**
-     * Get unlock status with details
-     */
     getUnlockStatus(): UnlockStatus;
-    /**
-     * Get completed actions
-     */
     getCompletedActions(): CompleteOptions[];
-    /**
-     * Register event listener
-     */
     on(event: EventType, callback: EventCallback): void;
-    /**
-     * Remove event listener
-     */
     off(event: EventType, callback: EventCallback): void;
     /**
-     * Restore session from localStorage
+     * Get storage key with optional userId suffix
+     * This ensures unlock status is per-user, not per-browser
      */
+    private getStorageKey;
     private restoreSession;
-    /**
-     * Save completed actions to localStorage
-     */
     private saveCompletedActions;
-    /**
-     * Build intent URL for platform
-     */
     private buildIntentUrl;
     private buildTwitterUrl;
     private buildBlueskyUrl;
     private buildLinkedInUrl;
-    /**
-     * Track analytics event
-     */
     private trackEvent;
     private emit;
 }
 declare const FollowGate: FollowGateClient;
 
-export { type CompleteOptions, type EventCallback, type EventType, FollowGate, FollowGateClient, type FollowGateConfig, FollowGateError, type Platform, type SocialAction, type UnlockStatus, type UserInfo };
+export { type CompleteOptions, type EventCallback, type EventType, FollowGate, FollowGateClient, type FollowGateConfig, FollowGateError, type Platform, type SocialAction, type TwitterConfig, type UnlockStatus, type UserInfo };