pdauth 1.0.1

package/PROXY-SPEC.md

@@ -0,0 +1,159 @@
+# pdauth proxy Command Specification
+
+## Overview
+
+Add a `proxy` command to pdauth that allows making authenticated HTTP requests to any Pipedream-connected API using the SDK's built-in proxy feature.
+
+## SDK Already Has Proxy
+
+The `@pipedream/sdk` has a `client.proxy` object with these methods:
+- `client.proxy.get(request)`
+- `client.proxy.post(request)`
+- `client.proxy.put(request)`
+- `client.proxy.delete(request)`
+- `client.proxy.patch(request)`
+
+Each takes:
+```typescript
+{
+  url: string;           // Target API URL (relative for dynamic domain apps)
+  externalUserId: string; // User ID
+  accountId: string;     // Account ID (e.g., "apn_1234567")
+  params?: Record<string, string>;  // Query params
+  headers?: Record<string, string>; // Custom headers
+  body?: Record<string, unknown>;   // Request body (POST/PUT/PATCH)
+}
+```
+
+## Command Interface
+
+```bash
+pdauth proxy <app> <path> [options]
+
+Arguments:
+  app   - App slug (e.g., zoho_mail, slack, notion)
+  path  - API path (e.g., /api/accounts, /api/accounts/123/folders)
+
+Options:
+  -X, --method <method>  HTTP method (GET|POST|PUT|DELETE|PATCH) [default: GET]
+  -u, --user <userId>    External user ID [default: from config]
+  -d, --data <json>      Request body as JSON string
+  -H, --header <header>  Custom header (can be repeated: -H "X-Foo: bar" -H "X-Baz: qux")
+  -q, --query <param>    Query parameter (can be repeated: -q "limit=10" -q "offset=0")
+  -j, --json             Output as JSON (default: pretty print)
+  -v, --verbose          Show request details
+```
+
+## Examples
+
+```bash
+# GET request
+pdauth proxy zoho_mail /api/accounts --user telegram:5439689035
+
+# GET with query params
+pdauth proxy zoho_mail /api/accounts/123/folders -q "limit=50" --user telegram:5439689035
+
+# POST with JSON body
+pdauth proxy zoho_mail /api/accounts/123/folders \
+  -X POST \
+  -d '{"folderName": "Projects"}' \
+  --user telegram:5439689035
+
+# PUT with headers
+pdauth proxy slack /api/chat.postMessage \
+  -X POST \
+  -d '{"channel": "C123", "text": "Hello"}' \
+  -H "Content-Type: application/json" \
+  --user telegram:5439689035
+```
+
+## Implementation Steps
+
+1. Create `src/commands/proxy.ts`:
+   - Import getClient from pipedream.ts
+   - Import listAccounts to find account ID for app + user
+   - Parse CLI arguments
+   - Call appropriate proxy method (get/post/put/delete/patch)
+   - Output response
+
+2. Add to `src/commands/index.ts`:
+   - Export registerProxyCommand
+
+3. Add to `src/cli.ts`:
+   - Register the proxy command
+
+## Code Structure
+
+```typescript
+// src/commands/proxy.ts
+import { Command } from 'commander';
+import { getClient, listAccounts } from '../pipedream.js';
+
+export function registerProxyCommand(program: Command): void {
+  program
+    .command('proxy <app> <path>')
+    .description('Make authenticated API request via Pipedream proxy')
+    .option('-X, --method <method>', 'HTTP method', 'GET')
+    .option('-u, --user <userId>', 'External user ID')
+    .option('-d, --data <json>', 'Request body JSON')
+    .option('-H, --header <header>', 'Custom header', collect, [])
+    .option('-q, --query <param>', 'Query parameter', collect, [])
+    .option('-j, --json', 'JSON output')
+    .option('-v, --verbose', 'Verbose output')
+    .action(async (app, path, options) => {
+      // 1. Get account ID for app + user
+      const accounts = await listAccounts(options.user);
+      const account = accounts.find(a => a.app.nameSlug === app);
+      if (!account) throw new Error(`No ${app} account connected for user`);
+      
+      // 2. Build request
+      const client = getClient();
+      const request = {
+        url: path,  // relative path for dynamic domain apps
+        externalUserId: options.user,
+        accountId: account.id,
+        params: parseParams(options.query),
+        headers: parseHeaders(options.header),
+        body: options.data ? JSON.parse(options.data) : undefined,
+      };
+      
+      // 3. Call proxy
+      const method = options.method.toLowerCase();
+      const response = await client.proxy[method](request);
+      
+      // 4. Output
+      console.log(options.json ? JSON.stringify(response) : response);
+    });
+}
+
+function collect(value: string, previous: string[]) {
+  return previous.concat([value]);
+}
+
+function parseParams(params: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const p of params) {
+    const [key, ...rest] = p.split('=');
+    result[key] = rest.join('=');
+  }
+  return result;
+}
+
+function parseHeaders(headers: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const h of headers) {
+    const [key, ...rest] = h.split(':');
+    result[key.trim()] = rest.join(':').trim();
+  }
+  return result;
+}
+```
+
+## Testing
+
+```bash
+# After implementation, test with:
+pdauth proxy zoho_mail /api/accounts --user telegram:5439689035 -v
+
+# Expected: List of Zoho Mail accounts
+```

