Orbito Orders managment

@orbito/api-lib (3.11.0)

Published 2026-09-23 12:04:12 +02:00 by wiktor

Installation

@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/
npm install @orbito/api-lib@3.11.0
"@orbito/api-lib": "3.11.0"

About this package

Na razie w kodzie modułu, ale docelowo do będzie standalone biblioteka do pobrania z npm

Orbito API

API obsługujące protokół binarny

Tozsamosc modulu i multi-instancja

Jeden kontener = jedna instancja modulu (ModuleInstance) = jedna firma. Firma moze zainstalowac ten sam modul wiele razy (np. trzy sklepy Prestashop) - kazda instalacja to osobny kontener z wlasna tozsamoscia i wlasnymi danymi.

companyId i instanceId sa ustalane przez rdzen z tokenu polaczenia; SDK nigdy ich nie wysyla i nie ma ich w zadnym przychodzacym payloadzie. Modul odczytuje je z odpowiedzi rejestracji:

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

Core.getCompanyId();   // firma obslugiwana przez ten kontener
Core.getInstanceId();  // tozsamosc TEJ instalacji modulu
Core.getModuleInfo();  // { instanceId, companyId, code, version }

Core.getUser(ctx.userId); // dane usera z firmy kontenera albo null

Core.getUser(userId) zamienia ctx.userId (jedyne, co handler metody dostaje o userze) na { id, firstname, lastname, email, isDisabled, isOwner, profile }. Zakres jest zawezony do firmy kontenera - user spoza niej, nieistniejacy albo usuniety daje tak samo null.

Wywolania miedzy modulami

// adresowanie po kodzie modulu - jednoznaczne tylko przy JEDNEJ instancji
try {
    await Core.callModule('core/prestashop', 'syncOrders', {});
} catch (err) {
    if (err.code !== 'AMBIGUOUS_MODULE_TARGET') throw err;
    // firma ma kilka instalacji - trzeba wskazac konkretna
    await Core.callInstanceMethod(shopInstanceId, 'syncOrders', {});
}

Wyjatek rzucony w handlerze metody (Core.registerMethod) wraca do wolajacego jako wyjatek - SDK odsyla go osobnym kanalem bledu (odpowiedz z dwoma parametrami: marker __orbitoError i komunikat), a rdzen rzuca z niego Error u wolajacego; to samo dotyczy wywolania nieistniejacej metody. Poprawny wynik to dalej dokladnie jeden parametr odpowiedzi, wiec try/catch wokol callModule / callInstanceMethod wystarcza, zeby zlapac blad drugiego modulu (wymaga SDK

= 3.7.0 po stronie wolanego modulu).

Kto mnie wywolal (this.caller)

Przy ruchu modul->modul rdzen dokleja tozsamosc wolajacego. Nie jest ona argumentem handlera - trafia jako this, wiec kontekst jest opcjonalny:

// nie potrzebuje kontekstu - funkcja strzalkowa
Core.registerHook('event:order:created', async (order) => {
    await saveOrder(order);
});

// potrzebuje kontekstu - zwykla function
Core.registerHook('event:order:created', async function (order) {
    // this.caller = { instanceId, moduleCode, instanceName } albo null (wolal rdzen)
    await saveOrder(order, { sourceInstanceId: this.caller?.instanceId });
});
  • Handlery metod dostaja kontekst rowniez pozycyjnie: async (params, ctx) => ... (tam liczba argumentow jest stala, wiec jest to bezpieczne).
  • this.caller jest budowane przez rdzen z tozsamosci polaczenia - wolajacy nie moze go podrobic.
  • Function.prototype.bind ma pierwszenstwo przed bindowaniem SDK - jesli potrzebujesz this.caller, rejestruj zwykla function, a nie obj.fn.bind(obj).

Automatyzacje a instancje

Schemat akcji/triggera jest wspolny dla modulu, ale pojedyncza automatyzacja dziala na JEDNEJ instancji. Rdzen dokleja do schemy parametrow zarezerwowane pole __instanceId (lista aktywnych instancji firmy w edytorze automatyzacji), routuje execute/nameGenerator/enable/disable do kontenera wybranej instancji (budzac go w razie potrzeby) i zdejmuje ten parametr przed wyslaniem payloadu - handler dostaje wylacznie wlasne parametry.

