@holidays-rest/sdk-ts 1.0.0

package/README.md

@@ -0,0 +1,213 @@
+# holidays.rest TypeScript SDK
+
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/32fc7ef7bedd4819a7b34a6ec409888d)](https://app.codacy.com/gh/holidays-rest/sdk-ts/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/32fc7ef7bedd4819a7b34a6ec409888d)](https://app.codacy.com/gh/holidays-rest/sdk-ts/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
+
+Official TypeScript SDK for the [holidays.rest](https://www.holidays.rest) API.
+
+## Requirements
+
+- Node.js ≥ 18 (uses native `fetch`)
+- TypeScript 5+ (for consumers using TypeScript)
+- Zero runtime dependencies
+
+## Installation
+
+```bash
+npm install holidays.rest
+```
+
+## Quick Start
+
+```ts
+import { HolidaysClient } from "holidays.rest";
+
+const client = new HolidaysClient({ apiKey: "YOUR_API_KEY" });
+
+const holidays = await client.getHolidays({ country: "US", year: 2024 });
+holidays.forEach((h) => console.log(`${h.date} — ${h.name.en}`));
+```
+
+Get an API key at [holidays.rest/dashboard](https://www.holidays.rest/dashboard).
+
+---
+
+## API
+
+### `new HolidaysClient(options)`
+
+```ts
+interface ClientOptions {
+  apiKey:   string;   // required — Bearer token from dashboard
+  baseUrl?: string;   // optional — override for testing
+}
+```
+
+---
+
+### `getHolidays(params)` → `Promise<Holiday[]>`
+
+```ts
+interface HolidaysParams {
+  country:   string;                          // required — ISO 3166 alpha-2 (e.g. "US")
+  year:      number | string;                 // required — e.g. 2024
+
+  month?:    number | string;                 // optional — 1–12
+  day?:      number | string;                 // optional — 1–31
+  type?:     string | string[];               // "religious" | "national" | "local"
+  religion?: number | number[];               // religion codes 1–11
+  region?:   string | string[];               // subdivision codes from getCountry()
+  lang?:     string | string[];               // language codes from getLanguages()
+  response?: "json" | "xml" | "yaml" | "csv"; // default: "json"
+}
+```
+
+```ts
+// All US holidays in 2024
+await client.getHolidays({ country: "US", year: 2024 });
+
+// National holidays only
+await client.getHolidays({ country: "DE", year: 2024, type: "national" });
+
+// Multiple types
+await client.getHolidays({ country: "TR", year: 2024, type: ["national", "religious"] });
+
+// Filter by month and day
+await client.getHolidays({ country: "GB", year: 2024, month: 12, day: 25 });
+
+// Specific region
+await client.getHolidays({ country: "US", year: 2024, region: "US-CA" });
+
+// Multiple regions
+await client.getHolidays({ country: "US", year: 2024, region: ["US-CA", "US-NY"] });
+```
+
+---
+
+### `getCountries()` → `Promise<Country[]>`
+
+```ts
+const countries = await client.getCountries();
+countries.forEach((c) => console.log(`${c.alpha2} — ${c.name}`));
+```
+
+---
+
+### `getCountry(countryCode)` → `Promise<Country>`
+
+Returns country details including subdivision codes usable as `region` filters.
+
+```ts
+const us = await client.getCountry("US");
+us.subdivisions?.forEach((s) => console.log(`${s.code} — ${s.name}`));
+```
+
+---
+
+### `getLanguages()` → `Promise<Language[]>`
+
+```ts
+const languages = await client.getLanguages();
+```
+
+---
+
+## Types
+
+All request and response types are exported:
+
+```ts
+import type {
+  Holiday,
+  HolidayDay,
+  HolidayName,
+  Country,
+  Subdivision,
+  Language,
+  HolidaysParams,
+  ClientOptions,
+} from "holidays.rest";
+```
+
+```ts
+interface HolidayName {
+  [lang: string]: string; // e.g. { en: "New Year's Day", de: "Neujahr" }
+}
+
+interface HolidayDay {
+  actual:   string; // weekday the holiday falls on, e.g. "Thursday"
+  observed: string; // weekday legally observed, e.g. "Monday"
+}
+
+interface Holiday {
+  country_code: string;   // ISO 3166 alpha-2, e.g. "DE"
+  country_name: string;   // e.g. "Germany"
+  date:         string;   // ISO 8601, e.g. "2026-01-01"
+  name:         HolidayName;
+  isNational:   boolean;
+  isReligious:  boolean;
+  isLocal:      boolean;
+  isEstimate:   boolean;
+  day:          HolidayDay;
+  religion:     string;   // e.g. "Christianity" or ""
+  regions:      string[]; // subdivision codes, e.g. ["BW", "BY"], or []
+}
+
+interface Country {
+  name: string; alpha2: string; subdivisions?: Subdivision[];
+}
+
+interface Subdivision { code: string; name: string; }
+interface Language    { code: string; name: string; }
+```
+
+---
+
+## Error Handling
+
+Non-2xx responses throw `HolidaysApiError`:
+
+```ts
+import { HolidaysClient, HolidaysApiError } from "holidays.rest";
+
+try {
+  await client.getHolidays({ country: "US", year: 2024 });
+} catch (err) {
+  if (err instanceof HolidaysApiError) {
+    console.log(err.status);   // HTTP status code (number)
+    console.log(err.message);  // Error message (string)
+    console.log(err.body);     // Raw response body (unknown)
+  }
+}
+```
+
+| Status | Meaning             |
+|--------|---------------------|
+| 400    | Bad request         |
+| 401    | Invalid API key     |
+| 404    | Not found           |
+| 500    | Server error        |
+| 503    | Service unavailable |
+
+---
+
+## Building
+
+```bash
+npm run build       # outputs ESM + CJS + .d.ts to dist/
+npm run typecheck   # type-check without emitting
+```
+
+The build outputs:
+
+| File               | Format | Used by                     |
+|--------------------|--------|-----------------------------|
+| `dist/index.js`    | ESM    | `import` / bundlers         |
+| `dist/index.cjs`   | CJS    | `require()` / older tooling |
+| `dist/index.d.ts`  | Types  | TypeScript consumers        |
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,133 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HolidaysApiError: () => HolidaysApiError,
+  HolidaysClient: () => HolidaysClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var HolidaysApiError = class extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "HolidaysApiError";
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.holidays.rest/v1";
+function toCommaSeparated(value) {
+  return Array.isArray(value) ? value.join(",") : String(value);
+}
+function buildQuery(params) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    query.set(key, toCommaSeparated(value));
+  }
+  const qs = query.toString();
+  return qs ? `?${qs}` : "";
+}
+var HolidaysClient = class {
+  apiKey;
+  baseUrl;
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }) {
+    if (!apiKey) throw new Error("HolidaysClient: apiKey is required");
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  // ── internal ──────────────────────────────────────────────────────────────
+  async request(path, query = "") {
+    const url = `${this.baseUrl}${path}${query}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        Accept: "application/json"
+      }
+    });
+    let body;
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      body = await response.json();
+    } else {
+      body = await response.text();
+    }
+    if (!response.ok) {
+      const message = typeof body === "object" && body !== null && "message" in body && typeof body.message === "string" ? body.message : response.statusText;
+      throw new HolidaysApiError(message, response.status, body);
+    }
+    return body;
+  }
+  // ── public API ────────────────────────────────────────────────────────────
+  /**
+   * Fetches public holidays matching the given parameters.
+   *
+   * @example
+   * await client.getHolidays({ country: "US", year: 2024 });
+   * await client.getHolidays({ country: "TR", year: 2024, type: ["national", "religious"] });
+   */
+  async getHolidays(params) {
+    if (!params.country) throw new Error("getHolidays: country is required");
+    if (!params.year) throw new Error("getHolidays: year is required");
+    const query = buildQuery({
+      country: params.country,
+      year: params.year,
+      month: params.month,
+      day: params.day,
+      type: params.type,
+      religion: params.religion,
+      region: params.region,
+      lang: params.lang,
+      response: params.response
+    });
+    return this.request("/holidays", query);
+  }
+  /** Returns all supported countries. */
+  async getCountries() {
+    return this.request("/countries");
+  }
+  /**
+   * Returns details for one country, including subdivision codes
+   * usable as `region` filters in {@link getHolidays}.
+   *
+   * @param countryCode ISO 3166 alpha-2 code, e.g. `"US"`.
+   */
+  async getCountry(countryCode) {
+    if (!countryCode) throw new Error("getCountry: countryCode is required");
+    return this.request(`/country/${encodeURIComponent(countryCode)}`);
+  }
+  /** Returns all supported language codes. */
+  async getLanguages() {
+    return this.request("/languages");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HolidaysApiError,
+  HolidaysClient
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/client.ts"],"sourcesContent":["export { HolidaysClient } from \"./client.js\";\nexport { HolidaysApiError } from \"./errors.js\";\nexport type {\n  ClientOptions,\n  Country,\n  Holiday,\n  HolidayDay,\n  HolidayName,\n  HolidaysParams,\n  Language,\n  Subdivision,\n} from \"./types.js\";\n","export class HolidaysApiError extends Error {\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(message: string, status: number, body: unknown) {\n    super(message);\n    this.name = \"HolidaysApiError\";\n    this.status = status;\n    this.body = body;\n  }\n}\n","import { HolidaysApiError } from \"./errors.js\";\nimport type {\n  ClientOptions,\n  Country,\n  Holiday,\n  HolidaysParams,\n  Language,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.holidays.rest/v1\";\n\nfunction toCommaSeparated(value: string | string[] | number | number[]): string {\n  return Array.isArray(value) ? value.join(\",\") : String(value);\n}\n\nfunction buildQuery(params: Record<string, string | number | string[] | number[] | undefined>): string {\n  const query = new URLSearchParams();\n\n  for (const [key, value] of Object.entries(params)) {\n    if (value === undefined || value === null) continue;\n    query.set(key, toCommaSeparated(value as string | string[] | number | number[]));\n  }\n\n  const qs = query.toString();\n  return qs ? `?${qs}` : \"\";\n}\n\nexport class HolidaysClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n\n  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }: ClientOptions) {\n    if (!apiKey) throw new Error(\"HolidaysClient: apiKey is required\");\n    this.apiKey = apiKey;\n    this.baseUrl = baseUrl.replace(/\\/$/, \"\");\n  }\n\n  // ── internal ──────────────────────────────────────────────────────────────\n\n  private async request<T>(path: string, query = \"\"): Promise<T> {\n    const url = `${this.baseUrl}${path}${query}`;\n\n    const response = await fetch(url, {\n      method: \"GET\",\n      headers: {\n        Authorization: `Bearer ${this.apiKey}`,\n        Accept: \"application/json\",\n      },\n    });\n\n    let body: unknown;\n    const contentType = response.headers.get(\"content-type\") ?? \"\";\n\n    if (contentType.includes(\"application/json\")) {\n      body = await response.json();\n    } else {\n      body = await response.text();\n    }\n\n    if (!response.ok) {\n      const message =\n        typeof body === \"object\" &&\n        body !== null &&\n        \"message\" in body &&\n        typeof (body as Record<string, unknown>).message === \"string\"\n          ? (body as { message: string }).message\n          : response.statusText;\n\n      throw new HolidaysApiError(message, response.status, body);\n    }\n\n    return body as T;\n  }\n\n  // ── public API ────────────────────────────────────────────────────────────\n\n  /**\n   * Fetches public holidays matching the given parameters.\n   *\n   * @example\n   * await client.getHolidays({ country: \"US\", year: 2024 });\n   * await client.getHolidays({ country: \"TR\", year: 2024, type: [\"national\", \"religious\"] });\n   */\n  async getHolidays(params: HolidaysParams): Promise<Holiday[]> {\n    if (!params.country) throw new Error(\"getHolidays: country is required\");\n    if (!params.year) throw new Error(\"getHolidays: year is required\");\n\n    const query = buildQuery({\n      country:  params.country,\n      year:     params.year,\n      month:    params.month,\n      day:      params.day,\n      type:     params.type,\n      religion: params.religion,\n      region:   params.region,\n      lang:     params.lang,\n      response: params.response,\n    });\n\n    return this.request<Holiday[]>(\"/holidays\", query);\n  }\n\n  /** Returns all supported countries. */\n  async getCountries(): Promise<Country[]> {\n    return this.request<Country[]>(\"/countries\");\n  }\n\n  /**\n   * Returns details for one country, including subdivision codes\n   * usable as `region` filters in {@link getHolidays}.\n   *\n   * @param countryCode ISO 3166 alpha-2 code, e.g. `\"US\"`.\n   */\n  async getCountry(countryCode: string): Promise<Country> {\n    if (!countryCode) throw new Error(\"getCountry: countryCode is required\");\n    return this.request<Country>(`/country/${encodeURIComponent(countryCode)}`);\n  }\n\n  /** Returns all supported language codes. */\n  async getLanguages(): Promise<Language[]> {\n    return this.request<Language[]>(\"/languages\");\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,111 @@
+/**
+ * Holiday name keyed by BCP 47 language code, e.g. `{ en: "New Year's Day", de: "Neujahr" }`.
+ * The `en` key is always present.
+ */
+interface HolidayName {
+    [lang: string]: string;
+}
+/** Actual and observed weekday names for a holiday date. */
+interface HolidayDay {
+    /** Weekday the holiday falls on, e.g. `"Thursday"`. */
+    actual: string;
+    /** Weekday the holiday is legally observed, e.g. `"Monday"` (for rolled-over holidays). */
+    observed: string;
+}
+interface Holiday {
+    /** ISO 3166 alpha-2 country code, e.g. `"DE"`. */
+    country_code: string;
+    /** Full country name, e.g. `"Germany"`. */
+    country_name: string;
+    /** ISO 8601 date string, e.g. `"2026-01-01"`. */
+    date: string;
+    /** Holiday name in one or more languages. */
+    name: HolidayName;
+    /** `true` when the holiday applies nationwide. */
+    isNational: boolean;
+    /** `true` when the holiday has a religious origin. */
+    isReligious: boolean;
+    /** `true` when the holiday applies to specific regions only. */
+    isLocal: boolean;
+    /** `true` when the date is an estimate (e.g. lunar-calendar holidays). */
+    isEstimate: boolean;
+    /** Actual and observed weekday information. */
+    day: HolidayDay;
+    /** Religion associated with the holiday, e.g. `"Christianity"`. Empty string when not applicable. */
+    religion: string;
+    /** Subdivision codes where the holiday applies, e.g. `["BW", "BY"]`. Empty array for nationwide holidays. */
+    regions: string[];
+}
+interface Subdivision {
+    code: string;
+    name: string;
+}
+interface Country {
+    name: string;
+    alpha2: string;
+    subdivisions?: Subdivision[];
+}
+interface Language {
+    code: string;
+    name: string;
+}
+interface HolidaysParams {
+    /** ISO 3166 alpha-2 country code, e.g. `"US"`. Required. */
+    country: string;
+    /** Four-digit year, e.g. `2024`. Required. */
+    year: number | string;
+    /** Month filter (1–12). Optional. */
+    month?: number | string;
+    /** Day filter (1–31). Optional. */
+    day?: number | string;
+    /** Holiday type(s): `"religious"` | `"national"` | `"local"`. Optional. */
+    type?: string | string[];
+    /** Religion code(s) 1–11. Optional. */
+    religion?: number | number[];
+    /** Region/subdivision code(s) — from `getCountry()`. Optional. */
+    region?: string | string[];
+    /** Language code(s) — from `getLanguages()`. Optional. */
+    lang?: string | string[];
+    /** Response format: `"json"` (default) | `"xml"` | `"yaml"` | `"csv"`. Optional. */
+    response?: "json" | "xml" | "yaml" | "csv";
+}
+interface ClientOptions {
+    /** Bearer token from https://www.holidays.rest/dashboard. Required. */
+    apiKey: string;
+    /** Override base URL. Useful for testing. */
+    baseUrl?: string;
+}
+
+declare class HolidaysClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor({ apiKey, baseUrl }: ClientOptions);
+    private request;
+    /**
+     * Fetches public holidays matching the given parameters.
+     *
+     * @example
+     * await client.getHolidays({ country: "US", year: 2024 });
+     * await client.getHolidays({ country: "TR", year: 2024, type: ["national", "religious"] });
+     */
+    getHolidays(params: HolidaysParams): Promise<Holiday[]>;
+    /** Returns all supported countries. */
+    getCountries(): Promise<Country[]>;
+    /**
+     * Returns details for one country, including subdivision codes
+     * usable as `region` filters in {@link getHolidays}.
+     *
+     * @param countryCode ISO 3166 alpha-2 code, e.g. `"US"`.
+     */
+    getCountry(countryCode: string): Promise<Country>;
+    /** Returns all supported language codes. */
+    getLanguages(): Promise<Language[]>;
+}
+
+declare class HolidaysApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+
+export { type ClientOptions, type Country, type Holiday, type HolidayDay, type HolidayName, HolidaysApiError, HolidaysClient, type HolidaysParams, type Language, type Subdivision };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Holiday name keyed by BCP 47 language code, e.g. `{ en: "New Year's Day", de: "Neujahr" }`.
+ * The `en` key is always present.
+ */
+interface HolidayName {
+    [lang: string]: string;
+}
+/** Actual and observed weekday names for a holiday date. */
+interface HolidayDay {
+    /** Weekday the holiday falls on, e.g. `"Thursday"`. */
+    actual: string;
+    /** Weekday the holiday is legally observed, e.g. `"Monday"` (for rolled-over holidays). */
+    observed: string;
+}
+interface Holiday {
+    /** ISO 3166 alpha-2 country code, e.g. `"DE"`. */
+    country_code: string;
+    /** Full country name, e.g. `"Germany"`. */
+    country_name: string;
+    /** ISO 8601 date string, e.g. `"2026-01-01"`. */
+    date: string;
+    /** Holiday name in one or more languages. */
+    name: HolidayName;
+    /** `true` when the holiday applies nationwide. */
+    isNational: boolean;
+    /** `true` when the holiday has a religious origin. */
+    isReligious: boolean;
+    /** `true` when the holiday applies to specific regions only. */
+    isLocal: boolean;
+    /** `true` when the date is an estimate (e.g. lunar-calendar holidays). */
+    isEstimate: boolean;
+    /** Actual and observed weekday information. */
+    day: HolidayDay;
+    /** Religion associated with the holiday, e.g. `"Christianity"`. Empty string when not applicable. */
+    religion: string;
+    /** Subdivision codes where the holiday applies, e.g. `["BW", "BY"]`. Empty array for nationwide holidays. */
+    regions: string[];
+}
+interface Subdivision {
+    code: string;
+    name: string;
+}
+interface Country {
+    name: string;
+    alpha2: string;
+    subdivisions?: Subdivision[];
+}
+interface Language {
+    code: string;
+    name: string;
+}
+interface HolidaysParams {
+    /** ISO 3166 alpha-2 country code, e.g. `"US"`. Required. */
+    country: string;
+    /** Four-digit year, e.g. `2024`. Required. */
+    year: number | string;
+    /** Month filter (1–12). Optional. */
+    month?: number | string;
+    /** Day filter (1–31). Optional. */
+    day?: number | string;
+    /** Holiday type(s): `"religious"` | `"national"` | `"local"`. Optional. */
+    type?: string | string[];
+    /** Religion code(s) 1–11. Optional. */
+    religion?: number | number[];
+    /** Region/subdivision code(s) — from `getCountry()`. Optional. */
+    region?: string | string[];
+    /** Language code(s) — from `getLanguages()`. Optional. */
+    lang?: string | string[];
+    /** Response format: `"json"` (default) | `"xml"` | `"yaml"` | `"csv"`. Optional. */
+    response?: "json" | "xml" | "yaml" | "csv";
+}
+interface ClientOptions {
+    /** Bearer token from https://www.holidays.rest/dashboard. Required. */
+    apiKey: string;
+    /** Override base URL. Useful for testing. */
+    baseUrl?: string;
+}
+
+declare class HolidaysClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor({ apiKey, baseUrl }: ClientOptions);
+    private request;
+    /**
+     * Fetches public holidays matching the given parameters.
+     *
+     * @example
+     * await client.getHolidays({ country: "US", year: 2024 });
+     * await client.getHolidays({ country: "TR", year: 2024, type: ["national", "religious"] });
+     */
+    getHolidays(params: HolidaysParams): Promise<Holiday[]>;
+    /** Returns all supported countries. */
+    getCountries(): Promise<Country[]>;
+    /**
+     * Returns details for one country, including subdivision codes
+     * usable as `region` filters in {@link getHolidays}.
+     *
+     * @param countryCode ISO 3166 alpha-2 code, e.g. `"US"`.
+     */
+    getCountry(countryCode: string): Promise<Country>;
+    /** Returns all supported language codes. */
+    getLanguages(): Promise<Language[]>;
+}
+
+declare class HolidaysApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+
+export { type ClientOptions, type Country, type Holiday, type HolidayDay, type HolidayName, HolidaysApiError, HolidaysClient, type HolidaysParams, type Language, type Subdivision };

