@innobrain/onoffice-adapter-js 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# onoffice-adapter-js
+
+A JavaScript/TypeScript client for the onOffice API, modeled after the Laravel adapter.
+
+## Installation
+
+```bash
+npm install onoffice-adapter-js
+```
+
+## Usage
+
+```ts
+import {
+  OnOfficeAction,
+  OnOfficeClient,
+  OnOfficeResourceType,
+  createRepositories,
+} from "onoffice-adapter-js";
+
+const client = new OnOfficeClient({
+  token: process.env.ON_OFFICE_TOKEN ?? "",
+  secret: process.env.ON_OFFICE_SECRET ?? "",
+  apiClaim: process.env.ON_OFFICE_API_CLAIM,
+});
+
+const { raw, estate, address, activity, fields, searchCriteria, file, marketplace, settings } =
+  createRepositories(client);
+
+const estates = await estate
+  .query()
+  .select(["Id", "kaufpreis"])
+  .where("status", 1)
+  .orderByField("kaufpreis")
+  .get();
+
+// Count records without fetching
+const totalEstates = await estate.query().where("status", 1).count();
+
+// Iterate over all records
+await estate.query().select(["Id"]).each((record) => {
+  console.log(record.id);
+});
+
+// Delete a record
+await estate.query().delete(12345);
+
+// Raw repository for custom resource types
+const custom = await raw.query(OnOfficeResourceType.Estate).select(["Id"]).find(12345);
+
+const uploaded = await file.upload().uploadInBlocks(20480).saveAndLink("base64EncodedFile", {
+  module: "estate",
+  relatedRecordId: 12345,
+  file: "offer.pdf",
+  Art: "Dokument",
+});
+
+const firstEstate = await estate.query().select(["Id"]).find(12345);
+
+const rawResponse = await client.request(OnOfficeAction.Read, OnOfficeResourceType.Estate, {
+  parameters: {
+    data: ["Id"],
+  },
+});
+
+const addresses = await address.query().select(["Name", "Vorname"]).get();
+
+const activities = await activity
+  .query()
+  .estateId(123)
+  .addressIds([456, 789])
+  .select(["Nr", "Aktionsart", "Aktionstyp", "Datum", "Bemerkung"])
+  .get();
+
+const fieldDefinitions = await fields.query().withModules(["estate", "address"]).get();
+
+const criteria = await searchCriteria.query().mode("searchcriteria").ids([29]).get();
+const criteriaFields = await searchCriteria.fields().get();
+const criteriaMatches = await searchCriteria
+  .search()
+  .searchData({ range_plz: "52074" })
+  .outputAll()
+  .get();
+
+const estateFiles = await file.estateFiles(12345, { includeImageUrl: "small" });
+const addressFiles = await file.addressFiles(6789);
+
+const users = await settings.users().select(["Nr", "Vorname"]).get();
+const regions = await settings.regions().get();
+const imprint = await settings.imprint().select(["Id"]).first();
+const actions = await settings.actions().get();
+
+const invoiceRecipient = await marketplace.invoiceRecipient({
+  transactionId: 1100135697,
+  userId: 42,
+});
+```
+
+Repository classes are exported (`RawRepository`, `EstateRepository`, `AddressRepository`,
+`ActivityRepository`, `FieldRepository`, `SearchCriteriaRepository`, `FileRepository`,
+`MarketplaceRepository`, `SettingRepository`) if you want to wire your own container.
+
+## Notes
+
+- Provide a `fetcher` in the client config if your runtime does not expose `fetch` (Node < 18).
+- Retries happen only on network errors by default; set `retry.onlyOnNetworkError` to `false` for all errors. Non-2xx HTTP responses throw `OnOfficeError` with status details.
+- Query builders are generic so you can type records (e.g. `estate.query<MyEstate>()`).
+- Query builders support Eloquent-style methods: `where()`, `whereIn()`, `first()`, `get()`, `find()`, `create()`, `modify()`, `delete()`, `count()`, `each()`.
+- The `where()` method accepts typed operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `in`, `not in`, `between`, `like`, `not like`.
+- File access uses `file.estateFiles`/`file.addressFiles` and requires a record ID.
+- File uploads for the `estate` module require an `Art` value (e.g. `Dokument`, `Foto`).
+- Pagination defaults to `MAX_PAGE_SIZE` (500), which is also exported as a constant.
+
+## Tooling
+
+```bash
+npm run build
+npm run test
+npm run lint
+npm run format
+```
+
+## Local testing
+
+Create a `.env` in `onoffice-adapter-js` with:
+
+```
+ON_OFFICE_TOKEN=...
+ON_OFFICE_SECRET=...
+ON_OFFICE_API_CLAIM=... # optional
+```
+
+Then run:
+
+```bash
+npm install
+npm run dev
+```

