Struktura modułu

Moduł Orbito to standardowy projekt Node.js z dwoma wymaganiami narzuconymi przez platformę: w katalogu głównym muszą znaleźć się pliki index.js (punkt wejścia) oraz module.json (manifest paczki). Poza tymi wymaganiami masz pełną swobodę w organizacji kodu.

Wymagany plik index.js

Plik index.js to punkt wejścia modułu — od niego Orbito uruchamia moduł w kontenerze Docker. Plik powinien wykonać całą konfigurację: zarejestrować metody, hooki i strony.

// index.js
const { Log, Core, Pages } = require('@orbito/api-lib');

// --- Rejestracja metod ---
Core.registerMethod('config.get', async (params, ctx) => {
  // logika metody
});

Core.registerMethod('config.save', async (params, ctx) => {
  // logika metody
});

// --- Rejestracja stron UI (widoki OVE w osobnych plikach) ---
Pages.registerPages({
  '/config': { name: 'Konfiguracja', view: 'pages/config.yaml' }
});

// --- Rejestracja hooków ---
Core.registerHook('core.shipping.getCarrier', async (order) => {
  // logika hooka
});

Log.info('Moduł załadowany');

Wymagany plik module.json

Każdy moduł musi zawierać w katalogu głównym paczki plik module.json — manifest opisujący tożsamość wersji. Repozytorium modułów odrzuca ZIP bez poprawnego manifestu już przy uploadzie, a manifest jest weryfikowany ponownie przy publikacji.

{
  "name": "moja-organizacja/inpost",
  "version": "1.0.0",
  "minOrbitoVersion": "2.0.0",
  "dependsOn": ["moja-organizacja/shipping-core"],
  "singleton": false
}

Flaga singleton

Flaga singleton decyduje o tym, czy jedna firma może zainstalować wiele instancji tego samego modułu. Typowy przypadek: firma obsługuje 3 sklepy Prestashop albo 2 konta InPost i dla każdego chce osobną, niezależnie skonfigurowaną instancję.

{
  "name": "moja-organizacja/prestashop",
  "version": "1.0.0",
  "singleton": false
}

• "singleton": true (wartość domyślna) — firma może mieć tylko jedną aktywną instancję modułu. Próba instalacji drugiej kończy się błędem.
• "singleton": false — firma może zainstalować dowolnie wiele instancji. Przy włączaniu kolejnej instancji użytkownik musi podać jej nazwę, unikalną wśród aktywnych instancji tego modułu w firmie (służy do rozróżniania ich w UI, nawigacji i automatyzacjach).

Sekrety aplikacji (secrets)

Niektóre moduły potrzebują kluczy, które należą do aplikacji autora modułu, a nie do firmy: clientId/clientSecret aplikacji zarejestrowanej w Allegro czy Amazon, klucz aplikacji partnerskiej wFirma. Takie wartości nie mogą leżeć w kodzie paczki — trafiłyby do każdego obrazu i repozytorium, a ich zmiana wymagałaby wydania nowej wersji modułu. Przechowuje je repozytorium modułów (zaszyfrowane), a Orbito przekazuje je do kontenera modułu jako zmienne środowiskowe.

Moduł deklaruje sekrety w module.json — tylko nazwy i opisy, nigdy wartości:

{
    "name": "core/allegro",
    "version": "1.2.0",
    "secrets": [
        { "name": "ALLEGRO_CLIENT_ID", "description": "Client ID aplikacji Allegro (produkcja)" },
        { "name": "ALLEGRO_CLIENT_SECRET", "description": "Client Secret aplikacji Allegro (produkcja)" }
    ]
}

• secrets jest opcjonalne — to tablica obiektów { name, description? },
• name to nazwa zmiennej środowiskowej: ^[A-Z][A-Z0-9_]*$, maks. 64 znaki, bez powtórzeń; prefiks ORBITO_ jest zarezerwowany dla zmiennych rdzenia,
• description jest opcjonalny, maks. 200 znaków — pokazuje się w omm secrets list i w panelu developera.

Wartości ustawiasz osobno, poza paczką — komendą omm secrets set albo w karcie modułu w panelu developera.

Odczyt w module

Każdy sekret trafia do kontenera jako zmienna środowiskowa o tej samej nazwie — moduł czyta go z process.env.NAZWA, bez żadnej metody SDK. Brak wartości nie powinien wywracać modułu: zgłoś problem przez Problems.report, a operację wymagającą klucza zakończ błędem. Gdy wartość się pojawi, skasuj zgłoszenie przez Problems.resolve:

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

const PROBLEM_KEY = 'app-keys';

async function getAppKeys() {
    const clientId = process.env.ALLEGRO_CLIENT_ID;
    const clientSecret = process.env.ALLEGRO_CLIENT_SECRET;

    if (!clientId || !clientSecret) {
        await Problems.report({
            problemKey: PROBLEM_KEY,
            code: 'ALLEGRO_APP_KEYS_MISSING',
            desc: {
                pl: 'Klucze aplikacji Allegro nie są skonfigurowane po stronie Orbito — skontaktuj się z administratorem platformy',
                en: 'Allegro application keys are not configured in Orbito — contact the platform administrator'
            }
        });
        throw new Error('Brak kluczy aplikacji Allegro');
    }

    await Problems.resolve({ problemKey: PROBLEM_KEY });
    return { clientId, clientSecret };
}

module.exports = { getAppKeys };

Zalecana struktura katalogów

Dla modułów o większej złożoności zaleca się poniższą strukturę:

moj-modul/
├── index.js          # punkt wejścia – wymagany przez Orbito
├── module.json       # manifest paczki – wymagany przez repozytorium modułów
├── package.json
├── package-lock.json
├── node_modules/
├── pages/            # widoki OVE rejestrowane przez Pages.registerPages
│   ├── config.yaml
│   └── dashboard.yaml
├── lib/              # logika biznesowa, helpery
│   ├── api.js
│   └── helpers.js
└── schemas/          # schematy DB
    └── config.js

Plik package.json

Minimalna konfiguracja package.json dla modułu Orbito:

{
  "name": "moj-modul",
  "version": "1.0.0",
  "description": "Opis modułu",
  "main": "index.js",
  "dependencies": {
    "@orbito/api-lib": "^4.3.0"
  }
}

Katalog node_modules nie trafia do paczki — omm wyklucza go zawsze, a zależności instaluje build kontenera na podstawie package.json i package-lock.json. Szczegóły w sekcji Pakowanie modułu.