onofficejs

Unofficial community client — not affiliated with onOffice GmbH.
This is not the official onOffice SDK. For the official PHP client see onOfficeGmbH/sdk.
See DISCLAIMER.md for legal and trademark information.

Unofficial TypeScript/JavaScript wrapper for the onOffice API.

Community-maintained, async-first, fully typed, and designed for Node.js 18+, Bun, Deno, and edge runtimes. Implements the public JSON API protocol documented by onOffice — including HMAC v2 signing and batch requests.

Features

• Async/await — no manual sendRequests() unless you want batch control
• TypeScript-first — strict types, declaration maps, IDE autocomplete
• Batch requests — multiple API actions in one HTTP round-trip
• HMAC v2 signing — compatible with documented onOffice API auth
• Pluggable cache — built-in LRU memory cache with TTL
• Resource helpers — client.estates.read(), client.addresses.read(), etc.
• Query builders — fluent filter/sort/pagination helpers
• Structured errors — transport vs API vs invalid response
• Retries & timeouts — resilient HTTP transport
• Zero runtime dependencies — uses native fetch and crypto
• Dual package — ESM + CommonJS exports

Install

npm install onofficejs
# or from GitHub:
npm install github:Felixfalk26/onofficejs

Use in another project

{
  "dependencies": {
    "onofficejs": "github:Felixfalk26/onofficejs"
  }
}

See docs/USAGE-AS-DEPENDENCY.md.

Quick start

Requires a valid onOffice enterprise API user (paid module) — see onOffice API docs.

import { OnOfficeClient, filter, sort, paginate } from 'onofficejs';

const client = new OnOfficeClient({
  token: process.env.ONOFFICE_TOKEN,
  secret: process.env.ONOFFICE_SECRET,
});

const { data } = await client.estates.read(
  paginate(10, 0, {
    data: ['Id', 'kaufpreis', 'lage'],
    sortby: sort({ kaufpreis: 'ASC' }),
    filter: filter().gt('kaufpreis', 300_000).eq('status', 1).build(),
  }),
);

console.log(data.records);

Documentation

| Guide | Description | |---|---| | DISCLAIMER.md | Unofficial status, legal & trademark notice | | docs/LEGAL.md | Detailed legal FAQ | | API Reference | Full client API | | Caching | Cache adapters & TTL | | Migration from PHP SDK | Side-by-side PHP → JS | | Security | Credential handling | | Contributing | Dev setup & PR process |

Usage patterns

Resource helpers (recommended)

await client.estates.read({ data: ['Id'], listlimit: 10 });
await client.estates.search('Berlin');
await client.estates.modifyFields('568', { kaufpreis: 200000 });
await client.addresses.read({ data: ['Id', 'Vorname', 'Name'] });

Updating estate fields

modifyFields() sends a Modify action with the estate id as the action resourceid and the changed fields under parameters.data, matching the onOffice API shape for estate updates.

await client.estates.modifyFields('568', {
  kaufpreis: 200000, // send numeric estate fields as numbers
  objekttitel: 'Wohnung in Berlin',
});

You can also pass the raw API parameter object:

await client.estates.modify('568', {
  data: { kaufpreis: 200000 },
});

Some read fields can be nested objects, for example parking-lot aggregates such as multiParkingLot. Treat record.elements as Record<string, unknown> and validate or narrow values in your application before displaying or writing them back.

Batch mode

import { ActionId, Module } from 'onofficejs';

const [estates, addresses] = await client.batch((b) => [
  b.callGeneric(ActionId.Read, Module.Estate, { data: ['Id'], listlimit: 5 }),
  b.callGeneric(ActionId.Read, Module.Address, { data: ['Id'], listlimit: 5 }),
]);

PHP SDK parity layer

import { ActionId, Module, onOfficeSDK } from 'onofficejs';

const sdk = new onOfficeSDK({ token, secret });
const handle = sdk.callGeneric(ActionId.Read, Module.Estate, { data: ['Id'] });
await sdk.sendRequests();
const response = sdk.getResponse(handle);

Error handling

import { OnOfficeApiError, OnOfficeTransportError } from 'onofficejs';

try {
  await client.estates.read({ data: ['Id'] });
} catch (error) {
  if (error instanceof OnOfficeApiError) {
    console.error(error.errorCode, error.message);
  }
}

Requirements

• Node.js 18+
• Valid onOffice enterprise API credentials — apidoc.onoffice.de

Official vs unofficial

| | Official PHP SDK | onofficejs (this repo) | |---|---|---| | Maintainer | onOffice GmbH | Community | | Language | PHP | TypeScript / JavaScript | | Support | [email protected] | GitHub Issues only | | Status | Official | Unofficial wrapper |

License

MIT — see LICENSE. Applies to this library’s source code only.

Trademarks and API services belong to onOffice GmbH — see DISCLAIMER.md and NOTICE.