Config

Moduł Config to magazyn konfiguracji modułu przechowywany przez platformę Orbito (od SDK 2.3.0). Rozwiązuje dwa problemy:

1. Przechowywanie ustawień — klucze API, adresy sklepów, mapowania statusów itd. bez tworzenia własnej kolekcji z jednym dokumentem typu store_config.
2. Ekran ustawień bez pisania UI — moduł deklaruje bloki konfiguracyjne (registerConfigBlocks), a panel Orbito sam renderuje z nich stronę konfiguracji z formularzami, walidacją, obsługą sekretów i własnymi przyciskami akcji (od SDK 3.3.0). Użytkownik znajdzie ją pod Ustawienia → Moduły → Konfiguruj.

const { Config } = require('@orbito/api-lib');

Odczyt i zapis wartości

const { Config } = require('@orbito/api-lib');

await Config.set('inpost.api_key', 'abc123');
let apiKey = await Config.get('inpost.api_key');
let mode = await Config.get('inpost.mode', 'sandbox'); // wartość domyślna

// ustawienia per użytkownik (userId zwykle z ctx.userId handlera metody)
await Config.forUser(ctx.userId).set('print_label', true);
let autoPrint = await Config.forUser(ctx.userId).get('print_label', false);

registerConfigBlocks — ekran ustawień modułu

Config.registerConfigBlocks(blocks) deklaruje bloki ustawień modułu. Wywołaj ją raz, przy starcie modułu. Panel Orbito:

• pokaże przycisk Konfiguruj przy module (bez uruchamiania kontenera),
• wyrenderuje stronę konfiguracji z zakładką per blok,
• po zapisie przez użytkownika wywoła Twoją funkcję validate, a gdy przejdzie — sam zapisze wartości do magazynu konfiguracji,
• wyrenderuje zadeklarowane przez blok akcje jako przyciski przy formularzu.

const { Config } = require('@orbito/api-lib');
const { PropertyType, DisplayFormat } = Config;

await Config.registerConfigBlocks({
  general: {
    title: { pl: 'Połączenie z InPost', en: 'InPost connection' },
    scope: 'global',

    schema: async (actualConfig) => ({
      apiKey: {
        type: PropertyType.STRING,
        format: DisplayFormat.SECRET,
        name: { pl: 'Klucz API', en: 'API key' },
        required: true
      },
      sandbox: {
        type: PropertyType.BOOLEAN,
        name: { pl: 'Tryb testowy (sandbox)', en: 'Sandbox mode' }
      },
      hint: {
        type: PropertyType.INFO,
        name: { pl: 'Klucz API znajdziesz w panelu InPost w zakładce Moje konto → API.' }
      }
    }),

    validate: async (params, raport) => {
      if (!params.apiKey) {
        raport.addError('apiKey', 'Klucz API jest wymagany');
        return;
      }
      const ok = await InpostApi.checkKey(params.apiKey, params.sandbox);
      if (!ok) raport.addError('apiKey', 'Niepoprawny klucz API');
    }
  },

  print: {
    title: { pl: 'Preferencje wydruku', en: 'Print preferences' },
    scope: 'user',
    schema: {
      autoPrint: {
        type: PropertyType.BOOLEAN,
        name: { pl: 'Drukuj etykietę automatycznie po utworzeniu' }
      }
    }
    // validate jest opcjonalne — brak oznacza, że każdy zapis przechodzi
  }
});

Klucz bloku jest prefiksem zmiennych

Wartości zapisane przez formularz lądują pod kluczami blok.pole. Blok general z polem apiKey odczytasz tak:

let apiKey = await Config.get('general.apiKey');

// blok scope: 'user' — czytaj w scope użytkownika z ctx
let autoPrint = await Config.forUser(ctx.userId).get('print.autoPrint', false);

Definicja bloku

Format schemy (DeclarativeSchema)

Ten sam format co parametry akcji i triggerów automatyzacji — panel renderuje z niego kontrolki formularza. Każde pole:

fieldKey: {
  type: PropertyType.STRING,        // string | number | boolean | datetime | array | info
  format: DisplayFormat.SECRET,     // opcjonalna podpowiedź UI/walidacji
  name: { pl: 'Etykieta pola' },    // string lub mapa język → tekst
  description: { pl: 'Dodatkowy opis pod polem' }, // opcjonalne
  required: true,                   // opcjonalne
  options: { values: [ { id: 'a', label: 'A' } ] } // opcjonalny dropdown (statyczny lub dynamiczny)
}

Najważniejsze DisplayFormat: SECRET, EMAIL, URL, PHONE, TEXT (textarea), HTML, MARKDOWN, CRON, formaty liczbowe (INTEGER, POSITIVE_DECIMAL, ...) oraz DATE_ONLY/TIME_ONLY dla DATETIME.

warehouses: {
  type: PropertyType.INFO,
  format: DisplayFormat.MARKDOWN,
  name: { pl: 'Dostępne magazyny', en: 'Available warehouses' },
  description: {
    pl: '| ID | Nazwa |\n| --- | --- |\n| 1 | Magazyn główny |\n| 2 | Magazyn zwrotów |',
    en: '| ID | Name |\n| --- | --- |\n| 1 | Main warehouse |\n| 2 | Returns warehouse |'
  }
}

Sekrety (DisplayFormat.SECRET)

Pola oznaczone SECRET są traktowane szczególnie:

