@hasna/connectors 0.4.0 → 0.4.2

package/connectors/connect-zendesk/.github/workflows/deploy.yml

@@ -0,0 +1,51 @@
+name: Deploy to EC2
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run tests
+        run: bun test
+
+      - name: Build
+        run: bun run build
+
+      - name: Deploy to EC2
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: ${{ secrets.EC2_HOST }}
+          username: ec2-user
+          key: ${{ secrets.EC2_SSH_KEY }}
+          script: |
+            cd /home/ec2-user/connectors/connect-zendesk
+            git pull origin main
+            ~/.bun/bin/bun install
+            ~/.bun/bin/bun run build
+            sudo systemctl restart connect-zendesk
+            echo "Deployment complete"
+
+      - name: Verify deployment
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: ${{ secrets.EC2_HOST }}
+          username: ec2-user
+          key: ${{ secrets.EC2_SSH_KEY }}
+          script: |
+            curl -sf http://localhost:21010/zendesk/health && echo "Health check passed"

package/connectors/connect-zendesk/CLAUDE.md

@@ -0,0 +1,78 @@
+---
+description: Use Bun instead of Node.js, npm, pnpm, or vite.
+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
+alwaysApply: false
+---
+
+Default to using Bun instead of Node.js.
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads .env, so don't use dotenv.
+
+## Project Structure
+
+This is a **connector** project for Zendesk that follows the Beep Media connector pattern:
+
+```
+connect-zendesk/
+├── src/
+│   ├── api/           # API client modules
+│   │   ├── client.ts  # Base HTTP client
+│   │   ├── index.ts   # Main connector class
+│   │   └── *.ts       # Resource-specific APIs
+│   ├── cli/           # CLI commands
+│   │   └── index.ts   # Commander-based CLI
+│   ├── types/         # TypeScript types
+│   │   └── index.ts   # All type definitions
+│   ├── utils/         # Utilities
+│   │   ├── config.ts  # CLI configuration storage
+│   │   └── output.ts  # Output formatting
+│   └── index.ts       # SDK entry point
+├── package.json
+└── tsconfig.json
+```
+
+## Infrastructure
+
+- **CLI Name**: `connect-zendesk`
+- **EC2 Instance**: `hasna-prod-connect-zendesk`
+- **RDS Database**: `hasna-prod-connect-zendesk`
+- **S3 Bucket**: `hasna-prod-connect-zendesk`
+- **Remote API**: `https://connect.hasna.com/zendesk`
+
+## Key Patterns
+
+1. **API Client**: All API calls go through `ZendeskClient` which handles auth and request formatting
+2. **Resource APIs**: Each resource type gets its own API class (e.g., `UsersApi`, `OrdersApi`)
+3. **CLI Commands**: Commander-based with subcommands for each resource
+4. **Configuration**: Stored in `~/.connect-zendesk/config.json`
+5. **Environment Variables**: `ZENDESK_API_KEY` for API authentication
+
+## APIs
+
+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
+- `Bun.redis` for Redis. Don't use `ioredis`.
+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
+- `WebSocket` is built-in. Don't use `ws`.
+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
+- Bun.$`ls` instead of execa.
+
+## Testing
+
+Use `bun test` to run tests.
+
+```ts#index.test.ts
+import { test, expect } from "bun:test";
+
+test("hello world", () => {
+  expect(1).toBe(1);
+});
+```
+
+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.

package/connectors/connect-zendesk/Makefile

