History

Moduł History to wspólna historia zdarzeń firmy (od SDK 3.10.0). Historia to tylko dopisywany rejestr tego, co się wydarzyło z obiektami biznesowymi firmy: zamówienie zostało utworzone, status się zmienił, przesyłka została nadana. Wszystkie moduły piszą do tego samego rejestru, a użytkownik czyta go w Ustawienia → Historia, filtrując po module źródłowym i po module, którego zdarzenie dotyczy.

Nie jest to ani Log, ani Problems. Logi służą diagnostyce technicznej dla programisty. Problems to bieżąca lista rzeczy, które użytkownik musi naprawić — wpisy deduplikują się po problemKey i znikają po resolve. Historia jest niezmiennym śladem audytowym: wpisu nie da się zmienić ani skasować, a każde add dopisuje kolejny.

const { History } = require('@orbito/api-lib');

History.add({ code, desc, relations, userId? })   // -> { _id } albo null
History.list(filters?)                            // -> { items, pagination }

Parametry History.add:

Historia nie ma odpowiednika update ani delete — poprawkę zapisujesz jako kolejne zdarzenie.

History.add

Dopisuje wpis do historii firmy. Zwraca { _id } nowego wpisu. Wołaj ją po tym, jak opisywana zmiana faktycznie się wydarzyła.

const { History } = require('@orbito/api-lib');

await History.add({
    code: 'ORDER_STATUS_CHANGED',
    desc: {
        pl: `Status zmieniony z „${from.name}” na „${to.name}”`,
        en: `Status changed from "${from.name}" to "${to.name}"`
    },
    relations: [{ module: 'core/orders', object: 'order', id: String(order._id) }],
    userId: this.userId
});

Zdarzenie dotyczące kilku encji — przesyłka utworzona w core.shipping dla zamówienia z core.orders — podaje obie relacje, dzięki czemu pojawi się zarówno w historii przesyłki, jak i w historii zamówienia:

await History.add({
    code: 'SHIPMENT_CREATED',
    desc: {
        pl: `Utworzono przesyłkę ${shipment.number} (${carrier.name})`,
        en: `Shipment ${shipment.number} created (${carrier.name})`
    },
    relations: [
        { module: 'core/shipping', object: 'shipment', id: String(shipment._id) },
        { module: 'core/orders', object: 'order', id: String(shipment.orderId) }
    ],
    userId: this.userId
});

Zdarzenie wywołane bez udziału użytkownika (cykliczne pobranie statusów, hook, automatyzacja) po prostu pomija userId — jeśli wywołanie wyszło z biegu automatyzacji, SDK samo dopisze do wpisu jego pochodzenie:

await History.add({
    code: 'SHIPMENT_STATUS_CHANGED',
    desc: {
        pl: `Status przesyłki ${shipment.number} zmieniony na „${status}”`,
        en: `Shipment ${shipment.number} status changed to "${status}"`
    },
    relations: [{ module: 'core/shipping', object: 'shipment', id: String(shipment._id) }]
});

Pochodzenie wpisu (automatyzacja)

(od SDK 4.3.0)

Wpis zapisany w wyniku akcji automatyzacji niesie pole origin — panel pokazuje wtedy w kolumnie użytkownika nazwę automatyzacji z linkiem do konkretnego biegu (oś czasu w Ustawienia → Automatyzacje → Biegi), a nie „system”. Ten sam link pojawia się w historii zamówienia w module zamówień.

origin: {
    type: 'automation',
    automationId: '66f0...',          // _id automatyzacji
    automationName: 'Wysyłka po opłaceniu',   // nazwa w chwili biegu (snapshot)
    runId: '66f1...:cron:2026-10-06T08:00:00.000Z'   // klucz biegu (string, nie ObjectId)
}

origin jest null dla wpisów użytkownika i zdarzeń systemowych. automationName to migawka z chwili biegu — późniejsza zmiana nazwy albo usunięcie automatyzacji nie zmienia wpisu (historia jest niezmienna).

Moduł niczego nie przekazuje. History.add nie przyjmuje origin w parametrach (rdzeń wycina takie pole z payloadu). Pochodzenie dokleja samo SDK z kontekstu wywołania:

