Dart · Flutter · API v2

Profirest API pro Dart a Flutter

Knihovna Profirest API v2 pro Dart 3 a Flutter bez závislostí – pokladna, kuchyňský displej, kiosek a telefon kurýra na Androidu i iOS jednou knihovnou, i služby v Dartu na serveru.

The Profirest API v2 library for Dart 3 and Flutter without dependencies – the register, kitchen display, kiosk and courier phone on Android and iOS with one library, plus Dart services on a server.

Knihovna dělá za vás to, co jinak musí každá aplikace napsat a hlavně nezapomenout: spáruje zařízení kódem, připojí aplikaci partnera se souhlasem majitele (OAuth s PKCE), uloží tokeny a obnoví je jen jednou i při souběžných požadavcích a mezi procesy, přihlásí zaměstnance PINem nebo čipem, pošle Idempotency-Key u každého POST (při opakování stejný), po výpadku opakuje podle Retry-After, chyby vrací s kódem z katalogu, prochází stránky seznamů a čte proud událostí. Cesty, těla a odpovědi jsou přesně podle reference; modely všech schémat jsou vygenerované ze smlouvy.

The library does what every application otherwise has to write and, above all, not forget: it pairs a device with a code, connects a partner application with the owner's consent (OAuth with PKCE), stores the tokens and refreshes them only once even for concurrent requests and across processes, signs employees in with a PIN or a card, sends an Idempotency-Key with every POST (the same one when retrying), retries after an outage following Retry-After, returns errors with a code from the catalog, walks list pages and reads the event feed. Paths, bodies and responses are exactly as in the reference; models of all schemas are generated from the contract.

Ke stažení

Download

Archiv obsahuje knihovnu, příkladového klienta, jednotkové testy, README s podrobným návodem, licenci (MIT) a seznam změn. Instalujte ho z archivu, jak ukazuje návod níže. Výchozí adresa knihovny je ostrá https://api.mujprofirest.cz – pracuje nad ostrými daty restaurací, zkoušejte na testovací provozovně.

The archive contains the library, the example client, unit tests, a README with a detailed guide, the licence (MIT) and the changelog. Install it from the archive as shown below. The default address of the library is production https://api.mujprofirest.cz – it works on live restaurant data, test on a test restaurant.

Instalace

Installation

Archiv rozbalte vedle projektu a přidejte ho jako path závislost (po zveřejnění stačí dart pub add profirest_api / flutter pub add profirest_api):

Unpack the archive next to your project and add it as a path dependency (once published, dart pub add profirest_api / flutter pub add profirest_api is enough):

dependencies:
  profirest_api:
    path: ../profirest-api-dart-1.0.0

import 'package:profirest_api/profirest_api.dart';
import 'package:profirest_api/io.dart';            // FileStorage, IoTransport (ne na webu)
import 'package:profirest_api/models.dart' as pr; // modely (pr. – Flutter má vlastní Tab a Category)

Příkladový klient

Example client

Hotová aplikace k vyzkoušení: docházkový terminál v příkazové řádce. Při prvním spuštění zařízení spáruje (vypíše kód, vedoucí ho potvrdí v administraci v Správa PC / zařízení → Připojit kódem), tokeny uloží do souboru a pak přijímá příkazy. Ukazuje párování, píchnutí PINem, výběr zaměstnance při stejném PINu, rozlišení chyb podle kódu a seznam lidí v práci. Adresu API mění proměnná PROFIREST_BASE_URL, soubor s tokeny PROFIREST_TOKENS.

A ready application to try: an attendance terminal on the command line. On the first run it pairs the device (it prints a code that a manager confirms in the administration under PC / devices → Connect a device), stores the tokens in a file and then accepts commands. It shows pairing, punching with a PIN, choosing the employee when a PIN is shared, telling errors apart by code and the list of people at work. PROFIREST_BASE_URL changes the API address, PROFIREST_TOKENS the token file.

dart run example/pichacka.dart

