Automatizări

Automatizările execută o instrucțiune conform unui program și livrează rezultatul ca sesiune chat obișnuită. Un rezumat zilnic de știri, o analiză săptămânală sau un raport lunar rulează fără interfață pe server, apare în lista de chat-uri și se deschide ca orice altă conversație.

Structură

O automatizare are un nume, instrucțiuni în text liber, unul sau mai multe declanșatoare, un model opțional (gol înseamnă Auto: modelul chat implicit la momentul execuției), o destinație și o preferință pentru notificări. Destinația stabilește rezultatul: Chat session (implicit) pune instrucțiunile în coadă ca o conversație, iar Work task pornește un sandbox izolat Work, cu instrucțiunile drept primul mesaj și, opțional, o politică nominalizată. Cu notificările activate, execuțiile eșuate apar și în centrul de notificări. Numele și instrucțiunile sunt criptate în repaus, iar automatizarea aparține creatorului ei.

Declanșatoarele folosesc modelul calendaristic — once, hourly, daily, weekly, monthly, yearly — și pot fi cel mult cinci. Următoarea execuție este cea mai apropiată apariție viitoare, calculată în fusul orar al serverului.

Execuție

Planificatorul verifică programul la fiecare minut, în spatele unui lease de coordonare, astfel încât o singură replică să avanseze calendarele. Când sosește momentul, este înregistrată o execuție, este pus job-ul durabil automation.run.v1 în coadă, iar next_run_at avansează prin compare-and-set, astfel încât fiecare apariție să fie declanșată cel mult o dată. Job-ul creează o sesiune chat cu numele automatizării și trimite instrucțiunile prin același flux durabil ca celelalte conversații, inclusiv rutarea furnizorului, valorile implicite ale personajului și stocarea.

Dacă serverul a fost oprit, următoarea verificare rulează o singură dată apariția recentă și le omite pe cele mai vechi. Pauza elimină programarea; reluarea sau editarea o recalculează. Ștergerea elimină istoricul prin foreign-key cascade.

Starea provine din registrul durabil: succes după generarea chat-ului, eșec când job-ul ajunge dead-lettered și stalled când o execuție nu începe în 30 de minute.

Destinațiile Work folosesc ciclul de viață Work, nu job-ul chat. Execuția este legată de sarcină, reușește când agentul finalizează sau solicită intervenție și eșuează la eroare/anulare. Accesul Work este verificat la declanșare; revocarea produce work-access-denied. Politica selectată este validată la salvare și limitele sale se aplică fiecărei sarcini. În Work rulează numai furnizori direcți, iar modelul trebuie să accepte instrumente.

Rutine pentru agenți

O automatizare Work poate fi legată de o sarcină existentă prin workTaskId, la fel ca secțiunea Routines din panoul agentului. Fiecare apariție pornește o execuție în spațiul de lucru și conversația existente, cu modelul, furnizorul și politica runtime ale sarcinii; câmpurile echivalente ale automatizării nu se aplică. Legătura este validată la salvare. O sarcină ștearsă produce work-task-missing, iar una deja activă sau cu preview pornit produce work-task-busy, în loc să aștepte.

Declanșatoare webhook

Dincolo de program, o automatizare poate fi declanșată de un sistem extern — un pipeline CI, un serviciu cron, automatizarea locuinței. În dialogul de editare al automatizării, Webhook trigger → Enable generează un secret pentru automatizarea respectivă; se stochează doar SHA-256 al lui, așa că textul în clar este afișat exact o dată. Rotirea secretului îl invalidează imediat pe cel anterior, iar dezactivarea webhook-ului închide la loc endpoint-ul.

Sistemul extern declanșează automatizarea cu:

curl -X POST https://your-host/api/automations/<automationId>/webhook \
  -H "Authorization: Bearer lwh_..."

(X-Libre-Webhook-Secret: lwh_... funcționează ca antet alternativ.) Răspunsul este 202 cu id-ul execuției puse în coadă — aceeași cale de rulare manuală ca Run now, deci execuțiile se încheie, notifică și apar în istoric identic. Compararea secretului se face în timp constant, o automatizare inexistentă și un secret greșit răspund identic (fără oracol pentru id-uri de automatizare), iar o automatizare suspendată răspunde 409: spre deosebire de Run now al proprietarului, un apelant extern nu poate declanșa peste o pauză.

API

Toate endpoint-urile în afară de declanșarea prin webhook necesită autentificare și operează numai asupra automatizărilor apelantului; declanșarea prin webhook se autentifică în schimb cu secretul automatizării.

Metodă	Rută	Scop
GET	/api/automations	Listează automatizările
POST	/api/automations	Creează o automatizare
GET	/api/automations/occurrences?from=&to=	Apariții viitoare
GET	/api/automations/runs	Istoricul execuțiilor
GET	/api/automations/runs/summary	Nevăzute + grupuri pe 30 de zile
POST	/api/automations/runs/seen	Marchează execuțiile încheiate ca văzute
GET	/api/automations/:automationId	Citește o automatizare
PUT	/api/automations/:automationId	Actualizează o automatizare
DELETE	/api/automations/:automationId	Șterge o automatizare
POST	/api/automations/:automationId/pause	Suspendă programul
POST	/api/automations/:automationId/resume	Reia programul
POST	/api/automations/:automationId/run	Rulează imediat (202 cu id)
POST	/api/automations/:automationId/webhook	Declanșează prin secret (202)
POST	/api/automations/:automationId/webhook-secret	Generează/rotește secretul
DELETE	/api/automations/:automationId/webhook-secret	Dezactivează webhook-ul

Un utilizator poate păstra cel mult 50 de automatizări. Numele sunt limitate la 200 de caractere, iar instrucțiunile la 20.000.