e-brocante JavaScript / TypeScript SDK

Official JS / TypeScript client for the public API of e-brocante.enum.fr — the French platform connecting flea-market organizers and stallholders (brocanteurs).

Code quality

✨ Overview

Idiomatic TypeScript client for the four public read-only endpoints of the e-brocante API:

• 🎪 Events — list & detail (flea markets, vide-greniers, antique markets, collector fairs)
• 👥 Organizers — list & profile

The API is free, REST + JSON, and strictly read-only (GET only). All transactional operations (booth reservations, payments, attendance register) live in the e-brocante.enum.fr web app, not in this SDK.

🔗 Site: https://e-brocante.enum.fr 📖 API docs: https://e-brocante.enum.fr/api/doc 🐛 Issues: https://code.e-cosplay.fr/shoko/e-brocante-js/issues

📦 Installation

# npm
npm install @ecosplay/e-brocante

# pnpm
pnpm add @ecosplay/e-brocante

# bun
bun add @ecosplay/e-brocante

Or pull from the Gitea Composer/npm registry (private/internal channel):

bun add git+https://code.e-cosplay.fr/shoko/e-brocante-js.git#v1.0.0

Requirements: Node.js ≥ 22 or Bun ≥ 1.1, TypeScript ≥ 5.4 recommended. The SDK uses native fetch and crypto — no axios/got/node-fetch dependency.

🔑 Getting an API key

The API authenticates with two headers:

| Header | Meaning | |--------|---------| | X-KEY | Your API key (eb_prod_… for live, eb_test_… for sandbox) | | X-BROC | The email of the e-brocante account the call is made for |

Step 1 — Create an account

• Stallholder → https://e-brocante.enum.fr/register/broc
• Organizer → https://e-brocante.enum.fr/register/orga

Step 2 — Generate an API key

| Account type | API key page | |--------------|--------------| | Stallholder (ROLE_BROC) | https://e-brocante.enum.fr/espace-broc/api | | Organizer (ROLE_ORGA) | https://e-brocante.enum.fr/espace-orga/api |

Pick prod (eb_prod_…) for production data, test (eb_test_…) for the sandbox. Keys are shown once.

⚠️ Read the key from an environment variable. Never bundle it in a browser build — the SDK is server-side. For frontend apps, proxy through your own backend.

🚀 Quick start

import { EBrocanteClient } from '@ecosplay/e-brocante';

const client = new EBrocanteClient({
    apiKey:    process.env.EBROCANTE_API_KEY!,   // eb_prod_...
    brocEmail: '[email protected]',
    mode:      'prod',
});

const { data: events } = await client.events.list({
    city: 'paris',
    from: '2026-06-01',
    to:   '2026-06-30',
});

for (const event of events) {
    console.log(`${event.name} — ${event.city} on ${event.startAt.toISOString().slice(0, 10)}`);
}

More runnable examples in samples/.

🟢 Live vs 🟡 Sandbox

