Orbito Orders managment

@orbito/api-lib (4.5.0)

Published 2026-10-27 13:03:18 +01:00 by wiktor

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

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.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 sluzy Time (ponizej).
  • Pola opcjonalne (legalForm, regon, krs, website, contactPhone, contactEmail) maja wartosc null, 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.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).
  • this.origin (od 4.3.0) to bieg automatyzacji, z ktorego wyszlo wywolanie ({ type: 'automation', automationId, automationName, runId }), takze przez inne moduly, albo null. 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 __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.

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):

  1. W emits triggerow i requires akcji dopisz prefiks do kazdego klucza innego modulu (ORDER_ID w core/shipping -> 'core/orders:ORDER_ID'). Wlasne klucze zostaja krotkie.
  2. callTrigger wysyla parametry pod tymi samymi kluczami, co w emits.
  3. Odczyty ctx.event.params kluczy 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

  • 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.
  • Automatyzacje oznacza SDK. Gdy add biegnie 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).
  • 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
});

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
  • list odrzuca Promise przy bledzie - odwrotnie niz add. 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 (at w ISO), bo wynik idzie przez JSON. user to dane uzytkownika dolaczone przez rdzen albo null dla 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 requires grup 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_VAR przechowuje pelna sciezke zmiennej skalarnej (core/orders:customer.email); rdzen rozwiazuje ja przed execute, wiec akcja dostaje gotowa wartosc.
  • Parametr akcji typu PropertyType.STRING z format: DisplayFormat.MESSAGE_TEMPLATE to 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 register zastepuje 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 pod ORBITO_DEBUG), a register zwraca null - 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.

  1. Metoda modulu (np. przycisk "Polacz" w OVE) tworzy bilet przez OAuth.createTicket i buduje URL zgody dostawcy z redirectUri i state.
  2. Akcja OVE redirect przekierowuje przegladarke na ten URL.
  3. Dostawca wraca na redirectUri rdzenia, rdzen zapisuje wszystkie parametry query na bilecie i przekierowuje przegladarke na front.
  4. Front (z zalogowanym uzytkownikiem) konczy bilet: rdzen wola finishMethod instancji z { callback, meta, redirectUri } w kontekscie tego uzytkownika, a front przechodzi na returnTo.
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.
  • redirectUri jest 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.
  • callback to 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 najpierw callback.error. redirectUri to adres z biletu - przekaz go przy wymianie kodu, bo dostawcy wymagaja tego samego redirect_uri.
  • Kod wymieniasz przez Core.fetch - domena endpointu tokenow musi byc na bialej liscie firmy. Tokeny trzymaj w Config pod runtime.*.
  • Wyjatek w finishMethod oznacza bilet jako nieudany, a front pokazuje jego komunikat uzytkownikowi. Wynik metody wraca do frontu, ale strona powrotu go nie uzywa.
  • createTicket odrzuca 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:30 w Europe/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 addCalendarDays nigdy 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 }) i view (plik .yaml/.yml/.json jak w registerPages). placement i moduleDependencies sa 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 z Core.hasPermission odmowia 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
Details
npm
2026-10-27 13:03:18 +01:00
129
ISC
latest
113 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