Automation.registerAction('sync_order', {
    displayName: 'Wyslij zamowienie do sklepu',
    params: { orderId: { type: PropertyType.STRING, name: 'Zamowienie' } },
    // __instanceId nie dociera tutaj - wywolanie juz trafilo do wlasciwej instancji
    execute: async (params, ctx) => sync(params.orderId, ctx.automationId)
});
  • Wlasny parametr o nazwie __instanceId przeslonilby pole rdzenia i zepsul routing - registerAction/registerTrigger rzucaja wtedy bledem przy starcie.
  • Listenery triggerow kluczuj po (triggerCode, actionId) - zdarzenie zgloszone przez callTrigger rdzen przypisuje do instancji po tozsamosci polaczenia.
  • clear (0x44) jako jedyna trafia do wszystkich dzialajacych kontenerow modulu.

DB - szybki start

Modul DB udostepnia proste operacje na kolekcjach (find, insert, update, delete) oraz klase Schema, ktora waliduje dane przed zapisem i pozwala definiowac hooki.

Definicja schematu

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

const OrdersSchema = new DB.Schema('orders', {
	orderNumber: { type: 'string', required: true },
	cart: { type: 'array', items: { type: 'object' }, default: [] },
	total: { type: 'number', default: 0 },
	createdAt: { type: 'date', default: () => new Date() }
});

OrdersSchema.pre('validate', function(data) {
	if (data.cart && Array.isArray(data.cart)) {
		data.total = data.cart.reduce((sum, item) => sum + (item.price * item.quantity), 0);
	}
});

OrdersSchema.post('create', function(doc) {
	// np. emit event po utworzeniu
});

DB.createIndex('orders', { orderNumber: 1 }, { unique: true });

module.exports = OrdersSchema;

Operacje na danych

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

// create z walidacja schematu
const doc = await OrdersSchema.create({
	orderNumber: 'ORD-123',
	cart: [{ price: 10, quantity: 2 }]
});

// find / findOne
const list = await OrdersSchema.find({}, 50, 0, { createdAt: -1 });
const one = await OrdersSchema.findOne({ orderNumber: 'ORD-123' });

// update
const result = await OrdersSchema.update({ _id: doc._id }, { $set: { total: 30 } });

// delete
const deleted = await OrdersSchema.delete({ _id: doc._id });

Uwagi

  • Schema automatycznie mapuje ObjectId w definicji na validator objectID.
  • W find (schemat) string w formacie 24-hex zostanie rzutowany na ObjectId, jesli pole w schemacie ma typ ObjectId.
  • Operacje DB.find/insert/update/delete/createIndex dzialaja bezposrednio na kolekcjach.
  • Nazwy kolekcji sa logiczne/surowe (np. "orders") - rdzen sam dokleja namespace {instanceId}_{collection}. Nie prefiksuj kolekcji companyId ani instanceId i nie dodawaj ich do filtrow zapytan - izolacja danych jest wymuszana przez rdzen. Kazda instalacja modulu (instancja) ma wlasne, odseparowane kolekcje - dwa sklepy tego samego modulu nie widza nawzajem swoich danych.

Config - zmienne konfiguracyjne modulu

Modul Config to generyczny magazyn konfiguracji przechowywany przez rdzen (per instancja modulu). Konfiguracja przezywa wylaczenie/wlaczenie modulu oraz aktualizacje wersji. Wartosci moga byc dowolnymi typami BSON (max 64 KB) - wieksze dane trzymaj w DB.

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

// config globalny instancji modulu
await Config.set('inpost.api_key', 'abc123');
let apiKey = await Config.get('inpost.api_key');
let mode = await Config.get('inpost.mode', 'sandbox'); // wartosc domyslna gdy klucz nie istnieje

// config per uzytkownik (userId zwykle z ctx.userId)
await Config.forUser(ctx.userId).set('print_label', true);
let autoPrint = await Config.forUser(ctx.userId).get('print_label', false);