package/dist/index.js

@@ -0,0 +1,105 @@
+// src/errors.ts
+var HolidaysApiError = class extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "HolidaysApiError";
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.holidays.rest/v1";
+function toCommaSeparated(value) {
+  return Array.isArray(value) ? value.join(",") : String(value);
+}
+function buildQuery(params) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    query.set(key, toCommaSeparated(value));
+  }
+  const qs = query.toString();
+  return qs ? `?${qs}` : "";
+}
+var HolidaysClient = class {
+  apiKey;
+  baseUrl;
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }) {
+    if (!apiKey) throw new Error("HolidaysClient: apiKey is required");
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  // ── internal ──────────────────────────────────────────────────────────────
+  async request(path, query = "") {
+    const url = `${this.baseUrl}${path}${query}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        Accept: "application/json"
+      }
+    });
+    let body;
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      body = await response.json();
+    } else {
+      body = await response.text();
+    }
+    if (!response.ok) {
+      const message = typeof body === "object" && body !== null && "message" in body && typeof body.message === "string" ? body.message : response.statusText;
+      throw new HolidaysApiError(message, response.status, body);
+    }
+    return body;
+  }
+  // ── public API ────────────────────────────────────────────────────────────
+  /**
+   * Fetches public holidays matching the given parameters.
+   *
+   * @example
+   * await client.getHolidays({ country: "US", year: 2024 });
+   * await client.getHolidays({ country: "TR", year: 2024, type: ["national", "religious"] });
+   */
+  async getHolidays(params) {
+    if (!params.country) throw new Error("getHolidays: country is required");
+    if (!params.year) throw new Error("getHolidays: year is required");
+    const query = buildQuery({
+      country: params.country,
+      year: params.year,
+      month: params.month,
+      day: params.day,
+      type: params.type,
+      religion: params.religion,
+      region: params.region,
+      lang: params.lang,
+      response: params.response
+    });
+    return this.request("/holidays", query);
+  }
+  /** Returns all supported countries. */
+  async getCountries() {
+    return this.request("/countries");
+  }
+  /**
+   * Returns details for one country, including subdivision codes
+   * usable as `region` filters in {@link getHolidays}.
+   *
+   * @param countryCode ISO 3166 alpha-2 code, e.g. `"US"`.
+   */
+  async getCountry(countryCode) {
+    if (!countryCode) throw new Error("getCountry: countryCode is required");
+    return this.request(`/country/${encodeURIComponent(countryCode)}`);
+  }
+  /** Returns all supported language codes. */
+  async getLanguages() {
+    return this.request("/languages");
+  }
+};
+export {
+  HolidaysApiError,
+  HolidaysClient
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"sourcesContent":["export class HolidaysApiError extends Error {\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(message: string, status: number, body: unknown) {\n    super(message);\n    this.name = \"HolidaysApiError\";\n    this.status = status;\n    this.body = body;\n  }\n}\n","import { HolidaysApiError } from \"./errors.js\";\nimport type {\n  ClientOptions,\n  Country,\n  Holiday,\n  HolidaysParams,\n  Language,\n} from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"https://api.holidays.rest/v1\";\n\nfunction toCommaSeparated(value: string | string[] | number | number[]): string {\n  return Array.isArray(value) ? value.join(\",\") : String(value);\n}\n\nfunction buildQuery(params: Record<string, string | number | string[] | number[] | undefined>): string {\n  const query = new URLSearchParams();\n\n  for (const [key, value] of Object.entries(params)) {\n    if (value === undefined || value === null) continue;\n    query.set(key, toCommaSeparated(value as string | string[] | number | number[]));\n  }\n\n  const qs = query.toString();\n  return qs ? `?${qs}` : \"\";\n}\n\nexport class HolidaysClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n\n  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }: ClientOptions) {\n    if (!apiKey) throw new Error(\"HolidaysClient: apiKey is required\");\n    this.apiKey = apiKey;\n    this.baseUrl = baseUrl.replace(/\\/$/, \"\");\n  }\n\n  // ── internal ──────────────────────────────────────────────────────────────\n\n  private async request<T>(path: string, query = \"\"): Promise<T> {\n    const url = `${this.baseUrl}${path}${query}`;\n\n    const response = await fetch(url, {\n      method: \"GET\",\n      headers: {\n        Authorization: `Bearer ${this.apiKey}`,\n        Accept: \"application/json\",\n      },\n    });\n\n    let body: unknown;\n    const contentType = response.headers.get(\"content-type\") ?? \"\";\n\n    if (contentType.includes(\"application/json\")) {\n      body = await response.json();\n    } else {\n      body = await response.text();\n    }\n\n    if (!response.ok) {\n      const message =\n        typeof body === \"object\" &&\n        body !== null &&\n        \"message\" in body &&\n        typeof (body as Record<string, unknown>).message === \"string\"\n          ? (body as { message: string }).message\n          : response.statusText;\n\n      throw new HolidaysApiError(message, response.status, body);\n    }\n\n    return body as T;\n  }\n\n  // ── public API ────────────────────────────────────────────────────────────\n\n  /**\n   * Fetches public holidays matching the given parameters.\n   *\n   * @example\n   * await client.getHolidays({ country: \"US\", year: 2024 });\n   * await client.getHolidays({ country: \"TR\", year: 2024, type: [\"national\", \"religious\"] });\n   */\n  async getHolidays(params: HolidaysParams): Promise<Holiday[]> {\n    if (!params.country) throw new Error(\"getHolidays: country is required\");\n    if (!params.year) throw new Error(\"getHolidays: year is required\");\n\n    const query = buildQuery({\n      country:  params.country,\n      year:     params.year,\n      month:    params.month,\n      day:      params.day,\n      type:     params.type,\n      religion: params.religion,\n      region:   params.region,\n      lang:     params.lang,\n      response: params.response,\n    });\n\n    return this.request<Holiday[]>(\"/holidays\", query);\n  }\n\n  /** Returns all supported countries. */\n  async getCountries(): Promise<Country[]> {\n    return this.request<Country[]>(\"/countries\");\n  }\n\n  /**\n   * Returns details for one country, including subdivision codes\n   * usable as `region` filters in {@link getHolidays}.\n   *\n   * @param countryCode ISO 3166 alpha-2 code, e.g. `\"US\"`.\n   */\n  async getCountry(countryCode: string): Promise<Country> {\n    if (!countryCode) throw new Error(\"getCountry: countryCode is required\");\n    return this.request<Country>(`/country/${encodeURIComponent(countryCode)}`);\n  }\n\n  /** Returns all supported language codes. */\n  async getLanguages(): Promise<Language[]> {\n    return this.request<Language[]>(\"/languages\");\n  }\n}\n"],"mappings":";AAAO,IAAM,mBAAN,cAA+B,MAAM;AAAA,EACjC;AAAA,EACA;AAAA,EAET,YAAY,SAAiB,QAAgB,MAAe;AAC1D,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,OAAO;AAAA,EACd;AACF;;;ACDA,IAAM,mBAAmB;AAEzB,SAAS,iBAAiB,OAAsD;AAC9E,SAAO,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,GAAG,IAAI,OAAO,KAAK;AAC9D;AAEA,SAAS,WAAW,QAAmF;AACrG,QAAM,QAAQ,IAAI,gBAAgB;AAElC,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,GAAG;AACjD,QAAI,UAAU,UAAa,UAAU,KAAM;AAC3C,UAAM,IAAI,KAAK,iBAAiB,KAA8C,CAAC;AAAA,EACjF;AAEA,QAAM,KAAK,MAAM,SAAS;AAC1B,SAAO,KAAK,IAAI,EAAE,KAAK;AACzB;AAEO,IAAM,iBAAN,MAAqB;AAAA,EACT;AAAA,EACA;AAAA,EAEjB,YAAY,EAAE,QAAQ,UAAU,iBAAiB,GAAkB;AACjE,QAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,oCAAoC;AACjE,SAAK,SAAS;AACd,SAAK,UAAU,QAAQ,QAAQ,OAAO,EAAE;AAAA,EAC1C;AAAA;AAAA,EAIA,MAAc,QAAW,MAAc,QAAQ,IAAgB;AAC7D,UAAM,MAAM,GAAG,KAAK,OAAO,GAAG,IAAI,GAAG,KAAK;AAE1C,UAAM,WAAW,MAAM,MAAM,KAAK;AAAA,MAChC,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,eAAe,UAAU,KAAK,MAAM;AAAA,QACpC,QAAQ;AAAA,MACV;AAAA,IACF,CAAC;AAED,QAAI;AACJ,UAAM,cAAc,SAAS,QAAQ,IAAI,cAAc,KAAK;AAE5D,QAAI,YAAY,SAAS,kBAAkB,GAAG;AAC5C,aAAO,MAAM,SAAS,KAAK;AAAA,IAC7B,OAAO;AACL,aAAO,MAAM,SAAS,KAAK;AAAA,IAC7B;AAEA,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,UACJ,OAAO,SAAS,YAChB,SAAS,QACT,aAAa,QACb,OAAQ,KAAiC,YAAY,WAChD,KAA6B,UAC9B,SAAS;AAEf,YAAM,IAAI,iBAAiB,SAAS,SAAS,QAAQ,IAAI;AAAA,IAC3D;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAM,YAAY,QAA4C;AAC5D,QAAI,CAAC,OAAO,QAAS,OAAM,IAAI,MAAM,kCAAkC;AACvE,QAAI,CAAC,OAAO,KAAM,OAAM,IAAI,MAAM,+BAA+B;AAEjE,UAAM,QAAQ,WAAW;AAAA,MACvB,SAAU,OAAO;AAAA,MACjB,MAAU,OAAO;AAAA,MACjB,OAAU,OAAO;AAAA,MACjB,KAAU,OAAO;AAAA,MACjB,MAAU,OAAO;AAAA,MACjB,UAAU,OAAO;AAAA,MACjB,QAAU,OAAO;AAAA,MACjB,MAAU,OAAO;AAAA,MACjB,UAAU,OAAO;AAAA,IACnB,CAAC;AAED,WAAO,KAAK,QAAmB,aAAa,KAAK;AAAA,EACnD;AAAA;AAAA,EAGA,MAAM,eAAmC;AACvC,WAAO,KAAK,QAAmB,YAAY;AAAA,EAC7C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,WAAW,aAAuC;AACtD,QAAI,CAAC,YAAa,OAAM,IAAI,MAAM,qCAAqC;AACvE,WAAO,KAAK,QAAiB,YAAY,mBAAmB,WAAW,CAAC,EAAE;AAAA,EAC5E;AAAA;AAAA,EAGA,MAAM,eAAoC;AACxC,WAAO,KAAK,QAAoB,YAAY;AAAA,EAC9C;AACF;","names":[]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@holidays-rest/sdk-ts",
+  "version": "1.0.0",
+  "description": "Official TypeScript SDK for the holidays.rest API",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "holidays",
+    "public-holidays",
+    "calendar",
+    "api",
+    "sdk",
+    "typescript"
+  ],
+  "author": "msdundar",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.4",
+    "tsup": "^8.0.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  }
+}