abra-flexi 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Tomas Kavan
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,193 @@
+# 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 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.
+
+**Knihovna je v rané fázi vývoje a její rozhraní zatím není stabilní**.
+
+## Instalace
+
+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
+
+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
+chmod a+x ./bin/index.js
+```
+
+a následně lze generování spustit například takto:
+```
+./bin/index.js -s https://muj-flexi-server.cz/c/moje-spolecnost/ -u uzivatel1 -p hesloUzivatele -c -e adresar -e faktura-prijata -e polozka-faktury-prijate
+```
+
+knihovnu s vygenerovanými třídami lze přeložit
+```
+npm run build:cli
+```
+
+### Příklady
+
+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říkaldy je možné spustit pomocí nástroje `ts-node`:
+```
+ts-node examples/loadEntityCli.ts -h #vypíše nápovědu k příkazu
+ts-node examples/loadEntity.ts -s https://muj.server.cz -c moje-firma -u uzivatel1 -h heslo1
+```
+
+## Použití
+
+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()`.
+
+### Import a inicializace knihovny
+
+```typescript 
+import { AFApiClient } from 'aftc'
+
+const apiOpts: AFApiConfig = {
+  url: '<doplnte_server>',
+  company: '<doplnte_spolecnost>
+}
+
+const api = new AFApiClient(apiOpts)
+```
+
+### 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). 
+
+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.
+
+Filtrování je možné vkládat pomocí metod `Filter`, `ID` nebo `CODE`. Metoda `Filter` akceptuje textovou šablonu, ve které budou všechny návěstí nahrazeny hodnotami předanými ve druhém argumentu. 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:`,
+- `:...kolekce` očekává, že klíč `kolekce` bude typu `Array`. Návěstí se nahradí výsledkem `kolekce.join(',')`. 
+
+```typescript 
+import { AFInterniDoklad, Filter } from 'aftc'
+
+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
+    console.log(data)
+  } catch (e) {
+    console.error(e)
+  }
+}
+run()
+
+```
+
+### 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 
+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
+    console.log(populatedEntity)
+    console.log(populatedEntity === loadedEntity) // Vypíše true
+  } catch (e) {
+    console.error(e)
+  }
+}
+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 }`.
+
+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.
+
+```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
+    console.log(pairs)
+  } catch (e) {
+    console.error(e)
+  }
+}
+run()
+
+```
+
+### Vytváření, změna a odstraňování instancí
+
+*TODO: Zatím neimplementováno*
+
+## 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] Refersh již načtených dat
+- [ ] Pohodlná práce se štítky
+- [ ] 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í
+- [ ] Kontrola kompatibility při připojování k REST API
+- [ ] English documentation
+
+# 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 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. 
+
+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. 

package/abra/AFApiClient.d.ts

@@ -0,0 +1,20 @@
+import { AFEntity } from "./AFEntity";
+import { AFApiConfig, AFQueryOptions, AFURelOptions, AFURelResult, AFPopulateOptions, AFURelMinimal, StitkyCacheStrategy } from "./AFTypes";
+export declare class AFApiClient {
+    private _url;
+    private _fetch;
+    private _company;
+    private _stitkyCache;
+    constructor(config: AFApiConfig);
+    get url(): string;
+    get company(): string;
+    get stitkyCacheStrategy(): StitkyCacheStrategy;
+    queryRaw<T extends typeof AFEntity>(entityPath: string, options: AFQueryOptions): Promise<any>;
+    query<T extends typeof AFEntity>(entity: T, options: AFQueryOptions): Promise<InstanceType<T>[]>;
+    queryOne<T extends typeof AFEntity>(entity: T, options: AFQueryOptions): Promise<InstanceType<T>>;
+    queryURels<T extends typeof AFEntity = typeof AFEntity>(relatedEntity: T, forObjects: AFURelMinimal | AFURelMinimal[], options?: AFURelOptions): Promise<AFURelResult<InstanceType<T>>[]>;
+    populate<T extends typeof AFEntity = typeof AFEntity>(entities: InstanceType<T>[], options: AFPopulateOptions): Promise<InstanceType<T>[]>;
+    populateOne<T extends typeof AFEntity = typeof AFEntity>(entity: InstanceType<T>, options: AFPopulateOptions): Promise<InstanceType<T>>;
+    private _processEntityObj;
+    private _setProperty;
+}

