@hasna/connectors 0.4.0 → 0.4.2

package/connectors/connect-zendesk/SCAFFOLD.md

@@ -0,0 +1,178 @@
+# Scaffold: connect
+
+This is a scaffold template for creating Beep Media API connectors.
+
+## Placeholders
+
+The following placeholders are used throughout this scaffold:
+
+| Placeholder | Description | Example |
+|-------------|-------------|---------|
+| `zendesk` | Lowercase connector name | `notion`, `gmail`, `github` |
+| `Zendesk` | Human-readable service name | `Notion`, `Gmail`, `GitHub` |
+| `ZENDESK` | Uppercase with underscores (for env vars) | `NOTION`, `GMAIL`, `GITHUB` |
+| `Zendesk` | PascalCase (for class names) | `Notion`, `Gmail`, `GitHub` |
+
+## Creating a New Connector
+
+### Option 1: Using the init script
+
+```bash
+# Copy the scaffold to a new directory
+cp -r scaffold-connect connect-notion
+cd connect-notion
+
+# Run the init script
+./scripts/init.sh notion "Notion"
+```
+
+### Option 2: Manual replacement
+
+1. Copy the scaffold directory
+2. Replace all placeholders in all files
+3. Update the API base URL in `src/api/client.ts`
+4. Add your API modules
+
+## Infrastructure Naming Convention
+
+Each connector follows this naming pattern:
+
+| Resource | Pattern | Example (for Notion) |
+|----------|---------|----------------------|
+| CLI | `connect-{name}` | `connect-notion` |
+| EC2 Instance | `hasna-prod-connect-{name}` | `hasna-prod-connect-notion` |
+| RDS Database | `hasna-prod-connect-{name}` | `hasna-prod-connect-notion` |
+| S3 Bucket | `hasna-prod-connect-{name}` | `hasna-prod-connect-notion` |
+| Remote API | `https://connect.hasna.com/{name}` | `https://connect.hasna.com/notion` |
+
+## Project Structure
+
+```
+connect-{name}/
+├── src/
+│   ├── api/
+│   │   ├── client.ts      # Base HTTP client with auth
+│   │   ├── index.ts       # Main connector class
+│   │   └── example.ts     # Example API module (rename/customize)
+│   ├── cli/
+│   │   └── index.ts       # CLI commands
+│   ├── types/
+│   │   └── index.ts       # TypeScript types
+│   ├── utils/
+│   │   ├── config.ts      # CLI config storage
+│   │   └── output.ts      # Output formatting
+│   └── index.ts           # SDK entry point
+├── scripts/
+│   └── init.sh            # Initialization script
+├── package.json
+├── tsconfig.json
+├── Makefile
+├── README.md
+├── CLAUDE.md
+├── SCAFFOLD.md            # This file (delete after init)
+├── .env.example
+└── .gitignore
+```
+
+## Adding API Modules
+
+1. **Create the API module** in `src/api/{resource}.ts`:
+
+```typescript
+import { ZendeskClient } from './client';
+
+export class ResourceApi {
+  constructor(private readonly client: ZendeskClient) {}
+
+  async get(id: string): Promise<Resource> {
+    return this.client.get(`/resources/${id}`);
+  }
+
+  async list(): Promise<{ data: Resource[]; hasMore: boolean }> {
+    const response = await this.client.get<{ data: Resource[]; _hasMore?: boolean }>('/resources');
+    return { data: response.data || [], hasMore: !!response._hasMore };
+  }
+}
+```
+
+2. **Add types** in `src/types/index.ts`:
+
+```typescript
+export interface Resource {
+  id: string;
+  name: string;
+  // ...
+}
+```
+
+3. **Register the module** in `src/api/index.ts`:
+
+```typescript
+import { ResourceApi } from './resource';
+
+export class Zendesk {
+  public readonly resource: ResourceApi;
+
+  constructor(config: ZendeskConfig) {
+    this.client = new ZendeskClient(config);
+    this.resource = new ResourceApi(this.client);
+  }
+}
+```
+
+4. **Add CLI commands** in `src/cli/index.ts`:
+
+```typescript
+const resourceCmd = program.command('resources').description('Manage resources');
+
+resourceCmd
+  .command('get <id>')
+  .description('Get resource by ID')
+  .action(async (id: string) => {
+    const client = getClient();
+    const resource = await client.resource.get(id);
+    print(resource, getFormat(resourceCmd));
+  });
+```
+
+## Authentication
+
+Update `src/api/client.ts` to match your service's authentication method:
+
+```typescript
+// Bearer token (most common)
+'Authorization': `Bearer ${this.apiKey}`
+
+// API key header
+'X-API-Key': this.apiKey
+
+// Basic auth
+'Authorization': `Basic ${btoa(`${this.apiKey}:`)}`
+
+// Custom header
+'Api-Key': this.apiKey
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run in development
+bun run dev
+
+# Build for production
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Deployment
+
+The connector is deployed to AWS infrastructure:
+
+1. Build the project: `make build`
+2. Deploy to EC2: `make deploy-ec2`
+3. Configure the remote API at `https://connect.hasna.com/{name}`

