@hasna/connectors 0.3.16 → 0.4.1

package/connectors/connect-linear/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+connect-linear is a TypeScript CLI and library for Linear's GraphQL API. It provides issue management, project management, team operations, and user operations with multi-profile support for managing multiple Linear workspaces.
+
+## Build & Run Commands
+
+```bash
+bun install           # Install dependencies
+bun run dev           # Run CLI in development
+bun run build         # Build for distribution
+bun run typecheck     # Type check
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (type: module)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+
+## Project Structure
+
+```
+src/
+├── api/
+│   ├── client.ts     # GraphQL client with Bearer auth
+│   ├── issues.ts     # Issues API
+│   ├── projects.ts   # Projects API
+│   ├── teams.ts      # Teams API
+│   ├── users.ts      # Users API
+│   └── index.ts      # Main Linear 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
+```
+
+## API Architecture
+
+The Linear API uses GraphQL. The client architecture:
+
+1. `LinearClient` - Base GraphQL client that handles authentication and requests
+2. API modules (Issues, Projects, Teams, Users) - Use the client to make specific queries/mutations
+3. `Linear` class - Main entry point that combines all API modules
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LINEAR_API_KEY` | Linear API key |
+
+## Multi-Profile Configuration
+
+Configuration stored in `~/.connect/connect-linear/`:
+
+```
+~/.connect/connect-linear/
+├── current_profile
+└── profiles/
+    └── default/
+        └── config.json
+```
+
+## GraphQL Endpoint
+
+- Base URL: https://api.linear.app/graphql
+- Auth: Bearer token (API key sent directly as Authorization header)
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling
+
+## Priority Values
+
+- 0: No priority
+- 1: Urgent
+- 2: High
+- 3: Normal
+- 4: Low

package/connectors/connect-linear/README.md

@@ -0,0 +1,201 @@
+# @hasna/connect-linear
+
+Linear API connector with CLI and library support. Provides a TypeScript-first interface for interacting with the Linear GraphQL API.
+
+## Installation
+
+```bash
+npm install @hasna/connect-linear
+# or
+bun add @hasna/connect-linear
+```
+
+For CLI usage, install globally:
+
+```bash
+npm install -g @hasna/connect-linear
+```
+
+## Configuration
+
+### Environment Variable
+
+Set your Linear API key as an environment variable:
+
+```bash
+export LINEAR_API_KEY="lin_api_xxxxx"
+```
+
+### CLI Configuration
+
+Or use the CLI to save your API key:
+
+```bash
+connect-linear config set-api-key lin_api_xxxxx
+```
+
+Configuration is stored in `~/.connect/connect-linear/`.
+
+## CLI Usage
+
+### Authentication
+
+```bash
+# Test authentication
+connect-linear test
+
+# Show current user
+connect-linear whoami
+```
+
+### Issues
+
+```bash
+# List issues
+connect-linear issues list
+connect-linear issues list --team <team-id>
+connect-linear issues list --project <project-id>
+connect-linear issues list --assignee <user-id>
+
+# Get issue details
+connect-linear issues get <issue-id>
+
+# Create issue
+connect-linear issues create --title "Bug fix" --team <team-id>
+connect-linear issues create --title "Feature" --team <team-id> --description "Details here" --priority 2
+
+# Update issue
+connect-linear issues update <issue-id> --title "New title"
+connect-linear issues update <issue-id> --state <state-id>
+connect-linear issues update <issue-id> --assignee <user-id>
+
+# Archive issue
+connect-linear issues archive <issue-id>
+
+# Search issues
+connect-linear issues search "bug"
+```
+
+### Projects
+
+```bash
+# List projects
+connect-linear projects list
+
+# Get project details
+connect-linear projects get <project-id>
+```
+
+### Teams
+
+```bash
+# List teams
+connect-linear teams list
+
+# Get team details
+connect-linear teams get <team-id>
+
+# List workflow states for a team
+connect-linear teams states <team-id>
+```
+
+### Users
+
+```bash
+# List users
+connect-linear users list
+connect-linear users list --all  # Include inactive users
+
+# Get user details
+connect-linear users get <user-id>
+
+# Current user
+connect-linear users me
+```
+
+### Multi-Profile Support
+
+```bash
+# Create a profile
+connect-linear profile create work
+
+# Switch profiles
+connect-linear profile use work
+
+# List profiles
+connect-linear profile list
+
+# Use profile for a single command
+connect-linear --profile work issues list
+```
+
+### Output Formats
+
+```bash
+# JSON output
+connect-linear issues list --format json
+
+# Table output
+connect-linear issues list --format table
+
+# Pretty output (default)
+connect-linear issues list --format pretty
+```
+
+## Library Usage
+
+```typescript
+import { Linear } from '@hasna/connect-linear';
+
+const linear = new Linear({
+  apiKey: process.env.LINEAR_API_KEY!,
+});
+
+// List issues
+const issues = await linear.issues.list({ teamId: 'team-id' });
+
+// Create issue
+const issue = await linear.issues.create({
+  title: 'New feature',
+  teamId: 'team-id',
+  description: 'Feature description',
+  priority: 2,
+});
+
+// Update issue
+await linear.issues.update(issue.id, {
+  stateId: 'done-state-id',
+});
+
+// Get current user
+const me = await linear.users.me();
+
+// List teams
+const teams = await linear.teams.list();
+
+// Get workflow states
+const states = await linear.teams.getWorkflowStates('team-id');
+
+// Search issues
+const results = await linear.issues.search('bug');
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LINEAR_API_KEY` | Linear API key (required) |
+
+## Priority Values
+
+| Value | Label |
+|-------|-------|
+| 0 | No priority |
+| 1 | Urgent |
+| 2 | High |
+| 3 | Normal |
+| 4 | Low |
+
+## License
+
+Apache-2.0