package/abra/AFApiClient.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFApiClient = void 0;
+const AFDataType_1 = require("./AFDataType");
+const AFError_1 = require("./AFError");
+const AFFilter_1 = require("./AFFilter");
+const AFTypes_1 = require("./AFTypes");
+const AFEntityRegistry_1 = require("../generated/AFEntityRegistry");
+const urlHelper_1 = require("../helpers/urlHelper");
+const AFApiUrlHelper_1 = require("./AFApiUrlHelper");
+const AFStitkyCache_1 = require("./AFStitkyCache");
+const ABRA_API_FORMAT = 'json';
+class AFApiClient {
+    _url;
+    _fetch;
+    _company;
+    _stitkyCache;
+    constructor(config) {
+        this._url = config.url;
+        this._company = config.company;
+        this._fetch = config.fetch || fetch;
+        this._stitkyCache = new AFStitkyCache_1.AFStitkyCache(this, config.stitkyCacheStrategy);
+    }
+    get url() { return this._url; }
+    get company() { return this._company; }
+    get stitkyCacheStrategy() { return this._stitkyCache.strategy; }
+    async queryRaw(entityPath, options) {
+        if (!this.company || !this.company.length) {
+            throw new AFError_1.AFError(AFError_1.AFErrorCode.MISSING_ABRA_COMPANY, `Can't query AFApiClient without providing company path component first.`);
+        }
+        const detail = options.detail || AFTypes_1.AFQueryDetail.SUMMARY;
+        let url = this._url + '/c/' + this.company + '/' + entityPath;
+        url += options.filter ? options.filter.toUrlComponent() : '';
+        url += '.' + ABRA_API_FORMAT;
+        url = (0, urlHelper_1.addParamToUrl)(url, 'detail', (0, AFApiUrlHelper_1.composeDetail)(detail));
+        url = (0, urlHelper_1.addParamToUrl)(url, 'includes', (0, AFApiUrlHelper_1.composeIncludes)(detail, entityPath));
+        url = (0, urlHelper_1.addParamToUrl)(url, 'relations', (0, AFApiUrlHelper_1.composeRelations)(detail));
+        url = (0, urlHelper_1.addParamToUrl)(url, 'limit', options.limit);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'start', options.start);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'addRowCount', options.addRowCount);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'onlyExtIds', options.onlyExtIds);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'noExtIds', options.noExtIds);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'noIds', options.noIds);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'codeAsId', options.codeAsId);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'dryRun', options.dryRun);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'noSimpleMode', options.noSimpleMode);
+        url = (0, urlHelper_1.addParamToUrl)(url, 'noValidityCheck', options.noValidityCheck);
+        // TODO - remove
+        console.log(url);
+        try {
+            const raw = await this._fetch(url, { signal: options.abortController?.signal });
+            if (raw.status >= 400 && raw.status < 600) {
+                throw new AFError_1.AFError(AFError_1.AFErrorCode.ABRA_FLEXI_ERROR, `${raw.status} ${raw.statusText}`);
+            }
+            const json = await raw.json();
+            let entityObj = json.winstrom[entityPath];
+            return entityObj;
+        }
+        catch (e) {
+            if (!(e instanceof AFError_1.AFError)) {
+                console.log(e);
+                e = new AFError_1.AFError(AFError_1.AFErrorCode.UNKNOWN, e.toString());
+            }
+            throw e;
+        }
+    }
+    async query(entity, options) {
+        const res = this.queryRaw(entity.EntityPath, options);
+        try {
+            const rawData = await res;
+            const data = this._processEntityObj(entity, rawData);
+            if (!options.noUpdateStitkyCache) {
+                await this._stitkyCache.fetchTick();
+            }
+            return data;
+        }
+        catch (e) {
+            if (!(e instanceof AFError_1.AFError)) {
+                console.log(e);
+                e = new AFError_1.AFError(AFError_1.AFErrorCode.UNKNOWN, e.toString());
+            }
+            throw e;
+        }
+    }
+    async queryOne(entity, options) {
+        const data = await this.query(entity, options);
+        if (!data || !data.length)
+            throw new AFError_1.AFError(AFError_1.AFErrorCode.OBJECT_NOT_FOUND, `${entity} object not found. Query filter: ${options.filter}`);
+        return data[0];
+    }
+    async queryURels(relatedEntity, forObjects, options = {}) {
+        if (!(forObjects instanceof Array)) {
+            forObjects = [forObjects];
+        }
+        if (options.vazbaTyp === 'string') {
+            options.vazbaTyp = [options.vazbaTyp];
+        }
+        const out = [];
+        const fetchedList = [];
+        for (const uobj of forObjects) {
+            const uvs = uobj["uzivatelske-vazby"];
+            if (!uvs)
+                continue;
+            for (const uv of uvs) {
+                // Check if vazba is properly defined and if it has proper vazbaTyp (if required)
+                if (!uv.evidenceType || !uv.objectId)
+                    continue;
+                if (options.vazbaTyp &&
+                    (!uv.vazbaTyp ||
+                        typeof uv.vazbaTyp.kod !== 'string' ||
+                        !options.vazbaTyp.includes(uv.vazbaTyp.kod)))
+                    continue;
+                // Check if related evidence type matches the requested type
+                const cls = (0, AFEntityRegistry_1.EntityByPath)(uv.evidenceType);
+                if (cls !== relatedEntity)
+                    continue;
+                // Get (or create) list of already fetched objects by evidenceType
+                let list = fetchedList.find(fli => fli[0] === uv.evidenceType);
+                if (!list) {
+                    list = [uv.evidenceType, []];
+                    fetchedList.push(list);
+                }
+                // Load data from cache or fetch it if missing
+                let data = list[1].find(li => li.id === uv.objectId);
+                if (!data) {
+                    try {
+                        const opts = {
+                            detail: options.detail,
+                            filter: (0, AFFilter_1.ID)(uv.objectId),
+                            abort: options.abortController,
+                            noUpdateStitkyCache: true
+                        };
+                        let outInner = await this.query(relatedEntity, opts);
+                        if (!outInner || !outInner.length)
+                            continue;
+                        list[1].push(outInner[0]);
+                        data = outInner[0];
+                        const res = {
+                            entity: uobj,
+                            referencedFrom: outInner[0]
+                        };
+                        out.push(res);
+                    }
+                    catch (e) {
+                        if (!(e instanceof AFError_1.AFError)) {
+                            console.log(e);
+                            e = new AFError_1.AFError(AFError_1.AFErrorCode.UNKNOWN, e.toString());
+                        }
+                        throw e;
+                    }
+                }
+                uv.object = data;
+            }
+        }
+        if (!options.noUpdateStitkyCache) {
+            await this._stitkyCache.fetchTick();
+        }
+        return out;
+    }
+    async populate(entities, options) {
+        const fetchBy = [];
+        for (const en of entities) {
+            if (typeof en.id !== 'undefined') {
+                fetchBy.push(['id', en.id.toString()]);
+                continue;
+            }
+            if (typeof en.kod !== 'undefined') {
+                fetchBy.push(['kod', en.kod || '']);
+                continue;
+            }
+            throw new AFError_1.AFError(AFError_1.AFErrorCode.MISSING_ID_IN_POPULATE, `Can't populate entity withoud id or kod set. It's not possible to fetch data. Entity: ${en}`);
+        }
+        // Nothing was requested to populate
+        if (!fetchBy.length)
+            return [];
+        let tplArr = fetchBy.map(entry => `${entry[0]} = '${entry[1]}'`);
+        if (!options.detail)
+            options.detail = [];
+        if (options.detail instanceof Array) {
+            if (!options.detail.includes('id'))
+                options.detail.push('id');
+            if (!options.detail.includes('kod'))
+                options.detail.push('kod');
+        }
+        const opts = {
+            filter: (0, AFFilter_1.Filter)(tplArr.join(' or ')),
+            detail: options.detail,
+            abortController: options.abortController
+        };
+        try {
+            const cls = (0, AFEntityRegistry_1.EntityByName)(entities[0].constructor.name);
+            const resQRaw = this.queryRaw(cls.EntityPath, opts);
+            let dataQ = await resQRaw;
+            if (!dataQ)
+                throw new AFError_1.AFError(AFError_1.AFErrorCode.UNKNOWN, 'Unable to fetch data to populate');
+            if (!(dataQ instanceof Array))
+                dataQ = [dataQ];
+            for (const enQ of dataQ) {
+                const en = entities.find(e => {
+                    if (typeof e.id !== 'undefined')
+                        return enQ.id === String(e.id);
+                    if (typeof e.kod !== 'undefined')
+                        return enQ.kod === String(e.kod);
+                    return false;
+                });
+                if (!en)
+                    continue;
+                const oKeys = Object.keys(enQ);
+                for (const okey of oKeys) {
+                    this._setProperty(en, okey, enQ);
+                }
+            }
+            if (!options.noUpdateStitkyCache) {
+                await this._stitkyCache.fetchTick();
+            }
+        }
+        catch (e) {
+            if (!(e instanceof AFError_1.AFError)) {
+                console.log(e);
+                e = new AFError_1.AFError(AFError_1.AFErrorCode.UNKNOWN, e.toString());
+            }
+            throw e;
+        }
+        return entities;
+    }
+    async populateOne(entity, options) {
+        const res = await this.populate([entity], options);
+        if (!res || !res.length)
+            throw new AFError_1.AFError(AFError_1.AFErrorCode.OBJECT_NOT_FOUND, `${entity} object not found. Kod / ID: ${entity.kod} / ${entity.id}`);
+        return res[0];
+    }
+    _processEntityObj(entity, obj) {
+        if (!obj)
+            return [];
+        // If there is no detail, prepare stub with code (kod)
+        if (typeof obj === 'string') {
+            if (obj.slice(0, 5) === 'code:') {
+                obj = {
+                    kod: obj.slice(5)
+                };
+            }
+        }
+        if (!(obj instanceof Array)) {
+            obj = [obj];
+        }
+        const res = [];
+        for (const o of obj) {
+            const ent = new entity(this._stitkyCache);
+            const oKeys = Object.keys(o);
+            for (const okey of oKeys) {
+                this._setProperty(ent, okey, o);
+            }
+            res.push(ent);
+        }
+        return res;
+    }
+    _setProperty(entity, key, obj) {
+        const annot = entity.getPropertyTypeAnnotation(key);
+        if (!annot)
+            return;
+        const v = obj[key];
+        if (!v)
+            return;
+        // If it's relation, recursively call _processEntityObj
+        if (annot.type === AFTypes_1.PropertyType.Relation) {
+            if (!annot.afClass)
+                return;
+            const cls = typeof annot.afClass === 'string' ? (0, AFEntityRegistry_1.EntityByName)(annot.afClass) : annot.afClass;
+            const propOut = this._processEntityObj(cls, v);
+            if (!propOut)
+                return;
+            if (annot.isArray) {
+                entity[key] = propOut;
+                return;
+            }
+            if (propOut.length) {
+                entity[key] = propOut[0];
+            }
+            return;
+        }
+        // Else set it as scalar type
+        //console.log(obj)
+        if (!obj)
+            return;
+        entity[annot.key] = (0, AFDataType_1.parsePropertyValue)(annot.type, annot, obj[annot.key]);
+    }
+}
+exports.AFApiClient = AFApiClient;

