api-connector

What this skill does

# API Connector

**⚡ UNIQUE FEATURE**: Natural language API integration for 100+ popular services. Automatically handles authentication (OAuth, API keys), builds requests, parses responses, and generates integration code. No API docs reading required!

## What This Skill Does

Connect to any API using plain English:

- **100+ Pre-configured APIs**: GitHub, Slack, Stripe, Twilio, SendGrid, OpenAI, and more
- **Natural language requests**: "Send a Slack message to #general" → API call
- **Auto authentication**: Handles OAuth, API keys, JWT automatically
- **Response parsing**: Extracts relevant data from complex responses
- **Code generation**: Generates integration code in your language
- **Webhook setup**: Creates and manages webhooks
- **Rate limiting**: Automatically handles rate limits and retries
- **Testing mode**: Test API calls before using in production

## Supported Services

### Communication
- **Slack**: Messages, channels, users, files
- **Discord**: Servers, channels, messages, roles
- **Twilio**: SMS, voice calls, WhatsApp
- **SendGrid**: Email campaigns, templates
- **Telegram**: Bots, messages, groups

### Development
- **GitHub**: Repos, issues, PRs, actions, releases
- **GitLab**: Projects, merge requests, CI/CD
- **Bitbucket**: Repositories, pipelines
- **Linear**: Issues, projects, teams
- **Jira**: Issues, boards, sprints

### Payments
- **Stripe**: Payments, customers, subscriptions
- **PayPal**: Transactions, invoices
- **Square**: Payments, inventory

### Cloud & Infrastructure
- **AWS**: S3, Lambda, EC2, RDS
- **Google Cloud**: Storage, Compute, Functions
- **Azure**: VMs, Storage, Functions
- **Vercel**: Deployments, projects
- **Netlify**: Sites, builds, functions

### Data & Analytics
- **Google Analytics**: Reports, events, conversions
- **Mixpanel**: Events, funnels, cohorts
- **Segment**: Events, identify, track

### AI & ML
- **OpenAI**: GPT, DALL-E, Embeddings
- **Anthropic Claude**: Messages, conversations
- **Hugging Face**: Models, inference
- **Replicate**: Model predictions

### CRM & Sales
- **Salesforce**: Leads, opportunities, accounts
- **HubSpot**: Contacts, deals, companies
- **Intercom**: Users, conversations, messages

### Productivity
- **Notion**: Pages, databases, blocks
- **Airtable**: Bases, records, tables
- **Google Workspace**: Drive, Sheets, Calendar, Gmail
- **Microsoft 365**: OneDrive, Excel, Outlook

### Social Media
- **Twitter/X**: Tweets, timelines, users
- **LinkedIn**: Posts, profiles, connections
- **Instagram**: Posts, stories, insights
- **YouTube**: Videos, playlists, analytics

## Instructions

### Phase 1: Service Discovery

1. **Identify API**:
   ```
   Ask user:
   - Which service to connect to?
   - What action to perform?
   - Authentication details (if not configured)
   ```

2. **Check Configuration**:
   ```bash
   # Load API configs from .api-connector-config.yml
   Use Read to check if API is already configured
   ```

3. **Setup Authentication** (if needed):

   **For API Key auth**:
   ```
   Ask user for API key
   Securely store in config (or use environment variable)
   ```

   **For OAuth**:
   ```bash
   1. Generate OAuth URL
   2. User authorizes in browser
   3. Receive callback with code
   4. Exchange for access token
   5. Store tokens securely
   ```

   **For JWT**:
   ```
   Request credentials
   Generate JWT token
   Store for subsequent requests
   ```

### Phase 2: Natural Language to API Call

When user makes a request:

1. **Parse Intent**:
   ```
   "Send a Slack message to #general saying Hello"

   Parsed:
   - Service: Slack
   - Action: Send message
   - Channel: #general
   - Content: "Hello"
   ```

