@orbito/api-lib (4.5.0)
Installation
@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/npm install @orbito/api-lib@4.5.0"@orbito/api-lib": "4.5.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.getCompany(); // profil firmy kontenera, w tym strefa czasowa (od 4.3.0)
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.
Core.getCompany() (od 4.3.0) zwraca profil firmy kontenera:
{ id, name, timezone, country, address, city, postCode, taxNo, legalForm, regon, krs, website, contactPhone, contactEmail }. Firme rdzen bierze z
polaczenia, wiec metoda nie ma parametrow.
timezone(IANA, np.Europe/Warsaw) jest zawsze wypelnione - to strefa, w ktorej pracuje firma, ustawiana przez administratora w panelu. Do dat w tej strefie sluzyTime(ponizej).- Pola opcjonalne (
legalForm,regon,krs,website,contactPhone,contactEmail) maja wartoscnull, gdy firma ich nie uzupelnila. - Nic nie jest cache'owane i rdzen nie wysyla powiadomien o zmianie - kazde wywolanie pyta rdzen. Pobieraj dane wtedy, kiedy ich potrzebujesz (np. na poczatku handlera), zamiast trzymac kopie w zmiennej modulu.
- Odrzuca Promise przy bledzie - modul zawsze nalezy do istniejacej firmy,
wiec brak firmy to awaria, a nie
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).this.origin(od 4.3.0) to bieg automatyzacji, z ktorego wyszlo wywolanie ({ type: 'automation', automationId, automationName, runId }), takze przez inne moduly, albonull. Zwykle nie trzeba go czytac: SDK samo dokleja go do wywolan wychodzacych z handlera (callModule,callInstanceMethod,execHook,History.add). Kontekst ginie poza asynchronicznym lancuchem handlera - praca podjeta przez petle uruchomiona poza handlerem (konsument kolejki w pamieci,setInterval) albo cron ida bez pochodzenia.
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. - Automatyzacje oznacza SDK. Gdy
addbiegnie w akcji automatyzacji albo w handlerze metody/hooka osiagnietym z takiej akcji, SDK (od 4.3.0) samo dokleja identyfikator biegu - modul niczego nie przekazuje, a wpis jest w panelu pokazany jako wykonany przez automatyzacje (nazwa z linkiem do biegu). 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' }, 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.
Docs - wiedza domenowa modulu dla asystenta AI (od 4.1.0)
Asystent AI firmy poznaje modul z tego, co modul sam zglosil: nazw, opisow i
schematow metod. Schemat nie powie jednak, co znaczy status ani jak jeden obiekt
wplywa na drugi. Te wiedze modul dostarcza w dokumentach markdown w swojej
paczce. Rdzen indeksuje je per wersja modulu, wiec asystent czyta dokumenty
wersji zainstalowanej w firmie, bez budzenia kontenera. Indeks (id, tytul,
streszczenie) widzi obok listy metod, a tresc pobiera, gdy jej potrzebuje.
const { Docs } = require('@orbito/api-lib');
// pliki docs/*.md w katalogu modulu (sciezka wzgledna do cwd modulu albo bezwzgledna)
await Docs.register({
statuses: {
title: 'Statusy zamowien',
summary: 'Co znaczy kazdy status i grupa statusow oraz co je zmienia.',
file: 'docs/statuses.md'
},
lifecycle: {
title: 'Cykl zycia zamowienia',
summary: 'Od importu do dostawy: ktory modul co robi i jakie zdarzenia emituje.',
file: 'docs/lifecycle.md'
}
});
| pole | typ | uwagi |
|---|---|---|
klucz mapy (docId) |
string, wymagane | ^[a-z][a-z0-9_-]*$, np. statuses |
title |
string, wymagane | niepusty, najwyzej 120 znakow |
summary |
string, wymagane | niepusty, najwyzej 300 znakow; asystent decyduje z niego, czy czytac dokument |
file |
string, wymagane | sciezka do pliku .md; niepusty, najwyzej 20 000 znakow |
- Najwyzej 20 dokumentow. Dluzszy tekst podziel na kilka dokumentow.
- Argument to caly zestaw: kolejne
registerzastepuje poprzedni zestaw, a rdzen usuwa z indeksu wersji dokumenty, ktorych zestaw juz nie zawiera. Po reconnect zestaw jest wysylany ponownie automatycznie. - Bledna definicja (zly id, brak lub pusty plik, przekroczony limit) rzuca przy rejestracji, przed wyslaniem czegokolwiek, z komunikatem wskazujacym dokument.
- Dostarczenie nigdy nie odrzuca Promise. Gdy rdzen odrzuci zestaw (waliduje
go niezaleznie, te same limity), nie zna jeszcze komendy (starszy rdzen) albo
zawiedzie transport, SDK zawsze wypisuje ostrzezenie (
console.warn, nie tylko podORBITO_DEBUG), aregisterzwracanull- modul dziala dalej bez dokumentow. To samo przy ponownej wysylce po reconnect. - Pisz dla asystenta diagnozujacego problem, nie dla programisty: co znacza statusy i pola, co je zmienia, typowe przyczyny, ktora metode wywolac, zeby cos sprawdzic. Asystent traktuje dokument jako opis (dane), a nie polecenia.
OAuth - bilety callbacku (od 4.2.0)
Dostawcy OAuth (Amazon SP-API, Allegro, ...) rejestruja adres powrotu raz, dla calej aplikacji autora modulu, wiec nie moze on zalezec od firmy ani instalacji. Dlatego publiczny adres callbacku ma rdzen, a modul nigdy nie serwuje wlasnej strony: tworzy bilet, rdzen odbiera przekierowanie dostawcy (bez uruchamiania kodu modulu), a po powrocie zalogowanego uzytkownika wola wskazana metode modulu z parametrami callbacku.
- Metoda modulu (np. przycisk "Polacz" w OVE) tworzy bilet przez
OAuth.createTicketi buduje URL zgody dostawcy zredirectUriistate. - Akcja OVE
redirectprzekierowuje przegladarke na ten URL. - Dostawca wraca na
redirectUrirdzenia, rdzen zapisuje wszystkie parametry query na bilecie i przekierowuje przegladarke na front. - Front (z zalogowanym uzytkownikiem) konczy bilet: rdzen wola
finishMethodinstancji z{ callback, meta, redirectUri }w kontekscie tego uzytkownika, a front przechodzi nareturnTo.
const { Core, Config, OAuth } = require('@orbito/api-lib');
// przycisk w OVE: { action: 'callMethod', method: 'connect',
// onSuccess: { action: 'redirect', url: '{{ $response.0.url }}' } }
Core.registerMethod('connect', async (params, ctx) => {
const { state, redirectUri } = await OAuth.createTicket({
finishMethod: 'oauth.finish',
returnTo: { module: 'vendor/shop', path: '/settings' },
userId: ctx.userId,
meta: { region: params.region }
}); // -> { state, redirectUri, expiresAt }
const url = new URL('https://provider.example.com/oauth/authorize');
url.searchParams.set('client_id', CLIENT_ID);
url.searchParams.set('response_type', 'code');
url.searchParams.set('redirect_uri', redirectUri);
url.searchParams.set('state', state);
return { url: url.toString() };
});
// wolana przez rdzen po powrocie uzytkownika od dostawcy
Core.registerMethod('oauth.finish', async ({ callback, meta, redirectUri }) => {
if (callback.error) {
throw new Error(`Dostawca odmowil dostepu: ${callback.error_description || callback.error}`);
}
const res = await Core.fetch(`https://api.${meta.region}.provider.example.com/oauth/token`, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'authorization_code',
code: callback.code,
redirect_uri: redirectUri, // wymiana kodu musi go powtorzyc
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET
}).toString()
});
if (res.status !== 200) {
throw new Error(`Wymiana kodu nie powiodla sie (${res.status})`);
}
const { access_token, refresh_token, expires_in } = res.json();
await Config.set('runtime.tokens', {
accessToken: access_token,
refreshToken: refresh_token,
expiresAt: Date.now() + expires_in * 1000
});
return { connected: true };
});
| pole | typ | uwagi |
|---|---|---|
finishMethod |
string, wymagane | metoda tej instancji (Core.registerMethod) wolana po powrocie z { callback, meta, redirectUri }, np. oauth.finish |
returnTo |
object, wymagane | { module, path, params? } - dokad front przechodzi po zakonczeniu, konwencja jak link w Problems i navigate w OVE |
returnTo.module |
string, wymagane | wlasny kod modulu albo core; inny modul rdzen odrzuca |
userId |
string, wymagane | uzytkownik, ktory moze zakonczyc bilet (24 znaki hex) - przekaz ctx.userId metody tworzacej bilet |
meta |
object, opcjonalne | dane zwrotne dla finishMethod bez zmian (region, sandbox/produkcja, ...), najwyzej 4 KB po serializacji |
ttl |
number, opcjonalne | sekundy na zgode u dostawcy, 60-1800, domyslnie 600 |
- Bilet jest jednorazowy i zwiazany z uzytkownikiem oraz firma. Zakonczyc go
moze tylko uzytkownik z
userId, i tylko w firmie tej instancji - to chroni przed podpieciem cudzego konta dostawcy do cudzej instalacji. Drugi callback albo drugie zakonczenie tego samego biletu konczy sie bledem. redirectUrijest staly dla srodowiska i to on trzeba zarejestrowac u dostawcy (produkcja:https://v2.orbito.pl/api/oauth/callback). Nie hardkoduj go - bierz z biletu, wtedy ten sam kod dziala lokalnie i na produkcji.- Tworz bilet w metodzie wywolanej przez uzytkownika (przycisk + akcja
redirect), a nie przy renderze strony - kazde wywolanie zuzywa bilet. callbackto wszystkie parametry query od dostawcy (code,error,error_description, wlasne parametry dostawcy). Odmowa po stronie dostawcy (?error=access_denied) przychodzi ta sama droga, wiec sprawdz najpierwcallback.error.redirectUrito adres z biletu - przekaz go przy wymianie kodu, bo dostawcy wymagaja tego samegoredirect_uri.- Kod wymieniasz przez
Core.fetch- domena endpointu tokenow musi byc na bialej liscie firmy. Tokeny trzymaj wConfigpodruntime.*. - Wyjatek w
finishMethodoznacza bilet jako nieudany, a front pokazuje jego komunikat uzytkownikowi. Wynik metody wraca do frontu, ale strona powrotu go nie uzywa. createTicketodrzuca Promise przy bledzie (zly payload, brak polaczenia) - bez biletu nie ma czego kontynuowac. Nic nie jest rejestrowane w rdzeniu, wiec po reconnect nie trzeba niczego wysylac ponownie.
Time - daty w strefie firmy (od 4.3.0)
Kontener modulu ma wlasna strefe czasowa, ktora nic nie mowi o firmie. "Dzis",
"zamowienia z 2026-10-06" czy "termin platnosci za 14 dni" to dni robocze firmy,
czyli w strefie z Core.getCompany().timezone. Time daje do tego helpery z
jawna strefa - nic nie jest przybite do Europe/Warsaw ani do TZ kontenera.
const { Core, DB, Time } = require('@orbito/api-lib');
Core.registerMethod('orders.list', async (params) => {
const time = await Time.forCompany(); // raz na wywolanie, potem przekazywane w dol
return DB.find('orders', buildQuery(params, time));
});
// funkcja synchroniczna dostaje helpery, zamiast czytac globalna strefe
function buildQuery({ dateFrom, dateTo }, time) {
return {
createdAt: {
$gte: time.dateBoundary(dateFrom), // 00:00:00 tego dnia w strefie firmy
$lte: time.dateBoundary(dateTo, true) // 23:59:59.999 tego dnia
}
};
}
| funkcja | opis |
|---|---|
Time.forCompany() |
Promise helperow dla strefy firmy - Time.inZone((await Core.getCompany()).timezone), bez cache |
Time.inZone(timeZone) |
synchroniczne helpery dla wskazanej strefy (zamrozony obiekt, formatter tworzony raz na strefe); nieznana strefa rzuca RangeError |
time.timeZone |
nazwa strefy |
time.parseDate(value) |
Date albo null; tekst bez offsetu (2026-10-06 14:30, 2026-10-06) to czas w strefie, Z/+02:00, Date i liczba zachowuja swoja chwile |
time.formatDate(value, pattern) |
tekst w strefie, tokeny YYYY MM DD HH mm ss, domyslnie DD.MM.YYYY HH:mm; '' dla zlej daty |
time.dateBoundary(value, endOfDay) |
dla YYYY-MM-DD poczatek (00:00:00.000) albo koniec (23:59:59.999) dnia w strefie; inna wartosc jak parseDate |
time.addCalendarDays(value, days) |
dzien kalendarzowy value w strefie przesuniety o days, jako YYYY-MM-DD; '' dla zlej daty |
- Strefe pobieraj na poczatku handlera metody/hooka i przekazuj helpery w dol jako argument. Nie trzymaj ich w zmiennej modulu - administrator moze zmienic strefe w kazdej chwili, a wartosc z startu kontenera po cichu sie zestarzeje.
- Zmiana czasu: godzina z wiosennej luki (np.
2026-03-29 02:30wEurope/Warsaw) jest nieprawidlowa (null), a powtorzona jesienna godzina (2026-10-25 02:30) to jej pierwsze wystapienie. - Dni sa kalendarzowe: dzien w strefie moze trwac 23 albo 25 godzin, wiec
addCalendarDaysnigdy nie liczy "+24 h".
Pages - strony publiczne (od 4.5.0)
Strona publiczna to widok OVE dostepny bez logowania, np. karta zamowienia
dla klienta sklepu. Adres ma postac https://orbi.do/p/<instanceId>/<pageCode>/?... -
firma wynika z instancji, wiec nie wystepuje w adresie. Adres buduje rdzen, modul
nigdy nie sklada go sam.
const { Core, DB, Pages } = require('@orbito/api-lib');
Pages.registerPublicPages({
'/track': {
name: { pl: 'Twoje zamowienie', en: 'Your order' },
view: 'pages/public/track.yaml'
}
});
// jedyne metody, ktore strona publiczna moze wolac
Core.registerMethod('public.getOrder', {
public: true,
params: { o: { type: 'string' } },
handler: async ({ o }, ctx) => {
// ctx.public === true, ctx.userId === null - kazde wejscie sprawdz sam
if (typeof o !== 'string' || !/^[0-9a-f]{24}$/.test(o)) throw new Error('ORDER_NOT_FOUND');
const [order] = await DB.find('orders', { _id: o }, 1);
if (!order) throw new Error('ORDER_NOT_FOUND');
return { orderNumber: order.orderNumber, status: order.status }; // tylko pola dla klienta
}
});
// adres do maila albo zmiennej szablonu wiadomosci
const url = await Pages.publicUrl('/track', { o: String(order._id) });
- Klucz to
/<pageCode>(wiodacy/opcjonalny): jeden segment[a-z0-9-], do 40 znakow, bez parametrow sciezki. Dane wejsciowe strona dostaje wylacznie w query (w OVE$page.urlParams). - Definicja:
name(string albo{ pl, en }) iview(plik.yaml/.yml/.jsonjak wregisterPages).placementimoduleDependenciessa bledem - strona publiczna nie trafia do menu. - Rejestracja dziala jak
registerPages: mozna wolac wielokrotnie, wysylany jest caly zestaw (strony spoza niego rdzen usuwa), po reconnect zestaw idzie ponownie. Bledna definicja odrzuca cale wywolanie, zanim cokolwiek zmieni. Pages.publicUrl(pageCode, query)zwraca pelny adres strony tej instancji; odrzuca Promise, gdy strona nie jest zarejestrowana.- Metody publiczne: strona moze wolac tylko metody zarejestrowane z
public: true(tylko forma obiektowa definicji), kazda inna konczy sie 403. Wywolanie nie ma uzytkownika:ctx = { public: true, userId: null, permissions: [], caller: null, origin: null, publicPage: { instanceId, pageCode } }. Metody zCore.hasPermissionodmowia same (puste uprawnienia). - Waliduj wejscie i ogranicz wynik. Rdzen nie sprawdza
params, a metode publiczna moze wywolac kazdy, kto zna adres - takze z innymi parametrami niz te, ktore wysyla Twoja strona. Zwracaj tylko pola przeznaczone dla odbiorcy strony, nigdy calego dokumentu.
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 |