npm - @omnizoek/react - Versions diffs - 0.1.0 → 0.1.2 - Mend

@omnizoek/react 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +362 -0
package/package.json +2 -2

package/README.md ADDED Viewed

@@ -0,0 +1,362 @@
+# @omnizoek/react
+React hooks for the [OmniZoek API](https://omnizoek.nl) — Dutch government data (addresses, IBAN, VAT, energy labels, vehicles and more) in one clean set of SWR-backed hooks.
+[![npm version](https://img.shields.io/npm/v/@omnizoek/react)](https://www.npmjs.com/package/@omnizoek/react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+---
+## Features
+- **10 ready-made hooks** — one per endpoint, typed in and out
+- **SWR-powered** — automatic caching, deduplication, and background revalidation
+- **Skip requests cleanly** — pass `null` as params to suspend a hook without conditionals
+- **`enabled` flag** — opt-out of fetching without unmounting the hook
+- **`refetch()`** — trigger manual revalidation from anywhere
+- **Full TypeScript support** — every hook is fully typed via `@omnizoek/sdk`
+- **ESM + CJS dual output** — works in Next.js, Vite, Remix, and plain CRA
+---
+## Installation
+```bash
+npm install @omnizoek/react @omnizoek/sdk swr
+# or
+pnpm add @omnizoek/react @omnizoek/sdk swr
+# or
+yarn add @omnizoek/react @omnizoek/sdk swr
+```
+> `@omnizoek/sdk`, `react ≥ 17`, and `swr ≥ 2` are **peer dependencies** — install them alongside this package.
+---
+## Quick start
+### 1. Wrap your app with `<OmniProvider>`
+```tsx
+import { OmniProvider } from "@omnizoek/react";
+function App() {
+  return (
+    <OmniProvider apiKey="omni_test_…">
+      <MyPage />
+    </OmniProvider>
+  );
+}
+```
+### 2. Use any hook inside the tree
+```tsx
+import { useAddressEnrich } from "@omnizoek/react";
+function AddressCard({ postcode, houseNumber }) {
+  const { data, loading, error } = useAddressEnrich(
+    postcode && houseNumber ? { postcode, houseNumber } : null
+  );
+  if (loading) return <p>Laden…</p>;
+  if (error)   return <p>Fout: {error.message}</p>;
+  if (!data)   return null;
+  return (
+    <p>
+      {data.street} {data.house_number}, {data.city}
+    </p>
+  );
+}
+```
+---
+## Next.js App Router example
+```tsx
+// app/layout.tsx
+"use client";
+import { OmniProvider } from "@omnizoek/react";
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="nl">
+      <body>
+        <OmniProvider apiKey={process.env.NEXT_PUBLIC_OMNI_API_KEY!}>
+          {children}
+        </OmniProvider>
+      </body>
+    </html>
+  );
+}
+```
+---
+## API key
+Get a free **sandbox key** instantly — no sign-up required:
+```bash
+curl -X POST https://api.omnizoek.nl/v1/keys/test
+```
+Or visit [omnizoek.nl/playground](https://omnizoek.nl/playground) to try every endpoint live.
+---
+## Hooks reference
+All hooks return an [`OmniHookResult<T>`](#omniHookResult) object.
+Pass `null` (or `undefined`) as `params` to skip the request without a conditional hook call.
+---
+### `useAddressEnrich` — Geographic enrichment
+Enriches a Dutch address via the BAG (postcode + house number → street, city, coordinates, energy label).
+```tsx
+import { useAddressEnrich } from "@omnizoek/react";
+const { data, loading, error } = useAddressEnrich(
+  postcode ? { postcode, houseNumber } : null
+);
+// data.street, data.city, data.lat, data.lon, data.energy_label, …
+```
+---
+### `useIbanToBic` — IBAN → BIC lookup
+Resolves a Dutch or EU IBAN to its BIC/SWIFT code and bank name.
+```tsx
+import { useIbanToBic } from "@omnizoek/react";
+const { data } = useIbanToBic({ iban: "NL91ABNA0417164300" });
+// data.bic, data.bank_name, data.country_code
+```
+---
+### `useVatVerify` — EU VAT verification
+Checks a VAT number via the EU VIES service.
+```tsx
+import { useVatVerify } from "@omnizoek/react";
+const { data } = useVatVerify({ countryCode: "NL", vatNumber: "123456782B01" });
+// data.valid, data.company_name, data.address, data.checked_at
+```
+---
+### `useValidateFinance` — BSN / IBAN checksum validation
+Validates the checksum of a BSN (11-proef) or IBAN (MOD-97).
+```tsx
+import { useValidateFinance } from "@omnizoek/react";
+const { data } = useValidateFinance({ type: "bsn", number: "123456782" });
+// data.valid, data.type, data.algorithm, data.detail
+```
+---
+### `useMinimumWage` — Statutory minimum wage (WML)
+Returns the applicable gross hourly, daily and monthly minimum wage for a given age and date.
+```tsx
+import { useMinimumWage } from "@omnizoek/react";
+const { data } = useMinimumWage({ age: 21, date: "2025-01-01" });
+// data.hourly_eur, data.daily_eur, data.monthly_eur, data.law_reference
+```
+---
+### `useHolidaySurcharge` — Holiday surcharge calculator
+Returns whether a date is a public holiday and the applicable surcharge multiplier for a given industry.
+```tsx
+import { useHolidaySurcharge } from "@omnizoek/react";
+const { data } = useHolidaySurcharge({ date: "2025-12-25", industry: "retail" });
+// data.is_holiday, data.holiday_name, data.surcharge_multiplier
+```
+---
+### `useEnergyLabel` — EP-Online energy label
+Looks up the registered energy label for a Dutch address.
+```tsx
+import { useEnergyLabel } from "@omnizoek/react";
+const { data } = useEnergyLabel({ postcode: "1012LG", houseNumber: "1" });
+// data.energy_label, data.label_class, data.registered_at, data.valid_until
+```
+---
+### `useEmissionZone` — Zero-emission zone check
+Checks whether a vehicle (by licence plate) is allowed in Dutch zero-emission zones.
+```tsx
+import { useEmissionZone } from "@omnizoek/react";
+const { data } = useEmissionZone({ kenteken: "AB123C" });
+// data.ze_compliant, data.fuel_types, data.euro_standard, data.zones_checked
+```
+---
+### `useTransitDisruptions` — NS train disruptions
+Returns active and planned train disruptions for a given NS station code.
+```tsx
+import { useTransitDisruptions } from "@omnizoek/react";
+const { data } = useTransitDisruptions({ stationCode: "ASD" });
+// data.disruptions: [{ type, title, cause, start, end }]
+```
+---
+### `useGridTrigger` — ENTSO-E electricity price trigger
+Returns the current day-ahead electricity price and whether it is negative (a grid overload trigger).
+```tsx
+import { useGridTrigger } from "@omnizoek/react";
+const { data } = useGridTrigger(); // no params required
+if (data?.trigger) {
+  // ⚡ Negative price — good time for high-consumption processes
+}
+// data.negative_price, data.current_price_eur_mwh, data.period_start
+```
+---
+## `OmniHookResult<T>`
+Every hook returns this shape:
+```ts
+interface OmniHookResult<T> {
+  /** Response data, or `undefined` while loading or on error */
+  data: T | undefined;
+  /** `true` on the initial load (no cached data yet) */
+  loading: boolean;
+  /** `true` whenever a background revalidation is in flight */
+  validating: boolean;
+  /** Typed error from the SDK, or `null` */
+  error: Error | null;
+  /** Manually trigger a refetch / revalidation */
+  refetch: () => Promise<T | undefined>;
+}
+```
+---
+## Hook options
+All hooks accept an optional second argument:
+```ts
+interface UseOmniQueryOptions {
+  /**
+   * Set to `false` to skip the request without passing `null` as params.
+   * @default true
+   */
+  enabled?: boolean;
+}
+```
+Example — skip fetching until a checkbox is checked:
+```tsx
+const { data } = useEnergyLabel(
+  { postcode, houseNumber },
+  { enabled: showEnergyLabel }
+);
+```
+---
+## Error handling
+All SDK errors extend `OmniError` and are available from `@omnizoek/sdk`:
+```tsx
+import {
+  OmniAuthError,
+  OmniNotFoundError,
+  OmniRateLimitError,
+} from "@omnizoek/sdk";
+const { error } = useAddressEnrich({ postcode: "0000XX", houseNumber: "0" });
+if (error instanceof OmniAuthError)      { /* invalid API key */ }
+if (error instanceof OmniNotFoundError)  { /* address not found */ }
+if (error instanceof OmniRateLimitError) { /* rate limited */ }
+```
+---
+## `OmniProvider` props
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | ✅ | Your OmniZoek API key (`omni_live_…` or `omni_test_…`) |
+| `baseUrl` | `string` | — | Override the API base URL (useful for local mocks) |
+| `options` | `OmniClientOptions` | — | Additional options forwarded to `OmniClient` (retries, timeout, …) |
+| `children` | `ReactNode` | ✅ | Component subtree that can use OmniZoek hooks |
+The underlying `OmniClient` is memoized and only recreated when `apiKey` or `baseUrl` changes.
+---
+## Requirements
+- **React ≥ 17**
+- **SWR ≥ 2**
+- **`@omnizoek/sdk` ≥ 0.1.1**
+- **Node.js ≥ 18** (for SSR / server components)
+---
+## Related packages
+| Package | Description |
+|---|---|
+| [`@omnizoek/sdk`](https://www.npmjs.com/package/@omnizoek/sdk) | Framework-agnostic TypeScript SDK |
+---
+## License
+MIT — see [LICENSE](LICENSE).

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@omnizoek/react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "React hooks for the OmniZoek API — address enrichment, IBAN, vehicle, energy labels and more.",
   "author": "OmniZoek <support@omnizoek.nl>",
   "license": "MIT",
@@ -47,7 +47,7 @@
     "swr": ">=2"
   },
   "devDependencies": {
-    "@omnizoek/sdk": "^0.1.1",
+    "@omnizoek/sdk": "^0.1.2",
     "@types/react": "^18.0.0",
     "react": "^18.0.0",
     "swr": "^2.2.0",