package/connectors/connect-zendesk/nginx-connector.conf

@@ -0,0 +1,218 @@
+user nginx;
+worker_processes auto;
+error_log /var/log/nginx/error.log;
+pid /run/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log /var/log/nginx/access.log main;
+
+    sendfile on;
+    tcp_nopush on;
+    tcp_nodelay on;
+    keepalive_timeout 65;
+    types_hash_max_size 4096;
+    types_hash_bucket_size 128;
+
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    upstream gmail_backend {
+        server 127.0.0.1:3001;
+    }
+
+    upstream googlecontacts_backend {
+        server 127.0.0.1:3002;
+    }
+
+    upstream googledrive_backend {
+        server 127.0.0.1:3003;
+    }
+
+    upstream linear_backend {
+        server 127.0.0.1:3004;
+    }
+
+    upstream notion_backend {
+        server 127.0.0.1:3005;
+    }
+
+    upstream clickbank_backend {
+        server 127.0.0.1:3013;
+    }
+
+    upstream zendesk_backend {
+        server 127.0.0.1:21010;
+    }
+
+    server {
+        listen 80;
+        server_name connect.hasna.com;
+
+        location / {
+            root /usr/share/nginx/html;
+            index index.html;
+        }
+
+        location /gmail/ {
+            proxy_pass http://127.0.0.1:3001/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix /gmail/;
+        }
+
+        location /googlecontacts/ {
+            proxy_pass http://127.0.0.1:3002/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix /googlecontacts/;
+        }
+
+        location /googledrive/ {
+            proxy_pass http://127.0.0.1:3003/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix /googledrive/;
+        }
+
+        location /linear/ {
+            proxy_pass http://127.0.0.1:3004/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix /linear/;
+        }
+
+        location /notion/ {
+            proxy_pass http://127.0.0.1:3005/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix /notion/;
+        }
+
+        location /clickbank/ {
+            proxy_pass http://127.0.0.1:3013/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix /clickbank/;
+        }
+
+        location /zendesk/ {
+            proxy_pass http://127.0.0.1:21010/zendesk/;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix /zendesk/;
+        }
+    }
+
+    server {
+        listen 80;
+        server_name gmail.connect.hasna.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:3001;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+    server {
+        listen 80;
+        server_name googlecontacts.connect.hasna.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:3002;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+    server {
+        listen 80;
+        server_name googledrive.connect.hasna.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:3003;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+    server {
+        listen 80;
+        server_name linear.connect.hasna.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:3004;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+    server {
+        listen 80;
+        server_name notion.connect.hasna.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:3005;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+    server {
+        listen 80;
+        server_name clickbank.connect.hasna.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:3013;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+
+    server {
+        listen 80;
+        server_name zendesk.connect.hasna.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:21010;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+}

package/connectors/connect-zendesk/nginx.conf

@@ -0,0 +1,61 @@
+# nginx configuration for connect-zendesk
+# Location: /etc/nginx/sites-available/connect-zendesk
+#
+# To enable:
+#   sudo ln -s /etc/nginx/sites-available/connect-zendesk /etc/nginx/sites-enabled/
+#   sudo nginx -t
+#   sudo systemctl reload nginx
+
+# Upstream server
+upstream connect_zendesk {
+    server 127.0.0.1:21010;
+    keepalive 32;
+}
+
+# Main server block for connect.hasna.com/zendesk
+# Add this location block to the existing connect.hasna.com server
+#
+# If you have a separate server block for connect.hasna.com, add:
+#
+#   location /zendesk {
+#       proxy_pass http://connect_zendesk;
+#       proxy_http_version 1.1;
+#       proxy_set_header Upgrade $http_upgrade;
+#       proxy_set_header Connection 'upgrade';
+#       proxy_set_header Host $host;
+#       proxy_set_header X-Real-IP $remote_addr;
+#       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+#       proxy_set_header X-Forwarded-Proto $scheme;
+#       proxy_cache_bypass $http_upgrade;
+#       proxy_read_timeout 86400;
+#   }
+
+# Standalone server configuration (use if connect.hasna.com doesn't exist)
+# Uncomment and modify as needed:
+#
+# server {
+#     listen 80;
+#     server_name connect.hasna.com;
+#     return 301 https://$host$request_uri;
+# }
+#
+# server {
+#     listen 443 ssl http2;
+#     server_name connect.hasna.com;
+#
+#     ssl_certificate /etc/letsencrypt/live/connect.hasna.com/fullchain.pem;
+#     ssl_certificate_key /etc/letsencrypt/live/connect.hasna.com/privkey.pem;
+#
+#     location /zendesk {
+#         proxy_pass http://connect_zendesk;
+#         proxy_http_version 1.1;
+#         proxy_set_header Upgrade $http_upgrade;
+#         proxy_set_header Connection 'upgrade';
+#         proxy_set_header Host $host;
+#         proxy_set_header X-Real-IP $remote_addr;
+#         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+#         proxy_set_header X-Forwarded-Proto $scheme;
+#         proxy_cache_bypass $http_upgrade;
+#         proxy_read_timeout 86400;
+#     }
+# }

package/connectors/connect-zendesk/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@hasna/connect-zendesk",
+  "version": "0.2.0",
+  "description": "Zendesk API connector CLI - A TypeScript wrapper for the Zendesk API",
+  "type": "module",
+  "bin": {
+    "connect-zendesk": "bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun && bun build ./src/server/index.ts --outdir ./server --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "server": "bun run ./src/server/index.ts",
+    "server:prod": "NODE_ENV=production bun run ./src/server/index.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "release": "bun run ./scripts/publish.ts",
+    "release:patch": "bun run ./scripts/publish.ts patch",
+    "release:minor": "bun run ./scripts/publish.ts minor",
+    "release:major": "bun run ./scripts/publish.ts major",
+    "release:dry": "bun run ./scripts/publish.ts --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/connect-zendesk.git"
+  },
+  "homepage": "https://github.com/hasna/connect-zendesk#readme",
+  "bugs": {
+    "url": "https://github.com/hasna/connect-zendesk/issues"
+  },
+  "keywords": [
+    "zendesk",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "support",
+    "helpdesk",
+    "tickets"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/connectors/connect-zendesk/scripts/init.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Initialize a new connector from the scaffold-connect template
+#
+# Usage: ./scripts/init.sh <connector-name> [service-display-name]
+#
+# Examples:
+#   ./scripts/init.sh notion "Notion"
+#   ./scripts/init.sh gmail "Gmail"
+#   ./scripts/init.sh github "GitHub"
+#
+# This will replace all placeholders:
+#   {{CONNECTOR_NAME}}      -> connector-name (lowercase)
+#   {{SERVICE_NAME}}        -> Service Display Name
+#   {{SERVICE_NAME_UPPER}}  -> SERVICE_NAME (uppercase with underscores)
+#   {{SERVICE_NAME_PASCAL}} -> ServiceName (PascalCase)
+
+set -e
+
+if [ -z "$1" ]; then
+    echo "Usage: $0 <connector-name> [service-display-name]"
+    echo ""
+    echo "Examples:"
+    echo "  $0 notion 'Notion'"
+    echo "  $0 gmail 'Gmail'"
+    echo "  $0 github 'GitHub'"
+    exit 1
+fi
+
+CONNECTOR_NAME="$1"
+SERVICE_NAME="${2:-$CONNECTOR_NAME}"
+
+# Convert to different cases
+SERVICE_NAME_UPPER=$(echo "$SERVICE_NAME" | tr '[:lower:]' '[:upper:]' | tr ' ' '_' | tr '-' '_')
+SERVICE_NAME_PASCAL=$(echo "$SERVICE_NAME" | sed 's/[- ]//g')
+
+echo "Initializing connector: connect-$CONNECTOR_NAME"
+echo "Service name: $SERVICE_NAME"
+echo "Environment variable prefix: ${SERVICE_NAME_UPPER}_"
+echo "Class name: $SERVICE_NAME_PASCAL"
+echo ""
+
+# Find all files and replace placeholders
+find . -type f \( -name "*.ts" -o -name "*.json" -o -name "*.md" -o -name ".env*" -o -name ".gitignore" \) ! -path "./node_modules/*" ! -path "./scripts/*" | while read -r file; do
+    if grep -q "{{CONNECTOR_NAME}}\|{{SERVICE_NAME}}\|{{SERVICE_NAME_UPPER}}\|{{SERVICE_NAME_PASCAL}}" "$file" 2>/dev/null; then
+        echo "Processing: $file"
+        sed -i '' \
+            -e "s/{{CONNECTOR_NAME}}/$CONNECTOR_NAME/g" \
+            -e "s/{{SERVICE_NAME_PASCAL}}/$SERVICE_NAME_PASCAL/g" \
+            -e "s/{{SERVICE_NAME_UPPER}}/$SERVICE_NAME_UPPER/g" \
+            -e "s/{{SERVICE_NAME}}/$SERVICE_NAME/g" \
+            "$file"
+    fi
+done
+
+echo ""
+echo "Done! Next steps:"
+echo "  1. cd connect-$CONNECTOR_NAME"
+echo "  2. bun install"
+echo "  3. Update src/api/client.ts with the correct API base URL"
+echo "  4. Add API modules in src/api/"
+echo "  5. Add CLI commands in src/cli/index.ts"
+echo "  6. bun run dev to test"