@followgate/js 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/dist/index.d.mts +74 -50
  2. package/dist/index.d.ts +74 -50
  3. package/dist/index.js +223 -194
  4. package/dist/index.mjs +221 -193
  5. package/package.json +1 -1
package/dist/index.d.mts CHANGED
@@ -16,108 +16,120 @@ interface FollowGateConfig {
16
16
  debug?: boolean;
17
17
  }
18
18
  /**
19
- * Open action options
19
+ * SDK Error class with helpful messages
20
20
  */
21
- interface OpenOptions {
21
+ declare class FollowGateError extends Error {
22
+ code: string;
23
+ hint?: string | undefined;
24
+ constructor(message: string, code: string, hint?: string | undefined);
25
+ }
26
+ /**
27
+ * Complete action options
28
+ */
29
+ interface CompleteOptions {
22
30
  platform: Platform;
23
31
  action: SocialAction;
24
32
  target: string;
25
- userId?: string;
26
33
  }
27
- /**
28
- * LinkedIn target type
29
- */
30
- type LinkedInTargetType = 'company' | 'profile';
31
34
  /**
32
35
  * Event types
33
36
  */
34
- type EventType = 'complete' | 'error' | 'cancel' | 'authenticated';
37
+ type EventType = 'complete' | 'error' | 'unlocked';
35
38
  /**
36
39
  * Event callback
37
40
  */
38
41
  type EventCallback = (data: unknown) => void;
39
42
  /**
40
- * Authenticated user info
43
+ * User info (stored locally)
41
44
  */
42
- interface AuthenticatedUser {
43
- userId: string;
45
+ interface UserInfo {
44
46
  username: string;
45
47
  platform: Platform;
46
48
  }
47
49
  /**
48
- * Auth state when username input is needed
50
+ * Unlock status
49
51
  */
50
- interface PendingUsernameState {
51
- needsUsername: true;
52
- token: string;
53
- }
54
- /**
55
- * Authentication options
56
- */
57
- interface AuthOptions {
58
- /** Where to redirect after auth (defaults to current page) */
59
- redirectUri?: string;
60
- /** Open in popup instead of redirect */
61
- popup?: boolean;
52
+ interface UnlockStatus {
53
+ unlocked: boolean;
54
+ username?: string;
55
+ completedActions?: CompleteOptions[];
62
56
  }
63
57
  /**
64
58
  * FollowGate SDK Client
59
+ *
60
+ * Simple username-based flow:
61
+ * 1. User enters username
62
+ * 2. User clicks intent URLs to follow/repost
63
+ * 3. User confirms they did it
64
+ * 4. App is unlocked
65
+ *
66
+ * No OAuth required!
65
67
  */
66
68
  declare class FollowGateClient {
67
69
  private config;
68
70
  private listeners;
69
71
  private currentUser;
70
- private authToken;
71
- private pendingUsername;
72
+ private completedActions;
72
73
  /**
73
74
  * Initialize the SDK
75
+ * @throws {FollowGateError} If configuration is invalid
74
76
  */
75
77
  init(config: FollowGateConfig): void;
76
78
  /**
77
- * Authenticate user via Twitter OAuth (handled by FollowGate)
78
- * This identifies WHO is completing the social actions.
79
+ * Set the user's social username
80
+ * This is the main entry point - no OAuth needed!
79
81
  */
80
- authenticate(options?: AuthOptions): void;
82
+ setUsername(username: string, platform?: Platform): void;
81
83
  /**
82
- * Get current authenticated user
84
+ * Get current user
83
85
  */
84
- getUser(): AuthenticatedUser | null;
86
+ getUser(): UserInfo | null;
85
87
  /**
86
- * Check if user is authenticated
88
+ * Check if username is set
87
89
  */
88
- isAuthenticated(): boolean;
90
+ hasUsername(): boolean;
89
91
  /**
90
- * Logout - clear stored session
92
+ * Clear stored session
91
93
  */
92
- logout(): void;
94
+ reset(): void;
93
95
  /**
94
- * Check if username input is needed (Twitter Free Tier limitation)
96
+ * Get follow intent URL for a platform
95
97
  */
96
- needsUsernameInput(): boolean;
98
+ getFollowUrl(platform: Platform, target: string): string;
97
99
  /**
98
- * Set username manually (when needsUsernameInput() returns true)
100
+ * Get repost/retweet intent URL for a platform
99
101
  */
100
- setUsername(username: string): void;
102
+ getRepostUrl(platform: Platform, target: string): string;
101
103
  /**
102
- * Handle auth callback from URL params
104
+ * Get like intent URL for a platform
103
105
  */
104
- private handleAuthCallback;
106
+ getLikeUrl(platform: Platform, target: string): string;
105
107
  /**
106
- * Restore session from localStorage
108
+ * Open intent URL in new window
107
109
  */
108
- private restoreSession;
110
+ openIntent(options: CompleteOptions): Promise<void>;
109
111
  /**
110
- * Open social action popup
112
+ * Mark an action as completed (trust-first)
113
+ * Call this when user confirms they did the action
111
114
  */
112
- open(options: OpenOptions): Promise<void>;
115
+ complete(options: CompleteOptions): Promise<void>;
113
116
  /**
114
- * Verify follow status (for Pro/Business tiers with OAuth)
117
+ * Mark the gate as unlocked
118
+ * Call this when all required actions are done
115
119
  */
116
- verify(options: OpenOptions): Promise<boolean>;
120
+ unlock(): Promise<void>;
117
121
  /**
118
- * Track analytics event
122
+ * Check if gate is unlocked
119
123
  */
120
- private trackEvent;
124
+ isUnlocked(): boolean;
125
+ /**
126
+ * Get unlock status with details
127
+ */
128
+ getUnlockStatus(): UnlockStatus;
129
+ /**
130
+ * Get completed actions
131
+ */
132
+ getCompletedActions(): CompleteOptions[];
121
133
  /**
122
134
  * Register event listener
123
135
  */
@@ -126,6 +138,14 @@ declare class FollowGateClient {
126
138
  * Remove event listener
127
139
  */
128
140
  off(event: EventType, callback: EventCallback): void;
141
+ /**
142
+ * Restore session from localStorage
143
+ */
144
+ private restoreSession;
145
+ /**
146
+ * Save completed actions to localStorage
147
+ */
148
+ private saveCompletedActions;
129
149
  /**
130
150
  * Build intent URL for platform
131
151
  */
@@ -133,8 +153,12 @@ declare class FollowGateClient {
133
153
  private buildTwitterUrl;
134
154
  private buildBlueskyUrl;
135
155
  private buildLinkedInUrl;
156
+ /**
157
+ * Track analytics event
158
+ */
159
+ private trackEvent;
136
160
  private emit;
137
161
  }
138
162
  declare const FollowGate: FollowGateClient;
139
163
 
140
- export { type AuthOptions, type AuthenticatedUser, type EventCallback, type EventType, FollowGate, FollowGateClient, type FollowGateConfig, type LinkedInTargetType, type OpenOptions, type PendingUsernameState, type Platform, type SocialAction };
164
+ export { type CompleteOptions, type EventCallback, type EventType, FollowGate, FollowGateClient, type FollowGateConfig, FollowGateError, type Platform, type SocialAction, type UnlockStatus, type UserInfo };
package/dist/index.d.ts CHANGED
@@ -16,108 +16,120 @@ interface FollowGateConfig {
16
16
  debug?: boolean;
17
17
  }
18
18
  /**
19
- * Open action options
19
+ * SDK Error class with helpful messages
20
20
  */
21
- interface OpenOptions {
21
+ declare class FollowGateError extends Error {
22
+ code: string;
23
+ hint?: string | undefined;
24
+ constructor(message: string, code: string, hint?: string | undefined);
25
+ }
26
+ /**
27
+ * Complete action options
28
+ */
29
+ interface CompleteOptions {
22
30
  platform: Platform;
23
31
  action: SocialAction;
24
32
  target: string;
25
- userId?: string;
26
33
  }
27
- /**
28
- * LinkedIn target type
29
- */
30
- type LinkedInTargetType = 'company' | 'profile';
31
34
  /**
32
35
  * Event types
33
36
  */
34
- type EventType = 'complete' | 'error' | 'cancel' | 'authenticated';
37
+ type EventType = 'complete' | 'error' | 'unlocked';
35
38
  /**
36
39
  * Event callback
37
40
  */
38
41
  type EventCallback = (data: unknown) => void;
39
42
  /**
40
- * Authenticated user info
43
+ * User info (stored locally)
41
44
  */
42
- interface AuthenticatedUser {
43
- userId: string;
45
+ interface UserInfo {
44
46
  username: string;
45
47
  platform: Platform;
46
48
  }
47
49
  /**
48
- * Auth state when username input is needed
50
+ * Unlock status
49
51
  */
50
- interface PendingUsernameState {
51
- needsUsername: true;
52
- token: string;
53
- }
54
- /**
55
- * Authentication options
56
- */
57
- interface AuthOptions {
58
- /** Where to redirect after auth (defaults to current page) */
59
- redirectUri?: string;
60
- /** Open in popup instead of redirect */
61
- popup?: boolean;
52
+ interface UnlockStatus {
53
+ unlocked: boolean;
54
+ username?: string;
55
+ completedActions?: CompleteOptions[];
62
56
  }
63
57
  /**
64
58
  * FollowGate SDK Client
59
+ *
60
+ * Simple username-based flow:
61
+ * 1. User enters username
62
+ * 2. User clicks intent URLs to follow/repost
63
+ * 3. User confirms they did it
64
+ * 4. App is unlocked
65
+ *
66
+ * No OAuth required!
65
67
  */
66
68
  declare class FollowGateClient {
67
69
  private config;
68
70
  private listeners;
69
71
  private currentUser;
70
- private authToken;
71
- private pendingUsername;
72
+ private completedActions;
72
73
  /**
73
74
  * Initialize the SDK
75
+ * @throws {FollowGateError} If configuration is invalid
74
76
  */
75
77
  init(config: FollowGateConfig): void;
76
78
  /**
77
- * Authenticate user via Twitter OAuth (handled by FollowGate)
78
- * This identifies WHO is completing the social actions.
79
+ * Set the user's social username
80
+ * This is the main entry point - no OAuth needed!
79
81
  */
80
- authenticate(options?: AuthOptions): void;
82
+ setUsername(username: string, platform?: Platform): void;
81
83
  /**
82
- * Get current authenticated user
84
+ * Get current user
83
85
  */
84
- getUser(): AuthenticatedUser | null;
86
+ getUser(): UserInfo | null;
85
87
  /**
86
- * Check if user is authenticated
88
+ * Check if username is set
87
89
  */
88
- isAuthenticated(): boolean;
90
+ hasUsername(): boolean;
89
91
  /**
90
- * Logout - clear stored session
92
+ * Clear stored session
91
93
  */
92
- logout(): void;
94
+ reset(): void;
93
95
  /**
94
- * Check if username input is needed (Twitter Free Tier limitation)
96
+ * Get follow intent URL for a platform
95
97
  */
96
- needsUsernameInput(): boolean;
98
+ getFollowUrl(platform: Platform, target: string): string;
97
99
  /**
98
- * Set username manually (when needsUsernameInput() returns true)
100
+ * Get repost/retweet intent URL for a platform
99
101
  */
100
- setUsername(username: string): void;
102
+ getRepostUrl(platform: Platform, target: string): string;
101
103
  /**
102
- * Handle auth callback from URL params
104
+ * Get like intent URL for a platform
103
105
  */
104
- private handleAuthCallback;
106
+ getLikeUrl(platform: Platform, target: string): string;
105
107
  /**
106
- * Restore session from localStorage
108
+ * Open intent URL in new window
107
109
  */
108
- private restoreSession;
110
+ openIntent(options: CompleteOptions): Promise<void>;
109
111
  /**
110
- * Open social action popup
112
+ * Mark an action as completed (trust-first)
113
+ * Call this when user confirms they did the action
111
114
  */
112
- open(options: OpenOptions): Promise<void>;
115
+ complete(options: CompleteOptions): Promise<void>;
113
116
  /**
114
- * Verify follow status (for Pro/Business tiers with OAuth)
117
+ * Mark the gate as unlocked
118
+ * Call this when all required actions are done
115
119
  */
116
- verify(options: OpenOptions): Promise<boolean>;
120
+ unlock(): Promise<void>;
117
121
  /**
118
- * Track analytics event
122
+ * Check if gate is unlocked
119
123
  */
120
- private trackEvent;
124
+ isUnlocked(): boolean;
125
+ /**
126
+ * Get unlock status with details
127
+ */
128
+ getUnlockStatus(): UnlockStatus;
129
+ /**
130
+ * Get completed actions
131
+ */
132
+ getCompletedActions(): CompleteOptions[];
121
133
  /**
122
134
  * Register event listener
123
135
  */
@@ -126,6 +138,14 @@ declare class FollowGateClient {
126
138
  * Remove event listener
127
139
  */
128
140
  off(event: EventType, callback: EventCallback): void;
141
+ /**
142
+ * Restore session from localStorage
143
+ */
144
+ private restoreSession;
145
+ /**
146
+ * Save completed actions to localStorage
147
+ */
148
+ private saveCompletedActions;
129
149
  /**
130
150
  * Build intent URL for platform
131
151
  */
@@ -133,8 +153,12 @@ declare class FollowGateClient {
133
153
  private buildTwitterUrl;
134
154
  private buildBlueskyUrl;
135
155
  private buildLinkedInUrl;
156
+ /**
157
+ * Track analytics event
158
+ */
159
+ private trackEvent;
136
160
  private emit;
137
161
  }
138
162
  declare const FollowGate: FollowGateClient;
139
163
 
140
- export { type AuthOptions, type AuthenticatedUser, type EventCallback, type EventType, FollowGate, FollowGateClient, type FollowGateConfig, type LinkedInTargetType, type OpenOptions, type PendingUsernameState, type Platform, type SocialAction };
164
+ export { type CompleteOptions, type EventCallback, type EventType, FollowGate, FollowGateClient, type FollowGateConfig, FollowGateError, type Platform, type SocialAction, type UnlockStatus, type UserInfo };