@ecosplay/e-brocante 1.0.2

package/src/models/Event.ts

@@ -0,0 +1,92 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import {
+    asBoolean,
+    asDate,
+    asNullableInt,
+    asNullableString,
+    asNumber,
+    asRecord,
+    asString,
+} from '../internal/safeStrings.js';
+
+export interface EventDto {
+    id: string;
+    slug: string;
+    name: string;
+    /** Free-form category. The platform currently emits one of:
+     *  `'brocante'`, `'vide_grenier'`, `'marche_aux_puces'`, `'bourse_collection'`. */
+    category: string;
+    description: string;
+    address: string;
+    zipcode: string;
+    city: string;
+    department: string;
+    region: string;
+    lat: number;
+    long: number;
+    mainPictureUrl: string | null;
+    startAt: Date;
+    endAt: Date;
+    outside: boolean;
+    inside: boolean;
+    tarifOutsideCents: number | null;
+    tarifInsideCents: number | null;
+    /** Pricing scheme — typically `'per_meter'` or `'flat'`. */
+    pricingMode: string;
+    availableBooths: number;
+    totalBooths: number;
+    /** Lifecycle — typically `'published'`, `'cancelled'`, or `'completed'`. */
+    state: string;
+    organizerSlug: string | null;
+    updatedAt: Date | null;
+}
+
+interface RawEvent {
+    id?: unknown;
+    type?: unknown;
+    attributes?: Record<string, unknown>;
+    relationships?: { organizer?: { slug?: unknown } };
+}
+
+function resolveOrganizerSlug(raw: RawEvent, attr: Record<string, unknown>): string | null {
+    const rel = raw.relationships?.organizer?.slug;
+    return asNullableString(rel) ?? asNullableString(attr.organizer_slug);
+}
+
+export function eventFromApi(raw: unknown): EventDto {
+    const r = asRecord(raw) as RawEvent;
+    const attr = asRecord(r.attributes ?? r);
+
+    const epoch = new Date(0);
+    return {
+        id: asString(r.id, asString(attr.id)),
+        slug: asString(attr.slug),
+        name: asString(attr.name),
+        category: asString(attr.category, 'brocante'),
+        description: asString(attr.description),
+        address: asString(attr.address),
+        zipcode: asString(attr.zipcode),
+        city: asString(attr.city),
+        department: asString(attr.department),
+        region: asString(attr.region),
+        lat: asNumber(attr.lat),
+        long: asNumber(attr.long),
+        mainPictureUrl: asNullableString(attr.main_picture_url),
+        startAt: asDate(attr.start_at) ?? epoch,
+        endAt: asDate(attr.end_at) ?? epoch,
+        outside: asBoolean(attr.outside),
+        inside: asBoolean(attr.inside),
+        tarifOutsideCents: asNullableInt(attr.tarif_outside_cents),
+        tarifInsideCents: asNullableInt(attr.tarif_inside_cents),
+        pricingMode: asString(attr.pricing_mode, 'per_meter'),
+        availableBooths: asNumber(attr.available_booths),
+        totalBooths: asNumber(attr.total_booths),
+        state: asString(attr.state, 'published'),
+        organizerSlug: resolveOrganizerSlug(r, attr),
+        updatedAt: asDate(attr.updated_at),
+    };
+}

package/src/models/Orga.ts

