reqon-dsl 0.2.0 → 0.4.0

package/docusaurus/docs/authentication/bearer.md

@@ -1,282 +0,0 @@
----
-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

@@ -1,317 +0,0 @@
----
-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.