// Příkladový klient Profirest API v2: docházkový terminál v příkazové řádce.
//
//   dart run example/pichacka.dart
//
// Při prvním spuštění zařízení spáruje – vypíše kód, který vedoucí potvrdí v administraci (Správa PC / zařízení →
// Připojit zařízení). Pak čte příkazy:
//   p PIN   příchod            o PIN   odchod
//   pz PIN  začátek přestávky  kz PIN  konec přestávky
//   k       kdo je v práci     odparovat   zapomenout spárování     q   konec
//
// Proměnné prostředí: PROFIREST_BASE_URL (výchozí https://api.mujprofirest.cz), PROFIREST_TOKENS (soubor s tokeny,
// výchozí profirest-pichacka.json vedle příkladu – chraňte ho jako heslo).
//
// Ve Flutteru je postup stejný: místo FileStorage dejte úložiště aplikace (viz README) a kód ukažte na displeji.
import 'dart:async';
import 'dart:convert';
import 'dart:io';

import 'package:profirest_api/io.dart';
import 'package:profirest_api/profirest_api.dart';

const types = {'p': 'clock_in', 'o': 'clock_out', 'pz': 'break_start', 'kz': 'break_end'};
const states = {'working': 'v práci', 'on_break': 'na přestávce', 'off': 'mimo práci'};

late final StreamIterator<String> input;

/// Další řádek ze vstupu, null na konci.
Future<String?> readLine() async => await input.moveNext() ? input.current : null;

Future<void> main() async {
  stdout.encoding = utf8;
  input = StreamIterator(stdin.transform(utf8.decoder).transform(const LineSplitter()));
  final env = Platform.environment;
  final tokens = env['PROFIREST_TOKENS'] ?? '${File.fromUri(Platform.script).parent.path}${Platform.pathSeparator}profirest-pichacka.json';
  final api = ProfirestApi(
    baseUrl: env['PROFIREST_BASE_URL'] ?? 'https://api.mujprofirest.cz',
    clientId: 'profirest-dochazka',
    storage: FileStorage(tokens),
  );

  // 1) spárování kódem (RFC 8628) – jen poprvé, tokeny pak zůstávají v souboru
  if (!await api.isPaired()) {
    try {
      final pairing = await api.pair(
        scope: 'restaurants:read staff:read staff:authenticate attendance:read attendance:punch',
        deviceName: 'Píchačka (příklad)',
      );
      print('Zařízení není spárované. Vedoucí potvrdí kód v administraci (Správa PC / zařízení → Připojit zařízení).');
      print('KÓD: ${pairing.userCode}');
      print('nebo otevřete: ${pairing.verificationUriComplete}');
      await pairing.connected; // ptá se podle intervalu, než vedoucí potvrdí
    } on OAuthError catch (e) {
      print(switch (e.error) {
        'access_denied' => 'Vedoucí párování odmítl.',
        'expired_token' => 'Kód vypršel (10 minut). Spusťte příklad znovu.',
        _ => 'Párování se nepovedlo: ${e.message}',
      });
      exit(1);
    } on ApiError catch (e) {
      print('Párování se nepovedlo: ${e.message}');
      exit(1);
    }
  }
  if (await api.restaurantId() == null) {
    await api.connection(); // zapamatuje provozovnu zařízení
  }
  final rid = (await api.restaurantId())!;
  print('Provozovna $rid. Příkazy: p/o/pz/kz PIN, k = kdo je v práci, odparovat, q = konec.');

  // 3) smyčka příkazů
  for (;;) {
    final line = await readLine();
    if (line == null) {
      break;
    }
    final parts = line.trim().split(RegExp(r'\s+'));
    final cmd = parts[0].toLowerCase();
    final arg = parts.length > 1 ? parts.sublist(1).join(' ') : null;
    try {
      if (types.containsKey(cmd) && arg != null) {
        await punch(api, rid, types[cmd]!, arg);
      } else if (cmd == 'k') {
        for (final p in await api.all('/restaurants/$rid/attendance/presence')) {
          print('  ${p['employee']['name']}: ${states[p['state']] ?? p['state']}');
        }
      } else if (cmd == 'odparovat') {
        await api.unpair();
        print('Spárování zapomenuto.');
        break;
      } else if (cmd == 'q') {
        break;
      } else if (cmd.isNotEmpty) {
        print('Příkazy: p/o/pz/kz PIN, k, odparovat, q');
      }
    } on ApiError catch (e) {
      if (e.code == ErrorCode.notPaired) {
        // vedoucí zařízení odpároval
        print('Zařízení bylo odpárováno. Spusťte příklad znovu.');
        exit(1);
      }
      print('Chyba: ${e.title} (${e.code})');
    }
  }
  await input.cancel();
  exit(0);
}