@@ -0,0 +1,76 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import { asDate, asNullableString, asNumber, asRecord, asString } from '../internal/safeStrings.js';
+import { type EventDto, eventFromApi } from './Event.js';
+
+export interface OrgaDto {
+    id: string;
+    slug: string;
+    name: string;
+    /** Legal form — typically `'asso'`, `'sarl'`, `'sas'`, or `'ei'`. */
+    legalForm: string;
+    siren: string | null;
+    rna: string | null;
+    address: string;
+    zipcode: string;
+    city: string;
+    department: string;
+    region: string;
+    lat: number;
+    long: number;
+    emailPublic: string | null;
+    phonePublic: string | null;
+    website: string | null;
+    rcProInsurer: string | null;
+    mediatorName: string | null;
+    totalEventsOrganized: number;
+    /** Lifecycle — currently always `'active'` for entries returned by the public API. */
+    state: string;
+    createdAt: Date | null;
+    upcomingEvents: EventDto[];
+}
+
+interface RawOrga {
+    id?: unknown;
+    attributes?: Record<string, unknown>;
+    included?: { upcoming_events?: unknown[] };
+}
+
+export function orgaFromApi(raw: unknown, upcomingOverride?: EventDto[]): OrgaDto {
+    const r = asRecord(raw) as RawOrga;
+    const attr = asRecord(r.attributes ?? r);
+
+    const upcoming =
+        upcomingOverride ??
+        (Array.isArray(r.included?.upcoming_events)
+            ? r.included.upcoming_events.map((e) => eventFromApi(e))
+            : []);
+
+    return {
+        id: asString(r.id, asString(attr.id)),
+        slug: asString(attr.slug),
+        name: asString(attr.name),
+        legalForm: asString(attr.legal_form, 'asso'),
+        siren: asNullableString(attr.siren),
+        rna: asNullableString(attr.rna),
+        address: asString(attr.address),
+        zipcode: asString(attr.zipcode),
+        city: asString(attr.city),
+        department: asString(attr.department),
+        region: asString(attr.region),
+        lat: asNumber(attr.lat),
+        long: asNumber(attr.long),
+        emailPublic: asNullableString(attr.email_public),
+        phonePublic: asNullableString(attr.phone_public),
+        website: asNullableString(attr.website),
+        rcProInsurer: asNullableString(attr.rc_pro_insurer),
+        mediatorName: asNullableString(attr.mediator_name),
+        totalEventsOrganized: asNumber(attr.total_events_organized),
+        state: asString(attr.state, 'active'),
+        createdAt: asDate(attr.created_at),
+        upcomingEvents: upcoming,
+    };
+}

package/src/models/PaginatedResult.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+export interface PaginationMeta {
+    page: number;
+    perPage: number;
+    totalPages: number;
+    totalCount: number;
+}
+
+export class PaginatedResult<T> implements Iterable<T> {
+    constructor(
+        readonly data: T[],
+        readonly page: number,
+        readonly perPage: number,
+        readonly totalPages: number,
+        readonly totalCount: number,
+        readonly requestId: string | null,
+        readonly now: string | null,
+        readonly links: Record<string, string>,
+    ) {}
+
+    static fromApi<T>(
+        items: T[],
+        meta: Record<string, unknown>,
+        links: Record<string, unknown>,
+    ): PaginatedResult<T> {
+        const pagination = (meta.pagination as Record<string, unknown> | undefined) ?? {};
+        const stringLinks: Record<string, string> = {};
+        for (const [k, v] of Object.entries(links)) {
+            if (typeof v === 'string' && v !== '') stringLinks[k] = v;
+        }
+        return new PaginatedResult<T>(
+            items,
+            Number(pagination.page ?? 1),
+            Number(pagination.per_page ?? items.length),
+            Number(pagination.total_pages ?? 1),
+            Number(pagination.total_count ?? items.length),
+            typeof meta.request_id === 'string' ? meta.request_id : null,
+            typeof meta.now === 'string' ? meta.now : null,
+            stringLinks,
+        );
+    }
+
+    get length(): number {
+        return this.data.length;
+    }
+
+    isEmpty(): boolean {
+        return this.data.length === 0;
+    }
+
+    hasNextPage(): boolean {
+        return this.page < this.totalPages;
+    }
+
+    [Symbol.iterator](): Iterator<T> {
+        return this.data[Symbol.iterator]();
+    }
+}

package/src/resources/EventsResource.ts