// pozostale operacje
let all = await Config.getAll();            // { 'inpost.api_key': 'abc123', ... }
await Config.delete('inpost.api_key');      // true gdy klucz istnial
  • Scope (instancja modulu) wynika z tozsamosci polaczenia - modul nie ma dostepu do konfiguracji innych firm, innych modulow ani innych instalacji tego samego modulu (dwa sklepy maja osobne klucze API).
  • Scope globalny i scope'y per-uzytkownik sa calkowicie rozlaczne (getAll() nie zwraca wpisow per-uzytkownik).
  • get zwraca wartosc domyslna tylko gdy klucz NIE istnieje - zapisany null jest zwracany jako null.
  • Brak cache po stronie SDK - kazdy get to odczyt z rdzenia, dzieki czemu wiele procesow tego samego modulu zawsze widzi spójne wartosci.

Config blocks - deklaratywna konfiguracja modulu

Zamiast budowac wlasna strone ustawien, modul deklaruje bloki konfiguracyjne - frontend Orbito renderuje z nich generyczny formularz (format schemy wspolny z automatyzacjami, patrz DeclarativeSchema.js). Po pozytywnej walidacji rdzen sam zapisuje wartosci do config store pod kluczami ${blockKey}.${fieldKey}.

const { Config } = require('@orbito/api-lib');
const { PropertyType, DisplayFormat } = Config;

Config.registerConfigBlocks({
    general: {
        title: { pl: 'Ustawienia polaczenia', en: 'Connection settings' },
        scope: 'global', // jeden zestaw wartosci per firma
        schema: async (actualConfig) => ({
            apiKey: { type: PropertyType.STRING, format: DisplayFormat.SECRET, name: 'Klucz API', required: true },
            hint:   { type: PropertyType.INFO, name: 'Klucz znajdziesz w panelu uslugi' } // tylko do wyswietlania, nie jest zapisywane
        }),
        validate: async (params, raport) => {
            if (!params.apiKey) raport.addError('apiKey', 'Klucz API jest wymagany');
        }
    },
    print: {
        title: { pl: 'Preferencje wydruku', en: 'Print preferences' },
        scope: 'user', // kazdy uzytkownik edytuje swoje wartosci
        schema: { autoPrint: { type: PropertyType.BOOLEAN, name: 'Drukuj automatycznie' } }
    }
});

// odczyt w metodach modulu - klucz bloku jest prefiksem:
let apiKey = await Config.get('general.apiKey');
let autoPrint = await Config.forUser(ctx.userId).get('print.autoPrint', false);
  • title.en jest wymagane (jezyk zapasowy); title moze byc tez stringiem.
  • schema to obiekt albo (async) funkcja (actualConfig) => schema - zestaw pol moze zalezec od obecnej konfiguracji.
  • validate (opcjonalne) dostaje KOMPLETNE dane bloku po zapisie (sekrety juz podstawione) i raportuje bledy przez raport.addError(field, message) - jakikolwiek blad odrzuca zapis.
  • Wartosci pol SECRET nigdy nie wracaja do frontu; puste pole SECRET przy zapisie oznacza "bez zmian".
  • Schematy i validate zostaja w module (rdzen pyta o nie on-demand), ale METADANE blokow (klucz/tytul/scope) sa wysylane do rdzenia przy rejestracji i automatycznie ponownie po reconnect - dzieki temu rdzen wie, ze modul ma konfiguracje (przycisk "Konfiguruj"), bez budzenia kontenera.

Akcje bloku - buttony przy formularzu

Blok moze wystawic actions - buttony, ktore frontend renderuje przy formularzu (np. w stopce bloku). Klikniecie wykonuje handler w module, a strona configa domyslnie pobiera blok ponownie, wiec dynamiczna schema od razu pokazuje efekt.

