@resira/sdk 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# @resira/sdk
+
+TypeScript SDK for the Resira public reservation API.
+
+## Installation
+
+```bash
+npm install @resira/sdk
+```
+
+## Quick start
+
+```typescript
+import { Resira } from "@resira/sdk";
+
+const resira = new Resira({
+  apiKey: "resira_live_your_api_key_here",
+});
+```
+
+## API reference
+
+### `new Resira(config)`
+
+| Option           | Type       | Default                     | Description                                       |
+| ---------------- | ---------- | --------------------------- | ------------------------------------------------- |
+| `apiKey`         | `string`   | **(required)**              | API key (`resira_live_…`)                         |
+| `baseUrl`        | `string`   | `https://api.resira.io`     | Base URL of the API                               |
+| `maxRetries`     | `number`   | `3`                         | Max retry attempts for 429 / 5xx                  |
+| `retryBaseDelay` | `number`   | `500`                       | Base delay (ms) for exponential backoff            |
+| `fetch`          | `function` | `globalThis.fetch`          | Custom fetch implementation                       |
+
+---
+
+### `resira.getAvailability(resourceId, params?)`
+
+Query availability for a resource.
+
+**Property (date-based):**
+```typescript
+const avail = await resira.getAvailability("prop-1", {
+  startDate: "2026-07-01",
+  endDate: "2026-07-07",
+});
+
+console.log(avail.dates?.available);     // true
+console.log(avail.dates?.totalPrice);    // 85000 (cents)
+console.log(avail.dates?.blockedDates);  // ["2026-07-15", …]
+```
+
+**Restaurant (time-slot):**
+```typescript
+const avail = await resira.getAvailability("table-5", {
+  date: "2026-07-01",
+  partySize: 4,
+});
+
+for (const slot of avail.timeSlots ?? []) {
+  console.log(`${slot.start} → ${slot.end}: ${slot.remaining} seats`);
+}
+```
+
+---
+
+### `resira.createReservation(payload, options?)`
+
+Create a reservation. The `resourceId` is included in the request body.
+An `Idempotency-Key` header is automatically generated to prevent
+duplicate bookings on retries.
+
+```typescript
+const { reservation } = await resira.createReservation({
+  resourceId: "prop-1",
+  guestName: "Jane Doe",
+  guestEmail: "jane@example.com",
+  startDate: "2026-07-01",
+  endDate: "2026-07-07",
+  partySize: 3,
+});
+
+console.log(reservation.id);        // "uuid-…"
+console.log(reservation.status);    // "pending"
+console.log(reservation.totalPrice);// 85000
+```
+
+**Custom idempotency key:**
+```typescript
+const { reservation } = await resira.createReservation(
+  payload,
+  { idempotencyKey: "form-submit-abc123" },
+);
+```
+
+---
+
+### `resira.listReservations(resourceId, params?)`
+
+List reservations (paginated).
+
+```typescript
+const page = await resira.listReservations("prop-1", {
+  status: "confirmed",
+  page: 1,
+  limit: 50,
+});
+
+console.log(page.data);       // Reservation[]
+console.log(page.total);      // 142
+console.log(page.totalPages); // 3
+```
+
+---
+
+### `resira.getReservation(resourceId, reservationId)`
+
+Get a single reservation by ID.
+
+```typescript
+const { reservation } = await resira.getReservation("prop-1", "res-uuid");
+```
+
+---
+
+## Error handling
+
+All errors extend `ResiraError`. Use `instanceof` to discriminate:
+
+```typescript
+import {
+  Resira,
+  ResiraApiError,
+  ResiraRateLimitError,
+  ResiraNetworkError,
+} from "@resira/sdk";
+
+try {
+  await resira.createReservation(payload);
+} catch (error) {
+  if (error instanceof ResiraRateLimitError) {
+    // 429 — SDK already retried `maxRetries` times
+    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+  } else if (error instanceof ResiraApiError) {
+    // 4xx / 5xx
+    console.log(`${error.status}: ${error.message}`);
+    console.log(error.retryable); // true for 5xx
+  } else if (error instanceof ResiraNetworkError) {
+    // DNS / TLS / offline
+    console.log("Network error:", error.message);
+  }
+}
+```
+
+| Error class            | When                          | Retried automatically? |
+| ---------------------- | ----------------------------- | ---------------------- |
+| `ResiraRateLimitError` | 429 Too Many Requests         | ✓ (respects Retry-After) |
+| `ResiraApiError`       | Any non-2xx                   | ✓ for 5xx only         |
+| `ResiraNetworkError`   | fetch failed (DNS, offline…)  | ✓                      |
+
+---
+
+## Retry behaviour
+
+The SDK retries failed requests with **exponential backoff + jitter**:
+
+- **Attempt 1**: 0 – 500 ms
+- **Attempt 2**: 0 – 1 000 ms
+- **Attempt 3**: 0 – 2 000 ms
+
+For 429 responses, the `Retry-After` header value is used as a minimum delay.
+
+Idempotency keys ensure that retried POST requests don't create
+duplicate reservations.
+
+---
+
+## Requirements
+
+- Node.js ≥ 18 (uses native `fetch`)
+- No runtime dependencies