@stacksjs/defaults 0.70.206 → 0.70.208

package/ai/skills/stacks-sms/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: stacks-sms
+description: Use when implementing SMS in Stacks — sending text messages, the SmsBuilder fluent API, SMS templates, phone verification (OTP/2FA), bulk sending, Twilio/Vonage drivers, E.164 formatting, or the SMS facade. Covers @stacksjs/sms and config/sms.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks SMS
+
+Multi-driver SMS system with verification (OTP), templates, bulk sending, and a fluent builder API. Two fully implemented drivers: Twilio and Vonage.
+
+## Key Paths
+- Core package: `storage/framework/core/sms/src/`
+- SMS facade and builder: `storage/framework/core/sms/src/sms.ts`
+- Twilio driver: `storage/framework/core/sms/src/drivers/twilio.ts`
+- Vonage driver: `storage/framework/core/sms/src/drivers/vonage.ts`
+- Drivers index: `storage/framework/core/sms/src/drivers/index.ts`
+- Configuration: `config/sms.ts`
+
+## Package Exports
+
+```typescript
+// Main facade and functions
+import SMS, { sms, send, sendSms, sendBulk, sendTemplate } from '@stacksjs/sms'
+import { startVerification, checkVerification, cancelVerification } from '@stacksjs/sms'
+import { formatE164, isValidPhoneNumber, isEnabled, getConfig, configure, getDriver, init } from '@stacksjs/sms'
+import { SmsBuilder } from '@stacksjs/sms'
+
+// Drivers
+import { TwilioDriver, createTwilioDriver } from '@stacksjs/sms'
+import { VonageDriver, createVonageDriver } from '@stacksjs/sms'
+```
+
+## SMS Facade Object
+
+The `SMS` default export aggregates all functions:
+
+```typescript
+SMS.init()                    // Load config from config/sms.ts
+SMS.configure(config)         // Override config at runtime
+SMS.isEnabled()               // Check if SMS is enabled (config.enabled)
+SMS.getConfig()               // Get current config (returns copy)
+
+SMS.send(message)             // Send single SMS
+SMS.sendSms(message)          // Alias for send
+SMS.sendBulk(messages)        // Send multiple SMS
+SMS.sendTemplate(to, name, vars)  // Send using template
+
+SMS.getStatus(messageId)      // Get delivery status
+SMS.getBalance()              // Get account balance
+SMS.verifyNumber(phone)       // Lookup/verify phone number
+
+SMS.startVerification(req)    // Start OTP flow
+SMS.checkVerification(req)    // Verify OTP code
+SMS.cancelVerification(id)    // Cancel pending verification
+
+SMS.formatE164(phone, cc?)    // Format to E.164
+SMS.isValidPhoneNumber(phone) // Validate E.164 format
+
+SMS.sms()                     // Create SmsBuilder instance
+SMS.getDriver(provider?)      // Get driver instance
+SMS.getVerificationDriver(p?) // Get verification driver
+```
+
+## SmsBuilder (Fluent API)
+
+```typescript
+import { sms } from '@stacksjs/sms'
+
+// Basic SMS
+await sms()
+  .to('+1234567890')
+  .body('Your code is 123456')
+  .from('+0987654321')
+  .send()
+
+// With provider selection
+await sms()
+  .to('+1234567890')
+  .body('Hello!')
+  .via('vonage')
+  .send()
+
+// MMS with media and callback
+await sms()
+  .to(['+1111111111', '+2222222222'])
+  .body('Check this out')
+  .media(['https://example.com/image.jpg'])
+  .callback('https://myapp.com/sms/status')
+  .send()
+
+// .text() is an alias for .body()
+await sms()
+  .to('+1234567890')
+  .text('Hello!')
+  .send()
+```
+
+The builder validates that `to` and `body` are set before sending. If missing, it returns a failed `SmsSendResult` without throwing. If `.via(provider)` is set, it creates a new driver for that provider; otherwise uses the default driver.
+
+## Direct Send Functions
+
+```typescript
+import { send, sendBulk } from '@stacksjs/sms'
+
+// SmsMessage shape
+await send({
+  to: '+1234567890',         // string or string[]
+  body: 'Hello!',
+  from: '+0987654321',       // optional, falls back to config
+  mediaUrls: ['url'],        // optional, for MMS
+  statusCallback: 'url',     // optional, webhook for status updates
+})
+
+// Bulk send
+await sendBulk([msg1, msg2, msg3])  // returns SmsSendResult[]
+```
+
+`send()` and all sending functions call `ensureConfig()` first, which lazily loads `config/sms.ts` via dynamic import.
+
+## Message Status & Info
+
+```typescript
+import { getStatus, verifyNumber, getBalance } from '@stacksjs/sms'
+
+// Get delivery status for a message
+const status = await getStatus('SM_message_id')
+// Returns SmsStatusUpdate | null (null if driver doesn't support it)
+
+// Verify/lookup a phone number
+const info = await verifyNumber('+1234567890')
+// Returns { valid: boolean, carrier?: string, type?: string }
+
+// Get account balance
+const balance = await getBalance()
+// Returns { balance: number, currency: string } | null
+```
+
+## Phone Verification (OTP/2FA)
+
+```typescript
+import { startVerification, checkVerification, cancelVerification } from '@stacksjs/sms'
+
+// Start -- sends OTP code via SMS (or 'call', 'email' for Twilio; 'sms', 'whatsapp' for Vonage)
+const result = await startVerification({
+  to: '+1234567890',
+  channel: 'sms',        // default: 'sms'
+  codeLength: 6,          // optional
+  locale: 'en',           // optional
+  customMessage: 'Your code: {code}',  // optional, Twilio only
+})
+// Returns { success: boolean, verificationId?: string, status: 'pending' | 'denied', error?: string }
+
+// Check -- verify the code the user entered
+const check = await checkVerification({
+  to: '+1234567890',           // Twilio requires 'to'
+  verificationId: result.verificationId,  // Vonage requires this
+  code: '123456',
+})
+// Returns { success: boolean, verificationId?: string, status: 'approved' | 'denied', error?: string }
+
+// Cancel -- cancel a pending verification
+const cancelled = await cancelVerification(result.verificationId!)
+// Returns boolean
+```
+
+**Twilio** uses the Verify service (`verify.twilio.com/v2`) and requires `verifyServiceSid` passed to the TwilioDriver constructor.
+
+**Vonage** uses the Verify V2 API (`api.nexmo.com/v2/verify`). Whatsapp channel maps to `whatsapp_interactive`.
+
+## SMS Templates
+
+```typescript
+import { sendTemplate } from '@stacksjs/sms'
+
+await sendTemplate('+1234567890', 'order-confirmation', {
+  orderNumber: '#12345',
+  total: '$29.99',
+})
+```
+
+Templates are defined in `config/sms.ts` under `templates[]`. Each template has `name`, `body`, and optional `variables`. Variables use single-brace syntax `{variableName}` in the template body. The function finds the template by name, replaces variables, and sends via the default driver.
+
+Returns a failed result (without throwing) if the template is not found.
+
+## Phone Number Utilities
+
+```typescript
+import { formatE164, isValidPhoneNumber } from '@stacksjs/sms'
+
+// Normalize to E.164 format
+formatE164('+1 (234) 567-890')        // '+12345678900'
+formatE164('2345678900', '1')          // '+12345678900'
+formatE164('002345678900')             // '+2345678900' (00 prefix stripped)
+
+// Validate E.164 format (regex: /^\+[1-9]\d{6,14}$/)
+isValidPhoneNumber('+1234567890')      // true
+isValidPhoneNumber('1234567890')       // true (formatted first, then validated)
+```
+
+`formatE164()` strips spaces, dashes, and parentheses. If the number starts with `+`, returns as-is. If it starts with `00`, replaces with `+`. Otherwise prepends `+` and the default country code (from `config.defaultCountryCode` or `'1'` for US).
+
+## Twilio Driver
+
+```typescript
+import { TwilioDriver, createTwilioDriver } from '@stacksjs/sms'
+
+const driver = new TwilioDriver({
+  accountSid: 'AC...',
+  authToken: '...',
+  from: '+1234567890',
+  messagingServiceSid: 'MG...',    // optional, used instead of 'from'
+  statusCallback: 'https://...',   // optional, default callback URL
+}, 'VA_verify_service_sid')         // optional second arg for verification
+
+// Or use factory
+const driver = createTwilioDriver(config, verifyServiceSid?)
+```
+
+Uses REST API at `https://api.twilio.com/2010-04-01`. Auth via HTTP Basic (`accountSid:authToken`).
+
+Features:
+- `send(message)` -- sends via Messages API, supports MMS (mediaUrls), statusCallback, messagingServiceSid
+- `sendBulk(messages)` -- sends in parallel via `Promise.all`
+- `getStatus(messageId)` -- retrieves message status
+- `verify(phoneNumber)` -- uses Twilio Lookup API v2 with line_type_intelligence
+- `getBalance()` -- retrieves account balance
+- `startVerification(req)` -- Twilio Verify service
+- `checkVerification(req)` -- check OTP code
+- `cancelVerification(id)` -- cancel pending verification
+
+Status mapping: queued, sending, sent, delivered, undelivered -> `SmsStatus`; canceled -> 'failed'.
+
+## Vonage Driver
+
+```typescript
+import { VonageDriver, createVonageDriver } from '@stacksjs/sms'
+
+const driver = new VonageDriver({
+  apiKey: '...',
+  apiSecret: '...',
+  from: 'MyApp',
+  applicationId: '...',    // optional, for JWT auth
+  privateKey: '...',        // optional, for JWT auth
+}, true)                    // optional: useMessagesApi (default: false)
+
+// Or use factory
+const driver = createVonageDriver(config, useMessagesApi?)
+```
+
+Two send modes:
+- **SMS API** (legacy, default) -- `https://rest.nexmo.com/sms/json`, uses API key/secret in body
+- **Messages API** (newer) -- `https://api.nexmo.com/v1/messages`, uses Basic auth or JWT
+
+Features:
+- `send(message)` -- sends via chosen API mode
+- `sendBulk(messages)` -- sends in parallel
+- `getStatus(messageId)` -- Messages API only
+- `verify(phoneNumber)` -- Vonage Number Insight API (basic)
+- `getBalance()` -- account balance in EUR
+- `startVerification(req)` -- Vonage Verify V2 API
+- `checkVerification(req)` -- requires `verificationId`
+- `cancelVerification(id)` -- DELETE request to cancel
+
+The `nexmo` export is a legacy alias for `vonage`.
+
+## Other Drivers (Commented Out / Placeholder)
+
+The `drivers/` directory contains placeholder files for: `gupshup`, `nexmo` (alias for vonage), `plivo`, `sms77`, `sns`, `telnyx`, `termii`. These are all commented out and not functional. Only Twilio and Vonage are active.
+
+## config/sms.ts
+
+```typescript
+{
+  enabled: false,                    // Must explicitly enable
+  provider: 'twilio',               // 'twilio' | 'vonage'
+  from: env.SMS_FROM_NUMBER || '',
+  defaultCountryCode: 'US',
+  messageType: 'TRANSACTIONAL',     // TRANSACTIONAL or PROMOTIONAL
+
+  drivers: {
+    twilio: {
+      accountSid: env.TWILIO_ACCOUNT_SID || '',
+      authToken: env.TWILIO_AUTH_TOKEN || '',
+      from: env.TWILIO_FROM_NUMBER || '',
+      messagingServiceSid: env.TWILIO_MESSAGING_SERVICE_SID || '',
+    },
+    vonage: {
+      apiKey: env.VONAGE_API_KEY || '',
+      apiSecret: env.VONAGE_API_SECRET || '',
+      from: env.VONAGE_FROM_NUMBER || '',
+    },
+    pinpoint: {
+      region: env.AWS_REGION || 'us-east-1',
+      accessKeyId: env.AWS_ACCESS_KEY_ID || '',
+      secretAccessKey: env.AWS_SECRET_ACCESS_KEY || '',
+      senderId: env.SMS_SENDER_ID || '',
+      originationNumber: env.SMS_ORIGINATION_NUMBER || '',
+    },
+  },
+
+  maxSpendPerMonth: 100,
+  optOut: {
+    enabled: true,
+    keywords: ['STOP', 'UNSUBSCRIBE', 'CANCEL', 'END', 'QUIT'],
+  },
+  templates: [],                     // Array of { name, body, variables }
+  twoWay: {
+    enabled: false,
+  },
+} satisfies SmsConfig
+```
+
+## Type Interfaces (from @stacksjs/types)
+
+```typescript
+interface SmsMessage {
+  to: string | string[]
+  body: string
+  from?: string
+  mediaUrls?: string[]
+  statusCallback?: string
+}
+
+interface SmsSendResult {
+  success: boolean
+  messageId?: string
+  status?: SmsStatus
+  to: string
+  provider: string
+  error?: string
+  segments?: number
+  price?: number
+  currency?: string
+}
+
+type SmsStatus = 'queued' | 'sending' | 'sent' | 'delivered' | 'undelivered' | 'failed' | 'unknown'
+
+interface SmsStatusUpdate {
+  messageId: string
+  to: string
+  status: SmsStatus
+  timestamp: Date
+  errorCode?: string
+  errorMessage?: string
+}
+
+type SmsProvider = 'twilio' | 'vonage' | 'pinpoint'
+
+interface VerificationRequest {
+  to: string
+  channel?: string        // 'sms' | 'call' | 'email' | 'whatsapp'
+  codeLength?: number
+  locale?: string
+  customMessage?: string  // Twilio only
+}
+
+interface VerificationCheckRequest {
+  to: string
+  code: string
+  verificationId?: string
+}
+
+interface VerificationResult {
+  success: boolean
+  verificationId?: string
+  status: 'pending' | 'approved' | 'denied'
+  error?: string
+}
+```
+
+## Gotchas
+- SMS is **disabled by default** (`enabled: false`) -- must set to `true` in `config/sms.ts`
+- Provider API keys go in `.env`, not config files
+- Config is loaded lazily via dynamic import on first `send()`/operation -- `init()` pre-loads it
+- Only Twilio and Vonage drivers are fully implemented; other drivers (gupshup, plivo, sns, telnyx, etc.) are commented-out placeholders
+- `pinpoint` appears in config but has no driver implementation in `getDriver()` -- using it throws `'Unsupported SMS provider: pinpoint'`
+- The `defaultCountryCode` in config is `'US'` but `formatE164()` uses it as a numeric code prefix (the fallback is `'1'`), so the actual behavior uses the number `'1'` for US
+- Template variables use single-brace syntax `{variableName}`, NOT double-brace
+- `sendBulk()` sends all messages in parallel via `Promise.all` -- no rate limiting
+- Twilio verification requires a `verifyServiceSid` passed to the driver constructor, which is not part of the standard config structure
+- Vonage JWT authentication is a simplified placeholder -- real RS256 signing is not fully implemented
+- `getDriver()` creates a new driver instance each time unless accessed through the cached `getDefaultDriver()`
+- `sendTemplate()` returns a failed result (not an exception) if the template name is not found

