# PearlGraph SDK

Dependency-free JavaScript ESM client with TypeScript declarations. Uses native fetch in Node.js 18+, browsers, Bun, Deno and edge runtimes.

## Install

```sh
npm install https://pearlgraph.com/sdk/pearlgraph-sdk-0.1.0.tgz
```

This installs the archive hosted by PearlGraph, not an npm registry listing.

```js
import { PearlGraph, PearlGraphError } from "pearlgraph-sdk";
const pearl = new PearlGraph();
const uganda = await pearl.map({ audience: "foreign", month: 11 });
const journey = await pearl.route({ from: "kampala", to: "jinja", month: 11 });
console.log(journey.data.roadKm, journey.data.driveMinutes);
```

Browser modules can import directly from `https://pearlgraph.com/sdk/pearlgraph.js` without installation.

## Methods

- `map({ audience?, month?, from?, to? })`: base travel rules, map and source catalogue. Supply from and to together.
- `route({ from, to, month? })`: road journey.
- `plan({ start, stops, month? })`: build an itinerary. Each stop is `{ attractionId, activityId }`.
- `plan({ start, days, month? })`: check an itinerary. Each day is an array of stops. Use stops or days, never both.
- `attractions({ q?, region?, category? })`, `fees(ids?)`, `lodges({ near?, tier?, district?, type?, q? })`, `districts({ q?, region? })`.
- `essentials(audience?)`, `seasons()`, `operators(region?)`, `permits(attraction?)`, `flights(to?)`, `ferries(q?)`.
- `search(query, { kind? })`, `graph(node?, { depth?, predicate? })`.

Base map responses expose fields directly; focused calls and planning return `{ schemaVersion, sources, data }`. Responses retain all API facts and source provenance unchanged. Exact accommodation coordinates are not inferred from routing anchors.

## Errors and cancellation

All methods accept `{ signal }` as their last argument. Requests time out after 30 seconds by default; override with `new PearlGraph({ timeoutMs: 10000 })`. Custom `fetch` and `baseUrl` can be provided. No automatic retries are made.

```js
try {
  await pearl.route({ from: "kampala", to: "jinja" });
} catch (error) {
  if (error instanceof PearlGraphError) {
    console.error(error.status, error.message, error.retryAfter);
  } else {
    throw error; // Network errors and cancellation retain their native error.
  }
}
```

`PearlGraphError.problem` preserves the API's problem+json response; `retryAfter` is the server's Retry-After header or null. No key or login is required. API usage limits still apply.