Config.registerConfigBlocks({
    rules: {
        title: { pl: 'Reguly wysylki', en: 'Shipping rules' },
        schema: async (actualConfig) => buildRulesSchema(actualConfig), // pola per regula
        actions: {
            addRule: {
                title: { pl: 'Dodaj nowa regule', en: 'Add new rule' },
                style: Config.ActionStyle.PRIMARY,
                handler: async (actualConfig, ctx) => {
                    await addEmptyRule(actualConfig);
                    return { message: 'Dodano regule' }; // success i needReload domyslnie true
                }
            },
            clearRules: {
                title: { pl: 'Usun wszystkie reguly', en: 'Remove all rules' },
                style: Config.ActionStyle.DANGER,
                confirm: { pl: 'Na pewno usunac wszystkie reguly?', en: 'Really remove all rules?' },
                handler: async () => { await clearRules(); } // brak returna = sukces + reload
            }
        }
    }
});
  • handler(actualConfig, ctx) dostaje ZAPISANE wartosci bloku (te same, ktore dostaje dynamiczna schema) - nie widzi niezapisanego stanu formularza. ctx to { userId } wywolujacego (jest tez zbindowany jako this).
  • Wynik { success, message, needReload } - wszystkie pola opcjonalne: success domyslnie true (zwroc false przy niepowodzeniu biznesowym), message frontend pokazuje uzytkownikowi, needReload domyslnie true (blok pobierany ponownie); wyjatek z handlera wraca jako { success: false, message: error.message }.
  • confirm (string albo mapa jezykowa) wlacza dialog potwierdzenia przed wykonaniem akcji, style to podpowiedz wygladu (Config.ActionStyle: DEFAULT/PRIMARY/DANGER).
  • actions moze byc tez (async) funkcja (actualConfig) => actions - zestaw buttonow moze zalezec od configu (np. "Rozlacz konto" tylko gdy polaczone). Akcji spoza aktualnego zestawu nie da sie wykonac.
  • Metadane akcji jada razem ze SCHEMA (nie z metadanymi blokow), wiec moga byc dynamiczne, a lista blokow i hasConfig nadal nie budza kontenera.

Mail - wysylanie e-maili

Modul Mail wysyla e-maile przez rdzen Orbito. Rdzen opakowuje tresc w szablon brandingowy (logo + stopka "Wiadomosc wyslana przez modul X w systemie Orbito") i wysyla przez serwer nadawczy wybrany przez firme: globalny serwer Orbito albo wlasny SMTP firmy (konfigurowany w ustawieniach firmy). Modul nie wybiera transportu sam - firma i tozsamosc modulu wynikaja z polaczenia.

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

await Mail.sendMail(
    'klient@example.com',
    'Twoje zamowienie zostalo wyslane',
    '<p>Zamowienie <b>#1234</b> zostalo nadane.</p>',
    { title: 'Zamowienie wyslane', replyTo: 'sklep@firma.pl' } // opcjonalne
);
  • content to WNETRZE szablonu - nie wysylaj pelnego dokumentu HTML (bez <html>/<body>).
  • Limity rdzenia: tresc max 256 KB, bez zalacznikow, max 30 maili/min na firme.
  • Gdy firma uzywa wlasnego SMTP, bledy jej serwera sa propagowane do modulu - nie ma cichego fallbacku na serwer Orbito.

Files - bucket plikow instancji modulu

Kazda instalacja modulu dostaje wlasny bucket na pliki - dokladnie tak samo jak dostaje wlasne kolekcje {instanceId}_*. Trzy instalacje tego samego modulu maja trzy niezalezne buckety, a odinstalowanie instancji kasuje jej pliki razem z danymi. Tozsamosc instancji rdzen bierze z polaczenia, wiec zadne wywolanie nie podaje instanceId - modul nie ma jak siegnac do cudzego bucketu.

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

await Files.upload('./assets/logo.png');                    // name = "logo.png"
await Files.upload('./assets/manual.pdf', { name: 'docs/manual.pdf' });
await Files.upload(thumbBuffer, { name: `miniatures/${productId}`, mime: 'image/jpeg' });

