@travories/frontend-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Travories
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF THE SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# @travories/sdk
+
+Official Travories SDK. Fetch packages by slug and drop the full **Package Detail page** into any React app.
+
+- 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
+
+---
+
+## Install
+
+```bash
+npm install @travories/sdk
+# peer deps (only needed if you use the React component / hooks)
+npm install react react-dom
+```
+
+---
+
+## 1. Just the data
+
+```ts
+import { TravoriesClient } from "@travories/sdk";
+
+const travories = new TravoriesClient({
+  baseUrl: "https://api.travories.com",
+});
+
+const pkg = await travories.packages.getBySlug("everest-base-camp");
+console.log(pkg?.title, pkg?.totalDays);
+
+// 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");
+```
+
+Returns `null` on 404 / network error (silent by default), or throws `TravoriesApiError` for unexpected statuses when not in silent mode.
+
+---
+
+## 2. The drop-in component
+
+`<PackageDetailView />` renders the whole detail page: gallery, overview, quick facts, itinerary, what's included / excluded / to pack, host card, and a sticky booking sidebar.
+
+```tsx
+import { TravoriesClient, PackageDetailView } from "@travories/sdk";
+import "@travories/sdk/styles.css"; // <- bundled styles
+
+const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
+
+export default function PackagePage({ slug }: { slug: string }) {
+  return (
+    <PackageDetailView
+      client={client}
+      slug={slug}
+      currency="USD"
+      onReserve={(pkg) => {
+        // navigate to your booking flow
+        window.location.href = `/checkout/${pkg.slug}`;
+      }}
+    />
+  );
+}
+```
+
+### Props
+
+| 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.                                                                   |
+
+### SSR example (Next.js App Router)
+
+```tsx
+// app/packages/[slug]/page.tsx
+import { TravoriesClient, PackageDetailView } from "@travories/sdk";
+import "@travories/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>;
+
+  return <PackageDetailView initialBundle={bundle} />;
+}
+```
+
+---
+
+## 3. Hooks (build your own UI)
+
+```tsx
+import { TravoriesClient, usePackageBySlug } from "@travories/sdk";
+
+const client = new TravoriesClient({ baseUrl: "https://api.travories.com" });
+
+function MyPackage({ slug }: { slug: string }) {
+  const { data, loading, error, refetch } = usePackageBySlug(client, slug);
+
+  if (loading) return <p>Loading…</p>;
+  if (error)   return <p>{error.message}</p>;
+  if (!data)   return <p>Not found</p>;
+
+  return <h1>{data.title}</h1>;
+}
+```
+
+`usePackageBundle(client, slug)` works the same way but returns `{ pkg, host, attractions }`.
+
+---
+
+## Client config
+
+```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
+});
+```
+
+`authToken` accepts a string, a function, or an async function — useful when the token is rotated.
+
+---
+
+## TypeScript
+
+All types are exported:
+
+```ts
+import type {
+  TravoriesPackage,
+  PackageHost,
+  PackageBundle,
+  PackageDay,
+  PackagePriceTier,
+  PackageDiscount,
+  TravoriesImage,
+} from "@travories/sdk";
+```
+
+---
+
+## Styling
+
+The component ships with scoped CSS (every class is prefixed `tvr-`). Import it once:
+
+```ts
+import "@travories/sdk/styles.css";
+```
+
+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;
+}
+```
+
+---
+
+## Local development
+
+```bash
+cd sdk
+npm install
+npm run build       # build to dist/
+npm run dev         # watch mode
+
+# example app
+cd example
+npm install
+npm run dev         # http://localhost:5173
+```
+
+The example uses `"@travories/sdk": "file:.."` so any rebuild of the SDK is picked up immediately.