nuki-api-js 0.2.1 → 1.1.0

package/README.md

@@ -1,13 +1,68 @@
-# Nuki API JavaScript SDK
+# nuki-api-js
 
-Unofficial Nuki API JavaScript SDK built from the OpenAPI specification and with TypeScript types.
+Auto-generated, fully typed client for the [Nuki Web API](https://api.nuki.io/).
+
+## Features
+
+- **Fully typed** - every operation, parameter and response is generated from the official OpenAPI spec
+- **Tree-shakable** - only the operations you import end up in your bundle
+- **Runtime agnostic** - uses the global `fetch`, or bring your own implementation
+- **Effect support** - optional [Effect](https://effect.website) bindings via `nuki-api-js/effect`
+
+## Installation
+
+```bash
+npm install nuki-api-js
+```
+
+## Quick Start
 
 ```ts
-const nuki = new NukiApi({ token: 'token' });
+import { NukiApi } from "nuki-api-js";
 
-// Direct methods
-const { accountId, name } = await nuki.request('GET /account', {});
+const client = new NukiApi({ token: process.env.NUKI_TOKEN ?? null });
 
-// Namespaced methods
-await nuki.api.smartlock.postSmartlockLockActionResource({ pathParams: { smartlockId: 'smartlockId' } });
+const accounts = await client.api.account.getAccountsResource({});
 ```
+
+Operations are grouped by tag: `client.api.<tag>.<operation>(params)`.
+
+### Custom fetch
+
+```ts
+const client = new NukiApi({
+  token: process.env.NUKI_TOKEN ?? null,
+  fetch: myFetchImplementation,
+});
+```
+
+## Effect
+
+The `effect` entrypoint exposes every operation as an `Effect`. It requires `effect` as a peer dependency.
+
+```ts
+import { Effect } from "effect";
+import { ApiService, makeApiLayer } from "nuki-api-js/effect";
+
+const program = ApiService.account.getAccountsResource({});
+
+await Effect.runPromise(
+  program.pipe(Effect.provide(makeApiLayer({ token: process.env.NUKI_TOKEN })))
+);
+```
+
+Errors are typed as `ApiError`, `NetworkError` and `ValidationError`.
+
+## Entrypoints
+
+| Import | Contents |
+| --- | --- |
+| `nuki-api-js` | client class, operations, schemas and types |
+| `nuki-api-js/components` | operations grouped by tag and by path |
+| `nuki-api-js/schemas` | Zod schemas for every operation |
+| `nuki-api-js/types` | TypeScript types for every operation |
+| `nuki-api-js/effect` | Effect bindings |
+
+## License
+
+ISC