@felixgeelhaar/jira-sdk 0.3.0 → 1.0.0

package/dist/http-client-BSzRYQZa.d.cts

@@ -0,0 +1,317 @@
+import { A as AuthProvider } from './types-E6djPHpW.cjs';
+
+/**
+ * Logging abstraction for the SDK.
+ * Provides a simple interface that can be implemented by any logging library.
+ */
+/** Log levels supported by the SDK */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Structured log fields */
+type LogFields = Record<string, unknown>;
+/**
+ * Logger interface that SDK consumers can implement.
+ * Compatible with most logging libraries.
+ */
+interface Logger {
+    /** Log debug messages (verbose, for development) */
+    debug(message: string, fields?: LogFields): void;
+    /** Log informational messages (normal operations) */
+    info(message: string, fields?: LogFields): void;
+    /** Log warning messages (potential issues) */
+    warn(message: string, fields?: LogFields): void;
+    /** Log error messages (failures) */
+    error(message: string, fields?: LogFields): void;
+    /** Create a child logger with additional context */
+    child?(fields: LogFields): Logger;
+}
+/**
+ * Check if a value implements the Logger interface
+ */
+declare function isLogger(value: unknown): value is Logger;
+
+/**
+ * HTTP request method
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+/**
+ * A value that may appear in a query string.
+ *
+ * Arrays are serialized as repeated keys (`id=1&id=2`), which is what Jira
+ * expects for parameters it documents as "ampersand-separated". Parameters it
+ * documents as "comma-separated" should be joined by the caller into a single
+ * string instead.
+ */
+type QueryParamValue = string | number | boolean | string[] | number[];
+/**
+ * HTTP request configuration
+ */
+interface HttpRequest {
+    /**
+     * Request URL (can be relative to base URL)
+     */
+    url: string;
+    /**
+     * HTTP method
+     */
+    method: HttpMethod;
+    /**
+     * Request headers
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Request body (will be JSON stringified if object)
+     */
+    body?: unknown;
+    /**
+     * Query parameters
+     */
+    params?: Record<string, QueryParamValue | undefined> | undefined;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number | undefined;
+    /**
+     * AbortSignal for request cancellation
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Custom metadata passed through middleware
+     */
+    metadata?: Record<string, unknown> | undefined;
+}
+/**
+ * HTTP response
+ */
+interface HttpResponse<T = unknown> {
+    /**
+     * Response status code
+     */
+    status: number;
+    /**
+     * Response status text
+     */
+    statusText: string;
+    /**
+     * Response headers
+     */
+    headers: Headers;
+    /**
+     * Parsed response body
+     */
+    data: T;
+    /**
+     * Original request
+     */
+    request: HttpRequest;
+    /**
+     * Response time in milliseconds
+     */
+    responseTime: number;
+}
+/**
+ * Middleware context passed through the chain
+ */
+interface MiddlewareContext {
+    /**
+     * Current request
+     */
+    request: HttpRequest;
+    /**
+     * Auth provider (if configured)
+     */
+    auth?: AuthProvider | undefined;
+    /**
+     * Logger instance
+     */
+    logger: Logger;
+    /**
+     * Retry count (incremented by retry middleware)
+     */
+    retryCount: number;
+    /**
+     * Custom context data
+     */
+    [key: string]: unknown;
+}
+/**
+ * Next function to call the next middleware or the actual request
+ */
+type MiddlewareNext = (context: MiddlewareContext) => Promise<HttpResponse>;
+/**
+ * Middleware function type
+ */
+type Middleware = (context: MiddlewareContext, next: MiddlewareNext) => Promise<HttpResponse>;
+/**
+ * HTTP client configuration
+ */
+interface HttpClientConfig {
+    /**
+     * Base URL for all requests
+     */
+    baseUrl: string;
+    /**
+     * Authentication provider
+     */
+    auth?: AuthProvider;
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+    /**
+     * Default request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Default headers for all requests
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Middleware chain
+     */
+    middleware?: Middleware[];
+    /**
+     * Custom fetch implementation (for testing or alternative runtimes)
+     */
+    fetch?: typeof fetch;
+    /**
+     * Allow insecure HTTP connections (not recommended for production)
+     *
+     * By default, HTTP URLs will throw an error in production and warn in development.
+     * Set to true to disable this security check (useful for testing or internal APIs).
+     *
+     * @default false
+     */
+    allowInsecureHttp?: boolean;
+}
+/**
+ * Request options for individual requests
+ */
+interface RequestOptions {
+    /**
+     * Request timeout override
+     */
+    timeout?: number | undefined;
+    /**
+     * AbortSignal for cancellation
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Additional headers for this request
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Query-string parameters for this request.
+     *
+     * Available on every verb, not just GET — Jira attaches query parameters to
+     * POST, PUT and DELETE endpoints too (`expand`, `notifyUsers`,
+     * `replaceWith`, and so on).
+     */
+    params?: Record<string, QueryParamValue | undefined> | undefined;
+    /**
+     * Custom metadata passed to middleware
+     */
+    metadata?: Record<string, unknown> | undefined;
+    /**
+     * Skip authentication for this request
+     */
+    skipAuth?: boolean | undefined;
+}
+
+/**
+ * HTTP client for making API requests
+ *
+ * Features:
+ * - Middleware support for request/response processing
+ * - Automatic authentication header injection
+ * - Request timeout handling
+ * - AbortSignal support for cancellation
+ * - Automatic JSON serialization/deserialization
+ * - Error classification (API errors, network errors, etc.)
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient({
+ *   baseUrl: 'https://your-domain.atlassian.net',
+ *   auth: new ApiTokenAuth({ email: '...', apiToken: '...' }),
+ *   middleware: [loggingMiddleware, retryMiddleware],
+ * });
+ *
+ * const response = await client.get('/rest/api/3/myself');
+ * ```
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly logger;
+    private readonly timeout;
+    private readonly defaultHeaders;
+    private readonly middleware;
+    private readonly fetchFn;
+    private middlewareChain;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make a GET request
+     */
+    get<T = unknown>(path: string, params?: Record<string, QueryParamValue | undefined>, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a POST request
+     */
+    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a PUT request
+     */
+    put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a PATCH request
+     */
+    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a DELETE request
+     */
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a request with full control over the configuration
+     */
+    request<T = unknown>(requestConfig: Omit<HttpRequest, 'method'> & {
+        method?: HttpMethod;
+    } & RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Build the middleware chain with the final request handler
+     */
+    private buildMiddlewareChain;
+    /**
+     * Execute the actual HTTP request
+     */
+    private executeRequest;
+    /**
+     * Handle error responses and throw appropriate errors
+     */
+    private handleErrorResponse;
+    /**
+     * Parse Retry-After header
+     */
+    private parseRetryAfter;
+    /**
+     * Combine multiple AbortSignals
+     */
+    private combineSignals;
+    /**
+     * Add middleware to the chain
+     * Note: This rebuilds the middleware chain for the new configuration
+     */
+    use(middleware: Middleware): this;
+    /**
+     * Get the base URL
+     */
+    getBaseUrl(): string;
+    /**
+     * Get the auth provider
+     */
+    getAuth(): AuthProvider | undefined;
+}
+/**
+ * Factory function to create HTTP client
+ */
+declare function createHttpClient(config: HttpClientConfig): HttpClient;
+
+export { HttpClient as H, type Logger as L, type Middleware as M, type QueryParamValue as Q, type RequestOptions as R, type LogFields as a, type LogLevel as b, type HttpClientConfig as c, type HttpMethod as d, type HttpRequest as e, type HttpResponse as f, type MiddlewareContext as g, type MiddlewareNext as h, createHttpClient as i, isLogger as j };

package/dist/http-client-erRvYNs-.d.ts

@@ -0,0 +1,317 @@
+import { A as AuthProvider } from './types-E6djPHpW.js';
+
+/**
+ * Logging abstraction for the SDK.
+ * Provides a simple interface that can be implemented by any logging library.
+ */
+/** Log levels supported by the SDK */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Structured log fields */
+type LogFields = Record<string, unknown>;
+/**
+ * Logger interface that SDK consumers can implement.
+ * Compatible with most logging libraries.
+ */
+interface Logger {
+    /** Log debug messages (verbose, for development) */
+    debug(message: string, fields?: LogFields): void;
+    /** Log informational messages (normal operations) */
+    info(message: string, fields?: LogFields): void;
+    /** Log warning messages (potential issues) */
+    warn(message: string, fields?: LogFields): void;
+    /** Log error messages (failures) */
+    error(message: string, fields?: LogFields): void;
+    /** Create a child logger with additional context */
+    child?(fields: LogFields): Logger;
+}
+/**
+ * Check if a value implements the Logger interface
+ */
+declare function isLogger(value: unknown): value is Logger;
+
+/**
+ * HTTP request method
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+/**
+ * A value that may appear in a query string.
+ *
+ * Arrays are serialized as repeated keys (`id=1&id=2`), which is what Jira
+ * expects for parameters it documents as "ampersand-separated". Parameters it
+ * documents as "comma-separated" should be joined by the caller into a single
+ * string instead.
+ */
+type QueryParamValue = string | number | boolean | string[] | number[];
+/**
+ * HTTP request configuration
+ */
+interface HttpRequest {
+    /**
+     * Request URL (can be relative to base URL)
+     */
+    url: string;
+    /**
+     * HTTP method
+     */
+    method: HttpMethod;
+    /**
+     * Request headers
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Request body (will be JSON stringified if object)
+     */
+    body?: unknown;
+    /**
+     * Query parameters
+     */
+    params?: Record<string, QueryParamValue | undefined> | undefined;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number | undefined;
+    /**
+     * AbortSignal for request cancellation
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Custom metadata passed through middleware
+     */
+    metadata?: Record<string, unknown> | undefined;
+}
+/**
+ * HTTP response
+ */
+interface HttpResponse<T = unknown> {
+    /**
+     * Response status code
+     */
+    status: number;
+    /**
+     * Response status text
+     */
+    statusText: string;
+    /**
+     * Response headers
+     */
+    headers: Headers;
+    /**
+     * Parsed response body
+     */
+    data: T;
+    /**
+     * Original request
+     */
+    request: HttpRequest;
+    /**
+     * Response time in milliseconds
+     */
+    responseTime: number;
+}
+/**
+ * Middleware context passed through the chain
+ */
+interface MiddlewareContext {
+    /**
+     * Current request
+     */
+    request: HttpRequest;
+    /**
+     * Auth provider (if configured)
+     */
+    auth?: AuthProvider | undefined;
+    /**
+     * Logger instance
+     */
+    logger: Logger;
+    /**
+     * Retry count (incremented by retry middleware)
+     */
+    retryCount: number;
+    /**
+     * Custom context data
+     */
+    [key: string]: unknown;
+}
+/**
+ * Next function to call the next middleware or the actual request
+ */
+type MiddlewareNext = (context: MiddlewareContext) => Promise<HttpResponse>;
+/**
+ * Middleware function type
+ */
+type Middleware = (context: MiddlewareContext, next: MiddlewareNext) => Promise<HttpResponse>;
+/**
+ * HTTP client configuration
+ */
+interface HttpClientConfig {
+    /**
+     * Base URL for all requests
+     */
+    baseUrl: string;
+    /**
+     * Authentication provider
+     */
+    auth?: AuthProvider;
+    /**
+     * Logger instance
+     */
+    logger?: Logger;
+    /**
+     * Default request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Default headers for all requests
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Middleware chain
+     */
+    middleware?: Middleware[];
+    /**
+     * Custom fetch implementation (for testing or alternative runtimes)
+     */
+    fetch?: typeof fetch;
+    /**
+     * Allow insecure HTTP connections (not recommended for production)
+     *
+     * By default, HTTP URLs will throw an error in production and warn in development.
+     * Set to true to disable this security check (useful for testing or internal APIs).
+     *
+     * @default false
+     */
+    allowInsecureHttp?: boolean;
+}
+/**
+ * Request options for individual requests
+ */
+interface RequestOptions {
+    /**
+     * Request timeout override
+     */
+    timeout?: number | undefined;
+    /**
+     * AbortSignal for cancellation
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Additional headers for this request
+     */
+    headers?: Record<string, string> | undefined;
+    /**
+     * Query-string parameters for this request.
+     *
+     * Available on every verb, not just GET — Jira attaches query parameters to
+     * POST, PUT and DELETE endpoints too (`expand`, `notifyUsers`,
+     * `replaceWith`, and so on).
+     */
+    params?: Record<string, QueryParamValue | undefined> | undefined;
+    /**
+     * Custom metadata passed to middleware
+     */
+    metadata?: Record<string, unknown> | undefined;
+    /**
+     * Skip authentication for this request
+     */
+    skipAuth?: boolean | undefined;
+}
+
+/**
+ * HTTP client for making API requests
+ *
+ * Features:
+ * - Middleware support for request/response processing
+ * - Automatic authentication header injection
+ * - Request timeout handling
+ * - AbortSignal support for cancellation
+ * - Automatic JSON serialization/deserialization
+ * - Error classification (API errors, network errors, etc.)
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient({
+ *   baseUrl: 'https://your-domain.atlassian.net',
+ *   auth: new ApiTokenAuth({ email: '...', apiToken: '...' }),
+ *   middleware: [loggingMiddleware, retryMiddleware],
+ * });
+ *
+ * const response = await client.get('/rest/api/3/myself');
+ * ```
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly logger;
+    private readonly timeout;
+    private readonly defaultHeaders;
+    private readonly middleware;
+    private readonly fetchFn;
+    private middlewareChain;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make a GET request
+     */
+    get<T = unknown>(path: string, params?: Record<string, QueryParamValue | undefined>, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a POST request
+     */
+    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a PUT request
+     */
+    put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a PATCH request
+     */
+    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a DELETE request
+     */
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Make a request with full control over the configuration
+     */
+    request<T = unknown>(requestConfig: Omit<HttpRequest, 'method'> & {
+        method?: HttpMethod;
+    } & RequestOptions): Promise<HttpResponse<T>>;
+    /**
+     * Build the middleware chain with the final request handler
+     */
+    private buildMiddlewareChain;
+    /**
+     * Execute the actual HTTP request
+     */
+    private executeRequest;
+    /**
+     * Handle error responses and throw appropriate errors
+     */
+    private handleErrorResponse;
+    /**
+     * Parse Retry-After header
+     */
+    private parseRetryAfter;
+    /**
+     * Combine multiple AbortSignals
+     */
+    private combineSignals;
+    /**
+     * Add middleware to the chain
+     * Note: This rebuilds the middleware chain for the new configuration
+     */
+    use(middleware: Middleware): this;
+    /**
+     * Get the base URL
+     */
+    getBaseUrl(): string;
+    /**
+     * Get the auth provider
+     */
+    getAuth(): AuthProvider | undefined;
+}
+/**
+ * Factory function to create HTTP client
+ */
+declare function createHttpClient(config: HttpClientConfig): HttpClient;
+
+export { HttpClient as H, type Logger as L, type Middleware as M, type QueryParamValue as Q, type RequestOptions as R, type LogFields as a, type LogLevel as b, type HttpClientConfig as c, type HttpMethod as d, type HttpRequest as e, type HttpResponse as f, type MiddlewareContext as g, type MiddlewareNext as h, createHttpClient as i, isLogger as j };