// 2) píchnutí – id vznikne jednou na píchnutí; při opakování (výběr zaměstnance, výpadek) se posílá stejné
Future<void> punch(ProfirestApi api, String rid, String type, String pin) async {
  final credential = <String, Object>{'method': 'pin', 'secret': pin};
  final body = {'id': ProfirestApi.uuid(), 'type': type, 'credential': credential};
  for (;;) {
    try {
      final r = await api.post('/restaurants/$rid/attendance/punches', body);
      print('OK: ${r['employee']['name']} – ${states[r['state']] ?? r['state']}');
      return;
    } on ApiError catch (e) {
      switch (e.code) {
        case ErrorCode.staffAmbiguous: // stejný PIN má víc lidí – vybrat a poslat znovu
          print('Tento PIN má víc lidí:');
          for (var i = 0; i < e.candidates.length; i++) {
            print('  ${i + 1}) ${e.candidates[i]['name']}');
          }
          stdout.write('Číslo: ');
          final choice = int.tryParse((await readLine() ?? '').trim()) ?? 0;
          if (choice < 1 || choice > e.candidates.length) {
            print('Zrušeno.');
            return;
          }
          credential['employee_id'] = e.candidates[choice - 1]['id'] as Object;
          continue;
        case ErrorCode.staffCredentialsInvalid:
          print('Neznámý PIN.');
        case ErrorCode.staffLocked:
          print('Moc špatných pokusů – zkuste to za ${e.retryAfter} s.');
        case ErrorCode.attendanceStateConflict:
          print('Teď to nejde: ${e.title}');
        case ErrorCode.networkError:
        case ErrorCode.timeout:
          print('Bez sítě – zkuste znovu.'); // skutečný terminál by píchnutí uložil a poslal dávkou
        default:
          print('Chyba: ${e.title} (${e.code})');
      }
      return;
    }
  }
}

Spárovat zařízení

Pair a device

Pokladna, kuchyňský displej, docházkový terminál a telefon kurýra se připojují kódem (RFC 8628). Zařízení ukáže kód, vedoucí ho zadá v administraci (Správa PC / zařízení → Připojit kódem) a vybere provozovnu; zařízení si tokeny vyzvedne samo a pak pracuje jen pro ni. Kód platí 10 minut; knihovna se ptá podle interval (5 s), po slow_down o 5 s déle a výpadek sítě přečká. Odmítnutí vedoucím = access_denied, propadlý kód = expired_token.

A register, kitchen display, attendance terminal and courier phone connect with a code (RFC 8628). The device shows the code, a manager enters it in the administration (PC / devices → Connect a device) and chooses the restaurant; the device collects its tokens itself and then works only for it. The code is valid for 10 minutes; the library polls every interval (5 s), 5 s slower after slow_down, and survives a network outage. A refusal by the manager = access_denied, an expired code = expired_token.

final api = ProfirestApi(
  clientId: 'profirest-kds',
  storage: SecureTokenStorage(),                    // adaptér nad flutter_secure_storage (Tokeny a úložiště)
  onUnpaired: (reason) => navigator.pushReplacementNamed('/parovani'),
);