• zapisana wartość nigdy nie wraca do przeglądarki — użytkownik widzi tylko maskę •••••••• i informację, że wartość jest ustawiona,
• puste pole SECRET przy zapisie oznacza „bez zmian" (obecna wartość zostaje),
• Twoja funkcja validate zawsze dostaje kompletne dane — platforma podstawia aktualną wartość sekretu przed walidacją, więc np. test klucza API działa także wtedy, gdy użytkownik zmienił tylko inne pole.

Pola SECRET służą do danych użytkownika firmy (jego klucz API, hasło do konta). Klucze aplikacji autora modułu, wspólne dla wszystkich firm (np. clientSecret aplikacji marketplace'u), nie należą do konfiguracji — deklarujesz je jako sekrety aplikacji w module.json.

Walidacja — ValidationRaport

validate(params, raport) dostaje pełny obraz bloku po zapisie (stare + nowe wartości) oraz raport z jedną metodą:

raport.addError(fieldKey, 'Komunikat wyświetlany przy polu');

Zgłoszone błędy pokazują się użytkownikowi przy odpowiednich polach formularza, a zapis jest odrzucany w całości. Możesz w validate wykonywać operacje asynchroniczne (np. testowe wywołanie zewnętrznego API).

Akcje bloku (przyciski przy formularzu)

(od SDK 3.3.0)

Blok może wystawić actions — przyciski, które panel renderuje w stopce bloku, obok Zapisz. Kliknięcie uruchamia handler w module, a panel domyślnie pobiera blok ponownie, więc dynamiczna schema od razu pokazuje efekt akcji. Typowe zastosowania: „Dodaj nową regułę", „Testuj połączenie", „Synchronizuj teraz", „Rozłącz konto".

const { Config } = require('@orbito/api-lib');
const { ActionStyle } = Config;

await Config.registerConfigBlocks({
  rules: {
    title: { pl: 'Reguły wysyłki', en: 'Shipping rules' },

    // schema dynamiczna — pola generowane per reguła zapisana w configu
    schema: async (actualConfig) => buildRulesSchema(actualConfig),

    actions: {
      addRule: {
        title: { pl: 'Dodaj nową regułę', en: 'Add new rule' },
        style: ActionStyle.PRIMARY,
        handler: async (actualConfig, ctx) => {
          await addEmptyRule(actualConfig);
          return { message: 'Dodano regułę' }; // success i needReload domyślnie true
        }
      },
      clearRules: {
        title: { pl: 'Usuń wszystkie reguły', en: 'Remove all rules' },
        style: ActionStyle.DANGER,
        confirm: { pl: 'Na pewno usunąć wszystkie reguły?', en: 'Really remove all rules?' },
        handler: async () => { await clearRules(); } // brak `return` = sukces + reload
      }
    }
  }
});

Definicja akcji

Handler akcji

handler: async (actualConfig, ctx) => {
  // actualConfig — ZAPISANE wartości bloku (te same, które dostaje dynamiczna schema)
  // ctx.userId   — id użytkownika, który kliknął przycisk (dostępne też jako this.userId)
  return { success: true, message: 'Gotowe', needReload: true };
}

• actualConfig to zapisane wartości bloku — dla scope: 'user' wartości klikającego użytkownika. Handler nie widzi niezapisanego stanu formularza, więc jeśli akcja ma działać na świeżych danych, użytkownik musi najpierw zapisać blok.
• ctx to { userId } wywołującego; ten sam obiekt jest zbindowany jako this (użyj zwykłego function, jeśli chcesz z tego korzystać — funkcja strzałkowa ignoruje bindowanie).
• Wynik { success, message, needReload } — wszystkie pola opcjonalne:

• Brak return w handlerze = sukces z odświeżeniem bloku.
• Wyjątek rzucony z handlera nie jest błędem protokołu — wraca jako { success: false, message: error.message }, a blok i tak się odświeża (akcja mogła coś zmienić, zanim rzuciła).

Dynamiczny zestaw akcji

actions może być funkcją konfiguracji — wtedy zestaw przycisków zależy od stanu modułu:

actions: async (actualConfig) => {
  if (!actualConfig.apiKey) {
    return {}; // brak klucza → żadnych przycisków
  }
  return actualConfig.connected
    ? { disconnect: { title: { pl: 'Rozłącz konto', en: 'Disconnect' }, style: ActionStyle.DANGER, handler: disconnect } }
    : { connect: { title: { pl: 'Połącz konto', en: 'Connect' }, style: ActionStyle.PRIMARY, handler: connect } };
}

Zestaw jest rozwiązywany za każdym razem — i przy pobraniu schemy, i przy wykonaniu akcji. Akcji, której nie ma w aktualnym zestawie, nie da się wykonać, więc ukryty warunkowo przycisk nie zostanie wywołany „na skróty".

Zachowanie i dobre praktyki

• Zapis jest merge, nie replace — pola nieobecne w żądaniu zachowują obecną wartość, a pola spoza schemy są ignorowane.
• Schema może być dynamiczna: funkcja schema(actualConfig) dostaje aktualne wartości bloku (dla scope: 'user' — wartości edytującego użytkownika).
• Nie duplikuj bloków w wielu wywołaniach — registerConfigBlocks możesz wywołać kilka razy, ale zestaw zgłoszony do platformy zawsze odzwierciedla sumę zarejestrowanych bloków.
• Wartości z formularza czytaj zwykłym Config.get('blok.pole') — także we własnych metodach, hookach i akcjach automatyzacji.
• Akcja bloku to dobre miejsce na operacje, których nie da się wyrazić formularzem (test połączenia, dodanie pozycji do listy, ręczna synchronizacja) — ale sam zapis wartości zostaw przyciskowi Zapisz i funkcji validate.