@Atlas Channels API

Distribution layer for @Atlas across multiple channels.

Ce fichier vivait dans src/app/api/channels/README.md. Le retrait du canal REST (security-identity/0271) a vide ce repertoire de tout code, et src/test/ownership-map-is-real.test.ts refuse — a raison — qu'un repertoire ne contenant qu'un README soit revendique comme un module. Aucun des canaux decrits ici n'a jamais vecu sous api/channels/ : ils sont sous /api/chat, /api/webhooks/[platform] et /api/mcp/v1/.

Channels

Ce que chaque canal reserve avant de streamer

Un canal metre est un canal qui reserve. La lecture simple (getCreditBalance puis balance <= 0) est un read-then-allow : N tours simultanes lisent le meme solde et chacun peut le depenser en entier, ce qui laisse l'organisation a un decouvert complet par tour supplementaire. reserveCreditsForChannel prend un verrou consultatif par organisation, relit le solde dessous, et insere une ligne Credit de type hold avant de le relacher : le tour suivant voit un solde deja diminue.

La voix a ete le dernier chemin a ne faire qu'une lecture, et c'est celui ou la course est la plus facile a declencher : Hume ouvre une requete CLM par enonce.

Le canal voix exige un orgId resolu avant d'exister : GET /api/chat/voice signe la session avec getOrgAccess / getStoreAccess, et refuse (403 NOT_A_MEMBER / STORE_NOT_IN_ORG) un appelant qui nomme une organisation ou une boutique qu'il n'atteint pas. Avant ai-platform/0597 la route lisait OrganizationMember a la main : le proprietaire d'une organisation heritee, qui n'a pas de ligne membre, recevait une session signee VIDE, que le CLM servait sans solde a debiter. Le micro fonctionnait, et personne n'etait facture.

Une reservation se regle sur les trois sorties, jamais sur une seule. onFinish passe holdId a trackUsage, qui ecrit l'usage et supprime le hold dans la meme transaction. onAbort fait la meme chose avec la somme des etapes DEJA finies : le SDK n'appelle pas onFinish sur un abort, donc sans ce rappel un plafond dur perdait a la fois la consommation partielle et la reservation. onError libere, sauf si des etapes ont deja consomme des jetons, auquel cas il facture ce partiel (voir runtime/handler-error-settlement.ts). Un verrou usageSettled garantit une seule ligne d'usage : une seconde serait un double debit reel.

Chat SDK (unified)

WhatsApp (and future platforms) use the Vercel Chat SDK (chat@4.23).

• Dynamic webhook: src/app/api/webhooks/[platform]/

Le bot Chat SDK vit dans src/features/ai/bot/ : bot.ts (singleton paresseux + adaptateur WhatsApp), bot-handlers.ts (prompt @Atlas, outils de recherche, rate limit par thread, historique, persistance et debit de credits) et whatsapp-per-store.ts (canal par boutique, scopes Shopify). Cette section a affirme jusqu'au 2026-09-05 que ces fichiers « n'ont jamais ete ecrits » : c'etait faux. Le webhook ci-dessus ne fait que router vers eux ; ajouter une plateforme veut dire ajouter un adaptateur dans bot.ts et un handler dans bot-handlers.ts.

TODO

WhatsApp Channel

• Meta Business Account setup + verification
• Dedicated WhatsApp phone number
• Environment variables (WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_BUSINESS_ACCOUNT_ID, WHATSAPP_ACCESS_TOKEN, WHATSAPP_VERIFY_TOKEN)
• HMAC-SHA256 webhook signature validation (crypto)
• Conversation persistence (database)
• Conversation history in AI context (multi-turn)
• Message delivery status tracking (sent/delivered/read)
• Rate limiting (Meta allows ~80 msgs/sec)
• Media message support (images, documents)
• Human escalation flow (notify Christopher)
• Knowledge base injection (Shopify docs, BoostEcom FAQ)
• Credit deduction per message
• WhatsApp template messages for outbound (proactive)
• Error retry logic with exponential backoff

API Channel (retire)

POST /api/channels/api a ete supprime le 2026-09-05 (security-identity/0271). Sa seule authentification etait une credential sk_ conservee dans une Map de processus : aucune cle n'a jamais survecu a une frontiere de requete, donc la route a repondu 401 a chaque appel depuis le jour de sa mise en ligne. La premiere case de cette liste, « API key validation against database », n'a jamais ete cochee, et c'est exactement ce qui manquait.

La position publique est la meme : « Is there a REST API? Not yet, and we would rather say so than sell one. » Les surfaces programmatiques supportees sont le MCP par boutique, le MCP Intelligence public et l'API REST Intelligence avec ses propres cles.

Ce qu'un vrai canal REST exigerait avant d'exister a nouveau est ecrit dans backlog/security-identity/0353 et la decision dans docs/decisions/0007.

• SDK client libraries (TypeScript, Python)
• Streaming SSE support
• Webhook callbacks for async responses

Database

ChannelDatabaseOperations n'existe plus, et src/types/channels.ts non plus (dead-code-duplication-10) : c'etait 284 lignes et 22 types exportes par le barrel global src/types, zero implementation et zero lecteur, dont un WhatsAppWebhookPayload que le vrai webhook (api/webhooks/[platform]) ne connaissait pas. Cette case a coche etait la seule reference au symbole dans tout le depot. Un futur provider definira son contrat la ou il vit, pas dans un barrel de types partage.

• Definir le contrat de persistance a cote du provider qui l'implemente
• SQL migrations for channels, conversations, messages tables
• Indexes for conversation lookup by external ID
• Message archiving and cleanup (90-day retention)

Platform UI

• Channel management page in team settings
• WhatsApp configuration wizard
• API key + channel binding UI
• Conversation viewer/dashboard
• Real-time message monitoring
• Analytics: messages/day, response time, escalation rate

Infrastructure

• Vercel deployment: webhook URL must be HTTPS
• Environment variable management
• Monitoring: webhook failures, API latency
• Logging: structured logs for debugging