Future<void> startPairing() async {
  try {
    final pairing = await api.pair(scope: 'restaurants:read staff:read staff:authenticate attendance:read attendance:punch', deviceName: 'KDS kuchyň', appVersion: '2.3.0');
    setState(() => code = pairing.userCode);        // + QR z pairing.verificationUriComplete
    await pairing.connected;                        // dotazuje se samo podle intervalu
    navigator.pushReplacementNamed('/kds');
  } on OAuthError catch (e) {
    showError(e.error);                             // access_denied, expired_token
  }
}
// dispose(): pairing.cancel()

Po startu aplikace stačí if (await api.isPaired()) …; provozovna je await api.restaurantId() (úložiště ve Flutteru je asynchronní, proto Future). Server, který se ptá v dalších požadavcích: pairing.toJson() a api.resumePairing(json).poll().

After the app starts, if (await api.isPaired()) … is enough; the restaurant is await api.restaurantId() (Flutter storage is asynchronous, hence Futures). A server asking in later requests: pairing.toJson() and api.resumePairing(json).poll().

Docházkový terminál

Attendance terminal

POST /v2/restaurants/{restaurant_id}/attendance/punches. Na terminálu se nikdo nepřihlašuje – každé píchnutí nese PIN nebo čip. id vznikne na zařízení ve chvíli píchnutí (UUIDv7 řazené podle času) a stejné id server nikdy nezapíše dvakrát: první zápis vrátí 201, opakování 200 se stejným tělem. Chyby se rozlišují podle kódu, ne podle HTTP stavu.

POST /v2/restaurants/{restaurant_id}/attendance/punches. Nobody signs in on a terminal – every punch carries a PIN or a card. The id is made on the device when the person punches (a time-ordered UUIDv7) and the server never records the same id twice: the first write returns 201, a repeat 200 with the same body. Errors differ by code, not by HTTP status.

final body = {
  'id': ProfirestApi.uuid(),                        // UUIDv7
  'type': 'clock_in',                               // clock_out, break_start, break_end
  'credential': {'method': 'pin', 'secret': pin},
};
try {
  final punch = pr.AttendancePunch.fromJson(
      await api.post('/restaurants/${await api.restaurantId()}/attendance/punches', body));
  showDone(punch.employee.name, punch.state);       // working, on_break, off
} on ApiError catch (e) {
  switch (e.code) {
    case ErrorCode.staffAmbiguous: chooseEmployee(e.candidates);   // znovu se stejným id a employee_id
    case ErrorCode.staffCredentialsInvalid: showWrongPin();
    case ErrorCode.staffLocked: showLocked(e.retryAfter);
    case ErrorCode.networkError || ErrorCode.timeout: saveOffline(body);
    default: showMessage(e.title);
  }
}

Bez sítě píchnutí uložte i s id a časem occurred_at a pošlete později dávkou (nejvýš 100) na POST …/attendance/punches/batch – každá položka má vlastní výsledek. Frontu držte jen na zařízení, nese PINy.

Without a network store the punch with its id and occurred_at and send it later in a batch (at most 100) to POST …/attendance/punches/batch – every item gets its own result. Keep the queue on the device only, it carries PINs.

Pokladna a zaměstnanec

Register and employee

Na pokladně se zaměstnanec přihlásí PINem nebo čipem a knihovna pak posílá jeho token v hlavičce Profirest-Staff-Token u každého požadavku sama; token drží jen v paměti. Relace vyprší po nečinnosti (idle_timeout_seconds, každý úspěšný požadavek ji prodlouží) a nejpozději v max_expires_at – počítá se podle hodin zařízení. Stejný PIN víc lidí = 409 staff_ambiguous s kandidáty: nechte vybrat a zavolejte znovu s employee_id. Volba staff u požadavku: automaticky (výchozí – poslat, je-li někdo přihlášený), vyžadovat (bez přihlášení chyba staff_session_required a nic se neodešle), neposílat, nebo konkrétní token.

