perigee-tides 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to the Perigee JavaScript SDK are documented here. Registry
+versions and `sdk-v*` tags are immutable.
+
+## 1.0.1 - 2026-07-10
+
+- Initial public release for the Perigee Developer API v1.
+- Added dependency-free ESM support for Node 20+, browsers, Deno, Bun, and edge
+  runtimes with standards-compatible `fetch`.
+- Added typed station, tide-prediction, trip-health, best-window,
+  evaluate-rules, and material-change operations.
+- Added bounded retries, `Retry-After` handling, request/quota metadata, and
+  structured API, transport, and protocol errors.
+- Retry and wrap response-body stream interruptions that occur after HTTP
+  headers arrive.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cardin LLC
+
+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 OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# Perigee JavaScript SDK
+
+The official, dependency-free JavaScript and TypeScript client for the
+[Perigee Developer API](https://perigeetides.com/developers).
+
+It is an ESM package for Node 20+, browsers, Deno, Bun, edge runtimes, and
+other environments with standards-compatible `fetch`.
+
+## Install
+
+```bash
+npm install perigee-tides
+```
+
+## Quick start
+
+Public station and tide-prediction calls do not require a key:
+
+```ts
+import { PerigeeClient } from "perigee-tides";
+
+const perigee = new PerigeeClient();
+const stations = await perigee.listStations({
+  q: "Port Aransas",
+  state: "TX",
+  limit: 5,
+});
+const predictions = await perigee.tidePredictions("8775237", {
+  hours: 24,
+  interval: "hilo",
+});
+
+console.log(stations.data);
+console.log(predictions.requestId);
+```
+
+Authenticated decision calls use a server-side environment variable:
+
+```ts
+import { PerigeeClient } from "perigee-tides";
+
+const perigee = new PerigeeClient({
+  apiKey: process.env.PERIGEE_API_KEY,
+});
+
+const { data, requestId, monthlyRemaining } = await perigee.bestWindow({
+  stationId: "9414290",
+  activity: "fishing",
+  candidates: [
+    { localDate: "2026-07-10", localTime: "06:00" },
+    { localDate: "2026-07-10", localTime: "12:00" },
+  ],
+});
+
+console.log(data.decision, requestId, monthlyRemaining);
+```
+
+Other decision recipes use the same client:
+
+```ts
+const evaluation = await perigee.evaluateRules({
+  stationId: "9414290",
+  activity: "boating",
+  localDate: "2026-07-10",
+  localTime: "09:00",
+  rules: [
+    {
+      id: "confidence",
+      kind: "minimum_confidence",
+      minimum: "moderate",
+    },
+  ],
+});
+
+const change = await perigee.materialChange({
+  stationId: "9414290",
+  activity: "boating",
+  localDate: "2026-07-10",
+  localTime: "09:00",
+  baseline: {
+    decisionId: "previous-decision-id",
+    evaluatedAt: "2026-07-09T12:00:00.000Z",
+    state: "normal",
+    confidence: "high",
+    reasonCodes: ["signal.tide"],
+    sources: [
+      {
+        id: "tide-prediction",
+        freshness: "fresh",
+        sourceAt: "2026-07-09T11:00:00.000Z",
+      },
+    ],
+  },
+});
+```
+
+## Responses and errors
+
+Every successful call returns a typed envelope with `data`, `requestId`,
+`rateRemaining`, `monthlyRemaining`, and `quotaWarning`.
+
+```ts
+import {
+  PerigeeApiError,
+  PerigeeProtocolError,
+  PerigeeTransportError,
+} from "perigee-tides";
+
+try {
+  await perigee.tripHealth({
+    stationId: "9414290",
+    activity: "fishing",
+    localDate: "2026-07-10",
+    localTime: "07:00",
+  });
+} catch (error) {
+  if (error instanceof PerigeeApiError) {
+    console.error(
+      error.status,
+      error.code,
+      error.requestId,
+      error.retryAfterSeconds,
+    );
+  } else if (error instanceof PerigeeTransportError) {
+    console.error(`No response after ${error.attempts} attempts`);
+  } else if (error instanceof PerigeeProtocolError) {
+    console.error(error.status, error.requestId);
+  }
+}
+```
+
+The client retries network failures, HTTP 429, and HTTP 5xx responses with
+bounded exponential backoff. `Retry-After` is honored up to a ten-second
+client-side cap.
+
+```ts
+const perigee = new PerigeeClient({
+  apiKey: process.env.PERIGEE_API_KEY,
+  timeoutMs: 10_000,
+  maxRetries: 2,
+});
+```
+
+Do not bundle an API key into browser JavaScript, a mobile binary, logs, or
+source control. Proxy authenticated requests through your own server. The
+SDK never reads a key from a browser global; it only sends the value supplied
+to the constructor.
+
+See the [OpenAPI document](https://perigeetides.com/openapi.json) for complete
+response schemas and the
+[developer status page](https://perigeetides.com/developer/status) during an
+incident. Use the public [help and support surface](https://perigeetides.com/help)
+for questions or issue reports.
+
+## Release history
+
+SDK releases follow semantic versioning and published registry versions are
+immutable. See the packaged [changelog](./CHANGELOG.md) before upgrading.

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Perigee Developer API v1 client.
+ * Surface coverage is checked against /openapi.json in the root test suite.
+ */
+export interface PerigeeClientOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetch?: typeof fetch;
+}
+export declare class PerigeeApiError extends Error {
+    readonly status: number;
+    readonly code: string | number | null;
+    readonly requestId: string | null;
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, status: number, code: string | number | null, requestId: string | null, retryAfterSeconds: number | null);
+}
+export declare class PerigeeTransportError extends Error {
+    readonly attempts: number;
+    constructor(message: string, attempts: number, cause: unknown);
+}
+export declare class PerigeeProtocolError extends Error {
+    readonly status: number;
+    readonly requestId: string | null;
+    constructor(message: string, status: number, requestId: string | null, cause?: unknown);
+}
+export interface TripHealthInput {
+    stationId: string;
+    activity: "fishing" | "boating" | "surf-paddle" | "beachcombing" | "photography" | "coastal-living";
+    localDate: string;
+    localTime: string;
+}
+export interface PerigeeResponse<T> {
+    data: T;
+    requestId: string | null;
+    rateRemaining: number | null;
+    monthlyRemaining: number | null;
+    quotaWarning: string | null;
+}
+export declare class PerigeeClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetcher;
+    constructor(options?: PerigeeClientOptions);
+    private request;
+    listStations(query?: {
+        q?: string;
+        state?: string;
+        limit?: number;
+    }): Promise<PerigeeResponse<{
+        count: number;
+        stations: unknown[];
+    }>>;
+    tidePredictions(stationId: string, query?: {
+        hours?: number;
+        interval?: string;
+        datum?: string;
+    }): Promise<PerigeeResponse<unknown>>;
+    tripHealth(input: TripHealthInput): Promise<PerigeeResponse<{
+        decision: unknown;
+    }>>;
+    bestWindow(input: Omit<TripHealthInput, "localDate" | "localTime"> & {
+        candidates: Array<Pick<TripHealthInput, "localDate" | "localTime">>;
+    }): Promise<PerigeeResponse<{
+        decision: unknown;
+    }>>;
+    evaluateRules(input: TripHealthInput & {
+        rules: unknown[];
+    }): Promise<PerigeeResponse<{
+        evaluation: unknown;
+    }>>;
+    materialChange(input: TripHealthInput & {
+        baseline: unknown;
+    }): Promise<PerigeeResponse<{
+        change: unknown;
+    }>>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,222 @@
+/**
+ * Perigee Developer API v1 client.
+ * Surface coverage is checked against /openapi.json in the root test suite.
+ */
+export class PerigeeApiError extends Error {
+    status;
+    code;
+    requestId;
+    retryAfterSeconds;
+    constructor(message, status, code, requestId, retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "PerigeeApiError";
+    }
+}
+export class PerigeeTransportError extends Error {
+    attempts;
+    constructor(message, attempts, cause) {
+        super(message, { cause });
+        this.attempts = attempts;
+        this.name = "PerigeeTransportError";
+    }
+}
+export class PerigeeProtocolError extends Error {
+    status;
+    requestId;
+    constructor(message, status, requestId, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.status = status;
+        this.requestId = requestId;
+        this.name = "PerigeeProtocolError";
+    }
+}
+function numericHeader(headers, name) {
+    const value = headers.get(name);
+    if (value === null)
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function retryAfterSeconds(headers) {
+    const value = headers.get("retry-after");
+    if (value === null)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds;
+    const timestamp = Date.parse(value);
+    if (Number.isNaN(timestamp))
+        return null;
+    return Math.max(0, Math.ceil((timestamp - Date.now()) / 1_000));
+}
+function retryDelayMs(attempt, retryAfter) {
+    const seconds = retryAfter ?? 2 ** attempt;
+    return Math.min(10_000, Math.max(0, seconds * 1_000));
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function apiError(body) {
+    if (!body || typeof body !== "object" || !("error" in body)) {
+        return { code: null, message: null };
+    }
+    const error = body.error;
+    if (typeof error === "string")
+        return { code: null, message: error };
+    if (!error || typeof error !== "object") {
+        return { code: null, message: null };
+    }
+    const code = "code" in error ? error.code : null;
+    const message = "message" in error ? error.message : null;
+    return {
+        code: typeof code === "string" || typeof code === "number" ? code : null,
+        message: typeof message === "string" ? message : null,
+    };
+}
+export class PerigeeClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    fetcher;
+    constructor(options = {}) {
+        if (!Number.isFinite(options.timeoutMs ?? 30_000) || (options.timeoutMs ?? 30_000) <= 0) {
+            throw new Error("timeoutMs must be a positive finite number.");
+        }
+        if (!Number.isInteger(options.maxRetries ?? 2) || (options.maxRetries ?? 2) < 0) {
+            throw new Error("maxRetries must be a non-negative integer.");
+        }
+        if (options.apiKey !== undefined && !options.apiKey.trim()) {
+            throw new Error("apiKey cannot be blank.");
+        }
+        const baseUrl = new URL(options.baseUrl ?? "https://perigeetides.com");
+        if (!["http:", "https:"].includes(baseUrl.protocol) ||
+            baseUrl.username ||
+            baseUrl.password ||
+            baseUrl.search ||
+            baseUrl.hash) {
+            throw new Error("baseUrl must be an http(s) URL without credentials, query, or fragment.");
+        }
+        const fetcher = options.fetch ?? globalThis.fetch;
+        if (!fetcher) {
+            throw new Error("A standards-compatible fetch implementation is required.");
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = baseUrl.toString().replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.fetcher = fetcher;
+    }
+    async request(path, options = {}) {
+        if (options.authenticated && !this.apiKey) {
+            throw new Error("This operation requires a Perigee API key.");
+        }
+        for (let attempt = 0;; attempt += 1) {
+            const headers = new Headers({ Accept: "application/json" });
+            if (this.apiKey)
+                headers.set("Authorization", `Bearer ${this.apiKey}`);
+            if (options.body !== undefined)
+                headers.set("Content-Type", "application/json");
+            let response;
+            try {
+                response = await this.fetcher(`${this.baseUrl}${path}`, {
+                    method: options.method ?? "GET",
+                    headers,
+                    // Never let a credential-bearing request follow a redirect to a
+                    // different origin. A 3xx is surfaced as an API error instead.
+                    redirect: "manual",
+                    ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (error) {
+                if (attempt < this.maxRetries) {
+                    await sleep(retryDelayMs(attempt, null));
+                    continue;
+                }
+                throw new PerigeeTransportError(`Could not reach Perigee after ${attempt + 1} attempt(s).`, attempt + 1, error);
+            }
+            const retryAfter = retryAfterSeconds(response.headers);
+            if (attempt < this.maxRetries &&
+                (response.status === 429 || response.status >= 500)) {
+                await response.body?.cancel().catch(() => undefined);
+                await sleep(retryDelayMs(attempt, retryAfter));
+                continue;
+            }
+            let body = null;
+            let responseText;
+            try {
+                responseText = await response.text();
+            }
+            catch (error) {
+                if (attempt < this.maxRetries) {
+                    await response.body?.cancel().catch(() => undefined);
+                    await sleep(retryDelayMs(attempt, retryAfter));
+                    continue;
+                }
+                throw new PerigeeTransportError(`Could not read a complete Perigee response after ${attempt + 1} attempt(s).`, attempt + 1, error);
+            }
+            if (responseText) {
+                try {
+                    body = JSON.parse(responseText);
+                }
+                catch (error) {
+                    if (response.ok) {
+                        throw new PerigeeProtocolError("Perigee returned a successful response that was not valid JSON.", response.status, response.headers.get("x-request-id"), error);
+                    }
+                }
+            }
+            if (!response.ok) {
+                const error = apiError(body);
+                throw new PerigeeApiError(error.message ?? `Perigee returned HTTP ${response.status}.`, response.status, error.code, response.headers.get("x-request-id"), retryAfter);
+            }
+            return {
+                data: body,
+                requestId: response.headers.get("x-request-id"),
+                rateRemaining: numericHeader(response.headers, "x-ratelimit-remaining"),
+                monthlyRemaining: numericHeader(response.headers, "x-quota-month-remaining"),
+                quotaWarning: response.headers.get("x-quota-warning"),
+            };
+        }
+    }
+    listStations(query = {}) {
+        const params = new URLSearchParams(Object.entries(query).flatMap(([key, value]) => value === undefined ? [] : [[key, String(value)]]));
+        return this.request(`/api/v1/stations${params.size ? `?${params}` : ""}`);
+    }
+    tidePredictions(stationId, query = {}) {
+        const params = new URLSearchParams(Object.entries(query).flatMap(([key, value]) => value === undefined ? [] : [[key, String(value)]]));
+        return this.request(`/api/v1/stations/${encodeURIComponent(stationId)}/predictions${params.size ? `?${params}` : ""}`);
+    }
+    tripHealth(input) {
+        return this.request("/api/v1/decisions/trip-health", {
+            method: "POST",
+            body: input,
+        });
+    }
+    bestWindow(input) {
+        return this.request("/api/v1/decisions/best-window", {
+            method: "POST",
+            body: input,
+            authenticated: true,
+        });
+    }
+    evaluateRules(input) {
+        return this.request("/api/v1/decisions/evaluate-rules", {
+            method: "POST",
+            body: input,
+            authenticated: true,
+        });
+    }
+    materialChange(input) {
+        return this.request("/api/v1/decisions/material-change", {
+            method: "POST",
+            body: input,
+            authenticated: true,
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "perigee-tides",
+  "version": "1.0.1",
+  "description": "Dependency-free JavaScript client for the Perigee Developer API",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "node --test tests/*.test.mjs",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
+    "verify": "npm run build && npm test && npm run pack:check && npm run pack:smoke"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Cardin Labs <support@cardinlabs.com> (https://cardinlabs.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RyanCardin15/perigee.git",
+    "directory": "sdks/javascript"
+  },
+  "homepage": "https://perigeetides.com/developers",
+  "bugs": "https://perigeetides.com/help",
+  "keywords": [
+    "noaa",
+    "tides",
+    "coastal",
+    "marine-weather",
+    "decision-api"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,306 @@
+/**
+ * Perigee Developer API v1 client.
+ * Surface coverage is checked against /openapi.json in the root test suite.
+ */
+
+export interface PerigeeClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+  fetch?: typeof fetch;
+}
+
+export class PerigeeApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code: string | number | null,
+    readonly requestId: string | null,
+    readonly retryAfterSeconds: number | null,
+  ) {
+    super(message);
+    this.name = "PerigeeApiError";
+  }
+}
+
+export class PerigeeTransportError extends Error {
+  constructor(
+    message: string,
+    readonly attempts: number,
+    cause: unknown,
+  ) {
+    super(message, { cause });
+    this.name = "PerigeeTransportError";
+  }
+}
+
+export class PerigeeProtocolError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly requestId: string | null,
+    cause?: unknown,
+  ) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "PerigeeProtocolError";
+  }
+}
+
+export interface TripHealthInput {
+  stationId: string;
+  activity:
+    | "fishing"
+    | "boating"
+    | "surf-paddle"
+    | "beachcombing"
+    | "photography"
+    | "coastal-living";
+  localDate: string;
+  localTime: string;
+}
+
+export interface PerigeeResponse<T> {
+  data: T;
+  requestId: string | null;
+  rateRemaining: number | null;
+  monthlyRemaining: number | null;
+  quotaWarning: string | null;
+}
+
+function numericHeader(headers: Headers, name: string): number | null {
+  const value = headers.get(name);
+  if (value === null) return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function retryAfterSeconds(headers: Headers): number | null {
+  const value = headers.get("retry-after");
+  if (value === null) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds;
+  const timestamp = Date.parse(value);
+  if (Number.isNaN(timestamp)) return null;
+  return Math.max(0, Math.ceil((timestamp - Date.now()) / 1_000));
+}
+
+function retryDelayMs(attempt: number, retryAfter: number | null): number {
+  const seconds = retryAfter ?? 2 ** attempt;
+  return Math.min(10_000, Math.max(0, seconds * 1_000));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function apiError(body: unknown): {
+  code: string | number | null;
+  message: string | null;
+} {
+  if (!body || typeof body !== "object" || !("error" in body)) {
+    return { code: null, message: null };
+  }
+  const error = body.error;
+  if (typeof error === "string") return { code: null, message: error };
+  if (!error || typeof error !== "object") {
+    return { code: null, message: null };
+  }
+  const code = "code" in error ? error.code : null;
+  const message = "message" in error ? error.message : null;
+  return {
+    code: typeof code === "string" || typeof code === "number" ? code : null,
+    message: typeof message === "string" ? message : null,
+  };
+}
+
+export class PerigeeClient {
+  private readonly apiKey: string | undefined;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private readonly maxRetries: number;
+  private readonly fetcher: typeof fetch;
+
+  constructor(options: PerigeeClientOptions = {}) {
+    if (!Number.isFinite(options.timeoutMs ?? 30_000) || (options.timeoutMs ?? 30_000) <= 0) {
+      throw new Error("timeoutMs must be a positive finite number.");
+    }
+    if (!Number.isInteger(options.maxRetries ?? 2) || (options.maxRetries ?? 2) < 0) {
+      throw new Error("maxRetries must be a non-negative integer.");
+    }
+    if (options.apiKey !== undefined && !options.apiKey.trim()) {
+      throw new Error("apiKey cannot be blank.");
+    }
+    const baseUrl = new URL(options.baseUrl ?? "https://perigeetides.com");
+    if (
+      !["http:", "https:"].includes(baseUrl.protocol) ||
+      baseUrl.username ||
+      baseUrl.password ||
+      baseUrl.search ||
+      baseUrl.hash
+    ) {
+      throw new Error(
+        "baseUrl must be an http(s) URL without credentials, query, or fragment.",
+      );
+    }
+    const fetcher = options.fetch ?? globalThis.fetch;
+    if (!fetcher) {
+      throw new Error("A standards-compatible fetch implementation is required.");
+    }
+    this.apiKey = options.apiKey;
+    this.baseUrl = baseUrl.toString().replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? 30_000;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.fetcher = fetcher;
+  }
+
+  private async request<T>(
+    path: string,
+    options: { method?: "GET" | "POST"; body?: unknown; authenticated?: boolean } = {},
+  ): Promise<PerigeeResponse<T>> {
+    if (options.authenticated && !this.apiKey) {
+      throw new Error("This operation requires a Perigee API key.");
+    }
+    for (let attempt = 0; ; attempt += 1) {
+      const headers = new Headers({ Accept: "application/json" });
+      if (this.apiKey) headers.set("Authorization", `Bearer ${this.apiKey}`);
+      if (options.body !== undefined) headers.set("Content-Type", "application/json");
+      let response: Response;
+      try {
+        response = await this.fetcher(`${this.baseUrl}${path}`, {
+          method: options.method ?? "GET",
+          headers,
+          // Never let a credential-bearing request follow a redirect to a
+          // different origin. A 3xx is surfaced as an API error instead.
+          redirect: "manual",
+          ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+          signal: AbortSignal.timeout(this.timeoutMs),
+        });
+      } catch (error) {
+        if (attempt < this.maxRetries) {
+          await sleep(retryDelayMs(attempt, null));
+          continue;
+        }
+        throw new PerigeeTransportError(
+          `Could not reach Perigee after ${attempt + 1} attempt(s).`,
+          attempt + 1,
+          error,
+        );
+      }
+      const retryAfter = retryAfterSeconds(response.headers);
+      if (
+        attempt < this.maxRetries &&
+        (response.status === 429 || response.status >= 500)
+      ) {
+        await response.body?.cancel().catch(() => undefined);
+        await sleep(retryDelayMs(attempt, retryAfter));
+        continue;
+      }
+      let body: unknown = null;
+      let responseText: string;
+      try {
+        responseText = await response.text();
+      } catch (error) {
+        if (attempt < this.maxRetries) {
+          await response.body?.cancel().catch(() => undefined);
+          await sleep(retryDelayMs(attempt, retryAfter));
+          continue;
+        }
+        throw new PerigeeTransportError(
+          `Could not read a complete Perigee response after ${attempt + 1} attempt(s).`,
+          attempt + 1,
+          error,
+        );
+      }
+      if (responseText) {
+        try {
+          body = JSON.parse(responseText) as unknown;
+        } catch (error) {
+          if (response.ok) {
+            throw new PerigeeProtocolError(
+              "Perigee returned a successful response that was not valid JSON.",
+              response.status,
+              response.headers.get("x-request-id"),
+              error,
+            );
+          }
+        }
+      }
+      if (!response.ok) {
+        const error = apiError(body);
+        throw new PerigeeApiError(
+          error.message ?? `Perigee returned HTTP ${response.status}.`,
+          response.status,
+          error.code,
+          response.headers.get("x-request-id"),
+          retryAfter,
+        );
+      }
+      return {
+        data: body as T,
+        requestId: response.headers.get("x-request-id"),
+        rateRemaining: numericHeader(response.headers, "x-ratelimit-remaining"),
+        monthlyRemaining: numericHeader(response.headers, "x-quota-month-remaining"),
+        quotaWarning: response.headers.get("x-quota-warning"),
+      };
+    }
+  }
+
+  listStations(query: { q?: string; state?: string; limit?: number } = {}) {
+    const params = new URLSearchParams(
+      Object.entries(query).flatMap(([key, value]) =>
+        value === undefined ? [] : [[key, String(value)]],
+      ),
+    );
+    return this.request<{ count: number; stations: unknown[] }>(
+      `/api/v1/stations${params.size ? `?${params}` : ""}`,
+    );
+  }
+
+  tidePredictions(
+    stationId: string,
+    query: { hours?: number; interval?: string; datum?: string } = {},
+  ) {
+    const params = new URLSearchParams(
+      Object.entries(query).flatMap(([key, value]) =>
+        value === undefined ? [] : [[key, String(value)]],
+      ),
+    );
+    return this.request<unknown>(
+      `/api/v1/stations/${encodeURIComponent(stationId)}/predictions${params.size ? `?${params}` : ""}`,
+    );
+  }
+
+  tripHealth(input: TripHealthInput) {
+    return this.request<{ decision: unknown }>("/api/v1/decisions/trip-health", {
+      method: "POST",
+      body: input,
+    });
+  }
+
+  bestWindow(input: Omit<TripHealthInput, "localDate" | "localTime"> & {
+    candidates: Array<Pick<TripHealthInput, "localDate" | "localTime">>;
+  }) {
+    return this.request<{ decision: unknown }>("/api/v1/decisions/best-window", {
+      method: "POST",
+      body: input,
+      authenticated: true,
+    });
+  }
+
+  evaluateRules(input: TripHealthInput & { rules: unknown[] }) {
+    return this.request<{ evaluation: unknown }>("/api/v1/decisions/evaluate-rules", {
+      method: "POST",
+      body: input,
+      authenticated: true,
+    });
+  }
+
+  materialChange(input: TripHealthInput & { baseline: unknown }) {
+    return this.request<{ change: unknown }>("/api/v1/decisions/material-change", {
+      method: "POST",
+      body: input,
+      authenticated: true,
+    });
+  }
+}