Migrator (migracje) — API v1 i MCP | Dokumentacja API Nodea

Moduł Migrator przenosi monitoring, kontakty, strony statusu i encje WHMCS z zewnętrznych dostawców do Nodea. Bieg migracji (MigratorRun) przechodzi cykl: start → discovery (odczyt zasobów przez API dostawcy) → przegląd → wykonanie (plan + import). Dokument opisuje warstwę REST API v1 (/api/v1) oraz narzędzia MCP z tego modułu.

Uwierzytelnianie i zakresy (scopes)

API v1 uwierzytelnia się osobistym tokenem Passport przez nagłówek Authorization: Bearer <token>. Trasy tego modułu są chronione zakresem konta odpowiadającym poziomowi operacji:

account:read — listowanie, podgląd, logi.
account:write — start biegu, wykonanie, ponowienie nieudanych zasobów.
account:delete — trwałe usunięcie biegu (kaskada zasobów i logów).

Cały moduł jest dodatkowo bramkowany flagą Pennant features:migrator — wyłączenie ukrywa go w web UI i w API. Limit zapytań: throttle:api-v1 = 240/min na użytkownika tokenu. Dodatkowo start biegu jest limitowany do 5 prób na minutę na użytkownika (wspólny budżet z web i MCP, kod discovery_rate_limited / 429). W MCP każde narzędzie wymaga też zakresu transportowego mcp:use oraz flagi migrator.

Własność i widoczność (ownership)

Biegi migracji nie mają klasy polityki ani modelu współdzielenia — każdy dostęp jest twardo ograniczony do właściciela przez user_id. Cudzy lub nieznany identyfikator zwraca konsekwentnie 404 (a nie 403), więc API nigdy nie potwierdza istnienia cudzego biegu. W MCP odpowiada temu jeden komunikat „nie znaleziono lub brak dostępu”. Identyfikator biegu to UUID (string).

Bezpieczeństwo danych wrażliwych

Poświadczenia dostawcy źródłowego są wyłącznie do zapisu (write-only): przyjmowane przy starcie biegu, przechowywane zaszyfrowane (encrypted:json + $hidden na modelu) i nigdy niezwracane przez żaden zasób. Wewnętrzne kolumny — wznawialny kursor checkpoint, surowy blob plan, wewnętrzne discovery_summary, credentials_purge_at — także nie są eksponowane. Zasoby biegu nie ujawniają surowych blobów dostawcy (external_data/normalized_data) ani wewnętrznego powiązania importu (target_model/target_id).

Efekty uboczne — asynchroniczne i stan biegu

Start, wykonanie i ponowienie działają out-of-band przez kolejkę (dedykowane kolejki discovery/planning/resources) — akcje zwracają 202 Accepted, a właściwy start biegu 201 Created z zasobem. Wykonać można tylko bieg w stanie awaiting_review (inaczej 422, kod run_not_awaiting_review). Ponowienie odrzuca się, gdy nie ma nieudanych zasobów (422, kod no_failed_resources).

API v1 — endpointy

Metoda	Ścieżka	Scope	Opis
GET	/api/v1/migrations	account:read	Lista biegów właściciela (najnowsze pierwsze), paginowana. Filtry `status`, `provider`. Każdy wiersz: `total_resources`, `failed_resources`.
GET	/api/v1/migrations/{run}	account:read	Szczegóły biegu z zasobami (cap 500) oraz `meta.resource_counts` (rozkład per status).
GET	/api/v1/migrations/{run}/logs	account:read	Dziennik biegu (najnowsze pierwsze), paginowany. Filtr `errors_only`.
POST	/api/v1/migrations	account:write	Start biegu (`provider` + `credentials` write-only). Kolejkuje discovery. Zwraca `201`; limit 5/min → `429`.
POST	/api/v1/migrations/{run}/execute	account:write	Wykonanie biegu (plan + import). Tylko stan `awaiting_review`. Zwraca `202`/`422`.
POST	/api/v1/migrations/{run}/retry-failed	account:write	Ponowienie nieudanych zasobów (reset do pending + redispatch). Zwraca `202` z `retried`; brak nieudanych → `422`.
DELETE	/api/v1/migrations/{run}	account:delete	Trwałe usunięcie biegu (kaskada). Zwraca `204`.