On a register an employee signs in with a PIN or a card and the library then sends their token in the Profirest-Staff-Token header with every request itself; the token stays in memory only. The session ends after inactivity (idle_timeout_seconds, every successful request extends it) and at max_expires_at at the latest – counted by the device clock. Several people with the same PIN = 409 staff_ambiguous with candidates: let the person choose and call again with employee_id. The staff request option: automatic (default – send it when somebody is signed in), required (without a sign-in the error staff_session_required and nothing is sent), never, or a specific token.

try {
  await api.signInStaff(rid, {'method': 'pin', 'secret': pin});
} on ApiError catch (e) {
  if (e.code != ErrorCode.staffAmbiguous) rethrow;
  final who = await chooseEmployee(e.candidates);
  await api.signInStaff(rid, {'method': 'pin', 'secret': pin, 'employee_id': who['id']});
}
await api.post('/restaurants/$rid/receipts', receipt, staff: true);   // bez přihlášení se ani neodešle
await api.signOutStaff();

Aplikace partnera

Partner application

E-shop nebo jiná aplikace partnera se připojuje se souhlasem majitele restaurace (authorization code + PKCE S256). Na serveru je to důvěrný klient: client_secret posílá knihovna jako HTTP Basic (client_secret_basic, RFC 6749 2.3.1) a nikdy nepatří do aplikace u zákazníka. Ověřovač PKCE a state drží mezi přesměrováním a zpětným voláním úložiště; zpětné volání ověří state a iss (RFC 9207) a vymění kód za tokeny. Jedna instance = jedno připojení: tokeny i rozpracovaný souhlas leží pod jedním klíčem úložiště a výchozí klíč (profirest-api:<clientId>) je jeden pro celou aplikaci. Pro každý připojený účet proto použijte vlastní instanci s vlastním klíčem úložiště odvozeným z ID účtu ve vašem systému (znáte ho už před přesměrováním) – se společným klíčem by souhlas dalšího majitele přepsal tokeny předchozího a dva souběžné souhlasy by si přepsaly state. Víc provozoven jednoho majitele je jedno připojení. Když už token máte odjinud, předejte ho jako pevný access token – knihovna ho pošle a nikdy neobnovuje.

An e-shop or another partner application connects with the consent of the restaurant owner (authorization code + PKCE S256). On a server it is a confidential client: the library sends the client_secret as HTTP Basic (client_secret_basic, RFC 6749 2.3.1) and it never belongs into an app on the customer's device. The PKCE verifier and state are kept in the storage between the redirect and the callback; the callback checks state and iss (RFC 9207) and exchanges the code for tokens. One instance = one connection: the tokens and a consent in progress sit under one storage key, and the default key (profirest-api:<clientId>) is one for the whole application. So use a separate instance with its own storage key for every connected account, derived from the account ID in your system (you know it before the redirect) – with a shared key the consent of the next owner would overwrite the tokens of the previous one and two concurrent consents would overwrite each other's state. Several restaurants of one owner are one connection. When you already have a token from elsewhere, pass it as a fixed access token – the library sends it and never refreshes it.

final api = ProfirestApi(
  clientId: 'muj-eshop',
  clientSecret: Platform.environment['PROFIREST_CLIENT_SECRET'],     // jen na serveru
  storage: FileStorage('/var/lib/eshop/profirest-tokens.json'),
  storageKey: 'account-7',
);

// tlačítko „Připojit Profirest“ – přesměrovat prohlížeč
final url = await api.authorizationUrl(
    redirectUri: 'https://eshop.example.cz/profirest/callback', scope: 'restaurants:read catalog:read orders:write');

// zpětné volání – ověří state a iss, vymění kód za tokeny
final connection = await api.completeAuthorization(request.requestedUri);   // String, Uri nebo mapa parametrů

Požadavky

Requests