package/abra/AFApiUrlHelper.d.ts

@@ -0,0 +1,4 @@
+import { AFQueryDetail, NestedDetail } from "./AFTypes";
+export declare function composeDetail(level: NestedDetail | AFQueryDetail): string | null;
+export declare function composeIncludes(level: NestedDetail | AFQueryDetail, entityPath: string): string | null;
+export declare function composeRelations(level: NestedDetail | AFQueryDetail): string | null;

package/abra/AFApiUrlHelper.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeRelations = exports.composeIncludes = exports.composeDetail = void 0;
+const AFEntityRegistry_1 = require("../generated/AFEntityRegistry");
+const AFEntity_1 = require("./AFEntity");
+const AFError_1 = require("./AFError");
+const AFTypes_1 = require("./AFTypes");
+function composeDetail(level) {
+    if (level === AFTypes_1.AFQueryDetail.FULL)
+        return 'full';
+    if (level === AFTypes_1.AFQueryDetail.ID)
+        return 'id';
+    if (level === AFTypes_1.AFQueryDetail.SUMMARY)
+        return null;
+    const levProc = (inp) => {
+        let out = '';
+        for (const ndi of inp) {
+            if (out.length)
+                out += ',';
+            if (typeof ndi === 'string') {
+                out += ndi;
+            }
+            else if (ndi instanceof Array) {
+                out += ndi[0] + '(' + levProc(ndi[1]) + ')';
+            }
+        }
+        return out;
+    };
+    const out = 'custom:' + levProc(level);
+    return out;
+}
+exports.composeDetail = composeDetail;
+function composeIncludes(level, entityPath) {
+    if (level === AFTypes_1.AFQueryDetail.FULL)
+        return null;
+    if (level === AFTypes_1.AFQueryDetail.ID)
+        return null;
+    if (level === AFTypes_1.AFQueryDetail.SUMMARY)
+        return null;
+    const includes = [];
+    const cls = (0, AFEntityRegistry_1.EntityByPath)(entityPath);
+    const levProc = (inp, base, entity) => {
+        for (const ndi of inp) {
+            if (typeof ndi === 'string')
+                continue;
+            if (ndi instanceof Array) {
+                const key = ndi[0];
+                const list = ndi[1];
+                const annot = (0, AFEntity_1.GetPropertyTypeAnnotation)(entity, key);
+                if (!annot || !annot.afClass)
+                    throw new AFError_1.AFError(AFError_1.AFErrorCode.QUERY_DETAIL_UNKNOWN_KEY, `[AFError].QUERY_DETAIL_UNKNOWN_KEY: Requested unknown key ${key} on entity ${(typeof entity)}. Or it has't type annotation set.`);
+                const relEnt = (0, AFEntityRegistry_1.EntityByName)(annot.afClass);
+                const thisIncl = base + '/' + key + '/' + relEnt.EntityPath;
+                includes.push(thisIncl);
+                levProc(list, thisIncl, relEnt);
+            }
+        }
+    };
+    levProc(level, cls.EntityPath, cls);
+    return includes.join(',');
+}
+exports.composeIncludes = composeIncludes;
+function composeRelations(level) {
+    if (level === AFTypes_1.AFQueryDetail.FULL)
+        return null;
+    if (level === AFTypes_1.AFQueryDetail.ID)
+        return null;
+    if (level === AFTypes_1.AFQueryDetail.SUMMARY)
+        return null;
+    const relations = [];
+    const levProc = (inp) => {
+        for (const ndi of inp) {
+            if (typeof ndi === 'string')
+                continue;
+            const key = ndi[0];
+            const list = ndi[1];
+            if (!relations.includes(key))
+                relations.push(key);
+            levProc(list);
+        }
+    };
+    levProc(level);
+    return relations.length ? relations.join(',') : null;
+}
+exports.composeRelations = composeRelations;

