@orbito/api-lib (3.3.3)
Installation
@orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/npm install @orbito/api-lib@3.3.3"@orbito/api-lib": "3.3.3"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 }
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', {});
}
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.
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.
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 |