@@ -0,0 +1,129 @@
+# Makefile for connect-zendesk
+#
+# Common commands:
+#   make install     - Install dependencies
+#   make dev         - Run CLI in development mode
+#   make server      - Run server in development mode
+#   make build       - Build for production
+#   make deploy      - Deploy to EC2 instance
+#   make typecheck   - Run TypeScript type checking
+#   make clean       - Remove build artifacts
+
+.PHONY: install dev server server-prod build typecheck test clean help link unlink deploy deploy-ec2 deploy-sync logs ssh npm-publish
+
+# Configuration
+EC2_HOST ?= hasna-prod-connect-zendesk
+EC2_USER ?= ec2-user
+DEPLOY_PATH ?= /home/ec2-user/connectors/connect-zendesk
+SERVICE_NAME ?= connect-zendesk
+PORT ?= 21010
+
+# Default target
+help:
+	@echo "Available commands:"
+	@echo "  make install       - Install dependencies"
+	@echo "  make dev           - Run CLI in development mode"
+	@echo "  make server        - Run server in development mode"
+	@echo "  make server-prod   - Run server in production mode"
+	@echo "  make build         - Build for production"
+	@echo "  make test          - Run tests"
+	@echo "  make typecheck     - Run TypeScript type checking"
+	@echo "  make clean         - Remove build artifacts"
+	@echo "  make link          - Link CLI globally for development"
+	@echo "  make unlink        - Unlink CLI"
+	@echo ""
+	@echo "Deployment:"
+	@echo "  make deploy        - Deploy to EC2 instance (build + sync + restart)"
+	@echo "  make deploy-sync   - Sync files to EC2 (without restart)"
+	@echo "  make logs          - View server logs on EC2"
+	@echo "  make ssh           - SSH into EC2 instance"
+	@echo ""
+	@echo "Publishing:"
+	@echo "  make npm-publish   - Publish to npm"
+
+install:
+	bun install
+
+dev:
+	bun run dev
+
+server:
+	PORT=$(PORT) bun run server
+
+server-prod:
+	PORT=$(PORT) NODE_ENV=production bun run server
+
+build:
+	bun run build
+
+test:
+	bun test
+
+typecheck:
+	bun run typecheck
+
+clean:
+	rm -rf dist bin server node_modules/.cache
+
+link:
+	bun link
+
+unlink:
+	bun unlink @hasna/connect-zendesk
+
+# Deployment targets
+deploy-sync:
+	@echo "Syncing to $(EC2_HOST):$(DEPLOY_PATH)..."
+	rsync -avz --delete \
+		--exclude='.git' \
+		--exclude='node_modules' \
+		--exclude='.env.local' \
+		. $(EC2_USER)@$(EC2_HOST):$(DEPLOY_PATH)/
+
+deploy-ec2: deploy-sync
+	@echo "Installing dependencies on EC2..."
+	ssh $(EC2_USER)@$(EC2_HOST) "cd $(DEPLOY_PATH) && bun install --production"
+	@echo "Building on EC2..."
+	ssh $(EC2_USER)@$(EC2_HOST) "cd $(DEPLOY_PATH) && bun run build"
+	@echo "Restarting service..."
+	ssh $(EC2_USER)@$(EC2_HOST) "sudo systemctl restart $(SERVICE_NAME) || sudo systemctl start $(SERVICE_NAME)"
+	@echo "Checking service status..."
+	ssh $(EC2_USER)@$(EC2_HOST) "sudo systemctl status $(SERVICE_NAME) --no-pager"
+
+deploy: build deploy-ec2
+	@echo "✅ Deployment complete"
+	@echo "Server running at https://connect.hasna.com/zendesk"
+
+logs:
+	ssh $(EC2_USER)@$(EC2_HOST) "sudo journalctl -u $(SERVICE_NAME) -f"
+
+ssh:
+	ssh $(EC2_USER)@$(EC2_HOST)
+
+# NPM publishing
+npm-publish: build test
+	@echo "Publishing to npm..."
+	npm publish --access public
+	@echo "✅ Published to npm"
+
+# Create systemd service file
+systemd-service:
+	@echo "[Unit]" > connect-zendesk.service
+	@echo "Description=connect-zendesk API Server" >> connect-zendesk.service
+	@echo "After=network.target" >> connect-zendesk.service
+	@echo "" >> connect-zendesk.service
+	@echo "[Service]" >> connect-zendesk.service
+	@echo "Type=simple" >> connect-zendesk.service
+	@echo "User=ec2-user" >> connect-zendesk.service
+	@echo "WorkingDirectory=$(DEPLOY_PATH)" >> connect-zendesk.service
+	@echo "ExecStart=/home/ec2-user/.bun/bin/bun run $(DEPLOY_PATH)/server/index.js" >> connect-zendesk.service
+	@echo "Restart=always" >> connect-zendesk.service
+	@echo "RestartSec=10" >> connect-zendesk.service
+	@echo "Environment=NODE_ENV=production" >> connect-zendesk.service
+	@echo "Environment=PORT=$(PORT)" >> connect-zendesk.service
+	@echo "" >> connect-zendesk.service
+	@echo "[Install]" >> connect-zendesk.service
+	@echo "WantedBy=multi-user.target" >> connect-zendesk.service
+	@echo "Created connect-zendesk.service"
+	@echo "Copy to EC2: scp connect-zendesk.service $(EC2_USER)@$(EC2_HOST):/tmp/"
+	@echo "Then run: sudo mv /tmp/connect-zendesk.service /etc/systemd/system/ && sudo systemctl daemon-reload && sudo systemctl enable connect-zendesk"