package/dist/activity.d.ts

@@ -0,0 +1,12 @@
+import { OnOfficeQueryBuilder, OnOfficeClient } from "./client";
+export declare class ActivityQueryBuilder<TRecord = unknown> extends OnOfficeQueryBuilder<TRecord> {
+    private estateIdValue?;
+    private addressIdsValue;
+    constructor(client: OnOfficeClient);
+    estateId(id: number): this;
+    addressIds(ids: number | number[]): this;
+    get(): Promise<TRecord[]>;
+    first(): Promise<TRecord | null>;
+    create(data: Record<string, unknown>): Promise<TRecord | null>;
+    private buildEstateOrAddressParameters;
+}

package/dist/activity.js

@@ -0,0 +1,67 @@
+import { OnOfficeAction, OnOfficeResourceType, ParameterKeys } from "./constants";
+import { OnOfficeQueryBuilder } from "./client";
+import { extractFirstRecord } from "./utils";
+export class ActivityQueryBuilder extends OnOfficeQueryBuilder {
+    constructor(client) {
+        super(client, OnOfficeResourceType.Activity);
+        this.addressIdsValue = [];
+    }
+    estateId(id) {
+        this.estateIdValue = id;
+        return this;
+    }
+    addressIds(ids) {
+        this.addressIdsValue = Array.isArray(ids) ? ids : [ids];
+        return this;
+    }
+    async get() {
+        return this.client.requestAll(OnOfficeAction.Read, this.resourceType, {
+            parameters: {
+                ...this.buildEstateOrAddressParameters(false),
+                [ParameterKeys.data]: this.columns,
+                [ParameterKeys.filter]: this.buildFilters(),
+                [ParameterKeys.sortBy]: this.buildOrderBy(),
+                ...this.customParameters,
+            },
+        }, {
+            pageSize: this.pageSizeValue,
+            offset: this.offsetValue,
+            limit: this.limitValue,
+        });
+    }
+    async first() {
+        const listLimit = this.limitValue > -1 ? this.limitValue : 1;
+        const response = await this.client.request(OnOfficeAction.Read, this.resourceType, {
+            parameters: {
+                ...this.buildEstateOrAddressParameters(false),
+                [ParameterKeys.data]: this.columns,
+                [ParameterKeys.filter]: this.buildFilters(),
+                [ParameterKeys.listLimit]: listLimit,
+                [ParameterKeys.listOffset]: this.offsetValue,
+                [ParameterKeys.sortBy]: this.buildOrderBy(),
+                ...this.customParameters,
+            },
+        });
+        return extractFirstRecord(response);
+    }
+    async create(data) {
+        const response = await this.client.request(OnOfficeAction.Create, this.resourceType, {
+            parameters: {
+                ...this.buildEstateOrAddressParameters(true),
+                [ParameterKeys.data]: data,
+                ...this.customParameters,
+            },
+        });
+        return extractFirstRecord(response);
+    }
+    buildEstateOrAddressParameters(isCreate) {
+        const parameters = {};
+        if (this.estateIdValue !== undefined) {
+            parameters.estateid = this.estateIdValue;
+        }
+        if (this.addressIdsValue.length > 0) {
+            parameters[isCreate ? "addressids" : "addressid"] = this.addressIdsValue;
+        }
+        return parameters;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,69 @@
+import { OnOfficeAction } from "./constants";
+import type { FilterOperator, OnOfficeApiResponse, OnOfficeClientConfig, OnOfficeRequestOptions, PaginationOptions } from "./types";
+export declare class OnOfficeClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly secret;
+    private readonly apiClaim?;
+    private readonly headers;
+    private readonly retryCount;
+    private readonly retryDelayMs;
+    private readonly onlyOnNetworkError;
+    private readonly fetcher;
+    private readonly onRequest?;
+    private readonly onResponse?;
+    constructor(config: OnOfficeClientConfig);
+    resource<TRecord = unknown>(resourceType: string): OnOfficeQueryBuilder<TRecord>;
+    request<TRecord = unknown>(actionId: OnOfficeAction, resourceType: string, options?: OnOfficeRequestOptions): Promise<OnOfficeApiResponse<TRecord>>;
+    requestAll<TRecord = unknown>(actionId: OnOfficeAction, resourceType: string, options: OnOfficeRequestOptions, pagination?: PaginationOptions): Promise<TRecord[]>;
+    private sendRequest;
+    private throwIfResponseFailed;
+    private buildRequestPayload;
+}
+export declare class OnOfficeQueryBuilder<TRecord = unknown> {
+    protected readonly client: OnOfficeClient;
+    protected readonly resourceType: string;
+    protected columns: string[];
+    protected filters: Record<string, Array<{
+        op: string;
+        val: unknown;
+    }>>;
+    protected modifies: Record<string, unknown>;
+    protected orderBy: Array<[string, string]>;
+    protected limitValue: number;
+    protected pageSizeValue: number;
+    protected offsetValue: number;
+    protected customParameters: Record<string, unknown>;
+    constructor(client: OnOfficeClient, resourceType: string);
+    select(columns?: string[] | string): this;
+    addSelect(column: string[] | string): this;
+    orderByField(column: string, direction?: "asc" | "desc"): this;
+    orderByDesc(column: string): this;
+    addModify(column: string | Record<string, unknown>, value?: unknown): this;
+    offset(value: number): this;
+    limit(value: number): this;
+    pageSize(value: number): this;
+    where(column: string, value: unknown): this;
+    where(column: string, operator: FilterOperator, value: unknown): this;
+    whereNot(column: string, value: string | number): this;
+    whereIn(column: string, values: unknown[]): this;
+    whereNotIn(column: string, values: unknown[]): this;
+    whereBetween(column: string, start: string | number, end: string | number): this;
+    whereLike(column: string, value: string): this;
+    whereNotLike(column: string, value: string): this;
+    parameter(key: string, value: unknown): this;
+    parameters(parameters: Record<string, unknown>): this;
+    get(): Promise<TRecord[]>;
+    first(): Promise<TRecord | null>;
+    find(id: string | number): Promise<TRecord | null>;
+    create(data: Record<string, unknown>): Promise<TRecord | null>;
+    modify(id: string | number, data?: Record<string, unknown>): Promise<boolean>;
+    delete(id: string | number): Promise<boolean>;
+    count(): Promise<number>;
+    each(callback: (record: TRecord) => void | Promise<void>): Promise<void>;
+    protected buildFilters(): Record<string, Array<{
+        op: string;
+        val: unknown;
+    }>>;
+    protected buildOrderBy(): Record<string, string>;
+}

package/dist/client.js

@@ -0,0 +1,363 @@
+import { MAX_PAGE_SIZE, OnOfficeAction, ParameterKeys } from "./constants";
+import { OnOfficeError } from "./errors";
+import { createHmacSignature } from "./hmac";
+import { extractFirstRecord } from "./utils";
+const DEFAULT_BASE_URL = "https://api.onoffice.de/api/stable/api.php";
+const DEFAULT_HEADERS = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+};
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class OnOfficeClient {
+    constructor(config) {
+        this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+        this.token = config.token;
+        this.secret = config.secret;
+        this.apiClaim = config.apiClaim;
+        this.headers = {
+            ...DEFAULT_HEADERS,
+            ...config.headers,
+        };
+        this.retryCount = Math.max(1, config.retry?.count ?? 3);
+        this.retryDelayMs = Math.max(1, config.retry?.delayMs ?? 200);
+        this.onlyOnNetworkError = config.retry?.onlyOnNetworkError ?? true;
+        this.fetcher = config.fetcher ?? globalThis.fetch?.bind(globalThis);
+        this.onRequest = config.onRequest;
+        this.onResponse = config.onResponse;
+        if (!this.fetcher) {
+            throw new Error("Fetch is not available. Provide a fetcher in the config.");
+        }
+    }
+    resource(resourceType) {
+        return new OnOfficeQueryBuilder(this, resourceType);
+    }
+    async request(actionId, resourceType, options = {}) {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const payload = await this.buildRequestPayload(actionId, resourceType, options, timestamp);
+        return this.sendRequest(payload);
+    }
+    async requestAll(actionId, resourceType, options, pagination = {}) {
+        const pageSize = pagination.pageSize ?? 500;
+        let offset = pagination.offset ?? 0;
+        const limit = pagination.limit ?? -1;
+        let maxPage = 0;
+        const records = [];
+        do {
+            const response = await this.request(actionId, resourceType, {
+                ...options,
+                parameters: {
+                    ...options.parameters,
+                    [ParameterKeys.listLimit]: pageSize,
+                    [ParameterKeys.listOffset]: offset,
+                },
+            });
+            const dataRecords = response.response?.results?.[0]?.data?.records ?? [];
+            if (maxPage === 0) {
+                const countAbsolute = response.response?.results?.[0]?.data?.meta?.cntabsolute ?? 0;
+                maxPage = Math.ceil(countAbsolute / pageSize);
+            }
+            if (Array.isArray(dataRecords)) {
+                records.push(...dataRecords);
+            }
+            if (limit > -1 && records.length > limit) {
+                return records.slice(0, limit);
+            }
+            offset += pageSize;
+            const currentPage = offset / pageSize;
+            if (maxPage <= currentPage) {
+                break;
+            }
+        } while (maxPage > 0);
+        return records;
+    }
+    async sendRequest(payload) {
+        let lastError;
+        const startTime = Date.now();
+        this.onRequest?.({
+            url: this.baseUrl,
+            method: "POST",
+            headers: { ...this.headers },
+            body: payload,
+            timestamp: startTime,
+        });
+        for (let attempt = 0; attempt < this.retryCount; attempt += 1) {
+            try {
+                const response = await this.fetcher(this.baseUrl, {
+                    method: "POST",
+                    headers: this.headers,
+                    body: JSON.stringify(payload),
+                });
+                if (response.ok === false) {
+                    const body = typeof response.text === "function" ? await response.text().catch(() => "") : "";
+                    throw new OnOfficeError(`HTTP ${response.status}: ${response.statusText}`, response.status, {
+                        response: body
+                            ? { status: response.status, statusText: response.statusText, body }
+                            : { status: response.status, statusText: response.statusText },
+                    });
+                }
+                const data = (await response.json());
+                this.onResponse?.({
+                    url: this.baseUrl,
+                    status: response.status,
+                    statusText: response.statusText,
+                    body: data,
+                    durationMs: Date.now() - startTime,
+                    timestamp: Date.now(),
+                });
+                this.throwIfResponseFailed(data);
+                return data;
+            }
+            catch (error) {
+                lastError = error;
+                const shouldRetry = !this.onlyOnNetworkError || error instanceof TypeError;
+                if (!shouldRetry || attempt >= this.retryCount - 1) {
+                    throw error;
+                }
+                await sleep(this.retryDelayMs);
+            }
+        }
+        throw lastError;
+    }
+    throwIfResponseFailed(response) {
+        const status = response.status ?? {};
+        const statusCode = status.code ?? 500;
+        const statusErrorCode = status.errorcode ?? 0;
+        const responseStatusCode = response.response?.results?.[0]?.status?.errorcode ?? 0;
+        const errorMessage = status.message || `Status code: ${statusCode}`;
+        const responseErrorMessage = response.response?.results?.[0]?.status?.message || `Status code: ${responseStatusCode}`;
+        if (statusCode >= 300 && statusErrorCode > 0 && responseStatusCode === 0) {
+            throw new OnOfficeError(errorMessage, statusErrorCode, {
+                isResponseError: true,
+                response,
+            });
+        }
+        if (statusCode >= 300 && statusErrorCode <= 0 && responseStatusCode === 0) {
+            throw new OnOfficeError(errorMessage, statusCode, { response });
+        }
+        if (responseStatusCode > 0) {
+            throw new OnOfficeError(responseErrorMessage, responseStatusCode, {
+                isResponseError: true,
+                response,
+            });
+        }
+    }
+    async buildRequestPayload(actionId, resourceType, options, timestamp) {
+        const resourceId = options.resourceId ?? "";
+        const identifier = options.identifier ?? "";
+        const parameters = {
+            ...(this.apiClaim ? { [ParameterKeys.extendedClaim]: this.apiClaim } : {}),
+            ...(options.parameters ?? {}),
+        };
+        const message = `${timestamp}${this.token}${resourceType}${actionId}`;
+        const hmac = await createHmacSignature(message, this.secret);
+        return {
+            token: this.token,
+            request: {
+                actions: [
+                    {
+                        actionid: actionId,
+                        resourceid: resourceId,
+                        resourcetype: resourceType,
+                        identifier,
+                        timestamp,
+                        hmac,
+                        hmac_version: 2,
+                        parameters,
+                    },
+                ],
+            },
+        };
+    }
+}
+export class OnOfficeQueryBuilder {
+    constructor(client, resourceType) {
+        this.client = client;
+        this.resourceType = resourceType;
+        this.columns = [];
+        this.filters = {};
+        this.modifies = {};
+        this.orderBy = [];
+        this.limitValue = -1;
+        this.pageSizeValue = MAX_PAGE_SIZE;
+        this.offsetValue = 0;
+        this.customParameters = {};
+    }
+    select(columns = ["ID"]) {
+        this.columns = Array.isArray(columns) ? columns : [columns];
+        return this;
+    }
+    addSelect(column) {
+        const next = Array.isArray(column) ? column : [column];
+        this.columns = [...this.columns, ...next];
+        return this;
+    }
+    orderByField(column, direction = "asc") {
+        this.orderBy.push([column, direction.toUpperCase()]);
+        return this;
+    }
+    orderByDesc(column) {
+        return this.orderByField(column, "desc");
+    }
+    addModify(column, value) {
+        if (typeof column === "string") {
+            this.modifies[column] = value;
+        }
+        else {
+            this.modifies = { ...this.modifies, ...column };
+        }
+        return this;
+    }
+    offset(value) {
+        this.offsetValue = Math.max(0, value);
+        return this;
+    }
+    limit(value) {
+        this.limitValue = Math.max(-1, value);
+        return this;
+    }
+    pageSize(value) {
+        const bounded = Math.min(MAX_PAGE_SIZE, Math.max(1, value));
+        this.pageSizeValue = bounded;
+        return this;
+    }
+    where(column, operatorOrValue, value) {
+        let operator = "=";
+        let filterValue;
+        if (value === undefined) {
+            filterValue = operatorOrValue;
+        }
+        else {
+            operator = operatorOrValue;
+            filterValue = value;
+        }
+        if (!this.filters[column]) {
+            this.filters[column] = [];
+        }
+        this.filters[column].push({ op: operator, val: filterValue });
+        return this;
+    }
+    whereNot(column, value) {
+        return this.where(column, "!=", value);
+    }
+    whereIn(column, values) {
+        return this.where(column, "in", values);
+    }
+    whereNotIn(column, values) {
+        return this.where(column, "not in", values);
+    }
+    whereBetween(column, start, end) {
+        return this.where(column, "between", [start, end]);
+    }
+    whereLike(column, value) {
+        return this.where(column, "like", value);
+    }
+    whereNotLike(column, value) {
+        return this.where(column, "not like", value);
+    }
+    parameter(key, value) {
+        this.customParameters[key] = value;
+        return this;
+    }
+    parameters(parameters) {
+        this.customParameters = {
+            ...this.customParameters,
+            ...parameters,
+        };
+        return this;
+    }
+    async get() {
+        return this.client.requestAll(OnOfficeAction.Read, this.resourceType, {
+            parameters: {
+                [ParameterKeys.data]: this.columns,
+                [ParameterKeys.filter]: this.buildFilters(),
+                [ParameterKeys.sortBy]: this.buildOrderBy(),
+                ...this.customParameters,
+            },
+        }, {
+            pageSize: this.pageSizeValue,
+            offset: this.offsetValue,
+            limit: this.limitValue,
+        });
+    }
+    async first() {
+        const listLimit = this.limitValue > -1 ? this.limitValue : 1;
+        const response = await this.client.request(OnOfficeAction.Read, this.resourceType, {
+            parameters: {
+                [ParameterKeys.data]: this.columns,
+                [ParameterKeys.filter]: this.buildFilters(),
+                [ParameterKeys.listLimit]: listLimit,
+                [ParameterKeys.listOffset]: this.offsetValue,
+                [ParameterKeys.sortBy]: this.buildOrderBy(),
+                ...this.customParameters,
+            },
+        });
+        return extractFirstRecord(response);
+    }
+    async find(id) {
+        const response = await this.client.request(OnOfficeAction.Read, this.resourceType, {
+            resourceId: id,
+            parameters: {
+                [ParameterKeys.data]: this.columns,
+                ...this.customParameters,
+            },
+        });
+        return extractFirstRecord(response);
+    }
+    async create(data) {
+        const response = await this.client.request(OnOfficeAction.Create, this.resourceType, {
+            parameters: {
+                [ParameterKeys.data]: data,
+                ...this.customParameters,
+            },
+        });
+        return extractFirstRecord(response);
+    }
+    async modify(id, data) {
+        const payload = data ?? this.modifies;
+        if (!payload || Object.keys(payload).length === 0) {
+            throw new Error("No data provided for modify().");
+        }
+        await this.client.request(OnOfficeAction.Modify, this.resourceType, {
+            resourceId: id,
+            parameters: {
+                [ParameterKeys.data]: payload,
+                ...this.customParameters,
+            },
+        });
+        return true;
+    }
+    async delete(id) {
+        await this.client.request(OnOfficeAction.Delete, this.resourceType, {
+            resourceId: id,
+            parameters: {
+                ...this.customParameters,
+            },
+        });
+        return true;
+    }
+    async count() {
+        const response = await this.client.request(OnOfficeAction.Read, this.resourceType, {
+            parameters: {
+                [ParameterKeys.data]: [],
+                [ParameterKeys.filter]: this.buildFilters(),
+                [ParameterKeys.listLimit]: 1,
+                ...this.customParameters,
+            },
+        });
+        return response.response?.results?.[0]?.data?.meta?.cntabsolute ?? 0;
+    }
+    async each(callback) {
+        const records = await this.get();
+        for (const record of records) {
+            await callback(record);
+        }
+    }
+    buildFilters() {
+        return { ...this.filters };
+    }
+    buildOrderBy() {
+        return Object.fromEntries(this.orderBy.map(([column, direction]) => [column, direction]));
+    }
+}