await Files.list('miniatures/');   // [{ name, sha256, size, mime, createdAt, updatedAt }]
await Files.get('logo.png');       // { buffer, name, sha256, size, mime } albo null
await Files.exists('logo.png');    // bool (bez pobierania tresci)
await Files.remove(`miniatures/${productId}`); // bool - false, gdy nie bylo czego kasowac
  • Nazwa jest kluczem w buckecie. Ponowny zapis pod ta sama nazwa podmienia zawartosc, nie tworzy drugiego pliku. Ukosniki w nazwie (miniatures/65ab12ff) to tylko konwencja - bucket nie ma katalogow, a list(prefix) filtruje po przedrostku nazwy.
  • Bucket nalezy do INSTANCJI modulu. Disable/enable i aktualizacja wersji go nie ruszaja, odinstalowanie kasuje go w calosci.
  • Dozwolone znaki w nazwie to wylacznie [a-zA-Z0-9._/-], bez .., bez wiodacego ukosnika, maksymalnie 255 znakow. zazolc.png z polskimi znakami albo nazwa ze spacja zostana odrzucone - SDK zglasza to od razu, z nazwa pliku w komunikacie. Nazwa jest czescia adresu HTTP pliku, stad twarde reguly.
  • upload nie przesyla bajtow, ktore rdzen juz zna. SDK liczy sha256 lokalnie i najpierw probuje podpiac istniejaca tresc pod nazwe (komenda FILES_LINK); dopiero gdy rdzen odpowie, ze tych bajtow nie ma, leci wlasciwy transfer (FILES_UPLOAD). Modul wgrywajacy to samo logo przy kazdym starcie przesyla je wiec raz, a nie przy kazdym restarcie kontenera.
  • source to sciezka do pliku albo Buffer. Przy sciezce domyslna nazwa to nazwa pliku (bez katalogow); Buffer wymaga { name }, bo nie niesie ani nazwy, ani typu.
  • MIME jest wnioskowany z rozszerzenia NAZWY W BUCKECIE - tak samo dla bufora, jak i dla sciezki; przy sciezce zapasowo z rozszerzenia samej sciezki, gdy nazwa go nie ma (upload('./thumb.jpg', { name: 'miniatures/65ab12' }) da image/jpeg). Plik, ktory ma sie pokazac jako obrazek w widoku OVE, musi miec rozpoznawalne rozszerzenie w nazwie (miniatures/65ab12.jpg) albo jawnie podany mime - inaczej trafia do bucketu bez typu i przegladarka dostaje strumien bajtow, ktorego nie wyrenderuje.
  • Bajty leza w rdzeniu raz na sume kontrolna, wiec remove kasuje tresc dopiero, gdy traci ona ostatnia referencje (np. to samo logo w innej firmie zostaje).
  • W tej wersji nie ma limitow rozmiaru ani dzielenia transferu na czesci - caly plik idzie jedna wiadomoscia RPC.

Typowe uzycia to dwa: plik statyczny wgrywany przy starcie modulu (logo, instrukcja, ikona - wgrywany bezwarunkowo, bo dedup i tak pilnuje transferu) oraz plik dynamiczny zapisywany w chwili powstania (miniatura produktu, wygenerowany PDF).

Core.onEnabled(async () => {
    await Files.upload('./assets/how-to-connect.jpg'); // za kazdym startem, transfer tylko raz
});

Plik z bucketu pokazuje widok OVE typu image - wskazuje sie go nazwa, a bucket kodem modulu albo instanceId:

type: image
src:
    module: core/orders          # albo: instanceId: "{{ $module.id }}"
    name: how-to-connect.jpg     # albo: miniatures/{{ product._id }}

Przegladarka pobiera plik z autoryzacja firmy, wiec pliki nie maja publicznych adresow, a pliki wylaczonej instancji sa niedostepne.

Problems - rejestr problemow firmy

Problem to sytuacja, o ktorej UZYTKOWNIK musi wiedziec i ktora zwykle musi naprawic: faktura nie zostala wystawiona, rezerwacja towaru sie nie zalozyla, przewoznik odrzucil paczke. Rdzen trzyma problemy per firma, pokazuje ich liste w ustawieniach i liczy nieobsluzone na dzwonku w naglowku. Zrodlo zgloszenia (kod modulu, instancja) rdzen bierze z polaczenia, wiec modul zglasza i kasuje wylacznie wlasne problemy.

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

await Problems.report({
    problemKey: `wfirma.issue:${order._id}`,
    code: 'WFIRMA_ISSUE_FAILED',
    desc: {
        pl: `Nie udalo sie wystawic faktury: ${err.message}`,
        en: `Could not issue the invoice: ${err.message}`
    },
    link: { module: 'core/orders', path: `details/${order._id}` },
    entityName: order.number
}); // -> { _id, created } albo null

