@hasna/connectors 0.0.1

package/connectors/connect-figma/CLAUDE.md

@@ -0,0 +1,185 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+connect-figma is a TypeScript connector for the Figma REST API with multi-profile configuration support. It provides both a CLI and a programmatic API for managing Files, Comments, Teams, Projects, Components, Styles, Webhooks, Variables, and Dev Resources.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`type: module`)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/           # API client modules
+│   ├── client.ts  # HTTP client with authentication
+│   └── index.ts   # Main connector class
+├── cli/
+│   └── index.ts   # CLI commands
+├── types/
+│   └── index.ts   # TypeScript types
+├── utils/
+│   ├── config.ts  # Multi-profile configuration
+│   └── output.ts  # CLI output formatting
+└── index.ts       # Library exports
+```
+
+## Authentication
+
+API Key authentication. Credentials can be set via:
+- Environment variable (see below)
+- Profile configuration: `connect-figma config set-key <key>`
+
+
+## Key Patterns
+
+### Multi-Profile Configuration
+
+Profiles stored in `~/.connect/connect-figma/profiles/`:
+- Each profile is a separate JSON file
+- `current_profile` file tracks active profile
+- `--profile` flag overrides for single command
+- Environment variables override profile config
+
+### Authentication
+
+Uses Figma Personal Access Tokens. Credentials can be set via:
+- Environment variables: `FIGMA_ACCESS_TOKEN` or `FIGMA_TOKEN`
+- Profile configuration: `connect-figma config set-token <token>`
+
+### Service APIs
+
+Each Figma resource has its own API module:
+- **FilesApi**: Get file, get nodes, get images, get image fills, get versions, get meta
+- **CommentsApi**: List, post, delete comments, add/remove reactions
+- **TeamsApi**: Get team projects
+- **ProjectsApi**: Get team projects, get project files
+- **UsersApi**: Get current user
+- **ComponentsApi**: Get team/file components, component sets, get component by key
+- **StylesApi**: Get team/file styles, get style by key
+- **WebhooksApi**: List, create, update, delete webhooks
+- **VariablesApi**: Get local/published variables, create/update/delete variables
+- **DevResourcesApi**: Get, create, update, delete dev resources
+
+## CLI Commands
+
+### Files
+```bash
+connect-figma files get <fileKey>                    # Get file info
+connect-figma files nodes <fileKey> --ids <nodeIds>  # Get specific nodes
+connect-figma files images <fileKey> --ids <ids>     # Export images
+connect-figma files versions <fileKey>               # Get version history
+connect-figma files meta <fileKey>                   # Get file metadata
+```
+
+### Comments
+```bash
+connect-figma comments list <fileKey>                # List comments
+connect-figma comments post <fileKey> <message>      # Post comment
+connect-figma comments delete <fileKey> <commentId>  # Delete comment
+```
+
+### Teams
+```bash
+connect-figma teams projects <teamId>                # List team projects
+```
+
+### Projects
+```bash
+connect-figma projects list <teamId>                 # List team projects
+connect-figma projects files <projectId>             # List project files
+```
+
+### Components
+```bash
+connect-figma components team <teamId>               # List team components
+connect-figma components file <fileKey>              # List file components
+connect-figma components sets <teamId>               # List team component sets
+```
+
+### Styles
+```bash
+connect-figma styles team <teamId>                   # List team styles
+connect-figma styles file <fileKey>                  # List file styles
+```
+
+### Webhooks
+```bash
+connect-figma webhooks list <teamId>                 # List team webhooks
+connect-figma webhooks create <teamId> -e FILE_UPDATE -u <url> --passcode <pass>
+connect-figma webhooks update <webhookId> -s PAUSED
+connect-figma webhooks delete <webhookId>
+```
+
+### Variables
+```bash
+connect-figma variables local <fileKey>              # Get local variables
+connect-figma variables published <fileKey>          # Get published variables
+connect-figma variables collections <fileKey>        # Get variable collections
+```
+
+### Dev Resources
+```bash
+connect-figma dev-resources list <fileKey>           # List dev resources
+connect-figma dev-resources create <fileKey> -n <name> -u <url> --node-id <id>
+connect-figma dev-resources delete <fileKey> <resourceId>
+```
+
+### User
+```bash
+connect-figma user me                                # Get current user
+```
+
+### Profile & Config
+```bash
+connect-figma profile list                           # List profiles
+connect-figma profile use <name>                     # Switch profile
+connect-figma profile create <name>                  # Create profile
+connect-figma config set-token <token>               # Set access token
+connect-figma config show                            # Show configuration
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FIGMA_ACCESS_TOKEN` | Personal access token (primary) |
+| `FIGMA_TOKEN` | Personal access token (alias) |
+
+## Data Storage
+
+```
+~/.connect/connect-figma/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-figma/GEMINI.md

