@resira/sdk 0.2.3 → 0.2.6

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable SDK and public API tracking updates are documented here.
+
+## 0.2.6
+
+- Updated SDK routing to ignore ambient host-app env API overrides by default.
+- Kept explicit `baseUrl` and `baseUrls` support for integrator-controlled routing.
+- Added DOM libs to the SDK package tsconfig so standalone typechecking passes cleanly.
+
+## 0.2.5
+
+- Added weighted-origin session stickiness so a browser session stays pinned to the same API origin instead of re-randomizing on every request.
+- Added lightweight client-side routing telemetry helpers for monitoring origin assignments during rollout.
+
+## 0.2.3
+
+- Current workspace release for the public reservation API package.
+- Tracks the typed payment intent, payment confirmation, promo-code validation, product catalog, and product-availability flows exposed by the SDK.
+- Keeps the SDK aligned with the current `v1/public` endpoints plus reservation creation via `v2/api/reservations`.
+
+## 0.2.1
+
+- Published package update after the initial TypeScript SDK rollout.
+- Stabilized the package metadata for the public reservation API client.
+
+## 0.2.0
+
+- Introduced the first public TypeScript SDK for Resira reservations.
+- Added typed availability, reservation creation, reservation lookup, and retry-aware error handling.
+
+## 0.1.1
+
+- Internal follow-up release used to align the early SDK package with the UI package work.
+
+## 0.1.0
+
+- Initial SDK package scaffold.

package/README.md

@@ -1,16 +1,18 @@
-# @resira/sdk v0.2.0
+# @resira/sdk v0.2.6
 
 TypeScript SDK for the Resira public reservation API.
 
+Version history lives in [CHANGELOG.md](./CHANGELOG.md).
+
 ## Installation
 
 ```bash
-npm install @resira/sdk@0.2.0
+npm install @resira/sdk@0.2.6
 ```
 
 ## Quick start
 