• w execute akcji automatyzacji (Automation),
• w handlerach metod i hooków osiągniętych z takiej akcji przez Core.callModule / Core.callInstanceMethod / Core.execHook — także w innych modułach i dalej w łańcuchu, np. akcja core/orders zmienia status → hook → core/shipping zapisuje wpis o przesyłce z tym samym biegiem.

Dzięki temu wystarczy podbić @orbito/api-lib do ^4.3.0 — kod modułu się nie zmienia. Wpis z biegu automatyzacji nie ma userId, nawet gdy bieg wyzwolił użytkownik: liczy się to, że akcję wykonała automatyzacja.

History.list

(od SDK 3.12.0)

Czyta historię zdarzeń, stosując te same filtry co strona Ustawienia → Historia (GET /history). Wynik jest stronicowany i posortowany od najnowszych wpisów.

Parametry History.list — wszystkie opcjonalne, łączone przez AND; bez żadnego z nich wywołanie przechodzi po całej historii firmy:

Zwraca { items, pagination }:

• items[] — wpisy w kształcie { _id, source: { moduleCode, instanceId, instanceName }, code, desc, relations, userId, user: { _id, firstname, lastname } | null, origin, at }. desc i relations są dokładnie takie, jak przekazane do add; user to dane autora dociągnięte przez rdzeń (null dla zdarzeń systemowych albo usuniętego użytkownika); origin to pochodzenie wpisu albo null. Identyfikatory i daty przychodzą jako stringi (at to ISO string), bo wynik podróżuje jako JSON.
• pagination — { page, limit, total }. Gdy total jest większe niż liczba elementów w items, zwrócona strona nie obejmuje całej historii.

Przykład — historia własnej encji razem ze zdarzeniami dopisanymi przez inne moduły:

// historia zamówienia, razem ze zdarzeniami core/shipping i core/invoicing,
// jeśli te dodały do swoich wpisów relację do tego zamówienia
const { items, pagination } = await History.list({
    module: 'core/orders', object: 'order', id: String(order._id),
    limit: 200
});

if (pagination.total > items.length) {
    // pobrana strona nie obejmuje całej historii — widoczne są tylko najnowsze wpisy
}

Dobre praktyki

Opis pisz dla użytkownika i od razu po ludzku – z historii ma dać się przeczytać, co się stało, bez zaglądania do kodu modułu. Wartości, które się zmieniły, wpleć w zdanie; surowych danych zdarzenie nie przenosi.

// ❌ Nigdy
desc: 'ORDER_STATUS_CHANGED'
desc: JSON.stringify({ from, to })

// ✅ Zamiast tego
desc: { pl: `Status zmieniony z „${from.name}” na „${to.name}”`, en: `Status changed from "${from.name}" to "${to.name}"` }

Każdy code powinien znaczyć jedno – to po nim filtrujesz listę i rozpoznajesz zdarzenia swojego modułu. Używaj stałego zestawu kodów w UPPER_SNAKE_CASE (ORDER_STATUS_CHANGED, SHIPMENT_CREATED), a nie treści opisu przepisanej na kod.

Wskaż wszystkie encje, których zdarzenie dotyczy – jeśli operacja łączy dwa obiekty, podaj obie relacje. Wpis z jedną relacją nie pojawi się w historii tej drugiej encji, a historii nie da się później poprawić.

// ❌ Nigdy
relations: [{ module: 'core/shipping', object: 'shipment', id }]   // utworzenie przesyłki dla zamówienia

// ✅ Zamiast tego
relations: [
    { module: 'core/shipping', object: 'shipment', id },
    { module: 'core/orders', object: 'order', id: orderId }
]

Zapisuj zdarzenia biznesowe, a nie kroki techniczne – historia jest dla użytkownika. Ponowienie zapytania do API, odświeżenie tokenu czy szczegóły odpowiedzi zewnętrznego serwisu zostaw Log, a sytuacje, które użytkownik musi naprawić — Problems.

Nie loguj zdarzenia, które się nie wydarzyło – add wołaj po udanym zapisie zmiany, nie przed. Historia jest niezmienna, więc wpisu o nieudanej operacji nie da się wycofać.