package/connectors/connect-zendesk/README.md

@@ -0,0 +1,295 @@
+# connect-zendesk
+
+A TypeScript CLI and SDK for the Zendesk API. Built with Bun.
+
+This connector provides programmatic access to Zendesk's Support API, including tickets, users, organizations, and groups.
+
+## Infrastructure
+
+| Resource | Name |
+|----------|------|
+| EC2 Instance | `hasna-prod-connect-zendesk` |
+| RDS Database | `hasna-prod-connect-zendesk` |
+| S3 Bucket | `hasna-prod-connect-zendesk` |
+| Remote API | `https://connect.hasna.com/zendesk` |
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+# Install globally
+npm install -g @hasna/connect-zendesk
+# or
+bun add -g @hasna/connect-zendesk
+```
+
+### From source
+
+```bash
+# Clone and install globally
+git clone https://github.com/hasna/connect-zendesk.git
+cd connect-zendesk
+bun install -g .
+
+# Or link for development
+bun link
+```
+
+### As a Dependency
+
+```bash
+bun add @hasna/connect-zendesk
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Configure authentication
+connect-zendesk config set-email your-email@company.com
+connect-zendesk config set-token YOUR_API_TOKEN
+connect-zendesk config set-base-url https://your-subdomain.zendesk.com/api/v2
+
+# Or use environment variables
+export ZENDESK_EMAIL=your-email@company.com
+export ZENDESK_API_TOKEN=YOUR_API_TOKEN
+export ZENDESK_BASE_URL=https://your-subdomain.zendesk.com/api/v2
+
+# List tickets
+connect-zendesk tickets list
+
+# Get a specific ticket
+connect-zendesk tickets get 12345
+
+# Create a ticket
+connect-zendesk tickets create -s "Issue Subject" -b "Issue description"
+
+# List users
+connect-zendesk users list
+
+# Get current user
+connect-zendesk users me
+```
+
+### SDK Usage
+
+```typescript
+import { Zendesk } from 'connect-zendesk';
+
+// Initialize with credentials
+const client = new Zendesk({
+  email: 'your-email@company.com',
+  apiToken: 'YOUR_API_TOKEN',
+  baseUrl: 'https://your-subdomain.zendesk.com/api/v2'
+});
+
+// Or use environment variables
+const client = Zendesk.fromEnv();
+
+// Work with tickets
+const tickets = await client.tickets.list();
+const ticket = await client.tickets.get(12345);
+const newTicket = await client.tickets.create({
+  ticket: {
+    subject: 'Help needed',
+    comment: { body: 'Description of the issue' }
+  }
+});
+
+// Work with users
+const users = await client.users.list();
+const currentUser = await client.users.me();
+
+// Work with organizations
+const orgs = await client.organizations.list();
+const org = await client.organizations.get(123);
+
+// Work with groups
+const groups = await client.groups.list();
+```
+
+## CLI Commands
+
+### Configuration
+
+```bash
+connect-zendesk config set-email <email>       # Set Zendesk email
+connect-zendesk config set-token <token>       # Set API token
+connect-zendesk config set-base-url <url>      # Set base URL
+connect-zendesk config set-account <name>      # Set default account
+connect-zendesk config show                    # Show configuration
+connect-zendesk config clear                   # Clear configuration
+```
+
+### Tickets
+
+```bash
+connect-zendesk tickets list                   # List all tickets
+connect-zendesk tickets list -p 2 -l 50        # List with pagination
+connect-zendesk tickets get <id>               # Get ticket by ID
+connect-zendesk tickets create -s "Subject" -b "Body"  # Create ticket
+connect-zendesk tickets update <id> -s "New Subject"   # Update ticket
+connect-zendesk tickets delete <id>            # Delete ticket
+```
+
+### Users
+
+```bash
+connect-zendesk users list                     # List all users
+connect-zendesk users list -r agent            # List users by role
+connect-zendesk users get <id>                 # Get user by ID
+connect-zendesk users me                       # Get current user
+connect-zendesk users create -n "Name" -e "email@example.com"  # Create user
+connect-zendesk users search -q "email@example.com"  # Search users
+```
+
+### Organizations
+
+```bash
+connect-zendesk organizations list             # List all organizations
+connect-zendesk orgs get <id>                  # Get organization by ID
+connect-zendesk orgs create -n "Company Name"  # Create organization
+connect-zendesk orgs search -q "Company"       # Search organizations
+```
+
+### Groups
+
+```bash
+connect-zendesk groups list                    # List all groups
+connect-zendesk groups get <id>                # Get group by ID
+```
+
+### Remote API
+
+```bash
+connect-zendesk remote status                  # Check remote API status
+connect-zendesk remote health                  # Check remote API health
+```
+
+## Output Formats
+
+Use the `-f` or `--format` flag to change output format:
+
+```bash
+connect-zendesk remote status -f json      # JSON output
+connect-zendesk remote status -f table     # Table output
+connect-zendesk remote status -f pretty    # Pretty output (default)
+```
+
+## API Reference
+
+### Zendesk Class
+
+```typescript
+import { Zendesk } from 'connect-zendesk';
+
+const client = new Zendesk({
+  email: 'your-email@company.com',
+  apiToken: 'YOUR_API_TOKEN',
+  baseUrl: 'https://your-subdomain.zendesk.com/api/v2'
+});
+
+// Available APIs
+client.tickets          // Tickets API
+client.users            // Users API
+client.organizations    // Organizations API
+client.groups           // Groups API
+```
+
+### Authentication
+
+Zendesk uses Basic Authentication with the following format:
+- Email: Your Zendesk account email
+- API Token: Generated in Zendesk Admin Center > Apps and integrations > APIs > Zendesk API > Settings
+- Base64 encode: `{email}/token:{api_token}`
+
+The connector handles this authentication automatically.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ZENDESK_EMAIL` | Your Zendesk email address |
+| `ZENDESK_API_TOKEN` | Your Zendesk API token |
+| `ZENDESK_BASE_URL` | Your Zendesk base URL (e.g., https://your-subdomain.zendesk.com/api/v2) |
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development mode
+bun run dev
+
+# Build for production
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## API Modules
+
+This connector implements the following Zendesk API modules:
+
+### Tickets API (`client.tickets`)
+- `list(params?)` - List all tickets
+- `get(ticketId)` - Get a ticket by ID
+- `create(data)` - Create a new ticket
+- `update(ticketId, data)` - Update a ticket
+- `delete(ticketId)` - Delete a ticket
+- `listByUser(userId, params?)` - List tickets for a user
+- `listByOrganization(orgId, params?)` - List tickets for an organization
+- `search(query, params?)` - Search tickets
+
+### Users API (`client.users`)
+- `list(params?)` - List all users
+- `get(userId)` - Get a user by ID
+- `create(data)` - Create a new user
+- `update(userId, data)` - Update a user
+- `delete(userId)` - Delete a user
+- `me()` - Get current authenticated user
+- `searchByEmail(email)` - Search users by email
+- `searchByName(name)` - Search users by name
+- `listByOrganization(orgId, params?)` - List users in an organization
+
+### Organizations API (`client.organizations`)
+- `list(params?)` - List all organizations
+- `get(orgId)` - Get an organization by ID
+- `create(data)` - Create a new organization
+- `update(orgId, data)` - Update an organization
+- `delete(orgId)` - Delete an organization
+- `search(name)` - Search organizations by name
+- `getByExternalId(externalId)` - Get organization by external ID
+
+### Groups API (`client.groups`)
+- `list(params?)` - List all groups
+- `get(groupId)` - Get a group by ID
+- `listAssignable(params?)` - List assignable groups
+- `listByUser(userId, params?)` - List groups for a user
+
+## Deployment
+
+This connector is deployed to:
+
+- **EC2**: `hasna-prod-connect-zendesk`
+- **Database**: `hasna-prod-connect-zendesk`
+- **S3**: `hasna-prod-connect-zendesk`
+
+The remote API is accessible at `https://connect.hasna.com/zendesk`
+
+## License
+
+MIT
+
+## Resources
+
+- [Zendesk API Documentation](https://developer.zendesk.com/api-reference/)
+- [Zendesk API Authentication](https://developer.zendesk.com/api-reference/introduction/security-and-auth/)
+- [Zendesk Tickets API](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/)
+- [Zendesk Users API](https://developer.zendesk.com/api-reference/ticketing/users/users/)
+- [Zendesk Organizations API](https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/)
+- [Zendesk Groups API](https://developer.zendesk.com/api-reference/ticketing/groups/groups/)