@ecosplay/e-brocante 1.0.2

package/src/http/HttpClient.ts

@@ -0,0 +1,266 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import type { CacheBackend } from '../cache/CacheBackend.js';
+import { stableHashKey } from '../cache/stableHashKey.js';
+import {
+    AuthenticationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+} from '../exceptions/index.js';
+import { stringifyPrimitive, trimLeadingSlash, trimTrailingSlash } from '../internal/safeStrings.js';
+import type { DebugWriter } from '../logger/DebugWriter.js';
+import type { Logger } from '../logger/Logger.js';
+import type { Mode, RequestOptions } from '../types.js';
+
+export const SDK_VERSION = '1.0.2';
+
+export interface HttpClientDeps {
+    apiKey: string;
+    brocEmail: string;
+    mode: Mode;
+    baseUrl: string;
+    timeoutMs: number;
+    cache: CacheBackend;
+    logger: Logger;
+    debugWriter: DebugWriter | null;
+    maxRetries: number;
+    fetchImpl: typeof fetch;
+}
+
+/** @internal */
+export class HttpClient {
+    constructor(private readonly deps: HttpClientDeps) {}
+
+    get cache(): CacheBackend {
+        return this.deps.cache;
+    }
+
+    async get(
+        endpoint: string,
+        query: Record<string, unknown> = {},
+        opts: RequestOptions = {},
+    ): Promise<Record<string, unknown>> {
+        const path = this.buildPath(endpoint);
+        const cacheKey = this.makeCacheKey(endpoint, query);
+        const skipCache = opts.skipCache === true;
+
+        if (!skipCache) {
+            const cached = await this.deps.cache.get(cacheKey);
+            if (cached !== null && cached !== undefined) {
+                this.deps.logger.debug('cache hit', { endpoint, key: cacheKey });
+                this.deps.debugWriter?.log(`GET ${path}`, { cache: 'hit', key: cacheKey });
+                return cached as Record<string, unknown>;
+            }
+        }
+
+        const url = `${trimTrailingSlash(this.deps.baseUrl)}${path}${this.encodeQuery(query)}`;
+        const start = performance.now();
+        const response = await this.sendWithRetry(url);
+        const durationMs = Math.round(performance.now() - start);
+
+        const body = await response.text();
+        const payload = this.decode(body);
+
+        const reqId = response.headers.get('x-request-id');
+        this.deps.logger.info('api call', {
+            method: 'GET',
+            endpoint,
+            mode: this.deps.mode,
+            status: response.status,
+            duration_ms: durationMs,
+            cached: false,
+            request_id: reqId,
+        });
+        this.deps.debugWriter?.log(`GET ${path}${this.encodeQuery(query)} -> ${response.status}`, {
+            ms: durationMs,
+            cache: 'miss',
+            req: reqId,
+        });
+
+        if (!skipCache) {
+            await this.deps.cache.set(cacheKey, payload, opts.ttl);
+            this.deps.debugWriter?.log('cache.set', { key: cacheKey, ttl: opts.ttl ?? 'default' });
+        }
+
+        return payload;
+    }
+
+    makeCacheKey(endpoint: string, query: Record<string, unknown>): string {
+        return `${this.deps.mode}:${stableHashKey(endpoint, { ...query, _broc: this.deps.brocEmail })}`;
+    }
+
+    private buildPath(endpoint: string): string {
+        return `/api/${this.deps.mode}/${trimLeadingSlash(endpoint)}`;
+    }
+
+    private encodeQuery(query: Record<string, unknown>): string {
+        const parts: string[] = [];
+        for (const [k, v] of Object.entries(query)) {
+            if (v === null || v === undefined || v === '') continue;
+            const value = stringifyPrimitive(v);
+            parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(value)}`);
+        }
+        return parts.length === 0 ? '' : `?${parts.join('&')}`;
+    }
+
+    private async sendWithRetry(url: string): Promise<Response> {
+        let attempt = 0;
+        while (true) {
+            attempt++;
+            const response = await this.attemptOrRetryConnect(url, attempt);
+            if (response === null) continue;
+
+            if (response.status >= 200 && response.status < 300) {
+                return response;
+            }
+
+            if (this.shouldRetryStatus(response.status, attempt)) {
+                await this.applyRetryDelay(response, response.status, attempt);
+                continue;
+            }
+
+            throw await this.buildHttpError(response);
+        }
+    }
+
+    private async attemptOrRetryConnect(url: string, attempt: number): Promise<Response | null> {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), this.deps.timeoutMs);
+        let response: Response;
+        try {
+            response = await this.deps.fetchImpl(url, {
+                method: 'GET',
+                headers: {
+                    'X-KEY': this.deps.apiKey,
+                    'X-BROC': this.deps.brocEmail,
+                    Accept: 'application/json',
+                    'User-Agent': `e-brocante-js/${SDK_VERSION} (Node/Bun)`,
+                },
+                signal: ac.signal,
+            });
+        } catch (cause) {
+            clearTimeout(timer);
+            return this.handleConnectError(cause, attempt);
+        }
+        clearTimeout(timer);
+        return response;
+    }
+
+    private async handleConnectError(cause: unknown, attempt: number): Promise<null> {
+        const message = errorMessage(cause);
+        if (attempt > this.deps.maxRetries) {
+            this.deps.logger.error('connection failed (gave up)', { attempt, error: message });
+            throw new NetworkError(`Connection failed after ${this.deps.maxRetries} retries: ${message}`, {
+                cause,
+            });
+        }
+        this.deps.logger.warn('connection failed, retrying', { attempt, error: message });
+        await this.sleepBackoff(attempt);
+        return null;
+    }
+
+    private shouldRetryStatus(status: number, attempt: number): boolean {
+        return (status === 429 || status >= 500) && attempt <= this.deps.maxRetries;
+    }
+
+    private async applyRetryDelay(response: Response, status: number, attempt: number): Promise<void> {
+        const retryAfter = Number(response.headers.get('retry-after') ?? 0);
+        this.deps.logger.warn('retryable status, retrying', {
+            status,
+            attempt,
+            retry_after: retryAfter,
+        });
+        this.deps.debugWriter?.log('retry', { attempt, status, retry_after: retryAfter });
+        if (retryAfter > 0) {
+            await sleep(Math.min(retryAfter, 30) * 1000);
+            return;
+        }
+        await this.sleepBackoff(attempt);
+    }
+
+    private async buildHttpError(response: Response): Promise<Error> {
+        const body = await response.text();
+        const message = this.extractErrorMessage(body) ?? `HTTP ${response.status}`;
+        this.deps.logger.error('api error', { status: response.status, message });
+        this.deps.debugWriter?.log('error', { status: response.status, message });
+
+        const status = response.status;
+        if (status === 401 || status === 403) return new AuthenticationError(message, status);
+        if (status === 404 || status === 410) return new NotFoundError(message, status);
+        if (status === 422) return new ValidationError(message, status, body);
+        if (status === 429) {
+            const retryAfter = response.headers.get('retry-after');
+            return new RateLimitError(message, status, retryAfter ? Number(retryAfter) : 0);
+        }
+        return new ServerError(message, status);
+    }
+
+    private async sleepBackoff(attempt: number): Promise<void> {
+        // Exponential backoff with jitter (0.5s -> 1s -> 2s -> 4s …, capped at 30s).
+        const base = Math.min(0.5 * 2 ** (attempt - 1), 30);
+        const jitter = secureJitter() / 1000;
+        await sleep((base + jitter) * 1000);
+    }
+
+    private decode(body: string): Record<string, unknown> {
+        if (body === '') return {};
+        let decoded: unknown;
+        try {
+            decoded = JSON.parse(body);
+        } catch (cause) {
+            throw new ServerError(`Invalid JSON response: ${(cause as Error).message}`, 0, { cause });
+        }
+        if (decoded === null || typeof decoded !== 'object' || Array.isArray(decoded)) {
+            throw new ServerError('Unexpected JSON response (not an object)', 0);
+        }
+        return decoded as Record<string, unknown>;
+    }
+
+    private extractErrorMessage(body: string): string | null {
+        if (body === '') return null;
+        let decoded: unknown;
+        try {
+            decoded = JSON.parse(body);
+        } catch {
+            decoded = null;
+        }
+
+        let candidate: unknown = null;
+        if (decoded && typeof decoded === 'object') {
+            const d = decoded as Record<string, unknown>;
+            const errs = d.errors;
+            if (Array.isArray(errs) && errs[0] && typeof errs[0] === 'object') {
+                const first = errs[0] as Record<string, unknown>;
+                candidate = first.title;
+            }
+            if (typeof candidate !== 'string') {
+                candidate = d.message;
+            }
+        }
+        return typeof candidate === 'string' ? candidate : null;
+    }
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function errorMessage(cause: unknown): string {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+
+function secureJitter(): number {
+    // 0..250 ms, derived from a CSPRNG to satisfy SonarQube S2245.
+    const buf = new Uint32Array(1);
+    crypto.getRandomValues(buf);
+    const raw = buf[0];
+    /* v8 ignore next — buf[0] is always populated by getRandomValues */
+    if (raw === undefined) return 0;
+    return Math.floor(raw % 251);
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * e-brocante JavaScript / TypeScript SDK — public entry point
+ *
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+export { EBrocanteClient } from './EBrocanteClient.js';
+
+export type {
+    EBrocanteClientOptions,
+    EventFilters,
+    OrgaFilters,
+    Mode,
+    CacheType,
+    RequestOptions,
+} from './types.js';
+
+export type { CacheBackend } from './cache/CacheBackend.js';
+export { LocalCache } from './cache/LocalCache.js';
+export { NullCache } from './cache/NullCache.js';
+export { RedisCache, type RedisLikeClient } from './cache/RedisCache.js';
+export { type RedisConfig, DEFAULT_REDIS_CONFIG } from './cache/RedisConfig.js';
+
+export type { Logger, LogLevel } from './logger/Logger.js';
+export { NullLogger } from './logger/NullLogger.js';
+export { FileLogger } from './logger/FileLogger.js';
+export { DebugWriter } from './logger/DebugWriter.js';
+
+export {
+    EBrocanteError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    NetworkError,
+} from './exceptions/index.js';
+
+export type { EventDto } from './models/Event.js';
+export type { OrgaDto } from './models/Orga.js';
+export { PaginatedResult, type PaginationMeta } from './models/PaginatedResult.js';

package/src/internal/safeStrings.ts

@@ -0,0 +1,154 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ *
+ * Hand-rolled string helpers used in place of unbounded regular
+ * expressions so that no input can trigger super-linear runtime
+ * (SonarQube rule S5852 / ReDoS). Every loop here is strictly O(n).
+ *
+ * @internal
+ */
+
+const SLASH = 0x2f;
+const AT = 0x40;
+const DOT = 0x2e;
+const SPACE = 0x20;
+const TAB = 0x09;
+const LF = 0x0a;
+const CR = 0x0d;
+const MAX_EMAIL_LENGTH = 254;
+
+/** Strip every leading `/` from a string. O(n). */
+export function trimLeadingSlash(s: string): string {
+    let i = 0;
+    while (i < s.length && s.codePointAt(i) === SLASH) i++;
+    return i === 0 ? s : s.slice(i);
+}
+
+/** Strip every trailing `/` from a string. O(n). */
+export function trimTrailingSlash(s: string): string {
+    let end = s.length;
+    while (end > 0 && s.codePointAt(end - 1) === SLASH) end--;
+    return end === s.length ? s : s.slice(0, end);
+}
+
+/** Strip leading AND trailing `/`. O(n). */
+export function trimSlashes(s: string): string {
+    return trimTrailingSlash(trimLeadingSlash(s));
+}
+
+/** Replace every `/` with `.`. O(n). */
+export function slashesToDots(s: string): string {
+    return s.replaceAll('/', '.');
+}
+
+/** Coerce an unknown value to a string, falling back when it isn't one. */
+export function asString(v: unknown, fallback = ''): string {
+    return typeof v === 'string' ? v : fallback;
+}
+
+/** Coerce an unknown value to a finite number, falling back when it isn't. */
+export function asNumber(v: unknown, fallback = 0): number {
+    if (typeof v === 'number' && Number.isFinite(v)) return v;
+    if (typeof v === 'string' && v !== '') {
+        const n = Number(v);
+        if (Number.isFinite(n)) return n;
+    }
+    return fallback;
+}
+
+/** Coerce an unknown value to a boolean (truthy primitives only). */
+export function asBoolean(v: unknown): boolean {
+    return v === true || v === 'true' || v === 1 || v === '1';
+}
+
+/** Returns the string value when truthy, otherwise null. */
+export function asNullableString(v: unknown): string | null {
+    return typeof v === 'string' && v !== '' ? v : null;
+}
+
+/** Parse an ISO-8601 string into a Date, returning null on garbage. */
+export function asDate(v: unknown): Date | null {
+    if (typeof v !== 'string' || v === '') return null;
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * Coerce an unknown value to a plain record. Returns an empty record
+ * on null, undefined, primitives, or arrays — never throws.
+ */
+export function asRecord(v: unknown): Record<string, unknown> {
+    if (v === null || v === undefined) return {};
+    if (typeof v !== 'object') return {};
+    if (Array.isArray(v)) return {};
+    return v as Record<string, unknown>;
+}
+
+/**
+ * Coerce an unknown value to an integer, returning null when the input
+ * is empty, missing or not finite (vs. asNumber which falls back to 0).
+ */
+export function asNullableInt(v: unknown): number | null {
+    if (v === null || v === undefined || v === '') return null;
+    const n = asNumber(v, Number.NaN);
+    return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Stringify a primitive value for use in URL query strings or cache keys.
+ * Refuses non-primitive values (objects, arrays, functions) to avoid the
+ * `[object Object]` foot-gun that `String(v)` produces for them.
+ */
+export function stringifyPrimitive(v: unknown): string {
+    if (v === null || v === undefined) return '';
+    if (typeof v === 'string') return v;
+    if (typeof v === 'number' || typeof v === 'bigint') return String(v);
+    if (typeof v === 'boolean') return v ? 'true' : 'false';
+    throw new TypeError(`Cannot stringify ${typeof v} value as a query/cache parameter.`);
+}
+
+function isWhitespaceCode(code: number | undefined): boolean {
+    return code === SPACE || code === TAB || code === LF || code === CR;
+}
+
+/** Find the index of `@` in a single forward scan, returning -1 on failure
+ *  (no `@`, multiple `@`, or any whitespace anywhere). */
+function findSingleAt(value: string): number {
+    let at = -1;
+    for (let i = 0; i < value.length; i++) {
+        const c = value.codePointAt(i);
+        if (isWhitespaceCode(c)) return -1;
+        if (c === AT) {
+            if (at !== -1) return -1; // more than one '@'
+            at = i;
+        }
+    }
+    return at;
+}
+
+/** Validate the domain part has a valid dot (not at the boundary). */
+function hasInteriorDot(domain: string): boolean {
+    for (let i = 0; i < domain.length; i++) {
+        if (domain.codePointAt(i) === DOT) {
+            // Reject leading dot, trailing dot.
+            if (i === 0 || i === domain.length - 1) return false;
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Strict, ReDoS-safe email validator. Constant-time wrt structure
+ * (single forward scan + a couple of bounded slices). Intentionally
+ * conservative — accepts the same shape as `/^[^@\s]+@[^@\s]+\.[^@\s]+$/`
+ * but with explicit upper bounds.
+ */
+export function isValidEmail(value: string): boolean {
+    const len = value.length;
+    if (len === 0 || len > MAX_EMAIL_LENGTH) return false;
+    const at = findSingleAt(value);
+    if (at < 1 || at >= len - 1) return false;
+    return hasInteriorDot(value.slice(at + 1));
+}

package/src/logger/DebugWriter.ts

@@ -0,0 +1,61 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { EBrocanteError } from '../exceptions/index.js';
+
+/**
+ * Plain-text debug writer. Appends ONE LINE per SDK action to a file
+ * (default: `./DEBUG.TXT`). Designed for `tail -f DEBUG.TXT` during
+ * development; not intended for production observability — use
+ * FileLogger or a custom Logger for that.
+ *
+ * Output format:
+ *   [2026-05-10 19:30:01.123] GET /api/prod/events?city=Paris -> 200 ms=45 cache=miss req=req_xxx
+ *   [2026-05-10 19:30:01.456] cache.set key=events.list:abc ttl=300
+ *   [2026-05-10 19:30:05.789] GET /api/prod/events?city=Paris cache=hit
+ *   [2026-05-10 19:31:10.001] retry attempt=2 status=429 retry_after=3
+ *   [2026-05-10 19:32:00.555] error status=401 message="HTTP 401"
+ */
+export class DebugWriter {
+    constructor(public readonly file: string = 'DEBUG.TXT') {
+        const dir = dirname(file);
+        if (dir && dir !== '.' && !existsSync(dir)) {
+            /* v8 ignore start — fs error mid-process (full disk, EROFS) */
+            try {
+                mkdirSync(dir, { recursive: true, mode: 0o755 });
+            } catch (cause) {
+                throw new EBrocanteError(`Cannot create debug directory: ${dir}`, { cause });
+            }
+            /* v8 ignore stop */
+        }
+    }
+
+    log(action: string, fields: Record<string, unknown> = {}): void {
+        const parts: string[] = [];
+        for (const [k, v] of Object.entries(fields)) {
+            if (v === null || v === undefined || v === '') continue;
+            parts.push(`${k}=${this.stringify(v)}`);
+        }
+
+        const ts = new Date().toISOString().replace('T', ' ').replace('Z', '').slice(0, 23);
+
+        const line = parts.length > 0 ? `[${ts}] ${action} ${parts.join(' ')}` : `[${ts}] ${action}`;
+        try {
+            appendFileSync(this.file, `${line}\n`, { mode: 0o644 });
+            /* v8 ignore start — best-effort; only triggers on fs errors */
+        } catch {
+            // swallowed
+        }
+        /* v8 ignore stop */
+    }
+
+    private stringify(v: unknown): string {
+        if (typeof v === 'boolean') return v ? 'true' : 'false';
+        const s = String(v);
+        return s.includes(' ') ? `"${s}"` : s;
+    }
+}

package/src/logger/FileLogger.ts

@@ -0,0 +1,106 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import { appendFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { EBrocanteError } from '../exceptions/index.js';
+import type { LogLevel, Logger } from './Logger.js';
+
+const LEVEL_PRIORITIES: Record<LogLevel, number> = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+
+/**
+ * File logger that appends one JSON-line per record to a date-stamped
+ * file in the configured directory. One file per UTC day:
+ * `ebrocante-YYYY-MM-DD.log`. Suitable for log shippers (Vector,
+ * Filebeat, Fluent Bit) and `tail -f` during local development.
+ *
+ * Sensitive context keys are automatically redacted (`api_key`,
+ * `X-KEY` and `Authorization` headers).
+ */
+export class FileLogger implements Logger {
+    private readonly minLevel: number;
+
+    constructor(
+        private readonly directory: string,
+        minLevel: LogLevel = 'info',
+    ) {
+        if (!directory || directory.trim() === '') {
+            throw new EBrocanteError('FileLogger directory cannot be empty');
+        }
+        if (!existsSync(directory)) {
+            /* v8 ignore start — fs error mid-process (full disk, EROFS) */
+            try {
+                mkdirSync(directory, { recursive: true, mode: 0o755 });
+            } catch (cause) {
+                throw new EBrocanteError(`Cannot create log directory: ${directory}`, { cause });
+            }
+            /* v8 ignore stop */
+        }
+        const stat = statSync(directory);
+        if (!stat.isDirectory()) {
+            throw new EBrocanteError(`Log path is not a directory: ${directory}`);
+        }
+        this.minLevel = LEVEL_PRIORITIES[minLevel];
+    }
+
+    debug(message: string, context: Record<string, unknown> = {}): void {
+        this.write('debug', message, context);
+    }
+
+    info(message: string, context: Record<string, unknown> = {}): void {
+        this.write('info', message, context);
+    }
+
+    warn(message: string, context: Record<string, unknown> = {}): void {
+        this.write('warn', message, context);
+    }
+
+    error(message: string, context: Record<string, unknown> = {}): void {
+        this.write('error', message, context);
+    }
+
+    private write(level: LogLevel, message: string, context: Record<string, unknown>): void {
+        if (LEVEL_PRIORITIES[level] < this.minLevel) return;
+
+        const entry = {
+            ts: new Date().toISOString(),
+            level,
+            message,
+            context: this.sanitize(context),
+            pid: process.pid,
+        };
+
+        const file = join(this.directory, `ebrocante-${entry.ts.slice(0, 10)}.log`);
+        try {
+            appendFileSync(file, `${JSON.stringify(entry)}\n`, { mode: 0o644 });
+            /* v8 ignore start — best-effort; only triggers on fs errors */
+        } catch {
+            // swallowed
+        }
+        /* v8 ignore stop */
+    }
+
+    private sanitize(context: Record<string, unknown>): Record<string, unknown> {
+        const out: Record<string, unknown> = { ...context };
+        if (out.headers && typeof out.headers === 'object') {
+            const headers: Record<string, unknown> = { ...(out.headers as Record<string, unknown>) };
+            for (const k of Object.keys(headers)) {
+                if (k.toLowerCase() === 'x-key' || k.toLowerCase() === 'authorization') {
+                    headers[k] = '***redacted***';
+                }
+            }
+            out.headers = headers;
+        }
+        if (typeof out.api_key === 'string') {
+            out.api_key = `${out.api_key.slice(0, 12)}***`;
+        }
+        return out;
+    }
+}

package/src/logger/Logger.ts

@@ -0,0 +1,13 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface Logger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}

package/src/logger/NullLogger.ts

@@ -0,0 +1,22 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import type { Logger } from './Logger.js';
+
+/** No-op logger used by default when no log destination is configured. */
+export class NullLogger implements Logger {
+    debug(_message: string, _context?: Record<string, unknown>): void {
+        /* intentional no-op */
+    }
+    info(_message: string, _context?: Record<string, unknown>): void {
+        /* intentional no-op */
+    }
+    warn(_message: string, _context?: Record<string, unknown>): void {
+        /* intentional no-op */
+    }
+    error(_message: string, _context?: Record<string, unknown>): void {
+        /* intentional no-op */
+    }
+}