abra-flexi 0.6.0 → 0.8.0

package/README.md

@@ -1,9 +1,9 @@
 # ABRA Flexi Typescript client
 **English version follows**
 
-[ABRA Flexi](https://www.abra.eu/flexi/) je český Ekonomický software pro malé a střední podniky vyvýjený společností [ABRA Software](https://www.abra.eu). ABRA Flexi poskytuje přístup k datům pomocí REST API s veřejnou dokumentací. 
+[ABRA Flexi](https://www.abra.eu/flexi/) je český Ekonomický software pro malé a střední podniky vyvýjený společností [ABRA Software](https://www.abra.eu). ABRA Flexi poskytuje přístup k datům pomocí REST API s veřejnou dokumentací.
 
-ABRA Flexi Typescript client (AFTC) je knihovna pro přístup k REST API ABRA Flexi. Použitelná v prohlížeči i na serveru (Node.js) a poskytující metody pro dotazování a mutaci dat. 
+ABRA Flexi Typescript client (AFTC) je knihovna pro přístup k REST API ABRA Flexi. Použitelná v prohlížeči i na serveru (Node.js) a poskytující metody pro dotazování a mutaci dat.
 
 AFTC obsahuje třídu pro každou z evidencí v ABRA Flexi. Vlastnosti těchto tříd zároveň modelují vztahy mezi evidencemi.
 
@@ -16,29 +16,13 @@ Knihovna je distribuovaná jako npm balíček
 npm install abra-flexi
 ```
 
-**!! Zatím nedistribuováno !!**
-Místo npm použíjte přímo git repository a `npm link` (knihovnu mustí nejdříve přeložit).
-```
-git checkout git@github.com:tomasKavan/abraFlexiClient.git
-cd abraFlexiClient
-npm install
-npm run build:lib
-npm link
-```
-
-Ve svém projektu potom:
-
-```
-npm link abra-flexi
-```
-
-### Gnerování evidenčních tříd
+### Generování evidenčních tříd
 
 Součástní repository knihovny je nástroj pro generování evidenčních tříd z metadat, které poskytuje API. Generátor dovoluje vybrat subset generovaných tříd. To je užitečné, pokud chcete udržet knihovnu co nejmenší a generovat pouze třídy pro Vámi použivané evidence.
 
 Generátor je třeba přeložit
 ```
-npm run build:cli
+npm run build:gen
 chmod a+x ./bin/index.js
 ```
 
@@ -49,12 +33,12 @@ a následně lze generování spustit například takto:
 
 knihovnu s vygenerovanými třídami lze přeložit
 ```
-npm run build:cli
+npm run build
 ```
 
 ### Příklady
 
-Složka `examples` obsahuje příklady použití knihovny. Prozatím jsem připravil 
+Složka `examples` obsahuje příklady použití knihovny. Prozatím jsem připravil
 - jednoduchý CLI nástroj pro načtení konkrétní evidence (loadEntityCli.ts)
 - soubor s příkladem volání více typů dotazů (loadEntity.ts)
 - příklad vytvoŕení nové faktury. Nutno nastavit konstanty na řádku 29-31 (createAndSave.ts)
@@ -69,34 +53,59 @@ ts-node examples/createAndSave.ts -s https://muj.server.cz -c moje-firma -u uziv
 
 V návodu se používají pojmy
 - **evidence** Typ evidence v systému ABRA Flexi, například Faktura přijatá či Položka faktury přijaté. Každá evidence je reprezentováná evidenční třídou, například `AFFakturaPrijata` či `AFPolozkaFakturyPrijate`.
-- **instance** Záznam v evidenci. Například faktura přijatá s kódem IV24.0001, identifikátorem 14 a dlšími hodnotami je instancí. Instance je v knihovně reprezentována instancí evidenční třídy, například: `const fp = new AFFakturaPrijata()`.
+- **instance** Záznam v evidenci. Například faktura přijatá s kódem IV24.0001, identifikátorem 14 a dlšími hodnotami je instancí. Instance je v knihovně reprezentována instancí evidenční třídy, například: `const fp = await api.create(AFFakturaPrijata)`.
 
 ### Import a inicializace knihovny
 
-```typescript 
-import { AFApiClient } from 'abra-flexi'
+```typescript
+import { AFApiClient, AFApiConfig } from 'abra-flexi'
 
 const apiOpts: AFApiConfig = {
   url: '<doplnte_server>',
-  company: '<doplnte_spolecnost>
+  company: '<doplnte_spolecnost>'
 }
 
 const api = new AFApiClient(apiOpts)
 ```
 
+### Logování
+
+Ve výchozím stavu je klient tichý (nevypisuje nic). Logování lze zapnout pomocí `logLevel`:
+
+```typescript
+const api = new AFApiClient({
+  url: '<server>',
+  company: '<spolecnost>',
+  logLevel: 'debug'   // 'none' | 'error' | 'warn' | 'info' | 'debug'
+})
+```
+
+Je možné také předat vlastní logger (např. Winston), který musí implementovat rozhraní `{ debug, info, warn, error }`:
+
+```typescript
+import winston from 'winston'
+
+const api = new AFApiClient({
+  url: '<server>',
+  company: '<spolecnost>',
+  logger: winston.createLogger({ ... }),
+  logLevel: 'info'   // pokud neuvedete, přeposílají se všechny úrovně
+})
+```
+
 ### Dotazování instancí
 
-Pro dotazování instancí jsou k dispozici metody `query` (vrací kolekci instancí evidenčních tříd) a `queryOne` (vrací jedu instanci). 
+Pro dotazování instancí jsou k dispozici metody `query` (vrací kolekci instancí evidenčních tříd) a `queryOne` (vrací jedu instanci).
 
 Parametrech dotazu může být uveden požadovaný detail. Detail se zapisuje formou pole vlastností evidencí formou textových řetězců. Detaily relací je možné vkládat pomocí pole o 2 prvcích, kde prvním je název vlastnosti relace v evidenci a druhým opět pole vlastností v napojené evidenci. Jasněji je to patrné z příkladu níže.
 
 Pozor! Vnořené M:N či 1:N relací knihovna zatím podporuje pouze na základní úrovni. Například detail `faktura-vydana-polozka.cenik.atributy.typAtributu` se načte pouze po instanci ceníku. Bude řešeno v dalších verzích.
 
-Filtrování je možné vkládat pomocí metod `Filter(expr, params)`, `ID(id)` nebo `CODE(code)`. Metoda `Filter` akceptuje textovou šablonu (`expr`), ve které budou všechny návěstí nahrazeny hodnotami předanými ve druhém argumentu (`params`). Návěstí mohou být:
+Filtrování je možné vkládat pomocí metod `Filter(expr, params)`, `ID(id)`, `CODE(code)` nebo `EXT(ext)`. Metoda `Filter` akceptuje textovou šablonu (`expr`), ve které budou všechny návěstí nahrazeny hodnotami předanými ve druhém argumentu (`params`). Návěstí mohou být:
 - `:key` se nahradí textovou hodnotou klíče `key` ve druhém argumentu,
 - `::mujKod` se nahradí textovou hodnotou klíče `mujKod` ve druhém argumentu a prefixuje se předponou `code:`,
 
-Obě návěští podporují kolekce. Návěstí se pak nahradí výsledkem `kolekce.join(',')`. Pokud je hodnotou instance evidence (podtřída AFEntity), ignoruje se typ návěští a použije se číselné id resp. kód, není-li číselné id vyplněno/načteno. 
+Obě návěští podporují kolekce. Návěstí se pak nahradí výsledkem `kolekce.join(',')`. Pokud je hodnotou instance evidence (podtřída AFEntity), ignoruje se typ návěští a použije se číselné id resp. kód, není-li číselné id vyplněno/načteno.
 
 Metoda `Filter` vrací objekt s mající následující metody:
 - `use(filter, op)` - přidá jiný objekt filtru do stávajícího. Atribut `op` určuje operátor pro spojení se stávajícím filtrem (`and` nebo `or`, defaultní je `or`). Filtr je vložen v závorkách.
@@ -106,19 +115,17 @@ Metoda `Filter` vrací objekt s mající následující metody:
 
 Všechny metody vrací vždy novou instanci filtru. Filtry si tedy můžete předpřipravit a následně spojivat pomocí `use()`/`useNot()`.
 
-```typescript 
+```typescript
 import { AFInterniDoklad, Filter } from 'abra-flexi'
 
 const queryOpts: AFQueryOptions = {
   detail: ['id', 'kod', 'typDokl', ['uzivatelske-vazby', ['id', 'evidenceType', 'objectId', 'vazbaTyp']]],
   filter: Filter(`typDokl = '::td'`, { td: 'MUJ_TYP_DOKLADU'})
-} 
-
-const query = api.query(AFInterniDoklad, queryOpts)
+}
 
 const run = async () => {
   try {
-    const data = await query
+    const data = await api.query(AFInterniDoklad, queryOpts)
     console.log(data)
   } catch (e) {
     console.error(e)
@@ -128,22 +135,49 @@ run()
 
 ```
 
+### Stránkování a celkový počet záznamů
+
+Dotazy podporují parametry `limit` a `start` pro stránkování. Pro zjištění celkového počtu záznamů (nezávislého na velikosti stránky) předejte `addRowCount: true`. Výsledek metody `query()` je standardní pole, ale navíc obsahuje vlastnost `totalCount` s celkovým počtem nalezených záznamů na serveru.
+
+```typescript
+const PAGE_SIZE = 50
+
+const firstPage = await api.query(AFAdresar, {
+  detail: ['id', 'kod', 'nazev'],
+  limit: PAGE_SIZE,
+  start: 0,
+  addRowCount: true   // vyžádá @rowCount od serveru
+})
+
+console.log(firstPage.totalCount)  // např. 1234 — celkový počet, bez ohledu na limit
+console.log(firstPage.length)      // 50 — velikost stránky
+
+const totalPages = Math.ceil(firstPage.totalCount! / PAGE_SIZE)
+
+// Další stránky — addRowCount není třeba opakovat (zvyšuje zátěž serveru)
+const secondPage = await api.query(AFAdresar, {
+  detail: ['id', 'kod', 'nazev'],
+  limit: PAGE_SIZE,
+  start: PAGE_SIZE
+})
+```
+
+> **Poznámka:** `addRowCount: true` způsobí extra COUNT dotaz na straně serveru. Používejte ho pouze pro první stránku a hodnotu `totalCount` si uložte pro výpočet dalších stránek.
+
 ### Načtení většího detailu
 
 Pro načtení většího detailu či aktualizaci dříve načtených instancí můžete použít metody `populate` a `populateOne`. Detailem požadované vlastnosti se aktualizují na původní instanci.
 
-```typescript 
+```typescript
 const loadedEntity // Zde máme uloženou dříve načtenou instanci entity AFInterniDoklad
 
 const options = {
   detail: AFQueryDetail.FULL
 }
 
-const populate = api.populateOne(loadEntity)
-
 const run = async () => {
   try {
-    const populatedEntity = await populate
+    const populatedEntity = await api.populateOne(loadedEntity, options)
     console.log(populatedEntity)
     console.log(populatedEntity === loadedEntity) // Vypíše true
   } catch (e) {
@@ -156,20 +190,18 @@ run()
 
 ### Načtení instancí z uživatelských vazeb
 
-Instance entit odkazované pomocí uživatelských vazeb je možné načíst metodou `queryURel`. Metodě je třeba zaslat zdrojovou kolekci instancí. Instance neumsí být stejného typu (evidence), ale musí mít klíč `uzivatelske-vazby`. Metoda načítá vazby na kokrétní evidenci (vazby ostatních typů jsou vynechány). Vazby je možné filtrovat dle typu `typVazby`. Načtená data jsou přidána do vazeb zrojových instancí (vlastnost `object`). Data jsou dále vrácena jako kolekce párů `{ entity: zdrojova_entity, referencedFrom: načtená_entita }`.
+Instance entit odkazované pomocí uživatelských vazeb je možné načíst metodou `queryURels`. Metodě je třeba zaslat zdrojovou kolekci instancí. Instance neumsí být stejného typu (evidence), ale musí mít klíč `uzivatelske-vazby`. Metoda načítá vazby na kokrétní evidenci (vazby ostatních typů jsou vynechány). Vazby je možné filtrovat dle typu `typVazby`. Načtená data jsou přidána do vazeb zrojových instancí (vlastnost `object`). Data jsou dále vrácena jako kolekce párů `{ entity: zdrojova_entity, referencedFrom: načtená_entita }`.
 
-Načteny jsou pouze instance vazeb, které se již vyskytují ve zdrojové kolekci! Metoda `queryURel` tedy sama uživatelské vazby na jednotlivých zdrojových instancích nenačítá. Načítá pouze instance, na které vazba odkazuje.
+Načteny jsou pouze instance vazeb, které se již vyskytují ve zdrojové kolekci! Metoda `queryURels` tedy sama uživatelské vazby na jednotlivých zdrojových instancích nenačítá. Načítá pouze instance, na které vazba odkazuje.
 
-```typescript 
+```typescript
 const soureEntities // Zde máme kolekci entit, pro které načítáme instance odkazované uživatelskou vazbou
 
-const query = api.queryURels(AFInterniDoklad, soureEntities, {
-  detail: ['id', 'kod', 'typDokl']
-})
-
 const run = async () => {
   try {
-    const pairs = await query
+    const pairs = await api.queryURels(AFInterniDoklad, soureEntities, {
+      detail: ['id', 'kod', 'typDokl']
+    })
     console.log(pairs)
   } catch (e) {
     console.error(e)
@@ -181,21 +213,136 @@ run()
 
 ### Práce se štítky
 
-*TODO: Přidat popis*
+Štítky (stitky) jsou na každé instanci dostupné jako textový řetězec ve vlastnosti `stitky`. Pro pohodlnější práci jsou k dispozici metody `getStitky()` a `getStitkyBySkupina(skup)`, které vrací pole instancí `AFStitek`.
+
+Knihovna udržuje interní cache štítků, která se průběžně aktualizuje. Strategii cache lze nastavit v konfiguraci klienta pomocí `stitkyCacheStrategy` (`None`, `Lazy` (výchozí), `Eager`).
 
 ### Vytváření, změna a odstraňování instancí
 
-*TODO: Přidat popis*
+#### Vytvoření nové instance
+
+Novou instanci evidence vytvoříte pomocí `api.create()`. **Nepoužívejte `new` přímo** — konstruktor vyžaduje interní závislosti, které správně injektuje pouze klient.
+
+```typescript
+import { AFFakturaVydana } from 'abra-flexi'
+
+const faktura = await api.create(AFFakturaVydana)
+faktura.popis = 'Testovací faktura'
+// ... nastavte další vlastnosti
+
+const saved = await api.save(faktura)
+console.log(saved.id)  // ID přidělené serverem je automaticky přiřazeno zpět na instanci
+```
+
+#### Odkaz na existující záznam bez načítání
+
+Pokud potřebujete odkázat na existující záznam (např. jako relaci na jiné entitě), ale nechcete ho načítat, použijte `createIdStub()`:
+
+```typescript
+const firma = await api.createIdStub(AFAdresar, { id: 123 })
+// nebo podle kódu:
+const firma = await api.createIdStub(AFAdresar, { kod: 'MOJE_FIRMA' })
+```
+
+Instance vytvořená přes `createIdStub()` je správně označena jako existující (`isNew === false`) a lze ji použít v relacích jiných entit.
+
+#### Uložení změn
+
+Metoda `save()` uloží jak novou instanci (POST/PUT), tak změny na existující. Na server se odesílají pouze změněné vlastnosti.
+
+```typescript
+const faktura = await api.queryOne(AFFakturaVydana, { filter: ID(42) })
+faktura.popis = 'Aktualizovaný popis'
+await api.save(faktura)
+```
+
+**Poznámka k uživatelským vazbám:** ABRA Flexi nepodporuje vytvoření nové entity společně s uživatelskými vazbami v jednom požadavku. Pokud entita obsahuje `uzivatelske-vazby`, je třeba ji nejdříve uložit bez vazeb a vazby přidat v samostatném volání `save()`.
+
+#### Smazání instance
+
+```typescript
+await api.delete(faktura)
+```
+
+Metoda funguje pro všechny typy evidencí, včetně `AFUzivatelskaVazba` (kde ABRA API nevystavuje standardní DELETE endpoint — knihovna to řeší automaticky).
+
+### Stahování souborů
+
+Metoda `queryFile()` slouží ke stažení dat v jiném formátu než JSON — například PDF, XML, CSV nebo ISDOC. Vrací objekt `{ blob, contentType, filename }`.
+
+```typescript
+import { AFFakturaVydana, ID } from 'abra-flexi'
+import fs from 'fs'
+
+// PDF faktury
+const pdf = await api.queryFile(AFFakturaVydana, 'pdf', { filter: ID(42) })
+fs.writeFileSync(pdf.filename ?? 'faktura.pdf', Buffer.from(await pdf.blob.arrayBuffer()))
+
+// XML
+const xml = await api.queryFile(AFFakturaVydana, 'xml', { filter: ID(42) })
+
+// CSV kolekce
+const csv = await api.queryFile(AFAdresar, 'csv', { limit: 100 })
+
+// ISDOC / ISDOCX a další rozšíření
+const isdocx = await api.queryFile(AFFakturaVydana, 'isdocx', { filter: ID(42) })
+```
+
+#### Tisk pomocí pojmenované sestavy
+
+Parametry `reportName` a `reportLang` umožňují zvolit konkrétní tiskovou sestavu:
+
+```typescript
+const pdf = await api.queryFile(AFFakturaVydana, 'pdf', {
+  filter: ID(42),
+  reportName: 'faktura-dph',
+  reportLang: 'cs'
+})
+```
+
+#### Seznam dostupných sestav
+
+Sestavy dostupné pro danou evidenci lze získat metodou `queryReports()`. Vrací pole `AFReportInfo` — každá obsahuje mimo jiné unikátní `reportId` (to je hodnota posílaná do `reportName`) a seznam podporovaných jazyků (`languages.language[]`).
+
+Objekt `AFReportInfo` (resp. `AFReportLanguage` z jeho `languages.language`) lze předat přímo do `reportName` / `reportLang` v `queryFile()` — knihovna z něj vytáhne správné hodnoty:
+
+```typescript
+const reports = await api.queryReports(AFFakturaVydana)
+const reportDef = reports.find(r => r.isDefault === 'true') ?? reports[0]
+
+const pdf = await api.queryFile(AFFakturaVydana, 'pdf', {
+  filter: ID(42),
+  reportName: reportDef, // → reportId
+  reportLang: reportDef.languages?.language.find(l => l.code === 'en') ?? 'cs'
+})
+```
+
+### Akce na instancích
+
+Pojmenované akce definované v ABRA Flexi (např. storno, uhrazení zápočtem) lze volat metodou `action()`. Instance musí být uložená (mít přidělené `id`) nebo v rozpoznatelném stavu — pokud má pouze `kod` / `ext`, klient si nejdříve dohledá `id`.
+
+Pro každou evidenci s reálnými business akcemi generátor vyrobí samostatný TypeScript enum (např. `AFFakturaPrijataAction`). CRUD pseudo-akce (`new`/`edit`/`delete`/`copy`) jsou vynechány — používají se přes dedikované metody `create()`, `save()` a `delete()`. Akce se validují podle metadat dané evidence; volání nepodporované akce skončí chybou ještě před jakýmkoli HTTP požadavkem.
+
+```typescript
+import { AFFakturaPrijata, AFFakturaPrijataAction } from 'abra-flexi'
+
+const faktura = await api.resolveStubId(AFFakturaPrijata, 2452)
+await api.action(faktura, AFFakturaPrijataAction.Storno)
+// nebo s textovou hodnotou:
+await api.action(faktura, 'uhrad-zapoctem')
+```
 
 ## Task list pro vydání stabilní verze
 
 - [X] Generování evidenčních tříd dle metadat REST API
 - [X] Načítání kolekcí a jednotlivých instancí z REST API
-- [X] Načítání užviatelských relací 
+- [X] Načítání užviatelských relací
 - [X] Refersh již načtených dat
 - [X] Pohodlná práce se štítky
+- [X] Vytváření, mazání a změna záznamů v REST API
+- [X] Stahování souborů (PDF, CSV, XML, ISDOC, ...)
+- [X] Akce na instancích
 - [ ] Jednotný handling identifikátorů záznamů
-- [x] Vytváření, mazání a změna záznamů v REST API
 - [ ] Lokální keš a společné instance pro jedno ID
 - [ ] Battle tested - reálné nasazení, úprava rozhraní dle reálného použití
 - [ ] Verzování, npm balíčkování
@@ -204,8 +351,8 @@ run()
 
 # English
 
-[ABRA Flexi]([https://www.abra.eu/flexi/](https://www.abra.eu/en/flexi/) is Czech ERP for small businesses, developer by [ABRA Software](https://www.abra.eu/en). To access data in ABRA Flexi there is a REST API with public documentation. 
+[ABRA Flexi](https://www.abra.eu/en/flexi/) is Czech ERP for small businesses, developed by [ABRA Software](https://www.abra.eu/en). To access data in ABRA Flexi there is a REST API with public documentation.
 
-ABRA Flexi Typescript client (AFTC) is library to call ABRA Fflexi REST API. It's for browsers and server environments (Node.js). It provides methods for CRUD. 
+ABRA Flexi Typescript client (AFTC) is library to call ABRA Flexi REST API. It's for browsers and server environments (Node.js). It provides methods for CRUD.
 
-Because ABRA Flexi is Czech software, it's expected to have mainly Czech developer audience. English version of the documentation will be finalized when the library API becomes stable. 
+Because ABRA Flexi is Czech software, it's expected to have mainly Czech developer audience. English version of the documentation will be finalized when the library API becomes stable.