npm package: @innobrain/onoffice-adapter-js
Description: OnOffice API adapter for JavaScript projects
Latest version: 0.2.0

# @innobrain/onoffice-adapter-js

A JavaScript/TypeScript client for the onOffice API, modeled after the Laravel adapter.

## Installation

```bash
npm install @innobrain/onoffice-adapter-js
```

## Usage

```ts
import {
  OnOfficeAction,
  OnOfficeClient,
  OnOfficeResourceType,
  createRepositories,
} from "@innobrain/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
```