Complete TypeScript interfaces and types for the Gately SDK.
Core Types
User
Represents an authenticated user in the system.
interface User {
id: string
email: string
name?: string
avatar_url?: string
created_at: string
project_id?: string
last_sign_in_at?: string
user_metadata?: Record<string, any>
app_metadata?: Record<string, any>
}
Unique user identifier (UUID)
URL to user’s profile picture
ISO timestamp when user was created
Project ID the user belongs to
ISO timestamp of last sign in
Custom user metadata (editable by user)
Application metadata (read-only for user)
Session
Represents an active user session with authentication tokens.
interface Session {
access_token: string
refresh_token: string
expires_at: number
user: User
}
JWT access token for API requests
Token used to refresh the access token
Unix timestamp when access token expires
User object associated with this session
UserProfile
Extended user profile information with additional fields.
interface UserProfile {
id: string
email: string
first_name?: string
last_name?: string
display_name?: string
avatar_url?: string
bio?: string
phone?: string
website?: string
location?: string
company?: string
job_title?: string
created_at: string
updated_at: string
user_metadata?: Record<string, any>
}
User’s preferred display name
URL to user’s profile picture
User’s biography or description
User’s location or address
User’s company or organization
ISO timestamp when profile was created
ISO timestamp when profile was last updated
Request Types
AuthResponse
Response object returned by authentication methods.
interface AuthResponse {
user: User
session: Session
project_id?: string
}
Authenticated user object
Active session with tokens
Project ID for the authentication
Optional metadata provided during user signup.
interface SignupMetadata {
tier?: string
role?: string
name?: string
[key: string]: any
}
User’s plan tier (e.g., ‘basic’, ‘premium’)
User’s role (e.g., ‘user’, ‘admin’)
Additional custom metadata fields
UpdateProfileRequest
Request object for updating user profiles.
interface UpdateProfileRequest {
first_name?: string
last_name?: string
display_name?: string
avatar_url?: string
bio?: string
phone?: string
website?: string
location?: string
company?: string
job_title?: string
user_metadata?: Record<string, any>
}
All fields are optional and only provided fields will be updated.
LoginOptions
Options for magic link and password reset operations.
interface LoginOptions {
redirectTo?: string
}
URL to redirect to after successful authentication
SSO Types
SSOOptions
Configuration options for OAuth authentication.
interface SSOOptions {
mode?: 'popup' | 'redirect'
redirectUrl?: string
popupOptions?: PopupOptions
}
mode
'popup' | 'redirect'
default:"'popup'"
Authentication mode
redirectUrl
string
default:"window.location.href"
URL to redirect to after authentication
Configuration for popup window
Configuration for OAuth popup windows.
interface PopupOptions {
width?: number
height?: number
scrollbars?: boolean
resizable?: boolean
left?: number
top?: number
}
Popup left position (auto-centered if not specified)
Popup top position (auto-centered if not specified)
Configuration Types
GatelyOptions
Configuration options for the Gately client.
interface GatelyOptions {
apiUrl?: string
autoRefresh?: boolean
}
apiUrl
string
default:"https://sdk.usegately.com"
Custom API URL for the Gately service
Automatically refresh tokens when they expire
UI Control Types
UIControlOptions
Options for controlling UI element visibility based on authentication state.
interface UIControlOptions {
hideIfLoggedOut?: boolean
hideIfLoggedIn?: boolean
showLoader?: boolean
customClass?: string
customStyle?: Record<string, string>
}
Hide element when user is not authenticated
Hide element when user is authenticated
Show loading state while checking authentication
CSS class to add based on authentication state
CSS styles to apply based on authentication state
Plan Management Types
UserPlan
Represents a user’s subscription plan.
interface UserPlan {
id: string
user_id: string
tier: string
features: string[]
billing_cycle?: 'monthly' | 'yearly'
next_billing_date?: string
status: 'active' | 'cancelled' | 'past_due'
created_at: string
updated_at: string
}
ID of the user this plan belongs to
Plan tier (e.g., ‘basic’, ‘premium’, ‘enterprise’)
List of features included in this plan
ISO timestamp of next billing date
status
'active' | 'cancelled' | 'past_due'
required
Current plan status
ISO timestamp when plan was created
ISO timestamp when plan was last updated
React Hook Types
UseGatelyReturn
Return type for the useGately
React hook.
interface UseGatelyReturn {
user: User | null
session: Session | null
profile: UserProfile | null
loading: boolean
error: string | null
login: (email: string, password: string) => Promise<AuthResponse>
signup: (email: string, password: string, metadata?: SignupMetadata) => Promise<AuthResponse>
loginWithGoogle: (options?: SSOOptions) => Promise<void>
loginWithGithubSSO: (options?: SSOOptions) => Promise<void>
logout: () => Promise<void>
sendMagicLink: (email: string, options?: LoginOptions) => Promise<void>
resetPassword: (email: string) => Promise<void>
getUserProfile: () => Promise<UserProfile | null>
updateUserProfile: (updates: UpdateProfileRequest) => Promise<UserProfile | null>
changePassword: (currentPassword: string, newPassword: string) => Promise<boolean>
deleteAccount: () => Promise<boolean>
getUserPlan: () => Promise<UserPlan | null>
updateUserPlan: (planId: string) => Promise<UserPlan>
hasFeatureAccess: (featureName: string) => Promise<boolean>
client: GatelyBrowserClient
}
Error Types
GatelyError
Base error type for all SDK errors.
interface GatelyError extends Error {
code: string
status?: number
details?: any
}
Error code identifying the type of error
HTTP status code (if applicable)
Common Error Codes
type ErrorCode =
| 'INVALID_CREDENTIALS'
| 'USER_NOT_FOUND'
| 'EMAIL_NOT_CONFIRMED'
| 'RATE_LIMITED'
| 'NETWORK_ERROR'
| 'INVALID_PROJECT_ID'
| 'PROFILE_NOT_FOUND'
| 'INVALID_PROFILE_DATA'
| 'PROFILE_UPDATE_FAILED'
| 'INVALID_CURRENT_PASSWORD'
| 'WEAK_PASSWORD'
| 'PASSWORD_CHANGE_FAILED'
| 'ACCOUNT_DELETION_FAILED'
| 'OAUTH_CANCELLED'
| 'OAUTH_ERROR'
| 'POPUP_BLOCKED'
| 'PROVIDER_NOT_CONFIGURED'
| 'INVALID_REDIRECT_URL'
Request object for form submissions.
interface FormSubmissionRequest {
formId: string
data: Record<string, any>
metadata?: Record<string, any>
}
Unique identifier for the form
data
Record<string, any>
required
Form data to submit
Additional metadata about the submission
Response object from form submissions.
interface FormSubmissionResponse {
success: boolean
submission_id: string
redirect_url?: string
}
Whether the form submission was successful
Unique identifier for the submission
URL to redirect to after submission
Usage Examples
Type Guards
function isUser(obj: any): obj is User {
return obj && typeof obj.id === 'string' && typeof obj.email === 'string'
}
function isSession(obj: any): obj is Session {
return obj && typeof obj.access_token === 'string' && isUser(obj.user)
}
// Usage
const user = gately.getUser()
if (isUser(user)) {
// TypeScript knows user is of type User
console.log(user.email)
}
Generic Error Handling
function handleGatelyError(error: GatelyError): string {
switch (error.code) {
case 'INVALID_CREDENTIALS':
return 'Invalid email or password'
case 'USER_NOT_FOUND':
return 'No account found with this email'
case 'RATE_LIMITED':
return 'Too many attempts. Please try again later'
default:
return error.message || 'An unexpected error occurred'
}
}
Next Steps