@followgate/js 0.6.0 → 0.8.0

package/README.md

@@ -10,141 +10,378 @@ 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();
+}
+```
 
-Initialize the SDK with your credentials.
+## Handling Success (Important!)
+
+**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.
+
+### Event Listeners for Fine-Grained Control
+
+```typescript
+// 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 }, ...] }
+});
+```
 
-Open a social action popup/intent.
+## Configuration Options
 
 ```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
+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)
 });
 ```
 
-### `FollowGate.verify(options)`
+### Handle & Target Formats
+
+The SDK automatically normalizes usernames - you can use `@username` or `username`, both work:
 
-Verify if a user completed the action (Pro/Business tiers with OAuth).
+| 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: 'lukasvanuden', // NOT @lukasvanuden
+});
+
+// For repost: target = tweet ID
+await FollowGate.openIntent({
+  platform: 'twitter',
+  action: 'repost',
+  target: '1234567890123456789', // Tweet ID from URL
+});
+
+// Mark action as completed (tracks locally + sends to API)
+await FollowGate.complete({
   platform: 'twitter',
   action: 'follow',
-  target: 'yourusername',
-  userId: 'user-123',
+  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[]
+// }
 ```
 
-### `FollowGate.on(event, callback)`
+### Server-Side Verification
+
+When `userId` is set, completions are automatically saved to the server. You can verify users from your backend:
+
+```typescript
+// Check if user is verified (server-side)
+const isVerified = await FollowGate.isVerified();
+// Returns: true | false
+
+// Get full verification status
+const status = await FollowGate.getVerificationStatus();
+// Returns: {
+//   verified: boolean,
+//   userId: string,
+//   completedAt?: string,  // ISO date string
+//   actions?: [{ action: 'follow', target: 'lukasvanuden' }, ...]
+// }
+```
 
-Listen for events.
+**Use Case: Conditional Features**
+
+```typescript
+// In your app (e.g., Chrome extension, Electron app)
+FollowGate.init({
+  appId: 'your-app-id',
+  apiKey: 'fg_live_xxx',
+  userId: clerkUserId,
+  twitter: { handle: 'lukasvanuden' },
+});
+
+const isVerified = await FollowGate.isVerified();
+
+if (isVerified) {
+  // User completed FollowGate → Full access
+  enableAllFeatures();
+} else {
+  // User hasn't completed → Limited access
+  enableTrialMode();
+}
+```
+
+### 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`                   |
+
+## Framework Examples
 
-- `target` for `follow`: Twitter username (without @)
-- `target` for `repost`/`like`: Tweet ID
+### 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.
+
+## TypeScript
 
-- `target` for `follow`: Company name or `in:username` for personal profiles
+Full TypeScript support included:
 
 ```typescript
-// Follow a company
-FollowGate.open({
-  platform: 'linkedin',
-  action: 'follow',
-  target: 'microsoft',
-});
-
-// Follow a personal profile
-FollowGate.open({
-  platform: 'linkedin',
-  action: 'follow',
-  target: 'in:satyanadella',
-});
+import type {
+  Platform,
+  SocialAction,
+  FollowGateConfig,
+  TwitterConfig,
+  CompleteOptions,
+  UserInfo,
+  UnlockStatus,
+  VerificationStatus,
+} from '@followgate/js';
 ```
 
 ## Pricing
@@ -156,19 +393,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

