TypeScript SDK โ Overview & Contracts
The @suitenumerique/slash-sources-sdk provides immutable schema validation and TypeScript DTOs for declaring custom slash command data providers. It guarantees strict contracts between the upstream APIs, the intermediary Django Proxy, and the BlockNote UI.
โก Quick Example: Defining a Custom Provider
The SDK exposes defineSourceProvider, an identity function enforcing the SourceProvider contract using TypeScript literal types and Object.freeze.
npm install @suitenumerique/slash-sources-sdkCode
๐งฉ The ExternalSourceEntity DTO
Every provider must normalize its upstream API data into the ExternalSourceEntity format. This strict normalization (snake_case on Django, camelCase on the TypeScript SDK) ensures that the frontend BlockNote extension can render any data source indiscriminately.
Key Properties
sourceId(string): The stable upstream identity (never generate this randomly, it must be persistent).entityType(string): The business category of the data (e.g.,law,company,address,procurement).provider(string): The upstream provider alias (e.g.,github,legifrance,insee). This is used for telemetry, Redis Quotas, and caching.country(string): Slasher supportsfr,eu,ca,de,nl,es, andinternational. It drives the UI preset filters.displayMode(string): Drives the default BlockNote format (callout,card,link,inline).freshness(string): Triggers the UI cache badge (live,cached,offline_index).verifiedAt(string, optional): ISO date for juridically verified data.
๐ก๏ธ Anti-SSRF & Security
This SDK is intended to be used in conjunction with a proxy tier (like django-lasuite-sources). Do not put upstream API secrets directly in the frontend SDK implementation.
Instead, the SDK's fetch() calls should route to the local Django Proxy:
Code
The Django Proxy will handle Rate-Limiting (Redis Token Bucket), the Circuit Breaker, and Anti-SSRF (Server-Side Request Forgery) protection via its PublicResolver.