@ecosplay/e-brocante 1.0.2

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ *
+ * Public type definitions exposed by the SDK.
+ */
+import type { CacheBackend } from './cache/CacheBackend.js';
+import type { RedisConfig } from './cache/RedisConfig.js';
+import type { Logger } from './logger/Logger.js';
+export type Mode = 'prod' | 'test';
+export type CacheType = 'local' | 'redis';
+export interface EBrocanteClientOptions {
+    /** API key (eb_prod_…, eb_test_…, eb_mock_…). */
+    apiKey: string;
+    /** Account email sent in the X-BROC header. */
+    brocEmail: string;
+    /** prod (live data) or test (sandbox). Defaults to 'prod'. */
+    mode?: Mode;
+    /** API base URL (override for the bundled mock server). */
+    baseUrl?: string;
+    /** HTTP timeout in milliseconds. Default: 10_000. */
+    timeoutMs?: number;
+    /** Enable response cache. Default: true. */
+    cache?: boolean;
+    /** Cache backend. Default: 'local'. */
+    cacheType?: CacheType;
+    /** Cache entry TTL in seconds. Default: 300. */
+    cacheTtl?: number;
+    /** Redis config (required when cacheType='redis'). */
+    cacheRedis?: RedisConfig;
+    /** Cache key prefix. Default: 'ebrocante:'. */
+    cacheKeyPrefix?: string;
+    /** Custom backend implementation (full override). */
+    cacheImpl?: CacheBackend;
+    /** Directory to write JSON-lines log files (one per day). */
+    logPath?: string;
+    /** Custom Logger implementation (overrides logPath). */
+    logger?: Logger;
+    /** Append one line per SDK action to a debug file. Default: false. */
+    debug?: boolean;
+    /** Debug file path when `debug` is true. Default: './DEBUG.TXT'. */
+    debugFile?: string;
+    /** Number of retries on 429 / 5xx. Default: 3. */
+    maxRetries?: number;
+    /** Custom fetch implementation (defaults to global fetch). */
+    fetch?: typeof fetch;
+}
+export interface EventFilters {
+    city?: string;
+    department?: string;
+    region?: string;
+    from?: string;
+    to?: string;
+    category?: string;
+    has_available_booths?: boolean;
+    outside?: boolean;
+    inside?: boolean;
+    since?: string;
+    q?: string;
+    sort?: string;
+    page?: number;
+    per_page?: number;
+    lat?: number;
+    lng?: number;
+    radius?: number;
+}
+export interface OrgaFilters {
+    city?: string;
+    legal_form?: string;
+    q?: string;
+    has_upcoming_events?: boolean;
+    since?: string;
+    sort?: string;
+    page?: number;
+    per_page?: number;
+}
+export interface RequestOptions {
+    skipCache?: boolean;
+    ttl?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AACnC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1C,MAAM,WAAW,sBAAsB;IACnC,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uCAAuC;IACvC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ *
+ * Public type definitions exposed by the SDK.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@ecosplay/e-brocante",
+  "version": "1.0.2",
+  "description": "Official JavaScript / TypeScript client for the public e-brocante.enum.fr API",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://e-brocante.enum.fr",
+  "keywords": ["brocante", "flea-market", "api", "sdk", "e-brocante", "ecosplay"],
+  "author": {
+    "name": "Association E-Cosplay",
+    "email": "contact@e-cosplay.fr",
+    "url": "https://e-cosplay.fr"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://code.e-cosplay.fr/shoko/e-brocante-js.git"
+  },
+  "bugs": {
+    "email": "contact@e-cosplay.fr",
+    "url": "https://code.e-cosplay.fr/shoko/e-brocante-js/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22",
+    "bun": ">=1.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:coverage": "vitest run --coverage",
+    "coverage:check": "node bin/check-coverage.mjs coverage/coverage-final.json 100",
+    "lint": "biome check src tests samples",
+    "lint:fix": "biome check --write src tests samples",
+    "typecheck": "tsc --noEmit",
+    "mock-api": "cd tools/mock-api && bun run src/server.ts",
+    "ci": "bun run lint && bun run typecheck && bun run test:coverage && bun run coverage:check",
+    "prepublishOnly": "bun run ci && bun run build"
+  },
+  "dependencies": {},
+  "optionalDependencies": {
+    "ioredis": "^5.4.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "ioredis": "^5.4.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/EBrocanteClient.ts

@@ -0,0 +1,110 @@
+/**
+ * e-brocante JavaScript / TypeScript SDK
+ *
+ * @copyright 2026 Association E-Cosplay
+ * @author    Association E-Cosplay <contact@e-cosplay.fr>
+ * @license   Proprietary — see LICENSE
+ *
+ * Redistribution and modification forbidden without prior written agreement.
+ * Contact: contact@e-cosplay.fr
+ */
+
+import type { CacheBackend } from './cache/CacheBackend.js';
+import { LocalCache } from './cache/LocalCache.js';
+import { NullCache } from './cache/NullCache.js';
+import { RedisCache } from './cache/RedisCache.js';
+import { HttpClient, SDK_VERSION } from './http/HttpClient.js';
+import { DebugWriter } from './logger/DebugWriter.js';
+import { FileLogger } from './logger/FileLogger.js';
+import type { Logger } from './logger/Logger.js';
+import { NullLogger } from './logger/NullLogger.js';
+import { EventsResource } from './resources/EventsResource.js';
+import { OrgaResource } from './resources/OrgaResource.js';
+import type { EBrocanteClientOptions } from './types.js';
+
+import { isValidEmail } from './internal/safeStrings.js';
+
+const DEFAULT_BASE_URL = 'https://e-brocante.enum.fr';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_CACHE_TTL = 300;
+
+/**
+ * Main client for the e-brocante.enum.fr public API.
+ *
+ *     const client = new EBrocanteClient({
+ *         apiKey: 'eb_prod_…',
+ *         brocEmail: 'orga@example.com',
+ *     });
+ *     const { data: events } = await client.events.list({ city: 'paris' });
+ *     const orga = await client.orga.get('asso-sakura');
+ */
+export class EBrocanteClient {
+    static readonly VERSION: string = SDK_VERSION;
+
+    readonly events: EventsResource;
+    readonly orga: OrgaResource;
+    readonly cache: CacheBackend;
+    readonly logger: Logger;
+    readonly mode: 'prod' | 'test';
+
+    private readonly http: HttpClient;
+
+    constructor(options: EBrocanteClientOptions) {
+        if (!options.apiKey || typeof options.apiKey !== 'string') {
+            throw new TypeError('apiKey is required and must be a string');
+        }
+        if (!options.brocEmail || !isValidEmail(options.brocEmail)) {
+            throw new TypeError(`Invalid brocEmail: '${options.brocEmail}'`);
+        }
+        const mode = options.mode ?? 'prod';
+        if (mode !== 'prod' && mode !== 'test') {
+            throw new TypeError(`mode must be 'prod' or 'test', got '${String(mode)}'`);
+        }
+        this.mode = mode;
+
+        this.cache = this.buildCache(options);
+        this.logger = this.buildLogger(options);
+        const debugWriter = options.debug === true ? new DebugWriter(options.debugFile ?? 'DEBUG.TXT') : null;
+
+        this.http = new HttpClient({
+            apiKey: options.apiKey,
+            brocEmail: options.brocEmail,
+            mode,
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            cache: this.cache,
+            logger: this.logger,
+            debugWriter,
+            maxRetries: options.maxRetries ?? 3,
+            fetchImpl: options.fetch ?? globalThis.fetch.bind(globalThis),
+        });
+
+        this.events = new EventsResource(this.http);
+        this.orga = new OrgaResource(this.http);
+    }
+
+    private buildCache(options: EBrocanteClientOptions): CacheBackend {
+        if (options.cacheImpl) return options.cacheImpl;
+        if (options.cache === false) return new NullCache();
+
+        const ttl = options.cacheTtl ?? DEFAULT_CACHE_TTL;
+        const mode = options.mode ?? 'prod';
+        const keyPrefix = `${options.cacheKeyPrefix ?? 'ebrocante:'}${mode}:`;
+        const type = options.cacheType ?? 'local';
+
+        if (type === 'local') return new LocalCache(ttl, keyPrefix);
+        if (type === 'redis') {
+            if (!options.cacheRedis) {
+                throw new TypeError("cacheRedis is required when cacheType='redis'");
+            }
+            return new RedisCache(options.cacheRedis, ttl, keyPrefix);
+        }
+        throw new TypeError(`cacheType must be 'local' or 'redis', got '${String(type)}'`);
+    }
+
+    private buildLogger(options: EBrocanteClientOptions): Logger {
+        if (options.logger) return options.logger;
+        if (options.logPath) return new FileLogger(options.logPath);
+        return new NullLogger();
+    }
+}

package/src/cache/CacheBackend.ts

@@ -0,0 +1,20 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+/**
+ * Minimal cache interface used by the SDK. Implementations are local
+ * (in-memory), Redis, or a no-op when caching is disabled.
+ */
+export interface CacheBackend {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    purge(): Promise<void>;
+    /**
+     * Bulk purge keys matching a wildcard pattern (`*` at the end). Used
+     * by the public `client.cache.purgeKey()` shortcut.
+     */
+    purgeKey(endpoint: string, params?: Record<string, unknown>): Promise<void>;
+}

package/src/cache/LocalCache.ts

@@ -0,0 +1,64 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import type { CacheBackend } from './CacheBackend.js';
+import { stableHashKey } from './stableHashKey.js';
+
+interface Entry {
+    value: unknown;
+    expiresAt: number;
+}
+
+/**
+ * In-memory cache backend. Lives for the duration of a single Node/Bun
+ * process. Suitable for short scripts and single-instance apps. For
+ * multi-process deployments use RedisCache.
+ */
+export class LocalCache implements CacheBackend {
+    private readonly store = new Map<string, Entry>();
+
+    constructor(
+        private readonly defaultTtl: number = 300,
+        private readonly keyPrefix: string = '',
+    ) {}
+
+    async get(key: string): Promise<unknown> {
+        const fullKey = this.keyPrefix + key;
+        const entry = this.store.get(fullKey);
+        if (!entry) {
+            return null;
+        }
+        if (entry.expiresAt < Date.now()) {
+            this.store.delete(fullKey);
+            return null;
+        }
+        return entry.value;
+    }
+
+    async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+        const ttl = ttlSeconds ?? this.defaultTtl;
+        this.store.set(this.keyPrefix + key, {
+            value,
+            expiresAt: Date.now() + ttl * 1000,
+        });
+    }
+
+    async delete(key: string): Promise<void> {
+        this.store.delete(this.keyPrefix + key);
+    }
+
+    async purge(): Promise<void> {
+        this.store.clear();
+    }
+
+    async purgeKey(endpoint: string, params: Record<string, unknown> = {}): Promise<void> {
+        const hashed = stableHashKey(endpoint, params);
+        for (const key of this.store.keys()) {
+            if (key.endsWith(hashed)) {
+                this.store.delete(key);
+            }
+        }
+    }
+}

package/src/cache/NullCache.ts

@@ -0,0 +1,32 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import type { CacheBackend } from './CacheBackend.js';
+
+/**
+ * No-op cache used when the SDK is constructed with `cache: false`.
+ * Every request hits the network; nothing is stored.
+ */
+export class NullCache implements CacheBackend {
+    async get(_key: string): Promise<null> {
+        return null;
+    }
+
+    async set(_key: string, _value: unknown, _ttlSeconds?: number): Promise<void> {
+        /* intentional no-op */
+    }
+
+    async delete(_key: string): Promise<void> {
+        /* intentional no-op */
+    }
+
+    async purge(): Promise<void> {
+        /* intentional no-op */
+    }
+
+    async purgeKey(_endpoint: string, _params?: Record<string, unknown>): Promise<void> {
+        /* intentional no-op */
+    }
+}

package/src/cache/RedisCache.ts

@@ -0,0 +1,123 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import { EBrocanteError } from '../exceptions/index.js';
+import type { CacheBackend } from './CacheBackend.js';
+import { DEFAULT_REDIS_CONFIG, type RedisConfig } from './RedisConfig.js';
+import { stableHashKey } from './stableHashKey.js';
+
+/**
+ * Lightweight Redis client surface required by RedisCache. Compatible
+ * with `ioredis`'s public API (and any equivalent client).
+ */
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode: 'EX', seconds: number): Promise<unknown>;
+    del(...keys: string[]): Promise<number>;
+    scan(cursor: string | number, ...args: unknown[]): Promise<[string, string[]]>;
+    quit(): Promise<unknown>;
+}
+
+/**
+ * Redis cache backend. Uses `ioredis` by default. The connection is
+ * lazily established on the first get/set and reused for the lifetime
+ * of the cache instance.
+ */
+export class RedisCache implements CacheBackend {
+    private client: RedisLikeClient | null = null;
+
+    constructor(
+        private readonly config: RedisConfig,
+        private readonly defaultTtl: number = 300,
+        private readonly keyPrefix: string = '',
+        private readonly clientFactory?: () => Promise<RedisLikeClient>,
+    ) {}
+
+    async get(key: string): Promise<unknown> {
+        const raw = await (await this.connect()).get(this.fullKey(key));
+        if (raw === null) return null;
+        try {
+            return JSON.parse(raw);
+        } catch {
+            return null;
+        }
+    }
+
+    async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+        const encoded = JSON.stringify(value);
+        await (await this.connect()).set(this.fullKey(key), encoded, 'EX', ttlSeconds ?? this.defaultTtl);
+    }
+
+    async delete(key: string): Promise<void> {
+        await (await this.connect()).del(this.fullKey(key));
+    }
+
+    async purge(): Promise<void> {
+        const client = await this.connect();
+        const pattern = this.fullKey('*');
+        let cursor = '0';
+        do {
+            const [next, keys] = await client.scan(cursor, 'MATCH', pattern, 'COUNT', '100');
+            cursor = next;
+            if (keys.length > 0) {
+                await client.del(...keys);
+            }
+        } while (cursor !== '0');
+    }
+
+    async purgeKey(endpoint: string, params: Record<string, unknown> = {}): Promise<void> {
+        const hashed = stableHashKey(endpoint, params);
+        const client = await this.connect();
+        const pattern = this.fullKey(`*${hashed}`);
+        let cursor = '0';
+        do {
+            const [next, keys] = await client.scan(cursor, 'MATCH', pattern, 'COUNT', '100');
+            cursor = next;
+            if (keys.length > 0) {
+                await client.del(...keys);
+            }
+        } while (cursor !== '0');
+    }
+
+    private async connect(): Promise<RedisLikeClient> {
+        if (this.client) return this.client;
+        /* v8 ignore start — live-Redis fallback path is integration-tested only */
+        if (!this.clientFactory) {
+            this.client = await this.realConnect();
+            return this.client;
+        }
+        /* v8 ignore stop */
+        this.client = await this.clientFactory();
+        return this.client;
+    }
+
+    /* v8 ignore start — exercised only against a live Redis instance */
+    private async realConnect(): Promise<RedisLikeClient> {
+        const cfg = { ...DEFAULT_REDIS_CONFIG, ...this.config };
+        let Redis: new (...args: unknown[]) => RedisLikeClient;
+        try {
+            ({ default: Redis } = (await import('ioredis')) as unknown as {
+                default: new (...args: unknown[]) => RedisLikeClient;
+            });
+        } catch {
+            throw new EBrocanteError(
+                "RedisCache requires the 'ioredis' package. Install it with: bun add ioredis",
+            );
+        }
+        return new Redis({
+            host: cfg.host,
+            port: cfg.port,
+            password: cfg.password,
+            db: cfg.db,
+            connectTimeout: cfg.timeoutMs,
+            tls: cfg.tls ? {} : undefined,
+        });
+    }
+    /* v8 ignore stop */
+
+    private fullKey(key: string): string {
+        return `${this.config.prefix ?? DEFAULT_REDIS_CONFIG.prefix}${this.keyPrefix}${key}`;
+    }
+}

