skrypt-ai 0.3.4 → 0.4.0

package/dist/template/src/app/docs/auth/page.mdx

@@ -0,0 +1,589 @@
+## Functions
+
+### `getAuthConfig`
+
+```typescript
+function getAuthConfig(): AuthConfig
+```
+
+Use this to retrieve the current authentication configuration from the local auth file. This is the primary way to check if a user is logged in, access their stored credentials, or verify token expiration before making API calls.
+
+Returns an `AuthConfig` object with the user's stored auth data, or an empty object `{}` if no auth file exists yet (unauthenticated state).
+
+#### Parameters
+
+This function takes no parameters.
+
+#### Returns
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `token` | `string` (optional) | The authentication token for API requests |
+| `email` | `string` (optional) | The authenticated user's email address |
+| `expiresAt` | `string` (optional) | ISO timestamp indicating when the token expires |
+| `error` | `string` (optional) | Any error message associated with the auth state |
+
+**Returns `{}`** (empty object) when no auth file is found — treat this as an unauthenticated state.
+
+**Returns a populated `AuthConfig`** when the user has previously authenticated.
+
+**Example:**
+
+```typescript example.ts
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// Inline the AuthConfig type
+type AuthConfig = {
+  token?: string
+  email?: string
+  expiresAt?: string
+  error?: string
+}
+
+// Inline the auth file path logic (mirrors the real implementation)
+const AUTH_FILE = join(homedir(), '.config', 'autodocs', 'auth.json')
+
+// Self-contained implementation of getAuthConfig
+function getAuthConfig(): AuthConfig {
+  if (!existsSync(AUTH_FILE)) {
+    return {}
+  }
+  try {
+    return JSON.parse(readFileSync(AUTH_FILE, 'utf-8')) as AuthConfig
+  } catch {
+    return { error: 'Failed to parse auth config' }
+  }
+}
+
+// --- Usage Examples ---
+
+function isAuthenticated(config: AuthConfig): boolean {
+  return !!config.token && !config.error
+}
+
+function isTokenExpired(config: AuthConfig): boolean {
+  if (!config.expiresAt) return false
+  return new Date(config.expiresAt) < new Date()
+}
+
+async function main() {
+  try {
+    const authConfig = getAuthConfig()
+
+    // Case 1: No auth file found
+    if (Object.keys(authConfig).length === 0) {
+      console.log('Status: Not authenticated — please run `autodocs login`')
+      // Output: Status: Not authenticated — please run `autodocs login`
+      return
+    }
+
+    // Case 2: Auth file exists, check validity
+    if (!isAuthenticated(authConfig)) {
+      console.log('Auth error:', authConfig.error ?? 'Unknown error')
+      return
+    }
+
+    if (isTokenExpired(authConfig)) {
+      console.log('Token expired at:', authConfig.expiresAt)
+      console.log('Please re-authenticate with `autodocs login`')
+      return
+    }
+
+    // Case 3: Valid, active session
+    console.log('Authenticated as:', authConfig.email)
+    console.log('Token (truncated):', authConfig.token?.slice(0, 8) + '...')
+    console.log('Session expires:', authConfig.expiresAt)
+    // Output:
+    // Authenticated as: user@example.com
+    // Token (truncated): eyJhbGci...
+    // Session expires: 2025-12-31T23:59:59.000Z
+
+  } catch (error) {
+    console.error('Unexpected error reading auth config:', error)
+  }
+}
+
+main()
+```
+
+### `saveAuthConfig`
+
+```typescript
+function saveAuthConfig(config: AuthConfig): void
+```
+
+Use this to persist authentication credentials to a local config file, ensuring the config directory exists before writing.
+
+Saves an `AuthConfig` object as formatted JSON to a file on disk. Automatically creates any missing parent directories in the config path before writing, so you don't need to pre-create the directory structure.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| config | `AuthConfig` | ✅ | Authentication configuration object containing credentials/tokens to persist |
+
+#### Returns
+
+`void` — Writes synchronously to disk. Throws a filesystem error if the path is not writable or permissions are insufficient.
+
+### Notes
+- Creates the config directory recursively if it does not exist (`mkdirSync` with `{ recursive: true }`)
+- Writes JSON with 2-space indentation for human readability
+- Overwrites any existing config file at the target path
+- Throws if the write fails (e.g., permission denied, disk full)
+
+**Example:**
+
+```typescript example.ts
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// --- Inline type definition ---
+interface AuthConfig {
+  token: string
+  userId: string
+  expiresAt?: number
+  refreshToken?: string
+}
+
+// --- Inline config path constants ---
+const CONFIG_DIR = join(homedir(), '.config', 'myapp')
+const AUTH_FILE = join(CONFIG_DIR, 'auth.json')
+
+// --- Inlined implementation of saveAuthConfig ---
+function saveAuthConfig(config: AuthConfig): void {
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  writeFileSync(AUTH_FILE, JSON.stringify(config, null, 2))
+}
+
+// --- Usage example ---
+const authConfig: AuthConfig = {
+  token: process.env.AUTH_TOKEN || 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example',
+  userId: process.env.USER_ID || 'usr_4f8a2b1c9d3e',
+  expiresAt: Date.now() + 1000 * 60 * 60 * 24, // 24 hours from now
+  refreshToken: process.env.REFRESH_TOKEN || 'ref_7k2m9p4q1r8s',
+}
+
+try {
+  saveAuthConfig(authConfig)
+  console.log(`✅ Auth config saved to: ${AUTH_FILE}`)
+
+  // Verify the file was written correctly
+  if (existsSync(AUTH_FILE)) {
+    const saved = JSON.parse(readFileSync(AUTH_FILE, 'utf-8')) as AuthConfig
+    console.log('Saved config:', saved)
+    // Output:
+    // {
+    //   token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example',
+    //   userId: 'usr_4f8a2b1c9d3e',
+    //   expiresAt: 1718123456789,
+    //   refreshToken: 'ref_7k2m9p4q1r8s'
+    // }
+  }
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('❌ Failed to save auth config:', error.message)
+    // Common causes: permission denied, disk full, invalid path
+  }
+}
+```
+
+### `clearAuth`
+
+```typescript
+function clearAuth(): void
+```
+
+Use this to log a user out by wiping stored authentication credentials from the local config file. Calling this resets the auth file to an empty state (`{}`) without deleting the file itself — safe to call even if no credentials have been saved yet.
+
+**Parameters**
+
+None.
+
+**Returns**
+
+`void` — no return value. The auth config file is overwritten with `{}` if it exists; if no file is found, the function exits silently.
+
+**Behavior**
+- ✅ Auth file exists → contents replaced with `{}`
+- ✅ Auth file does not exist → no-op, no error thrown
+
+**Example:**
+
+```typescript example.ts
+import { existsSync, writeFileSync, readFileSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+// --- Inline config (mirrors autodocs internals) ---
+const CONFIG_DIR = join(homedir(), '.config', 'autodocs-demo')
+const AUTH_FILE = join(CONFIG_DIR, 'auth.json')
+
+type AuthConfig = {
+  token?: string
+  userId?: string
+  expiresAt?: string
+}
+
+function saveAuthConfig(config: AuthConfig): void {
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  writeFileSync(AUTH_FILE, JSON.stringify(config, null, 2))
+}
+
+function clearAuth(): void {
+  if (existsSync(AUTH_FILE)) {
+    writeFileSync(AUTH_FILE, '{}')
+  }
+}
+
+// --- Example: save credentials, then clear them on logout ---
+async function main() {
+  try {
+    // Simulate a user logging in
+    const credentials: AuthConfig = {
+      token: process.env.AUTH_TOKEN || 'tok_abc123xyz',
+      userId: 'user_9876',
+      expiresAt: new Date(Date.now() + 3600 * 1000).toISOString(),
+    }
+
+    saveAuthConfig(credentials)
+    console.log('Logged in. Auth file contents:')
+    console.log(readFileSync(AUTH_FILE, 'utf-8'))
+    // Output: { "token": "tok_abc123xyz", "userId": "user_9876", "expiresAt": "..." }
+
+    // Simulate the user logging out
+    clearAuth()
+    console.log('\nLogged out. Auth file contents after clearAuth():')
+    console.log(readFileSync(AUTH_FILE, 'utf-8'))
+    // Output: {}
+
+    // Calling clearAuth again when already cleared is safe (no-op if file missing)
+    clearAuth()
+    console.log('\nCalled clearAuth() again — no error thrown. ✅')
+  } catch (error) {
+    console.error('Unexpected error during auth lifecycle:', error)
+  }
+}
+
+main()
+```
+
+### `checkPlan`
+
+```typescript
+async function checkPlan(apiKey: string): Promise<PlanCheckResponse>
+```
+
+Use this to verify an API key's validity and retrieve the associated subscription plan details before making API calls.
+
+`checkPlan` hits the `/v1/plan` endpoint with a Bearer token and returns plan metadata — useful for gating features, displaying plan info to users, or validating credentials at startup.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `apiKey` | `string` | ✅ Yes | The Bearer token used to authenticate against the API |
+
+#### Returns
+
+Returns a `Promise<PlanCheckResponse>` that resolves with the plan details for the given API key.
+
+| Scenario | Result |
+|----------|--------|
+| Valid API key | Resolves with plan metadata (e.g. plan name, limits, status) |
+| Invalid / expired key | Rejects or resolves with an error response depending on server behavior |
+| Network failure | Rejects with a fetch/network error |
+
+### `PlanCheckResponse` shape (typical)
+```typescript
+type PlanCheckResponse = {
+  plan: string        // e.g. "free", "pro", "enterprise"
+  valid: boolean      // whether the key is active
+  limits?: {
+    requests: number
+    storage: number
+  }
+  error?: string      // present if the key was rejected
+}
+```
+
+**Example:**
+
+```typescript example.ts
+// Inline types — no external imports needed
+type PlanCheckResponse = {
+  plan: string
+  valid: boolean
+  limits?: {
+    requests: number
+    storage: number
+  }
+  error?: string
+}
+
+// Self-contained implementation mirroring the real checkPlan behavior
+async function checkPlan(apiKey: string): Promise<PlanCheckResponse> {
+  const API_BASE = 'https://api.autodocs.dev'
+
+  const response = await fetch(`${API_BASE}/v1/plan`, {
+    headers: {
+      'Authorization': `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+  })
+
+  if (!response.ok) {
+    const errorBody = await response.json().catch(() => ({}))
+    return {
+      plan: 'unknown',
+      valid: false,
+      error: (errorBody as any).message || `HTTP ${response.status}: ${response.statusText}`,
+    }
+  }
+
+  return response.json() as Promise<PlanCheckResponse>
+}
+
+// --- Usage ---
+async function main() {
+  const apiKey = process.env.AUTODOCS_API_KEY || 'sk-your-api-key-here'
+
+  try {
+    console.log('Checking plan for API key...')
+    const planInfo = await checkPlan(apiKey)
+
+    if (!planInfo.valid) {
+      console.error('API key is invalid or expired:', planInfo.error)
+      process.exit(1)
+    }
+
+    console.log('Plan details:', planInfo)
+    // Expected output:
+    // Plan details: { plan: 'pro', valid: true, limits: { requests: 10000, storage: 5000 } }
+
+    // Example: gate a feature based on plan
+    if (planInfo.plan === 'free') {
+      console.log('Upgrade to Pro to unlock advanced features.')
+    } else {
+      console.log(`Welcome, ${planInfo.plan} user! All features unlocked.`)
+    }
+  } catch (error) {
+    // Network errors, DNS failures, etc.
+    console.error('Failed to reach the plan endpoint:', error)
+  }
+}
+
+main()
+```
+
+### `requirePro`
+
+```typescript
+async function requirePro(commandName: string): Promise<boolean>
+```
+
+Use this to gate CLI commands behind a Pro subscription — it checks the user's auth config and prints a helpful upgrade message if they're not on a paid plan.
+
+Call `requirePro` at the top of any command handler that requires a Pro account. It returns `true` if the user is authorized to proceed, or `false` (after printing an error) if they are not.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `commandName` | `string` | ✅ | The name of the CLI command being gated. Used in the error message shown to the user (e.g. `"sync"`, `"generate"`). |
+
+#### Returns
+
+| Value | When |
+|-------|------|
+| `Promise<true>` | User has a valid Pro API key and is authorized |
+| `Promise<false>` | User has no API key, is on the free plan, or the auth check fails — an error message is printed to `stderr` automatically |
+
+## Usage Pattern
+
+```typescript
+// In your command handler:
+if (!await requirePro('my-command')) return;
+// ... rest of Pro-only logic
+```
+
+**Example:**
+
+```typescript example.ts
+import * as fs from 'fs'
+import * as path from 'path'
+import * as os from 'os'
+
+// --- Inline types and helpers (self-contained, no external imports) ---
+
+type AuthConfig = {
+  apiKey: string | null
+}
+
+type LicenseStatus = {
+  valid: boolean
+  plan: 'free' | 'pro'
+  email: string
+  error?: string
+}
+
+// Simulates reading auth config from ~/.skrypt/config.json
+function getAuthConfig(): AuthConfig {
+  const configPath = path.join(os.homedir(), '.skrypt', 'config.json')
+  try {
+    if (fs.existsSync(configPath)) {
+      const raw = fs.readFileSync(configPath, 'utf-8')
+      const parsed = JSON.parse(raw)
+      return { apiKey: parsed.apiKey || null }
+    }
+  } catch {
+    // Config unreadable
+  }
+  return { apiKey: null }
+}
+
+// Simulates a license validation API call
+async function validateLicense(apiKey: string): Promise<LicenseStatus> {
+  // In real usage this would hit an API endpoint
+  // Here we simulate: keys starting with "pro_" are valid Pro keys
+  if (apiKey.startsWith('pro_')) {
+    return { valid: true, plan: 'pro', email: 'user@example.com' }
+  }
+  return { valid: false, plan: 'free', email: '', error: 'Not a Pro key' }
+}
+
+// The function being documented
+async function requirePro(commandName: string): Promise<boolean> {
+  const config = getAuthConfig()
+
+  if (!config.apiKey) {
+    console.error(`\n  ⚡ ${commandName} requires Skrypt Pro\n`)
+    console.error('  Get started:')
+    console.error('    https://skrypt.dev/pro\n')
+    return false
+  }
+
+  let status: LicenseStatus
+  try {
+    status = await validateLicense(config.apiKey)
+  } catch {
+    status = { valid: false, plan: 'free', email: '', error: 'Failed to connect to API' }
+  }
+
+  if (!status.valid || status.plan !== 'pro') {
+    console.error(`\n  ⚡ ${commandName} requires Skrypt Pro\n`)
+    console.error(`  Current plan: ${status.plan}`)
+    console.error('  Upgrade at: https://skrypt.dev/pro\n')
+    return false
+  }
+
+  return true
+}
+
+// --- Demo ---
+
+async function main() {
+  try {
+    // Scenario 1: No API key configured
+    console.log('--- Scenario 1: No API key ---')
+    const noKeyResult = await requirePro('generate')
+    console.log('Authorized:', noKeyResult)
+    // Output:
+    //   ⚡ generate requires Skrypt Pro
+    //   Get started:
+    //     https://skrypt.dev/pro
+    // Authorized: false
+
+    // Scenario 2: Free-tier key
+    console.log('\n--- Scenario 2: Free-tier key ---')
+    // Temporarily mock getAuthConfig by overriding the config file path behavior
+    // (In a real test you'd inject the config; here we call validateLicense directly)
+    const freeStatus = await validateLicense('free_abc123')
+    console.log('License status:', freeStatus)
+    // Output: { valid: false, plan: 'free', email: '', error: 'Not a Pro key' }
+
+    // Scenario 3: Valid Pro key
+    console.log('\n--- Scenario 3: Valid Pro key ---')
+    const proStatus = await validateLicense(
+      process.env.SKRYPT_API_KEY || 'pro_sk_live_abc123xyz'
+    )
+    console.log('License status:', proStatus)
+    // Output: { valid: true, plan: 'pro', email: 'user@example.com' }
+
+  } catch (error) {
+    console.error('Unexpected error:', error)
+  }
+}
+
+main()
+```
+
+### `isProCommand`
+
+```typescript
+function isProCommand(command: string): boolean
+```
+
+Use this to check whether a given CLI command requires a Pro subscription before executing it, enabling you to gate features and show appropriate upgrade prompts.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| command | string | Yes | The CLI command name to check against the list of Pro-only commands |
+
+#### Returns
+
+- **`true`** — the command is Pro-only and requires an upgraded account
+- **`false`** — the command is available on the free tier
+
+**Example:**
+
+```typescript example.ts
+// Define the Pro commands list inline (mirrors the source)
+const PRO_COMMANDS = ['gh-action', 'ci', 'mcp']
+
+// Inline implementation of isProCommand
+function isProCommand(command: string): boolean {
+  return PRO_COMMANDS.includes(command)
+}
+
+// Simulate a user running a CLI command
+function runCommand(command: string, isProUser: boolean) {
+  if (isProCommand(command)) {
+    if (!isProUser) {
+      console.log(`⛔ "${command}" is a Pro-only command. Upgrade at https://example.com/pro`)
+      return
+    }
+    console.log(`✅ Running Pro command: "${command}"`)
+  } else {
+    console.log(`✅ Running free command: "${command}"`)
+  }
+}
+
+const userCommand = process.env.CLI_COMMAND || 'ci'
+const userIsPro = process.env.IS_PRO === 'true' // set IS_PRO=true to simulate a Pro user
+
+// Check a few commands
+const commands = ['gh-action', 'ci', 'mcp', 'generate', 'help']
+
+console.log('--- isProCommand checks ---')
+for (const cmd of commands) {
+  console.log(`isProCommand("${cmd}") =>`, isProCommand(cmd))
+}
+// Output:
+// isProCommand("gh-action") => true
+// isProCommand("ci")        => true
+// isProCommand("mcp")       => true
+// isProCommand("generate")  => false
+// isProCommand("help")      => false
+
+console.log('\n--- Gating example ---')
+runCommand(userCommand, userIsPro)
+// With CLI_COMMAND=ci and IS_PRO unset:
+// ⛔ "ci" is a Pro-only command. Upgrade at https://example.com/pro
+```
+