@orbito/api-lib (4.0.0)
Installation
@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/npm install @orbito/api-lib@4.0.0"@orbito/api-lib": "4.0.0"About this package
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.callerjest budowane przez rdzen z tozsamosci polaczenia - wolajacy nie moze go podrobic.Function.prototype.bindma pierwszenstwo przed bindowaniem SDK - jesli potrzebujeszthis.caller, rejestruj zwyklafunction, a nieobj.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
__instanceIdprzeslonilby pole rdzenia i zepsul routing -registerAction/registerTriggerrzucaja wtedy bledem przy starcie. - Listenery triggerow kluczuj po
(triggerCode, actionId)- zdarzenie zgloszone przezcallTriggerrdzen przypisuje do instancji po tozsamosci polaczenia. clear(0x44) jako jedyna trafia do wszystkich dzialajacych kontenerow modulu.
Klucze zdarzen i prefiksy modulow (od 4.0.0)
Klucze w emits triggera, requires akcji i requires grupy zmiennych
szablonow (Templates.registerVarGroup) maja format KEY albo
<kodModulu>:KEY. Klucz bez prefiksu nalezy do modulu, ktory go deklaruje
(ORDER_ID w core/orders to core/orders:ORDER_ID), a klucz innego modulu
musi miec prefiks. SDK sprawdza tylko format (zly format rzuca przy
rejestracji), klucze tlumaczy rdzen.
// core/shipping - id zamowienia nalezy do core/orders, id przesylki jest wlasne
Automation.registerTrigger('shipment_created', {
displayName: 'Nowa przesylka',
emits: {
'core/orders:ORDER_ID': { type: 'ObjectId', name: 'Zamowienie' },
SHIPMENT_ID: { type: 'ObjectId', name: 'Przesylka' }
},
enable, disable, clear
});
// core/wfirma - akcja potrzebuje klucza core/orders
Automation.registerAction('issue_document', {
requires: ['core/orders:ORDER_ID'],
execute: async (params, ctx) => issue(ctx.event.params['core/orders:ORDER_ID'])
});
ctx.event.params niesie pelne klucze. Klucze wlasnego modulu akcji sa
dodatkowo dostepne w krotkiej formie (w core/orders
params['core/orders:ORDER_ID'] === params.ORDER_ID), klucze obce tylko z
prefiksem.
Migracja modulu na 4.0.0 (breaking, bez trybu zgodnosci):
- W
emitstriggerow irequiresakcji dopisz prefiks do kazdego klucza innego modulu (ORDER_IDw core/shipping ->'core/orders:ORDER_ID'). Wlasne klucze zostaja krotkie. callTriggerwysyla parametry pod tymi samymi kluczami, co wemits.- Odczyty
ctx.event.paramskluczy obcych zmien na forme z prefiksem (ctx.event.params['core/orders:ORDER_ID']); wlasne klucze czytane krotko dzialaja dalej.
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
Schemaautomatycznie mapujeObjectIdw definicji na validatorobjectID.- W
find(schemat) string w formacie 24-hex zostanie rzutowany naObjectId, jesli pole w schemacie ma typObjectId. - Operacje
DB.find/insert/update/delete/createIndexdzialaja bezposrednio na kolekcjach. - Nazwy kolekcji sa logiczne/surowe (np.
"orders") - rdzen sam dokleja namespace{instanceId}_{collection}. Nie prefiksuj kolekcjicompanyIdaniinstanceIdi 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). getzwraca wartosc domyslna tylko gdy klucz NIE istnieje - zapisanynulljest zwracany jakonull.- Brak cache po stronie SDK - kazdy
getto 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.enjest wymagane (jezyk zapasowy);titlemoze byc tez stringiem.schemato 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 przezraport.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 dynamicznaschema) - nie widzi niezapisanego stanu formularza.ctxto{ userId }wywolujacego (jest tez zbindowany jakothis).- Wynik
{ success, message, needReload }- wszystkie pola opcjonalne:successdomyslnietrue(zwrocfalseprzy niepowodzeniu biznesowym),messagefrontend pokazuje uzytkownikowi,needReloaddomyslnietrue(blok pobierany ponownie); wyjatek z handlera wraca jako{ success: false, message: error.message }. confirm(string albo mapa jezykowa) wlacza dialog potwierdzenia przed wykonaniem akcji,styleto podpowiedz wygladu (Config.ActionStyle:DEFAULT/PRIMARY/DANGER).actionsmoze 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
hasConfignadal 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
);
contentto 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, alist(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.pngz 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. uploadnie przesyla bajtow, ktore rdzen juz zna. SDK liczy sha256 lokalnie i najpierw probuje podpiac istniejaca tresc pod nazwe (komendaFILES_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.sourceto sciezka do pliku alboBuffer. Przy sciezce domyslna nazwa to nazwa pliku (bez katalogow);Bufferwymaga{ 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' })daimage/jpeg). Plik, ktory ma sie pokazac jako obrazek w widoku OVE, musi miec rozpoznawalne rozszerzenie w nazwie (miniatures/65ab12.jpg) albo jawnie podanymime- inaczej trafia do bucketu bez typu i przegladarka dostaje strumien bajtow, ktorego nie wyrenderuje. - Bajty leza w rdzeniu raz na sume kontrolna, wiec
removekasuje 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
descjest 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. problemKeydeduplikuje. Ponownyreportz tym samym kluczem nie tworzy drugiego wpisu - aktualizuje istniejacy (code,desc,link,entityName), odswieza czas ostatniego zgloszenia i cofa status dowaiting, nawet gdy uzytkownik zdazyl oznaczyc problem jako rozwiazany.resolvekasuje 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
catchi nie moze przeslonic pierwotnego bledu, wiec blad transportu lub walidacji jest logowany naconsole.errorprzyORBITO_DEBUG=1, a metoda zwracanull. - 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
desczapisujesz raz, od razu dla uzytkownika; mapa jezykowa jest zalecana, bo zespol firmy bywa wielojezyczny, a front wybiera jezyk zalogowanego uzytkownika z fallbackiempl->en-> pierwsza wartosc. relationsmoze byc kilka. Jedno zdarzenie potrafi dotyczyc kilku encji - utworzenie przesylki dotyczy i przesylki, i zamowienia - a zapytanie "historia zamowienia X" odpowiada po trojcemodule+object+id.- Zrodla i czasu nie podajesz. Kod modulu, instancje i
atdopisuje rdzen z tozsamosci polaczenia, wiec modul nie antydatuje wpisow ani nie pisze w cudzym imieniu. addnigdy nie odrzuca Promise. Zapis historii jest efektem ubocznym operacji biznesowej i nie moze jej wywrocic - blad transportu lub walidacji jest logowany naconsole.errorprzyORBITO_DEBUG=1, a metoda zwracanull.
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
});
Odczyt historii - History.list (od 3.12.0)
Modul moze czytac cala historie swojej firmy - nie tylko wpisy o wlasnych
encjach i nie tylko wlasne. Firme wyznacza polaczenie, wiec cudzej firmy nie
da sie odczytac. Filtry sa te same co w Ustawienia -> Historia
(GET /history), wynik jest posortowany od najnowszych.
// historia mojego zamowienia, razem ze zdarzeniami innych modulow (wysylka, faktura)
const { items, pagination } = await History.list({
module: 'core/orders', object: 'order', id: String(order._id),
limit: 200
});
// items[]: { _id, source: { moduleCode, instanceId, instanceName }, code, desc, relations,
// userId, user: { _id, firstname, lastname } | null, at }
// pagination: { page, limit, total }
| filtr | uwagi |
|---|---|
module, object, id |
relacja - cala trojka albo nic, dopasowana do jednego elementu relations |
instanceId |
zaweza relacje do instalacji (24 znaki hex); wymaga pelnej trojki |
sourceModule |
tylko wpisy zapisane przez ten modul |
relatedModule |
tylko wpisy z dowolna relacja do tego modulu |
code |
tylko wpisy o tym kodzie zdarzenia |
from, to |
zakres dat at (wlacznie) |
page, limit |
stronicowanie; limit domyslnie 20, rdzen przycina do 200 |
listodrzuca Promise przy bledzie - odwrotnie nizadd. To odczyt danych biznesowych, wiec wywolujacy ma zobaczyc blad (np. niepelna trojke relacji), a nie pusta liste udajaca brak historii.- Identyfikatory i daty przychodza jako stringi (
atw ISO), bo wynik idzie przez JSON.userto dane uzytkownika dolaczone przez rdzen albonulldla zdarzen systemowych.
Templates - zmienne szablonow wiadomosci (od 4.0.0)
Szablony wiadomosci firmy (np. e-maile wysylane przez automatyzacje) edytuje sie
w jednym, globalnym edytorze, ktory nie zna modulow. Dlatego modul deklaruje
grupy zmiennych: nazwany zestaw pol (customer -> email, fullName) i
handler, ktory zwraca ich wartosci. Rdzen indeksuje schematy grup per wersja
modulu, wiec edytor listuje zmienne i waliduje szablon bez budzenia kontenerow -
handler jest wolany dopiero przy wysylce prawdziwej wiadomosci.
W szablonie zmienna ma zawsze prefiks modulu: {{ core/orders:customer.email }},
a pole listy to sekcja mustache:
{{#core/orders:order.items}}{{ name }} x {{ quantity }}{{/core/orders:order.items}}.
const { Templates } = require('@orbito/api-lib');
// core/orders
await Templates.registerVarGroup('order', {
name: { pl: 'Zamowienie', en: 'Order' },
requires: ['ORDER_ID'],
fields: {
number: { name: { pl: 'Numer', en: 'Number' }, example: 'ZAM/2026/001' },
'total-to-pay': { name: { pl: 'Do zaplaty', en: 'To pay' }, type: 'number', example: 129.99 },
items: {
name: { pl: 'Pozycje', en: 'Items' },
type: 'list',
fields: {
name: { name: { pl: 'Nazwa', en: 'Name' }, example: 'Kubek' },
quantity: { name: { pl: 'Ilosc', en: 'Quantity' }, type: 'number', example: 2 }
},
example: [{ name: 'Kubek', quantity: 2 }]
}
},
// params: wartosci kluczy z requires (pelne klucze + krotkie aliasy wlasnych)
handler: async (params) => orderVars(params.ORDER_ID)
});
| pole | typ | uwagi |
|---|---|---|
code (1. argument) |
string, wymagane | ^[a-z][a-z0-9_-]*$ - bez kropek i dwukropkow, bo tworzy sciezke modul:grupa.pole |
name |
string albo mapa jezykowa, wymagane | nazwa grupy w edytorze, np. { pl, en } |
requires |
tablica kluczy, opcjonalne | klucze zdarzenia potrzebne handlerowi, format jak w emits/requires automatyzacji; domyslnie [] |
fields |
object, wymagane | niepusta mapa pol; klucz pola ^[A-Za-z][A-Za-z0-9_-]*$ (np. total-to-pay) |
fields.*.name |
string albo mapa jezykowa, wymagane | nazwa pola w pickerze edytora |
fields.*.type |
string, opcjonalne | string (domyslnie), number, boolean, date, list |
fields.*.format |
string, opcjonalne | podpowiedz wyswietlania, np. email |
fields.*.example |
dowolne, opcjonalne | wartosc do podgladu w edytorze; dla listy tablica przykladowych elementow |
fields.*.fields |
object | pola elementu listy (te same reguly); tylko przy type: 'list' |
handler |
async function, wymagane | (params) => wartosci pol; listy jako tablice obiektow |
- Podglad renderuje sie z
example, bez wolania modulu - podaj realistyczne przyklady. - Rdzen sprawdza, ze trigger automatyzacji emituje wszystkie klucze z
requiresgrup uzytych w szablonie. - Bledna definicja rzuca przy rejestracji, przed wyslaniem czegokolwiek. Ponowna rejestracja tego samego kodu podmienia grupe, a po reconnect grupy sa wysylane ponownie automatycznie.
- Wyjatek handlera wraca do rdzenia jako blad; rdzen zglasza go w rejestrze problemow i renderuje puste wartosci.
- Parametr akcji typu
PropertyType.TEMPLATE_VARprzechowuje pelna sciezke zmiennej skalarnej (core/orders:customer.email); rdzen rozwiazuje ja przedexecute, wiec akcja dostaje gotowa wartosc. - Parametr akcji typu
PropertyType.STRINGzformat: DisplayFormat.MESSAGE_TEMPLATEto identyfikator szablonu wiadomosci firmy (front pokazuje liste szablonow); rdzen przy zapisie automatyzacji sprawdza, ze szablon istnieje i ze trigger emituje klucze wymagane przez jego zmienne.
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 |