@@ -0,0 +1,48 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import { ServerError } from '../exceptions/index.js';
+import type { HttpClient } from '../http/HttpClient.js';
+import { type EventDto, eventFromApi } from '../models/Event.js';
+import { PaginatedResult } from '../models/PaginatedResult.js';
+import type { EventFilters, RequestOptions } from '../types.js';
+
+/**
+ * Read-only resource wrapping `GET /api/{mode}/events` and
+ * `GET /api/{mode}/event/{slug}`.
+ */
+export class EventsResource {
+    constructor(private readonly http: HttpClient) {}
+
+    async list(filters: EventFilters = {}, options: RequestOptions = {}): Promise<PaginatedResult<EventDto>> {
+        const payload = await this.http.get('events', filters as Record<string, unknown>, options);
+        const data = Array.isArray(payload.data) ? payload.data : [];
+        const items = data.map((raw: unknown) => eventFromApi(raw));
+        const meta = (payload.meta as Record<string, unknown>) ?? {};
+        const links = (payload.links as Record<string, unknown>) ?? {};
+        return PaginatedResult.fromApi(items, meta, links);
+    }
+
+    async get(slug: string, options: RequestOptions = {}): Promise<EventDto> {
+        const payload = await this.http.get(`event/${encodeURIComponent(slug)}`, {}, options);
+        const data = payload.data;
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            throw new ServerError(`Unexpected response shape for event/${slug}`, 0);
+        }
+        return eventFromApi(data);
+    }
+
+    async *iter(filters: EventFilters = {}): AsyncIterable<EventDto> {
+        let page = filters.page ?? 1;
+        const perPage = filters.per_page ?? 50;
+        let totalPages = Number.POSITIVE_INFINITY;
+        while (page <= totalPages) {
+            const result = await this.list({ ...filters, page, per_page: perPage });
+            totalPages = result.totalPages;
+            for (const event of result.data) yield event;
+            page++;
+        }
+    }
+}

package/src/resources/OrgaResource.ts

@@ -0,0 +1,53 @@
+/**
+ * @copyright 2026 Association E-Cosplay
+ * @license   Proprietary — see LICENSE
+ */
+
+import { ServerError } from '../exceptions/index.js';
+import type { HttpClient } from '../http/HttpClient.js';
+import { type EventDto, eventFromApi } from '../models/Event.js';
+import { type OrgaDto, orgaFromApi } from '../models/Orga.js';
+import { PaginatedResult } from '../models/PaginatedResult.js';
+import type { OrgaFilters, RequestOptions } from '../types.js';
+
+/**
+ * Read-only resource wrapping `GET /api/{mode}/orga` and
+ * `GET /api/{mode}/orga/{slug}`.
+ */
+export class OrgaResource {
+    constructor(private readonly http: HttpClient) {}
+
+    async list(filters: OrgaFilters = {}, options: RequestOptions = {}): Promise<PaginatedResult<OrgaDto>> {
+        const payload = await this.http.get('orga', filters as Record<string, unknown>, options);
+        const data = Array.isArray(payload.data) ? payload.data : [];
+        const items = data.map((raw: unknown) => orgaFromApi(raw));
+        const meta = (payload.meta as Record<string, unknown>) ?? {};
+        const links = (payload.links as Record<string, unknown>) ?? {};
+        return PaginatedResult.fromApi(items, meta, links);
+    }
+
+    async get(slug: string, options: RequestOptions = {}): Promise<OrgaDto> {
+        const payload = await this.http.get(`orga/${encodeURIComponent(slug)}`, {}, options);
+        const data = payload.data;
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            throw new ServerError(`Unexpected response shape for orga/${slug}`, 0);
+        }
+        const included = (data as { included?: { upcoming_events?: unknown[] } }).included;
+        const upcoming: EventDto[] = Array.isArray(included?.upcoming_events)
+            ? included.upcoming_events.map((raw) => eventFromApi(raw))
+            : [];
+        return orgaFromApi(data, upcoming);
+    }
+
+    async *iter(filters: OrgaFilters = {}): AsyncIterable<OrgaDto> {
+        let page = filters.page ?? 1;
+        const perPage = filters.per_page ?? 50;
+        let totalPages = Number.POSITIVE_INFINITY;
+        while (page <= totalPages) {
+            const result = await this.list({ ...filters, page, per_page: perPage });
+            totalPages = result.totalPages;
+            for (const orga of result.data) yield orga;
+            page++;
+        }
+    }
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+/**
+ * @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;
+}