ADS-B aéronefs militaires — exemple de source de données

Téléchargements

Les deux fichiers sont générés par le script de build de la documentation (apps/docs/scripts/build-pack-examples.ts) à partir d'un manifeste source unique situé à apps/docs/examples/scrydon-pack-adsb-aircraft/manifest.ts. Ils sont régénérés à chaque bun run dev / bun run build de l'application de documentation — ce sont les mêmes octets, simplement deux formes de distribution pour la même source de données.

Chemin A — installation via l'interface (recommandé)

L'installation d'un pack se déroule en deux étapes par conception — voir ADR 2026-05-30 pour la justification. L'étape 1 catalogue le pack au niveau de l'organisation ; l'étape 2 instancie la source de données dans un environnement d'espace de travail.

Étape 1 — L'administrateur d'organisation télécharge le pack

1. En tant qu'administrateur d'organisation, ouvrez Paramètres → Packs.
2. Déposez le fichier scrydon-pack-adsb-aircraft.scrydon-pack.tar.gz téléchargé sur la zone de dépôt (ou cliquez pour le sélectionner). La boîte de dialogue affiche l'id du pack scrydon-pack-adsb-aircraft, la version 1.0.0 et un résumé de contribution en une ligne : 1 source de données.
3. Cochez Je comprends que ce pack n'est pas signé… et cliquez sur Télécharger. Le pack est admis dans le catalogue de l'organisation. Aucune ligne data_source n'est encore créée — les packs contenant uniquement des sources de données reportent la matérialisation à l'étape 2 (le téléchargement se termine silencieusement et le pack apparaît dans la marketplace).

Étape 2 — L'utilisateur de l'espace de travail instancie la source de données

