# 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`.

<PackageInstallTabs packages={["@suitenumerique/slash-sources-sdk"]} />

```typescript
import { defineSourceProvider, ExternalSourceEntity } from "@suitenumerique/slash-sources-sdk";

export const githubIssuesSlasher = defineSourceProvider({
  name: "GitHub Issues",
  slashCommand: "issue",
  slashAliases: ["gh", "bug"],
  icon: "🐙",
  description: "Insert verified GitHub issues directly into documents",

  // The suggest method provides quick results for the `/issue` command
  suggest: async (query) => {
    const res = await fetch(`https://api.github.com/search/issues?q=${encodeURIComponent(query)}`);
    const data = await res.json();
    return data.items.map((item: any): ExternalSourceEntity => ({
      sourceId: String(item.id),
      entityType: "issue",
      provider: "github",
      country: "international",
      title: `#${item.number} ${item.title}`,
      subtitle: item.user.login,
      displayMode: "callout",
      freshness: "live",
      rawPayload: item,
    }));
  },

  // The search method is used in the expansive popover menu
  search: async (query) => {
    // Should return full ExternalSourceEntity array
    return [];
  },
});
```

---

## 🧩 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 supports `fr`, `eu`, `ca`, `de`, `nl`, `es`, and `international`. 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:

```typescript
search: async (query) => {
  // Safe: Routing through the local proxy
  const res = await fetch(`/api/v1/sources/github/search/?q=${encodeURIComponent(query)}`);
  return res.json(); // the proxy already normalizes into the DTO
};
```

The Django Proxy will handle Rate-Limiting (Redis Token Bucket), the Circuit Breaker, and Anti-SSRF (Server-Side Request Forgery) protection via its `PublicResolver`.