package/src/cache/RedisConfig.ts

@@ -0,0 +1,23 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+export interface RedisConfig {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    prefix?: string;
+    timeoutMs?: number;
+    tls?: boolean;
+}
+
+export const DEFAULT_REDIS_CONFIG: Required<Omit<RedisConfig, 'password'>> & { password?: string } = {
+    host: '127.0.0.1',
+    port: 6379,
+    db: 0,
+    prefix: 'ebrocante:',
+    timeoutMs: 1500,
+    tls: false,
+};

package/src/cache/stableHashKey.ts

@@ -0,0 +1,28 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import { createHash } from 'node:crypto';
+import { slashesToDots, stringifyPrimitive, trimSlashes } from '../internal/safeStrings.js';
+
+/**
+ * Deterministic, key-order-independent hash for cache lookups.
+ * Mirrors the PHP SDK's makeCacheKey() so both clients can share
+ * a Redis instance without collisions.
+ */
+export function stableHashKey(endpoint: string, params: Record<string, unknown>): string {
+    const sortedKeys = Object.keys(params).sort((a, b) => a.localeCompare(b, 'en'));
+    const queryString = sortedKeys
+        .map((k) => {
+            const v = params[k];
+            if (v === undefined || v === null || v === '') return null;
+            return `${encodeURIComponent(k)}=${encodeURIComponent(stringifyPrimitive(v))}`;
+        })
+        .filter((s): s is string => s !== null)
+        .join('&');
+
+    const cleanEndpoint = slashesToDots(trimSlashes(endpoint));
+    const digest = createHash('sha256').update(queryString).digest('hex').slice(0, 32);
+    return `${cleanEndpoint}:${digest}`;
+}

