@felixgeelhaar/jira-sdk 0.2.0 → 1.0.0

package/README.md

@@ -1,17 +1,21 @@
-# @felixgeelhaar/jira-sdk
+# Jira SDK TypeScript
 
-Type-safe TypeScript SDK for the Atlassian Jira REST API with Zod validation and built-in resilience.
+[![security](https://raw.githubusercontent.com/felixgeelhaar/jirasdk-ts/main/.github/badges/security.svg)](https://github.com/felixgeelhaar/jirasdk-ts)
+
+A type-safe, production-ready SDK for the Jira REST API with built-in resilience patterns.
 
 ## Features
 
-- **Type-Safe**: Full TypeScript support with strict mode
+- **Type-Safe**: Full TypeScript support with strict mode enabled
 - **Runtime Validation**: Zod schemas for request/response validation
-- **Resilience Built-In**: Circuit breaker, retry, rate limiting
-- **Multiple Auth Methods**: API Token, PAT, Basic Auth, OAuth 2.0
-- **Middleware Architecture**: Extensible request/response pipeline
+- **Resilience Built-In**: Circuit breaker, retry with exponential backoff, rate limiting
+- **Multiple Auth Methods**: API Token, Personal Access Token, Basic Auth, OAuth 2.0
+- **Middleware Architecture**: Extensible request/response processing pipeline
 - **Tree-Shakeable**: ESM and CJS builds with proper exports
 
-## Installation
+## Quick Start
+
+### Installation
 
 ```bash
 npm install @felixgeelhaar/jira-sdk
@@ -21,7 +25,7 @@ pnpm add @felixgeelhaar/jira-sdk
 yarn add @felixgeelhaar/jira-sdk
 ```
 
-## Quick Start
+### Basic Usage
 
 ```typescript
 import { createJiraClient, createApiTokenAuth } from '@felixgeelhaar/jira-sdk';
@@ -29,7 +33,7 @@ import { createJiraClient, createApiTokenAuth } from '@felixgeelhaar/jira-sdk';
 // Create auth provider
 const auth = createApiTokenAuth({
   email: 'your-email@example.com',
-  apiToken: 'your-api-token', // From https://id.atlassian.com/manage-profile/security/api-tokens
+  apiToken: 'your-api-token',
 });
 
 // Create client
@@ -47,262 +51,235 @@ const results = await client.search.jql('project = PROJ AND status = Open');
 for (const issue of results.issues) {
   console.log(issue.key, issue.fields.summary);
 }
-```
 
-## Authentication
+// Create an issue
+const newIssue = await client.issues.create({
+  fields: {
+    project: { key: 'PROJ' },
+    summary: 'New issue from SDK',
+    issuetype: { name: 'Task' },
+  },
+});
+```
 
-### API Token (Atlassian Cloud)
+### From environment variables
 
-Recommended for Atlassian Cloud instances:
+The SDK reads the same variables as the Go SDK, so both can share a deployment's
+configuration:
 
 ```typescript
-import { createApiTokenAuth } from '@felixgeelhaar/jira-sdk';
+import { createJiraClientFromEnv } from '@felixgeelhaar/jira-sdk';
 
-const auth = createApiTokenAuth({
-  email: 'your-email@example.com',
-  apiToken: 'your-api-token',
-});
+// JIRA_BASE_URL=https://your-domain.atlassian.net
+// JIRA_EMAIL=you@example.com
+// JIRA_API_TOKEN=...
+const client = createJiraClientFromEnv();
 ```
 
-Get your API token from [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens).
-
-### Personal Access Token (Server/Data Center)
+Credentials resolve in this order: `JIRA_EMAIL` + `JIRA_API_TOKEN`, then
+`JIRA_PAT`, then `JIRA_USERNAME` + `JIRA_PASSWORD`, then `JIRA_OAUTH_CLIENT_ID` +
+`JIRA_OAUTH_CLIENT_SECRET`. Also read: `JIRA_TIMEOUT` (seconds), `JIRA_MAX_RETRIES`,
+`JIRA_USER_AGENT`.
 
-For Jira Server or Data Center:
+### With Resilience
 
 ```typescript
-import { createPatAuth } from '@felixgeelhaar/jira-sdk';
+import {
+  createJiraClient,
+  createApiTokenAuth,
+  createResilienceMiddleware,
+} from '@felixgeelhaar/jira-sdk';
 
-const auth = createPatAuth({
-  token: 'your-personal-access-token',
+const auth = createApiTokenAuth({
+  email: 'your-email@example.com',
+  apiToken: 'your-api-token',
 });
-```
-
-### Basic Auth
 
-```typescript
-import { createBasicAuth } from '@felixgeelhaar/jira-sdk';
+// Create resilience middleware with circuit breaker, retry, and rate limiting
+const { middleware, circuitBreaker } = createResilienceMiddleware({
+  retry: {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 30000,
+  },
+  rateLimit: {
+    maxRequests: 90,
+    windowMs: 60000,
+  },
+  circuitBreaker: {
+    failureThreshold: 5,
+    resetTimeoutMs: 30000,
+  },
+});
 
-const auth = createBasicAuth({
-  username: 'your-username',
-  password: 'your-password',
+const client = createJiraClient({
+  host: 'https://your-domain.atlassian.net',
+  auth,
+  middleware: [middleware],
 });
-```
 
-### OAuth 2.0
+// Monitor circuit breaker state
+console.log(circuitBreaker?.getStats());
+```
 
-For OAuth 2.0 3LO (three-legged OAuth):
+Or apply the whole stack as a client option, which also exposes the breaker on
+the client:
 
 ```typescript
-import { createOAuth2Auth } from '@felixgeelhaar/jira-sdk';
+import { createJiraClient, withResilience } from '@felixgeelhaar/jira-sdk';
 
-const auth = createOAuth2Auth({
-  clientId: 'your-client-id',
-  clientSecret: 'your-client-secret',
-  accessToken: 'current-access-token',
-  refreshToken: 'refresh-token',
-  expiresAt: Date.now() + 3600000,
-});
+const client = createJiraClient({ host, auth }, withResilience());
 
-// Automatic token refresh with persistence
-auth.onTokenRefresh = async (tokens) => {
-  await saveTokensToDatabase(tokens);
-};
+console.log(client.circuitBreaker?.getStats());
 ```
 
-## Services
+`withResilience()` disables the client's built-in retry, since the resilience
+stack supplies its own — otherwise the two would compound into
+`maxRetries * maxRetries` attempts.
 
-### Issues
+## Building Content and Queries
+
+### Rich text (ADF)
+
+Jira represents descriptions and comment bodies as Atlassian Document Format,
+not plain strings:
 
 ```typescript
-// Get an issue
-const issue = await client.issues.get('PROJ-123');
-const issue = await client.issues.get('PROJ-123', {
-  fields: ['summary', 'status', 'assignee'],
-  expand: ['changelog', 'renderedFields'],
-});
+import { AdfBuilder } from '@felixgeelhaar/jira-sdk';
 
-// Create an issue
-const newIssue = await client.issues.create({
-  fields: {
-    project: { key: 'PROJ' },
-    summary: 'New issue from SDK',
-    description: 'Detailed description here',
-    issuetype: { name: 'Task' },
-    priority: { name: 'High' },
-    assignee: { accountId: 'user-account-id' },
-  },
-});
+const description = new AdfBuilder()
+  .addHeading('Steps to reproduce', 2)
+  .addOrderedList(['Open the app', 'Click Save', 'Observe the error'])
+  .addCodeBlock('TypeError: undefined is not a function', 'text')
+  .toDocument();
 
-// Update an issue
-await client.issues.update('PROJ-123', {
+await client.issues.create({
   fields: {
-    summary: 'Updated summary',
-    description: 'New description',
+    project: { key: 'PROJ' },
+    summary: 'Crash on save',
+    issuetype: { name: 'Bug' },
+    description,
   },
 });
-
-// Delete an issue
-await client.issues.delete('PROJ-123');
-
-// Transition an issue
-await client.issues.transition('PROJ-123', {
-  transition: { id: '31' }, // Transition ID
-});
-
-// Get available transitions
-const transitions = await client.issues.getTransitions('PROJ-123');
 ```
 
-### Comments
+### JQL
+
+The builder quotes and escapes every value, so user input cannot break out of a
+string literal and inject JQL:
 
 ```typescript
-// Get comments
-const comments = await client.issues.getComments('PROJ-123');
+import { JqlQueryBuilder } from '@felixgeelhaar/jira-sdk';
 
-// Add a comment
-await client.issues.addComment('PROJ-123', {
-  body: 'This is a comment from the SDK',
-});
+const jql = new JqlQueryBuilder()
+  .project('PROJ')
+  .status('In Progress')
+  .assignee(untrustedUserInput) // safely escaped
+  .orderBy('created', 'DESC')
+  .build();
 
-// Update a comment
-await client.issues.updateComment('PROJ-123', 'comment-id', {
-  body: 'Updated comment text',
-});
-
-// Delete a comment
-await client.issues.deleteComment('PROJ-123', 'comment-id');
+const results = await client.search.jql(jql);
 ```
 
-### Search (JQL)
+### Custom fields
 
 ```typescript
-// Simple JQL search
-const results = await client.search.jql('project = PROJ');
-
-// Advanced search with options
-const results = await client.search.jql(
-  'project = PROJ AND status = "In Progress" ORDER BY created DESC',
-  {
-    startAt: 0,
-    maxResults: 50,
-    fields: ['summary', 'status', 'assignee'],
-    expand: ['changelog'],
-  }
-);
-
-// Iterate through all results
-for (const issue of results.issues) {
-  console.log(`${issue.key}: ${issue.fields.summary}`);
-}
+import { CustomFields } from '@felixgeelhaar/jira-sdk';
 
-// Pagination info
-console.log(`Showing ${results.startAt + 1} to ${results.startAt + results.issues.length} of ${results.total}`);
+const fields = new CustomFields()
+  .setString('customfield_10001', 'Team Alpha')
+  .setNumber('customfield_10002', 42)
+  .setLabels('customfield_10003', ['backend', 'urgent']);
 ```
 
-### Projects
+## Authentication Methods
+
+### API Token (Atlassian Cloud)
 
 ```typescript
-// List all projects
-const projects = await client.projects.list();
+import { createApiTokenAuth } from '@felixgeelhaar/jira-sdk';
 
-// Get a project
-const project = await client.projects.get('PROJ');
-const project = await client.projects.get('PROJ', {
-  expand: ['description', 'lead', 'issueTypes'],
+const auth = createApiTokenAuth({
+  email: 'your-email@example.com',
+  apiToken: 'your-api-token', // From https://id.atlassian.com/manage-profile/security/api-tokens
 });
 ```
 
-### Users
+### Personal Access Token (Server/Data Center)
 
 ```typescript
-// Get current user
-const myself = await client.users.getCurrentUser();
-
-// Get user by account ID
-const user = await client.users.get('account-id');
-
-// Search users
-const users = await client.users.search({
-  query: 'john',
-  maxResults: 10,
-});
+import { createPatAuth } from '@felixgeelhaar/jira-sdk';
 
-// Find users assignable to a project
-const assignable = await client.users.findAssignable({
-  project: 'PROJ',
-  query: 'jane',
+const auth = createPatAuth({
+  token: 'your-personal-access-token',
 });
 ```
 
-## Resilience
-
-### Built-in Resilience Middleware
-
-Add retry, rate limiting, and circuit breaker with one call:
+### OAuth 2.0
 
 ```typescript
-import { createJiraClient, createResilienceMiddleware } from '@felixgeelhaar/jira-sdk';
-
-const { middleware, circuitBreaker } = createResilienceMiddleware({
-  retry: {
-    maxRetries: 3,
-    initialDelayMs: 1000,
-    maxDelayMs: 30000,
-    multiplier: 2,
-    jitter: true,
-  },
-  rateLimit: {
-    maxRequests: 90,    // Jira Cloud limit is ~100/min
-    windowMs: 60000,
-    waitForSlot: true,
-  },
-  circuitBreaker: {
-    failureThreshold: 5,
-    resetTimeoutMs: 30000,
-    failureWindowMs: 60000,
-  },
-});
+import { createOAuth2Auth } from '@felixgeelhaar/jira-sdk';
 
-const client = createJiraClient({
-  host: 'https://your-domain.atlassian.net',
-  auth,
-  middleware: [middleware],
+const auth = createOAuth2Auth({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  accessToken: 'current-access-token',
+  refreshToken: 'refresh-token',
+  expiresAt: Date.now() + 3600000, // 1 hour
 });
 
-// Monitor circuit breaker
-setInterval(() => {
-  const stats = circuitBreaker?.getStats();
-  console.log('Circuit state:', stats?.state);
-}, 10000);
+// Automatic token refresh with callback
+auth.onTokenRefresh = async (tokens) => {
+  await saveTokensToDatabase(tokens);
+};
 ```
 
-### Using Default Configuration
+## Available Services
+
+All 27 services are reachable from the client and constructed lazily on first
+access, so an application that only touches issues never pays for the rest.
+
+| Area          | Accessor                                   | Covers                                                                     |
+| ------------- | ------------------------------------------ | -------------------------------------------------------------------------- |
+| Work items    | `client.issues`                            | CRUD, comments, transitions, worklogs, attachments, links, votes, watchers |
+|               | `client.projects`                          | CRUD, components, versions, archive/restore                                |
+|               | `client.search`                            | JQL search, plus the enhanced token-paginated API                          |
+|               | `client.users`                             | Lookup, search, groups, user properties, default columns                   |
+| Agile         | `client.agile`                             | Boards, sprints, epics, backlog (`/rest/agile/1.0`)                        |
+| Configuration | `client.fields`                            | Custom fields, contexts, options, project association                      |
+|               | `client.issueTypes`                        | Issue types and issue type schemes                                         |
+|               | `client.issueLinkTypes`                    | Issue link types                                                           |
+|               | `client.priorities` / `client.resolutions` | Priorities and resolutions                                                 |
+|               | `client.screens`                           | Screens, tabs, screen fields                                               |
+|               | `client.workflows`                         | Workflows, statuses, status categories, schemes                            |
+| Views         | `client.dashboards`                        | Dashboards and gadgets                                                     |
+|               | `client.filters`                           | Saved filters, favourites, share permissions                               |
+| Access        | `client.groups`                            | Groups and membership                                                      |
+|               | `client.myself`                            | Current user and preferences                                               |
+|               | `client.permissions`                       | Permissions, schemes, project roles                                        |
+|               | `client.securityLevels`                    | Issue security levels and schemes                                          |
+| Operations    | `client.appProperties`                     | Application properties, advanced settings                                  |
+|               | `client.audit`                             | Audit records                                                              |
+|               | `client.bulk`                              | Bulk create/delete with task progress polling                              |
+|               | `client.expressions`                       | Jira expression evaluation and analysis                                    |
+|               | `client.labels`                            | Labels and suggestions                                                     |
+|               | `client.notifications`                     | Notification schemes, issue notifications                                  |
+|               | `client.serverInfo`                        | Server info and instance configuration                                     |
+|               | `client.timeTracking`                      | Providers, configuration, worklogs                                         |
+|               | `client.webhooks`                          | Registration, refresh, delivery failures                                   |
+
+### Pagination
+
+Every paginated endpoint exposes an async iterator plus an `all()` collector:
 
 ```typescript
-import { createJiraClient, withResilience } from '@felixgeelhaar/jira-sdk';
-
-// Apply default resilience configuration
-const options = withResilience();
-
-const client = createJiraClient({
-  host: 'https://your-domain.atlassian.net',
-  auth,
-  ...options,
-});
-```
-
-### Disable Specific Features
+// Stream, one page fetched at a time
+for await (const issue of client.search.iterate('project = PROJ')) {
+  console.log(issue.key);
+}
 
-```typescript
-const { middleware } = createResilienceMiddleware({
-  retry: {
-    maxRetries: 5,
-    initialDelayMs: 500,
-  },
-  rateLimit: false,      // Disable rate limiting
-  circuitBreaker: false, // Disable circuit breaker
-});
+// Or collect everything
+const boards = await client.agile.allBoards();
 ```
 
 ## Error Handling
@@ -311,14 +288,9 @@ const { middleware } = createResilienceMiddleware({
 import {
   ApiError,
   UnauthorizedError,
-  ForbiddenError,
   NotFoundError,
   RateLimitError,
-  ServerError,
   NetworkError,
-  TimeoutError,
-  ValidationError,
-  CircuitBreakerOpenError,
 } from '@felixgeelhaar/jira-sdk';
 
 try {
@@ -327,23 +299,11 @@ try {
   if (error instanceof NotFoundError) {
     console.log('Issue not found');
   } else if (error instanceof UnauthorizedError) {
-    console.log('Invalid credentials - check your API token');
-  } else if (error instanceof ForbiddenError) {
-    console.log('You do not have permission to access this issue');
+    console.log('Invalid credentials');
   } else if (error instanceof RateLimitError) {
     console.log(`Rate limited. Retry after ${error.retryAfter}ms`);
-  } else if (error instanceof ServerError) {
-    console.log('Jira server error - try again later');
   } else if (error instanceof NetworkError) {
     console.log('Network error:', error.message);
-  } else if (error instanceof TimeoutError) {
-    console.log('Request timed out');
-  } else if (error instanceof CircuitBreakerOpenError) {
-    console.log('Circuit breaker open - Jira may be unavailable');
-  } else if (error instanceof ValidationError) {
-    console.log('Invalid data:', error.errors);
-  } else if (error instanceof ApiError) {
-    console.log(`API error ${error.statusCode}:`, error.responseBody);
   }
 }
 ```
@@ -352,183 +312,63 @@ try {
 
 ```typescript
 const client = createJiraClient({
-  // Required
   host: 'https://your-domain.atlassian.net',
   auth,
-
-  // Optional
-  apiVersion: '3',           // Jira API version (default: '3')
-  timeout: 30000,            // Request timeout in ms (default: 30000)
-  middleware: [],            // Custom middleware
-  allowInsecureHttp: false,  // Allow HTTP (not recommended)
+  apiVersion: '3', // Jira API version (default: '3')
+  timeout: 30000, // Request timeout in ms (default: 30000)
+  middleware: [], // Custom middleware
+  allowInsecureHttp: false, // Allow HTTP (not recommended)
 });
 ```
 
-## Request Cancellation
+## Development
 
-```typescript
-const controller = new AbortController();
+### Prerequisites
 
-// Start request
-const promise = client.search.jql('project = PROJ', {
-  signal: controller.signal,
-});
+- Node.js >= 20.0.0
+- pnpm >= 9.0.0
 
-// Cancel after 5 seconds
-setTimeout(() => controller.abort(), 5000);
+### Setup
 
-try {
-  const results = await promise;
-} catch (error) {
-  if (error instanceof AbortError) {
-    console.log('Request was cancelled');
-  }
-}
-```
-
-## Custom Middleware
-
-```typescript
-import type { Middleware } from '@felixgeelhaar/jira-sdk';
-
-// Timing middleware
-const timingMiddleware: Middleware = async (context, next) => {
-  const start = Date.now();
-  const response = await next(context);
-  console.log(`${context.request.method} ${context.request.url} - ${Date.now() - start}ms`);
-  return response;
-};
-
-// Add custom headers
-const headerMiddleware: Middleware = async (context, next) => {
-  context.request.headers = {
-    ...context.request.headers,
-    'X-Custom-Header': 'value',
-  };
-  return next(context);
-};
-
-const client = createJiraClient({
-  host: 'https://your-domain.atlassian.net',
-  auth,
-  middleware: [timingMiddleware, headerMiddleware],
-});
-```
-
-## Logging
-
-```typescript
-import { createJiraClient, createLoggingMiddleware, ConsoleLogger } from '@felixgeelhaar/jira-sdk';
-
-const logger = new ConsoleLogger('debug');
-
-const client = createJiraClient({
-  host: 'https://your-domain.atlassian.net',
-  auth,
-  middleware: [createLoggingMiddleware(logger)],
-});
-```
-
-## Subpath Exports
-
-Import specific modules for better tree-shaking:
-
-```typescript
-// Schemas only
-import { IssueSchema, ProjectSchema } from '@felixgeelhaar/jira-sdk/schemas';
-
-// Services only
-import { IssueService, SearchService } from '@felixgeelhaar/jira-sdk/services';
-```
+```bash
+# Install dependencies
+pnpm install
 
-## TypeScript Support
+# Build
+pnpm build
 
-Full TypeScript support with strict mode:
+# Run tests
+pnpm test
 
-```typescript
-import type {
-  Issue,
-  Project,
-  User,
-  SearchResults,
-  JiraClientConfig,
-  ResilienceConfig,
-} from '@felixgeelhaar/jira-sdk';
-
-// Type-safe issue fields
-const issue: Issue = await client.issues.get('PROJ-123');
-console.log(issue.fields.summary); // Type-safe access
+# Type check
+pnpm typecheck
 ```
 
-## Examples
-
-### Bulk Operations
+### Project Structure
 
-```typescript
-// Create multiple issues
-const issues = await Promise.all([
-  client.issues.create({
-    fields: {
-      project: { key: 'PROJ' },
-      summary: 'Task 1',
-      issuetype: { name: 'Task' },
-    },
-  }),
-  client.issues.create({
-    fields: {
-      project: { key: 'PROJ' },
-      summary: 'Task 2',
-      issuetype: { name: 'Task' },
-    },
-  }),
-]);
 ```
-
-### Iterate All Issues
-
-```typescript
-async function* getAllIssues(client: JiraClient, jql: string) {
-  let startAt = 0;
-  const maxResults = 100;
-
-  while (true) {
-    const results = await client.search.jql(jql, { startAt, maxResults });
-
-    for (const issue of results.issues) {
-      yield issue;
-    }
-
-    startAt += results.issues.length;
-    if (startAt >= results.total) break;
-  }
-}
-
-// Usage
-for await (const issue of getAllIssues(client, 'project = PROJ')) {
-  console.log(issue.key);
-}
+jirasdk-ts/
+├── src/
+│   ├── adf/           # Atlassian Document Format builder
+│   ├── auth/          # Authentication providers
+│   ├── client/        # Client, options, env configuration
+│   ├── custom-fields/ # Typed custom-field accessors
+│   ├── errors/        # Error hierarchy
+│   ├── jql/           # JQL query builder and escaping
+│   ├── logging/       # Logging abstraction
+│   ├── pagination/    # Shared pagination primitives
+│   ├── schemas/       # Zod schemas, one directory per domain
+│   ├── services/      # 27 domain services
+│   ├── transport/     # HTTP client, middleware, circuit breaker
+│   └── utils/         # Utility functions
+└── package.json
 ```
 
-### Webhook Handler
+## Security
 
-```typescript
-import express from 'express';
-import { IssueSchema } from '@felixgeelhaar/jira-sdk/schemas';
-
-const app = express();
-
-app.post('/webhook/jira', express.json(), (req, res) => {
-  const result = IssueSchema.safeParse(req.body.issue);
-
-  if (result.success) {
-    console.log('Issue updated:', result.data.key);
-    res.sendStatus(200);
-  } else {
-    console.error('Invalid webhook payload:', result.error);
-    res.sendStatus(400);
-  }
-});
-```
+- **HTTPS Required**: HTTP URLs throw in production (configurable)
+- **Credential Safety**: Sensitive headers automatically redacted in logs
+- **Token Refresh**: OAuth2 uses mutex to prevent concurrent refresh races
 
 ## License