> ## Documentation Index
> Fetch the complete documentation index at: https://usegately.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Signup

> Create new user accounts

## Basic Signup

```javascript theme={null}
const { user, session } = await gately.signup(email, password, metadata)
```

### Parameters

| Parameter  | Type   | Required | Description                   |
| ---------- | ------ | -------- | ----------------------------- |
| `email`    | string | Yes      | User's email address          |
| `password` | string | Yes      | User's password (min 8 chars) |
| `metadata` | object | No       | Additional user data          |

### Metadata Options

```typescript theme={null}
interface SignupMetadata {
  full_name?: string
  avatar_url?: string
  [key: string]: any  // Custom fields
}
```

## Example

```javascript theme={null}
import { GatelyClient } from '@gately/sdk'

const gately = new GatelyClient('YOUR_PROJECT_ID')

async function handleSignup(email, password, name) {
  try {
    const { user, session } = await gately.signup(email, password, {
      full_name: name,
      // Add any custom fields
      company: 'Acme Inc',
      role: 'Developer'
    })
    
    console.log('Account created:', user.email)
    window.location.href = '/welcome'
  } catch (error) {
    console.error('Signup failed:', error.message)
  }
}
```

## Password Requirements

Passwords must meet these requirements:

* Minimum 8 characters
* At least one uppercase letter (A-Z)
* At least one lowercase letter (a-z)
* At least one number (0-9)

```javascript theme={null}
// This will fail
await gately.signup('user@example.com', 'weak')
// Error: Password must be at least 8 characters long

// This will succeed
await gately.signup('user@example.com', 'SecurePass123!')
```

## React Hook

```jsx theme={null}
import { useGately } from '@gately/sdk'

function SignupForm() {
  const { signup } = useGately()
  const [formData, setFormData] = useState({
    email: '',
    password: '',
    confirmPassword: '',
    fullName: ''
  })
  const [error, setError] = useState('')

  const handleSubmit = async (e) => {
    e.preventDefault()
    
    if (formData.password !== formData.confirmPassword) {
      setError('Passwords do not match')
      return
    }

    try {
      await signup(formData.email, formData.password, {
        full_name: formData.fullName
      })
    } catch (err) {
      setError(err.message)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {error && <p className="error">{error}</p>}
      
      <input 
        type="text"
        value={formData.fullName}
        onChange={(e) => setFormData({ ...formData, fullName: e.target.value })}
        placeholder="Full Name"
      />
      
      <input 
        type="email"
        value={formData.email}
        onChange={(e) => setFormData({ ...formData, email: e.target.value })}
        placeholder="Email"
        required
      />
      
      <input 
        type="password"
        value={formData.password}
        onChange={(e) => setFormData({ ...formData, password: e.target.value })}
        placeholder="Password"
        required
      />
      
      <input 
        type="password"
        value={formData.confirmPassword}
        onChange={(e) => setFormData({ ...formData, confirmPassword: e.target.value })}
        placeholder="Confirm Password"
        required
      />
      
      <button type="submit">Create Account</button>
    </form>
  )
}
```

## Error Handling

Common signup errors:

| Error                                    | Description                         |
| ---------------------------------------- | ----------------------------------- |
| `Invalid email format`                   | Email doesn't match expected format |
| `Password must be at least 8 characters` | Password too short                  |
| `Password must contain uppercase letter` | Missing uppercase                   |
| `Password must contain lowercase letter` | Missing lowercase                   |
| `Password must contain a number`         | Missing number                      |
| `Email already registered`               | Account exists                      |

```javascript theme={null}
try {
  await gately.signup(email, password, metadata)
} catch (error) {
  if (error.message.includes('already registered')) {
    showError('An account with this email already exists. Try logging in.')
  } else if (error.message.includes('Password')) {
    showError(error.message) // Show password requirement
  } else {
    showError('Signup failed. Please try again.')
  }
}
```

## Email Verification

If email verification is enabled in your project settings:

```javascript theme={null}
const { user } = await gately.signup(email, password)

// User is created but not verified
console.log(user.status) // 'pending'

// User receives verification email
// After clicking link, status becomes 'active'
```

## Webhooks

When a user signs up, the `member.created` webhook is triggered:

```json theme={null}
{
  "event": "member.created",
  "data": {
    "id": "mem_xyz",
    "email": "user@example.com",
    "full_name": "John Doe",
    "plan_id": "free",
    "status": "active",
    "metadata": {
      "company": "Acme Inc"
    },
    "created_at": "2024-01-15T10:00:00Z"
  }
}
```

## Default Plan

New users are assigned to the default plan configured in your project settings. To assign a specific plan:

```javascript theme={null}
// Via API (server-side)
await fetch('/api/members/' + user.id, {
  method: 'PUT',
  body: JSON.stringify({ plan_id: 'pro' })
})
```