@felixgeelhaar/jira-sdk 0.2.0 → 1.0.0

package/dist/transport/index.d.ts

@@ -0,0 +1,372 @@
+import { g as MiddlewareContext, M as Middleware } from '../http-client-erRvYNs-.js';
+export { H as HttpClient, c as HttpClientConfig, d as HttpMethod, e as HttpRequest, f as HttpResponse, L as Logger, h as MiddlewareNext, Q as QueryParamValue, R as RequestOptions, i as createHttpClient } from '../http-client-erRvYNs-.js';
+import '../types-E6djPHpW.js';
+import 'zod';
+
+/**
+ * Logging middleware configuration
+ */
+interface LoggingMiddlewareConfig {
+    /**
+     * Log request details
+     */
+    logRequests?: boolean;
+    /**
+     * Log response details
+     */
+    logResponses?: boolean;
+    /**
+     * Log errors
+     */
+    logErrors?: boolean;
+    /**
+     * Redact sensitive headers (authorization, etc.)
+     */
+    redactHeaders?: string[];
+}
+/**
+ * Create a logging middleware
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient({
+ *   baseUrl: '...',
+ *   middleware: [
+ *     createLoggingMiddleware({ logRequests: true, logResponses: true }),
+ *   ],
+ * });
+ * ```
+ */
+declare function createLoggingMiddleware(config?: LoggingMiddlewareConfig): Middleware;
+/**
+ * Retry middleware configuration
+ */
+interface RetryMiddlewareConfig {
+    /**
+     * Maximum number of retries (default: 3)
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in ms (default: 1000)
+     */
+    initialDelayMs?: number;
+    /**
+     * Maximum delay in ms (default: 30000)
+     */
+    maxDelayMs?: number;
+    /**
+     * Backoff multiplier (default: 2)
+     */
+    multiplier?: number;
+    /**
+     * Add random jitter (default: true)
+     */
+    jitter?: boolean;
+    /**
+     * Custom retry condition
+     */
+    shouldRetry?: (error: unknown, context: MiddlewareContext) => boolean;
+}
+/**
+ * Create a retry middleware with exponential backoff
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient({
+ *   baseUrl: '...',
+ *   middleware: [
+ *     createRetryMiddleware({ maxRetries: 3 }),
+ *   ],
+ * });
+ * ```
+ */
+declare function createRetryMiddleware(config?: RetryMiddlewareConfig): Middleware;
+/**
+ * Rate limit middleware configuration
+ */
+interface RateLimitMiddlewareConfig {
+    /**
+     * Maximum requests per window
+     */
+    maxRequests: number;
+    /**
+     * Window duration in ms
+     */
+    windowMs: number;
+    /**
+     * Wait for slot instead of throwing error
+     */
+    waitForSlot?: boolean;
+}
+/**
+ * Create a client-side rate limiting middleware
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient({
+ *   baseUrl: '...',
+ *   middleware: [
+ *     createRateLimitMiddleware({ maxRequests: 100, windowMs: 60000 }),
+ *   ],
+ * });
+ * ```
+ */
+declare function createRateLimitMiddleware(config: RateLimitMiddlewareConfig): Middleware;
+/**
+ * Request ID middleware - adds a unique ID to each request
+ */
+declare function createRequestIdMiddleware(headerName?: string): Middleware;
+/**
+ * User-Agent middleware configuration
+ */
+interface UserAgentMiddlewareConfig {
+    /**
+     * SDK name
+     */
+    sdkName: string;
+    /**
+     * SDK version
+     */
+    sdkVersion: string;
+    /**
+     * Additional user agent suffix
+     */
+    suffix?: string;
+}
+/**
+ * Create a User-Agent middleware
+ */
+declare function createUserAgentMiddleware(config: UserAgentMiddlewareConfig): Middleware;
+/**
+ * Compose multiple middleware into a single middleware
+ */
+declare function composeMiddleware(...middlewares: Middleware[]): Middleware;
+
+/**
+ * Circuit breaker states
+ */
+declare enum CircuitState {
+    CLOSED = "CLOSED",// Normal operation, requests flow through
+    OPEN = "OPEN",// Circuit is open, requests fail fast
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit breaker configuration
+ */
+interface CircuitBreakerConfig {
+    /**
+     * Number of failures before opening the circuit (default: 5)
+     */
+    failureThreshold?: number;
+    /**
+     * Time in ms to wait before testing recovery (default: 30000)
+     */
+    resetTimeoutMs?: number;
+    /**
+     * Time window in ms to count failures (default: 60000)
+     */
+    failureWindowMs?: number;
+    /**
+     * Number of successful requests in half-open state to close circuit (default: 1)
+     */
+    successThreshold?: number;
+    /**
+     * Custom function to determine if an error should count as a failure
+     */
+    isFailure?: (error: unknown) => boolean;
+    /**
+     * Callback when state changes
+     */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+/**
+ * Circuit breaker error thrown when circuit is open
+ */
+declare class CircuitBreakerOpenError extends Error {
+    readonly code = "CIRCUIT_BREAKER_OPEN";
+    readonly remainingMs: number;
+    constructor(message: string, remainingMs: number);
+}
+/**
+ * Circuit breaker state manager
+ */
+declare class CircuitBreaker {
+    private state;
+    private failures;
+    private lastFailureTime;
+    private successCount;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly failureWindowMs;
+    private readonly successThreshold;
+    private readonly isFailure;
+    private readonly onStateChange;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Get current circuit state
+     */
+    getState(): CircuitState;
+    /**
+     * Check if request is allowed
+     */
+    canExecute(): boolean;
+    /**
+     * Record a successful request
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed request
+     */
+    recordFailure(error: unknown): void;
+    /**
+     * Get remaining time until circuit can transition to half-open
+     */
+    getRemainingOpenTime(): number;
+    /**
+     * Force reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        remainingOpenTimeMs: number;
+    };
+    private updateState;
+    private transitionTo;
+    private cleanupFailures;
+}
+/**
+ * Create a circuit breaker middleware
+ *
+ * The circuit breaker pattern prevents cascading failures by:
+ * 1. Tracking failures within a time window
+ * 2. Opening the circuit when failure threshold is reached
+ * 3. Failing fast while circuit is open
+ * 4. Testing recovery with half-open state
+ *
+ * @example
+ * ```typescript
+ * const circuitBreaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   resetTimeoutMs: 30000,
+ *   onStateChange: (from, to) => console.log(`Circuit: ${from} -> ${to}`),
+ * });
+ *
+ * const client = new HttpClient({
+ *   baseUrl: '...',
+ *   middleware: [
+ *     createCircuitBreakerMiddleware(circuitBreaker),
+ *   ],
+ * });
+ * ```
+ */
+declare function createCircuitBreakerMiddleware(circuitBreaker: CircuitBreaker): Middleware;
+/**
+ * Create a circuit breaker with default configuration
+ */
+declare function createDefaultCircuitBreaker(config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+
+/**
+ * Rate-limit budget advertised by Jira's `Beta-RateLimit-Policy` header.
+ */
+interface RateLimitPolicy {
+    /** Total cost budget for the window. */
+    limit: number;
+    /** Window length in seconds. */
+    windowSeconds: number;
+}
+/**
+ * A point-in-time read of the rate-limit headers on a single response.
+ *
+ * Every field is optional: Jira does not send these headers on all endpoints,
+ * and the beta headers in particular are only present on APIs enrolled in the
+ * cost-based rate-limiting rollout (Atlassian CHANGE-3045).
+ */
+interface RateLimitSnapshot {
+    /** `X-RateLimit-Remaining` — legacy request-count budget. */
+    remainingRequests?: number;
+    /** `Retry-After` — seconds to wait, present on 429 responses. */
+    retryAfterSeconds?: number;
+    /** Parsed `Beta-RateLimit-Policy`. */
+    policy?: RateLimitPolicy;
+    /** Parsed `r=` value from `Beta-RateLimit` — remaining cost points. */
+    remainingPoints?: number;
+}
+/**
+ * Parse the `Beta-RateLimit-Policy` header.
+ *
+ * Format: `"100;w=60"` — a limit followed by `;w=<window seconds>`.
+ *
+ * @param header Raw header value.
+ * @returns The parsed policy, or `undefined` if absent or malformed.
+ */
+declare function parseBetaRateLimitPolicy(header: string | null | undefined): RateLimitPolicy | undefined;
+/**
+ * Parse the `Beta-RateLimit` header.
+ *
+ * Format: `r=85;policy="100;w=60"` — `r` is the remaining cost points.
+ *
+ * @param header Raw header value.
+ * @returns Remaining points, or `undefined` if absent or malformed.
+ */
+declare function parseBetaRateLimit(header: string | null | undefined): number | undefined;
+/**
+ * Parse a `Retry-After` header, which may be either a number of seconds or an
+ * HTTP-date.
+ *
+ * @param header Raw header value.
+ * @param now Reference time for HTTP-date values; defaults to the current time.
+ * @returns Seconds to wait, or `undefined` if absent or malformed.
+ */
+declare function parseRetryAfterSeconds(header: string | null | undefined, now?: number): number | undefined;
+/**
+ * Read every rate-limit signal Jira exposes from a response's headers.
+ *
+ * @param headers Response headers.
+ * @returns A snapshot with whichever fields were present.
+ */
+declare function readRateLimitHeaders(headers: Headers): RateLimitSnapshot;
+/**
+ * Configuration for {@link createRateLimitHeaderMiddleware}.
+ */
+interface RateLimitHeaderMiddlewareConfig {
+    /**
+     * Called after every response that carries at least one rate-limit header.
+     *
+     * Use it to drive adaptive throttling, emit metrics, or warn as the budget
+     * runs low. Errors thrown here are swallowed so observability never breaks a
+     * request.
+     */
+    onRateLimit: (snapshot: RateLimitSnapshot) => void;
+}
+/**
+ * Observe Jira's rate-limit headers on every response.
+ *
+ * The Go SDK parses these headers and only logs them. This middleware hands
+ * them to a callback instead, so a consumer can react — for example by backing
+ * off before Jira starts returning 429s.
+ *
+ * @example
+ * ```typescript
+ * const client = createJiraClient({
+ *   host,
+ *   auth,
+ *   middleware: [
+ *     createRateLimitHeaderMiddleware({
+ *       onRateLimit: (snapshot) => {
+ *         if (snapshot.remainingPoints !== undefined && snapshot.remainingPoints < 10) {
+ *           logger.warn('Jira rate-limit budget nearly exhausted', snapshot);
+ *         }
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function createRateLimitHeaderMiddleware(config: RateLimitHeaderMiddlewareConfig): Middleware;
+
+export { CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerOpenError, CircuitState, type LoggingMiddlewareConfig, Middleware, MiddlewareContext, type RateLimitHeaderMiddlewareConfig, type RateLimitMiddlewareConfig, type RateLimitPolicy, type RateLimitSnapshot, type RetryMiddlewareConfig, type UserAgentMiddlewareConfig, composeMiddleware, createCircuitBreakerMiddleware, createDefaultCircuitBreaker, createLoggingMiddleware, createRateLimitHeaderMiddleware, createRateLimitMiddleware, createRequestIdMiddleware, createRetryMiddleware, createUserAgentMiddleware, parseBetaRateLimit, parseBetaRateLimitPolicy, parseRetryAfterSeconds, readRateLimitHeaders };