GET /migrations — parametry zapytania

status (enum, opcjonalny) — pending, discovering, awaiting_review, executing, paused_conflicts, completed, completed_with_errors, failed, cancelled.
provider (enum, opcjonalny) — uptime_robot, statuscake, pingdom, better_stack, oh_dear, hetrix_tools, site24x7, whmcs, phpipam.
per_page (int 1–100, domyślnie 20), page (int ≥1).

Wiersz biegu (MigrationRunResource): id (UUID), provider, status, stats, total_resources, failed_resources, error_message, started_at, finished_at, created_at, updated_at. Szczegóły dokładają resources[] (zasób: id, resource_type, external_id, action, status, attempts, error_message). Log (MigrationLogResource): id, level, message, context, logged_at.

POST /migrations — parametry ciała

provider (string, wymagany) — jeden z dostawców powyżej.
credentials (obiekt klucz→string, opcjonalny) — write-only. Pola wymagane zależą od dostawcy: schemat credentials_schema z config/migrator.php wymusza obecność pól oznaczonych jako required (brak → 422 na credentials.<pole>).

Kody błędów

401 — brak/niepoprawny token.
403 — brak wymaganego scope.
404 — nieznany lub cudzy bieg.
422 — walidacja, wykonanie biegu spoza awaiting_review (run_not_awaiting_review), brak nieudanych zasobów do ponowienia (no_failed_resources).
429 — przekroczony limit startów (discovery_rate_limited).

Przykłady — API

Lista biegów z filtrem statusu i dostawcy

curl -s "https://app.nodea.io/api/v1/migrations?status=awaiting_review&provider=uptime_robot" \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"

Start biegu migracji (poświadczenia write-only)

curl -s -X POST https://app.nodea.io/api/v1/migrations \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "uptime_robot",
    "credentials": { "api_key": "u123456-abcdef..." }
  }'

Wykonanie zrewidowanego biegu

curl -s -X POST https://app.nodea.io/api/v1/migrations/{run}/execute \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"

Ponowienie nieudanych zasobów

curl -s -X POST https://app.nodea.io/api/v1/migrations/{run}/retry-failed \
  -H "Authorization: Bearer $NODEA_TOKEN" \
  -H "Accept: application/json"

MCP — narzędzia

Narzędzia MCP dzielą model uwierzytelniania i zakresów z API v1 (Bearer + scope w ensureScope) oraz flagę migrator (narzędzie na nieaktywnej fladze znika z tools/list). Identyfikator biegu to UUID (string). Brakujący i cudzy identyfikator zwracają ten sam błąd. Start, wykonanie i ponowienie są asynchroniczne (potwierdzenie zlecenia). Narzędzie niszczące migration-delete jest oznaczone jako destructive i wymaga jawnego confirm: true. Poświadczenia dostawcy pozostają write-only.

Nazwa	Scope	Tryb	Opis
migrations-list	account:read	read-only	Lista biegów (najnowsze pierwsze) z `total_resources`/`failed_resources`. Filtry `status`, `provider`; `page`, `per_page` (max 50).
migration-get	account:read	read-only	Szczegóły biegu: nagłówek, zasoby (cap 500), 50 ostatnich logów i `resource_counts`. Param: `id`. Poświadczenia nigdy nie wracają.
migration-create	account:write	zapis	Start biegu; `provider`, `credentials` (obiekt, write-only). Kolejkuje discovery. Limit 5/min.
migration-execute	account:write	zapis	Wykonanie biegu (plan + import); `id`. Tylko stan `awaiting_review`.
migration-retry-failed	account:write	zapis	Ponowienie nieudanych zasobów; `id`. Odrzucone, gdy brak nieudanych.
migration-delete	account:delete	destrukcyjne (confirm)	Trwałe usunięcie biegu wraz z zasobami i logami. Wymaga `confirm: true`; `id`.

Przykłady — MCP (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "migration-create",
    "arguments": {
      "provider": "uptime_robot",
      "credentials": { "api_key": "u123456-abcdef..." }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "migration-delete",
    "arguments": { "id": "9b1f...uuid", "confirm": true }
  }
}

Migrator — API v1 i MCP | Dokumentacja Nodea