package/connectors/connect-linear/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hasna/connect-linear",
+  "version": "0.0.1",
+  "description": "Linear API connector with CLI and library support",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "connect-linear": "bin/index.js"
+  },
+  "scripts": {
+    "dev": "bun run ./src/cli/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "linear",
+    "api",
+    "cli",
+    "connector",
+    "graphql"
+  ],
+  "author": "Hasna",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "restricted"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "CLAUDE.md"
+  ]
+}

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

@@ -0,0 +1,62 @@
+import type { LinearConfig, GraphQLResponse } from '../types';
+import { LinearApiError } from '../types';
+
+const DEFAULT_BASE_URL = 'https://api.linear.app/graphql';
+
+export class LinearClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: LinearConfig) {
+    if (!config.apiKey) {
+      throw new Error('Linear API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  /**
+   * Execute a GraphQL query
+   */
+  async query<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
+    const response = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': this.apiKey,
+      },
+      body: JSON.stringify({ query, variables }),
+    });
+
+    if (!response.ok) {
+      throw new LinearApiError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        'http_error',
+        response.status
+      );
+    }
+
+    const result = await response.json() as GraphQLResponse<T>;
+
+    if (result.errors && result.errors.length > 0) {
+      const error = result.errors[0];
+      throw new LinearApiError(
+        error.message,
+        error.extensions?.code as string || 'graphql_error'
+      );
+    }
+
+    if (!result.data) {
+      throw new LinearApiError('No data returned', 'no_data');
+    }
+
+    return result.data;
+  }
+
+  /**
+   * Execute a GraphQL mutation
+   */
+  async mutate<T>(mutation: string, variables?: Record<string, unknown>): Promise<T> {
+    return this.query<T>(mutation, variables);
+  }
+}

package/connectors/connect-linear/src/api/index.ts

@@ -0,0 +1,46 @@
+import type { LinearConfig } from '../types';
+import { LinearClient } from './client';
+import { IssuesApi } from './issues';
+import { ProjectsApi } from './projects';
+import { TeamsApi } from './teams';
+import { UsersApi } from './users';
+
+export { LinearClient } from './client';
+export { IssuesApi } from './issues';
+export { ProjectsApi } from './projects';
+export { TeamsApi } from './teams';
+export { UsersApi } from './users';
+
+/**
+ * Main Linear API class
+ */
+export class Linear {
+  private readonly client: LinearClient;
+
+  public readonly issues: IssuesApi;
+  public readonly projects: ProjectsApi;
+  public readonly teams: TeamsApi;
+  public readonly users: UsersApi;
+
+  constructor(config: LinearConfig) {
+    this.client = new LinearClient(config);
+    this.issues = new IssuesApi(this.client);
+    this.projects = new ProjectsApi(this.client);
+    this.teams = new TeamsApi(this.client);
+    this.users = new UsersApi(this.client);
+  }
+
+  /**
+   * Test authentication and return current user
+   */
+  async test() {
+    return this.users.me();
+  }
+
+  /**
+   * Get the GraphQL client for custom queries
+   */
+  getClient(): LinearClient {
+    return this.client;
+  }
+}

package/connectors/connect-linear/src/api/issues.ts