await Problems.resolve({ problemKey: `wfirma.issue:${order._id}` }); // -> { removed } albo null
pole typ uwagi
problemKey string, opcjonalne klucz deduplikacji w obrebie instancji (max 200 znakow). Bez niego kazde zgloszenie tworzy nowy wpis
code string, wymagane kod typu problemu nadawany przez modul, np. WFIRMA_ISSUE_FAILED (1-100 znakow) - badge i filtr na liscie
desc string albo object, wymagane opis dla uzytkownika, z komunikatem pierwotnego bledu. Albo zwykly string (1-2000 znakow), albo zalecana mapa jezykowa { pl: '...', en: '...' } - klucze to kody jezyka (pl, en, en-GB), kazde tlumaczenie 1-2000 znakow, co najmniej jeden wpis
link object, opcjonalne strona modulu dla przycisku "otworz", podawana tak jak akcja navigate w OVE - adres sklada front, bo modul nie zna jego routingu
link.module string, wymagane w link kod modulu, do ktorego nalezy strona, <vendor>/<nazwa>, np. core/orders (max 100 znakow)
link.path string, wymagane w link sciezka strony w tym module, np. details/65ab12ff (1-500 znakow); wiodacy / jest opcjonalny
entityName string, opcjonalne etykieta obiektu, ktorego dotyczy problem, pokazywana uzytkownikowi obok opisu, np. numer zamowienia (max 200 znakow)
  • Mapa jezykowa w desc jest zalecana. Zespol firmy bywa wielojezyczny, a wszyscy widza te sama liste problemow, wiec tlumaczenie musi siedziec w rekordzie, a nie w kliencie. Rdzen zapisuje dokladnie to, co dostal - nie tlumaczy i nie normalizuje - a front wybiera jezyk zalogowanego uzytkownika z fallbackiem: jezyk uzytkownika -> pl -> en -> pierwsza wartosc z mapy. Zwykly string dziala nadal i jest wyswietlany wszystkim tak samo.
  • problemKey deduplikuje. Ponowny report z tym samym kluczem nie tworzy drugiego wpisu - aktualizuje istniejacy (code, desc, link, entityName), odswieza czas ostatniego zgloszenia i cofa status do waiting, nawet gdy uzytkownik zdazyl oznaczyc problem jako rozwiazany. resolve kasuje wpis calkowicie; nieznany klucz to cichy no-op, wiec nie trzeba nic sprawdzac.
  • Klucz musi byc deterministyczny - '<operacja>:<id encji>', nigdy losowy uuid, bo wtedy kazda nieudana proba zostawia kolejny wiersz na liscie.
  • Zadna z metod nie odrzuca Promise. Zgloszenie dzieje sie zwykle w catch i nie moze przeslonic pierwotnego bledu, wiec blad transportu lub walidacji jest logowany na console.error przy ORBITO_DEBUG=1, a metoda zwraca null.
  • Zglaszaj problemy operacji o skutku biznesowym dla uzytkownika (dokument niewystawiony, mail niewyslany), a nie kazdy blad techniczny - od tego jest Log.

Wzorzec jest zawsze ten sam: report w catch, resolve po udanej probie tej samej operacji - dzieki temu problem znika z listy sam, gdy ponowienie sie uda.

async function issueInvoice(order) {
    const problemKey = `wfirma.issue:${order._id}`;
    try {
        await wfirma.issue(order);
        await Problems.resolve({ problemKey });
    } catch (err) {
        await Problems.report({
            problemKey,
            code: 'WFIRMA_ISSUE_FAILED',
            desc: {
                pl: `Nie udalo sie wystawic faktury do zamowienia ${order.number}: ${err.message}`,
                en: `Could not issue the invoice for order ${order.number}: ${err.message}`
            },
            link: { module: 'core/orders', path: `details/${order._id}` },
            entityName: order.number
        });
        throw err; // report nie zastepuje obslugi bledu
    }
}

History - wspolna historia zdarzen firmy