@@ -0,0 +1,185 @@
+# GEMINI.md
+
+This file provides guidance to Gemini when working with this repository.
+
+## Project Overview
+
+connect-figma is a TypeScript connector for the Figma REST API with multi-profile configuration support. It provides both a CLI and a programmatic API for managing Files, Comments, Teams, Projects, Components, Styles, Webhooks, Variables, and Dev Resources.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`type: module`)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/           # API client modules
+│   ├── client.ts  # HTTP client with authentication
+│   └── index.ts   # Main connector class
+├── cli/
+│   └── index.ts   # CLI commands
+├── types/
+│   └── index.ts   # TypeScript types
+├── utils/
+│   ├── config.ts  # Multi-profile configuration
+│   └── output.ts  # CLI output formatting
+└── index.ts       # Library exports
+```
+
+## Authentication
+
+API Key authentication. Credentials can be set via:
+- Environment variable (see below)
+- Profile configuration: `connect-figma config set-key <key>`
+
+
+## Key Patterns
+
+### Multi-Profile Configuration
+
+Profiles stored in `~/.connect/connect-figma/profiles/`:
+- Each profile is a separate JSON file
+- `current_profile` file tracks active profile
+- `--profile` flag overrides for single command
+- Environment variables override profile config
+
+### Authentication
+
+Uses Figma Personal Access Tokens. Credentials can be set via:
+- Environment variables: `FIGMA_ACCESS_TOKEN` or `FIGMA_TOKEN`
+- Profile configuration: `connect-figma config set-token <token>`
+
+### Service APIs
+
+Each Figma resource has its own API module:
+- **FilesApi**: Get file, get nodes, get images, get image fills, get versions, get meta
+- **CommentsApi**: List, post, delete comments, add/remove reactions
+- **TeamsApi**: Get team projects
+- **ProjectsApi**: Get team projects, get project files
+- **UsersApi**: Get current user
+- **ComponentsApi**: Get team/file components, component sets, get component by key
+- **StylesApi**: Get team/file styles, get style by key
+- **WebhooksApi**: List, create, update, delete webhooks
+- **VariablesApi**: Get local/published variables, create/update/delete variables
+- **DevResourcesApi**: Get, create, update, delete dev resources
+
+## CLI Commands
+
+### Files
+```bash
+connect-figma files get <fileKey>                    # Get file info
+connect-figma files nodes <fileKey> --ids <nodeIds>  # Get specific nodes
+connect-figma files images <fileKey> --ids <ids>     # Export images
+connect-figma files versions <fileKey>               # Get version history
+connect-figma files meta <fileKey>                   # Get file metadata
+```
+
+### Comments
+```bash
+connect-figma comments list <fileKey>                # List comments
+connect-figma comments post <fileKey> <message>      # Post comment
+connect-figma comments delete <fileKey> <commentId>  # Delete comment
+```
+
+### Teams
+```bash
+connect-figma teams projects <teamId>                # List team projects
+```
+
+### Projects
+```bash
+connect-figma projects list <teamId>                 # List team projects
+connect-figma projects files <projectId>             # List project files
+```
+
+### Components
+```bash
+connect-figma components team <teamId>               # List team components
+connect-figma components file <fileKey>              # List file components
+connect-figma components sets <teamId>               # List team component sets
+```
+
+### Styles
+```bash
+connect-figma styles team <teamId>                   # List team styles
+connect-figma styles file <fileKey>                  # List file styles
+```
+
+### Webhooks
+```bash
+connect-figma webhooks list <teamId>                 # List team webhooks
+connect-figma webhooks create <teamId> -e FILE_UPDATE -u <url> --passcode <pass>
+connect-figma webhooks update <webhookId> -s PAUSED
+connect-figma webhooks delete <webhookId>
+```
+
+### Variables
+```bash
+connect-figma variables local <fileKey>              # Get local variables
+connect-figma variables published <fileKey>          # Get published variables
+connect-figma variables collections <fileKey>        # Get variable collections
+```
+
+### Dev Resources
+```bash
+connect-figma dev-resources list <fileKey>           # List dev resources
+connect-figma dev-resources create <fileKey> -n <name> -u <url> --node-id <id>
+connect-figma dev-resources delete <fileKey> <resourceId>
+```
+
+### User
+```bash
+connect-figma user me                                # Get current user
+```
+
+### Profile & Config
+```bash
+connect-figma profile list                           # List profiles
+connect-figma profile use <name>                     # Switch profile
+connect-figma profile create <name>                  # Create profile
+connect-figma config set-token <token>               # Set access token
+connect-figma config show                            # Show configuration
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FIGMA_ACCESS_TOKEN` | Personal access token (primary) |
+| `FIGMA_TOKEN` | Personal access token (alias) |
+
+## Data Storage
+
+```
+~/.connect/connect-figma/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-figma/README.md

