@datatamer.ai/agentdev 1.0.6 → 1.0.7

package/skills/api-integration-guide.md

@@ -0,0 +1,1382 @@
+# API Integration Guide — Step-by-Step Playbook
+
+A comprehensive guide for integrating new APIs into the agentdev platform, based on the LinkedIn integration process.
+
+## Overview
+
+This guide provides a proven, repeatable process for integrating third-party APIs into agentdev. Follow these steps to add support for any OAuth-based API (Twitter, GitHub, Slack, etc.) or API-key-based services.
+
+**Time Estimate:** 20-40 hours depending on API complexity
+**Difficulty:** Medium to Advanced
+**Prerequisites:** Node.js, ES modules, OAuth 2.0 knowledge
+
+---
+
+## Phase 1: Research & Planning (2-4 hours)
+
+### Step 1.1: API Research
+
+**Objective:** Understand the API capabilities, limitations, and requirements.
+
+**Tasks:**
+1. **Review API Documentation**
+   - Read official API docs thoroughly
+   - Identify API version (e.g., LinkedIn uses v2, Twitter uses v2)
+   - Note API base URL (e.g., `https://api.linkedin.com`)
+   - Document rate limits and quotas
+   - Understand authentication method (OAuth 2.0, API keys, etc.)
+
+2. **Identify Core Endpoints**
+   - List all available endpoints
+   - Categorize by functionality (e.g., posts, analytics, users)
+   - Note request/response formats
+   - Document required vs. optional parameters
+
+3. **Understand OAuth Scopes**
+   - List all available OAuth scopes
+   - Map scopes to features you want to implement
+   - Note scope dependencies (some scopes require others)
+   - Check for special permissions (e.g., LinkedIn org admin)
+
+**Example (LinkedIn):**
+```
+API Base: https://api.linkedin.com
+Version: 202501
+Auth: OAuth 2.0
+
+Core Endpoints:
+- POST /rest/posts - Create posts (scope: w_member_social)
+- GET /rest/posts - List posts (scope: r_member_social)
+- GET /rest/socialMetadata/{urn} - Get analytics (scope: r_member_social)
+- GET /v2/connections - List connections (scope: r_1st_connections)
+
+Rate Limits:
+- 150 posts/day per user
+- 100,000 API requests/day per app
+```
+
+### Step 1.2: Feature Prioritization
+
+**Objective:** Decide what features to implement first.
+
+**Process:**
+1. **List Potential Features**
+   - Write down all possible features
+   - Group by complexity (simple, medium, complex)
+   - Estimate implementation time for each
+
+2. **Create Implementation Phases**
+   - Phase 1: Quick wins (basic functionality)
+   - Phase 2: Medium features (analytics, advanced reads)
+   - Phase 3: Complex features (video uploads, webhooks)
+
+3. **Define MVP (Minimum Viable Product)**
+   - Choose 3-5 core features for initial release
+   - Ensure features provide immediate value
+   - Keep scope manageable (1-2 weeks max)
+
+**Example (LinkedIn):**
+```
+MVP Features (Week 1):
+✅ Create text posts
+✅ Create article posts (with URL)
+✅ Create image posts
+✅ View user profile
+✅ Check auth status
+
+Phase 2 (Week 2):
+✅ Post management (list, view, edit, delete)
+✅ Analytics (stats, reactions, comments)
+✅ Connections management
+
+Phase 3 (Week 3):
+✅ Organization pages
+✅ Video uploads
+❌ Messages API (requires special approval)
+```
+
+### Step 1.3: Create Implementation Plan
+
+**Objective:** Document the implementation strategy.
+
+**Create:** `IMPLEMENTATION_PLAN.md`
+
+**Template:**
+```markdown
+# [API Name] Integration Plan
+
+## Context
+- Current state: [What exists now]
+- Problem: [What's missing]
+- Solution: [What we're building]
+
+## Features
+### Phase 1: MVP
+- Feature 1: [Description]
+- Feature 2: [Description]
+
+### Phase 2: Advanced
+- Feature 3: [Description]
+
+## Technical Approach
+- OAuth provider: [Name]
+- Scopes needed: [List]
+- API endpoints: [List]
+
+## Files to Create/Modify
+- `/agentdev-webui/lib/[api].js` - OAuth handler
+- `/packages/agentdev-client/src/[api]/api.js` - API client
+- `/packages/agentdev-client/src/cli/[api].js` - CLI commands
+- `/packages/agentdev-client/skills/agentdev-[api].md` - Documentation
+
+## Timeline
+- Week 1: OAuth + Basic API
+- Week 2: Advanced features
+- Week 3: Testing + Documentation
+```
+
+---
+
+## Phase 2: OAuth Setup (3-5 hours)
+
+### Step 2.1: Register OAuth Application
+
+**Objective:** Get OAuth credentials from the API provider.
+
+**Tasks:**
+1. **Create Developer Account**
+   - Sign up for developer access
+   - Verify email/identity if required
+   - Accept developer terms
+
+2. **Create OAuth Application**
+   - Go to API provider's developer portal
+   - Create new app/project
+   - Fill in application details:
+     - Name: "AgentDev Integration"
+     - Description: "AI agent platform integration"
+     - Website: Your agentdev URL
+     - Redirect URI: `https://your-domain.com/api/auth/callback/[provider]`
+
+3. **Save Credentials**
+   - Copy Client ID
+   - Copy Client Secret
+   - Store securely (never commit to git)
+   - Add to password manager
+
+**Example (LinkedIn):**
+```
+Portal: https://www.linkedin.com/developers/apps
+Redirect URI: https://agentdev.datatamer.ai/api/auth/callback/linkedin
+Scopes: openid profile email w_member_social r_member_social...
+```
+
+### Step 2.2: Create Server-Side OAuth Handler
+
+**Objective:** Implement OAuth flow in the backend.
+
+**File:** `/agentdev-webui/lib/[api-name].js`
+
+**Template:**
+```javascript
+const db = require('./database');
+const encryption = require('./encryption');
+
+const AUTH_URL = 'https://provider.com/oauth/authorize';
+const TOKEN_URL = 'https://provider.com/oauth/token';
+const API_BASE = 'https://api.provider.com';
+const SCOPES = 'scope1 scope2 scope3';
+
+/**
+ * Build authorization URL
+ */
+async function getAuthorizationUrl(state, redirectUri) {
+  const config = await db.getOAuthProviderConfig('[provider]');
+  if (!config || !config.client_id) {
+    throw new Error('[Provider] OAuth not configured');
+  }
+
+  const clientId = encryption.decrypt(config.client_id);
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    state: state,
+    scope: SCOPES
+  });
+
+  return `${AUTH_URL}?${params.toString()}`;
+}
+
+/**
+ * Exchange authorization code for access token
+ */
+async function exchangeCodeForToken(code, redirectUri) {
+  const config = await db.getOAuthProviderConfig('[provider]');
+  const clientId = encryption.decrypt(config.client_id);
+  const clientSecret = encryption.decrypt(config.client_secret);
+
+  const res = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      client_secret: clientSecret
+    }).toString()
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Token exchange failed (${res.status}): ${text}`);
+  }
+
+  const data = await res.json();
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token || null,
+    expiresIn: data.expires_in
+  };
+}
+
+/**
+ * Refresh an expired access token
+ */
+async function refreshAccessToken(refreshToken) {
+  const config = await db.getOAuthProviderConfig('[provider]');
+  const clientId = encryption.decrypt(config.client_id);
+  const clientSecret = encryption.decrypt(config.client_secret);
+
+  const res = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret
+    }).toString()
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Token refresh failed (${res.status}): ${text}`);
+  }
+
+  const data = await res.json();
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token || refreshToken,
+    expiresIn: data.expires_in
+  };
+}
+
+/**
+ * Fetch user profile
+ */
+async function fetchProfile(accessToken) {
+  const res = await fetch(`${API_BASE}/v1/user`, {
+    headers: {
+      'Authorization': `Bearer ${accessToken}`
+    }
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Profile fetch failed (${res.status}): ${text}`);
+  }
+
+  const data = await res.json();
+  return {
+    id: data.id,
+    name: data.name,
+    email: data.email,
+    picture: data.avatar_url
+  };
+}
+
+module.exports = {
+  getAuthorizationUrl,
+  exchangeCodeForToken,
+  refreshAccessToken,
+  fetchProfile,
+  AUTH_URL,
+  TOKEN_URL,
+  SCOPES
+};
+```
+
+### Step 2.3: Configure OAuth in Admin Panel
+
+**Objective:** Add OAuth credentials to database.
+
+**Tasks:**
+1. **Access Admin Panel**
+   - Navigate to `/admin/oauth` (or create this page)
+   - Add new provider section
+
+2. **Add Provider Configuration**
+   ```sql
+   INSERT INTO oauth_providers (
+     provider_name,
+     client_id,
+     client_secret,
+     enabled
+   ) VALUES (
+     '[provider]',
+     '[encrypted_client_id]',
+     '[encrypted_client_secret]',
+     true
+   );
+   ```
+
+3. **Test OAuth Flow**
+   - Visit `/profile` page
+   - Click "Connect [Provider]"
+   - Complete authorization
+   - Verify token is saved
+
+---
+
+## Phase 3: API Client Implementation (8-12 hours)
+
+### Step 3.1: Create Modular API Structure
+
+**Objective:** Build a well-organized API client.
+
+**Directory Structure:**
+```
+/packages/agentdev-client/src/[api-name]/
+├── api.js (re-export wrapper)
+└── api/
+    ├── index.js (main entry point)
+    ├── core.js (HTTP client)
+    ├── [feature1].js (e.g., posts.js)
+    ├── [feature2].js (e.g., analytics.js)
+    └── [feature3].js (e.g., users.js)
+```
+
+### Step 3.2: Create Core HTTP Client
+
+**File:** `/packages/agentdev-client/src/[api]/api/core.js`
+
+**Template:**
+```javascript
+/**
+ * [API Name] API Core - Base HTTP client and utilities
+ */
+
+export const API_BASE = 'https://api.provider.com';
+export const API_VERSION = 'v1';
+
+/**
+ * Core REST API helper
+ * Handles authentication, error responses, and standard headers
+ */
+export async function apiRequest(method, path, token, body = null, extraHeaders = {}) {
+  const opts = {
+    method,
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Accept': 'application/json',
+      ...extraHeaders
+    }
+  };
+
+  if (body) {
+    opts.headers['Content-Type'] = 'application/json';
+    opts.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(`${API_BASE}${path}`, opts);
+
+  if (!res.ok) {
+    const text = await res.text();
+
+    // Handle token expiration
+    if (res.status === 401) {
+      throw new Error('TOKEN_EXPIRED');
+    }
+
+    // Handle rate limiting
+    if (res.status === 429) {
+      const retryAfter = res.headers.get('Retry-After');
+      throw new Error(`API rate limit exceeded. Retry after: ${retryAfter || 'unknown'}`);
+    }
+
+    // Handle forbidden
+    if (res.status === 403) {
+      throw new Error('Insufficient permissions. Check OAuth scopes.');
+    }
+
+    throw new Error(`API ${method} ${path} failed (${res.status}): ${text}`);
+  }
+
+  // Handle No Content responses
+  if (res.status === 204) {
+    return { success: true };
+  }
+
+  // Handle Created responses
+  if (res.status === 201) {
+    const location = res.headers.get('Location');
+    if (location) {
+      return { id: location, success: true };
+    }
+  }
+
+  return res.json();
+}
+
+/**
+ * Resolve token from CLI argument or environment variable
+ */
+export function resolveToken(cliToken) {
+  return cliToken || process.env.[PROVIDER]_TOKEN || null;
+}
+```
+
+### Step 3.3: Implement Feature Modules
+
+**Pattern:** One module per feature category
+
+**Example - Posts Module:**
+
+**File:** `/packages/agentdev-client/src/[api]/api/posts.js`
+
+```javascript
+/**
+ * [API Name] - Posts Operations
+ */
+
+import { apiRequest } from './core.js';
+
+/**
+ * Create a text post
+ */
+export async function createPost(token, text, options = {}) {
+  const body = {
+    text: text,
+    visibility: options.visibility || 'public'
+  };
+
+  return apiRequest('POST', '/v1/posts', token, body);
+}
+
+/**
+ * List user's posts
+ */
+export async function listPosts(token, userId, options = {}) {
+  const params = new URLSearchParams({
+    user_id: userId,
+    limit: options.limit || 10,
+    offset: options.offset || 0
+  });
+
+  return apiRequest('GET', `/v1/posts?${params}`, token);
+}
+
+/**
+ * Get post details
+ */
+export async function getPost(token, postId) {
+  return apiRequest('GET', `/v1/posts/${postId}`, token);
+}
+
+/**
+ * Delete a post
+ */
+export async function deletePost(token, postId) {
+  return apiRequest('DELETE', `/v1/posts/${postId}`, token);
+}
+
+/**
+ * Update a post
+ */
+export async function updatePost(token, postId, updates) {
+  return apiRequest('PATCH', `/v1/posts/${postId}`, token, updates);
+}
+```
+
+### Step 3.4: Create Main Index
+
+**File:** `/packages/agentdev-client/src/[api]/api/index.js`
+
+```javascript
+/**
+ * [API Name] - Main Entry Point
+ * Re-exports all API functions from modular structure
+ */
+
+// Core utilities
+export { apiRequest, resolveToken, API_BASE, API_VERSION } from './core.js';
+
+// Feature modules
+export {
+  createPost,
+  listPosts,
+  getPost,
+  deletePost,
+  updatePost
+} from './posts.js';
+
+export {
+  getUserProfile,
+  updateUserProfile
+} from './users.js';
+
+// Add more exports as you create modules
+```
+
+### Step 3.5: Create Re-export Wrapper
+
+**File:** `/packages/agentdev-client/src/[api]/api.js`
+
+```javascript
+/**
+ * [API Name] REST API module (ESM)
+ * Provides programmatic access to [Provider] APIs for agents.
+ *
+ * This file maintains backward compatibility by re-exporting
+ * from the modular structure in ./api/
+ */
+
+export * from './api/index.js';
+```
+
+---
+
+## Phase 4: CLI Commands Implementation (6-10 hours)
+
+### Step 4.1: Create Modular CLI Structure
+
+**Directory Structure:**
+```
+/packages/agentdev-client/src/cli/[api-name]/
+├── index.js (main registration)
+├── helpers.js (shared utilities)
+├── [feature1].js (e.g., posts.js)
+├── [feature2].js (e.g., analytics.js)
+└── [feature3].js (e.g., users.js)
+```
+
+### Step 4.2: Create CLI Helpers
+
+**File:** `/packages/agentdev-client/src/cli/[api]/helpers.js`
+
+```javascript
+/**
+ * [API Name] CLI - Shared Helpers
+ */
+
+import chalk from 'chalk';
+import { getConfig } from '../../config/config.js';
+
+/**
+ * Fetch [Provider] access token from server OAuth endpoint
+ */
+export async function getProviderToken() {
+  const config = getConfig();
+  const apiUrl = config.apiUrl || 'https://agentdev.datatamer.ai';
+  const agentToken = config.token;
+
+  if (!agentToken) {
+    throw new Error('Agent not registered. Run "agentdev register" first.');
+  }
+
+  try {
+    const res = await fetch(`${apiUrl}/api/agent/oauth?provider=[provider]`, {
+      headers: {
+        'Authorization': `Bearer ${agentToken}`,
+        'Content-Type': 'application/json'
+      }
+    });
+
+    if (!res.ok) {
+      if (res.status === 404) {
+        throw new Error('[Provider] not connected. Connect at ' + apiUrl + '/profile');
+      }
+      const text = await res.text();
+      throw new Error(`Failed to fetch token (${res.status}): ${text}`);
+    }
+
+    const data = await res.json();
+    return data.[provider].access_token;
+  } catch (error) {
+    if (error.message.includes('not connected')) {
+      throw error;
+    }
+    throw new Error(`Failed to fetch token: ${error.message}`);
+  }
+}
+
+/**
+ * Centralized error handler
+ */
+export function handleProviderError(error) {
+  if (error.message === 'TOKEN_EXPIRED') {
+    console.error(chalk.red('✗ Token expired. Please reconnect at /profile'));
+  } else if (error.message.includes('not connected')) {
+    console.error(chalk.red('✗ ' + error.message));
+  } else if (error.message.includes('rate limit')) {
+    console.error(chalk.red('✗ ' + error.message));
+  } else if (error.message.includes('permissions')) {
+    console.error(chalk.red('✗ ' + error.message));
+    console.error(chalk.yellow('Please reconnect to grant new permissions'));
+  } else {
+    console.error(chalk.red('✗ Operation failed:'), error.message);
+  }
+  process.exit(1);
+}
+```
+
+### Step 4.3: Create Feature Command Handlers
+
+**File:** `/packages/agentdev-client/src/cli/[api]/posts.js`
+
+```javascript
+/**
+ * [API Name] CLI - Post Commands
+ */
+
+import chalk from 'chalk';
+import {
+  resolveToken,
+  createPost,
+  listPosts,
+  getPost,
+  deletePost,
+  updatePost
+} from '../../[api]/api.js';
+import { getProviderToken, handleProviderError } from './helpers.js';
+
+/**
+ * Handle post creation
+ */
+export async function handlePostCreate(opts) {
+  try {
+    const token = resolveToken() || await getProviderToken();
+
+    const result = await createPost(token, opts.text, {
+      visibility: opts.visibility || 'public'
+    });
+
+    console.log(chalk.green('✓ Post created successfully'));
+    if (result.id) {
+      console.log(chalk.gray(`Post ID: ${result.id}`));
+    }
+  } catch (error) {
+    handleProviderError(error);
+  }
+}
+
+/**
+ * Handle post listing
+ */
+export async function handlePostList(opts) {
+  try {
+    const token = resolveToken() || await getProviderToken();
+
+    const result = await listPosts(token, opts.userId, {
+      limit: opts.limit || 10
+    });
+
+    if (!result.posts || result.posts.length === 0) {
+      console.log(chalk.yellow('No posts found'));
+      return;
+    }
+
+    console.log(chalk.bold(`\nPosts (${result.posts.length} shown)`));
+    console.log(chalk.gray('─'.repeat(80)));
+
+    result.posts.forEach((post, index) => {
+      console.log(`${chalk.cyan(`${index + 1}.`)} ${post.text.substring(0, 100)}...`);
+      console.log(`   ${chalk.gray('ID:')} ${post.id}`);
+      console.log();
+    });
+
+    console.log(chalk.gray('─'.repeat(80)));
+  } catch (error) {
+    handleProviderError(error);
+  }
+}
+
+/**
+ * Handle post deletion
+ */
+export async function handlePostDelete(postId, opts) {
+  try {
+    const token = resolveToken() || await getProviderToken();
+
+    if (!opts.confirm) {
+      console.log(chalk.yellow('⚠ Add --confirm flag to proceed'));
+      process.exit(0);
+    }
+
+    await deletePost(token, postId);
+    console.log(chalk.green('✓ Post deleted successfully'));
+  } catch (error) {
+    handleProviderError(error);
+  }
+}
+
+/**
+ * Register post commands
+ */
+export function registerPostCommands(api) {
+  const post = api
+    .command('post')
+    .description('[Provider] post operations');
+
+  post
+    .command('create')
+    .description('Create a post')
+    .requiredOption('--text <text>', 'Post text')
+    .option('--visibility <type>', 'Visibility: public or private', 'public')
+    .action(handlePostCreate);
+
+  post
+    .command('list')
+    .description('List posts')
+    .option('--user-id <id>', 'User ID')
+    .option('--limit <number>', 'Number of posts', '10')
+    .action(handlePostList);
+
+  post
+    .command('delete <post-id>')
+    .description('Delete a post')
+    .option('--confirm', 'Confirm deletion')
+    .action(handlePostDelete);
+}
+```
+
+### Step 4.4: Create Main CLI Index
+
+**File:** `/packages/agentdev-client/src/cli/[api]/index.js`
+
+```javascript
+/**
+ * [API Name] CLI - Main Entry Point
+ */
+
+import { registerPostCommands } from './posts.js';
+import { registerUserCommands } from './users.js';
+// Import other command modules
+
+/**
+ * Register [Provider] command group with Commander
+ */
+export function register[Provider]Command(program) {
+  const api = program
+    .command('[provider]')
+    .description('[Provider] operations');
+
+  // Register all command groups
+  registerPostCommands(api);
+  registerUserCommands(api);
+  // Register other command groups
+
+  return api;
+}
+```
+
+### Step 4.5: Create CLI Re-export Wrapper
+
+**File:** `/packages/agentdev-client/src/cli/[api].js`
+
+```javascript
+/**
+ * `agentdev [provider]` subcommand group
+ *
+ * This file maintains backward compatibility by re-exporting
+ * from the modular structure in ./[api]/
+ */
+
+export { register[Provider]Command } from './[api]/index.js';
+```
+
+---
+
+## Phase 5: Skill Documentation (2-4 hours)
+
+### Step 5.1: Create Skill File
+
+**File:** `/packages/agentdev-client/skills/agentdev-[provider].md`
+
+**Template:**
+```markdown
+# agentdev [provider] — [Provider] CLI
+
+Use `agentdev [provider]` for ALL [Provider] operations. Do NOT attempt to use [Provider] APIs directly.
+
+## Prerequisites
+
+User must connect their [Provider] account first:
+1. Visit /profile page on AgentDev
+2. Click "Connect [Provider]"
+3. Complete OAuth authorization flow
+
+If [Provider] is not connected, all commands will fail with instructions to connect.
+
+## Commands
+
+### Create Post
+
+```bash
+agentdev [provider] post create --text "Hello world!"
+```
+
+### List Posts
+
+```bash
+agentdev [provider] post list --limit 10
+```
+
+### Delete Post
+
+```bash
+agentdev [provider] post delete <post-id> --confirm
+```
+
+## Rate Limits
+
+- **[X] requests per hour** per user
+- **[Y] posts per day** per user
+
+If rate limit is exceeded, you'll receive a clear error message.
+
+## Error Handling
+
+| Error | Meaning | Action |
+|-------|---------|--------|
+| "[Provider] not connected" | User hasn't connected account | Direct user to /profile |
+| "Token expired" | OAuth token expired | User must reconnect at /profile |
+| "Rate limit exceeded" | Hit API rate limits | Wait for retry period |
+
+## Agent Task Examples
+
+### Example 1: Post update
+
+When asked to "post to [Provider] about completing task":
+
+```bash
+agentdev [provider] post create --text "✅ Completed task #123"
+```
+
+### Example 2: Check recent posts
+
+When asked to "show my recent [Provider] posts":
+
+```bash
+agentdev [provider] post list --limit 5
+```
+
+## Required OAuth Scopes
+
+The following scopes are automatically requested during OAuth flow:
+- `scope1` - Description
+- `scope2` - Description
+- `scope3` - Description
+
+## Notes
+
+- All posts are created as the authenticated user
+- Post IDs are returned on successful creation
+- Token refresh is handled automatically
+```
+
+---
+
+## Phase 6: Testing & Validation (4-6 hours)
+
+### Step 6.1: Manual Testing Checklist
+
+**OAuth Flow:**
+- [ ] Visit /profile page
+- [ ] Click "Connect [Provider]"
+- [ ] Complete authorization
+- [ ] Verify token is saved in database
+- [ ] Verify token works for API calls
+
+**CLI Commands:**
+- [ ] Test `agentdev [provider] auth` - Check connection status
+- [ ] Test `agentdev [provider] post create --text "test"` - Create post
+- [ ] Test `agentdev [provider] post list` - List posts
+- [ ] Test `agentdev [provider] post delete <id> --confirm` - Delete post
+- [ ] Test error handling (invalid token, missing scopes, rate limits)
+
+**Error Cases:**
+- [ ] Test with expired token
+- [ ] Test with missing OAuth scopes
+- [ ] Test with invalid post ID
+- [ ] Test rate limit handling
+- [ ] Test network errors
+
+### Step 6.2: Create Unit Tests
+
+**File:** `/packages/agentdev-client/src/[api]/api/core.test.js`
+
+```javascript
+import { apiRequest } from './core.js';
+
+describe('[Provider] API Core', () => {
+  test('apiRequest handles 401 errors', async () => {
+    global.fetch = jest.fn(() =>
+      Promise.resolve({
+        ok: false,
+        status: 401,
+        text: () => Promise.resolve('Unauthorized')
+      })
+    );
+
+    await expect(
+      apiRequest('GET', '/test', 'invalid-token')
+    ).rejects.toThrow('TOKEN_EXPIRED');
+  });
+
+  test('apiRequest handles 429 rate limits', async () => {
+    global.fetch = jest.fn(() =>
+      Promise.resolve({
+        ok: false,
+        status: 429,
+        headers: new Map([['Retry-After', '60']]),
+        text: () => Promise.resolve('Rate limit')
+      })
+    );
+
+    await expect(
+      apiRequest('GET', '/test', 'token')
+    ).rejects.toThrow('rate limit');
+  });
+});
+```
+
+### Step 6.3: Integration Testing
+
+**Create:** `/packages/agentdev-client/src/[api]/integration.test.js`
+
+```javascript
+/**
+ * Integration tests for [Provider] API
+ * These tests require valid OAuth credentials
+ */
+
+import {
+  createPost,
+  listPosts,
+  deletePost
+} from './api.js';
+
+// Only run if token is available
+const TOKEN = process.env.[PROVIDER]_TOKEN;
+const runIntegrationTests = TOKEN && process.env.RUN_INTEGRATION_TESTS;
+
+describe.skipIf(!runIntegrationTests)('[Provider] Integration Tests', () => {
+  let testPostId;
+
+  test('Create post', async () => {
+    const result = await createPost(TOKEN, 'Test post from integration tests');
+    expect(result.id).toBeDefined();
+    testPostId = result.id;
+  });
+
+  test('List posts', async () => {
+    const result = await listPosts(TOKEN, 'me');
+    expect(result.posts).toBeDefined();
+    expect(Array.isArray(result.posts)).toBe(true);
+  });
+
+  test('Delete post', async () => {
+    if (testPostId) {
+      const result = await deletePost(TOKEN, testPostId);
+      expect(result.success).toBe(true);
+    }
+  });
+});
+```
+
+---
+
+## Phase 7: Deployment & Documentation (2-3 hours)
+
+### Step 7.1: Update Main CLI Entry Point
+
+**File:** `/packages/agentdev-client/src/cli/index.js`
+
+Add your new command:
+
+```javascript
+import { register[Provider]Command } from './cli/[provider].js';
+
+export function registerCommands(program) {
+  // ... existing commands
+  register[Provider]Command(program);
+}
+```
+
+### Step 7.2: Build & Test
+
+```bash
+cd /packages/agentdev-client
+npm run build
+npm test
+
+# Test CLI locally
+node dist/cli/index.js [provider] auth
+node dist/cli/index.js [provider] post create --text "Test"
+```
+
+### Step 7.3: Create Migration Guide
+
+**File:** `MIGRATION_GUIDE_[PROVIDER].md`
+
+```markdown
+# [Provider] Integration - Migration Guide
+
+## For Users
+
+### Step 1: Connect Your Account
+1. Visit https://agentdev.datatamer.ai/profile
+2. Click "Connect [Provider]"
+3. Authorize the application
+4. Verify connection with: `agentdev [provider] auth`
+
+### Step 2: Update CLI (if needed)
+```bash
+npm install -g agentdev-client@latest
+```
+
+### Step 3: Start Using
+```bash
+agentdev [provider] post create --text "Hello from AgentDev!"
+```
+
+## For Developers
+
+### New Files Added
+- `/agentdev-webui/lib/[provider].js` - OAuth handler
+- `/packages/agentdev-client/src/[provider]/api/` - API modules
+- `/packages/agentdev-client/src/cli/[provider]/` - CLI modules
+- `/packages/agentdev-client/skills/agentdev-[provider].md` - Documentation
+
+### OAuth Scopes
+The following scopes are requested:
+- scope1, scope2, scope3
+
+### Environment Variables (optional)
+```bash
+export [PROVIDER]_TOKEN="your-token-here"
+```
+```
+
+### Step 7.4: Create README Section
+
+Add to main README:
+
+```markdown
+## [Provider] Integration
+
+AgentDev supports [Provider] integration for [brief description].
+
+### Setup
+1. Connect your [Provider] account at `/profile`
+2. Use CLI: `agentdev [provider] --help`
+3. See full docs: [Link to skill doc]
+
+### Examples
+```bash
+# Create a post
+agentdev [provider] post create --text "Hello!"
+
+# List posts
+agentdev [provider] post list --limit 10
+```
+
+### Rate Limits
+- X posts per day
+- Y API requests per hour
+```
+
+---
+
+## Phase 8: Monitoring & Iteration (Ongoing)
+
+### Step 8.1: Add Logging
+
+**Update API client to log important events:**
+
+```javascript
+export async function apiRequest(method, path, token, body, extraHeaders) {
+  console.log(`[${new Date().toISOString()}] ${method} ${path}`);
+
+  try {
+    const result = await fetch(/* ... */);
+    console.log(`[${new Date().toISOString()}] ${method} ${path} - ${result.status}`);
+    return result;
+  } catch (error) {
+    console.error(`[${new Date().toISOString()}] ${method} ${path} - ERROR:`, error.message);
+    throw error;
+  }
+}
+```
+
+### Step 8.2: Monitor Usage
+
+**Track:**
+- Number of API calls per day
+- Error rates
+- Most used commands
+- Token refresh frequency
+- Rate limit hits
+
+### Step 8.3: Gather Feedback
+
+**Create feedback channels:**
+- GitHub issues for bug reports
+- Discord/Slack for questions
+- Usage analytics for feature requests
+
+### Step 8.4: Iterate
+
+**Based on feedback:**
+1. Add missing features
+2. Fix bugs
+3. Improve error messages
+4. Optimize performance
+5. Update documentation
+
+---
+
+## Common Patterns & Best Practices
+
+### OAuth Best Practices
+
+1. **Always Encrypt Credentials**
+   ```javascript
+   const encrypted = encryption.encrypt(clientSecret);
+   ```
+
+2. **Handle Token Refresh**
+   ```javascript
+   if (isTokenExpired(token)) {
+     token = await refreshAccessToken(refreshToken);
+   }
+   ```
+
+3. **Store Tokens Securely**
+   - Never log tokens
+   - Encrypt in database
+   - Don't commit to git
+
+### API Client Best Practices
+
+1. **Use Modular Structure**
+   - One module per feature category
+   - Core module for shared logic
+   - Index for re-exports
+
+2. **Handle Errors Gracefully**
+   ```javascript
+   if (res.status === 401) throw new Error('TOKEN_EXPIRED');
+   if (res.status === 429) throw new Error('RATE_LIMIT');
+   if (res.status === 403) throw new Error('FORBIDDEN');
+   ```
+
+3. **Validate Input**
+   ```javascript
+   if (!text || text.length > 280) {
+     throw new Error('Text must be 1-280 characters');
+   }
+   ```
+
+4. **Provide Clear Error Messages**
+   ```javascript
+   throw new Error('Post not found. Check the post ID and try again.');
+   ```
+
+### CLI Best Practices
+
+1. **Use Chalk for Colors**
+   ```javascript
+   console.log(chalk.green('✓ Success'));
+   console.error(chalk.red('✗ Error'));
+   console.log(chalk.yellow('⚠ Warning'));
+   console.log(chalk.gray('Additional info'));
+   ```
+
+2. **Require Confirmation for Destructive Actions**
+   ```javascript
+   if (!opts.confirm) {
+     console.log(chalk.yellow('Add --confirm to proceed'));
+     process.exit(0);
+   }
+   ```
+
+3. **Show Progress for Long Operations**
+   ```javascript
+   console.log('Uploading video...');
+   for (let i = 0; i < parts.length; i++) {
+     console.log(`  Part ${i+1}/${parts.length} uploaded`);
+   }
+   ```
+
+4. **Provide Examples in Help**
+   ```javascript
+   .command('create')
+   .description('Create a post')
+   .example('agentdev [provider] post create --text "Hello"')
+   ```
+
+### Documentation Best Practices
+
+1. **Include Examples**
+   - Show common use cases
+   - Provide copy-paste commands
+   - Explain expected output
+
+2. **Document Errors**
+   - List common errors
+   - Explain what they mean
+   - Provide solutions
+
+3. **Keep Updated**
+   - Update when adding features
+   - Document breaking changes
+   - Maintain changelog
+
+---
+
+## Quick Reference Checklist
+
+Use this checklist for every new API integration:
+
+### Pre-Implementation
+- [ ] Research API documentation
+- [ ] Identify OAuth scopes needed
+- [ ] List core endpoints
+- [ ] Document rate limits
+- [ ] Create implementation plan
+
+### OAuth Setup
+- [ ] Register OAuth application
+- [ ] Get client ID and secret
+- [ ] Create `/lib/[provider].js`
+- [ ] Implement authorization URL
+- [ ] Implement token exchange
+- [ ] Implement token refresh
+- [ ] Test OAuth flow
+
+### API Client
+- [ ] Create `/src/[api]/api/core.js`
+- [ ] Create feature modules (posts, users, etc.)
+- [ ] Create `/src/[api]/api/index.js`
+- [ ] Create `/src/[api]/api.js` wrapper
+- [ ] Write unit tests
+- [ ] Test API calls
+
+### CLI Commands
+- [ ] Create `/src/cli/[api]/helpers.js`
+- [ ] Create feature command modules
+- [ ] Create `/src/cli/[api]/index.js`
+- [ ] Create `/src/cli/[api].js` wrapper
+- [ ] Register with main CLI
+- [ ] Test all commands
+
+### Documentation
+- [ ] Create skill file `/skills/agentdev-[api].md`
+- [ ] Document all commands
+- [ ] Add examples
+- [ ] Document errors
+- [ ] Add to main README
+
+### Testing & Deployment
+- [ ] Manual testing
+- [ ] Integration testing
+- [ ] Build and verify
+- [ ] Create migration guide
+- [ ] Deploy to production
+- [ ] Monitor for issues
+
+---
+
+## Example Integrations
+
+This pattern has been successfully used for:
+
+1. **LinkedIn** (Implemented)
+   - OAuth 2.0
+   - Posts, analytics, connections
+   - Organization pages
+   - Video uploads
+
+2. **Twitter/X** (Future)
+   - OAuth 2.0
+   - Tweets, timelines, DMs
+   - Media uploads
+   - Analytics
+
+3. **GitHub** (Future)
+   - OAuth 2.0
+   - Repos, issues, PRs
+   - Actions, releases
+   - Webhooks
+
+4. **Slack** (Future)
+   - OAuth 2.0
+   - Messages, channels
+   - File uploads
+   - Slash commands
+
+---
+
+## Troubleshooting
+
+### OAuth Issues
+
+**Problem:** "Invalid redirect URI"
+**Solution:** Ensure redirect URI matches exactly in OAuth app settings
+
+**Problem:** "Invalid scopes"
+**Solution:** Check scopes are supported and spelled correctly
+
+**Problem:** "Token expired immediately"
+**Solution:** Check token expiration handling and refresh logic
+
+### API Issues
+
+**Problem:** 401 Unauthorized
+**Solution:** Verify token is valid and not expired
+
+**Problem:** 403 Forbidden
+**Solution:** Check OAuth scopes include required permissions
+
+**Problem:** 429 Rate Limited
+**Solution:** Implement exponential backoff and respect rate limits
+
+### CLI Issues
+
+**Problem:** Command not found
+**Solution:** Rebuild CLI with `npm run build`
+
+**Problem:** "Not connected" error
+**Solution:** Direct user to connect account at /profile
+
+**Problem:** Module import errors
+**Solution:** Check file paths and ensure proper ES module syntax
+
+---
+
+## Conclusion
+
+This guide provides a complete, battle-tested process for integrating any API into agentdev. Follow these steps and you'll have a production-ready integration in 2-4 weeks.
+
+**Key Takeaways:**
+1. ✅ Start with research and planning
+2. ✅ Use modular architecture
+3. ✅ Test thoroughly before deployment
+4. ✅ Document everything
+5. ✅ Monitor and iterate
+
+For questions or help with integration, refer to this guide or ask the team!