2. **Build API Request**:

   **Example 1: Slack Message**
   ```bash
   curl -X POST https://slack.com/api/chat.postMessage \
     -H "Authorization: Bearer ${SLACK_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "channel": "#general",
       "text": "Hello"
     }'
   ```

   **Example 2: GitHub Create Issue**
   ```bash
   curl -X POST https://api.github.com/repos/owner/repo/issues \
     -H "Authorization: token ${GITHUB_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Bug: App crashes on startup",
       "body": "Description...",
       "labels": ["bug"]
     }'
   ```

   **Example 3: Stripe Create Payment**
   ```bash
   curl -X POST https://api.stripe.com/v1/payment_intents \
     -u "${STRIPE_SECRET_KEY}:" \
     -d amount=2000 \
     -d currency=usd \
     -d "payment_method_types[]"=card
   ```

3. **Execute Request**:
   ```bash
   Use Bash to make curl request
   Or use WebFetch for simple GET requests
   ```

### Phase 3: Response Handling

1. **Parse Response**:
   ```json
   // Raw GitHub API response
   {
     "id": 123456,
     "number": 42,
     "title": "Bug: App crashes",
     "html_url": "https://github.com/owner/repo/issues/42",
     "state": "open",
     "created_at": "2025-01-13T10:30:00Z",
     ...100 more fields
   }
   ```

2. **Extract Relevant Data**:
   ```
   ✅ Issue created successfully!

   Issue #42: Bug: App crashes
   URL: https://github.com/owner/repo/issues/42
   Status: Open
   ```

3. **Handle Errors**:
   ```
   ❌ API Error: Rate limit exceeded

   Details:
   - Limit: 5000 requests/hour
   - Remaining: 0
   - Resets at: 2025-01-13 11:00:00 UTC

   Suggestion: Retry in 15 minutes or use a different token
   ```

### Phase 4: Code Generation

Offer to generate integration code:

**Python**:
```python
import requests

def send_slack_message(channel: str, text: str) -> dict:
    """Send a message to a Slack channel."""
    url = "https://slack.com/api/chat.postMessage"
    headers = {
        "Authorization": f"Bearer {os.environ['SLACK_TOKEN']}",
        "Content-Type": "application/json"
    }
    data = {
        "channel": channel,
        "text": text
    }

    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

# Usage
result = send_slack_message("#general", "Hello from Python!")
print(f"Message sent: {result['ts']}")
```

**JavaScript**:
```javascript
async function sendSlackMessage(channel, text) {
  const response = await fetch('https://slack.com/api/chat.postMessage', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SLACK_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ channel, text })
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

// Usage
const result = await sendSlackMessage('#general', 'Hello from JavaScript!');
console.log(`Message sent: ${result.ts}`);
```

## Examples

### Example 1: GitHub Automation

**User**: "Create a GitHub issue in my-repo about fixing the login bug"

**Workflow**:
1. Parse: repo=my-repo, action=create issue, title=about login bug
2. Build request with GitHub API
3. Execute: POST /repos/owner/my-repo/issues
4. Show result: "Issue #42 created: https://github.com/..."
5. Offer code generation

**Result**:
```
✅ GitHub issue created!

Issue #42: Fix login bug
Repository: owner/my-repo
URL: https://github.com/owner/my-repo/issues/42

Would you like me to:
1. Generate Python/JS code for this
2. Set up a webhook to track this issue
3. Create a similar issue in another repo
```

### Example 2: Multi-Service Workflow

**User**: "When a new Stripe payment succeeds, send a thank you email via SendGrid and log it to Airtable"

**Workflow**:
1. Setup Stripe webhook
2. Generate webhook handler code:
   ```python
   @app.route('/webhook/stripe', methods=['POST'])
   def stripe_webhook():
       event = stripe.Webhook.construct_event(
           request.data, request.headers['STRIPE_SIGNATURE'],
           webhook_secret
       )

       if event['type'] == 'payment_intent.succeeded':
           payment = event['data']['object']
           email = payment['receipt_email']

           # Send thank you email