@@ -0,0 +1,164 @@
+# connect-figma
+
+Figma connector CLI - Files, Comments, Projects, Components with multi-profile support
+
+## Installation
+
+```bash
+bun install -g @hasna/connect-figma
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+connect-figma config set-key YOUR_API_KEY
+
+# Or use environment variable
+export FIGMA_ACCESS_TOKEN=YOUR_API_KEY
+```
+
+## CLI Commands
+
+### Files
+```bash
+connect-figma files get <fileKey>                    # Get file info
+connect-figma files nodes <fileKey> --ids <nodeIds>  # Get specific nodes
+connect-figma files images <fileKey> --ids <ids>     # Export images
+connect-figma files versions <fileKey>               # Get version history
+connect-figma files meta <fileKey>                   # Get file metadata
+```
+
+### Comments
+```bash
+connect-figma comments list <fileKey>                # List comments
+connect-figma comments post <fileKey> <message>      # Post comment
+connect-figma comments delete <fileKey> <commentId>  # Delete comment
+```
+
+### Teams
+```bash
+connect-figma teams projects <teamId>                # List team projects
+```
+
+### Projects
+```bash
+connect-figma projects list <teamId>                 # List team projects
+connect-figma projects files <projectId>             # List project files
+```
+
+### Components
+```bash
+connect-figma components team <teamId>               # List team components
+connect-figma components file <fileKey>              # List file components
+connect-figma components sets <teamId>               # List team component sets
+```
+
+### Styles
+```bash
+connect-figma styles team <teamId>                   # List team styles
+connect-figma styles file <fileKey>                  # List file styles
+```
+
+### Webhooks
+```bash
+connect-figma webhooks list <teamId>                 # List team webhooks
+connect-figma webhooks create <teamId> -e FILE_UPDATE -u <url> --passcode <pass>
+connect-figma webhooks update <webhookId> -s PAUSED
+connect-figma webhooks delete <webhookId>
+```
+
+### Variables
+```bash
+connect-figma variables local <fileKey>              # Get local variables
+connect-figma variables published <fileKey>          # Get published variables
+connect-figma variables collections <fileKey>        # Get variable collections
+```
+
+### Dev Resources
+```bash
+connect-figma dev-resources list <fileKey>           # List dev resources
+connect-figma dev-resources create <fileKey> -n <name> -u <url> --node-id <id>
+connect-figma dev-resources delete <fileKey> <resourceId>
+```
+
+### User
+```bash
+connect-figma user me                                # Get current user
+```
+
+### Profile & Config
+```bash
+connect-figma profile list                           # List profiles
+connect-figma profile use <name>                     # Switch profile
+connect-figma profile create <name>                  # Create profile
+connect-figma config set-token <token>               # Set access token
+connect-figma config show                            # Show configuration
+```
+
+## Profile Management
+
+```bash
+# Create profiles for different accounts
+connect-figma profile create work --api-key xxx --use
+connect-figma profile create personal --api-key yyy
+
+# Switch profiles
+connect-figma profile use work
+
+# Use profile for single command
+connect-figma -p personal <command>
+
+# List profiles
+connect-figma profile list
+```
+
+## Library Usage
+
+```typescript
+import { Figma } from '@hasna/connect-figma';
+
+const client = new Figma({ apiKey: 'YOUR_API_KEY' });
+
+// Use the client
+// See CLAUDE.md for detailed API documentation
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FIGMA_ACCESS_TOKEN` | Personal access token (primary) |
+| `FIGMA_TOKEN` | Personal access token (alias) |
+
+## Data Storage
+
+Configuration stored in `~/.connect/connect-figma/`:
+
+```
+~/.connect/connect-figma/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## License
+
+MIT

package/connectors/connect-figma/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hasna/connect-figma",
+  "version": "0.0.2",
+  "description": "Figma connector CLI - Files, Comments, Projects, Components with multi-profile support",
+  "type": "module",
+  "bin": {
+    "connect-figma": "./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",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "figma",
+    "design",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/opensource-connectors.git"
+  }
+}

package/connectors/connect-figma/src/api/client.ts

@@ -0,0 +1,111 @@
+import type { FigmaConfig } from '../types';
+import { FigmaApiError } from '../types';
+
+const FIGMA_API_BASE = 'https://api.figma.com/v1';
+
+export interface FigmaRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Figma API Client
+ */
+export class FigmaClient {
+  private readonly accessToken: string;
+
+  constructor(config: FigmaConfig) {
+    if (!config.accessToken) {
+      throw new Error('Figma Access Token is required');
+    }
+    this.accessToken = config.accessToken;
+  }
+
+  /**
+   * Make a request to the Figma API
+   */
+  async request<T>(
+    path: string,
+    options: FigmaRequestOptions = {}
+  ): Promise<T> {
+    const { method = 'GET', params, body, headers = {} } = options;
+
+    const url = new URL(`${FIGMA_API_BASE}${path}`);
+
+    // Add query params
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    const requestHeaders: Record<string, string> = {
+      'X-Figma-Token': this.accessToken,
+      ...headers,
+    };
+
+    if (body) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const response = await fetch(url.toString(), {
+      method,
+      headers: requestHeaders,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    // Handle response
+    let data: unknown;
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      let errorMessage = `Figma API Error: ${response.status} ${response.statusText}`;
+      let errorCode: string | undefined;
+
+      if (typeof data === 'object' && data !== null) {
+        const errData = data as Record<string, unknown>;
+        errorCode = errData.err as string;
+        if (errData.message) {
+          errorMessage = errData.message as string;
+        } else if (errData.err) {
+          errorMessage = errData.err as string;
+        }
+      }
+
+      throw new FigmaApiError(errorMessage, response.status, errorCode);
+    }
+
+    return data as T;
+  }
+
+  /**
+   * Get a preview of the access token (for display/debugging)
+   */
+  getAccessTokenPreview(): string {
+    if (this.accessToken.length > 8) {
+      return `${this.accessToken.substring(0, 8)}...`;
+    }
+    return '***';
+  }
+}