reqon-dsl 0.2.0

package/docusaurus/docs/authentication/bearer.md

@@ -0,0 +1,282 @@
+---
+sidebar_position: 3
+---
+
+# Bearer Token Authentication
+
+Bearer token authentication is the most common auth method for REST APIs. The token is sent in the `Authorization` header with each request.
+
+## Configuration
+
+### Mission File
+
+```vague
+source API {
+  auth: bearer,
+  base: "https://api.example.com"
+}
+```
+
+### Credentials File
+
+```json
+{
+  "API": {
+    "type": "bearer",
+    "token": "your-api-token"
+  }
+}
+```
+
+## How It Works
+
+Reqon adds the token to every request:
+
+```http
+GET /api/users HTTP/1.1
+Host: api.example.com
+Authorization: Bearer your-api-token
+```
+
+## Credential Options
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Must be `"bearer"` |
+| `token` | Yes | The bearer token |
+
+## Environment Variables
+
+### In Credentials File
+
+```json
+{
+  "API": {
+    "type": "bearer",
+    "token": "${API_TOKEN}"
+  }
+}
+```
+
+Then set the environment variable:
+
+```bash
+export API_TOKEN="your-token"
+reqon mission.vague --auth credentials.json
+```
+
+### In Mission File
+
+```vague
+source API {
+  auth: bearer,
+  base: "https://api.example.com",
+  token: env("API_TOKEN")
+}
+```
+
+## Common Use Cases
+
+### GitHub API
+
+```vague
+source GitHub {
+  auth: bearer,
+  base: "https://api.github.com"
+}
+```
+
+```json
+{
+  "GitHub": {
+    "type": "bearer",
+    "token": "ghp_xxxxxxxxxxxxxxxxxxxx"
+  }
+}
+```
+
+### Stripe API
+
+```vague
+source Stripe {
+  auth: bearer,
+  base: "https://api.stripe.com/v1"
+}
+```
+
+```json
+{
+  "Stripe": {
+    "type": "bearer",
+    "token": "sk_live_xxxxxxxxxxxxxxxxxxxx"
+  }
+}
+```
+
+### Custom API
+
+```vague
+source CustomAPI {
+  auth: bearer,
+  base: "https://api.mycompany.com/v1"
+}
+```
+
+```json
+{
+  "CustomAPI": {
+    "type": "bearer",
+    "token": "your-custom-token"
+  }
+}
+```
+
+## Token Rotation
+
+### Manual Rotation
+
+1. Generate new token in API provider
+2. Update credentials file
+3. Run mission
+
+### Programmatic Rotation
+
+```typescript
+import { execute } from 'reqon';
+
+const token = await fetchNewToken(); // Your logic
+
+await execute(source, {
+  auth: {
+    API: {
+      type: 'bearer',
+      token
+    }
+  }
+});
+```
+
+## Handling Expiration
+
+Bearer tokens may expire. Handle with match:
+
+```vague
+action FetchData {
+  get "/data"
+
+  match response {
+    { error: _, code: 401 } -> abort "Token expired - please update credentials",
+    _ -> continue
+  }
+}
+```
+
+Or with token refresh:
+
+```vague
+action FetchData {
+  get "/data"
+
+  match response {
+    { error: _, code: 401 } -> jump RefreshToken then retry,
+    _ -> continue
+  }
+}
+
+action RefreshToken {
+  post "/auth/token" {
+    body: { apiKey: env("API_KEY") }
+  }
+  // Response contains new token
+}
+```
+
+## Multiple Tokens
+
+For APIs requiring different tokens per endpoint:
+
+```vague
+source ReadAPI {
+  auth: bearer,
+  base: "https://api.example.com"
+}
+
+source WriteAPI {
+  auth: bearer,
+  base: "https://api.example.com"
+}
+```
+
+```json
+{
+  "ReadAPI": {
+    "type": "bearer",
+    "token": "read-only-token"
+  },
+  "WriteAPI": {
+    "type": "bearer",
+    "token": "write-token"
+  }
+}
+```
+
+## Security Best Practices
+
+### Store Tokens Securely
+
+```bash
+# Never commit tokens
+echo "credentials.json" >> .gitignore
+```
+
+### Use Environment Variables
+
+```bash
+export API_TOKEN=$(cat ~/.secrets/api-token)
+```
+
+### Rotate Regularly
+
+Set up periodic token rotation in your CI/CD pipeline.
+
+### Use Minimal Scopes
+
+If the API supports scoped tokens, use the minimum required permissions.
+
+## Troubleshooting
+
+### "401 Unauthorized"
+
+1. Check token is correct
+2. Check token hasn't expired
+3. Verify token has required permissions
+
+### "Invalid token format"
+
+Ensure token doesn't have extra whitespace:
+
+```json
+{
+  "API": {
+    "type": "bearer",
+    "token": "your-token"  // No leading/trailing spaces
+  }
+}
+```
+
+### Token Not Being Sent
+
+Verify source name matches:
+
+```vague
+source MyAPI { auth: bearer }  // Name: MyAPI
+```
+
+```json
+{
+  "MyAPI": {  // Must match exactly
+    "type": "bearer",
+    "token": "..."
+  }
+}
+```

