@travories/frontend-sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,66 +1,98 @@
-# @travories/sdk
+# @travories/frontend-sdk
 
-Official Travories SDK. Fetch packages by slug and drop the full **Package Detail page** into any React app.
+[![npm](https://img.shields.io/npm/v/@travories/frontend-sdk?color=cb3837&label=npm&logo=npm)](https://www.npmjs.com/package/@travories/frontend-sdk)
+[![downloads](https://img.shields.io/npm/dm/@travories/frontend-sdk?color=blue)](https://www.npmjs.com/package/@travories/frontend-sdk)
+[![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)
 
-- Framework-agnostic API client (`TravoriesClient`)
-- React hooks (`usePackageBySlug`, `usePackageBundle`)
-- Self-contained UI component (`<PackageDetailView />`) with bundled styles — **no Tailwind required**
-- Full TypeScript types
-- ESM + CJS builds
+> 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.
 
----
+```bash
+npm install @travories/frontend-sdk
+```
 
-## Install
+```tsx
+import { TravoriesClient, PackageDetailView } from "@travories/frontend-sdk";
+import "@travories/frontend-sdk/styles.css";
 
-```bash
-npm install @travories/sdk
-# peer deps (only needed if you use the React component / hooks)
-npm install react react-dom
+const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
+
+export default function Page({ slug }: { slug: string }) {
+  return <PackageDetailView client={client} slug={slug} />;
+}
 ```
 
+That's a complete, production-grade package detail page: gallery, itinerary with map, day-by-day routes, booking sidebar, host card. ~95 KB gzipped.
+
 ---
 
-## 1. Just the data
+## Features
 
-```ts
-import { TravoriesClient } from "@travories/sdk";
+- **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.
 
-const travories = new TravoriesClient({
-  baseUrl: "https://api.travories.com",
-});
+---
 
-const pkg = await travories.packages.getBySlug("everest-base-camp");
-console.log(pkg?.title, pkg?.totalDays);
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+  - [Detail page](#detail-page)
+  - [Landing carousels](#landing-carousels)
+  - [Just the data](#just-the-data)
+- [Components](#components)
+- [Hooks](#hooks)
+- [Client configuration](#client-configuration)
+- [SSR with Next.js](#ssr-with-nextjs)
+- [Composable landing layouts](#composable-landing-layouts)
+- [Styling](#styling)
+- [TypeScript](#typescript)
+- [API reference](#api-reference)
+- [Support](#support)
+- [License](#license)
 
-// Or the convenience shortcut:
-const pkg2 = await travories.getPackageBySlug("everest-base-camp");
+---
 
-// Or fetch the full bundle (package + host + attractions) in one call:
-const bundle = await travories.getPackageBundle("everest-base-camp");
+## Install
+
+```bash
+npm install @travories/frontend-sdk
+```
+
+**Peer dependencies** (skip if you only use the API client):
+
+```bash
+npm install react react-dom
 ```
 
-Returns `null` on 404 / network error (silent by default), or throws `TravoriesApiError` for unexpected statuses when not in silent mode.
+Requires React 17+, Node 18+ (uses built-in `fetch`).
 
 ---
 
-## 2. The drop-in component
+## Quick start
 
-`<PackageDetailView />` renders the whole detail page: gallery, overview, quick facts, itinerary, what's included / excluded / to pack, host card, and a sticky booking sidebar.
+### Detail page
 
 ```tsx
-import { TravoriesClient, PackageDetailView } from "@travories/sdk";
-import "@travories/sdk/styles.css"; // <- bundled styles
+import { TravoriesClient, PackageDetailView } from "@travories/frontend-sdk";
+import "@travories/frontend-sdk/styles.css";
 
 const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
 
-export default function PackagePage({ slug }: { slug: string }) {
+function PackagePage({ slug }: { slug: string }) {
   return (
     <PackageDetailView
       client={client}
       slug={slug}
       currency="USD"
       onReserve={(pkg) => {
-        // navigate to your booking flow
+        // hook your booking flow here
         window.location.href = `/checkout/${pkg.slug}`;
       }}
     />
@@ -68,126 +100,307 @@ export default function PackagePage({ slug }: { slug: string }) {
 }
 ```
 
-### Props
+### Landing carousels
+
+```tsx
+import { TravoriesClient, HomeSections } from "@travories/frontend-sdk";
+import "@travories/frontend-sdk/styles.css";
+
+const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
+
+function Landing() {
+  return (
+    <HomeSections
+      client={client}
+      currency="USD"
+      hrefFor={(pkg) => `/package/${pkg.slug}`}
+      openInNewTab
+    />
+  );
+}
+```
+
+Renders the four canonical sections: **Popular**, **Trending Right Now**, **Top Rated**, **More to Explore**.
+
+### Just the data
+
+```ts
+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();
+```
+
+No React, no UI — just typed data. Use in scripts, edge functions, Node servers, anywhere.
+
+---
+
+## Components
+
+### Page-level drop-ins
+
+| Component | What it 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. |
+
+### Composable sub-components
+
+For custom layouts, every visual primitive is exported:
+
+| 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. |
+
+---
+
+## Hooks
+
+For headless / build-your-own-UI consumers:
+
+```tsx
+import { usePackageBundle, useHomeSections } from "@travories/frontend-sdk";
+
+function Custom() {
+  const { data, loading, error, refetch } = usePackageBundle(client, slug);
+  // data: { pkg, host, attractions, routes }
+
+  const home = useHomeSections(client);
+  // home.data: { popular, trending, topRated, moreToExplore }
+
+  // ... render however you want
+}
+```
+
+| 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
+
+```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
+  fetchImpl: customFetch,                    // optional — supply your own fetch
+});
+```
+
+`authToken` accepts a string, a function, or an async function — useful when the token rotates.
 
-| Prop            | Type                                  | Notes                                                                                       |
-| --------------- | ------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `client`        | `TravoriesClient`                     | Required when using `slug`.                                                                 |
-| `slug`          | `string`                              | Package slug to fetch.                                                                      |
-| `initialBundle` | `PackageBundle \| null`               | Pre-fetched data. If set, no client-side fetch runs. Use this for SSR.                      |
-| `currency`      | `string`                              | Default `"USD"`. Anything `Intl.NumberFormat` accepts.                                      |
-| `onReserve`     | `(pkg: TravoriesPackage) => void`     | If omitted, the Reserve button shows a disabled "Contact host to book" state.               |
-| `className`     | `string`                              | Extra class on the root container.                                                          |
-| `renderLoading` | `() => ReactNode`                     | Override the loading skeleton.                                                              |
-| `renderNotFound`| `() => ReactNode`                     | Override the empty state.                                                                   |
+Errors fall back silently and return `null` by default. Pass `silent: false` per-call to throw `TravoriesApiError`:
 
-### SSR example (Next.js App Router)
+```ts
+import { TravoriesApiError } from "@travories/frontend-sdk";
+
+try {
+  const pkg = await client.packages.getBySlug("missing", { silent: false });
+} catch (err) {
+  if (err instanceof TravoriesApiError) {
+    console.error(err.status, err.url, err.body);
+  }
+}
+```
+
+---
+
+## SSR with Next.js
+
+The recommended pattern: fetch on the server, hand off via `initialBundle` / `initialSections`. The component skips its internal fetch and renders synchronously.
 
 ```tsx
 // app/packages/[slug]/page.tsx
-import { TravoriesClient, PackageDetailView } from "@travories/sdk";
-import "@travories/sdk/styles.css";
+import { TravoriesClient, PackageDetailView } from "@travories/frontend-sdk";
+import "@travories/frontend-sdk/styles.css";
 
 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 <div>Not found</div>;
+  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}`}
+    />
+  );
+}
+```
+
+Works with Pages Router (`getServerSideProps`), Remix loaders, and React Router data API too — the pattern is the same.
+
 ---
 
-## 3. Hooks (build your own UI)
+## 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, usePackageBySlug } from "@travories/sdk";
+import {
+  TravoriesClient,
+  HomeSectionsProvider,
+  PackagesSection,
+} from "@travories/frontend-sdk";
 
 const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
 
-function MyPackage({ slug }: { slug: string }) {
-  const { data, loading, error, refetch } = usePackageBySlug(client, slug);
+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>
+  );
+}
+```
 
-  if (loading) return <p>Loading…</p>;
-  if (error)   return <p>{error.message}</p>;
-  if (!data)   return <p>Not found</p>;
+Each section can override `title`, `subtitle`, `currency`, `onSelect`, `hrefFor`, `openInNewTab`, `hideWhenLoading`, `hideWhenEmpty`.
 
-  return <h1>{data.title}</h1>;
+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>;
 }
 ```
 
-`usePackageBundle(client, slug)` works the same way but returns `{ pkg, host, attractions }`.
-
 ---
 
-## Client config
+## Styling
+
+The SDK ships precompiled, scoped CSS:
 
 ```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
-  fetchImpl: customFetch,                     // optional, e.g. node-fetch in old Node
-});
+import "@travories/frontend-sdk/styles.css";
 ```
 
-`authToken` accepts a string, a function, or an async function — useful when the token is rotated.
+**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.
+
+**Re-skinning** — override the design tokens at the wrapper:
+
+```css
+.tvr-package-detail {
+  /* CSS variables you can override */
+  --tvr-radius: 0.75rem;
+}
+```
+
+Tailwind tokens like `text-primary-normal` and `bg-secondary` remain customizable via standard CSS overrides if needed — the precompiled output is plain CSS.
 
 ---
 
 ## TypeScript
 
-All types are exported:
+Every export ships with full type definitions. Notable types:
 
 ```ts
 import type {
+  // Domain
   TravoriesPackage,
-  PackageHost,
   PackageBundle,
+  PackageHost,
   PackageDay,
   PackagePriceTier,
   PackageDiscount,
+  PackageRoute,
+  PackageRoutesDay,
+  HomePackageCard,
+  HomeSectionsResponse,
+  MajorAttractionItem,
   TravoriesImage,
-} from "@travories/sdk";
+
+  // Component props
+  PackageDetailViewProps,
+  HomeSectionsProps,
+  HomeSectionsProviderProps,
+  PackagesSectionProps,
+  HomeSectionKey,
+
+  // Hooks
+  UsePackageBySlugResult,
+  UsePackageBundleResult,
+  UseHomeSectionsResult,
+
+  // Errors
+  HttpClientConfig,
+  HttpRequestOptions,
+} from "@travories/frontend-sdk";
 ```
 
 ---
 
-## Styling
+## API reference
 
-The component ships with scoped CSS (every class is prefixed `tvr-`). Import it once:
+### `client.packages` methods
 
-```ts
-import "@travories/sdk/styles.css";
-```
+| 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` |
 
-CSS variables on `.tvr-root` let you re-skin without overriding individual selectors:
-
-```css
-.tvr-root {
-  --tvr-primary: #1d4ed8;
-  --tvr-accent: #ec4899;
-  --tvr-radius: 18px;
-}
-```
+Shortcut methods on the client itself: `client.getPackageBySlug(slug)`, `client.getPackageBundle(slug)`.
 
 ---
 
-## Local development
+## Support
 
-```bash
-cd sdk
-npm install
-npm run build       # build to dist/
-npm run dev         # watch mode
+- **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)
 
-# example app
-cd example
-npm install
-npm run dev         # http://localhost:5173
-```
+---
+
+## License
 
-The example uses `"@travories/sdk": "file:.."` so any rebuild of the SDK is picked up immediately.
+MIT © [Travories](https://travories.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travories/frontend-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official Travories SDK — fetch packages by slug and render the full Travories package detail page in any React app.",
   "license": "MIT",
   "author": {
@@ -59,8 +59,12 @@
     "react-dom": ">=17"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "react-dom": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@iconify/react": "^5.0.0",