Node.js SDK

The @weatherit/node SDK wraps the WeatherIt API for partners building an API integration in Node.js. It handles authentication, retries, idempotency and error mapping, so your backend only has to decide what to do with each outcome.

• Package: @weatherit/node on npm
• Runtime: Node.js 18 or later, server-side only
• API reference: every SDK method maps to an endpoint in the API Reference

Install

npm install @weatherit/node

Quick start

import { WeatherIt } from '@weatherit/node';

const wi = new WeatherIt({ apiKey: process.env.WEATHERIT_API_KEY!, environment: 'sandbox' });

const { quote } = await wi.quotes.create({
  productName: 'Camping Adventure',
  experienceDetails: {
    name: 'Byron Bay Summer Camping', type: 'camping',
    location: { suburb: 'Byron Bay', state: 'NSW', country: 'AUS', coordinates: { latitude: -28.6436, longitude: 153.6125 } },
  },
  coverage: { startDate: '2026-12-15', endDate: '2026-12-18', exposureAmount: 1200 }, // whole-trip total
  customer: { email: '[email protected]', firstName: 'Jane', lastName: 'Smith' },
});

const option = quote!.pricing_options![0]!; // each option has its own quote_id

// 1. AUTHORISE the guest's card with your payment provider (do not capture yet).
// 2. Bind:
const outcome = await wi.quotes.purchase(option, { transactionId: authorisation.id, bookingReference: 'BK-1001' });

switch (outcome.status) {
  case 'bound':     /* capture the authorisation */ break;
  case 'not_bound': /* void it: this charge did not and will not bind a policy */ break;
  case 'unknown':   /* do nothing yet; later: wi.quotes.resolvePurchase(outcome) */ break;
}

API keys and environments

API keys are issued during onboarding. Start on Sandbox; a production key is issued once your integration has been tested.

❗

Your API key is a secret. The SDK refuses to run in a browser, and refuses a key that does not match its environment (for example, a wt_prod_ key with environment: 'sandbox').

Authorise, bind, then capture

The safe order for taking payment is: authorise the guest's card, bind the policy with purchase(), then capture or void the authorisation based on the outcome. This way a guest is never charged for a policy that was not issued.

purchase() never throws for a business outcome. It returns one of three statuses:

resolvePurchase() makes no purchase request. It checks whether the policy exists, and returns not_bound once 20 minutes have passed with no policy.

📘

Retries and idempotency. The SDK sends one X-Request-Id and a byte-identical body on every retry, and never has two requests in flight for the same key. If you retry a purchase yourself (for example from a job queue), pass the same idempotencyKey and the same body each time. After a not_bound outcome, never reuse that key: start a new purchase with a new key and a new authorisation.

Methods

Errors

Every method other than purchase() throws a WeatherItError on failure, or one of its subclasses: AuthError, ValidationError, NotFoundError, ConflictError, RateLimitError, ServiceError or ConnectionError.

• Branch on err.code, the stable public error class.
• err.originalCode carries the specific reason, for example DURATION_EXCEEDED.
• err.requestId identifies the request. Quote it when contacting support.

Input checks

By default the SDK normalises country (AU or Australia becomes AUS; NZ or New Zealand becomes NZL) and rejects locally only the requests the API is certain to refuse:

• more than 21 nights of cover
• less than 2 days' notice before the start date
• more than $1,000 or less than $1 of cover per day
• impossible dates or out-of-range coordinates

The API's answer is always final. Pass normalise: false to send requests unchanged.

Testing your integration

The SDK includes a Sandbox smoke test that creates a quote, binds it with a fake payment reference, looks the policy up by quote and by payment, and cancels it. It refuses to run against production.

import { WeatherIt } from '@weatherit/node';
import { runSandboxSmoke } from '@weatherit/node/testing';

const report = await runSandboxSmoke(new WeatherIt({ apiKey: sandboxKey, environment: 'sandbox' }));
console.log(report.ok, report.steps);

Versioning

The SDK follows semantic versioning, independent of the API. Release notes are in the package's changelog on npm. Release candidates are published under the next tag; npm install @weatherit/node always installs the latest stable release.