@@ -0,0 +1,247 @@
+import type { LinearClient } from './client';
+import type {
+  LinearIssue,
+  IssueListOptions,
+  CreateIssueInput,
+  UpdateIssueInput,
+  IssuesResponse,
+  IssueResponse,
+  CreateIssueResponse,
+  UpdateIssueResponse,
+  ArchiveIssueResponse,
+  IssueFilter,
+} from '../types';
+
+const ISSUE_FRAGMENT = `
+  fragment IssueFragment on Issue {
+    id
+    identifier
+    title
+    description
+    priority
+    priorityLabel
+    estimate
+    sortOrder
+    boardOrder
+    startedAt
+    completedAt
+    canceledAt
+    dueDate
+    createdAt
+    updatedAt
+    archivedAt
+    url
+    number
+    team {
+      id
+      name
+      key
+    }
+    state {
+      id
+      name
+      color
+      type
+    }
+    assignee {
+      id
+      name
+      displayName
+      email
+    }
+    creator {
+      id
+      name
+      displayName
+    }
+    labels {
+      nodes {
+        id
+        name
+        color
+      }
+    }
+    project {
+      id
+      name
+    }
+  }
+`;
+
+export class IssuesApi {
+  constructor(private readonly client: LinearClient) {}
+
+  /**
+   * List issues with optional filters
+   */
+  async list(options: IssueListOptions = {}): Promise<LinearIssue[]> {
+    const { first = 50, after, teamId, projectId, assigneeId, filter } = options;
+
+    // Build filter object
+    const filterObj: IssueFilter = filter || {};
+    if (teamId) {
+      filterObj.team = { id: { eq: teamId } };
+    }
+    if (projectId) {
+      filterObj.project = { id: { eq: projectId } };
+    }
+    if (assigneeId) {
+      filterObj.assignee = { id: { eq: assigneeId } };
+    }
+
+    const query = `
+      ${ISSUE_FRAGMENT}
+      query Issues($first: Int, $after: String, $filter: IssueFilter) {
+        issues(first: $first, after: $after, filter: $filter) {
+          nodes {
+            ...IssueFragment
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    `;
+
+    const result = await this.client.query<IssuesResponse>(query, {
+      first,
+      after,
+      filter: Object.keys(filterObj).length > 0 ? filterObj : undefined,
+    });
+
+    return result.issues.nodes;
+  }
+
+  /**
+   * Get a single issue by ID
+   */
+  async get(id: string): Promise<LinearIssue> {
+    const query = `
+      ${ISSUE_FRAGMENT}
+      query Issue($id: String!) {
+        issue(id: $id) {
+          ...IssueFragment
+        }
+      }
+    `;
+
+    const result = await this.client.query<IssueResponse>(query, { id });
+    return result.issue;
+  }
+
+  /**
+   * Create a new issue
+   */
+  async create(input: CreateIssueInput): Promise<LinearIssue> {
+    const mutation = `
+      ${ISSUE_FRAGMENT}
+      mutation CreateIssue($input: IssueCreateInput!) {
+        issueCreate(input: $input) {
+          success
+          issue {
+            ...IssueFragment
+          }
+        }
+      }
+    `;
+
+    const result = await this.client.mutate<CreateIssueResponse>(mutation, {
+      input,
+    });
+
+    if (!result.issueCreate.success || !result.issueCreate.issue) {
+      throw new Error('Failed to create issue');
+    }
+
+    return result.issueCreate.issue;
+  }
+
+  /**
+   * Update an existing issue
+   */
+  async update(id: string, input: UpdateIssueInput): Promise<LinearIssue> {
+    const mutation = `
+      ${ISSUE_FRAGMENT}
+      mutation UpdateIssue($id: String!, $input: IssueUpdateInput!) {
+        issueUpdate(id: $id, input: $input) {
+          success
+          issue {
+            ...IssueFragment
+          }
+        }
+      }
+    `;
+
+    const result = await this.client.mutate<UpdateIssueResponse>(mutation, {
+      id,
+      input,
+    });
+
+    if (!result.issueUpdate.success || !result.issueUpdate.issue) {
+      throw new Error('Failed to update issue');
+    }
+
+    return result.issueUpdate.issue;
+  }
+
+  /**
+   * Archive an issue (soft delete)
+   */
+  async archive(id: string): Promise<boolean> {
+    const mutation = `
+      mutation ArchiveIssue($id: String!) {
+        issueArchive(id: $id) {
+          success
+        }
+      }
+    `;
+
+    const result = await this.client.mutate<ArchiveIssueResponse>(mutation, { id });
+    return result.issueArchive.success;
+  }
+
+  /**
+   * Change issue state by state ID
+   */
+  async changeState(id: string, stateId: string): Promise<LinearIssue> {
+    return this.update(id, { stateId });
+  }
+
+  /**
+   * Assign issue to a user
+   */
+  async assign(id: string, assigneeId: string): Promise<LinearIssue> {
+    return this.update(id, { assigneeId });
+  }
+
+  /**
+   * Add issue to a project
+   */
+  async addToProject(id: string, projectId: string): Promise<LinearIssue> {
+    return this.update(id, { projectId });
+  }
+
+  /**
+   * Search issues by query text
+   */
+  async search(query: string, first = 20): Promise<LinearIssue[]> {
+    const gqlQuery = `
+      ${ISSUE_FRAGMENT}
+      query SearchIssues($query: String!, $first: Int) {
+        issueSearch(query: $query, first: $first) {
+          nodes {
+            ...IssueFragment
+          }
+        }
+      }
+    `;
+
+    const result = await this.client.query<{ issueSearch: { nodes: LinearIssue[] } }>(
+      gqlQuery,
+      { query, first }
+    );
+
+    return result.issueSearch.nodes;
+  }
+}