Historia to wspolny, tylko dopisywany rejestr tego, co dzialo sie z obiektami biznesowymi firmy: zamowienie utworzone, status zmieniony, przesylka nadana. Wszystkie moduly pisza do tego samego rejestru, a uzytkownik czyta go w Ustawienia -> Historia, filtrujac po module zrodlowym i po module, ktorego zdarzenie dotyczy.

To nie jest ani Log, ani Problems. Log to diagnostyka dla programisty, Problems to biezaca lista rzeczy do naprawienia (wpisy deduplikuja sie i znikaja po resolve), a historia jest niezmiennym sladem audytowym - wpisu nie da sie zmienic ani skasowac, a kazdy add dopisuje kolejny.

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

await History.add({
    code: 'ORDER_STATUS_CHANGED',
    desc: {
        pl: `Status zmieniony z "${from}" na "${to}"`,
        en: `Status changed from "${from}" to "${to}"`
    },
    relations: [{ module: 'core/orders', object: 'order', id: String(order._id) }],
    userId: this.userId   // z kontekstu wywolania; pomin przy zdarzeniach systemowych
}); // -> { _id } albo null
pole typ uwagi
code string, wymagane kod zdarzenia nadawany przez modul, np. ORDER_STATUS_CHANGED (1-100 znakow) - sluzy do filtrowania i diagnostyki, uzytkownik czyta desc
desc string albo object, wymagane gotowy opis dla uzytkownika: zwykly string (1-2000 znakow) albo zalecana mapa jezykowa { pl: '...', en: '...' } - klucze to kody jezyka, kazde tlumaczenie 1-2000 znakow, min. jeden wpis
relations tablica, wymagane encje, ktorych dotyczy zdarzenie, 1-10 elementow
relations[].module string, wymagane kod modulu wlasciciela encji, <vendor>/<nazwa>, np. core/orders (max 100 znakow)
relations[].object string, wymagane typ encji w tym module, np. order, shipment (max 50 znakow, ^[a-z][a-z0-9_-]*$)
relations[].id string, wymagane identyfikator encji - string, zeby dzialaly takze identyfikatory zewnetrzne (1-100 znakow)
relations[].instanceId string, opcjonalne instalacja bedaca wlascicielem encji (24 znaki hex), gdy samo id nie jest jednoznaczne w firmie
userId string, opcjonalne kto wywolal zdarzenie (24 znaki hex) - bierz z this.userId w handlerze metody; brak = zdarzenie systemowe
  • Wpis niesie gotowy opis. Modul siedzi w osobnym kontenerze i moze dzialac w kilku wersjach naraz, wiec ani rdzen, ani front nie maja jak wykonac jego deskryptora w czasie odczytu. Dlatego desc zapisujesz raz, od razu dla uzytkownika; mapa jezykowa jest zalecana, bo zespol firmy bywa wielojezyczny, a front wybiera jezyk zalogowanego uzytkownika z fallbackiem pl -> en -> pierwsza wartosc.
  • relations moze byc kilka. Jedno zdarzenie potrafi dotyczyc kilku encji - utworzenie przesylki dotyczy i przesylki, i zamowienia - a zapytanie "historia zamowienia X" odpowiada po trojce module + object + id.
  • Zrodla i czasu nie podajesz. Kod modulu, instancje i at dopisuje rdzen z tozsamosci polaczenia, wiec modul nie antydatuje wpisow ani nie pisze w cudzym imieniu.
  • add nigdy nie odrzuca Promise. Zapis historii jest efektem ubocznym operacji biznesowej i nie moze jej wywrocic - blad transportu lub walidacji jest logowany na console.error przy ORBITO_DEBUG=1, a metoda zwraca null.

Zdarzenie dotyczace dwoch encji (przesylka utworzona dla zamowienia):

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

Dependencies

Dependencies

ID Version
bson ^6.10.4
fastest-validator ^1.19.1

Development Dependencies

ID Version
eslint ^8.29.0
eslint-plugin-jest ^28.11.0
jest ^29.7.0
nodemon ^2.0.19
supertest ^7.0.0
Details
npm
2026-09-23 12:04:12 +02:00
82
ISC
76 KiB
Assets (1)
Versions (73) View all
4.5.0 2026-10-27
4.4.3 2026-10-17
4.4.1 2026-10-14
4.4.0 2026-10-14
4.3.0 2026-10-06