@omnizoek/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,410 @@
+/**
+ * client.ts — Core HTTP client with automatic retry and error mapping.
+ */
+interface OmniClientOptions {
+    /** Your OmniZoek API key (omni_live_… or omni_test_…) */
+    apiKey: string;
+    /** Override the base URL — useful for testing. Default: https://api.omnizoek.nl */
+    baseUrl?: string;
+    /** Max retries on 429 rate-limit responses. Default: 3 */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff. Default: 500 */
+    retryDelayMs?: number;
+    /** Request timeout in ms. Default: 20000 */
+    timeoutMs?: number;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly timeoutMs;
+    constructor(options: OmniClientOptions);
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    delete(path: string): Promise<void>;
+    private _throwFromResponse;
+}
+
+interface AddressEnrichParams {
+    postcode: string;
+    houseNumber: string;
+    /** Include EP-Online energy label (default: true) */
+    energy?: boolean;
+}
+interface AddressEnrichResponse {
+    street: string;
+    house_number: string;
+    house_letter: string | null;
+    house_addition: string | null;
+    postcode: string;
+    city: string;
+    municipality: string | null;
+    province: string | null;
+    lat: number | null;
+    lon: number | null;
+    bag_id: string;
+    surface_m2: number | null;
+    building_year: number | null;
+    usage_function: string | null;
+    status: string | null;
+    energy_label: string | null;
+    energy_label_registered: string | null;
+    energy_label_valid_until: string | null;
+    energy_label_calculation_type: string | null;
+}
+interface IbanToBicParams {
+    iban: string;
+}
+interface IbanToBicResponse {
+    iban: string;
+    bic: string;
+    bank_name: string;
+    country_code: string;
+}
+interface VatVerifyParams {
+    countryCode: string;
+    vatNumber: string;
+}
+interface VatVerifyResponse {
+    valid: boolean;
+    status: string;
+    country_code: string;
+    vat_number: string;
+    company_name: string | null;
+    address: string | null;
+    checked_at: string;
+}
+type FinanceValidationType = "bsn" | "iban";
+interface ValidateFinanceParams {
+    type: FinanceValidationType;
+    number: string;
+}
+interface FinanceValidationResponse {
+    valid: boolean;
+    type: string;
+    number: string;
+    algorithm: string;
+    detail: string;
+}
+interface MinimumWageParams {
+    age: number;
+    /** Reference date YYYY-MM-DD (defaults to today) */
+    date?: string;
+}
+interface MinimumWageResponse {
+    age: number;
+    date: string;
+    hourly_eur: number;
+    daily_eur: number;
+    monthly_eur: number;
+    law_reference: string;
+    note: string | null;
+}
+interface HolidaySurchargeParams {
+    date: string;
+    industry: string;
+}
+interface HolidaySurchargeResponse {
+    date: string;
+    is_holiday: boolean;
+    holiday_name: string | null;
+    industry: string;
+    surcharge_multiplier: number;
+    surcharge_basis: string;
+    disclaimer: string;
+}
+interface EnergyLabelParams {
+    postcode: string;
+    houseNumber: string;
+}
+interface EnergyLabelResponse {
+    bag_id: string;
+    postcode: string;
+    house_number: string;
+    energy_label: string;
+    label_class: string;
+    calculation_type: string | null;
+    registered_at: string | null;
+    valid_until: string | null;
+}
+interface EmissionZoneParams {
+    kenteken: string;
+}
+interface EmissionZoneResponse {
+    kenteken: string;
+    ze_compliant: boolean;
+    fuel_types: string[];
+    euro_standard: string | null;
+    emission_category: string | null;
+    vehicle_category: string | null;
+    reason: string;
+    zones_checked: string[];
+}
+interface TransitDisruptionsParams {
+    stationCode: string;
+}
+interface TransitDisruptionItem {
+    type: string;
+    title: string;
+    cause: string | null;
+    start: string | null;
+    end: string | null;
+    impact: string | null;
+}
+interface TransitDisruptionsResponse {
+    station_code: string;
+    disruptions: TransitDisruptionItem[];
+    retrieved_at: string;
+}
+interface GridTriggerParams {
+    /** ISO alpha-2 country code (default: "NL") */
+    countryCode?: string;
+}
+interface GridTriggerResponse {
+    country_code: string;
+    current_price_eur_mwh: number;
+    negative_price: boolean;
+    trigger: boolean;
+    period_start: string | null;
+    period_end: string | null;
+    retrieved_at: string;
+}
+type OmniWebhookEvent = "key.created" | "key.test_created" | "quota.warning" | "quota.exceeded";
+interface RegisterWebhookParams {
+    url: string;
+    events: OmniWebhookEvent[];
+}
+interface WebhookCreatedResponse {
+    webhook_id: string;
+    url: string;
+    events: OmniWebhookEvent[];
+    /** Shown once — store securely for HMAC signature verification */
+    secret: string;
+    note: string;
+}
+interface WebhookSummary {
+    webhook_id: string;
+    url: string;
+    events: OmniWebhookEvent[];
+    active: boolean;
+    created_at: string;
+    last_fired_at: string | null;
+    failure_count: number;
+}
+interface WebhookListResponse {
+    webhooks: WebhookSummary[];
+}
+
+declare class GeoModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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 });
+     */
+    enrichAddress(params: AddressEnrichParams): Promise<AddressEnrichResponse>;
+}
+
+declare class FinanceModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Resolve an IBAN to its BIC/SWIFT code and bank name.
+     *
+     * @example
+     * const result = await omni.finance.ibanToBic({ iban: "NL91ABNA0417164300" });
+     */
+    ibanToBic(params: IbanToBicParams): Promise<IbanToBicResponse>;
+    /**
+     * Verify a Dutch BTW (VAT) number via the EU VIES service and return
+     * company metadata.
+     *
+     * @example
+     * const result = await omni.finance.vatVerify({ vatNumber: "NL123456782B01" });
+     */
+    vatVerify(params: VatVerifyParams): Promise<VatVerifyResponse>;
+}
+
+declare class ComplianceModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Validate a Dutch BSN or IBAN number using checksum algorithms.
+     *
+     * @example
+     * const result = await omni.compliance.validateFinance({ type: "iban", number: "NL91ABNA0417164300" });
+     */
+    validateFinance(params: ValidateFinanceParams): Promise<FinanceValidationResponse>;
+}
+
+declare class HrModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Look up the current Dutch statutory minimum wage for a given age.
+     *
+     * @example
+     * const result = await omni.hr.minimumWage({ age: 21 });
+     */
+    minimumWage(params: MinimumWageParams): Promise<MinimumWageResponse>;
+    /**
+     * 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" });
+     */
+    holidaySurcharge(params: HolidaySurchargeParams): Promise<HolidaySurchargeResponse>;
+}
+
+declare class RealEstateModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Retrieve the official EP-Online energy label for a Dutch address.
+     *
+     * @example
+     * const result = await omni.realEstate.energyLabel({ postcode: "1012LG", houseNumber: 1 });
+     */
+    energyLabel(params: EnergyLabelParams): Promise<EnergyLabelResponse>;
+}
+
+declare class LogisticsModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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" });
+     */
+    emissionZone(params: EmissionZoneParams): Promise<EmissionZoneResponse>;
+    /**
+     * Retrieve current and upcoming NS train disruptions, optionally filtered
+     * by station code.
+     *
+     * @example
+     * const result = await omni.logistics.transitDisruptions({ stationCode: "ASD" });
+     */
+    transitDisruptions(params?: TransitDisruptionsParams): Promise<TransitDisruptionsResponse>;
+}
+
+declare class EnergyModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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" });
+     */
+    gridTrigger(params?: GridTriggerParams): Promise<GridTriggerResponse>;
+}
+
+declare class WebhooksModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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"],
+     * });
+     */
+    register(params: RegisterWebhookParams): Promise<WebhookCreatedResponse>;
+    /**
+     * List all registered webhooks for this API key.
+     *
+     * @example
+     * const { webhooks } = await omni.webhooks.list();
+     */
+    list(): Promise<WebhookListResponse>;
+    /**
+     * Delete a webhook by its ID.
+     *
+     * @example
+     * await omni.webhooks.delete("wh_abc123");
+     */
+    delete(webhookId: string): Promise<void>;
+}
+
+/**
+ * The main entry point for the OmniZoek SDK.
+ *
+ * @example
+ * ```ts
+ * import { OmniClient } from "@omnizoek/sdk";
+ *
+ * const omni = new OmniClient({ apiKey: "omni_live_…" });
+ *
+ * const address = await omni.geo.enrichAddress({ postcode: "1012LG", houseNumber: 1 });
+ * const wage    = await omni.hr.minimumWage({ age: 21 });
+ * ```
+ */
+declare class OmniClient {
+    /** Geographic address enrichment (BAG, CBS, energy labels) */
+    readonly geo: GeoModule;
+    /** Financial utilities (IBAN → BIC, VAT verification) */
+    readonly finance: FinanceModule;
+    /** Compliance checks (financial institution registers) */
+    readonly compliance: ComplianceModule;
+    /** HR calculations (minimum wage, holiday surcharge) */
+    readonly hr: HrModule;
+    /** Real-estate data (EP-Online energy labels) */
+    readonly realEstate: RealEstateModule;
+    /** Logistics (ZE-zones, NS disruptions) */
+    readonly logistics: LogisticsModule;
+    /** Energy (grid congestion triggers) */
+    readonly energy: EnergyModule;
+    /** Outbound webhooks (register, list, delete) */
+    readonly webhooks: WebhooksModule;
+    constructor(options: OmniClientOptions);
+}
+
+/**
+ * errors.ts — Typed error classes for the OmniZoek SDK.
+ */
+declare class OmniError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly detail: string;
+    constructor(message: string, status: number, code: string, detail: string);
+}
+/** 401 — API key missing or invalid. */
+declare class OmniAuthError extends OmniError {
+    constructor(detail: string);
+}
+/** 404 — Requested resource not found (address, label, etc.). */
+declare class OmniNotFoundError extends OmniError {
+    constructor(detail: string);
+}
+/** 422 — Request parameters failed validation. */
+declare class OmniValidationError extends OmniError {
+    constructor(detail: string);
+}
+/** 429 — Rate limit exceeded. Retried automatically by the client. */
+declare class OmniRateLimitError extends OmniError {
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+/** 503 — Upstream data source unavailable (BAG, EP-Online, RDW, etc.). */
+declare class OmniUpstreamError extends OmniError {
+    constructor(detail: string);
+}
+/** Network-level failure (DNS, timeout, no internet). */
+declare class OmniNetworkError extends Error {
+    readonly cause?: Error;
+    constructor(cause: unknown);
+}
+
+export { type AddressEnrichParams, type AddressEnrichResponse, type EmissionZoneParams, type EmissionZoneResponse, type EnergyLabelParams, type EnergyLabelResponse, type FinanceValidationResponse, type GridTriggerParams, type GridTriggerResponse, type HolidaySurchargeParams, type HolidaySurchargeResponse, type IbanToBicParams, type IbanToBicResponse, type MinimumWageParams, type MinimumWageResponse, OmniAuthError, OmniClient, type OmniClientOptions, OmniError, OmniNetworkError, OmniNotFoundError, OmniRateLimitError, OmniUpstreamError, OmniValidationError, type RegisterWebhookParams, type TransitDisruptionsParams, type TransitDisruptionsResponse, type ValidateFinanceParams, type VatVerifyParams, type VatVerifyResponse, type WebhookCreatedResponse, type WebhookListResponse, type WebhookSummary };