Cesty se píšou relativně k /v2, přesně jako v referenci (/oauth/… a /.well-known/… jdou od kořene). Tělo: objekt nebo model → JSON; řetězec nebo bajty → syrově s typem obsahu (zálohy ZIP). Dotaz: prázdné hodnoty se vynechají, pole se spojí čárkou. Odpověď: JSON dekódovaný, 204 nic, jiný obsah bajty. U POST pošle knihovna vlastní Idempotency-Key a při automatickém opakování stejný; když požadavek opakujete vy (po restartu aplikace), předejte vlastní klíč uložený u záznamu. Klíč knihovny žije jen v paměti procesu, po pádu aplikace ho nemáte – u zápisů, které se nesmí provést dvakrát (objednávka), proto vlastní klíč vytvořte a uložte k záznamu dřív, než požadavek odešlete (server výsledek drží 24 hodin). Objednávka má navíc pojistky nezávislé na klíči: kalkulace jde použít jen jednou (409 quote_already_used) a external_id je trvalé (409 external_id_conflict); obě chyby nesou ID existující objednávky. Tokeny (Authorization i Profirest-Staff-Token) odcházejí jen na adresu API, nikdy na cizí absolutní adresu; přesměrování se nesledují.

Paths are written relative to /v2, exactly as in the reference (/oauth/… and /.well-known/… go from the root). Body: an object or a model → JSON; a string or bytes → raw with a content type (ZIP backups). Query: empty values are left out, arrays are joined with a comma. Response: JSON decoded, 204 nothing, other content bytes. For a POST the library sends its own Idempotency-Key and the same one on an automatic retry; when you repeat a request yourself (after an application restart), pass your own key stored with the record. The library's key lives only in the memory of the process, after a crash you do not have it – for writes that must not happen twice (an order) create your own key and store it with the record before you send the request (the server keeps the result for 24 hours). An order also has guards that do not depend on the key: a quote can be used only once (409 quote_already_used) and external_id is permanent (409 external_id_conflict); both errors carry the ID of the existing order. Tokens (Authorization and Profirest-Staff-Token) go only to the API address, never to a foreign absolute URL; redirects are not followed.

final catalog = await api.get('/restaurants/11/catalog', query: {'channel': 'pos'});

// stav a hlavičky (ETag, Location)
final r = await api.get('/customers/$id', withResponse: true) as ApiResponse;
await api.patch('/customers/$id', {'name': 'Jana Nováková'}, ifMatch: r.header('ETag'));

// vlastní Idempotency-Key uložený u objednávky
await api.post('/restaurants/11/orders', order, idempotencyKey: 'order-$localId');

// binární tělo a stažení
await api.post('/restaurants/$rid/backups', await File('zaloha.zip').readAsBytes(), contentType: 'application/zip');
final zip = await api.get('/restaurants/$rid/backups/$backupId/content', accept: 'application/zip');

Seznamy po stránkách

Paged lists

Seznamy vrací {data, next_cursor}. Knihovna projde stránky sama (všechny položky najednou, nebo stránku po stránce); konec je stránka bez next_cursor nebo prázdná stránka. Kurzor je neprůhledný řetězec – nikdy ho neskládejte.

Lists return {data, next_cursor}. The library walks the pages itself (all items at once, or page by page); the end is a page without next_cursor or an empty page. The cursor is an opaque string – never build one.

final staff = await api.all('/restaurants/11/staff');
await for (final page in api.pages('/restaurants/11/attendance/presence')) {
  render(page['data']);
}

Proud událostí

Event feed

