@followgate/js 0.14.0 → 0.15.0

package/README.md

@@ -108,6 +108,41 @@ FollowGate.on('unlocked', (data) => {
 });
 ```
 
+## Username Input (2 Methods)
+
+The SDK needs the user's social media username to work. There are exactly 2 ways to provide it:
+
+**Method 1: User enters username manually (default)**
+If no username is passed, the modal shows a Welcome step where the user types their username.
+
+```typescript
+FollowGate.init({
+  appId: 'your-app-id',
+  apiKey: 'fg_live_xxx',
+  twitter: { handle: 'your_handle' },
+});
+
+FollowGate.show(); // → Modal starts with username input step
+```
+
+**Method 2: App passes username via code (skips Welcome step)**
+If your app already knows the user's username (e.g. from your own auth system), pass it directly. The Welcome step is skipped entirely.
+
+```typescript
+FollowGate.init({
+  appId: 'your-app-id',
+  apiKey: 'fg_live_xxx',
+  twitter: {
+    handle: 'your_handle',
+    username: 'their_x_username', // ← skips Welcome step
+  },
+});
+
+FollowGate.show(); // → Modal starts directly with Follow step
+```
+
+> **Note:** No Twitter API calls are made in either case. The SDK uses intent URLs only.
+
 ## Configuration Options
 
 ```typescript

package/dist/index.d.mts

@@ -29,6 +29,7 @@ interface FollowGateConfig {
     onComplete?: () => void;
     theme?: 'dark' | 'light';
     accentColor?: string;
+    forceShow?: boolean;
 }
 /**
  * SDK Error class with helpful messages
@@ -93,6 +94,7 @@ declare class FollowGateClient {
     private completedActions;
     private modalElement;
     private stylesInjected;
+    private currentStep;
     /**
      * Initialize the SDK
      */