package/src/exceptions/index.ts

@@ -0,0 +1,75 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ *
+ * Typed exception hierarchy. Catch `EBrocanteError` to handle any SDK
+ * failure, or a more specific subclass for finer control.
+ */
+
+export class EBrocanteError extends Error {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = this.constructor.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+/** HTTP 401 / 403 — invalid key, wrong scope, or mode mismatch. */
+export class AuthenticationError extends EBrocanteError {
+    constructor(
+        message: string,
+        readonly status: number,
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+    }
+}
+
+/** HTTP 404 / 410 — resource missing or gone. */
+export class NotFoundError extends EBrocanteError {
+    constructor(
+        message: string,
+        readonly status: number,
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+    }
+}
+
+/** HTTP 422 — request schema rejected. Carries the raw error body. */
+export class ValidationError extends EBrocanteError {
+    constructor(
+        message: string,
+        readonly status: number,
+        readonly body: string,
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+    }
+}
+
+/** HTTP 429 — rate limit exhausted. `retryAfter` in seconds. */
+export class RateLimitError extends EBrocanteError {
+    constructor(
+        message: string,
+        readonly status: number,
+        readonly retryAfter: number,
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+    }
+}
+
+/** HTTP 5xx (or any unmapped status) once retries have been exhausted. */
+export class ServerError extends EBrocanteError {
+    constructor(
+        message: string,
+        readonly status: number,
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+    }
+}
+
+/** Transport-level failure (DNS, TCP timeout, broken pipe, abort, …). */
+export class NetworkError extends EBrocanteError {}