@travories/frontend-sdk 0.1.4 → 0.1.5

package/README.md

@@ -5,7 +5,7 @@
 [![types](https://img.shields.io/npm/types/@travories/frontend-sdk?logo=typescript&logoColor=white)](https://www.npmjs.com/package/@travories/frontend-sdk)
 [![license](https://img.shields.io/npm/l/@travories/frontend-sdk?color=brightgreen)](./LICENSE)
 
-> Official Travories SDK. Drop the full **package detail page** and **landing carousels** into any React app, or just use the API client to fetch packages on your own terms.
+> Official Travories SDK. Drop **landing carousels**, the full **package detail page**, the **agency profile page**, and a real **booking flow** into any React app — or just use the API client to fetch data on your own terms.
 
 ```bash
 npm install @travories/frontend-sdk
@@ -22,38 +22,30 @@ export default function Page({ slug }: { slug: string }) {
 }
 ```
 
-That's a complete, production-grade package detail page: gallery, itinerary with map, day-by-day routes, booking sidebar, host card. ~95 KB gzipped.
+That's a complete, production-grade package detail page: gallery, itinerary with map and per-day routes, booking sidebar, host card. ~100 KB gzipped, no Tailwind required in your app.
 
 ---
 
-## Features
-
-- **Framework-agnostic API client** — fetch packages, hosts, routes, home sections. Works in Node, browser, Next.js server components, edge runtimes.
-- **Drop-in pages** — `<PackageDetailView />` for detail, `<HomeSections />` for landing. One prop and you're done.
-- **Composable layouts** — `<HomeSectionsProvider>` + `<PackagesSection>` lets you interleave SDK sections with your own content (FAQs, banners, etc.), all sharing one fetch.
-- **Real maps** — Leaflet-powered map with per-day GeoJSON routes flown to on day change.
-- **Bundled styling** — Tailwind precompiled and scoped to `.tvr-package-detail`. No Tailwind required in your app, no class conflicts with your own.
-- **Full TypeScript types** — every prop, every API response shape, ergonomic union types.
-- **ESM + CJS + sourcemaps** — works with any bundler, any Node version ≥ 18.
-- **SSR-first** — pass `initialBundle` / `initialSections` to skip client fetches and render on the server.
-
----
-
-## Contents
+## Table of contents
 
 - [Install](#install)
 - [Quick start](#quick-start)
-  - [Detail page](#detail-page)
-  - [Landing carousels](#landing-carousels)
+  - [Package detail page](#package-detail-page)
+  - [Landing — all four carousels](#landing--all-four-carousels)
+  - [Landing — interleaved sections (FAQ between carousels)](#landing--interleaved-sections-faq-between-carousels)
+  - [Agency profile page](#agency-profile-page)
   - [Just the data](#just-the-data)
-- [Components](#components)
-- [Hooks](#hooks)
+- [Booking flow](#booking-flow)
+- [Components reference](#components-reference)
+- [Hooks reference](#hooks-reference)
 - [Client configuration](#client-configuration)
-- [SSR with Next.js](#ssr-with-nextjs)
-- [Composable landing layouts](#composable-landing-layouts)
+- [SSR with Next.js / Remix](#ssr-with-nextjs--remix)
 - [Styling](#styling)
-- [TypeScript](#typescript)
-- [API reference](#api-reference)
+- [TypeScript types](#typescript-types)
+- [API endpoints called](#api-endpoints-called)
+- [Edge cases & FAQ](#edge-cases--faq)
+- [Browser support](#browser-support)
+- [Versioning & releases](#versioning--releases)
 - [Support](#support)
 - [License](#license)
 
@@ -65,19 +57,27 @@ That's a complete, production-grade package detail page: gallery, itinerary with
 npm install @travories/frontend-sdk
 ```
 
-**Peer dependencies** (skip if you only use the API client):
+**Peer dependencies** (skip if you only use the API client / Node):
 
 ```bash
 npm install react react-dom
 ```
 
-Requires React 17+, Node 18+ (uses built-in `fetch`).
+| Requirement | Version |
+|---|---|
+| Node | ≥ 18 (uses built-in `fetch`) |
+| React | ≥ 17 |
+| TypeScript | optional but recommended ≥ 5 |
+
+`leaflet` and `react-leaflet` are runtime deps, included automatically when you install the SDK — needed for the itinerary map.
 
 ---
 
 ## Quick start
 
-### Detail page
+### Package detail page
+
+The all-in-one drop-in. Pass `client` + `slug` — the SDK fetches everything and renders.
 
 ```tsx
 import { TravoriesClient, PackageDetailView } from "@travories/frontend-sdk";
@@ -91,16 +91,23 @@ function PackagePage({ slug }: { slug: string }) {
       client={client}
       slug={slug}
       currency="USD"
-      onReserve={(pkg) => {
-        // hook your booking flow here
-        window.location.href = `/checkout/${pkg.slug}`;
+      onReserve={async ({ pkg, arrival, travelers }) => {
+        // see "Booking flow" section below for the canonical pattern
+        const { data: bookingId } = await client.bookings.initiate({
+          packageId: pkg.slug,
+          arrivalDate: arrival,
+          travelers,
+        });
+        window.location.href = `/checkout/${bookingId}`;
       }}
+      agencyHrefFor={(host) => `/agency/${host.slug}`}
+      openAgencyInNewTab
     />
   );
 }
 ```
 
-### Landing carousels
+### Landing — all four carousels
 
 ```tsx
 import { TravoriesClient, HomeSections } from "@travories/frontend-sdk";
@@ -112,7 +119,6 @@ function Landing() {
   return (
     <HomeSections
       client={client}
-      currency="USD"
       hrefFor={(pkg) => `/package/${pkg.slug}`}
       openInNewTab
     />
@@ -122,6 +128,55 @@ function Landing() {
 
 Renders the four canonical sections: **Popular**, **Trending Right Now**, **Top Rated**, **More to Explore**.
 
+### Landing — interleaved sections (FAQ between carousels)
+
+When you want SDK sections mixed with your own content (hero, FAQ, banners), wrap with `<HomeSectionsProvider>` and drop `<PackagesSection>` anywhere inside. **All sections share one fetch.**
+
+```tsx
+import {
+  TravoriesClient,
+  HomeSectionsProvider,
+  PackagesSection,
+} from "@travories/frontend-sdk";
+
+const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
+
+function Landing() {
+  return (
+    <HomeSectionsProvider client={client}>
+      <Hero />                                       {/* your own */}
+      <PackagesSection section="popular"  hrefFor={...} openInNewTab />
+      <PackagesSection section="trending" hrefFor={...} openInNewTab />
+      <FAQ />                                        {/* your own */}
+      <PackagesSection section="topRated" title="Editor's picks" />
+      <PackagesSection section="moreToExplore" />
+      <Newsletter />                                 {/* your own */}
+    </HomeSectionsProvider>
+  );
+}
+```
+
+Available section keys: `"popular" | "trending" | "topRated" | "moreToExplore"`.
+
+### Agency profile page
+
+```tsx
+import { TravoriesClient, AgencyDetailView } from "@travories/frontend-sdk";
+
+function AgencyPage({ slug }: { slug: string }) {
+  return (
+    <AgencyDetailView
+      client={client}
+      slug={slug}
+      packageHrefFor={(pkg) => `/package/${pkg.slug}`}
+      openPackagesInNewTab
+    />
+  );
+}
+```
+
+Renders: breadcrumb → title → host card + overview + verified badge → partner associations → "Popular packages from {agency}" carousel.
+
 ### Just the data
 
 ```ts
@@ -129,74 +184,145 @@ import { TravoriesClient } from "@travories/frontend-sdk";
 
 const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
 
-const pkg = await client.getPackageBySlug("everest-base-camp");
-const bundle = await client.getPackageBundle("everest-base-camp");
-//    ↑ pkg + host + attractions + routes in one call
-const sections = await client.packages.getHomeSections();
+const pkg       = await client.getPackageBySlug("everest-base-camp");
+const bundle    = await client.getPackageBundle("everest-base-camp");
+//        ↑ pkg + host + attractions + per-day GeoJSON routes, in one call
+const sections  = await client.packages.getHomeSections();
+const agency    = await client.getAgencyBundle("travel-route-pvt-ltd");
+const routes    = await client.packages.getRoutes("everest-base-camp");
+```
+
+Returns `null` on 404 / network errors by default (silent mode). Pass `{ silent: false }` to throw instead.
+
+---
+
+## Booking flow
+
+End-to-end booking takes 3 lines of consumer code:
+
+```tsx
+<PackageDetailView
+  client={client}
+  slug={slug}
+  onReserve={async ({ pkg, arrival, travelers }) => {
+    const { data: bookingId } = await client.bookings.initiate({
+      packageId: pkg.slug,
+      arrivalDate: arrival,            // ISO date string e.g. "2027-08-15"
+      travelers,                       // [{ name: "Adult", count: 2 }, …]
+    });
+    // bookingId is a UUID returned by the BE.
+    // Hand off to your payment flow:
+    window.location.href = `/checkout/${bookingId}`;
+    // …or open in a new tab:
+    // window.open(`/checkout/${bookingId}`, "_blank", "noopener,noreferrer");
+  }}
+/>
 ```
 
-No React, no UI — just typed data. Use in scripts, edge functions, Node servers, anywhere.
+**What happens visually:** the user picks a date + travelers in the built-in BookingCardLite. When they click **Book Now**, the button switches to **"Initiating…"** and disables itself until `onReserve` resolves (it auto-detects a returned `Promise`). On success, your callback navigates wherever it needs to. On error, throw or `alert` — the button re-enables automatically.
+
+**Errors:** `client.bookings.initiate()` throws `TravoriesApiError` on a non-2xx response. Wrap in try/catch:
+
+```tsx
+onReserve={async (payload) => {
+  try {
+    const { data } = await client.bookings.initiate({ ... });
+    navigateToCheckout(data);
+  } catch (err) {
+    alert(`Failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}}
+```
 
 ---
 
-## Components
+## Components reference
 
 ### Page-level drop-ins
 
-| Component | What it renders |
+| Component | Renders |
 |---|---|
-| `<PackageDetailView />` | Full detail page: gallery, overview, key facts, itinerary + map, included/excluded/to-pack, host. |
-| `<HomeSections />` | All four landing sections in one block (one fetch). |
-| `<HomeSectionsProvider />` | Fetches the four sections once, exposes via context. Wrap your tree to use `<PackagesSection>` anywhere inside. |
-| `<PackagesSection section="trending" />` | One specific section (Popular / Trending / Top Rated / More to Explore). Drop multiple inside a Provider — they share one fetch. |
+| `<PackageDetailView />` | Full package detail page |
+| `<AgencyDetailView />` | Full agency profile page |
+| `<HomeSections />` | All four landing carousels in one block |
+| `<HomeSectionsProvider />` | Wraps your tree; fetches once; sub-sections share data |
+| `<PackagesSection section="..." />` | One specific section, consumes the Provider |
 
-### Composable sub-components
+### Sub-components for custom layouts
 
-For custom layouts, every visual primitive is exported:
+All exported individually:
 
 | Component | Purpose |
 |---|---|
-| `<PackagesCarousel />` | Horizontal scrollable strip with title + arrows. Pass your own list of packages. |
-| `<PackageCard />` | Single card. Use in grids, masonry, anywhere. |
-| `<TopSection />` | Detail-page header: breadcrumb, title, rating, gallery. |
-| `<GallerySection />` | 5-image gallery grid + lightbox. |
-| `<PackageOverview />` | Description + key facts panel. |
-| `<Itinerary />` | Day tabs + day card + map (with FlyToBounds). |
-| `<PackageMap />` | Leaflet wrapper with markers + GeoJSON polylines. |
-| `<PackageIncluded />` | What's-included checklist. |
-| `<PackageExcludedAndToPack />` | What's-excluded + what-to-pack lists. |
-| `<HostCard />`, `<HostAbout />` | Host / agency card + about block. |
-| `<BookingCardLite />` | Booking sidebar: date picker, traveler stepper, price math, Reserve CTA. |
+| `<PackagesCarousel title packages />` | Horizontal scrollable carousel with arrows |
+| `<PackageCard pkg />` | Single card (image + title + duration · stars · price) |
+| `<TopSection topData />` | Detail-page header (breadcrumb, title, rating, gallery) |
+| `<GallerySection media />` | 5-image grid + click-to-open lightbox |
+| `<PackageOverview description topData />` | Description + key facts panel |
+| `<Itinerary Description routes />` | Day tabs + day card + map (sticky on scroll) |
+| `<PackageMap locations routes dayNumber />` | Leaflet map with markers + GeoJSON polylines |
+| `<PackageIncluded thingsToDo />` | What's-included checklist |
+| `<PackageExcludedAndToPack thingsExcluded thingsToPack />` | Two checklists |
+| `<HostCard hostData onAgencyClick />` | Agency card with stats |
+| `<HostAbout hostName description />` | "About {host}" prose block |
+| `<BookingCardLite DescriptionData onReserve />` | Booking sidebar |
+| `<AgencyAssociations associations />` | Partner-badge strip |
+
+### Shared `<PackageDetailView />` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `client` | `TravoriesClient` | Required when not using `initialBundle` |
+| `slug` | `string` | Required when not using `initialBundle` |
+| `initialBundle` | `PackageBundle \| null` | Pre-fetched (SSR pattern). Skips the internal fetch |
+| `currency` | `string` | Default `"USD"`. Anything `Intl.NumberFormat` accepts |
+| `onReserve` | `(payload: ReservePayload) => void \| Promise<void>` | Return a Promise to enable the "Initiating…" CTA state |
+| `onSelectHost` | `(host: PackageHost) => void` | Fired when host card is clicked |
+| `agencyHrefFor` | `(host) => string` | If set, host card becomes an `<a href>` |
+| `openAgencyInNewTab` | `boolean` | Adds `target="_blank"` on the host anchor |
+| `className` | `string` | Extra class on root |
+| `renderLoading` | `() => ReactNode` | Custom skeleton |
+| `renderNotFound` | `() => ReactNode` | Custom 404 |
+
+### Shared `<AgencyDetailView />` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `client` / `slug` / `initialBundle` | — | Same dual mode as `<PackageDetailView />` |
+| `currency` | `string` | For package card prices |
+| `onSelectPackage` | `(pkg: HomePackageCard) => void` | Click handler |
+| `packageHrefFor` | `(pkg) => string` | Renders package cards as anchors |
+| `openPackagesInNewTab` | `boolean` | Adds `target="_blank"` |
+| `renderLoading` / `renderNotFound` | — | Override defaults |
 
 ---
 
-## Hooks
+## Hooks reference
 
-For headless / build-your-own-UI consumers:
+| Hook | Returns |
+|---|---|
+| `usePackageBySlug(client, slug)` | `{ data: TravoriesPackage \| null, loading, error, refetch }` |
+| `usePackageBundle(client, slug)` | `{ data: PackageBundle \| null, loading, error, refetch }` |
+| `useHomeSections(client)` | `{ data: HomeSectionsResponse \| null, loading, error, refetch }` |
+| `useHomeSectionsContext()` | Same shape — reads from `<HomeSectionsProvider>` (shared fetch) |
+| `useAgencyBundle(client, slug)` | `{ data: AgencyBundle \| null, loading, error, refetch }` |
 
-```tsx
-import { usePackageBundle, useHomeSections } from "@travories/frontend-sdk";
+All hooks accept `null` for `client` / `slug` to **stay inert** (no fetch). Use when you already have data via `initialBundle` and just need the hook to satisfy rules-of-hooks.
 
-function Custom() {
+Example with custom UI:
+
+```tsx
+function Custom({ slug }: { slug: string }) {
   const { data, loading, error, refetch } = usePackageBundle(client, slug);
-  // data: { pkg, host, attractions, routes }
 
-  const home = useHomeSections(client);
-  // home.data: { popular, trending, topRated, moreToExplore }
+  if (loading) return <MySpinner />;
+  if (error)   return <button onClick={refetch}>Retry: {error.message}</button>;
+  if (!data)   return <My404 />;
 
-  // ... render however you want
+  return <article><h1>{data.pkg.title}</h1>{/* ... */}</article>;
 }
 ```
 
-| Hook | Returns |
-|---|---|
-| `usePackageBySlug(client, slug)` | `{ data: TravoriesPackage | null, loading, error, refetch }` |
-| `usePackageBundle(client, slug)` | `{ data: PackageBundle | null, loading, error, refetch }` |
-| `useHomeSections(client)` | `{ data: HomeSectionsResponse | null, loading, error, refetch }` |
-| `useHomeSectionsContext()` | Same as above, but reads from `<HomeSectionsProvider>` context (one shared fetch). |
-
-All hooks accept `null` instead of a client to stay inert (useful when you already have data via `initialBundle` / `initialSections`).
-
 ---
 
 ## Client configuration
@@ -204,37 +330,40 @@ All hooks accept `null` instead of a client to stay inert (useful when you alrea
 ```ts
 new TravoriesClient({
   baseUrl: "https://api.travories.com",      // required
-  apiKey: "tvr_xxx",                         // optional — sent as x-api-key
-  authToken: () => session?.accessToken,     // optional — sent as Bearer
-  defaultHeaders: { "x-trace-id": "abc" },   // optional
+  apiKey: "tvr_xxx",                         // optional — sent as `x-api-key`
+  authToken: () => session?.accessToken,     // optional — sent as `Bearer`
+  defaultHeaders: { "x-trace-id": "abc" },   // optional — merged into every request
   fetchImpl: customFetch,                    // optional — supply your own fetch
 });
 ```
 
-`authToken` accepts a string, a function, or an async function — useful when the token rotates.
+`authToken` accepts a **string**, a **sync function**, or an **async function** — useful when the token rotates per request.
 
-Errors fall back silently and return `null` by default. Pass `silent: false` per-call to throw `TravoriesApiError`:
+### Available resources
 
 ```ts
-import { TravoriesApiError } from "@travories/frontend-sdk";
+client.packages    // PackagesResource
+client.agencies    // AgenciesResource
+client.bookings    // BookingsResource
+```
 
-try {
-  const pkg = await client.packages.getBySlug("missing", { silent: false });
-} catch (err) {
-  if (err instanceof TravoriesApiError) {
-    console.error(err.status, err.url, err.body);
-  }
-}
+### Convenience shortcuts on the client itself
+
+```ts
+client.getPackageBySlug(slug)
+client.getPackageBundle(slug)
+client.getAgencyBySlug(slug)
+client.getAgencyBundle(slug)
 ```
 
 ---
 
-## SSR with Next.js
+## SSR with Next.js / Remix
 
-The recommended pattern: fetch on the server, hand off via `initialBundle` / `initialSections`. The component skips its internal fetch and renders synchronously.
+Fetch on the server, hand off via `initialBundle` / `initialSections`. The component skips its internal fetch and renders synchronously.
 
 ```tsx
-// app/packages/[slug]/page.tsx
+// app/packages/[slug]/page.tsx — Next.js App Router
 import { TravoriesClient, PackageDetailView } from "@travories/frontend-sdk";
 import "@travories/frontend-sdk/styles.css";
 
@@ -243,102 +372,59 @@ const client = new TravoriesClient({ baseUrl: process.env.TRAVORIES_API_URL! });
 export default async function Page({ params }: { params: { slug: string } }) {
   const bundle = await client.getPackageBundle(params.slug);
   if (!bundle) return <NotFound />;
-
   return <PackageDetailView initialBundle={bundle} />;
 }
 ```
 
 ```tsx
-// app/page.tsx (landing)
-import { TravoriesClient, HomeSections } from "@travories/frontend-sdk";
-import "@travories/frontend-sdk/styles.css";
-
-const client = new TravoriesClient({ baseUrl: process.env.TRAVORIES_API_URL! });
-
-export default async function Landing() {
-  const sections = await client.packages.getHomeSections();
-  return (
-    <HomeSections
-      initialSections={sections}
-      hrefFor={(p) => `/package/${p.slug}`}
-    />
-  );
-}
+// app/page.tsx — landing
+const sections = await client.packages.getHomeSections();
+return <HomeSections initialSections={sections} hrefFor={...} />;
 ```
 
-Works with Pages Router (`getServerSideProps`), Remix loaders, and React Router data API too — the pattern is the same.
-
----
-
-## Composable landing layouts
-
-When you want **SDK sections interleaved with your own content** (FAQs, testimonials, ads), wrap the page in `<HomeSectionsProvider>` and drop `<PackagesSection>` anywhere inside. Sections share one fetch.
-
 ```tsx
-import {
-  TravoriesClient,
-  HomeSectionsProvider,
-  PackagesSection,
-} from "@travories/frontend-sdk";
-
-const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
-
-function Landing() {
-  return (
-    <HomeSectionsProvider client={client}>
-      <Hero />
-      <PackagesSection section="popular" hrefFor={(p) => `/package/${p.slug}`} />
-      <PackagesSection section="trending" />
-      <FAQ />                                       {/* your own */}
-      <Newsletter />                                {/* your own */}
-      <PackagesSection section="topRated" title="Editor's picks" />
-      <PackagesSection section="moreToExplore" />
-      <Footer />
-    </HomeSectionsProvider>
-  );
-}
+// app/agency/[slug]/page.tsx
+const agency = await client.getAgencyBundle(params.slug);
+if (!agency) return <NotFound />;
+return <AgencyDetailView initialBundle={agency} packageHrefFor={...} />;
 ```
 
-Each section can override `title`, `subtitle`, `currency`, `onSelect`, `hrefFor`, `openInNewTab`, `hideWhenLoading`, `hideWhenEmpty`.
-
-For a totally custom block, drop down to `useHomeSectionsContext()`:
-
-```tsx
-function StatsBar() {
-  const { data } = useHomeSectionsContext();
-  if (!data) return null;
-  return <div>{data.popular.length + data.trending.length} packages featured</div>;
-}
-```
+Same shape works with Remix / React Router data loaders.
 
 ---
 
 ## Styling
 
-The SDK ships precompiled, scoped CSS:
+The SDK ships **precompiled CSS** scoped under a wrapper class — your app's styling is never affected.
 
 ```ts
 import "@travories/frontend-sdk/styles.css";
 ```
 
-**Scope guarantee**: all utility classes are scoped under `.tvr-package-detail` so they cannot collide with your own Tailwind setup. Your app's CSS is never affected.
+**Scope guarantee**: every utility class is generated under `.tvr-package-detail` selectors, so there's no collision risk with your own Tailwind / CSS Modules / whatever.
 
-**Re-skinning** — override the design tokens at the wrapper:
+**Re-skinning**: override the design tokens with CSS:
 
 ```css
 .tvr-package-detail {
-  /* CSS variables you can override */
   --tvr-radius: 0.75rem;
+  /* …any other CSS vars you've added */
 }
 ```
 
-Tailwind tokens like `text-primary-normal` and `bg-secondary` remain customizable via standard CSS overrides if needed — the precompiled output is plain CSS.
+For more aggressive customization, increase specificity:
+
+```css
+.my-app .tvr-package-detail .text-primary-normal {
+  color: #1d4ed8;
+}
+```
 
 ---
 
-## TypeScript
+## TypeScript types
 
-Every export ships with full type definitions. Notable types:
+Every export ships with full `.d.ts` definitions. Notable types:
 
 ```ts
 import type {
@@ -353,11 +439,21 @@ import type {
   PackageRoutesDay,
   HomePackageCard,
   HomeSectionsResponse,
+  AgencyHostDetails,
+  AgencyAssociationItem,
+  AgencyBundle,
   MajorAttractionItem,
   TravoriesImage,
 
+  // Booking
+  BookingTraveler,
+  BookingInitiateRequest,
+  BookingInitiateResponse,
+  ReservePayload,
+
   // Component props
   PackageDetailViewProps,
+  AgencyDetailViewProps,
   HomeSectionsProps,
   HomeSectionsProviderProps,
   PackagesSectionProps,
@@ -367,8 +463,9 @@ import type {
   UsePackageBySlugResult,
   UsePackageBundleResult,
   UseHomeSectionsResult,
+  UseAgencyBundleResult,
 
-  // Errors
+  // HTTP
   HttpClientConfig,
   HttpRequestOptions,
 } from "@travories/frontend-sdk";
@@ -376,28 +473,96 @@ import type {
 
 ---
 
-## API reference
+## API endpoints called
 
-### `client.packages` methods
+For network/CORS troubleshooting, here's exactly what each method hits:
 
-| Method | Endpoint | Returns |
-|---|---|---|
-| `getBySlug(slug)` | `GET /agency-package/by-slug/:slug` | `TravoriesPackage \| null` |
-| `getHost(slug)` | `GET /agency-info/by-package-slug/:slug` | `PackageHostResponse \| null` |
-| `getMajorAttractions(slug)` | `GET /major-attractions/package/:slug` | `MajorAttractionsResponse \| null` |
-| `getRoutes(slug)` | `GET /agency-package/routes/:slug` | `PackageRoutesResponse \| null` |
-| `getHomeSections()` | `GET /agency-package/home/sections` | `HomeSectionsResponse \| null` |
-| `getBundle(slug)` | parallel — combines the first four | `PackageBundle \| null` |
+| Method | Endpoint |
+|---|---|
+| `client.packages.getBySlug(slug)` | `GET /agency-package/by-slug/:slug` |
+| `client.packages.getHost(slug)` | `GET /agency-info/by-package-slug/:slug` |
+| `client.packages.getMajorAttractions(slug)` | `GET /major-attractions/package/:slug` |
+| `client.packages.getRoutes(slug)` | `GET /agency-package/routes/:slug` |
+| `client.packages.getHomeSections()` | `GET /agency-package/home/sections` |
+| `client.packages.getBundle(slug)` | parallel: by-slug + host + attractions + routes |
+| `client.agencies.getBySlug(slug)` | `GET /agency-info/by-slug/:slug` |
+| `client.agencies.getAssociations(slug)` | `GET /agency-association/agency/slug/:slug` |
+| `client.agencies.getPackages(slug)` | `GET /agency-package/by-agency/:slug?limit&page` |
+| `client.agencies.getBundle(slug)` | parallel: 3 calls above |
+| `client.bookings.initiate(payload)` | `POST /booking/initiate` |
+
+All `GET`s are silent by default (return `null` on 404 / network error). The `POST` throws `TravoriesApiError` so you can surface failures to the user.
+
+---
+
+## Edge cases & FAQ
+
+**Q: What happens if the package slug doesn't exist?**
+A: `<PackageDetailView>` shows the not-found state (override with `renderNotFound`). Hooks return `{ data: null, loading: false, error: null }`.
+
+**Q: What if the API is unreachable / CORS / network down?**
+A: Silent endpoints log to the console and return `null`. Components display the not-found state. The booking endpoint (POST) throws, so wrap it in try/catch.
+
+**Q: How do I show "Sold out" / disable Reserve?**
+A: Don't pass `onReserve` — the button auto-disables and shows "Contact host to book".
+
+**Q: My consumer doesn't have auth yet — how do I hide the wishlist heart?**
+A: It's already hidden by default. Opt in by passing `showHeart` + `liked` + `onLike` to `<PackageCard>`.
+
+**Q: Can I show only one section from the home payload?**
+A: Yes — either filter via `<HomeSections order={["trending"]} />` or use `<PackagesSection section="trending" />` inside a `<HomeSectionsProvider>`.
+
+**Q: Does the SDK fetch data multiple times if I render `<HomeSections>` and `<PackageDetailView>` on the same page?**
+A: Each component does its own fetch independently. Use the Provider pattern for `HomeSections` to share its fetch across multiple `<PackagesSection>`. Package detail and agency detail each do their own bundle fetch.
+
+**Q: How do I get the user to a new tab on card click?**
+A: Pass `hrefFor={(p) => "/package/" + p.slug}` + `openInNewTab` on `<PackagesCarousel>` / `<PackagesSection>` / `<HomeSections>`. Cards render as real `<a href target="_blank">` so right-click → "Open in new tab" also works.
+
+**Q: Can I change a section's title?**
+A: Pass `title` to `<PackagesSection>`, or use the `titles` map on `<HomeSections>`.
+
+**Q: How do I handle currency conversion?**
+A: Pass `currency="EUR"` etc. — uses `Intl.NumberFormat` under the hood. The SDK doesn't convert; it just formats the amount the BE returned.
+
+**Q: Can I use the SDK on the server only (no React)?**
+A: Yes. Import only the client + types: `import { TravoriesClient } from "@travories/frontend-sdk"`. The React pieces are tree-shaken out if you never touch them.
+
+**Q: Does it work in Edge runtimes (Vercel Edge, Cloudflare Workers)?**
+A: Yes — the client uses only the built-in `fetch`. No Node-specific APIs.
+
+**Q: Bundle size?**
+A: ~100 KB gzipped (ESM, including Leaflet which is the heaviest dep). Tree-shakeable — Node-only consumers get ~10 KB.
+
+**Q: How do I pre-warm the Leaflet map for faster perceived load?**
+A: Map only mounts client-side (it's wrapped in an effect that imports `react-leaflet` on demand). Nothing to pre-warm.
+
+**Q: My styles look broken — what's wrong?**
+A: Make sure you imported `@travories/frontend-sdk/styles.css` exactly once at your app entry point. Don't import multiple times — that's fine but wasteful.
+
+---
+
+## Browser support
+
+Last 2 versions of Chrome, Firefox, Safari, Edge. IE 11 is not supported.
+
+`fetch`, `URL`, `IntersectionObserver`, CSS Grid, and `Intl.NumberFormat` are required.
+
+---
+
+## Versioning & releases
+
+The SDK uses [semver](https://semver.org/). While < `1.0`, **breaking changes** are released as **minor** bumps (e.g. `0.1.x` → `0.2.0`), not majors. At `1.0` we switch to strict semver.
 
-Shortcut methods on the client itself: `client.getPackageBySlug(slug)`, `client.getPackageBundle(slug)`.
+Release cadence is on-demand. Subscribe to the [releases page](https://github.com/Travories/frontend-sdk/releases) for notifications.
 
 ---
 
 ## Support
 
-- **Docs / source**: [GitHub](https://github.com/Travories/frontend-sdk)
-- **Issues / requests**: [github.com/Travories/frontend-sdk/issues](https://github.com/Travories/frontend-sdk/issues)
-- **API**: [api.travories.com](https://api.travories.com)
+- **Source** / **issues**: [github.com/Travories/frontend-sdk](https://github.com/Travories/frontend-sdk)
+- **Demo**: [github.com/Travories/frontend-sdk-preview](https://github.com/Travories/frontend-sdk-preview) — clone + `npm install` + `npm run dev`
+- **API** (rate limits, auth, raw responses): [api.travories.com](https://api.travories.com)
+- **Production site**: [travories.com](https://travories.com)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travories/frontend-sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Official Travories SDK — fetch packages by slug and render the full Travories package detail page in any React app.",
   "license": "MIT",
   "author": {