@@ -103,7 +105,7 @@ declare class FollowGateClient {
     private fetchServerConfig;
     /**
      * Show the FollowGate modal
-     * If user is already unlocked, calls onComplete immediately
+     * If user is already unlocked, calls onComplete immediately (unless forceShow is true)
      */
     show(): Promise<void>;
     /**

package/dist/index.d.ts

@@ -29,6 +29,7 @@ interface FollowGateConfig {
     onComplete?: () => void;
     theme?: 'dark' | 'light';
     accentColor?: string;
+    forceShow?: boolean;
 }
 /**
  * SDK Error class with helpful messages
@@ -93,6 +94,7 @@ declare class FollowGateClient {
     private completedActions;
     private modalElement;
     private stylesInjected;
+    private currentStep;
     /**
      * Initialize the SDK
      */
@@ -103,7 +105,7 @@ declare class FollowGateClient {
     private fetchServerConfig;
     /**
      * Show the FollowGate modal
-     * If user is already unlocked, calls onComplete immediately
+     * If user is already unlocked, calls onComplete immediately (unless forceShow is true)
      */
     show(): Promise<void>;
     /**

package/dist/index.js

@@ -503,6 +503,7 @@ var FollowGateClient = class {
   completedActions = [];
   modalElement = null;
   stylesInjected = false;
+  currentStep = "welcome";
   /**
    * Initialize the SDK
    */
@@ -598,22 +599,29 @@ var FollowGateClient = class {
   }
   /**
    * Show the FollowGate modal
-   * If user is already unlocked, calls onComplete immediately
+   * If user is already unlocked, calls onComplete immediately (unless forceShow is true)
    */
   async show() {
     if (!this.config) {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
     if (this.isUnlocked()) {
-      if (this.config.debug) {
-        console.log(
+      if (this.config.forceShow) {
+        this.clearUnlockStatus();
+        if (this.config.debug) {
+          console.log(
+            "[FollowGate] forceShow enabled - cleared unlock status, showing modal"
+          );
+        }
+      } else {
+        console.warn(
           "[FollowGate] Modal skipped - user already unlocked.",
-          "Call FollowGate.reset() to clear unlock status.",
+          "Use forceShow: true in init() to always show modal, or call FollowGate.reset() to clear.",
           this.config.userId ? `(userId: ${this.config.userId})` : "(no userId set)"
         );
+        this.config.onComplete?.();
+        return;
       }
-      this.config.onComplete?.();
-      return;
     }
     await this.fetchServerConfig();
     if (this.config.twitter?.username && !this.hasUsername()) {
@@ -625,6 +633,7 @@ var FollowGateClient = class {
         );
       }
     }
+    this.trackEvent("modal_opened");
     this.injectStyles();
     this.createModal();
   }
@@ -681,6 +690,7 @@ var FollowGateClient = class {
     document.body.appendChild(backdrop);
     this.modalElement = backdrop;
     document.getElementById("fg-close-btn")?.addEventListener("click", () => {
+      this.trackEvent("modal_closed", { step: this.currentStep });
       this.hide(true);
     });
     requestAnimationFrame(() => {
@@ -773,14 +783,16 @@ var FollowGateClient = class {
   renderUsernameStep() {
     const content = this.getContentElement();
     if (!content) return;
+    this.currentStep = "welcome";
+    this.trackEvent("step_viewed", { step: "welcome" });
     const handle = this.getTargetHandle();
     const hasRepost = this.shouldShowRepostStep();
     const allowSkip = this.serverConfig?.allowSkip ?? false;
     const welcomeTitle = this.serverConfig?.welcomeTitle || "Unlock Free Access";
     const welcomeMessage = this.serverConfig?.welcomeMessage || "Enter your X username to get started";
-    let explanationText = handle ? `Complete a quick follow${hasRepost ? " & repost" : ""} on X for @${handle} to unlock access.` : `Complete a quick social action to unlock access.`;
+    let explanationText = handle ? `Follow @${handle} on X${hasRepost ? " and repost a post" : ""} to unlock.` : `Complete a quick action on X to unlock.`;
     if (allowSkip) {
-      explanationText += ` You can skip if you prefer, but it helps support the developer.`;
+      explanationText += ` You can skip single steps, but it really helps the developer.`;
     }
     content.innerHTML = `
       <div class="fg-icon-box">
@@ -824,11 +836,14 @@ var FollowGateClient = class {
   handleUsernameSubmit(username) {
     const normalized = username.replace(/^@/, "");
     this.setUsername(normalized);
+    this.trackEvent("username_submitted", { username: normalized });
     this.renderFollowStep();
   }
   renderFollowStep() {
     const content = this.getContentElement();
     if (!content) return;
+    this.currentStep = "follow";
+    this.trackEvent("step_viewed", { step: "follow" });
     const handle = this.getTargetHandle();
     if (!handle) {
       console.error(
@@ -871,6 +886,7 @@ var FollowGateClient = class {
     });
   }
   handleSkipFollow() {
+    this.trackEvent("step_skipped", { step: "follow" });
     if (this.shouldShowRepostStep()) {
       this.renderRepostStep();
     } else {
@@ -952,6 +968,8 @@ var FollowGateClient = class {
     const content = this.getContentElement();
     const postId = this.getTargetPostUrl();
     if (!content || !postId) return;
+    this.currentStep = "repost";
+    this.trackEvent("step_viewed", { step: "repost" });
     content.innerHTML = `
       ${this.renderStepIndicator(2)}
       <div class="fg-icon-box fg-success">
@@ -978,6 +996,7 @@ var FollowGateClient = class {
       this.handleRepostClick();
     });
     document.getElementById("fg-skip-repost")?.addEventListener("click", () => {
+      this.trackEvent("step_skipped", { step: "repost" });
       this.renderConfirmStep();
     });
   }
@@ -1049,6 +1068,8 @@ var FollowGateClient = class {
   renderConfirmStep() {
     const content = this.getContentElement();
     if (!content) return;
+    this.currentStep = "confirm";
+    this.trackEvent("step_viewed", { step: "confirm" });
     const username = this.currentUser?.username;
     const targetHandle = this.getTargetHandle();
     const postId = this.getTargetPostUrl();
@@ -1065,7 +1086,10 @@ var FollowGateClient = class {
       verifyText = "Verifying repost";
     }
     content.innerHTML = `
-      <h2 class="fg-title">${this.escapeHtml(successTitle)}</h2>
+      <div style="display: flex; align-items: center; justify-content: center; gap: 10px; margin-bottom: 4px;">
+        <span style="color: #4ade80; width: 28px; height: 28px;">${ICONS.check}</span>
+        <h2 class="fg-title" style="margin: 0;">${this.escapeHtml(successTitle)}</h2>
+      </div>
       ${successMessage ? `<p class="fg-subtitle" style="margin-bottom: 16px;">${this.escapeHtml(successMessage)}</p>` : ""}
       <div class="fg-verify-box">
         <div class="fg-verify-box-left">
@@ -1080,15 +1104,13 @@ var FollowGateClient = class {
         ` : ""}
       </div>
       <p class="fg-verify-hint">Verification may take some time</p>
-      <div class="fg-warning-box">
-        ${ICONS.warning}
-        <p><strong>Note:</strong> Access may be revoked if actions are not completed.</p>
-      </div>
+      <p style="color: rgba(255,255,255,0.4); font-size: 11px; margin: 8px 0 16px; text-align: center;">Access may be revoked if actions are not completed.</p>
       <button class="fg-btn fg-btn-green" id="fg-finish-btn">
         ${ICONS.check}
-        Got it
+        Got it \u2014 Continue
       </button>
       ${hasFollow || hasRepost ? `
+        <p style="color: rgba(255,255,255,0.4); font-size: 11px; margin: 12px 0 6px; text-align: center;">Missed something? Open again:</p>
         <div class="fg-btn-row">
           ${hasFollow ? `
             <button class="fg-btn fg-btn-secondary" id="fg-redo-follow">
@@ -1543,8 +1565,37 @@ var FollowGateClient = class {
         throw new Error(`[FollowGate] Unsupported LinkedIn action: ${action}`);
     }
   }
-  async trackEvent(event, data) {
+  async trackEvent(event, data = {}) {
     if (!this.config) return;
+    const payload = {
+      event
+    };
+    if (data.platform) {
+      payload.platform = data.platform.toUpperCase();
+    }
+    if (data.action) {
+      payload.action = data.action.toUpperCase();
+    }
+    if (data.target) {
+      payload.target = data.target;
+    }
+    if (data.username || this.currentUser?.username) {
+      payload.username = data.username || this.currentUser?.username;
+    }
+    if (data.externalUserId) {
+      payload.externalUserId = data.externalUserId;
+    }
+    const {
+      platform: _p,
+      action: _a,
+      target: _t,
+      username: _u,
+      externalUserId: _e,
+      ...rest
+    } = data;
+    if (Object.keys(rest).length > 0) {
+      payload.metadata = rest;
+    }
     try {
       await fetch(`${this.config.apiUrl}/api/v1/events`, {
         method: "POST",
@@ -1552,11 +1603,7 @@ var FollowGateClient = class {
           "Content-Type": "application/json",
           "X-API-Key": this.config.apiKey
         },
-        body: JSON.stringify({
-          event,
-          appId: this.config.appId,
-          ...data
-        })
+        body: JSON.stringify(payload)
       });
     } catch (error) {
       if (this.config.debug) {

package/dist/index.mjs

@@ -477,6 +477,7 @@ var FollowGateClient = class {
   completedActions = [];
   modalElement = null;
   stylesInjected = false;
+  currentStep = "welcome";
   /**
    * Initialize the SDK
    */
@@ -572,22 +573,29 @@ var FollowGateClient = class {
   }
   /**
    * Show the FollowGate modal
-   * If user is already unlocked, calls onComplete immediately
+   * If user is already unlocked, calls onComplete immediately (unless forceShow is true)
    */
   async show() {
     if (!this.config) {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
     if (this.isUnlocked()) {
-      if (this.config.debug) {
-        console.log(
+      if (this.config.forceShow) {
+        this.clearUnlockStatus();
+        if (this.config.debug) {
+          console.log(
+            "[FollowGate] forceShow enabled - cleared unlock status, showing modal"
+          );
+        }
+      } else {
+        console.warn(
           "[FollowGate] Modal skipped - user already unlocked.",
-          "Call FollowGate.reset() to clear unlock status.",
+          "Use forceShow: true in init() to always show modal, or call FollowGate.reset() to clear.",
           this.config.userId ? `(userId: ${this.config.userId})` : "(no userId set)"
         );
+        this.config.onComplete?.();
+        return;
       }
-      this.config.onComplete?.();
-      return;
     }
     await this.fetchServerConfig();
     if (this.config.twitter?.username && !this.hasUsername()) {
@@ -599,6 +607,7 @@ var FollowGateClient = class {
         );
       }
     }
+    this.trackEvent("modal_opened");
     this.injectStyles();
     this.createModal();
   }
@@ -655,6 +664,7 @@ var FollowGateClient = class {
     document.body.appendChild(backdrop);
     this.modalElement = backdrop;
     document.getElementById("fg-close-btn")?.addEventListener("click", () => {
+      this.trackEvent("modal_closed", { step: this.currentStep });
       this.hide(true);
     });
     requestAnimationFrame(() => {
@@ -747,14 +757,16 @@ var FollowGateClient = class {
   renderUsernameStep() {
     const content = this.getContentElement();
     if (!content) return;
+    this.currentStep = "welcome";
+    this.trackEvent("step_viewed", { step: "welcome" });
     const handle = this.getTargetHandle();
     const hasRepost = this.shouldShowRepostStep();
     const allowSkip = this.serverConfig?.allowSkip ?? false;
     const welcomeTitle = this.serverConfig?.welcomeTitle || "Unlock Free Access";
     const welcomeMessage = this.serverConfig?.welcomeMessage || "Enter your X username to get started";
-    let explanationText = handle ? `Complete a quick follow${hasRepost ? " & repost" : ""} on X for @${handle} to unlock access.` : `Complete a quick social action to unlock access.`;
+    let explanationText = handle ? `Follow @${handle} on X${hasRepost ? " and repost a post" : ""} to unlock.` : `Complete a quick action on X to unlock.`;
     if (allowSkip) {
-      explanationText += ` You can skip if you prefer, but it helps support the developer.`;
+      explanationText += ` You can skip single steps, but it really helps the developer.`;
     }
     content.innerHTML = `
       <div class="fg-icon-box">
@@ -798,11 +810,14 @@ var FollowGateClient = class {
   handleUsernameSubmit(username) {
     const normalized = username.replace(/^@/, "");
     this.setUsername(normalized);
+    this.trackEvent("username_submitted", { username: normalized });
     this.renderFollowStep();
   }
   renderFollowStep() {
     const content = this.getContentElement();
     if (!content) return;
+    this.currentStep = "follow";
+    this.trackEvent("step_viewed", { step: "follow" });
     const handle = this.getTargetHandle();
     if (!handle) {
       console.error(
@@ -845,6 +860,7 @@ var FollowGateClient = class {
     });
   }
   handleSkipFollow() {
+    this.trackEvent("step_skipped", { step: "follow" });
     if (this.shouldShowRepostStep()) {
       this.renderRepostStep();
     } else {
@@ -926,6 +942,8 @@ var FollowGateClient = class {
     const content = this.getContentElement();
     const postId = this.getTargetPostUrl();
     if (!content || !postId) return;
+    this.currentStep = "repost";
+    this.trackEvent("step_viewed", { step: "repost" });
     content.innerHTML = `
       ${this.renderStepIndicator(2)}
       <div class="fg-icon-box fg-success">
@@ -952,6 +970,7 @@ var FollowGateClient = class {
       this.handleRepostClick();
     });
     document.getElementById("fg-skip-repost")?.addEventListener("click", () => {
+      this.trackEvent("step_skipped", { step: "repost" });
       this.renderConfirmStep();
     });
   }
@@ -1023,6 +1042,8 @@ var FollowGateClient = class {
   renderConfirmStep() {
     const content = this.getContentElement();
     if (!content) return;
+    this.currentStep = "confirm";
+    this.trackEvent("step_viewed", { step: "confirm" });
     const username = this.currentUser?.username;
     const targetHandle = this.getTargetHandle();
     const postId = this.getTargetPostUrl();
@@ -1039,7 +1060,10 @@ var FollowGateClient = class {
       verifyText = "Verifying repost";
     }
     content.innerHTML = `
-      <h2 class="fg-title">${this.escapeHtml(successTitle)}</h2>
+      <div style="display: flex; align-items: center; justify-content: center; gap: 10px; margin-bottom: 4px;">
+        <span style="color: #4ade80; width: 28px; height: 28px;">${ICONS.check}</span>
+        <h2 class="fg-title" style="margin: 0;">${this.escapeHtml(successTitle)}</h2>
+      </div>
       ${successMessage ? `<p class="fg-subtitle" style="margin-bottom: 16px;">${this.escapeHtml(successMessage)}</p>` : ""}
       <div class="fg-verify-box">
         <div class="fg-verify-box-left">
@@ -1054,15 +1078,13 @@ var FollowGateClient = class {
         ` : ""}
       </div>
       <p class="fg-verify-hint">Verification may take some time</p>
-      <div class="fg-warning-box">
-        ${ICONS.warning}
-        <p><strong>Note:</strong> Access may be revoked if actions are not completed.</p>
-      </div>
+      <p style="color: rgba(255,255,255,0.4); font-size: 11px; margin: 8px 0 16px; text-align: center;">Access may be revoked if actions are not completed.</p>
       <button class="fg-btn fg-btn-green" id="fg-finish-btn">
         ${ICONS.check}
-        Got it
+        Got it \u2014 Continue
       </button>
       ${hasFollow || hasRepost ? `
+        <p style="color: rgba(255,255,255,0.4); font-size: 11px; margin: 12px 0 6px; text-align: center;">Missed something? Open again:</p>
         <div class="fg-btn-row">
           ${hasFollow ? `
             <button class="fg-btn fg-btn-secondary" id="fg-redo-follow">
@@ -1517,8 +1539,37 @@ var FollowGateClient = class {
         throw new Error(`[FollowGate] Unsupported LinkedIn action: ${action}`);
     }
   }
-  async trackEvent(event, data) {
+  async trackEvent(event, data = {}) {
     if (!this.config) return;
+    const payload = {
+      event
+    };
+    if (data.platform) {
+      payload.platform = data.platform.toUpperCase();
+    }
+    if (data.action) {
+      payload.action = data.action.toUpperCase();
+    }
+    if (data.target) {
+      payload.target = data.target;
+    }
+    if (data.username || this.currentUser?.username) {
+      payload.username = data.username || this.currentUser?.username;
+    }
+    if (data.externalUserId) {
+      payload.externalUserId = data.externalUserId;
+    }
+    const {
+      platform: _p,
+      action: _a,
+      target: _t,
+      username: _u,
+      externalUserId: _e,
+      ...rest
+    } = data;
+    if (Object.keys(rest).length > 0) {
+      payload.metadata = rest;
+    }
     try {
       await fetch(`${this.config.apiUrl}/api/v1/events`, {
         method: "POST",
@@ -1526,11 +1577,7 @@ var FollowGateClient = class {
           "Content-Type": "application/json",
           "X-API-Key": this.config.apiKey
         },
-        body: JSON.stringify({
-          event,
-          appId: this.config.appId,
-          ...data
-        })
+        body: JSON.stringify(payload)
       });
     } catch (error) {
       if (this.config.debug) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@followgate/js",
-  "version": "0.14.0",
+  "version": "0.15.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",