{"_id":"@ecosplay/e-brocante","name":"@ecosplay/e-brocante","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.2":{"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":{"url":"https://code.e-cosplay.fr/shoko/e-brocante-js/issues","email":"contact@e-cosplay.fr"},"main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"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"},"_id":"@ecosplay/e-brocante@1.0.2","gitHead":"aeef6411fef8d3efbe36a96c0080b432b1038c86","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-24XavXSJkENMr2biFJ1TRsd6qZ5dIZWyoOl2v+reHdvWH/zrI9wEzzSTZDjDaQqrHWNfiivK8bHmJqbMtAfRtA==","shasum":"de8180038411b82beef29535692e467f3a090c63","tarball":"https://registry.npmjs.org/@ecosplay/e-brocante/-/e-brocante-1.0.2.tgz","fileCount":110,"unpackedSize":203797,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCeGS7HigXfLp5y41/npumXl69DiSxUrXEZTLo7pg2+MQIhAK6v1C5IDZIfkADUaMugTzXJLsPVibyC8dEizeR2Cw5x"}]},"_npmUser":{"name":"ecosplay","email":"contact@e-cosplay.fr"},"directories":{},"maintainers":[{"name":"ecosplay","email":"contact@e-cosplay.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/e-brocante_1.0.2_1778447366093_0.5228720733627417"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-10T21:09:26.002Z","1.0.2":"2026-05-10T21:09:26.239Z","modified":"2026-05-10T21:09:26.440Z"},"maintainers":[{"name":"ecosplay","email":"contact@e-cosplay.fr"}],"description":"Official JavaScript / TypeScript client for the public e-brocante.enum.fr API","homepage":"https://e-brocante.enum.fr","keywords":["brocante","flea-market","api","sdk","e-brocante","ecosplay"],"repository":{"type":"git","url":"https://code.e-cosplay.fr/shoko/e-brocante-js.git"},"author":{"name":"Association E-Cosplay","email":"contact@e-cosplay.fr","url":"https://e-cosplay.fr"},"bugs":{"url":"https://code.e-cosplay.fr/shoko/e-brocante-js/issues","email":"contact@e-cosplay.fr"},"license":"SEE LICENSE IN LICENSE","readme":"# e-brocante JavaScript / TypeScript SDK\n\n> Official JS / TypeScript client for the **public API of [e-brocante.enum.fr](https://e-brocante.enum.fr)** — the French platform connecting flea-market organizers and stallholders (brocanteurs).\n\n[![License](https://img.shields.io/badge/license-proprietary-red.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A522-339933.svg)](https://nodejs.org/)\n[![Bun](https://img.shields.io/badge/bun-%E2%89%A51.1-fbf0df.svg)](https://bun.sh/)\n[![TypeScript](https://img.shields.io/badge/typescript-strict-3178C6.svg)](https://www.typescriptlang.org/)\n[![API](https://img.shields.io/badge/API-v1-d97706.svg)](https://e-brocante.enum.fr/api/doc)\n\n### Code quality\n\n[![Quality Gate Status](https://sn.e-cosplay.fr/api/project_badges/measure?project=e-brocante-js&metric=alert_status&token=sqb_1f2640dc563aa40f73924fd10ff275036e68e520)](https://sn.e-cosplay.fr/dashboard?id=e-brocante-js)\n[![Coverage](https://sn.e-cosplay.fr/api/project_badges/measure?project=e-brocante-js&metric=coverage&token=sqb_1f2640dc563aa40f73924fd10ff275036e68e520)](https://sn.e-cosplay.fr/dashboard?id=e-brocante-js)\n[![Maintainability Rating](https://sn.e-cosplay.fr/api/project_badges/measure?project=e-brocante-js&metric=software_quality_maintainability_rating&token=sqb_1f2640dc563aa40f73924fd10ff275036e68e520)](https://sn.e-cosplay.fr/dashboard?id=e-brocante-js)\n[![Reliability Rating](https://sn.e-cosplay.fr/api/project_badges/measure?project=e-brocante-js&metric=software_quality_reliability_rating&token=sqb_1f2640dc563aa40f73924fd10ff275036e68e520)](https://sn.e-cosplay.fr/dashboard?id=e-brocante-js)\n[![Security Rating](https://sn.e-cosplay.fr/api/project_badges/measure?project=e-brocante-js&metric=software_quality_security_rating&token=sqb_1f2640dc563aa40f73924fd10ff275036e68e520)](https://sn.e-cosplay.fr/dashboard?id=e-brocante-js)\n\n---\n\n## ✨ Overview\n\nIdiomatic TypeScript client for the **four public read-only endpoints** of the e-brocante API:\n\n- 🎪 **Events** — list & detail (flea markets, vide-greniers, antique markets, collector fairs)\n- 👥 **Organizers** — list & profile\n\nThe 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.\n\n> 🔗 **Site**: https://e-brocante.enum.fr\n> 📖 **API docs**: https://e-brocante.enum.fr/api/doc\n> 🐛 **Issues**: https://code.e-cosplay.fr/shoko/e-brocante-js/issues\n\n---\n\n## 📦 Installation\n\n```bash\n# npm\nnpm install @ecosplay/e-brocante\n\n# pnpm\npnpm add @ecosplay/e-brocante\n\n# bun\nbun add @ecosplay/e-brocante\n```\n\nOr pull from the **Gitea Composer/npm registry** (private/internal channel):\n\n```bash\nbun add git+https://code.e-cosplay.fr/shoko/e-brocante-js.git#v1.0.0\n```\n\n**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.\n\n---\n\n## 🔑 Getting an API key\n\nThe API authenticates with **two headers**:\n\n| Header | Meaning |\n|--------|---------|\n| **`X-KEY`** | Your API key (`eb_prod_…` for live, `eb_test_…` for sandbox) |\n| **`X-BROC`** | The email of the e-brocante account the call is made for |\n\n### Step 1 — Create an account\n\n- Stallholder → https://e-brocante.enum.fr/register/broc\n- Organizer → https://e-brocante.enum.fr/register/orga\n\n### Step 2 — Generate an API key\n\n| Account type | API key page |\n|--------------|--------------|\n| Stallholder (`ROLE_BROC`) | **https://e-brocante.enum.fr/espace-broc/api** |\n| Organizer (`ROLE_ORGA`) | **https://e-brocante.enum.fr/espace-orga/api** |\n\nPick **prod** (`eb_prod_…`) for production data, **test** (`eb_test_…`) for the sandbox. Keys are shown once.\n\n> ⚠️ 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.\n\n---\n\n## 🚀 Quick start\n\n```typescript\nimport { EBrocanteClient } from '@ecosplay/e-brocante';\n\nconst client = new EBrocanteClient({\n    apiKey:    process.env.EBROCANTE_API_KEY!,   // eb_prod_...\n    brocEmail: 'orga@example.com',\n    mode:      'prod',\n});\n\nconst { data: events } = await client.events.list({\n    city: 'paris',\n    from: '2026-06-01',\n    to:   '2026-06-30',\n});\n\nfor (const event of events) {\n    console.log(`${event.name} — ${event.city} on ${event.startAt.toISOString().slice(0, 10)}`);\n}\n```\n\nMore runnable examples in [`samples/`](samples/).\n\n---\n\n## 🟢 Live vs 🟡 Sandbox\n\n| Mode | URL prefix | Key prefix | Data | Stripe |\n|------|------------|------------|------|--------|\n| 🟢 **`prod`** (live) | `/api/prod/*` | `eb_prod_…` | **Real** organizers and events | Stripe **live** |\n| 🟡 **`test`** (sandbox) | `/api/test/*` | `eb_test_…` | **Fake** (1 fake orga + 3-7 fake events, deterministic per day) | Stripe **test** |\n\n```typescript\nconst client = new EBrocanteClient({ apiKey: 'eb_test_xxx', brocEmail: 'tester@example.com', mode: 'test' });\nconst { data: orgas } = await client.orga.list();\nconsole.assert(orgas.length === 1 && orgas[0]?.slug === 'test-orga');\n```\n\n> 💡 Develop and test in `mode: 'test'`, then flip to `mode: 'prod'`. **Data never crosses between modes.**\n\n---\n\n## ⚡ Response cache\n\n```typescript\nimport { EBrocanteClient } from '@ecosplay/e-brocante';\n\n// 1) Local in-memory cache (default, TTL 5 min)\nconst client = new EBrocanteClient({ apiKey: '...', brocEmail: '...' });\n\n// 2) Local with custom TTL\nconst c2 = new EBrocanteClient({ apiKey: '...', brocEmail: '...', cacheTtl: 3600 });\n\n// 3) Redis (multi-instance — requires `bun add ioredis`)\nconst c3 = new EBrocanteClient({\n    apiKey:     '...',\n    brocEmail:  '...',\n    cacheType:  'redis',\n    cacheRedis: { host: 'redis.internal', port: 6379, db: 3 },\n    cacheTtl:   600,\n});\n\n// 4) Disabled\nconst c4 = new EBrocanteClient({ apiKey: '...', brocEmail: '...', cache: false });\n\n// 5) One-shot bypass\nconst fresh = await client.events.list({ city: 'paris' }, { skipCache: true });\n\n// 6) Invalidation\nawait client.cache.purge();\nawait client.cache.purgeKey('events.list', { city: 'paris' });\n```\n\n---\n\n## 🪵 Logging\n\n```typescript\nimport { EBrocanteClient } from '@ecosplay/e-brocante';\n\n// A) Built-in JSON-lines file logger (one file per day)\nnew EBrocanteClient({ apiKey: '...', brocEmail: '...', logPath: '/var/log/ebrocante' });\n\n// B) Plug your own Logger (any `{ debug, info, warn, error }` interface)\nnew EBrocanteClient({ apiKey: '...', brocEmail: '...', logger: pino() });\n\n// C) Verbose plain-text trace to ./DEBUG.TXT (one line per action)\nnew EBrocanteClient({ apiKey: '...', brocEmail: '...', debug: true });\nnew EBrocanteClient({ apiKey: '...', brocEmail: '...', debug: true, debugFile: '/tmp/ebr.debug' });\n```\n\nAPI keys and `Authorization` headers are automatically redacted from log output.\n\n---\n\n## 📡 Available endpoints\n\n| SDK method | API endpoint | Description |\n|------------|--------------|-------------|\n| `client.events.list(filters)` | `GET /api/{mode}/events` | Paginated list (geo / date / category filters) |\n| `client.events.get(slug)` | `GET /api/{mode}/event/{slug}` | Event detail |\n| `client.orga.list(filters)` | `GET /api/{mode}/orga` | Paginated list of organizers |\n| `client.orga.get(slug)` | `GET /api/{mode}/orga/{slug}` | Organizer profile + upcoming events |\n\nBoth `events` and `orga` resources expose an `iter()` `AsyncIterable` that walks every page automatically.\n\n---\n\n## 🧪 Bundled mock API server\n\nThe package ships a Bun-based mock server in [`tools/mock-api/`](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.\n\n```bash\nbun run mock-api\n# → server listening on http://127.0.0.1:3000\n\n# In another terminal:\nEBROCANTE_BASE_URL=http://127.0.0.1:3000 bun run samples/01-list-events.ts\n```\n\nPoint any client at it via `baseUrl`:\n\n```typescript\nconst client = new EBrocanteClient({\n    apiKey:    'eb_mock_dev',\n    brocEmail: 'dev@example.com',\n    mode:      'prod',\n    baseUrl:   'http://127.0.0.1:3000',\n});\n```\n\nSee [`tools/mock-api/README.md`](tools/mock-api/README.md) for fixtures and configuration.\n\n---\n\n## 🤖 AI assistants\n\nThis 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`](AGENTS.md).\n\n---\n\n## 📜 License\n\n**Proprietary** — © 2026 Association E-Cosplay (RNA W022006988, SIREN 943121517).\n\nThe SDK is **free to use**. **Redistribution, modification, distributed forks, and derivative works are forbidden without prior written agreement** — `contact@e-cosplay.fr`.\n\nSee [`LICENSE`](LICENSE) for the full text.\n\n---\n\n## 🔗 Useful links\n\n- 🌸 **Platform**: https://e-brocante.enum.fr\n- 📖 **API docs**: https://e-brocante.enum.fr/api/doc\n- 🔐 **API keys (stallholder)**: https://e-brocante.enum.fr/espace-broc/api\n- 🔐 **API keys (organizer)**: https://e-brocante.enum.fr/espace-orga/api\n- 🐛 **Issues**: https://code.e-cosplay.fr/shoko/e-brocante-js/issues\n- 💬 **Contact**: contact@e-cosplay.fr\n- 🏢 **Publisher**: Association E-Cosplay — https://e-cosplay.fr\n","readmeFilename":"README.md","_rev":"1-a46b2de18b1cb00cc57bfbb2a23b2c98"}