1. En tant qu'utilisateur de l'espace de travail, ouvrez apps/analytics et confirmez qu'un espace de travail et un environnement sont sélectionnés (sélecteur en haut à droite).
2. Ouvrez Marketplace dans la barre latérale. La carte scrydon-pack-adsb-aircraft apparaît avec un unique bouton Installer dans cet environnement (le pack contient exactement une source de données qui n'est pas encore présente dans cet environnement).
3. Cliquez sur Installer dans cet environnement. La plateforme appelle packs.install({ contentKinds: ["data-source"], workspaceEnvironmentId }) → api-table enregistre une ligne dans data_source limitée à votre environnement.
4. Ouvrez Sources de données dans la barre latérale — la nouvelle ligne apparaît avec Source : adsb-lol-military-declarative, Fournisseur : adsb-lol, Intervalle : 60s, Statut : En attente.
5. Ouvrez le menu d'actions de la ligne et cliquez sur Synchroniser maintenant. Attendez-vous à une notification verte avec le nombre de lignes écrites ; le Statut passe à Sain et la Dernière synchronisation s'affiche après l'actualisation automatique.

Chemin B — appliquer le JSON directement (développeur)

Ignorez l'outillage de création de pack et appliquez directement le manifeste brut à l'endpoint interne /data-sources/apply d'api-table. Cela emprunte le même chemin de code que le hook installDataSource du chemin A — les deux convergent vers POST /api/table/data-sources/apply.

Il s'agit de l'exercice de bout en bout le plus rapide pour :

• le domaine des sources de données api-table (ligne dans data_source, colonnes d'état de synchronisation mises à jour à chaque tick),
• le runtime de sondage générique dans @scrydon/better-auth-integrations/host/declarative-poll/runtime.ts (HTTP fetch → sélection itemsPath → mapping de champs → validation des lignes),
• la vue Analytics → Sources de données (badge de statut, heure de dernière synchronisation, compteur de lignes écrites, action « Synchroniser maintenant »).

Le manifeste ci-dessous est la source canonique adsb-lol-military-declarative de @scrydon/sdk-authoring, sérialisée en JSON simple. Le test de parité golden dans le monorepo affirme que cela produit des lignes identiques octet par octet à la source de code équivalente sur la même fixture — donc une fois que « Synchroniser maintenant » réussit, vous exercez le runtime de sondage en production contre une vraie API publique.

Prérequis

Vous disposez d'une stack Scrydon locale en cours d'exécution. Le service api-table doit répondre :

curl -fsS http://localhost:7500/api/table/health

Vous avez besoin d'un identifiant d'organisation pour délimiter la source de données. Récupérez-le depuis la table organization de votre base de données auth, ou depuis l'URL de n'importe quelle page limitée à une organisation dans l'interface de la plateforme.

export ORG="<your-org-uuid>"

Le manifeste

Voici le manifeste déclaratif complet. Il s'agit de JSON pur — sans fonctions, sans code. Le bundler de pack émet exactement cette forme à partir de defineDataSource({...}).

{
  "kind": "table",
  "id": "adsb-lol-military-declarative",
  "vendor": "adsb-lol",
  "displayName": "ADS-B Lol — Military Aircraft (declarative)",
  "scope": "global",
  "table": {
    "name": "aircraft_position",
    "primaryKey": ["icao24", "seenAt"],
    "timestampColumn": "seenAt",
    "columns": [
      { "name": "icao24",           "dataType": "string",    "isPrimaryKey": true },
      { "name": "callsign",         "dataType": "string",    "nullable": true },
      { "name": "registration",     "dataType": "string",    "nullable": true },
      { "name": "aircraftType",     "dataType": "string",    "nullable": true },
      { "name": "category",         "dataType": "string",    "nullable": true },
      { "name": "latitude",         "dataType": "decimal" },
      { "name": "longitude",        "dataType": "decimal" },
      { "name": "altitudeFeet",     "dataType": "int",       "nullable": true },
      { "name": "groundSpeedKnots", "dataType": "double",    "nullable": true },
      { "name": "heading",          "dataType": "double",    "nullable": true },
      { "name": "seenAt",           "dataType": "timestamp", "isPrimaryKey": true }
    ]
  },
  "ingest": {
    "mode": "poll",
    "intervalSec": 60,
    "minIntervalSec": 30,
    "request": {
      "url": "https://api.adsb.lol/v2/mil",
      "method": "GET",
      "headers": { "accept": "application/json" }
    },
    "response": { "itemsPath": "$.ac" },
    "filter": {
      "requireNonNull": ["hex", "lat", "lon"]
    },
    "mapping": {
      "icao24":          { "path": "hex" },
      "callsign":        { "path": "flight",   "transform": "trim_to_null" },
      "registration":    { "path": "r" },
      "aircraftType":    { "path": "t" },
      "category":        { "path": "category" },
      "latitude":        { "path": "lat" },
      "longitude":       { "path": "lon" },
      "altitudeFeet": {
        "path": "alt_baro",
        "transform": "value_map",
        "args": { "map": { "ground": 0 }, "passthrough": "number", "default": null }
      },
      "groundSpeedKnots": { "path": "gs",    "transform": "number_or_null" },
      "heading":          { "path": "track", "transform": "number_or_null" },
      "seenAt": {
        "path": "seen",
        "transform": "iso_from_epoch_offset",
        "args": {
          "basePath": "$.now",
          "baseUnit": "ms",
          "offsetUnit": "s",
          "direction": "subtract"
        }
      }
    }
  }
}

Ce que fait chaque bloc

Appliquer le manifeste

Téléchargez le fichier JSON lié ci-dessus, puis assemblez le corps de la requête d'application. Le chemin le plus propre utilise jq pour que le JSON soit composé de façon sûre (sans problèmes d'échappement shell) :

# 1) Téléchargez le manifeste une fois.
curl -fsS -o adsb-lol-military-declarative.json \
  http://localhost:4001/static/scrydon-pack-adsb-aircraft/adsb-lol-military-declarative.json

# 2) Composez le corps de la requête d'application et envoyez-le en POST.
jq -n \
  --arg org "$ORG" \
  --slurpfile manifest adsb-lol-military-declarative.json \
  '{ organizationId: $org, packId: "scrydon-pack-adsb-aircraft", packVersion: "1.0.0", manifest: $manifest[0] }' \
  | curl -fsS -X POST http://localhost:7500/api/table/data-sources/apply \
      -H 'content-type: application/json' \
      -H 'x-scrydon-internal-dev: 1' \
      -d @-

Réponse attendue :

{ "sourceId": "adsb-lol-military-declarative" }

Si vous préférez ne pas dépendre de jq, enregistrez le corps complet de la requête sur disque une fois et envoyez-le directement en POST :

ORG="<your-org-uuid>"
jq -n --arg org "$ORG" \
  --slurpfile manifest adsb-lol-military-declarative.json \
  '{ organizationId: $org, packId: "scrydon-pack-adsb-aircraft", packVersion: "1.0.0", manifest: $manifest[0] }' \
  > apply-body.json

curl -fsS -X POST http://localhost:7500/api/table/data-sources/apply \
  -H 'content-type: application/json' \
  -H 'x-scrydon-internal-dev: 1' \
  -d @apply-body.json

Exploiter et observer (Analytics → Sources de données)

Une fois la source instanciée dans votre environnement, tout ce qui suit est accessible en quelques clics — sans SDK, sans appels API. Voici l'expérience complète de l'opérateur pour n'importe quelle source de données, en utilisant l'exemple ADS-B comme sujet concret.

Si une synchronisation échoue

Si le Statut passe à Erreur, survolez la cellule Dernière erreur (ou lisez-la dans le panneau de détail). Les causes les plus courantes :

Aparté développeur — vérifier la ligne et l'état de synchronisation en base de données

L'interface opérateur ci-dessus est la surface supportée. Si vous développez localement et souhaitez confirmer la ligne sous-jacente directement :

SELECT source_id, status, last_sync_at, last_rows_written, last_error, consecutive_failures
FROM data_source
WHERE organization_id = :ORG;

Après une Synchronisation maintenant réussie :

       source_id            | status | last_sync_at        | last_rows_written | last_error | consecutive_failures
-----------------------------+--------+---------------------+-------------------+------------+----------------------
 adsb-lol-military-declarative | ok     | 2026-05-28 14:02:11 |               37  |            |                    0

D'où vient ce manifeste

La source TypeScript se trouve à packages/sdk-authoring/src/integrations/data-source/adsb-lol-military-declarative.ts — elle appelle defineDataSource({...}) avec la même forme. Le bundler de pack sérialise l'argument de l'appel en JSON et l'émet dans un sous-répertoire data-source/ à l'intérieur d'un .scrydon-pack.tar.gz. L'endpoint /data-sources/apply accepte ce JSON directement, ce que démontre cette page : le même manifeste, simplement sans l'enveloppe pack.

Si vous souhaitez livrer la source dans un pack plutôt que de l'appliquer manuellement, suivez le parcours Auteur dans sdks/authoring/data-sources.