package/docusaurus/docs/authentication/oauth2.md

@@ -0,0 +1,317 @@
+---
+sidebar_position: 2
+---
+
+# OAuth 2.0 Authentication
+
+OAuth 2.0 is the industry standard for API authentication, used by most enterprise APIs. Reqon supports OAuth 2.0 with automatic token refresh.
+
+## Configuration
+
+### Mission File
+
+```vague
+source Xero {
+  auth: oauth2,
+  base: "https://api.xero.com/api.xro/2.0"
+}
+```
+
+### Credentials File
+
+```json
+{
+  "Xero": {
+    "type": "oauth2",
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret",
+    "accessToken": "current-access-token",
+    "refreshToken": "current-refresh-token",
+    "tokenUrl": "https://identity.xero.com/connect/token",
+    "scopes": ["accounting.transactions.read", "accounting.contacts.read"],
+    "expiresAt": "2024-01-20T10:30:00Z"
+  }
+}
+```
+
+## Credential Options
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Must be `"oauth2"` |
+| `clientId` | Yes | OAuth client ID |
+| `clientSecret` | Yes | OAuth client secret |
+| `accessToken` | Yes | Current access token |
+| `refreshToken` | Yes | Token used to get new access tokens |
+| `tokenUrl` | Yes | Token endpoint URL |
+| `scopes` | No | Requested scopes |
+| `expiresAt` | No | When current token expires |
+
+## Token Refresh
+
+### Automatic Refresh
+
+When `expiresAt` is set and token expires, Reqon automatically:
+
+1. Calls `tokenUrl` with refresh token
+2. Updates access token
+3. Retries the failed request
+
+```json
+{
+  "Xero": {
+    "type": "oauth2",
+    "clientId": "...",
+    "clientSecret": "...",
+    "accessToken": "old-token",
+    "refreshToken": "refresh-token",
+    "tokenUrl": "https://identity.xero.com/connect/token",
+    "expiresAt": "2024-01-20T10:30:00Z"
+  }
+}
+```
+
+### On 401 Response
+
+Even without `expiresAt`, Reqon refreshes on 401:
+
+```vague
+action FetchData {
+  get "/data"
+  // If 401, automatic refresh attempt
+}
+```
+
+### Manual Refresh Pattern
+
+For non-standard APIs:
+
+```vague
+action FetchData {
+  get "/data"
+
+  match response {
+    { error: _, code: 401 } -> jump RefreshToken then retry,
+    _ -> continue
+  }
+}
+
+action RefreshToken {
+  post "/oauth/token" {
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded"
+    },
+    body: {
+      grant_type: "refresh_token",
+      refresh_token: env("REFRESH_TOKEN"),
+      client_id: env("CLIENT_ID"),
+      client_secret: env("CLIENT_SECRET")
+    }
+  }
+
+  // Store new tokens
+  store {
+    accessToken: response.access_token,
+    refreshToken: response.refresh_token
+  } -> tokens
+}
+```
+
+## Common OAuth2 Providers
+
+### Xero
+
+```json
+{
+  "Xero": {
+    "type": "oauth2",
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret",
+    "accessToken": "...",
+    "refreshToken": "...",
+    "tokenUrl": "https://identity.xero.com/connect/token"
+  }
+}
+```
+
+### QuickBooks
+
+```json
+{
+  "QuickBooks": {
+    "type": "oauth2",
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret",
+    "accessToken": "...",
+    "refreshToken": "...",
+    "tokenUrl": "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer"
+  }
+}
+```
+
+### Salesforce
+
+```json
+{
+  "Salesforce": {
+    "type": "oauth2",
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret",
+    "accessToken": "...",
+    "refreshToken": "...",
+    "tokenUrl": "https://login.salesforce.com/services/oauth2/token"
+  }
+}
+```
+
+### Google APIs
+
+```json
+{
+  "Google": {
+    "type": "oauth2",
+    "clientId": "your-client-id.apps.googleusercontent.com",
+    "clientSecret": "your-client-secret",
+    "accessToken": "...",
+    "refreshToken": "...",
+    "tokenUrl": "https://oauth2.googleapis.com/token"
+  }
+}
+```
+
+### Microsoft Graph
+
+```json
+{
+  "Microsoft": {
+    "type": "oauth2",
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret",
+    "accessToken": "...",
+    "refreshToken": "...",
+    "tokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token"
+  }
+}
+```
+
+## Token Storage
+
+### File-Based (Development)
+
+Tokens are stored in the credentials file. Reqon updates them after refresh.
+
+### Secure Storage (Production)
+
+For production, use secure storage:
+
+```typescript
+import { execute } from 'reqon';
+import { getSecureTokens, saveSecureTokens } from './secure-storage';
+
+const tokens = await getSecureTokens('Xero');
+
+const result = await execute(source, {
+  auth: {
+    Xero: {
+      type: 'oauth2',
+      ...tokens
+    }
+  },
+  onTokenRefresh: async (source, newTokens) => {
+    await saveSecureTokens(source, newTokens);
+  }
+});
+```
+
+## Scopes
+
+Request specific scopes:
+
+```json
+{
+  "API": {
+    "type": "oauth2",
+    "scopes": [
+      "read:users",
+      "write:users",
+      "read:orders"
+    ]
+  }
+}
+```
+
+## Additional Headers
+
+Some APIs require extra headers:
+
+```vague
+source API {
+  auth: oauth2,
+  base: "https://api.example.com",
+  headers: {
+    "Xero-Tenant-Id": env("XERO_TENANT_ID")
+  }
+}
+```
+
+## Handling Multi-Tenant
+
+For APIs like Xero with multiple organizations:
+
+```vague
+mission XeroSync {
+  source Xero {
+    auth: oauth2,
+    base: "https://api.xero.com/api.xro/2.0",
+    headers: {
+      "Xero-Tenant-Id": env("XERO_TENANT_ID")
+    }
+  }
+}
+```
+
+Or iterate over tenants:
+
+```vague
+action SyncAllTenants {
+  get "/connections"
+
+  for tenant in response {
+    // Each tenant request
+    get concat("/", tenant.tenantId, "/invoices") {
+      headers: { "Xero-Tenant-Id": tenant.tenantId }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### "invalid_grant" Error
+
+Refresh token is invalid or expired. Re-authenticate:
+
+1. Go through OAuth flow again
+2. Get new access and refresh tokens
+3. Update credentials file
+
+### "Token expired" but No Refresh
+
+Ensure `refreshToken` and `tokenUrl` are set:
+
+```json
+{
+  "API": {
+    "refreshToken": "must-be-present",
+    "tokenUrl": "must-be-present"
+  }
+}
+```
+
+### "Invalid client" Error
+
+Check `clientId` and `clientSecret` are correct.
+
+### Scope Issues
+
+Ensure requested scopes are authorized for your app.