Proud událostí knihovna čte dokola. Když běží služba proudu, čte živě GET /v2/events/stream (Server-Sent Events) – událost přijde pár sekund po změně a nic se nedotazuje. Když neběží (503), na starším serveru nebo s vlastním transportem, který neumí číst odpověď po kouscích, čte GET /v2/events a o proud se pokusí znovu za Retry-After (výchozí 5 minut). Kurzor je v obou stejný (u proudu jde jako Last-Event-ID), přechod nic nepřeskočí; výpadek spojení není chyba – připojí se znovu za 2 s, 4 s, po třetím nezdaru minutu dotazuje. Volba stream (výchozí zapnuto; vypnuto = jen dotazování) a dotaz, zda teď běží proud, mají jména podle jazyka (viz Metody); krok pro cron (once) dělá dál jeden dotaz GET /v2/events. Kurzor posune a uloží až po úspěšném zpracování – událost tak přijde aspoň jednou, zpracování má být idempotentní (např. podle id události). Plnou stránku dožene hned, jinak čeká interval (5 s); bez uloženého kurzoru začne na konci proudu. Po 410 cursor_expired zavolá obsluhu resetu (načtěte si stav znovu), při chybě čeká podle Retry-After nebo déle a déle (až 60 s) a ztráta spárování čtení ukončí. limit je nejvýš 100. Kurzor leží v úložišti pod events_cursor[:provozovna][:typy].

The library reads the event feed in a loop. While the stream service runs, it reads GET /v2/events/stream live (Server-Sent Events) – an event arrives a few seconds after the change and nothing is polled. When it does not run (503), on an older server or with a custom transport that cannot read a response in pieces, it reads GET /v2/events and tries the stream again after Retry-After (5 minutes by default). The cursor is the same in both (the stream gets it as Last-Event-ID), switching skips nothing; a dropped connection is not an error – it reconnects after 2 s, 4 s, and after the third failure polls for a minute. The stream option (on by default; off = polling only) and the query whether the stream runs now are named per language (see Methods); the cron step (once) still makes one GET /v2/events request. It moves and stores the cursor only after successful processing – an event arrives at least once, so processing should be idempotent (for example by the event id). A full page is caught up at once, otherwise it waits the interval (5 s); without a stored cursor it starts at the end of the feed. After 410 cursor_expired it calls the reset handler (reload your state), on an error it waits per Retry-After or longer and longer (up to 60 s), and losing the pairing ends the reading. limit is at most 100. The cursor lives in the storage under events_cursor[:restaurant][:types].

final feed = api.watchEvents(
  restaurantId: rid,
  types: ['kitchen.ticket_updated', 'order.created', 'order.status_changed'],
  onEvents: (events) async { await reloadBoard(); },   // výjimka = stránka přijde znovu
  onReset: (error) => reloadBoard(),
)..start();                                             // živý proud; bez služby (a na webu) dotazuje
// feed.isStreaming – běží proud; dispose(): feed.stop()

Chyby

Errors

Každá chyba API přijde jako výjimka s kódem z katalogu (RFC 9457). Rozhodujte se podle kódu, ne podle HTTP stavu – kódy se nikdy nemění, nové mohou přibýt. Název pro člověka je česky nebo anglicky podle volby jazyka.

Every API error arrives as an exception with a code from the catalog (RFC 9457). Decide by the code, not by the HTTP status – codes never change, new ones may come. The title for a person is in Czech or English depending on the language option.

try {
  await api.post('/restaurants/$rid/quotes', quote);
} on ApiError catch (e) {
  if (e.code == ErrorCode.validationFailed) {
    for (final f in e.errors) print('${f['pointer']}: ${f['message']}');
  }
  log('Profirest ${e.code} (${e.requestId})');
}

Kódy jen z knihovny

Library-only codes

Opakování a výpadky

Retries and outages

Knihovna opakuje jen to, co opakovat jde, nejvýš 3× se stejným tělem a Idempotency-Key. Odstup se zdvojnásobuje od 1 s do 30 s s rozptylem ±25 %, aby se zařízení po výpadku nevrátila všechna najednou. Retry-After (sekundy i HTTP datum) má přednost; delší než 30 s knihovna nečeká a vrátí chybu s počtem sekund.

The library retries only what can be retried, at most 3× with the same body and Idempotency-Key. The delay doubles from 1 s up to 30 s with ±25 % jitter so devices do not all come back at once after an outage. Retry-After (seconds or an HTTP date) wins; the library does not wait longer than 30 s and returns the error with the seconds.

Tokeny a úložiště

Tokens and storage

