@omnizoek/sdk 0.1.0

package/README.md

@@ -0,0 +1,234 @@
+# @omnizoek/sdk
+
+Official TypeScript/JavaScript SDK for the [OmniZoek API](https://omnizoek.nl) — Dutch government data in one clean REST API.
+
+[![npm version](https://img.shields.io/npm/v/@omnizoek/sdk)](https://www.npmjs.com/package/@omnizoek/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Features
+
+- **Full TypeScript support** — every request and response is typed
+- **ESM + CJS dual output** — works in Node.js, Deno, Bun, and browser bundles
+- **Automatic retries** — exponential back-off on `429 Rate Limit` responses
+- **Typed errors** — `OmniAuthError`, `OmniNotFoundError`, `OmniRateLimitError` etc.
+- **Zero dependencies** — uses the native `fetch` API (Node ≥ 18)
+
+---
+
+## Installation
+
+```bash
+npm install @omnizoek/sdk
+# or
+pnpm add @omnizoek/sdk
+# or
+yarn add @omnizoek/sdk
+```
+
+---
+
+## Quick start
+
+```ts
+import { OmniClient } from "@omnizoek/sdk";
+
+const omni = new OmniClient({ apiKey: "omni_live_…" });
+
+// Enrich a Dutch address
+const address = await omni.geo.enrichAddress({
+  postcode: "1012LG",
+  houseNumber: "1",
+});
+console.log(address.city); // "Amsterdam"
+
+// Get the statutory minimum wage for a 21-year-old
+const wage = await omni.hr.minimumWage({ age: 21 });
+console.log(wage.hourly_eur); // e.g. 13.27
+```
+
+---
+
+## 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.
+
+---
+
+## Endpoints
+
+### `omni.geo` — Geographic enrichment
+
+```ts
+const result = await omni.geo.enrichAddress({
+  postcode: "1012LG",
+  houseNumber: "1",
+  // energy?: boolean  — include EP-Online energy label (default: true)
+});
+```
+
+Returns: full BAG address, coordinates, municipality, province, energy label.
+
+---
+
+### `omni.finance` — Financial utilities
+
+```ts
+// IBAN → BIC
+const bic = await omni.finance.ibanToBic({ iban: "NL91ABNA0417164300" });
+// result: { iban, bic, bank_name, country_code }
+
+// VAT number verification (EU VIES)
+const vat = await omni.finance.vatVerify({
+  countryCode: "NL",
+  vatNumber: "123456782B01",
+});
+// result: { valid, status, company_name, address, checked_at, … }
+```
+
+---
+
+### `omni.compliance` — Compliance checks
+
+```ts
+// Validate a BSN or IBAN checksum
+const result = await omni.compliance.validateFinance({
+  type: "iban",           // "bsn" | "iban"
+  number: "NL91ABNA0417164300",
+});
+// result: { valid, type, number, algorithm, detail }
+```
+
+---
+
+### `omni.hr` — HR calculations
+
+```ts
+// Statutory minimum wage (WML)
+const wage = await omni.hr.minimumWage({ age: 21, date: "2024-07-01" });
+// result: { age, date, hourly_eur, daily_eur, monthly_eur, law_reference }
+
+// Holiday/public-holiday surcharge
+const surcharge = await omni.hr.holidaySurcharge({
+  date: "2024-12-25",
+  industry: "retail",
+});
+// result: { is_holiday, holiday_name, surcharge_multiplier, … }
+```
+
+---
+
+### `omni.realEstate` — Real estate
+
+```ts
+// EP-Online energy label
+const label = await omni.realEstate.energyLabel({
+  postcode: "1012LG",
+  houseNumber: "1",
+});
+// result: { energy_label, label_class, registered_at, valid_until, … }
+```
+
+---
+
+### `omni.logistics` — Logistics
+
+```ts
+// Zero-emission zone check
+const ze = await omni.logistics.emissionZone({ kenteken: "AB123C" });
+// result: { ze_compliant, fuel_types, euro_standard, zones_checked, … }
+
+// NS train disruptions
+const disruptions = await omni.logistics.transitDisruptions({ stationCode: "ASD" });
+// result: { station_code, disruptions: [{ type, title, cause, start, end }], … }
+```
+
+---
+
+### `omni.energy` — Energy grid
+
+```ts
+// ENTSO-E negative price / grid trigger
+const grid = await omni.energy.gridTrigger(); // defaults to NL
+// result: { negative_price, trigger, current_price_eur_mwh, period_start, … }
+```
+
+---
+
+### `omni.webhooks` — Outbound webhooks
+
+```ts
+// Register
+const wh = await omni.webhooks.register({
+  url: "https://example.com/hook",
+  events: ["quota.warning", "quota.exceeded"],
+});
+// result: { webhook_id, secret }  ← store secret for HMAC verification
+
+// List all
+const { webhooks } = await omni.webhooks.list();
+
+// Delete
+await omni.webhooks.delete(wh.webhook_id);
+```
+
+---
+
+## Error handling
+
+All errors extend `OmniError`:
+
+```ts
+import {
+  OmniAuthError,
+  OmniNotFoundError,
+  OmniRateLimitError,
+  OmniUpstreamError,
+  OmniNetworkError,
+} from "@omnizoek/sdk";
+
+try {
+  const result = await omni.geo.enrichAddress({ postcode: "0000XX", houseNumber: "0" });
+} catch (err) {
+  if (err instanceof OmniAuthError)       console.error("Invalid API key");
+  if (err instanceof OmniNotFoundError)   console.error("Address not found");
+  if (err instanceof OmniRateLimitError)  console.error("Rate limited — retry after", err.retryAfterMs, "ms");
+  if (err instanceof OmniUpstreamError)   console.error("Upstream data source unavailable");
+  if (err instanceof OmniNetworkError)    console.error("Network error", err.cause);
+}
+```
+
+---
+
+## Client options
+
+```ts
+const omni = new OmniClient({
+  apiKey: "omni_live_…",       // required
+  baseUrl: "https://api.omnizoek.nl", // optional override
+  maxRetries: 3,               // max 429 retries (default: 3)
+  retryDelayMs: 500,           // base back-off delay (default: 500 ms)
+  timeoutMs: 20_000,           // request timeout (default: 20 s)
+});
+```
+
+---
+
+## Requirements
+
+- **Node.js ≥ 18** (native `fetch`)
+- Browsers and edge runtimes with `fetch` support
+- TypeScript 5.x (optional, for types)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,448 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  OmniAuthError: () => exports.OmniAuthError,
+  OmniError: () => exports.OmniError,
+  OmniNetworkError: () => exports.OmniNetworkError,
+  OmniNotFoundError: () => exports.OmniNotFoundError,
+  OmniRateLimitError: () => exports.OmniRateLimitError,
+  OmniUpstreamError: () => exports.OmniUpstreamError,
+  OmniValidationError: () => exports.OmniValidationError
+});
+exports.OmniError = void 0; exports.OmniAuthError = void 0; exports.OmniNotFoundError = void 0; exports.OmniValidationError = void 0; exports.OmniRateLimitError = void 0; exports.OmniUpstreamError = void 0; exports.OmniNetworkError = void 0;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    exports.OmniError = class extends Error {
+      constructor(message, status, code, detail) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.detail = detail;
+        this.name = "OmniError";
+      }
+    };
+    exports.OmniAuthError = class extends exports.OmniError {
+      constructor(detail) {
+        super(`Authentication failed: ${detail}`, 401, "auth_error", detail);
+        this.name = "OmniAuthError";
+      }
+    };
+    exports.OmniNotFoundError = class extends exports.OmniError {
+      constructor(detail) {
+        super(`Not found: ${detail}`, 404, "not_found", detail);
+        this.name = "OmniNotFoundError";
+      }
+    };
+    exports.OmniValidationError = class extends exports.OmniError {
+      constructor(detail) {
+        super(`Validation error: ${detail}`, 422, "validation_error", detail);
+        this.name = "OmniValidationError";
+      }
+    };
+    exports.OmniRateLimitError = class extends exports.OmniError {
+      constructor(retryAfterMs) {
+        super(
+          `Rate limit exceeded. Retry after ${retryAfterMs}ms.`,
+          429,
+          "rate_limit",
+          `Retry after ${retryAfterMs}ms`
+        );
+        this.retryAfterMs = retryAfterMs;
+        this.name = "OmniRateLimitError";
+      }
+    };
+    exports.OmniUpstreamError = class extends exports.OmniError {
+      constructor(detail) {
+        super(`Upstream error: ${detail}`, 503, "upstream_error", detail);
+        this.name = "OmniUpstreamError";
+      }
+    };
+    exports.OmniNetworkError = class extends Error {
+      constructor(cause) {
+        super(`Network error: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "OmniNetworkError";
+        if (cause instanceof Error) this.cause = cause;
+      }
+    };
+  }
+});
+
+// src/client.ts
+init_errors();
+var DEFAULT_BASE_URL = "https://api.omnizoek.nl";
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_DELAY_MS = 500;
+var DEFAULT_TIMEOUT_MS = 2e4;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var HttpClient = class {
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+  async get(path, params) {
+    const url = new URL(this.baseUrl + path);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    let attempt = 0;
+    while (true) {
+      let response;
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        response = await fetch(url.toString(), {
+          method: "GET",
+          headers: {
+            "X-API-Key": this.apiKey,
+            "Accept": "application/json",
+            "User-Agent": "@omnizoek/sdk/0.1.0"
+          },
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+      } catch (err) {
+        throw new exports.OmniNetworkError(err);
+      }
+      if (response.status === 429 && attempt < this.maxRetries) {
+        const retryAfter = Number(response.headers.get("Retry-After") ?? 0);
+        const delay = retryAfter > 0 ? retryAfter * 1e3 : this.retryDelayMs * Math.pow(2, attempt);
+        attempt++;
+        await sleep(delay);
+        continue;
+      }
+      if (!response.ok) {
+        await this._throwFromResponse(response);
+      }
+      return response.json();
+    }
+  }
+  async post(path, body) {
+    let response;
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+      response = await fetch(this.baseUrl + path, {
+        method: "POST",
+        headers: {
+          "X-API-Key": this.apiKey,
+          "Accept": "application/json",
+          "Content-Type": "application/json",
+          "User-Agent": "@omnizoek/sdk/0.1.0"
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+    } catch (err) {
+      throw new exports.OmniNetworkError(err);
+    }
+    if (!response.ok) {
+      await this._throwFromResponse(response);
+    }
+    return response.json();
+  }
+  async delete(path) {
+    let response;
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+      response = await fetch(this.baseUrl + path, {
+        method: "DELETE",
+        headers: {
+          "X-API-Key": this.apiKey,
+          "User-Agent": "@omnizoek/sdk/0.1.0"
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+    } catch (err) {
+      throw new exports.OmniNetworkError(err);
+    }
+    if (!response.ok) {
+      await this._throwFromResponse(response);
+    }
+  }
+  async _throwFromResponse(response) {
+    let detail = response.statusText;
+    try {
+      const body = await response.json();
+      detail = body.detail ?? body.error ?? detail;
+    } catch {
+    }
+    switch (response.status) {
+      case 401:
+        throw new exports.OmniAuthError(detail);
+      case 404:
+        throw new exports.OmniNotFoundError(detail);
+      case 422:
+        throw new exports.OmniValidationError(detail);
+      case 429:
+        throw new exports.OmniRateLimitError(0);
+      case 503:
+        throw new exports.OmniUpstreamError(detail);
+      default: {
+        const { OmniError: OmniError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+        throw new OmniError2(
+          `API error ${response.status}: ${detail}`,
+          response.status,
+          "api_error",
+          detail
+        );
+      }
+    }
+  }
+};
+
+// src/geo.ts
+var GeoModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Enrich a Dutch address with BAG data, coordinates, neighbourhood
+   * statistics, energy labels and more.
+   *
+   * @example
+   * const result = await omni.geo.enrichAddress({ postcode: "1012LG", houseNumber: 1 });
+   */
+  async enrichAddress(params) {
+    return this.http.get("/v1/geo/enrich-address", {
+      postcode: params.postcode,
+      house_number: params.houseNumber
+    });
+  }
+};
+
+// src/finance.ts
+var FinanceModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Resolve an IBAN to its BIC/SWIFT code and bank name.
+   *
+   * @example
+   * const result = await omni.finance.ibanToBic({ iban: "NL91ABNA0417164300" });
+   */
+  async ibanToBic(params) {
+    return this.http.get("/v1/finance/iban-to-bic", {
+      iban: params.iban
+    });
+  }
+  /**
+   * Verify a Dutch BTW (VAT) number via the EU VIES service and return
+   * company metadata.
+   *
+   * @example
+   * const result = await omni.finance.vatVerify({ vatNumber: "NL123456782B01" });
+   */
+  async vatVerify(params) {
+    return this.http.get("/v1/finance/vat-verify", {
+      vat_number: params.vatNumber
+    });
+  }
+};
+
+// src/compliance.ts
+var ComplianceModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Validate a Dutch BSN or IBAN number using checksum algorithms.
+   *
+   * @example
+   * const result = await omni.compliance.validateFinance({ type: "iban", number: "NL91ABNA0417164300" });
+   */
+  async validateFinance(params) {
+    return this.http.get("/v1/compliance/validate-finance", {
+      type: params.type,
+      number: params.number
+    });
+  }
+};
+
+// src/hr.ts
+var HrModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Look up the current Dutch statutory minimum wage for a given age.
+   *
+   * @example
+   * const result = await omni.hr.minimumWage({ age: 21 });
+   */
+  async minimumWage(params) {
+    return this.http.get("/v1/hr/minimum-wage", {
+      age: params.age
+    });
+  }
+  /**
+   * Check whether a given date is a public holiday (and get the applicable
+   * surcharge multiplier for a given industry).
+   *
+   * @example
+   * const result = await omni.hr.holidaySurcharge({ date: "2024-12-25", industry: "retail" });
+   */
+  async holidaySurcharge(params) {
+    return this.http.get("/v1/hr/holiday-surcharge", {
+      date: params.date,
+      industry: params.industry
+    });
+  }
+};
+
+// src/realEstate.ts
+var RealEstateModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Retrieve the official EP-Online energy label for a Dutch address.
+   *
+   * @example
+   * const result = await omni.realEstate.energyLabel({ postcode: "1012LG", houseNumber: 1 });
+   */
+  async energyLabel(params) {
+    return this.http.get("/v1/real-estate/energy-label", {
+      postcode: params.postcode,
+      house_number: params.houseNumber
+    });
+  }
+};
+
+// src/logistics.ts
+var LogisticsModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Check whether a vehicle (by Dutch licence plate / kenteken) is allowed
+   * in a zero-emission zone (ZE-zone).
+   *
+   * @example
+   * const result = await omni.logistics.emissionZone({ kenteken: "AB123C" });
+   */
+  async emissionZone(params) {
+    return this.http.get("/v1/logistics/emission-zone", {
+      kenteken: params.kenteken
+    });
+  }
+  /**
+   * Retrieve current and upcoming NS train disruptions, optionally filtered
+   * by station code.
+   *
+   * @example
+   * const result = await omni.logistics.transitDisruptions({ stationCode: "ASD" });
+   */
+  async transitDisruptions(params) {
+    return this.http.get("/v1/logistics/transit-disruptions", {
+      station_code: params?.stationCode
+    });
+  }
+};
+
+// src/energy.ts
+var EnergyModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Retrieve the current Dutch electricity grid congestion status for a
+   * given postal code / province.
+   *
+   * @example
+   * const result = await omni.energy.gridTrigger();
+   * const result = await omni.energy.gridTrigger({ countryCode: "NL" });
+   */
+  async gridTrigger(params) {
+    return this.http.get("/v1/energy/grid-trigger", {
+      country_code: params?.countryCode
+    });
+  }
+};
+
+// src/webhooks.ts
+var WebhooksModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Register a new outbound webhook. OmniZoek will POST to `url` whenever
+   * any of the specified `events` fire.
+   *
+   * @example
+   * const wh = await omni.webhooks.register({
+   *   url: "https://example.com/hook",
+   *   events: ["quota.warning"],
+   * });
+   */
+  async register(params) {
+    return this.http.post("/v1/webhooks", {
+      url: params.url,
+      events: params.events
+    });
+  }
+  /**
+   * List all registered webhooks for this API key.
+   *
+   * @example
+   * const { webhooks } = await omni.webhooks.list();
+   */
+  async list() {
+    return this.http.get("/v1/webhooks");
+  }
+  /**
+   * Delete a webhook by its ID.
+   *
+   * @example
+   * await omni.webhooks.delete("wh_abc123");
+   */
+  async delete(webhookId) {
+    return this.http.delete(`/v1/webhooks/${encodeURIComponent(webhookId)}`);
+  }
+};
+
+// src/OmniClient.ts
+var OmniClient = class {
+  constructor(options) {
+    const http = new HttpClient(options);
+    this.geo = new GeoModule(http);
+    this.finance = new FinanceModule(http);
+    this.compliance = new ComplianceModule(http);
+    this.hr = new HrModule(http);
+    this.realEstate = new RealEstateModule(http);
+    this.logistics = new LogisticsModule(http);
+    this.energy = new EnergyModule(http);
+    this.webhooks = new WebhooksModule(http);
+  }
+};
+
+// src/index.ts
+init_errors();
+
+exports.OmniClient = OmniClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map