-```typescript
+```ts
 import { Resira } from "@resira/sdk";
 
 const resira = new Resira({
@@ -18,57 +20,115 @@ const resira = new Resira({
 });
 ```
 
-## API reference
+## Client config
 
-### `new Resira(config)`
+```ts
+const resira = new Resira({
+  apiKey: "resira_live_your_api_key_here",
+  maxRetries: 3,
+  retryBaseDelay: 500,
+  // Optional explicit overrides:
+  // baseUrl: "https://your-api.example.com",
+  // baseUrls: [
+  //   { url: "https://origin-a.example.com", weight: 1 },
+  //   { url: "https://origin-b.example.com", weight: 1 },
+  // ],
+});
+```
 
-| 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                       |
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | required | Public Resira API key |
+| `baseUrl` | `string` | unset | Pin all SDK requests to one origin |
+| `baseUrls` | `Array<string \| { url: string; weight?: number }>` | unset | Explicit client-side routing override |
+| `maxRetries` | `number` | `3` | Retry attempts for 429 and 5xx responses |
+| `retryBaseDelay` | `number` | `500` | Base exponential backoff delay in ms |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation |
 
----
+## Routing behavior
 
-### `resira.getAvailability(resourceId, params?)`
+- The SDK keeps a browser session sticky to the selected origin.
+- Ambient host-app env vars such as `NEXT_PUBLIC_API_URL` are ignored.
+- Only explicit SDK config via `baseUrl` or `baseUrls` overrides the built-in production defaults.
+- In development, the SDK defaults to `http://localhost:3001`.
+
+## Core methods
 
-Query availability for a resource.
+### `resira.getConfig()`
+
+Fetch non-sensitive public property config such as Stripe publishable key, deposit percentage, currency, and branding.
+
+```ts
+const config = await resira.getConfig();
+console.log(config.stripePublishableKey);
+```
+
+### `resira.validatePromoCode(code)`
+
+```ts
+const promo = await resira.validatePromoCode("SUMMER20");
+if (promo.valid) {
+  console.log(promo.discountType, promo.discountValue);
+}
+```
 
-**Property (date-based):**
-```typescript
-const avail = await resira.getAvailability("prop-1", {
+### `resira.getAvailability(resourceId, params?)`
+
+```ts
+const availability = 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", {
+```ts
+const slots = 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.listResources()`
+
+```ts
+const { resources } = await resira.listResources();
 ```
 
----
+### `resira.listProducts()`
+
+```ts
+const { products } = await resira.listProducts();
+```
+
+### `resira.createPaymentIntent(payload, options?)`
+
+```ts
+const paymentIntent = await resira.createPaymentIntent({
+  productId: "prod-123",
+  resourceId: "res-456",
+  partySize: 2,
+  startDate: "2026-07-01",
+  startTime: "2026-07-01T10:00:00Z",
+  endTime: "2026-07-01T11:00:00Z",
+  guestName: "Jane Doe",
+  guestEmail: "jane@example.com",
+});
+```
+
+### `resira.confirmPayment(payload)`
+
+```ts
+const confirmation = await resira.confirmPayment({
+  paymentIntentId: "pi_xxx",
+  reservationId: "res_123",
+});
+```
 
 ### `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.
+Creates a reservation via the public booking flow. An idempotency key is automatically generated unless you pass one explicitly.
 
-```typescript
+```ts
 const { reservation } = await resira.createReservation({
   resourceId: "prop-1",
   guestName: "Jane Doe",
@@ -77,103 +137,59 @@ const { reservation } = await resira.createReservation({
   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
+```ts
 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");
+```ts
+const result = await resira.getReservation("prop-1", "res-uuid");
 ```
 
----
-
 ## Error handling
 
-All errors extend `ResiraError`. Use `instanceof` to discriminate:
+All SDK errors extend `ResiraError`.
 
-```typescript
+```ts
 import {
-  Resira,
   ResiraApiError,
-  ResiraRateLimitError,
   ResiraNetworkError,
+  ResiraRateLimitError,
 } 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`);
+    console.log(error.retryAfter);
   } else if (error instanceof ResiraApiError) {
-    // 4xx / 5xx
-    console.log(`${error.status}: ${error.message}`);
-    console.log(error.retryable); // true for 5xx
+    console.log(error.status, error.message);
   } else if (error instanceof ResiraNetworkError) {
-    // DNS / TLS / offline
-    console.log("Network error:", error.message);
+    console.log(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.
-
----
+| Error class | Meaning |
+| --- | --- |
+| `ResiraRateLimitError` | 429 response after retry handling |
+| `ResiraApiError` | Non-2xx API response |
+| `ResiraNetworkError` | Network/DNS/TLS failure |
 
 ## Requirements
 
-- Node.js ≥ 18 (uses native `fetch`)
+- Node.js >= 18
 - No runtime dependencies
+
+## Release notes
+
+See [CHANGELOG.md](./CHANGELOG.md) for release-by-release details.

package/dist/index.cjs

@@ -40,8 +40,188 @@ var ResiraNetworkError = class extends ResiraError {
   }
 };
 
+// src/routing.ts
+var DEFAULT_LOCAL_BASE_URLS = [
+  { url: "http://localhost:3001", weight: 100 }
+];
+var DEFAULT_PRODUCTION_BASE_URLS = [
+  { url: "https://resira-api-sips-production.up.railway.app", weight: 50 },
+  { url: "https://api.resira.app", weight: 50 }
+];
+var STICKY_SELECTION_KEY = "resira_sdk_api_origin_sticky_v1";
+var ROUTING_STATS_KEY = "resira_sdk_api_routing_stats_v1";
+var stickySelectionCache = /* @__PURE__ */ new Map();
+function readEnv(name) {
+  if (typeof process === "undefined") return void 0;
+  return process.env?.[name];
+}
+function isBrowser() {
+  return typeof window !== "undefined";
+}
+function getStorage(type) {
+  if (!isBrowser()) return null;
+  try {
+    return type === "session" ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function getBaseUrlSignature(baseUrls) {
+  return baseUrls.map((entry) => `${entry.url}|${entry.weight}`).join(",");
+}
+function pickWeightedBaseUrl(baseUrls) {
+  const totalWeight = baseUrls.reduce((sum, entry) => sum + entry.weight, 0);
+  if (totalWeight <= 0) {
+    return DEFAULT_PRODUCTION_BASE_URLS[0];
+  }
+  let cursor = Math.random() * totalWeight;
+  for (const entry of baseUrls) {
+    cursor -= entry.weight;
+    if (cursor < 0) {
+      return entry;
+    }
+  }
+  return baseUrls[baseUrls.length - 1] ?? DEFAULT_PRODUCTION_BASE_URLS[0];
+}
+function ensureAnalyticsQueue() {
+  if (!isBrowser()) return null;
+  const analyticsWindow = window;
+  if (!analyticsWindow.va) {
+    analyticsWindow.va = (...params) => {
+      analyticsWindow.vaq = analyticsWindow.vaq || [];
+      analyticsWindow.vaq.push(params);
+    };
+  }
+  return analyticsWindow;
+}
+function readStickySelection(signature) {
+  const cached = stickySelectionCache.get(signature);
+  if (cached) return cached;
+  const storage = getStorage("session");
+  const raw = storage?.getItem(STICKY_SELECTION_KEY);
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed?.signature || !parsed?.url || parsed.signature !== signature) {
+      return null;
+    }
+    stickySelectionCache.set(signature, parsed);
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function persistStickySelection(signature, url) {
+  const selection = {
+    signature,
+    url,
+    assignedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  stickySelectionCache.set(signature, selection);
+  getStorage("session")?.setItem(STICKY_SELECTION_KEY, JSON.stringify(selection));
+}
+function recordRoutingStats(signature, entry) {
+  const storage = getStorage("local");
+  if (!storage) return;
+  let stats = {};
+  try {
+    stats = JSON.parse(storage.getItem(ROUTING_STATS_KEY) ?? "{}");
+  } catch {
+    stats = {};
+  }
+  const current = stats[signature] ?? {
+    lastAssignedAt: "",
+    lastOrigin: "",
+    selections: 0,
+    origins: {}
+  };
+  current.lastAssignedAt = (/* @__PURE__ */ new Date()).toISOString();
+  current.lastOrigin = entry.url;
+  current.selections += 1;
+  current.origins[entry.url] = (current.origins[entry.url] ?? 0) + 1;
+  stats[signature] = current;
+  storage.setItem(ROUTING_STATS_KEY, JSON.stringify(stats));
+}
+function emitRoutingSelection(entry, signature, totalWeight) {
+  if (!isBrowser()) return;
+  const detail = {
+    source: "sdk",
+    strategy: "session-sticky",
+    originHost: new URL(entry.url).host,
+    originUrl: entry.url,
+    originWeight: entry.weight,
+    totalWeight,
+    signature
+  };
+  ensureAnalyticsQueue()?.va?.("event", {
+    name: "api_origin_selected",
+    data: detail
+  });
+  window.dispatchEvent(
+    new CustomEvent("resira:api-origin-selected", {
+      detail
+    })
+  );
+  const debugEnabled = /^(1|true)$/i.test(
+    readEnv("NEXT_PUBLIC_RESIRA_API_ROUTING_DEBUG") ?? readEnv("NEXT_PUBLIC_API_ROUTING_DEBUG") ?? ""
+  );
+  if (debugEnabled) {
+    console.info("[resira-sdk] sticky origin selected", detail);
+  }
+}
+function normalizeUrl(url) {
+  return url.trim().replace(/\/+$/, "");
+}
+function isPositiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function toResolvedBaseUrl(value) {
+  if (typeof value === "string") {
+    const url2 = normalizeUrl(value);
+    return url2 ? { url: url2, weight: 1 } : null;
+  }
+  const url = normalizeUrl(value.url);
+  if (!url) return null;
+  return {
+    url,
+    weight: isPositiveNumber(value.weight) ? value.weight : 1
+  };
+}
+function resolveBaseUrls(config) {
+  if (config.baseUrl) {
+    return [{ url: normalizeUrl(config.baseUrl), weight: 100 }];
+  }
+  if (config.baseUrls?.length) {
+    const explicit = config.baseUrls.flatMap((entry) => {
+      const resolved = toResolvedBaseUrl(entry);
+      return resolved ? [resolved] : [];
+    });
+    if (explicit.length > 0) return explicit;
+  }
+  if (readEnv("NODE_ENV") === "development") {
+    return DEFAULT_LOCAL_BASE_URLS;
+  }
+  return DEFAULT_PRODUCTION_BASE_URLS;
+}
+function pickBaseUrl(baseUrls) {
+  const signature = getBaseUrlSignature(baseUrls);
+  const stickySelection = readStickySelection(signature);
+  const stickyEntry = stickySelection ? baseUrls.find((entry) => entry.url === stickySelection.url) : null;
+  if (stickyEntry) {
+    return stickyEntry.url;
+  }
+  const selectedEntry = pickWeightedBaseUrl(baseUrls);
+  persistStickySelection(signature, selectedEntry.url);
+  recordRoutingStats(signature, selectedEntry);
+  emitRoutingSelection(
+    selectedEntry,
+    signature,
+    baseUrls.reduce((sum, entry) => sum + entry.weight, 0)
+  );
+  return selectedEntry.url;
+}
+
 // src/client.ts
-var DEFAULT_BASE_URL = "https://api-res-production.up.railway.app";
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_RETRY_BASE_DELAY = 500;
 var API_PREFIX = "/v1/public";
@@ -96,7 +276,7 @@ var Resira = class {
       throw new Error("Resira: apiKey is required");
     }
     this.apiKey = config.apiKey;
-    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.baseUrls = resolveBaseUrls(config);
     this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.retryBaseDelay = config.retryBaseDelay ?? DEFAULT_RETRY_BASE_DELAY;
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
@@ -249,7 +429,7 @@ var Resira = class {
       throw new Error("resourceId is required for createReservation");
     }
     const idempotencyKey = options?.idempotencyKey ?? uuid();
-    const url = `${this.baseUrl}/v2/api/reservations`;
+    const url = `${this.getBaseUrl()}/v2/api/reservations`;
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
       Accept: "application/json",
@@ -467,7 +647,7 @@ var Resira = class {
    * - Parses error bodies and throws typed error classes.
    */
   async request(method, path, body, extraHeaders) {
-    const url = `${this.baseUrl}${API_PREFIX}${path}`;
+    const url = `${this.getBaseUrl()}${API_PREFIX}${path}`;
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
       Accept: "application/json",
@@ -545,6 +725,9 @@ var Resira = class {
     }
     return jittered;
   }
+  getBaseUrl() {
+    return pickBaseUrl(this.baseUrls);
+  }
 };
 
 exports.Resira = Resira;