redmine-context 1.0.0

package/dist/cache-first.js

@@ -0,0 +1,227 @@
+/**
+ * Leitura CACHE-FIRST não-bloqueante das extrações de anexos (M4-11, ADR-004).
+ *
+ * O núcleo do modo cache-first do MCP (#70): dado uma issue JÁ normalizada, para
+ * cada anexo com extrator registrado LÊ o cache attachment-level e devolve
+ * IMEDIATAMENTE o que já está pronto (`done`/`text`). Quando a extração de um
+ * anexo pesado (vídeo/áudio) ainda NÃO está no cache, NÃO espera a extração
+ * terminar: marca o anexo como {@link ExtractionStatus} `processing` com
+ * metadados e, opcionalmente, dispara o job de extração em SEGUNDO PLANO via a
+ * fila (`runQueue`, #67) — fire-and-forget. Assim nenhuma chamada MCP bloqueia
+ * aguardando mídia (resposta imediata; a continuação que completa na 2ª chamada
+ * é a #71).
+ *
+ * A leitura de cache (índice/`extraction.json`) é barata (ms); só a COMPUTAÇÃO da
+ * extração é cara — e é justamente ela que este módulo evita no caminho síncrono.
+ * A chave attachment-level é montada EXATAMENTE como no caminho bloqueante
+ * ({@link extractIssueAttachments}) — mesmos `probableMime`/`toExtractorConfig` —
+ * garantindo cache-hit coerente com o que o job de background grava.
+ *
+ * Fronteira ADR-005: módulo de core (pipeline de extração). Não importa de
+ * `src/surfaces/**` e nunca usa `console.*` — avisos vão pelo {@link Logger}.
+ */
+import { buildAttachmentKey, serializeCacheKey, } from './cache/index.js';
+import { probableMime, toExtractorConfig } from './extract-issue-attachments.js';
+import { runQueue } from './extract/index.js';
+/** Extrai uma mensagem legível de um erro desconhecido. */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Constrói um {@link ExtractionResult} `processing` — o anexo existe e TEM
+ * extrator, mas a extração (cara) ainda não está no cache. Sinaliza à superfície
+ * que o texto virá em uma consulta futura (#71), sem bloquear a atual.
+ *
+ * @returns Resultado `processing` com motivo/dica legíveis (sem texto).
+ */
+export function processingResult() {
+    return {
+        status: 'processing',
+        metadata: {
+            reason: 'extracao-em-andamento',
+            hint: 'anexo ainda nao processado; a extracao roda em segundo plano — consulte novamente em instantes',
+        },
+    };
+}
+/**
+ * Lê o cache das extrações de TODOS os anexos com extrator registrado de uma
+ * issue, SEM computar nenhuma extração (não-bloqueante).
+ *
+ * Para cada anexo:
+ * - sem extrator para o MIME provável → nem entra no mapa (igual ao bloqueante);
+ * - cache-hit → o {@link ExtractionResult} pronto (texto imediato);
+ * - cache-miss → `processing` + (opcional) dispara o job de background.
+ *
+ * @param issue - Issue normalizada cujos anexos serão consultados no cache.
+ * @param options - Ver {@link CacheFirstExtractionOptions}.
+ * @returns `Map<attachmentId, ExtractionResult>` só com anexos que têm extrator.
+ * @example
+ * const map = await extractIssueAttachmentsCacheFirst(issue, {
+ *   instanceUrl, registry, store, background,
+ * });
+ */
+export async function extractIssueAttachmentsCacheFirst(issue, options) {
+    const { instanceUrl, registry, store, background, logger } = options;
+    const result = new Map();
+    for (const attachment of issue.attachments) {
+        const mime = probableMime(attachment);
+        const extractor = mime !== undefined ? registry.find(mime) : undefined;
+        if (extractor === undefined) {
+            // Sem extrator: não há trabalho a fazer — não entra no mapa (paridade com
+            // o caminho bloqueante `extractIssueAttachments`).
+            continue;
+        }
+        const key = buildAttachmentKey({ instanceUrl, attachment, extractor: toExtractorConfig(extractor) });
+        let cached;
+        try {
+            cached = await store.get(key);
+        }
+        catch (error) {
+            // Falha de leitura de cache não bloqueia nem derruba: trata como miss.
+            logger?.warn(`cache-first: falha ao ler o cache do anexo #${attachment.id}: ${messageOf(error)}`);
+            cached = undefined;
+        }
+        if (cached !== undefined) {
+            result.set(attachment.id, cached);
+            continue;
+        }
+        // Cache-miss: NÃO espera a extração cara — sinaliza `processing` na hora e,
+        // se um dispatcher foi injetado, enfileira o job em background (fire-and-forget).
+        result.set(attachment.id, processingResult());
+        background?.({ attachment, extractor, key });
+    }
+    return result;
+}
+/**
+ * Constrói um {@link ExtractionResult} `failed` para PERSISTIR quando o job de
+ * background falha (compute lança/rejeita). É o que impede o `processing` eterno:
+ * sem um `failed` no cache, a próxima chamada re-dispararia o job em loop.
+ *
+ * @param reason - Motivo legível da falha (mensagem do erro/`reason` da fila).
+ * @returns Resultado `failed` com o motivo preservado no `metadata`.
+ */
+function backgroundFailedResult(reason) {
+    return {
+        status: 'failed',
+        metadata: {
+            reason: 'background-extracao-falhou',
+            error: reason ?? 'motivo desconhecido',
+        },
+    };
+}
+/**
+ * Grava `value` no cache sob `key` APENAS se ainda não houver valor — idempotente
+ * e sem clobber. Uma falha de IO do próprio cache vira aviso (nunca derruba o job
+ * de background). É o ponto que fecha o loop do #71: garante que, após o job, a
+ * chave attachment-level NUNCA fique vazia (senão a próxima chamada re-dispara).
+ *
+ * @param store - Store attachment-level a persistir.
+ * @param key - Chave attachment-level (idêntica à lida no cache-first).
+ * @param value - Resultado a gravar quando a chave está ausente.
+ * @param attachmentId - Id do anexo (para compor a mensagem de aviso).
+ * @param logger - Sink de avisos; ausente = silencioso.
+ */
+async function persistIfAbsent(store, key, value, attachmentId, logger) {
+    try {
+        const existing = await store.get(key);
+        if (existing !== undefined) {
+            return;
+        }
+        await store.put(key, value);
+    }
+    catch (error) {
+        logger?.warn(`cache-first: falha ao persistir o resultado do anexo #${attachmentId}: ${messageOf(error)}`);
+    }
+}
+/**
+ * Consome, em segundo plano, as transições de uma fila de background — sem
+ * bloquear o chamador — e FECHA O LOOP do #71: quando `store` é dado, PERSISTE o
+ * resultado do job sob a chave do alvo para que a 2ª chamada acerte o cache.
+ *
+ * - `done`: grava o resultado (idempotente/if-absent). Cobre o caso em que o
+ *   pipeline devolveu `failed` capturado por anexo SEM persistir — sem isso a
+ *   chave ficaria vazia e a próxima chamada re-dispararia (processing eterno).
+ * - `failed`: avisa e PERSISTE um `failed`, garantindo que uma falha do job vire
+ *   `failed` no cache — NUNCA `processing` para sempre.
+ *
+ * Falhas/cancelamentos nunca são relançados (a resposta MCP já voltou).
+ *
+ * @param events - Sequência de transições de {@link runQueue}.
+ * @param target - Alvo do cache-miss (anexo + chave attachment-level).
+ * @param logger - Sink de avisos; ausente = silencioso.
+ * @param store - Store onde persistir o resultado de fechamento; ausente = não persiste.
+ */
+async function drainDetached(events, target, logger, store) {
+    const attachmentId = target.attachment.id;
+    try {
+        for await (const event of events) {
+            if (event.status === 'done') {
+                // Nunca persistir um `processing` (invariante do #71): cachear `processing`
+                // faria a 2ª chamada acertar o cache em `processing` e nunca re-disparar.
+                if (store !== undefined && event.result !== undefined && event.result.status !== 'processing') {
+                    await persistIfAbsent(store, target.key, event.result, attachmentId, logger);
+                }
+            }
+            else if (event.status === 'failed') {
+                logger?.warn(`cache-first: extracao em background do anexo #${attachmentId} falhou: ${event.reason ?? 'motivo desconhecido'}`);
+                if (store !== undefined) {
+                    await persistIfAbsent(store, target.key, backgroundFailedResult(event.reason), attachmentId, logger);
+                }
+            }
+        }
+    }
+    catch (error) {
+        logger?.warn(`cache-first: fila de background do anexo #${attachmentId} abortou: ${messageOf(error)}`);
+    }
+}
+/**
+ * Cria um {@link BackgroundExtractor} respaldado pela fila de jobs (#67): cada
+ * anexo com cache-miss vira UM {@link QueueJob} rodado por `runQueue`, cujas
+ * transições são consumidas de forma DESACOPLADA (fire-and-forget). O dispatcher
+ * retorna imediatamente — o trabalho caro acontece na fila, fora do caminho da
+ * resposta MCP. O `AbortSignal` da fila é propagado ao `compute` via
+ * {@link JobContext.signal} (#69), pronto para o kill de subprocesso do #68.
+ *
+ * DEDUP DE IN-FLIGHT (#71): o dispatcher mantém um registro dos jobs em andamento
+ * POR CHAVE attachment-level. Uma 2ª chamada para um anexo cujo job ainda processa
+ * NÃO dispara um job duplicado — reusa o que já corre. O registro é limpo quando o
+ * job conclui (via `finally`), liberando futuras re-extrações (ex.: cache invalidado).
+ *
+ * @param compute - Executa a extração real do anexo — ver {@link BackgroundCompute}.
+ * @param options - Logger/signal/store opcionais — ver {@link QueueBackgroundOptions}.
+ * @returns Um dispatcher fire-and-forget para injetar em {@link CacheFirstExtractionOptions.background}.
+ * @example
+ * const background = makeQueueBackgroundExtractor(async (target) => {
+ *   const map = await extractIssueAttachments(http, single, { store, registry, instanceUrl });
+ *   return map.get(target.attachment.id) ?? processingResult();
+ * }, { store });
+ */
+export function makeQueueBackgroundExtractor(compute, options = {}) {
+    const { logger, signal, store } = options;
+    // Registro de jobs em andamento por chave serializada: dedup de disparo (#71).
+    const inFlight = new Map();
+    return (target) => {
+        const keyId = serializeCacheKey(target.key);
+        // Dedup: se já há um job em andamento para esta chave, não dispara outro —
+        // reusa o existente (evita reprocessar o mesmo anexo em chamadas concorrentes).
+        if (inFlight.has(keyId)) {
+            return;
+        }
+        const job = {
+            id: `attachment:${target.attachment.id}`,
+            run: (context) => compute(target, context.signal),
+        };
+        const queueOptions = {
+            ...(logger !== undefined ? { logger } : {}),
+            ...(signal !== undefined ? { signal } : {}),
+        };
+        // Fire-and-forget: consome as transições em segundo plano (persistindo o
+        // resultado de fechamento no `store`, #71); NUNCA bloqueia nem relança (a
+        // resposta MCP já voltou com `processing`). Ao concluir, libera a chave.
+        const settled = drainDetached(runQueue([job], queueOptions), target, logger, store).finally(() => {
+            inFlight.delete(keyId);
+        });
+        inFlight.set(keyId, settled);
+        void settled;
+    };
+}

package/dist/client/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Erros tipados do client HTTP do Redmine (ADR-003).
+ *
+ * Union por classe (instanceof + `status`) — o mais simples para o M1.
+ * Nenhuma mensagem carrega a api_key: a redação acontece na camada de request
+ * (ver `redactSecret` em `./http.ts`) antes de qualquer texto chegar aqui.
+ */
+/** Erro base de qualquer resposta HTTP ≥ 400 do Redmine. */
+export declare class RedmineHttpError extends Error {
+    /** Código HTTP da resposta (ex.: 500). */
+    readonly status: number;
+    /** URL já redigida (sem api_key) — segura para log. */
+    readonly url: string;
+    constructor(message: string, status: number, url: string);
+}
+/** 401 — api_key ausente/inválida. */
+export declare class RedmineAuthError extends RedmineHttpError {
+}
+/** 403 — autenticado, porém sem permissão para o recurso. */
+export declare class RedmineForbiddenError extends RedmineHttpError {
+}
+/** 404 — recurso inexistente. */
+export declare class RedmineNotFoundError extends RedmineHttpError {
+}
+/**
+ * Mapeia um status HTTP para a classe de erro correspondente.
+ *
+ * @param message - Mensagem já redigida (sem segredos).
+ * @param status - Código HTTP da resposta.
+ * @param url - URL já redigida (sem api_key).
+ * @returns Instância do erro tipado adequado ao status.
+ */
+export declare function httpErrorFor(message: string, status: number, url: string): RedmineHttpError;

package/dist/client/errors.js

@@ -0,0 +1,49 @@
+/**
+ * Erros tipados do client HTTP do Redmine (ADR-003).
+ *
+ * Union por classe (instanceof + `status`) — o mais simples para o M1.
+ * Nenhuma mensagem carrega a api_key: a redação acontece na camada de request
+ * (ver `redactSecret` em `./http.ts`) antes de qualquer texto chegar aqui.
+ */
+/** Erro base de qualquer resposta HTTP ≥ 400 do Redmine. */
+export class RedmineHttpError extends Error {
+    /** Código HTTP da resposta (ex.: 500). */
+    status;
+    /** URL já redigida (sem api_key) — segura para log. */
+    url;
+    constructor(message, status, url) {
+        super(message);
+        this.name = new.target.name;
+        this.status = status;
+        this.url = url;
+    }
+}
+/** 401 — api_key ausente/inválida. */
+export class RedmineAuthError extends RedmineHttpError {
+}
+/** 403 — autenticado, porém sem permissão para o recurso. */
+export class RedmineForbiddenError extends RedmineHttpError {
+}
+/** 404 — recurso inexistente. */
+export class RedmineNotFoundError extends RedmineHttpError {
+}
+/**
+ * Mapeia um status HTTP para a classe de erro correspondente.
+ *
+ * @param message - Mensagem já redigida (sem segredos).
+ * @param status - Código HTTP da resposta.
+ * @param url - URL já redigida (sem api_key).
+ * @returns Instância do erro tipado adequado ao status.
+ */
+export function httpErrorFor(message, status, url) {
+    switch (status) {
+        case 401:
+            return new RedmineAuthError(message, status, url);
+        case 403:
+            return new RedmineForbiddenError(message, status, url);
+        case 404:
+            return new RedmineNotFoundError(message, status, url);
+        default:
+            return new RedmineHttpError(message, status, url);
+    }
+}

package/dist/client/http.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Client HTTP base do Redmine — autenticação por api_key e TLS obrigatório (ADR-003).
+ *
+ * `GET` (JSON) com retry/backoff exponencial (issue #10) para 429/5xx/erros de
+ * rede, mais `getBinary` (download bruto de anexos, issue #48) que herda a mesma
+ * auth/TLS/retry sem parse JSON. Sem paginação ou timeout sofisticado (issue #9).
+ * Usa `fetch` nativo do Node ≥ 20, sem dependência nova.
+ */
+/** Logger mínimo — só o nível de aviso é necessário neste módulo. */
+export interface Logger {
+    warn(message: string): void;
+}
+/** Parâmetros de query aceitos por uma requisição GET. */
+export type QueryParams = Record<string, string | number | boolean>;
+/**
+ * Ajustes do retry com backoff exponencial (issue #10). Só se aplica a falhas
+ * transientes: 429, 5xx e erros de rede. Erros 4xx (exceto 429) nunca retentam.
+ */
+export interface RetryOptions {
+    /** Número máximo de tentativas (inclui a primeira). Default: 3; mínimo 1. */
+    maxAttempts?: number;
+    /** Atraso base em ms para o backoff exponencial (`base * 2^tentativa`). Default: 250. */
+    baseDelayMs?: number;
+}
+/** Opções de construção do client HTTP. */
+export interface HttpClientOptions {
+    /** URL base da instância Redmine (ex.: `https://redmine.example`). */
+    baseUrl: string;
+    /** api_key do usuário — enviada por header (ou query, ver `keyInQuery`). */
+    apiKey: string;
+    /**
+     * Envia a api_key como `?key=` em vez do header `X-Redmine-API-Key`.
+     * Fallback explícito para proxies que removem headers (ADR-003). Default: `false`.
+     */
+    keyInQuery?: boolean;
+    /**
+     * Permite `http://` (sem TLS). Opt-in explícito e ruidoso: emite um `warn`.
+     * Default: `false` (só `https://` é aceito).
+     */
+    insecure?: boolean;
+    /** Logger para avisos; default no-op (não introduz lib de logging no M1). */
+    logger?: Logger;
+    /** Política de retry para falhas transientes. Ver {@link RetryOptions}. */
+    retry?: RetryOptions;
+}
+/** Client HTTP do core — expõe `get` (JSON) e `getBinary` (download bruto). */
+export interface HttpClient {
+    /**
+     * Executa `GET {baseUrl}{path}` com autenticação e retorna o JSON já parseado.
+     *
+     * @param path - Caminho absoluto na API (ex.: `/issues/100.json`).
+     * @param params - Parâmetros de query opcionais.
+     * @returns Corpo da resposta parseado como JSON.
+     * @throws {RedmineAuthError} Em 401.
+     * @throws {RedmineForbiddenError} Em 403.
+     * @throws {RedmineNotFoundError} Em 404.
+     * @throws {RedmineHttpError} Em qualquer outro status ≥ 400.
+     */
+    get(path: string, params?: QueryParams): Promise<unknown>;
+    /**
+     * Executa `GET {baseUrl}{path}` autenticado e retorna o corpo BRUTO como um
+     * stream de bytes, SEM parse JSON — usado para baixar anexos (M3-06, ADR-004).
+     *
+     * Reusa a mesma autenticação, política de TLS e retry/backoff transiente de
+     * {@link get}; os erros são os mesmos tipos ({@link RedmineHttpError} e
+     * subclasses). O chamador é responsável por consumir/encerrar o stream.
+     *
+     * @param path - Caminho absoluto na API (ex.: `/attachments/download/7/foo.png`).
+     * @param params - Parâmetros de query opcionais.
+     * @returns Stream de leitura dos bytes da resposta.
+     * @throws {RedmineAuthError} Em 401.
+     * @throws {RedmineForbiddenError} Em 403.
+     * @throws {RedmineNotFoundError} Em 404.
+     * @throws {RedmineHttpError} Em qualquer outro status ≥ 400.
+     * @throws {Error} Se a resposta vier sem corpo.
+     */
+    getBinary(path: string, params?: QueryParams): Promise<ReadableStream<Uint8Array>>;
+}
+/**
+ * Remove qualquer ocorrência da api_key (em texto ou em `?key=`) de uma string.
+ * Garante que nenhum segredo vaze para mensagens de erro ou logs (ADR-003).
+ *
+ * @param text - Texto potencialmente contendo o segredo.
+ * @param apiKey - Segredo a redigir.
+ * @returns Texto com o segredo substituído por `[REDACTED]`.
+ */
+export declare function redactSecret(text: string, apiKey: string): string;
+/**
+ * Valida o esquema da URL base conforme a política de TLS do ADR-003.
+ *
+ * Exportada para ser reutilizada por outros fluxos de autenticação (ex.: login
+ * por senha em `config/login.ts`), evitando duplicar a política de TLS.
+ *
+ * @param baseUrl - URL base a validar.
+ * @param insecure - Se `true`, permite `http://` com aviso ruidoso.
+ * @param logger - Logger para o aviso de conexão insegura.
+ * @throws {Error} Se `http://` for usado sem `insecure`, ou se o esquema for inválido.
+ */
+export declare function validateBaseUrl(baseUrl: string, insecure: boolean, logger: Logger): void;
+/**
+ * Cria um client HTTP autenticado para uma instância Redmine.
+ *
+ * @param options - Configuração do client (ver {@link HttpClientOptions}).
+ * @returns Um {@link HttpClient} com o método `get`.
+ * @throws {Error} Se `apiKey` for vazia ou a política de TLS for violada.
+ * @example
+ * const client = createHttpClient({ baseUrl: 'https://redmine.example', apiKey: KEY });
+ * const issue = await client.get('/issues/100.json');
+ */
+export declare function createHttpClient(options: HttpClientOptions): HttpClient;

package/dist/client/http.js

@@ -0,0 +1,207 @@
+/**
+ * Client HTTP base do Redmine — autenticação por api_key e TLS obrigatório (ADR-003).
+ *
+ * `GET` (JSON) com retry/backoff exponencial (issue #10) para 429/5xx/erros de
+ * rede, mais `getBinary` (download bruto de anexos, issue #48) que herda a mesma
+ * auth/TLS/retry sem parse JSON. Sem paginação ou timeout sofisticado (issue #9).
+ * Usa `fetch` nativo do Node ≥ 20, sem dependência nova.
+ */
+import { httpErrorFor } from './errors.js';
+/** Header do Redmine para autenticação por api_key (ADR-003). */
+const API_KEY_HEADER = 'X-Redmine-API-Key';
+/** Placeholder usado ao redigir segredos em mensagens/logs. */
+const REDACTED = '[REDACTED]';
+const noopLogger = { warn: () => undefined };
+/** Tentativas default quando `retry.maxAttempts` não é informado. */
+const DEFAULT_MAX_ATTEMPTS = 3;
+/** Atraso base (ms) default do backoff quando `retry.baseDelayMs` não é informado. */
+const DEFAULT_BASE_DELAY_MS = 250;
+/** Aguarda `ms` milissegundos; isolado num `setTimeout` para ser mockável com fake timers. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Indica se um status HTTP é transiente e merece nova tentativa.
+ * Retentam: 429 (throttling) e 5xx (falha do servidor). Demais 4xx são definitivos.
+ *
+ * @param status - Código HTTP da resposta.
+ * @returns `true` se vale a pena retentar.
+ */
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+/**
+ * Calcula o atraso do backoff exponencial com jitter para a tentativa `attempt` (0-based).
+ * `baseDelay * 2^attempt` mais um jitter aleatório pequeno para evitar thundering herd.
+ *
+ * @param attempt - Índice da tentativa já realizada (0 na primeira falha).
+ * @param baseDelayMs - Atraso base em milissegundos.
+ * @returns Atraso, em milissegundos, antes da próxima tentativa.
+ */
+function backoffDelay(attempt, baseDelayMs) {
+    const exponential = baseDelayMs * 2 ** attempt;
+    const jitter = Math.random() * baseDelayMs;
+    return exponential + jitter;
+}
+/**
+ * Remove qualquer ocorrência da api_key (em texto ou em `?key=`) de uma string.
+ * Garante que nenhum segredo vaze para mensagens de erro ou logs (ADR-003).
+ *
+ * @param text - Texto potencialmente contendo o segredo.
+ * @param apiKey - Segredo a redigir.
+ * @returns Texto com o segredo substituído por `[REDACTED]`.
+ */
+export function redactSecret(text, apiKey) {
+    let out = text;
+    if (apiKey.length > 0) {
+        out = out.split(apiKey).join(REDACTED);
+        // URLs são percent-encoded: uma key com caracteres URL-unsafe não casaria
+        // com a forma bruta acima.
+        const encoded = encodeURIComponent(apiKey);
+        if (encoded !== apiKey) {
+            out = out.split(encoded).join(REDACTED);
+        }
+    }
+    // Redige também o valor de `key=` na querystring, caso a URL tenha sido montada
+    // com um segredo diferente do informado (defesa em profundidade).
+    return out.replace(/([?&]key=)[^&#\s]+/gi, `$1${REDACTED}`);
+}
+/**
+ * Valida o esquema da URL base conforme a política de TLS do ADR-003.
+ *
+ * Exportada para ser reutilizada por outros fluxos de autenticação (ex.: login
+ * por senha em `config/login.ts`), evitando duplicar a política de TLS.
+ *
+ * @param baseUrl - URL base a validar.
+ * @param insecure - Se `true`, permite `http://` com aviso ruidoso.
+ * @param logger - Logger para o aviso de conexão insegura.
+ * @throws {Error} Se `http://` for usado sem `insecure`, ou se o esquema for inválido.
+ */
+export function validateBaseUrl(baseUrl, insecure, logger) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`baseUrl inválida: "${baseUrl}". Informe uma URL absoluta (ex.: https://redmine.example).`);
+    }
+    if (parsed.protocol === 'https:') {
+        return;
+    }
+    if (parsed.protocol === 'http:') {
+        if (!insecure) {
+            throw new Error(`Conexão http:// recusada para "${parsed.origin}": TLS é obrigatório. ` +
+                `Use https:// ou, para uma CA interna, configure NODE_EXTRA_CA_CERTS. ` +
+                `Para ignorar a verificação (NÃO recomendado), passe insecure: true.`);
+        }
+        logger.warn(`AVISO DE SEGURANÇA: conexão insegura (http://) habilitada para "${parsed.origin}". ` +
+            `O tráfego, incluindo a api_key, NÃO é criptografado.`);
+        return;
+    }
+    throw new Error(`Esquema não suportado em baseUrl: "${parsed.protocol}". Use https://.`);
+}
+/**
+ * Cria um client HTTP autenticado para uma instância Redmine.
+ *
+ * @param options - Configuração do client (ver {@link HttpClientOptions}).
+ * @returns Um {@link HttpClient} com o método `get`.
+ * @throws {Error} Se `apiKey` for vazia ou a política de TLS for violada.
+ * @example
+ * const client = createHttpClient({ baseUrl: 'https://redmine.example', apiKey: KEY });
+ * const issue = await client.get('/issues/100.json');
+ */
+export function createHttpClient(options) {
+    const { baseUrl, apiKey, keyInQuery = false, insecure = false } = options;
+    const logger = options.logger ?? noopLogger;
+    const maxAttempts = Math.max(1, options.retry?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+    const baseDelayMs = options.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    if (apiKey.length === 0) {
+        throw new Error('apiKey é obrigatória e não pode ser vazia.');
+    }
+    validateBaseUrl(baseUrl, insecure, logger);
+    const redact = (text) => redactSecret(text, apiKey);
+    /**
+     * Monta a URL final da requisição, aplicando params e (se configurado) `?key=`.
+     */
+    const buildUrl = (path, params) => {
+        const url = new URL(path, baseUrl);
+        if (params) {
+            for (const [name, value] of Object.entries(params)) {
+                url.searchParams.set(name, String(value));
+            }
+        }
+        if (keyInQuery) {
+            url.searchParams.set('key', apiKey);
+        }
+        return url;
+    };
+    /**
+     * Executa a requisição `GET` com autenticação e retry transiente, devolvendo a
+     * `Response` já validada (status < 400) mais a URL redigida para mensagens de
+     * erro. Compartilhado por {@link HttpClient.get} (JSON) e
+     * {@link HttpClient.getBinary} (bytes), para que ambos herdem a MESMA política
+     * de auth/TLS/retry e os mesmos erros tipados (issue #10, #48).
+     *
+     * @param path - Caminho absoluto na API.
+     * @param params - Parâmetros de query opcionais.
+     * @param accept - Valor do header Accept (JSON, ou coringa para binário).
+     * @returns A resposta bem-sucedida e a URL já redigida (sem a api_key).
+     */
+    const requestWithRetry = async (path, params, accept) => {
+        const url = buildUrl(path, params);
+        // URL segura para log/erro: a api_key nunca aparece em texto.
+        const safeUrl = redact(url.toString());
+        const headers = { Accept: accept };
+        if (!keyInQuery) {
+            headers[API_KEY_HEADER] = apiKey;
+        }
+        // Retry com backoff exponencial: só falhas transientes (429/5xx/rede) retentam.
+        // `attempt` é 0-based; a última tentativa (attempt === maxAttempts - 1) sempre
+        // propaga o erro tipado original, sem embrulhar (issue #10).
+        for (let attempt = 0;; attempt++) {
+            const lastAttempt = attempt >= maxAttempts - 1;
+            let response;
+            try {
+                response = await fetch(url, { method: 'GET', headers });
+            }
+            catch (cause) {
+                if (!lastAttempt) {
+                    await sleep(backoffDelay(attempt, baseDelayMs));
+                    continue;
+                }
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                throw new Error(`Falha de rede ao acessar ${safeUrl}: ${redact(reason)}`);
+            }
+            if (!response.ok) {
+                if (isRetryableStatus(response.status) && !lastAttempt) {
+                    await sleep(backoffDelay(attempt, baseDelayMs));
+                    continue;
+                }
+                const message = `GET ${safeUrl} respondeu ${response.status} ${redact(response.statusText)}`;
+                const error = httpErrorFor(message, response.status, safeUrl);
+                throw error;
+            }
+            return { response, safeUrl };
+        }
+    };
+    return {
+        async get(path, params) {
+            const { response, safeUrl } = await requestWithRetry(path, params, 'application/json');
+            try {
+                return (await response.json());
+            }
+            catch (cause) {
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                throw new Error(`Resposta de ${safeUrl} não é JSON válido: ${redact(reason)}`);
+            }
+        },
+        async getBinary(path, params) {
+            const { response, safeUrl } = await requestWithRetry(path, params, '*/*');
+            // Uma resposta 2xx sem corpo (ex.: 204) não tem o que baixar.
+            if (response.body === null) {
+                throw new Error(`Resposta binária de ${safeUrl} veio sem corpo.`);
+            }
+            return response.body;
+        },
+    };
+}

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+export declare const MODULE_NAME: "client";
+export { createHttpClient, redactSecret, validateBaseUrl, type HttpClient, type HttpClientOptions, type Logger, type QueryParams, type RetryOptions, } from './http.js';
+export { RedmineHttpError, RedmineAuthError, RedmineForbiddenError, RedmineNotFoundError, httpErrorFor, } from './errors.js';
+export { getIssue, listIssues, type RedmineIssuePayload, type ListIssuesOptions, } from './issues.js';
+export { searchIssues, SEARCH_MAX_LIMIT, type SearchIssuesOptions, type SearchIssuesPage, type RedmineSearchHit, } from './search.js';

package/dist/client/index.js

@@ -0,0 +1,5 @@
+export const MODULE_NAME = 'client';
+export { createHttpClient, redactSecret, validateBaseUrl, } from './http.js';
+export { RedmineHttpError, RedmineAuthError, RedmineForbiddenError, RedmineNotFoundError, httpErrorFor, } from './errors.js';
+export { getIssue, listIssues, } from './issues.js';
+export { searchIssues, SEARCH_MAX_LIMIT, } from './search.js';