package/abra/AFDataType.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { Big } from 'big.js';
+import { PropertyType, TypeAnnotation } from './AFTypes';
+type PropertyTypeMap = {
+    [PropertyType.Integer]: number;
+    [PropertyType.String]: string;
+    [PropertyType.Select]: string;
+    [PropertyType.DateTime]: Date;
+    [PropertyType.Date]: Date;
+    [PropertyType.Numeric]: Big;
+    [PropertyType.Logic]: boolean;
+    [PropertyType.Blob]: Buffer;
+    [PropertyType.Array]: any[];
+};
+type ParsedType<T extends PropertyType> = T extends keyof PropertyTypeMap ? PropertyTypeMap[T] : never;
+export declare function parsePropertyValue<T extends PropertyType>(propertyType: T, annot: TypeAnnotation, obj: any): ParsedType<T> | undefined;
+export declare function serializePropertyValue<T extends PropertyType>(propertyType: T, annotation: TypeAnnotation, property: any): string;
+export {};

package/abra/AFDataType.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializePropertyValue = exports.parsePropertyValue = void 0;
+const big_js_1 = require("big.js");
+const AFTypes_1 = require("./AFTypes");
+function parsePropertyValue(propertyType, annot, obj) {
+    if (obj === null || obj === undefined)
+        return undefined;
+    switch (propertyType) {
+        case AFTypes_1.PropertyType.Integer:
+            return parseInt(obj, 10);
+        case AFTypes_1.PropertyType.String:
+            return (annot?.maxLength ? obj.slice(0, annot.maxLength) : obj);
+        case AFTypes_1.PropertyType.Select:
+            if (!annot?.enum)
+                throw new Error(`Enum typeAnnotation is required for Select (property ${annot.key})`);
+            return (annot.enum[obj] ?? obj);
+        case AFTypes_1.PropertyType.DateTime:
+            return new Date(obj);
+        case AFTypes_1.PropertyType.Date:
+            const split = obj.split('+');
+            const dateStr = split[0] + 'T00:00:00.000+' + split[1];
+            return new Date(dateStr);
+        case AFTypes_1.PropertyType.Numeric:
+            return new big_js_1.Big(obj).round(annot?.decimals ?? 2);
+        case AFTypes_1.PropertyType.Logic:
+            return (obj.toLowerCase() === "true");
+        case AFTypes_1.PropertyType.Blob:
+            return Buffer.from(obj, "base64");
+        case AFTypes_1.PropertyType.Array:
+            if (!annot?.itemType)
+                throw new Error("itemType is required for Array");
+            const myAnnot = { ...annot };
+            myAnnot.type = annot.itemType;
+            return (Array.isArray(obj)
+                ? obj.map((item) => parsePropertyValue(annot.itemType, myAnnot, item))
+                : []);
+        default:
+            throw new Error(`Unknown PropertyType: ${propertyType} of property ${annot.key}`);
+    }
+}
+exports.parsePropertyValue = parsePropertyValue;
+function serializePropertyValue(propertyType, annotation, property) {
+    throw new Error('TODO: serializePropertyValue not implemented yet');
+}
+exports.serializePropertyValue = serializePropertyValue;