package/README.md

@@ -0,0 +1,142 @@
+# 🔐 pdauth
+
+**Pipedream OAuth CLI** — Give AI agents access to 2500+ APIs via dynamic OAuth
+
+```
+Agent: "I need Spotify access to manage your playlist"
+  ↓
+$ pdauth connect spotify
+  ↓  
+🔗 https://pipedream.com/_static/connect.html?token=ctok_xxx&app=spotify
+  ↓
+User clicks → OAuth flow → Done
+  ↓
+Agent can now call Spotify tools via MCP
+```
+
+## Installation
+
+```bash
+npm install -g pdauth
+```
+
+## Quick Start
+
+### 1. Configure Pipedream credentials
+
+Get your credentials at https://pipedream.com/settings/api
+
+```bash
+pdauth config
+```
+
+Or set directly:
+```bash
+pdauth config --set clientId=YOUR_CLIENT_ID
+pdauth config --set clientSecret=YOUR_CLIENT_SECRET
+pdauth config --set projectId=YOUR_PROJECT_ID
+```
+
+### 2. Generate OAuth link for any app
+
+```bash
+# Generate link for Spotify
+pdauth connect spotify
+
+# Generate for a specific user
+pdauth connect google_sheets --user pedro@example.com
+
+# Copy to clipboard
+pdauth connect slack --copy
+```
+
+### 3. Check connection status
+
+```bash
+# Show connected accounts
+pdauth status
+
+# Show all users
+pdauth status --all
+
+# JSON output for scripts
+pdauth status --json
+```
+
+### 4. Use connected tools
+
+```bash
+# List available tools for an app
+pdauth tools slack
+
+# Call a tool
+pdauth call slack.send_message channel=general text="Hello from AI!"
+
+# Call with JSON args
+pdauth call notion.create_page --args '{"title": "New Page", "parent_id": "..."}'
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pdauth config` | Configure Pipedream credentials |
+| `pdauth apps [--search <query>]` | List available apps (2500+) |
+| `pdauth app <slug>` | Get info about an app |
+| `pdauth connect <app>` | Generate OAuth link |
+| `pdauth status` | List connected accounts |
+| `pdauth disconnect <app>` | Revoke app access |
+| `pdauth tools <app>` | List MCP tools for an app |
+| `pdauth call <app.tool>` | Invoke an MCP tool |
+
+## Options
+
+All commands support:
+- `-u, --user <id>` — Specify user ID (default: "default")
+- `-j, --json` — Output as JSON
+
+## How It Works
+
+1. **You run** `pdauth connect <app>` → generates a secure OAuth link
+2. **User clicks** the link → Pipedream handles OAuth flow
+3. **Credentials stored** securely in Pipedream (not locally)
+4. **Agent calls tools** via MCP using `pdauth call` or direct MCP
+
+Powered by [Pipedream Connect](https://pipedream.com/docs/connect) — managed OAuth for 2500+ APIs.
+
+## For AI Agents (OpenClaw)
+
+This CLI is designed for AI agents to request and use OAuth access dynamically:
+
+```
+User: "Add this song to my Spotify playlist"
+
+Agent: I need Spotify access. Here's a link to authorize:
+       https://pipedream.com/_static/connect.html?token=...
+
+User: *clicks, authorizes*
+
+Agent: *calls pdauth call spotify.add_to_playlist ...*
+       ✓ Added "Song Name" to your playlist!
+```
+
+## Environment Variables
+
+Instead of `pdauth config`, you can use environment variables:
+
+```bash
+export PIPEDREAM_CLIENT_ID=your_client_id
+export PIPEDREAM_CLIENT_SECRET=your_client_secret
+export PIPEDREAM_PROJECT_ID=your_project_id
+export PIPEDREAM_ENVIRONMENT=development  # or production
+```
+
+## Links
+
+- [Pipedream MCP](https://mcp.pipedream.com) — Browse all available apps
+- [Pipedream Connect Docs](https://pipedream.com/docs/connect)
+- [OpenClaw](https://openclaw.ai) — AI agent platform
+
+## License
+
+MIT © Versatly

package/bin/ga.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+
+/**
+ * ga - Google Analytics CLI powered by pdauth
+ * 
+ * Usage:
+ *   ga properties                    List all properties
+ *   ga report <property>             30-day overview
+ *   ga traffic <property>            Traffic sources breakdown
+ *   ga devices <property>            Device breakdown
+ *   ga pages <property>              Top pages
+ *   ga compare <property>            Compare periods
+ *   ga franchise                     All Hale franchises overview
+ */
+
+import { execSync } from 'child_process';
+
+const USER = 'telegram:5439689035';
+
+function pdauthCall(instruction) {
+  const args = JSON.stringify({ instruction });
+  const cmd = `pdauth call google_analytics.google_analytics-run-report-in-ga4 --user ${USER} --args '${args}' --json`;
+  
+  try {
+    const result = execSync(cmd, { encoding: 'utf-8', timeout: 120000 });
+    const parsed = JSON.parse(result);
+    return parsed?.content?.[0]?.text || 'No data';
+  } catch (e) {
+    return `Error: ${e.message}`;
+  }
+}
+
+function printHeader(title) {
+  console.log('\n' + '═'.repeat(60));
+  console.log(`  📊 ${title}`);
+  console.log('═'.repeat(60) + '\n');
+}
+
+import { writeFileSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const ALERTS_FILE = join(process.env.HOME, '.config/pdauth/ga-alerts.json');
+
+function loadAlerts() {
+  if (existsSync(ALERTS_FILE)) {
+    return JSON.parse(readFileSync(ALERTS_FILE, 'utf-8'));
+  }
+  return { alerts: [] };
+}
+
+function saveAlerts(data) {
+  writeFileSync(ALERTS_FILE, JSON.stringify(data, null, 2));
+}
+
+const commands = {
+  properties: () => {
+    printHeader('Google Analytics Properties');
+    const result = pdauthCall('List ALL available Google Analytics properties I have access to. Show property names and IDs in a clean list format.');
+    console.log(result);
+  },
+
+  report: (property) => {
+    if (!property) {
+      console.log('Usage: ga report <property-name-or-id>');
+      process.exit(1);
+    }
+    printHeader(`30-Day Report: ${property}`);
+    const result = pdauthCall(`For property "${property}", get a comprehensive 30-day report showing: total users, new users, sessions, page views, and average session duration. Format as a clean summary with numbers.`);
+    console.log(result);
+  },
+
+  traffic: (property) => {
+    if (!property) {
+      console.log('Usage: ga traffic <property-name-or-id>');
+      process.exit(1);
+    }
+    printHeader(`Traffic Sources: ${property}`);
+    const result = pdauthCall(`For property "${property}", get sessions breakdown by traffic source (sessionSource) for the last 30 days. Show top 15 sources with users, sessions, and pageviews. Format as a table.`);
+    console.log(result);
+  },
+
+  devices: (property) => {
+    if (!property) {
+      console.log('Usage: ga devices <property-name-or-id>');
+      process.exit(1);
+    }
+    printHeader(`Device Breakdown: ${property}`);
+    const result = pdauthCall(`For property "${property}", get sessions breakdown by device category (desktop, mobile, tablet) for the last 30 days. Show users, sessions, and percentage for each.`);
+    console.log(result);
+  },
+
+  pages: (property) => {
+    if (!property) {
+      console.log('Usage: ga pages <property-name-or-id>');
+      process.exit(1);
+    }
+    printHeader(`Top Pages: ${property}`);
+    const result = pdauthCall(`For property "${property}", get the top 20 pages by pageviews for the last 30 days. Show page path, pageviews, and users.`);
+    console.log(result);
+  },
+
+  countries: (property) => {
+    if (!property) {
+      console.log('Usage: ga countries <property-name-or-id>');
+      process.exit(1);
+    }
+    printHeader(`Countries: ${property}`);
+    const result = pdauthCall(`For property "${property}", get sessions breakdown by country for the last 30 days. Show top 15 countries with users and sessions.`);
+    console.log(result);
+  },
+
+  compare: (property) => {
+    if (!property) {
+      console.log('Usage: ga compare <property-name-or-id>');
+      process.exit(1);
+    }
+    printHeader(`Period Comparison: ${property}`);
+    const result = pdauthCall(`For property "${property}", compare the last 30 days vs the previous 30 days. Show users, sessions, and pageviews for both periods with percentage change.`);
+    console.log(result);
+  },
+
+  franchise: () => {
+    printHeader('Hale Pet Door Franchise Overview');
+    console.log('Fetching data for all franchises (this may take a moment)...\n');
+    
+    const franchises = [
+      { name: 'Hale Pet Door (Main)', id: '494080031' },
+      { name: 'HPD Orlando', id: '494128845' },
+      { name: 'Denver', id: '398496582' },
+      { name: 'Atlanta', id: '393738911' },
+      { name: 'San Antonio', id: '392790632' },
+      { name: 'Twin Cities', id: '392331022' },
+      { name: 'Boise', id: '393448653' },
+    ];
+
+    const result = pdauthCall(`Get a quick summary for these GA4 properties showing total users and sessions for the last 30 days: ${franchises.map(f => `${f.name} (ID: ${f.id})`).join(', ')}. Format as a comparison table.`);
+    console.log(result);
+  },
+
+  export: (property) => {
+    if (!property) {
+      console.log('Usage: ga export <property-name-or-id> [filename]');
+      process.exit(1);
+    }
+    const filename = `ga-export-${Date.now()}.csv`;
+    printHeader(`Exporting: ${property}`);
+    
+    const result = pdauthCall(`For property "${property}", get the last 30 days data with: date, users, sessions, pageviews, bounceRate. Format the output as CSV with headers. One row per day.`);
+    
+    // Try to extract CSV-like content
+    console.log('Raw data:\n');
+    console.log(result);
+    
+    // Save to file
+    const filepath = join(process.cwd(), filename);
+    writeFileSync(filepath, result);
+    console.log(`\n✅ Saved to: ${filepath}`);
+  },
+
+  'export-all': () => {
+    printHeader('Exporting All Properties');
+    const timestamp = new Date().toISOString().split('T')[0];
+    const filename = `ga-franchise-export-${timestamp}.csv`;
+    
+    const result = pdauthCall(`For ALL Hale Pet Door properties I have access to, get total users and sessions for the last 30 days. Format as CSV with columns: property_name, property_id, users, sessions. Include all 22 properties.`);
+    
+    console.log(result);
+    
+    const filepath = join(process.cwd(), filename);
+    writeFileSync(filepath, result);
+    console.log(`\n✅ Saved to: ${filepath}`);
+  },
+
+  'alert-add': (args) => {
+    const parts = args.split(' ');
+    if (parts.length < 3) {
+      console.log('Usage: ga alert-add <property> <metric> <threshold>');
+      console.log('Example: ga alert-add 494080031 users-drop 20%');
+      console.log('Example: ga alert-add "Hale Pet Door" sessions-below 100');
+      process.exit(1);
+    }
+    
+    const threshold = parts.pop();
+    const metric = parts.pop();
+    const property = parts.join(' ');
+    
+    const data = loadAlerts();
+    const alert = {
+      id: Date.now(),
+      property,
+      metric,
+      threshold,
+      created: new Date().toISOString(),
+      enabled: true
+    };
+    data.alerts.push(alert);
+    saveAlerts(data);
+    
+    printHeader('Alert Created');
+    console.log(`  Property: ${property}`);
+    console.log(`  Metric: ${metric}`);
+    console.log(`  Threshold: ${threshold}`);
+    console.log(`  ID: ${alert.id}`);
+    console.log('\n✅ Alert saved! Run "ga alert-check" to test.');
+  },
+
+  'alert-list': () => {
+    printHeader('Configured Alerts');
+    const data = loadAlerts();
+    
+    if (data.alerts.length === 0) {
+      console.log('No alerts configured.');
+      console.log('Run: ga alert-add <property> <metric> <threshold>');
+      return;
+    }
+    
+    data.alerts.forEach((alert, i) => {
+      const status = alert.enabled ? '✅' : '❌';
+      console.log(`${i + 1}. ${status} ${alert.property}`);
+      console.log(`   Metric: ${alert.metric} | Threshold: ${alert.threshold}`);
+      console.log(`   ID: ${alert.id}`);
+      console.log('');
+    });
+  },
+
+  'alert-check': () => {
+    printHeader('Checking Alerts');
+    const data = loadAlerts();
+    
+    if (data.alerts.length === 0) {
+      console.log('No alerts to check.');
+      return;
+    }
+    
+    data.alerts.filter(a => a.enabled).forEach(alert => {
+      console.log(`\n🔍 Checking: ${alert.property} (${alert.metric} ${alert.threshold})`);
+      
+      const result = pdauthCall(`For property "${alert.property}", check if ${alert.metric} has crossed threshold ${alert.threshold} in the last 7 days compared to previous 7 days. Give a brief YES/NO answer with the actual numbers.`);
+      
+      console.log(result);
+    });
+  },
+
+  'alert-remove': (id) => {
+    if (!id) {
+      console.log('Usage: ga alert-remove <alert-id>');
+      process.exit(1);
+    }
+    
+    const data = loadAlerts();
+    const before = data.alerts.length;
+    data.alerts = data.alerts.filter(a => String(a.id) !== String(id));
+    
+    if (data.alerts.length === before) {
+      console.log(`Alert ${id} not found.`);
+      process.exit(1);
+    }
+    
+    saveAlerts(data);
+    console.log(`✅ Alert ${id} removed.`);
+  },
+
+  realtime: (property) => {
+    if (!property) {
+      console.log('Usage: ga realtime <property>');
+      process.exit(1);
+    }
+    printHeader(`Realtime: ${property}`);
+    console.log('⚠️  Note: GA4 realtime requires special API access.');
+    const result = pdauthCall(`For property "${property}", get the most recent data available - today's users and sessions if possible, otherwise the last 24 hours.`);
+    console.log(result);
+  },
+
+  help: () => {
+    console.log(`
+📊 ga - Google Analytics CLI
+
+USAGE:
+  ga <command> [property]
+
+COMMANDS:
+  properties          List all available properties
+  report <prop>       30-day overview (users, sessions, pageviews)
+  traffic <prop>      Traffic sources breakdown
+  devices <prop>      Desktop vs Mobile vs Tablet
+  pages <prop>        Top pages by views
+  countries <prop>    Geographic breakdown
+  compare <prop>      This month vs last month
+  franchise           Hale Pet Door network overview
+  realtime <prop>     Today/last 24h snapshot
+
+EXPORT:
+  export <prop>       Export 30 days to CSV
+  export-all          Export all franchises to CSV
+
+ALERTS:
+  alert-add <prop> <metric> <threshold>   Add alert
+  alert-list                               List all alerts
+  alert-check                              Check all alerts now
+  alert-remove <id>                        Remove an alert
+
+EXAMPLES:
+  ga properties
+  ga report "Hale Pet Door"
+  ga traffic 494080031
+  ga franchise
+  ga export "HPD-Orlando"
+  ga alert-add "Hale Pet Door" users-drop 20%
+  ga alert-check
+
+PROPERTY:
+  Can be name ("Hale Pet Door") or ID (494080031)
+`);
+  }
+};
+
+// Parse args
+const [,, command, ...rest] = process.argv;
+const property = rest.join(' ');
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  commands.help();
+} else if (commands[command]) {
+  commands[command](property);
+} else {
+  console.log(`Unknown command: ${command}`);
+  console.log('Run "ga help" for usage');
+  process.exit(1);
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}