package/ai/skills/stacks-socials/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: stacks-socials
+description: Use when implementing social authentication in Stacks — OAuth2 flows with GitHub/Google/Facebook/Twitter providers, the AbstractProvider base class, PKCE support, state management, scope configuration, social user profiles, or token handling. Covers @stacksjs/socials.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Socials
+
+OAuth2-based social authentication with 4 built-in providers.
+
+## Key Paths
+- Core package: `storage/framework/core/socials/src/`
+
+## Source Files
+```
+socials/src/
+├── index.ts          # re-exports from drivers/
+├── abstract.ts       # AbstractProvider base class
+├── token.ts          # Token class
+├── types.ts          # SocialUser, provider-specific interfaces
+├── exceptions.ts     # InvalidStateException, ConfigException
+└── drivers/
+    ├── index.ts      # re-exports all 4 providers
+    ├── github.ts     # GitHub OAuth provider
+    ├── google.ts     # Google OAuth provider
+    ├── facebook.ts   # Facebook OAuth provider
+    └── twitter.ts    # Twitter/X OAuth2 + PKCE provider
+```
+
+## AbstractProvider Base Class
+
+All providers extend `AbstractProvider` which implements `ProviderInterface`. The constructor takes a `ProviderConfig`:
+
+```typescript
+interface ProviderConfig {
+  clientId: string
+  clientSecret: string
+  redirectUrl: string
+  guzzle?: Record<string, any>
+}
+```
+
+Properties and methods on `AbstractProvider`:
+
+```typescript
+abstract class AbstractProvider implements ProviderInterface {
+  // Protected state
+  protected clientId: string
+  protected clientSecret: string
+  protected redirectUrl: string
+  protected parameters: Record<string, any> = {}
+  protected _scopes: string[] = []
+  protected scopeSeparator: string = ','
+  protected _stateless: boolean = false
+  protected _usesPKCE: boolean = false
+  protected user: SocialUser | null = null
+
+  // Abstract methods (each provider implements)
+  abstract getAuthUrl(): Promise<string>           // public, returns Promise
+  protected abstract getTokenUrl(): string         // protected
+  abstract getAccessToken(code: string): Promise<string>
+  abstract getUserByToken(token: string): Promise<SocialUser>
+
+  // Scope management
+  scopes(scopes: string | string[]): this      // merge into existing (deduplicates via Set)
+  setScopes(scopes: string | string[]): this   // replace all scopes (deduplicates via Set)
+  getScopes(): string[]
+
+  // Configuration
+  setRedirectUrl(url: string): this
+  stateless(): this                             // sets _stateless = true
+  enablePKCE(): this                            // sets _usesPKCE = true
+  with(parameters: Record<string, any>): this   // replaces custom query parameters
+
+  // User retrieval
+  async userFromToken(token: string): Promise<SocialUser>  // calls getUserByToken, adds token
+
+  // URL building (protected)
+  protected buildAuthUrlFromBase(url: string, state: string | null): string
+  protected getCodeFields(state: string | null = null): Record<string, any>
+  protected formatScopes(scopes: string[], scopeSeparator: string): string
+
+  // State helpers (protected)
+  protected usesState(): boolean          // returns !_stateless
+  protected isStateless(): boolean        // returns _stateless
+  protected getState(): string            // 20 random bytes -> 40 hex chars
+
+  // PKCE helpers (protected)
+  protected usesPKCE(): boolean
+  protected getCodeVerifier(): string              // 48 random bytes -> 96 hex chars
+  protected async getCodeChallenge(): Promise<string>  // SHA-256 of verifier, base64url encoded
+  protected getCodeChallengeMethod(): string       // always 'S256'
+}
+```
+
+The `getCodeFields()` method builds the query parameters for the authorization URL:
+- Always includes: `client_id`, `redirect_uri`, `scope` (joined by `scopeSeparator`), `response_type: 'code'`
+- Conditionally adds `state` when `usesState()` is true
+- Conditionally adds `code_challenge` and `code_challenge_method` when `usesPKCE()` is true
+- Merges in any custom `parameters` set via `with()`
+
+## Provider Implementations
+
+### GitHub Provider
+
+```typescript
+class GitHubProvider extends AbstractProvider {
+  protected baseUrl = 'https://github.com'
+  protected apiUrl = 'https://api.github.com'
+}
+```
+
+- Config source: `config.services.github` (clientId, clientSecret, redirectUrl, scopes)
+- Default scopes: `['read:user', 'user:email']`
+- Auth URL: `https://github.com/login/oauth/authorize` with scopes joined by space
+- Token URL: `https://github.com/login/oauth/access_token` (POST)
+- User API: Fetches `/user` and `/user/emails` in parallel via `Promise.all`
+- Email resolution: Primary email first, then verified, then first available
+- Uses `@stacksjs/api` `fetcher` for HTTP requests
+- Throws `ConfigException` if clientId, clientSecret, or redirectUrl missing
+- GitHub token response: `GitHubTokenResponse { access_token, error?, error_description? }`
+
+### Google Provider
+
+```typescript
+class GoogleProvider extends AbstractProvider {
+  protected baseUrl = 'https://accounts.google.com'
+  protected apiUrl = 'https://www.googleapis.com'
+}
+```
+
+- Config source: `config.services.google`
+- Default scopes: `['https://www.googleapis.com/auth/userinfo.profile', 'https://www.googleapis.com/auth/userinfo.email']`
+- Auth URL: `https://accounts.google.com/o/oauth2/v2/auth` (includes `access_type: 'offline'`, `prompt: 'consent'`)
+- Token URL: `https://accounts.google.com/oauth2/v4/token` (POST with `grant_type: 'authorization_code'`)
+- User API: `https://www.googleapis.com/oauth2/v2/userinfo` with Bearer token
+- Maps `given_name` to `nickname`, `picture` to `avatar`
+- Google user type: `{ id, email, verified_email, name, given_name, family_name, picture, locale }`
+
+### Facebook Provider
+
+```typescript
+class FacebookProvider extends AbstractProvider {
+  protected baseUrl = 'https://www.facebook.com'
+  protected apiUrl = 'https://graph.facebook.com'
+}
+```
+
+- Config source: `config.services.facebook`
+- Default scopes: `['email', 'public_profile']`
+- Auth URL: `https://www.facebook.com/v18.0/dialog/oauth` with scopes joined by comma
+- Token URL: `https://graph.facebook.com/v18.0/oauth/access_token` (GET request, not POST)
+- User API: `https://graph.facebook.com/v18.0/me?fields=id,name,email,picture`
+- Token is passed as query parameter `access_token`, not in Authorization header
+- Always sets `nickname: null` (Facebook does not expose usernames)
+- Avatar extracted from `picture.data.url`
+- Error response shape: `{ error: { message, type, code } }` (nested object, unlike other providers)
+
+### Twitter/X Provider
+
+```typescript
+class TwitterProvider extends AbstractProvider {
+  protected baseUrl = 'https://twitter.com'
+  protected apiUrl = 'https://api.twitter.com'
+  private codeVerifier: string | null = null
+}
+```
+
+- Config source: `config.services.twitter`
+- Default scopes: `['users.read', 'tweet.read']`
+- Uses OAuth 2.0 with PKCE (not OAuth 1.0a)
+- Auth URL: `https://twitter.com/i/oauth2/authorize` with PKCE code challenge
+- Token URL: `https://api.twitter.com/2/oauth2/token` (POST with Basic auth)
+- User API: `https://api.twitter.com/2/users/me?user.fields=profile_image_url` with Bearer token
+- PKCE implementation uses its own `generateCodeVerifier()` and `generateCodeChallenge()` methods (using `node:crypto` `randomBytes` and `createHash`), not the base class PKCE
+- Code verifier: `randomBytes(32)` -> base64 -> alphanumeric only -> max 128 chars
+- Token exchange uses Basic auth: `Buffer.from(clientId:clientSecret).toString('base64')`
+- `getAccessToken()` throws if `codeVerifier` is null -- `getAuthUrl()` must be called first
+- Maps `username` to `nickname`, `profile_image_url` to `avatar`
+
+## SocialUser Interface
+
+```typescript
+interface SocialUser {
+  id: string
+  nickname: string | null
+  name: string
+  email: string | null
+  avatar: string | null
+  token: string
+  raw?: any               // full provider API response
+}
+```
+
+## ProviderInterface
+
+```typescript
+interface ProviderInterface {
+  getAuthUrl: () => Promise<string>
+  getAccessToken: (code: string) => Promise<string>
+  getUserByToken: (token: string) => Promise<SocialUser>
+}
+```
+
+## Token Class
+
+```typescript
+class Token {
+  constructor(
+    public accessToken: string,
+    public refreshToken: string | null = null,
+    public expiresIn: number | null = null,
+    public approvedScopes: string[] = [],
+  ) {}
+}
+```
+
+## Provider-Specific Types
+
+```typescript
+// GitHub
+interface GitHubUser { id: number, login: string, name: string | null, avatar_url: string | null, [key: string]: any }
+interface GitHubEmail { email: string, primary: boolean, verified: boolean }
+interface GitHubTokenResponse { access_token: string, error?: string, error_description?: string }
+
+// Twitter/X
+interface TwitterUser { id: string, username: string, name: string, email?: string, profile_image_url?: string }
+interface TwitterTokenResponse { access_token: string, token_type: string, expires_in: number, scope: string, error?: string, error_description?: string }
+
+// Google (local to google.ts)
+interface GoogleUser { id: string, email: string, verified_email: boolean, name: string, given_name: string, family_name: string, picture: string, locale: string }
+interface GoogleTokenResponse { access_token: string, token_type: string, expires_in: number, error?: string, error_description?: string }
+
+// Facebook (local to facebook.ts)
+interface FacebookUser { id: string, email?: string, name: string, picture?: { data: { url: string } } }
+interface FacebookTokenResponse { access_token: string, token_type: string, expires_in: number, error?: { message: string, type: string, code: number } }
+```
+
+## Exceptions
+
+```typescript
+class InvalidStateException extends Error { name = 'InvalidStateException' }
+class ConfigException extends Error { name = 'ConfigException' }
+```
+
+Providers throw `ConfigException` when `clientId`, `clientSecret`, or `redirectUrl` are missing.
+
+## OAuth2 Flow
+
+### 1. Get Auth URL
+```typescript
+const github = new GitHubProvider({ clientId: '', clientSecret: '', redirectUrl: '' })
+const authUrl = await github.scopes(['user:email', 'read:org']).getAuthUrl()
+// Each provider reads actual config from config.services.<provider>
+// The constructor config is overridden by getConfig() in each provider
+```
+
+### 2. Handle Callback
+```typescript
+const token = await github.getAccessToken(code)
+const user = await github.getUserByToken(token)
+// user: { id, nickname, name, email, avatar, token, raw }
+```
+
+### 3. User from Existing Token
+```typescript
+const user = await github.userFromToken(existingToken)
+// Calls getUserByToken internally, adds token to result
+```
+
+## Configuration Source
+
+All providers read from the Stacks config object:
+```typescript
+config.services.github   // { clientId, clientSecret, redirectUrl, scopes }
+config.services.google   // { clientId, clientSecret, redirectUrl, scopes }
+config.services.facebook // { clientId, clientSecret, redirectUrl, scopes }
+config.services.twitter  // { clientId, clientSecret, redirectUrl, scopes }
+```
+
+Each provider's `getConfig()` method reads these and also calls `this.setScopes()` with the configured scopes.
+
+## Dependencies
+- `@stacksjs/api` -- `fetcher` used for all HTTP requests (provides `.withHeaders()`, `.get()`, `.post()`)
+- `@stacksjs/config` -- provides `config.services.*` for provider credentials
+- `node:buffer` and `node:crypto` -- used by Twitter provider for PKCE and Basic auth
+
+## Gotchas
+- The `ProviderConfig` constructor params are largely ignored -- each provider's `getConfig()` reads from `config.services.*` instead
+- `getAuthUrl()` returns `Promise<string>` (not `string`) -- it is async
+- `getTokenUrl()` is `protected` -- not part of the public `ProviderInterface`
+- GitHub joins scopes with space, Facebook with comma, Google with space, Twitter with space
+- Facebook uses GET for token exchange; all others use POST
+- Facebook `nickname` is always `null`
+- Twitter requires `getAuthUrl()` before `getAccessToken()` because the code verifier is stored as instance state
+- Twitter uses its own PKCE implementation via `node:crypto`, not the base class `getCodeVerifier()`/`getCodeChallenge()`
+- Google auth URL includes `access_type: 'offline'` and `prompt: 'consent'` for refresh token support
+- The base class state token is 40 hex chars (20 bytes), not the 20 chars stated in some docs
+- `userFromToken()` spreads the user object and adds/overwrites the `token` field
+- All providers include the full API response in `SocialUser.raw`
+- Errors from GitHub/Google/Twitter are flat objects with `error` + `error_description`; Facebook nests it under `error.message`