@atzentis/booking-sdk 0.0.0 → 0.1.1

package/README.md

@@ -0,0 +1,89 @@
+# @atzentis/booking-sdk
+
+[![npm](https://img.shields.io/npm/v/@atzentis/booking-sdk)](https://www.npmjs.com/package/@atzentis/booking-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENCE.md)
+
+Core TypeScript client for [atzentis.io](https://atzentis.io) — the Atzentis Hospitality Platform. Framework-agnostic with zero runtime dependencies.
+
+## Install
+
+```bash
+npm install @atzentis/booking-sdk
+```
+
+## Quick Start
+
+```typescript
+import { BookingClient } from '@atzentis/booking-sdk';
+
+const booking = new BookingClient({
+  baseUrl: 'https://api.atzentis.io',
+  apiKey: 'your-api-key',
+});
+
+// Properties
+const properties = await booking.properties.list();
+
+// Availability
+const availability = await booking.availability.check({
+  propertyId: 'prop_123',
+  checkIn: '2026-06-01',
+  checkOut: '2026-06-05',
+});
+
+// Bookings
+const result = await booking.bookings.create({
+  propertyId: 'prop_123',
+  spaceId: 'space_456',
+  guestId: 'guest_789',
+  checkIn: '2026-06-01',
+  checkOut: '2026-06-05',
+});
+```
+
+## Services
+
+Wraps all 205 endpoints of the atzentis.io v4.0 API across 28 services:
+
+| Category | Services |
+| --- | --- |
+| Inventory | Properties, Spaces |
+| Booking | Availability, Bookings, Groups |
+| Guest | Profiles, Intelligence, ID Scanning |
+| Finance | Folios, Payments, POS Bridge |
+| Operations | Housekeeping, Night Audit, Staff, Supply, Tasks |
+| Rate | Plans, Periods, Restrictions |
+| Distribution | Channels, Mappings, Sync, iCal |
+| AI | Concierge, Revenue |
+| Compliance | Fiscal (myDATA, TSE) |
+| Platform | Webhooks, Settings, Notifications, SSE |
+
+## Booking Verticals
+
+| Vertical | Space Types | Granularity |
+| --- | --- | --- |
+| **Stays** (nights) | room, sunbed, parking | night, day, month |
+| **Tables** (reservations) | table, locker | hour |
+| **Services** (appointments) | service, meeting_room, desk | hour |
+
+## Features
+
+- ESM and CJS dual output
+- Strict TypeScript with full type coverage
+- Zod validation schemas for all request/response types
+- Tree-shakeable exports
+- Zero runtime dependencies
+
+## React
+
+For React hooks and components, see [`@atzentis/booking-react`](https://www.npmjs.com/package/@atzentis/booking-react).
+
+## Links
+
+- [atzentis.io](https://atzentis.io) — Hospitality Platform
+- [API Documentation](https://docs.atzentis.com)
+- [GitHub](https://github.com/atzentis/atzentis-booking-sdk)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -3,6 +3,9 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -16,16 +19,546 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  VERSION: () => VERSION
+  AuthenticationError: () => AuthenticationError,
+  BookingClient: () => BookingClient,
+  BookingError: () => BookingError,
+  ConflictError: () => ConflictError,
+  ForbiddenError: () => ForbiddenError,
+  HttpClient: () => HttpClient,
+  NotFoundError: () => NotFoundError,
+  PaymentError: () => PaymentError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  TimeoutError: () => TimeoutError,
+  VERSION: () => VERSION,
+  ValidationError: () => ValidationError,
+  bookingClientConfigSchema: () => bookingClientConfigSchema,
+  createErrorFromResponse: () => createErrorFromResponse,
+  firstPage: () => firstPage,
+  paginate: () => paginate
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "0.0.0";
+
+// src/config.ts
+var import_zod = require("zod");
+var bookingClientConfigSchema = import_zod.z.object({
+  apiKey: import_zod.z.string().min(1, "apiKey is required"),
+  baseUrl: import_zod.z.string().url().default("https://api.atzentis.io"),
+  tenantId: import_zod.z.string().min(1).optional(),
+  timeout: import_zod.z.number().int().positive().default(3e4),
+  retry: import_zod.z.object({
+    maxRetries: import_zod.z.number().int().min(0).max(10).default(3),
+    baseDelay: import_zod.z.number().int().positive().default(500)
+  }).optional(),
+  debug: import_zod.z.boolean().default(false),
+  logger: import_zod.z.object({
+    debug: import_zod.z.custom(
+      (val) => typeof val === "function"
+    )
+  }).optional()
+});
+
+// src/errors.ts
+var BookingError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "BookingError";
+    this.code = options.code;
+    this.status = options.status;
+    this.details = options.details ?? {};
+  }
+};
+var AuthenticationError = class extends BookingError {
+  constructor(message = "Authentication failed: invalid or missing API key", details) {
+    super(message, { code: "AUTHENTICATION_ERROR", status: 401, details });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "AuthenticationError";
+  }
+};
+var PaymentError = class extends BookingError {
+  constructor(message = "Payment required or payment failed", details) {
+    super(message, { code: "PAYMENT_ERROR", status: 402, details });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "PaymentError";
+  }
+};
+var ForbiddenError = class extends BookingError {
+  constructor(message = "Insufficient permissions to perform this action", details) {
+    super(message, { code: "FORBIDDEN_ERROR", status: 403, details });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "ForbiddenError";
+  }
+};
+var NotFoundError = class extends BookingError {
+  constructor(message = "The requested resource was not found", details) {
+    super(message, { code: "NOT_FOUND_ERROR", status: 404, details });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "NotFoundError";
+  }
+};
+var ConflictError = class extends BookingError {
+  constructor(message = "Resource conflict \u2014 the booking may already exist", details) {
+    super(message, { code: "CONFLICT_ERROR", status: 409, details });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "ConflictError";
+  }
+};
+var ValidationError = class extends BookingError {
+  constructor(message = "Request validation failed", fieldErrors = {}, details) {
+    super(message, { code: "VALIDATION_ERROR", status: 422, details });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "ValidationError";
+    this.fieldErrors = fieldErrors;
+  }
+};
+var RateLimitError = class extends BookingError {
+  constructor(message = "Rate limit exceeded", retryAfter = 60) {
+    super(message, { code: "RATE_LIMIT_ERROR", status: 429 });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ServerError = class extends BookingError {
+  constructor(message = "An unexpected server error occurred", status = 500, details) {
+    super(message, { code: "SERVER_ERROR", status, details });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "ServerError";
+  }
+};
+var TimeoutError = class extends BookingError {
+  constructor(message = "The request timed out") {
+    super(message, { code: "TIMEOUT_ERROR" });
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.name = "TimeoutError";
+  }
+};
+function parseRetryAfter(header) {
+  if (!header) return 60;
+  const seconds = Number.parseInt(header, 10);
+  if (Number.isFinite(seconds) && seconds > 0) return seconds;
+  const date = new Date(header);
+  if (!Number.isNaN(date.getTime())) {
+    return Math.max(0, Math.round((date.getTime() - Date.now()) / 1e3));
+  }
+  return 60;
+}
+function extractBody(body) {
+  if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+    return body;
+  }
+  return {};
+}
+function extractMessage(body, fallback) {
+  if (typeof body.message === "string" && body.message.length > 0) {
+    return body.message;
+  }
+  return fallback;
+}
+function parseFieldErrors(errors) {
+  if (typeof errors !== "object" || errors === null || Array.isArray(errors)) {
+    return {};
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(errors)) {
+    if (Array.isArray(value)) {
+      result[key] = value.map(String);
+    } else if (typeof value === "string") {
+      result[key] = [value];
+    }
+  }
+  return result;
+}
+function createErrorFromResponse(response, body, retryAfterHeader) {
+  const bodyObj = extractBody(body);
+  const status = response.status;
+  switch (status) {
+    case 401:
+      return new AuthenticationError(
+        extractMessage(bodyObj, "Authentication failed: invalid or missing API key"),
+        bodyObj
+      );
+    case 402:
+      return new PaymentError(
+        extractMessage(bodyObj, "Payment required or payment failed"),
+        bodyObj
+      );
+    case 403:
+      return new ForbiddenError(
+        extractMessage(bodyObj, "Insufficient permissions to perform this action"),
+        bodyObj
+      );
+    case 404:
+      return new NotFoundError(
+        extractMessage(bodyObj, "The requested resource was not found"),
+        bodyObj
+      );
+    case 409:
+      return new ConflictError(extractMessage(bodyObj, "Resource conflict"), bodyObj);
+    case 422:
+      return new ValidationError(
+        extractMessage(bodyObj, "Request validation failed"),
+        parseFieldErrors(bodyObj.errors),
+        bodyObj
+      );
+    case 429:
+      return new RateLimitError(
+        extractMessage(bodyObj, "Rate limit exceeded"),
+        parseRetryAfter(retryAfterHeader ?? null)
+      );
+    default:
+      if (status >= 500) {
+        return new ServerError(
+          extractMessage(bodyObj, "An unexpected server error occurred"),
+          status,
+          bodyObj
+        );
+      }
+      return new BookingError(extractMessage(bodyObj, `HTTP ${status} error`), {
+        code: "HTTP_ERROR",
+        status,
+        details: bodyObj
+      });
+  }
+}
+
+// src/http.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([500, 502, 503, 504]);
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  baseDelay: 500,
+  retryOnMethods: ["GET", "DELETE"]
+};
+function parseRetryAfterHeader(header) {
+  if (!header) return 1;
+  const seconds = Number.parseInt(header, 10);
+  if (Number.isNaN(seconds) || seconds < 0) return 1;
+  return seconds;
+}
+function createDefaultLogger() {
+  return {
+    debug(message, ...args) {
+      console.debug(message, ...args);
+    }
+  };
+}
+function redactHeaders(headers) {
+  const result = { ...headers };
+  if (result.Authorization) {
+    result.Authorization = "Bearer ***";
+  }
+  return result;
+}
+var _apiKey, _tenantId, _retryConfig, _timeout, _debug, _logger;
+var HttpClient = class {
+  constructor(options) {
+    __privateAdd(this, _apiKey);
+    __privateAdd(this, _tenantId);
+    __privateAdd(this, _retryConfig);
+    __privateAdd(this, _timeout);
+    __privateAdd(this, _debug);
+    __privateAdd(this, _logger);
+    this.baseUrl = options.baseUrl;
+    this.fetchFn = options.fetch ?? globalThis.fetch;
+    this.defaultHeaders = { ...options.defaultHeaders };
+    __privateSet(this, _apiKey, options.apiKey);
+    __privateSet(this, _tenantId, options.tenantId);
+    __privateSet(this, _retryConfig, {
+      ...DEFAULT_RETRY_CONFIG,
+      ...options.retryConfig
+    });
+    __privateSet(this, _timeout, options.timeout ?? 3e4);
+    __privateSet(this, _debug, options.debug ?? false);
+    __privateSet(this, _logger, options.logger ?? createDefaultLogger());
+  }
+  async request(method, path, options) {
+    if (!__privateGet(this, _apiKey)) {
+      throw new Error("BookingSDK: apiKey is required but was not provided");
+    }
+    const url = this.buildUrl(path, options?.query);
+    const headers = this.buildHeaders(options?.headers);
+    if (options?.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    headers.Authorization = `Bearer ${__privateGet(this, _apiKey)}`;
+    if (__privateGet(this, _tenantId)) {
+      headers["X-Tenant-ID"] = __privateGet(this, _tenantId);
+    }
+    const init = {
+      method,
+      headers
+    };
+    if (options?.body !== void 0) {
+      init.body = JSON.stringify(options.body);
+    }
+    const effectiveRetry = {
+      maxRetries: options?.retry?.maxRetries ?? __privateGet(this, _retryConfig).maxRetries,
+      baseDelay: options?.retry?.baseDelay ?? __privateGet(this, _retryConfig).baseDelay,
+      retryOnMethods: __privateGet(this, _retryConfig).retryOnMethods,
+      force: options?.retry?.force ?? false,
+      maxRetryAfter: __privateGet(this, _retryConfig).maxRetryAfter ?? 60
+    };
+    if (__privateGet(this, _debug)) {
+      __privateGet(this, _logger).debug(`[BookingSDK] --> ${method} ${url}`, {
+        headers: redactHeaders(headers),
+        ...options?.body ? { body: JSON.stringify(options.body).slice(0, 200) } : {}
+      });
+    }
+    const timeoutMs = options?.timeout ?? __privateGet(this, _timeout);
+    const startTime = Date.now();
+    let lastError;
+    let wasRateLimited = false;
+    for (let attempt = 0; attempt <= effectiveRetry.maxRetries; attempt++) {
+      if (attempt > 0 && !wasRateLimited) {
+        await this.sleep(this.calculateDelay(attempt - 1, effectiveRetry.baseDelay));
+      }
+      wasRateLimited = false;
+      let timedOut = false;
+      const controller = new AbortController();
+      const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, timeoutMs);
+      if (options?.signal) {
+        if (options.signal.aborted) {
+          clearTimeout(timer);
+          controller.abort();
+        } else {
+          options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+        }
+      }
+      try {
+        const response = await this.fetchFn(url, {
+          ...init,
+          signal: controller.signal
+        });
+        if (__privateGet(this, _debug)) {
+          const elapsed = Date.now() - startTime;
+          __privateGet(this, _logger).debug(`[BookingSDK] <-- ${response.status} (${elapsed}ms)`);
+        }
+        if (!response.ok) {
+          if (response.status === 429 && this.shouldRetry(method, effectiveRetry, attempt)) {
+            const retryAfterHeader2 = response.headers.get("Retry-After");
+            const retryAfterSeconds = parseRetryAfterHeader(retryAfterHeader2);
+            const cappedSeconds = Math.min(retryAfterSeconds, effectiveRetry.maxRetryAfter);
+            if (__privateGet(this, _debug)) {
+              __privateGet(this, _logger).debug(
+                `[BookingSDK] retry attempt ${attempt + 1}/${effectiveRetry.maxRetries} in ${cappedSeconds * 1e3}ms (reason: 429 Rate Limited)`
+              );
+            }
+            await this.sleep(cappedSeconds * 1e3);
+            wasRateLimited = true;
+            lastError = response;
+            continue;
+          }
+          if (RETRYABLE_STATUSES.has(response.status) && this.shouldRetry(method, effectiveRetry, attempt)) {
+            if (__privateGet(this, _debug)) {
+              const delay = this.calculateDelay(attempt, effectiveRetry.baseDelay);
+              __privateGet(this, _logger).debug(
+                `[BookingSDK] retry attempt ${attempt + 1}/${effectiveRetry.maxRetries} in ${delay}ms (reason: ${response.status})`
+              );
+            }
+            lastError = response;
+            continue;
+          }
+          const body = await response.json().catch(() => ({}));
+          const retryAfterHeader = response.headers.get("Retry-After");
+          throw createErrorFromResponse(response, body, retryAfterHeader);
+        }
+        if (__privateGet(this, _debug)) {
+          const text = await response.clone().text().catch(() => "");
+          if (text) {
+            __privateGet(this, _logger).debug(`[BookingSDK] body preview: ${text.slice(0, 500)}`);
+          }
+        }
+        return response.json();
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          if (timedOut) {
+            throw new TimeoutError(`Request timed out after ${timeoutMs}ms`);
+          }
+          throw error;
+        }
+        if (!(error instanceof TypeError)) {
+          throw error;
+        }
+        if (!this.shouldRetry(method, effectiveRetry, attempt)) {
+          throw error;
+        }
+        lastError = error;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    if (lastError instanceof Response) {
+      const body = await lastError.json().catch(() => ({}));
+      const retryAfterHeader = lastError.headers.get("Retry-After");
+      throw createErrorFromResponse(lastError, body, retryAfterHeader);
+    }
+    throw lastError;
+  }
+  async get(path, options) {
+    return this.request("GET", path, options);
+  }
+  async post(path, options) {
+    return this.request("POST", path, options);
+  }
+  async put(path, options) {
+    return this.request("PUT", path, options);
+  }
+  async patch(path, options) {
+    return this.request("PATCH", path, options);
+  }
+  async delete(path, options) {
+    return this.request("DELETE", path, options);
+  }
+  setApiKey(key) {
+    __privateSet(this, _apiKey, key);
+  }
+  setTenantId(id) {
+    __privateSet(this, _tenantId, id);
+  }
+  setDefaultHeader(key, value) {
+    this.defaultHeaders[key] = value;
+  }
+  removeDefaultHeader(key) {
+    delete this.defaultHeaders[key];
+  }
+  shouldRetry(method, config, attempt) {
+    if (attempt >= config.maxRetries) return false;
+    if (config.force) return true;
+    return config.retryOnMethods.includes(method);
+  }
+  calculateDelay(attempt, baseDelay) {
+    return baseDelay * 2 ** attempt + Math.floor(Math.random() * 100);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  buildUrl(path, query) {
+    const cleanPath = path.startsWith("/") ? path.slice(1) : path;
+    let url = `${this.baseUrl}/${cleanPath}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value === null || value === void 0) {
+          continue;
+        }
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            params.append(key, item);
+          }
+        } else {
+          params.set(key, String(value));
+        }
+      }
+      const qs = params.toString();
+      if (qs) {
+        url = `${url}?${qs}`;
+      }
+    }
+    return url;
+  }
+  buildHeaders(perRequestHeaders) {
+    return {
+      Accept: "application/json",
+      ...this.defaultHeaders,
+      ...perRequestHeaders
+    };
+  }
+};
+_apiKey = new WeakMap();
+_tenantId = new WeakMap();
+_retryConfig = new WeakMap();
+_timeout = new WeakMap();
+_debug = new WeakMap();
+_logger = new WeakMap();
+
+// src/client.ts
+var BookingClient = class {
+  constructor(config) {
+    const validated = bookingClientConfigSchema.parse(config);
+    this.httpClient = new HttpClient({
+      baseUrl: validated.baseUrl,
+      apiKey: validated.apiKey,
+      tenantId: validated.tenantId,
+      timeout: validated.timeout,
+      retryConfig: validated.retry ? {
+        maxRetries: validated.retry.maxRetries,
+        baseDelay: validated.retry.baseDelay
+      } : void 0,
+      debug: validated.debug,
+      logger: validated.logger
+    });
+  }
+  setApiKey(key) {
+    if (!key || key.trim().length === 0) {
+      throw new Error("apiKey must be a non-empty string");
+    }
+    this.httpClient.setApiKey(key);
+  }
+  setTenantId(id) {
+    if (!id || id.trim().length === 0) {
+      throw new Error("tenantId must be a non-empty string");
+    }
+    this.httpClient.setTenantId(id);
+  }
+};
+
+// src/pagination.ts
+function paginate(fetcher, options) {
+  return {
+    [Symbol.asyncIterator]() {
+      let cursor = options?.cursor;
+      let done = false;
+      return {
+        async next() {
+          if (done) return { value: void 0, done: true };
+          const result = await fetcher({ ...options ?? {}, cursor });
+          if (!result.hasMore || result.cursor === null) {
+            done = true;
+          } else {
+            cursor = result.cursor;
+          }
+          return { value: result.data, done: false };
+        }
+      };
+    }
+  };
+}
+async function firstPage(fetcher, options) {
+  return fetcher({ ...options ?? {} });
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  VERSION
+  AuthenticationError,
+  BookingClient,
+  BookingError,
+  ConflictError,
+  ForbiddenError,
+  HttpClient,
+  NotFoundError,
+  PaymentError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  VERSION,
+  ValidationError,
+  bookingClientConfigSchema,
+  createErrorFromResponse,
+  firstPage,
+  paginate
 });
 //# sourceMappingURL=index.cjs.map