Stav klienta (tokeny, provozovna zařízení, kurzory událostí) ukládá rozhraní úložiště se třemi metodami – načíst, uložit a smazat řetězec. Paměťové úložiště vydrží do konce procesu, souborové drží JSON s právy jen pro vlastníka. Access token platí 30 minut; knihovna ho obnoví minutu před koncem a po 401 invalid_token. Refresh token veřejného klienta platí jen na jedno použití – sdílí-li úložiště víc procesů, obnovuje pod zámkem úložiště jen jeden a ostatní použijí jeho nový token. invalid_grant (zařízení odpárováno) tokeny smaže a zavolá obsluhu odpárování; invalid_client a unauthorized_client jsou přechodné a tokeny nechá. Pod klíčem profirest-api:<client_id> leží JSON se stejnými klíči ve všech knihovnách.

The client state (tokens, the device's restaurant, event cursors) is kept by a storage interface with three methods – read, write and delete a string. Memory storage lasts until the process ends; file storage keeps JSON readable by the owner only. An access token is valid for 30 minutes; the library refreshes it a minute before the end and after 401 invalid_token. A public client's refresh token is single-use – when several processes share the storage, only one refreshes under the storage lock and the others use its new token. invalid_grant (device unpaired) deletes the tokens and calls the unpaired handler; invalid_client and unauthorized_client are temporary and keep them. Under the key profirest-api:<client_id> lies JSON with the same keys in every library.

import 'package:flutter_secure_storage/flutter_secure_storage.dart';

class SecureTokenStorage implements TokenStorage {   // Keychain / Keystore – doporučeno pro tokeny
  final _s = const FlutterSecureStorage();
  @override Future<String?> get(String key) => _s.read(key: key);
  @override Future<void> set(String key, String value) => _s.write(key: key, value: value);
  @override Future<void> remove(String key) => _s.delete(key: key);
}

MemoryStorage() (výchozí) vydrží do konce procesu, FileStorage(path) zamyká <soubor>.lock pro víc procesů na serveru. Ve Flutteru držte klienta v hlavním izolátu – souběžné požadavky se podělí o jednu obnovu tokenu. Na webu předejte vlastní HttpTransport (README).

MemoryStorage() (default) lasts until the process ends, FileStorage(path) locks <file>.lock for several processes on a server. In Flutter keep the client in the main isolate – concurrent requests share one token refresh. On the web pass your own HttpTransport (README).

Reference

Volby klienta

Client options

final api = ProfirestApi(clientId: '…', storage: …);

Metody

Methods

Pojmenované volby požadavku: query, contentType, idempotencyKey (false = bez klíče), ifMatch, ifNoneMatch, staff ('auto', true, false, token), retries, timeout, accept, headers, auth, withResponse.

Named request options: query, contentType, idempotencyKey (false = no key), ifMatch, ifNoneMatch, staff ('auto', true, false, a token), retries, timeout, accept, headers, auth, withResponse.

Bezpečnost

Security

• client_secret patří jen na server, nikdy do aplikace na zařízení nebo v prohlížeči.
• client_secret belongs on a server only, never into an app on a device or in a browser.
• Tokeny zařízení patří zařízení a jen jeho provozovně. Soubor s tokeny chraňte jako heslo; ztracené zařízení odpárujte v administraci – tokeny přestanou platit hned.
• Device tokens belong to the device and its restaurant only. Protect the token file like a password; unpair a lost device in the administration – its tokens stop working at once.
• Token zaměstnance zůstává jen v paměti a končí nečinností. PIN knihovna nikam neukládá.
• The staff token stays in memory only and ends with inactivity. The library never stores a PIN.
• Tokeny odcházejí jen na adresu API; přesměrování se nesledují.
• Tokens go only to the API address; redirects are not followed.
• Offline fronta docházkového terminálu nese PINy – držte ji jen na zařízení a po odeslání ji smažte.
• The offline queue of an attendance terminal carries PINs – keep it on the device only and delete it after sending.

Změny

Changes