@followgate/js 0.3.0 → 0.5.0

package/dist/index.mjs

@@ -1,276 +1,243 @@
 // src/index.ts
 var DEFAULT_API_URL = "https://api.followgate.app";
+var FollowGateError = class extends Error {
+  constructor(message, code, hint) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.name = "FollowGateError";
+  }
+};
+function isValidApiKeyFormat(apiKey) {
+  return /^fg_(live|test)_[a-zA-Z0-9_-]+$/.test(apiKey);
+}
 var FollowGateClient = class {
   config = null;
   listeners = /* @__PURE__ */ new Map();
   currentUser = null;
-  authToken = null;
-  pendingUsername = null;
+  completedActions = [];
   /**
    * Initialize the SDK
+   * @throws {FollowGateError} If configuration is invalid
    */
   init(config) {
+    if (!config.appId || typeof config.appId !== "string") {
+      throw new FollowGateError(
+        "[FollowGate] Missing or invalid appId",
+        "INVALID_APP_ID",
+        "Get your App ID from https://followgate.app/dashboard. Make sure NEXT_PUBLIC_FOLLOWGATE_APP_ID is set in your environment."
+      );
+    }
+    if (config.appId.trim() === "" || config.appId === "undefined") {
+      throw new FollowGateError(
+        "[FollowGate] appId is empty or undefined",
+        "EMPTY_APP_ID",
+        "Your appId appears to be empty. This often happens when environment variables are not properly configured. Check that NEXT_PUBLIC_FOLLOWGATE_APP_ID is set and rebuild your application."
+      );
+    }
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new FollowGateError(
+        "[FollowGate] Missing or invalid apiKey",
+        "INVALID_API_KEY",
+        "Get your API Key from https://followgate.app/dashboard. Make sure NEXT_PUBLIC_FOLLOWGATE_API_KEY is set in your environment."
+      );
+    }
+    if (config.apiKey.trim() === "" || config.apiKey === "undefined") {
+      throw new FollowGateError(
+        "[FollowGate] apiKey is empty or undefined",
+        "EMPTY_API_KEY",
+        "Your apiKey appears to be empty. This often happens when environment variables are not properly configured at BUILD TIME (not runtime). Set NEXT_PUBLIC_FOLLOWGATE_API_KEY and REBUILD your application."
+      );
+    }
+    if (!isValidApiKeyFormat(config.apiKey)) {
+      throw new FollowGateError(
+        `[FollowGate] Invalid API key format: "${config.apiKey.substring(0, 10)}..."`,
+        "INVALID_API_KEY_FORMAT",
+        'API keys should start with "fg_live_" (production) or "fg_test_" (development). Get a valid key from https://followgate.app/dashboard'
+      );
+    }
     this.config = {
       ...config,
       apiUrl: config.apiUrl || DEFAULT_API_URL
     };
-    this.handleAuthCallback();
     this.restoreSession();
     if (config.debug) {
       console.log("[FollowGate] Initialized with appId:", config.appId);
+      console.log(
+        "[FollowGate] API Key:",
+        config.apiKey.substring(0, 12) + "..."
+      );
       if (this.currentUser) {
         console.log("[FollowGate] Restored user:", this.currentUser.username);
       }
     }
   }
   /**
-   * Authenticate user via Twitter OAuth (handled by FollowGate)
-   * This identifies WHO is completing the social actions.
+   * Set the user's social username
+   * This is the main entry point - no OAuth needed!
    */
