> ## 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.

# Auto Protect

> Automatically protect pages based on URL patterns

Auto Protect automatically enforces access control on pages matching configured URL patterns, without requiring code changes on each page.

## Quick Setup

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

// Protect current page
autoProtectPage({
  loginUrl: '/login',
  upgradeUrl: '/upgrade'
})
```

## Configuration

### Basic Configuration

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

const autoProtect = createAutoProtect({
  // URL patterns to protect
  patterns: [
    { pattern: '/dashboard/*', requireAuth: true },
    { pattern: '/premium/*', requirePlan: 'pro' },
    { pattern: '/admin/*', requirePlan: 'enterprise' }
  ],
  
  // Redirect URLs
  loginUrl: '/login',
  upgradeUrl: '/upgrade',
  
  // Options
  checkOnLoad: true,
  showLoadingState: true
})
```

### Pattern Options

```typescript theme={null}
interface ProtectionPattern {
  pattern: string           // URL pattern to match
  requireAuth?: boolean     // Require authentication
  requirePlan?: string      // Require specific plan
  requirePlans?: string[]   // Require one of these plans
  redirectUrl?: string      // Custom redirect for this pattern
  allowedRoles?: string[]   // Require specific roles
}
```

## URL Patterns

| Pattern        | Description     | Examples                              |
| -------------- | --------------- | ------------------------------------- |
| `/exact`       | Exact match     | `/dashboard`                          |
| `/path/*`      | Wildcard suffix | `/courses/intro`, `/courses/advanced` |
| `/path/*/edit` | Wildcard middle | `/posts/123/edit`                     |
| `*.pdf`        | File extension  | `/docs/guide.pdf`                     |

## Usage Examples

### Protect Dashboard

```javascript theme={null}
createAutoProtect({
  patterns: [
    { pattern: '/dashboard', requireAuth: true },
    { pattern: '/dashboard/*', requireAuth: true }
  ],
  loginUrl: '/login'
})
```

### Plan-Based Protection

```javascript theme={null}
createAutoProtect({
  patterns: [
    { pattern: '/free/*', requireAuth: true },
    { pattern: '/pro/*', requirePlan: 'pro' },
    { pattern: '/enterprise/*', requirePlan: 'enterprise' }
  ],
  upgradeUrl: '/pricing'
})
```

### Multiple Plans

```javascript theme={null}
createAutoProtect({
  patterns: [
    { 
      pattern: '/premium/*', 
      requirePlans: ['pro', 'business', 'enterprise']
    }
  ]
})
```

## React Integration

### With Router

```jsx theme={null}
import { useEffect } from 'react'
import { useLocation } from 'react-router-dom'
import { useAutoProtect } from '@gately/sdk'

function App() {
  const location = useLocation()
  const { checkAccess, isChecking } = useAutoProtect({
    patterns: [
      { pattern: '/dashboard/*', requireAuth: true }
    ]
  })

  useEffect(() => {
    checkAccess(location.pathname)
  }, [location.pathname])

  if (isChecking) {
    return <LoadingScreen />
  }

  return <Routes />
}
```

### Protected Route Component

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

function App() {
  return (
    <AutoProtect
      patterns={[
        { pattern: '/dashboard/*', requireAuth: true },
        { pattern: '/premium/*', requirePlan: 'pro' }
      ]}
      loginUrl="/login"
      upgradeUrl="/upgrade"
      loadingComponent={<Spinner />}
    >
      <Router>
        <Routes />
      </Router>
    </AutoProtect>
  )
}
```

## Event Handlers

```javascript theme={null}
createAutoProtect({
  patterns: [...],
  
  onAccessGranted: (pattern, user) => {
    console.log('Access granted to:', pattern)
    analytics.track('page_access', { pattern })
  },
  
  onAccessDenied: (pattern, reason, user) => {
    console.log('Access denied:', reason)
    
    if (reason === 'not_authenticated') {
      // Custom login redirect with return URL
      window.location.href = `/login?return=${encodeURIComponent(window.location.href)}`
      return false // Prevent default redirect
    }
    
    return true // Allow default redirect
  },
  
  onRedirect: (url) => {
    console.log('Redirecting to:', url)
  }
})
```

## Loading States

### Show Loading While Checking

```javascript theme={null}
createAutoProtect({
  patterns: [...],
  showLoadingState: true,
  loadingSelector: '#app', // Element to show loading state
  loadingClass: 'is-loading' // Class to add during check
})
```

### Custom Loading UI

```javascript theme={null}
createAutoProtect({
  patterns: [...],
  onCheckStart: () => {
    document.getElementById('loader').style.display = 'block'
  },
  onCheckComplete: () => {
    document.getElementById('loader').style.display = 'none'
  }
})
```

## Caching

Access checks are cached to improve performance:

```javascript theme={null}
createAutoProtect({
  patterns: [...],
  cacheTimeout: 5 * 60 * 1000 // 5 minutes (default)
})
```

To clear cache:

```javascript theme={null}
autoProtect.clearCache()
```

## Server-Side Rendering

For SSR frameworks, check access on the server:

```javascript theme={null}
// Next.js middleware
import { NextResponse } from 'next/server'

export function middleware(request) {
  const token = request.cookies.get('gately_auth_token')
  
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    if (!token) {
      return NextResponse.redirect(new URL('/login', request.url))
    }
  }
  
  return NextResponse.next()
}
```

## Debugging

Enable debug mode:

```javascript theme={null}
createAutoProtect({
  patterns: [...],
  debug: true
})
```

This logs:

* Pattern matching results
* Access check outcomes
* Redirect decisions

## Best Practices

<AccordionGroup>
  <Accordion title="Order Patterns Specifically">
    More specific patterns should come before general ones.
  </Accordion>

  <Accordion title="Use Consistent URLs">
    Ensure your login and upgrade URLs are consistent across patterns.
  </Accordion>

  <Accordion title="Handle Edge Cases">
    Consider what happens when users navigate directly to protected URLs.
  </Accordion>

  <Accordion title="Test Thoroughly">
    Test all patterns with different user states (logged out, free, pro, etc.).
  </Accordion>
</AccordionGroup>