Uprawnienia

System uprawnień pozwala ograniczać dostęp do metod modułu per użytkownik. Uprawnienia to płaskie kody tekstowe (np. orders.view) nadawane użytkownikom per firma w panelu Orbito. Platforma nie egzekwuje ich sama — przy każdym wywołaniu metody przekazuje modułowi tablicę uprawnień użytkownika w ctx.permissions, a moduł decyduje, czy wywołanie przepuścić (Core.hasPermission).

Z punktu widzenia twórcy modułu system sprowadza się do dwóch kroków:

1. Rejestracja kodów uprawnień przy starcie modułu (Core.registerPermission) — dzięki temu pojawią się w panelu Orbito, gdzie administrator firmy może je nadawać użytkownikom.
2. Sprawdzanie uprawnień w handlerach metod (Core.hasPermission).

{
  "dependencies": {
    "@orbito/api-lib": "^2.1.0"
  }
}

Kody uprawnień

• Kod składa się z segmentów [a-z0-9_-] rozdzielonych kropkami, np. orders.view, orders.edit, config.save.
• Moduł zawsze operuje krótkimi kodami — bez prefiksu modułu i bez wildcardów. Platforma sama prefiksuje je kodem modułu na potrzeby panelu i bazy (np. orders.view w module core/orders staje się core.orders.orders.view), ale w kodzie modułu nigdy nie używasz pełnej formy.
• W ctx.permissions moduł dostaje wyłącznie swoje uprawnienia użytkownika, już bez prefiksu — dokładnie te same kody, które podał w registerPermission. Uprawnienia do innych modułów nie są widoczne.

Core.registerPermission

Rejestruje kod uprawnienia wraz z opisem. Rejestracja służy wyłącznie temu, by panel Orbito znał listę możliwych uprawnień modułu — nie jest warunkiem działania hasPermission.

await Core.registerPermission(code, description)

Przykład — rejestracja przy starcie modułu:

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

await Core.registerPermission('orders.view', 'Podgląd zamówień');
await Core.registerPermission('orders.edit', 'Edycja zamówień');

Core.hasPermission

Sprawdza, czy tablica uprawnień użytkownika zawiera dane uprawnienie. Używaj w handlerach metod z tymi samymi krótkimi kodami, które podałeś w registerPermission.

Core.hasPermission(code, permissionsTable)

Zwraca boolean.

Semantyka:

• '*' w tablicy użytkownika ⇒ zawsze true. Tak oznaczani są właściciele i administratorzy firmy — mają wszystkie uprawnienia bez nadawania ich ręcznie.
• Kod bez wildcardów ⇒ zwykłe sprawdzenie obecności w tablicy.
• Wildcard działa tylko w kodzie sprawdzanym: segment * dopasowuje dokładnie jeden segment, a końcowa * dowolny niepusty ogon. Core.hasPermission('orders.*', perms) zwróci true, gdy użytkownik ma jakikolwiek kod pod tym prefiksem.

Pełny przykład

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

// Rejestracja (raz, przy starcie) — dzięki temu kody pojawią się w panelu Orbito
await Core.registerPermission('orders.view', 'Podgląd zamówień');
await Core.registerPermission('orders.edit', 'Edycja zamówień');

Core.registerMethod('order.delete', {
  params: {
    orderId: { type: 'string' },
  },
  handler: async (params, ctx) => {
    // Egzekwowanie — te same krótkie kody co w registerPermission
    if (!Core.hasPermission('orders.edit', ctx.permissions)) {
      throw new Error('PERMISSION_DENIED');
    }

    await OrdersSchema.deleteOne({ _id: params.orderId });
    return { ok: true };
  },
});