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>
}
id
string
required
Unique user identifier (UUID)
email
string
required
User’s email address
name
string
User’s display name
avatar_url
string
URL to user’s profile picture
created_at
string
required
ISO timestamp when user was created
project_id
string
Project ID the user belongs to
last_sign_in_at
string
ISO timestamp of last sign in
user_metadata
Record<string, any>
Custom user metadata (editable by user)
app_metadata
Record<string, any>
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
}
access_token
string
required
JWT access token for API requests
refresh_token
string
required
Token used to refresh the access token
expires_at
number
required
Unix timestamp when access token expires
user
User
required
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>
}
id
string
required
Unique user identifier
email
string
required
User’s email address
first_name
string
User’s first name
last_name
string
User’s last name
display_name
string
User’s preferred display name
avatar_url
string
URL to user’s profile picture
bio
string
User’s biography or description
phone
string
User’s phone number
website
string
User’s website URL
location
string
User’s location or address
company
string
User’s company or organization
job_title
string
User’s job title or role
created_at
string
required
ISO timestamp when profile was created
updated_at
string
required
ISO timestamp when profile was last updated
user_metadata
Record<string, any>
Custom user metadata

Request Types

AuthResponse

Response object returned by authentication methods.
interface AuthResponse {
  user: User
  session: Session
  project_id?: string
}
user
User
required
Authenticated user object
session
Session
required
Active session with tokens
project_id
string
Project ID for the authentication

SignupMetadata

Optional metadata provided during user signup.
interface SignupMetadata {
  tier?: string
  role?: string
  name?: string
  [key: string]: any
}
tier
string
User’s plan tier (e.g., ‘basic’, ‘premium’)
role
string
User’s role (e.g., ‘user’, ‘admin’)
name
string
User’s display name
[key: string]
any
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
}
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
popupOptions
PopupOptions
Configuration for popup window

PopupOptions

Configuration for OAuth popup windows.
interface PopupOptions {
  width?: number
  height?: number
  scrollbars?: boolean
  resizable?: boolean
  left?: number
  top?: number
}
width
number
default:"500"
Popup width in pixels
height
number
default:"600"
Popup height in pixels
scrollbars
boolean
default:"true"
Show scrollbars in popup
resizable
boolean
default:"true"
Allow popup resizing
left
number
Popup left position (auto-centered if not specified)
top
number
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
autoRefresh
boolean
default:"true"
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>
}
hideIfLoggedOut
boolean
default:"false"
Hide element when user is not authenticated
hideIfLoggedIn
boolean
default:"false"
Hide element when user is authenticated
showLoader
boolean
default:"false"
Show loading state while checking authentication
customClass
string
CSS class to add based on authentication state
customStyle
Record<string, string>
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
string
required
Unique plan identifier
user_id
string
required
ID of the user this plan belongs to
tier
string
required
Plan tier (e.g., ‘basic’, ‘premium’, ‘enterprise’)
features
string[]
required
List of features included in this plan
billing_cycle
'monthly' | 'yearly'
Billing frequency
next_billing_date
string
ISO timestamp of next billing date
status
'active' | 'cancelled' | 'past_due'
required
Current plan status
created_at
string
required
ISO timestamp when plan was created
updated_at
string
required
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
}
code
string
required
Error code identifying the type of error
status
number
HTTP status code (if applicable)
details
any
Additional error details

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'

Form Types

FormSubmissionRequest

Request object for form submissions.
interface FormSubmissionRequest {
  formId: string
  data: Record<string, any>
  metadata?: Record<string, any>
}
formId
string
required
Unique identifier for the form
data
Record<string, any>
required
Form data to submit
metadata
Record<string, any>
Additional metadata about the submission

FormSubmissionResponse

Response object from form submissions.
interface FormSubmissionResponse {
  success: boolean
  submission_id: string
  redirect_url?: string
}
success
boolean
required
Whether the form submission was successful
submission_id
string
required
Unique identifier for the submission
redirect_url
string
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