| Mode | URL prefix | Key prefix | Data | Stripe | |------|------------|------------|------|--------| | 🟢 prod (live) | /api/prod/* | eb_prod_… | Real organizers and events | Stripe live | | 🟡 test (sandbox) | /api/test/* | eb_test_… | Fake (1 fake orga + 3-7 fake events, deterministic per day) | Stripe test |

const client = new EBrocanteClient({ apiKey: 'eb_test_xxx', brocEmail: '[email protected]', mode: 'test' });
const { data: orgas } = await client.orga.list();
console.assert(orgas.length === 1 && orgas[0]?.slug === 'test-orga');

💡 Develop and test in mode: 'test', then flip to mode: 'prod'. Data never crosses between modes.

⚡ Response cache

import { EBrocanteClient } from '@ecosplay/e-brocante';

// 1) Local in-memory cache (default, TTL 5 min)
const client = new EBrocanteClient({ apiKey: '...', brocEmail: '...' });

// 2) Local with custom TTL
const c2 = new EBrocanteClient({ apiKey: '...', brocEmail: '...', cacheTtl: 3600 });

// 3) Redis (multi-instance — requires `bun add ioredis`)
const c3 = new EBrocanteClient({
    apiKey:     '...',
    brocEmail:  '...',
    cacheType:  'redis',
    cacheRedis: { host: 'redis.internal', port: 6379, db: 3 },
    cacheTtl:   600,
});

// 4) Disabled
const c4 = new EBrocanteClient({ apiKey: '...', brocEmail: '...', cache: false });

// 5) One-shot bypass
const fresh = await client.events.list({ city: 'paris' }, { skipCache: true });

// 6) Invalidation
await client.cache.purge();
await client.cache.purgeKey('events.list', { city: 'paris' });

🪵 Logging

import { EBrocanteClient } from '@ecosplay/e-brocante';

// A) Built-in JSON-lines file logger (one file per day)
new EBrocanteClient({ apiKey: '...', brocEmail: '...', logPath: '/var/log/ebrocante' });

// B) Plug your own Logger (any `{ debug, info, warn, error }` interface)
new EBrocanteClient({ apiKey: '...', brocEmail: '...', logger: pino() });

// C) Verbose plain-text trace to ./DEBUG.TXT (one line per action)
new EBrocanteClient({ apiKey: '...', brocEmail: '...', debug: true });
new EBrocanteClient({ apiKey: '...', brocEmail: '...', debug: true, debugFile: '/tmp/ebr.debug' });

API keys and Authorization headers are automatically redacted from log output.

📡 Available endpoints

| SDK method | API endpoint | Description | |------------|--------------|-------------| | client.events.list(filters) | GET /api/{mode}/events | Paginated list (geo / date / category filters) | | client.events.get(slug) | GET /api/{mode}/event/{slug} | Event detail | | client.orga.list(filters) | GET /api/{mode}/orga | Paginated list of organizers | | client.orga.get(slug) | GET /api/{mode}/orga/{slug} | Organizer profile + upcoming events |

Both events and orga resources expose an iter() AsyncIterable that walks every page automatically.

🧪 Bundled mock API server

The package ships a Bun-based mock server in tools/mock-api/ reproducing the four endpoints on http://127.0.0.1:3000. Use it for local development, integration tests, and CI without ever touching production.

bun run mock-api
# → server listening on http://127.0.0.1:3000

# In another terminal:
EBROCANTE_BASE_URL=http://127.0.0.1:3000 bun run samples/01-list-events.ts

Point any client at it via baseUrl:

const client = new EBrocanteClient({
    apiKey:    'eb_mock_dev',
    brocEmail: '[email protected]',
    mode:      'prod',
    baseUrl:   'http://127.0.0.1:3000',
});

See tools/mock-api/README.md for fixtures and configuration.

🤖 AI assistants

This SDK is compatible with AI coding assistants (Claude, ChatGPT, Copilot, Cursor, …) for read-only integration help. Modifying or republishing the SDK requires written authorization from the publisher. See AGENTS.md.

📜 License

Proprietary — © 2026 Association E-Cosplay (RNA W022006988, SIREN 943121517).

The SDK is free to use. Redistribution, modification, distributed forks, and derivative works are forbidden without prior written agreement — [email protected].

See LICENSE for the full text.

🔗 Useful links

• 🌸 Platform: https://e-brocante.enum.fr
• 📖 API docs: https://e-brocante.enum.fr/api/doc
• 🔐 API keys (stallholder): https://e-brocante.enum.fr/espace-broc/api
• 🔐 API keys (organizer): https://e-brocante.enum.fr/espace-orga/api
• 🐛 Issues: https://code.e-cosplay.fr/shoko/e-brocante-js/issues
• 💬 Contact: [email protected]
• 🏢 Publisher: Association E-Cosplay — https://e-cosplay.fr