@@ -21,6 +21,7 @@ interface FollowGateConfig {
     apiKey: string;
     apiUrl?: string;
     debug?: boolean;
+    userId?: string;
     twitter?: TwitterConfig;
     onComplete?: () => void;
     theme?: 'dark' | 'light';
@@ -65,6 +66,18 @@ interface UnlockStatus {
     username?: string;
     completedActions?: CompleteOptions[];
 }
+/**
+ * Server-side verification status
+ */
+interface VerificationStatus {
+    verified: boolean;
+    userId: string;
+    completedAt?: string;
+    actions?: Array<{
+        action: string;
+        target: string;
+    }>;
+}
 /**
  * FollowGate SDK Client
  */
@@ -129,10 +142,32 @@ declare class FollowGateClient {
     isUnlocked(): boolean;
     getUnlockStatus(): UnlockStatus;
     getCompletedActions(): CompleteOptions[];
+    /**
+     * Check if user is verified server-side
+     * Requires userId to be set in config
+     * @returns Promise<boolean> - true if verified, false otherwise
+     */
+    isVerified(): Promise<boolean>;
+    /**
+     * Get full verification status from server
+     * Requires userId to be set in config
+     * @returns Promise<VerificationStatus> - full verification details
+     */
+    getVerificationStatus(): Promise<VerificationStatus>;
     on(event: EventType, callback: EventCallback): void;
     off(event: EventType, callback: EventCallback): void;
+    /**
+     * Get storage key with optional userId suffix
+     * This ensures unlock status is per-user, not per-browser
+     */
+    private getStorageKey;
     private restoreSession;
     private saveCompletedActions;
+    /**
+     * Save completion to server for verification
+     * Only works if userId is set in config
+     */
+    private saveCompletion;
     private buildIntentUrl;
     private buildTwitterUrl;
     private buildBlueskyUrl;
@@ -142,4 +177,4 @@ declare class FollowGateClient {
 }
 declare const FollowGate: FollowGateClient;
 
-export { type CompleteOptions, type EventCallback, type EventType, FollowGate, FollowGateClient, type FollowGateConfig, FollowGateError, type Platform, type SocialAction, type TwitterConfig, 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, type VerificationStatus };

package/dist/index.d.ts

@@ -21,6 +21,7 @@ interface FollowGateConfig {
     apiKey: string;
     apiUrl?: string;
     debug?: boolean;
+    userId?: string;
     twitter?: TwitterConfig;
     onComplete?: () => void;
     theme?: 'dark' | 'light';
@@ -65,6 +66,18 @@ interface UnlockStatus {
     username?: string;
     completedActions?: CompleteOptions[];
 }
+/**
+ * Server-side verification status
+ */
+interface VerificationStatus {
+    verified: boolean;
+    userId: string;
+    completedAt?: string;
+    actions?: Array<{
+        action: string;
+        target: string;
+    }>;
+}
 /**
  * FollowGate SDK Client
  */
@@ -129,10 +142,32 @@ declare class FollowGateClient {
     isUnlocked(): boolean;
     getUnlockStatus(): UnlockStatus;
     getCompletedActions(): CompleteOptions[];
+    /**
+     * Check if user is verified server-side
+     * Requires userId to be set in config
+     * @returns Promise<boolean> - true if verified, false otherwise
+     */
+    isVerified(): Promise<boolean>;
+    /**
+     * Get full verification status from server
+     * Requires userId to be set in config
+     * @returns Promise<VerificationStatus> - full verification details
+     */
+    getVerificationStatus(): Promise<VerificationStatus>;
     on(event: EventType, callback: EventCallback): void;
     off(event: EventType, callback: EventCallback): void;
+    /**
+     * Get storage key with optional userId suffix
+     * This ensures unlock status is per-user, not per-browser
+     */
+    private getStorageKey;
     private restoreSession;
     private saveCompletedActions;
+    /**
+     * Save completion to server for verification
+     * Only works if userId is set in config
+     */
+    private saveCompletion;
     private buildIntentUrl;
     private buildTwitterUrl;
     private buildBlueskyUrl;
@@ -142,4 +177,4 @@ declare class FollowGateClient {
 }
 declare const FollowGate: FollowGateClient;
 
-export { type CompleteOptions, type EventCallback, type EventType, FollowGate, FollowGateClient, type FollowGateConfig, FollowGateError, type Platform, type SocialAction, type TwitterConfig, 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, type VerificationStatus };

package/dist/index.js

@@ -507,8 +507,14 @@ var FollowGateClient = class {
     style.textContent = MODAL_STYLES;
     document.head.appendChild(style);
     if (this.config?.accentColor) {
-      document.documentElement.style.setProperty("--fg-accent", this.config.accentColor);
-      document.documentElement.style.setProperty("--fg-accent-hover", this.config.accentColor);
+      document.documentElement.style.setProperty(
+        "--fg-accent",
+        this.config.accentColor
+      );
+      document.documentElement.style.setProperty(
+        "--fg-accent-hover",
+        this.config.accentColor
+      );
     }
     this.stylesInjected = true;
   }
@@ -556,8 +562,12 @@ var FollowGateClient = class {
       </button>
       <p class="fg-hint">No login required \u2013 just your username</p>
     `;
-    const input = document.getElementById("fg-username-input");
-    const btn = document.getElementById("fg-username-submit");
+    const input = document.getElementById(
+      "fg-username-input"
+    );
+    const btn = document.getElementById(
+      "fg-username-submit"
+    );
     input?.addEventListener("input", () => {
       btn.disabled = !input.value.trim();
     });
@@ -641,7 +651,9 @@ var FollowGateClient = class {
           Open again
         </button>
       `;
-      const confirmBtn = document.getElementById("fg-follow-confirm");
+      const confirmBtn = document.getElementById(
+        "fg-follow-confirm"
+      );
       const retryBtn = document.getElementById("fg-follow-retry");
       const interval = setInterval(() => {
         seconds--;
@@ -736,7 +748,9 @@ var FollowGateClient = class {
           Open tweet again
         </button>
       `;
-      const confirmBtn = document.getElementById("fg-repost-confirm");
+      const confirmBtn = document.getElementById(
+        "fg-repost-confirm"
+      );
       const retryBtn = document.getElementById("fg-repost-retry");
       const interval = setInterval(() => {
         seconds--;
@@ -851,7 +865,10 @@ var FollowGateClient = class {
       platform
     };
     if (typeof localStorage !== "undefined") {
-      localStorage.setItem("followgate_user", JSON.stringify(this.currentUser));
+      localStorage.setItem(
+        this.getStorageKey("followgate_user"),
+        JSON.stringify(this.currentUser)
+      );
     }
     if (this.config.debug) {
       console.log("[FollowGate] Username set:", normalizedUsername);
@@ -876,9 +893,9 @@ var FollowGateClient = class {
     this.currentUser = null;
     this.completedActions = [];
     if (typeof localStorage !== "undefined") {
-      localStorage.removeItem("followgate_user");
-      localStorage.removeItem("followgate_actions");
-      localStorage.removeItem("followgate_unlocked");
+      localStorage.removeItem(this.getStorageKey("followgate_user"));
+      localStorage.removeItem(this.getStorageKey("followgate_actions"));
+      localStorage.removeItem(this.getStorageKey("followgate_unlocked"));
     }
     if (this.config?.debug) {
       console.log("[FollowGate] Session reset");
@@ -915,7 +932,9 @@ var FollowGateClient = class {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
     if (!this.currentUser) {
-      throw new Error("[FollowGate] No username set. Call setUsername() first.");
+      throw new Error(
+        "[FollowGate] No username set. Call setUsername() first."
+      );
     }
     const alreadyCompleted = this.completedActions.some(
       (a) => a.platform === options.platform && a.action === options.action && a.target === options.target
@@ -941,8 +960,9 @@ var FollowGateClient = class {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
     if (typeof localStorage !== "undefined") {
-      localStorage.setItem("followgate_unlocked", "true");
+      localStorage.setItem(this.getStorageKey("followgate_unlocked"), "true");
     }
+    await this.saveCompletion();
     await this.trackEvent("gate_unlocked", {
       username: this.currentUser?.username,
       actions: this.completedActions
@@ -957,7 +977,7 @@ var FollowGateClient = class {
   }
   isUnlocked() {
     if (typeof localStorage === "undefined") return false;
-    return localStorage.getItem("followgate_unlocked") === "true";
+    return localStorage.getItem(this.getStorageKey("followgate_unlocked")) === "true";
   }
   getUnlockStatus() {
     return {
@@ -970,6 +990,90 @@ var FollowGateClient = class {
     return [...this.completedActions];
   }
   // ============================================
+  // Server-Side Verification
+  // ============================================
+  /**
+   * Check if user is verified server-side
+   * Requires userId to be set in config
+   * @returns Promise<boolean> - true if verified, false otherwise
+   */
+  async isVerified() {
+    if (!this.config) {
+      throw new Error("[FollowGate] SDK not initialized. Call init() first.");
+    }
+    if (!this.config.userId) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] isVerified() requires userId to be set");
+      }
+      return false;
+    }
+    try {
+      const response = await fetch(
+        `${this.config.apiUrl}/api/v1/completions/verify/${encodeURIComponent(this.config.userId)}`,
+        {
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`
+          }
+        }
+      );
+      if (!response.ok) {
+        if (this.config.debug) {
+          console.warn("[FollowGate] Verification check failed:", response.status);
+        }
+        return false;
+      }
+      const data = await response.json();
+      return data.data?.verified === true;
+    } catch (error) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] Verification check error:", error);
+      }
+      return false;
+    }
+  }
+  /**
+   * Get full verification status from server
+   * Requires userId to be set in config
+   * @returns Promise<VerificationStatus> - full verification details
+   */
+  async getVerificationStatus() {
+    if (!this.config) {
+      throw new Error("[FollowGate] SDK not initialized. Call init() first.");
+    }
+    if (!this.config.userId) {
+      return {
+        verified: false,
+        userId: ""
+      };
+    }
+    try {
+      const response = await fetch(
+        `${this.config.apiUrl}/api/v1/completions/verify/${encodeURIComponent(this.config.userId)}`,
+        {
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`
+          }
+        }
+      );
+      if (!response.ok) {
+        return {
+          verified: false,
+          userId: this.config.userId
+        };
+      }
+      const data = await response.json();
+      return data.data;
+    } catch (error) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] getVerificationStatus error:", error);
+      }
+      return {
+        verified: false,
+        userId: this.config.userId
+      };
+    }
+  }
+  // ============================================
   // Event System
   // ============================================
   on(event, callback) {
@@ -984,33 +1088,84 @@ var FollowGateClient = class {
   // ============================================
   // Private Methods
   // ============================================
+  /**
+   * Get storage key with optional userId suffix
+   * This ensures unlock status is per-user, not per-browser
+   */
+  getStorageKey(base) {
+    if (this.config?.userId) {
+      return `${base}_${this.config.userId}`;
+    }
+    return base;
+  }
   restoreSession() {
     if (typeof localStorage === "undefined") return;
-    const userJson = localStorage.getItem("followgate_user");
+    const userJson = localStorage.getItem(
+      this.getStorageKey("followgate_user")
+    );
     if (userJson) {
       try {
         this.currentUser = JSON.parse(userJson);
       } catch {
-        localStorage.removeItem("followgate_user");
+        localStorage.removeItem(this.getStorageKey("followgate_user"));
       }
     }
-    const actionsJson = localStorage.getItem("followgate_actions");
+    const actionsJson = localStorage.getItem(
+      this.getStorageKey("followgate_actions")
+    );
     if (actionsJson) {
       try {
         this.completedActions = JSON.parse(actionsJson);
       } catch {
-        localStorage.removeItem("followgate_actions");
+        localStorage.removeItem(this.getStorageKey("followgate_actions"));
       }
     }
   }
   saveCompletedActions() {
     if (typeof localStorage !== "undefined") {
       localStorage.setItem(
-        "followgate_actions",
+        this.getStorageKey("followgate_actions"),
         JSON.stringify(this.completedActions)
       );
     }
   }
+  /**
+   * Save completion to server for verification
+   * Only works if userId is set in config
+   */
+  async saveCompletion() {
+    if (!this.config?.userId) {
+      return;
+    }
+    try {
+      const response = await fetch(`${this.config.apiUrl}/api/v1/completions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify({
+          userId: this.config.userId,
+          platform: this.currentUser?.platform || "twitter",
+          actions: this.completedActions.map((a) => ({
+            action: a.action,
+            target: a.target
+          }))
+        })
+      });
+      if (this.config.debug) {
+        if (response.ok) {
+          console.log("[FollowGate] Completion saved to server");
+        } else {
+          console.warn("[FollowGate] Failed to save completion:", response.status);
+        }
+      }
+    } catch (error) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] Failed to save completion:", error);
+      }
+    }
+  }
   buildIntentUrl(options) {
     const { platform, action, target } = options;
     switch (platform) {

package/dist/index.mjs

@@ -481,8 +481,14 @@ var FollowGateClient = class {
     style.textContent = MODAL_STYLES;
     document.head.appendChild(style);
     if (this.config?.accentColor) {
-      document.documentElement.style.setProperty("--fg-accent", this.config.accentColor);
-      document.documentElement.style.setProperty("--fg-accent-hover", this.config.accentColor);
+      document.documentElement.style.setProperty(
+        "--fg-accent",
+        this.config.accentColor
+      );
+      document.documentElement.style.setProperty(
+        "--fg-accent-hover",
+        this.config.accentColor
+      );
     }
     this.stylesInjected = true;
   }
@@ -530,8 +536,12 @@ var FollowGateClient = class {
       </button>
       <p class="fg-hint">No login required \u2013 just your username</p>
     `;
-    const input = document.getElementById("fg-username-input");
-    const btn = document.getElementById("fg-username-submit");
+    const input = document.getElementById(
+      "fg-username-input"
+    );
+    const btn = document.getElementById(
+      "fg-username-submit"
+    );
     input?.addEventListener("input", () => {
       btn.disabled = !input.value.trim();
     });
@@ -615,7 +625,9 @@ var FollowGateClient = class {
           Open again
         </button>
       `;
-      const confirmBtn = document.getElementById("fg-follow-confirm");
+      const confirmBtn = document.getElementById(
+        "fg-follow-confirm"
+      );
       const retryBtn = document.getElementById("fg-follow-retry");
       const interval = setInterval(() => {
         seconds--;
@@ -710,7 +722,9 @@ var FollowGateClient = class {
           Open tweet again
         </button>
       `;
-      const confirmBtn = document.getElementById("fg-repost-confirm");
+      const confirmBtn = document.getElementById(
+        "fg-repost-confirm"
+      );
       const retryBtn = document.getElementById("fg-repost-retry");
       const interval = setInterval(() => {
         seconds--;
@@ -825,7 +839,10 @@ var FollowGateClient = class {
       platform
     };
     if (typeof localStorage !== "undefined") {
-      localStorage.setItem("followgate_user", JSON.stringify(this.currentUser));
+      localStorage.setItem(
+        this.getStorageKey("followgate_user"),
+        JSON.stringify(this.currentUser)
+      );
     }
     if (this.config.debug) {
       console.log("[FollowGate] Username set:", normalizedUsername);
@@ -850,9 +867,9 @@ var FollowGateClient = class {
     this.currentUser = null;
     this.completedActions = [];
     if (typeof localStorage !== "undefined") {
-      localStorage.removeItem("followgate_user");
-      localStorage.removeItem("followgate_actions");
-      localStorage.removeItem("followgate_unlocked");
+      localStorage.removeItem(this.getStorageKey("followgate_user"));
+      localStorage.removeItem(this.getStorageKey("followgate_actions"));
+      localStorage.removeItem(this.getStorageKey("followgate_unlocked"));
     }
     if (this.config?.debug) {
       console.log("[FollowGate] Session reset");
@@ -889,7 +906,9 @@ var FollowGateClient = class {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
     if (!this.currentUser) {
-      throw new Error("[FollowGate] No username set. Call setUsername() first.");
+      throw new Error(
+        "[FollowGate] No username set. Call setUsername() first."
+      );
     }
     const alreadyCompleted = this.completedActions.some(
       (a) => a.platform === options.platform && a.action === options.action && a.target === options.target
@@ -915,8 +934,9 @@ var FollowGateClient = class {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
     if (typeof localStorage !== "undefined") {
-      localStorage.setItem("followgate_unlocked", "true");
+      localStorage.setItem(this.getStorageKey("followgate_unlocked"), "true");
     }
+    await this.saveCompletion();
     await this.trackEvent("gate_unlocked", {
       username: this.currentUser?.username,
       actions: this.completedActions
@@ -931,7 +951,7 @@ var FollowGateClient = class {
   }
   isUnlocked() {
     if (typeof localStorage === "undefined") return false;
-    return localStorage.getItem("followgate_unlocked") === "true";
+    return localStorage.getItem(this.getStorageKey("followgate_unlocked")) === "true";
   }
   getUnlockStatus() {
     return {
@@ -944,6 +964,90 @@ var FollowGateClient = class {
     return [...this.completedActions];
   }
   // ============================================
+  // Server-Side Verification
+  // ============================================
+  /**
+   * Check if user is verified server-side
+   * Requires userId to be set in config
+   * @returns Promise<boolean> - true if verified, false otherwise
+   */
+  async isVerified() {
+    if (!this.config) {
+      throw new Error("[FollowGate] SDK not initialized. Call init() first.");
+    }
+    if (!this.config.userId) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] isVerified() requires userId to be set");
+      }
+      return false;
+    }
+    try {
+      const response = await fetch(
+        `${this.config.apiUrl}/api/v1/completions/verify/${encodeURIComponent(this.config.userId)}`,
+        {
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`
+          }
+        }
+      );
+      if (!response.ok) {
+        if (this.config.debug) {
+          console.warn("[FollowGate] Verification check failed:", response.status);
+        }
+        return false;
+      }
+      const data = await response.json();
+      return data.data?.verified === true;
+    } catch (error) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] Verification check error:", error);
+      }
+      return false;
+    }
+  }
+  /**
+   * Get full verification status from server
+   * Requires userId to be set in config
+   * @returns Promise<VerificationStatus> - full verification details
+   */
+  async getVerificationStatus() {
+    if (!this.config) {
+      throw new Error("[FollowGate] SDK not initialized. Call init() first.");
+    }
+    if (!this.config.userId) {
+      return {
+        verified: false,
+        userId: ""
+      };
+    }
+    try {
+      const response = await fetch(
+        `${this.config.apiUrl}/api/v1/completions/verify/${encodeURIComponent(this.config.userId)}`,
+        {
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`
+          }
+        }
+      );
+      if (!response.ok) {
+        return {
+          verified: false,
+          userId: this.config.userId
+        };
+      }
+      const data = await response.json();
+      return data.data;
+    } catch (error) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] getVerificationStatus error:", error);
+      }
+      return {
+        verified: false,
+        userId: this.config.userId
+      };
+    }
+  }
+  // ============================================
   // Event System
   // ============================================
   on(event, callback) {
@@ -958,33 +1062,84 @@ var FollowGateClient = class {
   // ============================================
   // Private Methods
   // ============================================
+  /**
+   * Get storage key with optional userId suffix
+   * This ensures unlock status is per-user, not per-browser
+   */
+  getStorageKey(base) {
+    if (this.config?.userId) {
+      return `${base}_${this.config.userId}`;
+    }
+    return base;
+  }
   restoreSession() {
     if (typeof localStorage === "undefined") return;
-    const userJson = localStorage.getItem("followgate_user");
+    const userJson = localStorage.getItem(
+      this.getStorageKey("followgate_user")
+    );
     if (userJson) {
       try {
         this.currentUser = JSON.parse(userJson);
       } catch {
-        localStorage.removeItem("followgate_user");
+        localStorage.removeItem(this.getStorageKey("followgate_user"));
       }
     }
-    const actionsJson = localStorage.getItem("followgate_actions");
+    const actionsJson = localStorage.getItem(
+      this.getStorageKey("followgate_actions")
+    );
     if (actionsJson) {
       try {
         this.completedActions = JSON.parse(actionsJson);
       } catch {
-        localStorage.removeItem("followgate_actions");
+        localStorage.removeItem(this.getStorageKey("followgate_actions"));
       }
     }
   }
   saveCompletedActions() {
     if (typeof localStorage !== "undefined") {
       localStorage.setItem(
-        "followgate_actions",
+        this.getStorageKey("followgate_actions"),
         JSON.stringify(this.completedActions)
       );
     }
   }
+  /**
+   * Save completion to server for verification
+   * Only works if userId is set in config
+   */
+  async saveCompletion() {
+    if (!this.config?.userId) {
+      return;
+    }
+    try {
+      const response = await fetch(`${this.config.apiUrl}/api/v1/completions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify({
+          userId: this.config.userId,
+          platform: this.currentUser?.platform || "twitter",
+          actions: this.completedActions.map((a) => ({
+            action: a.action,
+            target: a.target
+          }))
+        })
+      });
+      if (this.config.debug) {
+        if (response.ok) {
+          console.log("[FollowGate] Completion saved to server");
+        } else {
+          console.warn("[FollowGate] Failed to save completion:", response.status);
+        }
+      }
+    } catch (error) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] Failed to save completion:", error);
+      }
+    }
+  }
   buildIntentUrl(options) {
     const { platform, action, target } = options;
     switch (platform) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@followgate/js",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "FollowGate SDK - Grow your audience with every download. Require social actions (follow, repost) before users can access your app.",
   "author": "FollowGate <hello@followgate.app>",
   "homepage": "https://followgate.app",