-  authenticate(options = {}) {
+  setUsername(username, platform = "twitter") {
     if (!this.config) {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
-    const redirectUri = options.redirectUri || window.location.href.split("?")[0];
-    const authUrl = `${this.config.apiUrl}/api/v1/auth/twitter?app_id=${encodeURIComponent(this.config.appId)}&redirect_uri=${encodeURIComponent(redirectUri)}`;
-    if (this.config.debug) {
-      console.log("[FollowGate] Starting auth flow:", authUrl);
+    const normalizedUsername = username.startsWith("@") ? username.slice(1) : username;
+    this.currentUser = {
+      username: normalizedUsername,
+      platform
+    };
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem("followgate_user", JSON.stringify(this.currentUser));
     }
-    if (options.popup) {
-      const popup = window.open(
-        authUrl,
-        "followgate_auth",
-        "width=600,height=700"
-      );
-      if (!popup) {
-        this.emit("error", { message: "Popup blocked" });
-      }
-    } else {
-      window.location.href = authUrl;
+    if (this.config.debug) {
+      console.log("[FollowGate] Username set:", normalizedUsername);
     }
   }
   /**
-   * Get current authenticated user
+   * Get current user
    */
   getUser() {
     return this.currentUser;
   }
   /**
-   * Check if user is authenticated
+   * Check if username is set
    */
-  isAuthenticated() {
-    return this.currentUser !== null && this.authToken !== null;
+  hasUsername() {
+    return this.currentUser !== null;
   }
   /**
-   * Logout - clear stored session
+   * Clear stored session
    */
-  logout() {
+  reset() {
     this.currentUser = null;
-    this.authToken = null;
-    this.pendingUsername = null;
+    this.completedActions = [];
     if (typeof localStorage !== "undefined") {
-      localStorage.removeItem("followgate_token");
       localStorage.removeItem("followgate_user");
-      localStorage.removeItem("followgate_pending_username");
+      localStorage.removeItem("followgate_actions");
+      localStorage.removeItem("followgate_unlocked");
     }
     if (this.config?.debug) {
-      console.log("[FollowGate] User logged out");
+      console.log("[FollowGate] Session reset");
     }
   }
+  // ============================================
+  // Intent URL Methods
+  // ============================================
   /**
-   * Check if username input is needed (Twitter Free Tier limitation)
+   * Get follow intent URL for a platform
    */
-  needsUsernameInput() {
-    return this.pendingUsername !== null;
+  getFollowUrl(platform, target) {
+    return this.buildIntentUrl({ platform, action: "follow", target });
   }
   /**
-   * Set username manually (when needsUsernameInput() returns true)
+   * Get repost/retweet intent URL for a platform
    */
-  setUsername(username) {
-    if (!this.pendingUsername) {
-      throw new Error(
-        "[FollowGate] No pending username state. User is either not authenticated or username is already set."
-      );
-    }
-    const normalizedUsername = username.startsWith("@") ? username.slice(1) : username;
-    this.currentUser = {
-      userId: "user_input",
-      username: normalizedUsername,
-      platform: "twitter"
-    };
-    this.authToken = this.pendingUsername.token;
-    if (typeof localStorage !== "undefined") {
-      localStorage.setItem("followgate_token", this.authToken);
-      localStorage.setItem("followgate_user", JSON.stringify(this.currentUser));
-      localStorage.removeItem("followgate_pending_username");
-    }
-    this.pendingUsername = null;
-    this.emit("authenticated", this.currentUser);
-    if (this.config?.debug) {
-      console.log("[FollowGate] Username set manually:", normalizedUsername);
-    }
+  getRepostUrl(platform, target) {
+    return this.buildIntentUrl({ platform, action: "repost", target });
   }
   /**
-   * Handle auth callback from URL params
+   * Get like intent URL for a platform
    */
-  handleAuthCallback() {
-    if (typeof window === "undefined") return;
-    const params = new URLSearchParams(window.location.search);
-    const token = params.get("followgate_token");
-    const username = params.get("followgate_user");
-    const needsUsername = params.get("followgate_needs_username") === "true";
-    if (token && needsUsername) {
-      this.pendingUsername = {
-        needsUsername: true,
-        token
-      };
-      if (typeof localStorage !== "undefined") {
-        localStorage.setItem(
-          "followgate_pending_username",
-          JSON.stringify(this.pendingUsername)
-        );
-      }
-      const url = new URL(window.location.href);
-      url.searchParams.delete("followgate_token");
-      url.searchParams.delete("followgate_needs_username");
-      window.history.replaceState({}, "", url.toString());
-      if (this.config?.debug) {
-        console.log("[FollowGate] OAuth successful, username input needed");
-      }
-    } else if (token && username) {
-      this.authToken = token;
-      this.currentUser = {
-        userId: "",
-        // Will be set from token verification
-        username,
-        platform: "twitter"
-      };
-      if (typeof localStorage !== "undefined") {
-        localStorage.setItem("followgate_token", token);
-        localStorage.setItem(
-          "followgate_user",
-          JSON.stringify(this.currentUser)
-        );
-      }
-      const url = new URL(window.location.href);
-      url.searchParams.delete("followgate_token");
-      url.searchParams.delete("followgate_user");
-      window.history.replaceState({}, "", url.toString());
-      this.emit("authenticated", this.currentUser);
-      if (this.config?.debug) {
-        console.log("[FollowGate] User authenticated:", username);
-      }
-    }
+  getLikeUrl(platform, target) {
+    return this.buildIntentUrl({ platform, action: "like", target });
   }
   /**
-   * Restore session from localStorage
+   * Open intent URL in new window
    */
-  restoreSession() {
-    if (typeof localStorage === "undefined") return;
-    const pendingJson = localStorage.getItem("followgate_pending_username");
-    if (pendingJson) {
-      try {
-        this.pendingUsername = JSON.parse(pendingJson);
-        if (this.config?.debug) {
-          console.log("[FollowGate] Restored pending username state");
-        }
-        return;
-      } catch {
-        localStorage.removeItem("followgate_pending_username");
-      }
+  async openIntent(options) {
+    if (!this.config) {
+      throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
-    const token = localStorage.getItem("followgate_token");
-    const userJson = localStorage.getItem("followgate_user");
-    if (token && userJson) {
-      try {
-        this.authToken = token;
-        this.currentUser = JSON.parse(userJson);
-      } catch {
-        localStorage.removeItem("followgate_token");
-        localStorage.removeItem("followgate_user");
-      }
+    const url = this.buildIntentUrl(options);
+    if (this.config.debug) {
+      console.log("[FollowGate] Opening intent:", url);
     }
+    await this.trackEvent("intent_opened", { ...options });
+    window.open(url, "_blank", "width=600,height=700");
   }
+  // ============================================
+  // Completion Methods
+  // ============================================
   /**
-   * Open social action popup
+   * Mark an action as completed (trust-first)
+   * Call this when user confirms they did the action
    */
-  async open(options) {
+  async complete(options) {
     if (!this.config) {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
-    const url = this.buildIntentUrl(options);
-    if (this.config.debug) {
-      console.log("[FollowGate] Opening:", url);
+    if (!this.currentUser) {
+      throw new Error(
+        "[FollowGate] No username set. Call setUsername() first."
+      );
     }
-    await this.trackEvent("gate_opened", options);
-    const popup = window.open(url, "_blank", "width=600,height=700");
-    if (!popup) {
-      this.emit("error", { message: "Popup blocked" });
-      return;
+    const alreadyCompleted = this.completedActions.some(
+      (a) => a.platform === options.platform && a.action === options.action && a.target === options.target
+    );
+    if (!alreadyCompleted) {
+      this.completedActions.push(options);
+      this.saveCompletedActions();
     }
-    await this.trackEvent("action_clicked", options);
+    await this.trackEvent("action_completed", {
+      ...options,
+      username: this.currentUser.username
+    });
     this.emit("complete", {
-      platform: options.platform,
-      action: options.action,
-      target: options.target
+      ...options,
+      username: this.currentUser.username
     });
+    if (this.config.debug) {
+      console.log("[FollowGate] Action completed:", options);
+    }
   }
   /**
-   * Verify follow status (for Pro/Business tiers with OAuth)
+   * Mark the gate as unlocked
+   * Call this when all required actions are done
    */
-  async verify(options) {
+  async unlock() {
     if (!this.config) {
       throw new Error("[FollowGate] SDK not initialized. Call init() first.");
     }
-    try {
-      const response = await fetch(`${this.config.apiUrl}/api/v1/verify`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "X-API-Key": this.config.apiKey
-        },
-        body: JSON.stringify({
-          platform: options.platform,
-          action: options.action,
-          target: options.target,
-          externalUserId: options.userId
-        })
-      });
-      const data = await response.json();
-      return data.success && data.data?.verified === true;
-    } catch (error) {
-      if (this.config.debug) {
-        console.error("[FollowGate] Verification error:", error);
-      }
-      return false;
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem("followgate_unlocked", "true");
+    }
+    await this.trackEvent("gate_unlocked", {
+      username: this.currentUser?.username,
+      actions: this.completedActions
+    });
+    this.emit("unlocked", {
+      username: this.currentUser?.username,
+      actions: this.completedActions
+    });
+    if (this.config.debug) {
+      console.log("[FollowGate] Gate unlocked!");
     }
   }
   /**
-   * Track analytics event
+   * Check if gate is unlocked
    */
-  async trackEvent(event, options) {
-    if (!this.config) return;
-    try {
-      await fetch(`${this.config.apiUrl}/api/v1/events`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "X-API-Key": this.config.apiKey
-        },
-        body: JSON.stringify({
-          event,
-          platform: options.platform,
-          action: options.action,
-          target: options.target,
-          externalUserId: options.userId
-        })
-      });
-    } catch (error) {
-      if (this.config.debug) {
-        console.warn("[FollowGate] Failed to track event:", error);
-      }
-    }
+  isUnlocked() {
+    if (typeof localStorage === "undefined") return false;
+    return localStorage.getItem("followgate_unlocked") === "true";
   }
+  /**
+   * Get unlock status with details
+   */
+  getUnlockStatus() {
+    return {
+      unlocked: this.isUnlocked(),
+      username: this.currentUser?.username,
+      completedActions: [...this.completedActions]
+    };
+  }
+  /**
+   * Get completed actions
+   */
+  getCompletedActions() {
+    return [...this.completedActions];
+  }
+  // ============================================
+  // Event System
+  // ============================================
   /**
    * Register event listener
    */
@@ -286,6 +253,42 @@ var FollowGateClient = class {
   off(event, callback) {
     this.listeners.get(event)?.delete(callback);
   }
+  // ============================================
+  // Private Methods
+  // ============================================
+  /**
+   * Restore session from localStorage
+   */
+  restoreSession() {
+    if (typeof localStorage === "undefined") return;
+    const userJson = localStorage.getItem("followgate_user");
+    if (userJson) {
+      try {
+        this.currentUser = JSON.parse(userJson);
+      } catch {
+        localStorage.removeItem("followgate_user");
+      }
+    }
+    const actionsJson = localStorage.getItem("followgate_actions");
+    if (actionsJson) {
+      try {
+        this.completedActions = JSON.parse(actionsJson);
+      } catch {
+        localStorage.removeItem("followgate_actions");
+      }
+    }
+  }
+  /**
+   * Save completed actions to localStorage
+   */
+  saveCompletedActions() {
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem(
+        "followgate_actions",
+        JSON.stringify(this.completedActions)
+      );
+    }
+  }
   /**
    * Build intent URL for platform
    */
@@ -347,6 +350,30 @@ var FollowGateClient = class {
         throw new Error(`[FollowGate] Unsupported LinkedIn action: ${action}`);
     }
   }
+  /**
+   * Track analytics event
+   */
+  async trackEvent(event, data) {
+    if (!this.config) return;
+    try {
+      await fetch(`${this.config.apiUrl}/api/v1/events`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.config.apiKey
+        },
+        body: JSON.stringify({
+          event,
+          appId: this.config.appId,
+          ...data
+        })
+      });
+    } catch (error) {
+      if (this.config.debug) {
+        console.warn("[FollowGate] Failed to track event:", error);
+      }
+    }
+  }
   emit(event, data) {
     this.listeners.get(event)?.forEach((callback) => callback(data));
   }
@@ -354,5 +381,6 @@ var FollowGateClient = class {
 var FollowGate = new FollowGateClient();
 export {
   FollowGate,
-  FollowGateClient
+  FollowGateClient,
+  FollowGateError
 };

package/package.json

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