@parkgraph/agent-sdk 0.0.0-stage → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.4.0 — 2026-10-15
+
+- First npm release of the typed client documented at https://parkgraph.com/developers/sdk: `ParkGraphClient` with
+  `searchLots`, `createSession`, `getSession`, `endSession` and `health()`, and `ParkGraphError` with `status`.
+- Types are generated from Park Graph's OpenAPI spec 1.4.0, including `GET /health`.
+- `apiKey` is optional: `searchLots` works without a key; the other methods surface the API's 401 as a
+  `ParkGraphError`.
+- Works with `pk_test_` sandbox keys; `createSession` takes the sandbox-only `test_card`.
+- No dependencies; uses the platform's `fetch` (Node.js 20+).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Park Graph
+
+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

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @parkgraph/agent-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The typed TypeScript client for the [Park Graph](https://parkgraph.com) parking API. Search lots, book a session,
+check it and end it from LangChain, CrewAI, AutoGPT, Semantic Kernel or your own agent.
+
+- No dependencies. Uses the platform's `fetch` (Node.js 20+, browsers, Deno, Bun, edge runtimes).
+- Types generated from Park Graph's OpenAPI spec (`https://parkgraph.com/openapi.json`).
+- `apiKey` is optional: `searchLots` works without a key.
+
+Docs: https://parkgraph.com/developers/sdk
+
+## Install
+
+```bash
+npm install @parkgraph/agent-sdk@1.4.0
+```
+
+## Quick start
+
+```ts
+import { ParkGraphClient } from "@parkgraph/agent-sdk";
+
+const pg = new ParkGraphClient({ apiKey: "pk_live_..." });
+
+// Search for parking by coordinates
+const { lots } = await pg.searchLots({
+  lat: 39.6403,
+  lng: -106.3742,
+  radius_km: 5,
+});
+
+// Book a session
+const { session } = await pg.createSession({
+  lot_id: lots[0].id,
+  plate: "CO-7891",
+});
+
+// Check status
+const status = await pg.getSession(session.id);
+
+// End session
+const receipt = await pg.endSession({
+  session_id: session.id,
+  session_code: session.session_code,
+});
+```
+
+## API
+
+| Method | Returns |
+| --- | --- |
+| `searchLots(params)`: search lots by lat/lng coordinates (no key needed) | `Promise<SearchResult>` |
+| `createSession(params)`: create a parking session | `Promise<{ session: Session }>` |
+| `getSession(sessionId)`: get a session by UUID | `Promise<{ session: SessionDetail }>` |
+| `endSession(params)`: end a session and get the receipt | `Promise<{ session: SessionReceipt }>` |
+| `health()`: check API health | `Promise<{ status, version }>` |
+
+## Errors
+
+Every non-2xx answer throws a `ParkGraphError` with the HTTP `status`, the API's error `code` and `message`, the
+`requestId` and the raw `body`. A request that can't reach Park Graph throws one with `status` 0.
+
+```ts
+import { ParkGraphClient, ParkGraphError } from "@parkgraph/agent-sdk";
+
+const pg = new ParkGraphClient({ apiKey: "pk_live_..." });
+
+try {
+  const { lots } = await pg.searchLots({ lat: 0, lng: 0 });
+} catch (err) {
+  if (err instanceof ParkGraphError) {
+    console.error(`API error ${err.status}: ${err.message}`);
+  }
+}
+```
+
+## Sandbox
+
+Use a `pk_test_` key (create one in your Park Graph dashboard, API keys → Test) against the same base URL. Test keys
+see three sandbox lots and pay with Stripe test cards; no real payments are processed. `createSession` takes a
+sandbox-only `test_card`:
+
+| `test_card` | Result |
+| --- | --- |
+| `4242 4242 4242 4242` (default) | Successful payment |
+| `4000 0000 0000 0002` | Card declined (`ParkGraphError`, status 402, code `CARD_DECLINED`) |
+| `4000 0000 0000 3220` | 3D Secure required (`payment_status` `requires_action`) |
+
+Sandbox docs: https://parkgraph.com/developers/sandbox
+
+## Options
+
+```ts
+new ParkGraphClient({
+  apiKey: process.env.PARKGRAPH_API_KEY, // optional
+  baseUrl: "https://parkgraph.com/api/v1", // default
+  fetch, // optional fetch implementation
+});
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,70 @@
+// @parkgraph/agent-sdk: typed client for the Park Graph parking API.
+// The API's request and response shapes live in ./types.js, generated from
+// Park Graph's OpenAPI spec (https://parkgraph.com/openapi.json).
+
+import type {
+  CreateSessionRequest,
+  CreateSessionResponse,
+  EndSessionRequest,
+  EndSessionResponse,
+  GetSessionResponse,
+  Health,
+  SearchParkingParams,
+  SearchParkingResponse,
+} from "./types.js";
+
+export type * from "./types.js";
+
+export declare const VERSION: "1.4.0";
+
+/** Parameters of searchLots: GET /lots/search. */
+export type SearchParams = SearchParkingParams;
+/** What searchLots resolves to. */
+export type SearchResult = SearchParkingResponse;
+/** Parameters of createSession: POST /sessions. */
+export type CreateSessionParams = CreateSessionRequest;
+/** Parameters of endSession: POST /sessions/end. */
+export type EndSessionParams = EndSessionRequest;
+
+export interface ParkGraphConfig {
+  /**
+   * A Park Graph API key: `pk_live_…`, or `pk_test_…` for the sandbox.
+   * Optional: searchLots works without one; the other methods need it.
+   */
+  apiKey?: string;
+  /** Default https://parkgraph.com/api/v1 */
+  baseUrl?: string;
+  /** A fetch implementation, if the runtime has none. */
+  fetch?: typeof fetch;
+}
+
+/** A non-2xx answer from the API, or a request that could not reach it (status 0). */
+export declare class ParkGraphError extends Error {
+  readonly name: "ParkGraphError";
+  /** HTTP status (0 when Park Graph could not be reached). */
+  readonly status: number;
+  /** The raw response body. */
+  readonly body: string;
+  /** The API's error code, e.g. "UNAUTHORIZED" or "RATE_LIMITED". */
+  readonly code: string | null;
+  /** The API's request id, for support. */
+  readonly requestId: string | null;
+  constructor(message: string, status: number, body?: string, code?: string | null, requestId?: string | null);
+}
+
+export declare class ParkGraphClient {
+  constructor(config?: ParkGraphConfig);
+  /** Search lots by lat/lng coordinates. Works without an API key. */
+  searchLots(params: SearchParams): Promise<SearchResult>;
+  /** Create a parking session. */
+  createSession(params: CreateSessionParams): Promise<CreateSessionResponse>;
+  /** Get a session by UUID. */
+  getSession(sessionId: string): Promise<GetSessionResponse>;
+  /** End a session and get the receipt. */
+  endSession(params: EndSessionParams): Promise<EndSessionResponse>;
+  /** Check API health. */
+  health(): Promise<Health>;
+}
+
+export { ParkGraphClient as ParkGraph };
+export default ParkGraphClient;

package/index.js

@@ -0,0 +1,130 @@
+// @parkgraph/agent-sdk: typed client for the Park Graph parking API.
+// Docs: https://parkgraph.com/developers/sdk
+//
+// Plain ESM with no dependencies; uses the platform's fetch (Node 20+,
+// browsers, Deno, Bun, edge runtimes). Types: index.d.ts, with the API's
+// shapes in types.d.ts, generated from Park Graph's OpenAPI spec.
+
+export const VERSION = "1.4.0";
+
+const DEFAULT_BASE_URL = "https://parkgraph.com/api/v1";
+
+/** A non-2xx answer from the API, or a request that could not reach it (status 0). */
+export class ParkGraphError extends Error {
+  constructor(message, status, body = "", code = null, requestId = null) {
+    super(message);
+    this.name = "ParkGraphError";
+    this.status = status;
+    this.body = body;
+    this.code = code;
+    this.requestId = requestId;
+  }
+}
+
+function errorFrom(status, text) {
+  let message = `API error ${status}`;
+  let code = null;
+  let requestId = null;
+  try {
+    const parsed = JSON.parse(text);
+    const err = parsed && typeof parsed === "object" ? parsed.error : null;
+    if (err && typeof err === "object") {
+      if (typeof err.message === "string" && err.message) message = err.message;
+      if (typeof err.code === "string") code = err.code;
+      if (typeof err.request_id === "string") requestId = err.request_id;
+    } else if (typeof err === "string" && err) {
+      message = err;
+    }
+  } catch {
+    // Not JSON: keep the generic message; the raw text is on `body`.
+  }
+  return new ParkGraphError(message, status, text, code, requestId);
+}
+
+function finiteNumber(name, value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new TypeError(`${name} must be a finite number`);
+  }
+  return value;
+}
+
+export class ParkGraphClient {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+
+  /**
+   * @param {{ apiKey?: string, baseUrl?: string, fetch?: typeof fetch }} [config]
+   * `apiKey` is optional: searchLots works without one. The other methods
+   * need a key and surface the API's 401 as a ParkGraphError.
+   */
+  constructor(config = {}) {
+    const key = typeof config.apiKey === "string" ? config.apiKey.trim() : "";
+    this.#apiKey = key || undefined;
+    this.#baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const f = config.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new TypeError("No fetch available: use Node.js 20+ or pass config.fetch");
+    }
+    this.#fetch = f;
+  }
+
+  async #request(path, init = {}) {
+    const headers = { Accept: "application/json" };
+    if (init.body !== undefined) headers["Content-Type"] = "application/json";
+    if (this.#apiKey) headers.Authorization = `Bearer ${this.#apiKey}`;
+    let res;
+    try {
+      res = await this.#fetch(`${this.#baseUrl}${path}`, { ...init, headers });
+    } catch (err) {
+      throw new ParkGraphError(`Could not reach Park Graph: ${err instanceof Error ? err.message : String(err)}`, 0);
+    }
+    const text = await res.text();
+    if (!res.ok) throw errorFrom(res.status, text);
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new ParkGraphError("Park Graph answered with something that is not JSON", res.status, text);
+    }
+  }
+
+  /** GET /lots/search. Works without an API key. */
+  async searchLots(params) {
+    const qs = new URLSearchParams({
+      lat: String(finiteNumber("lat", params?.lat)),
+      lng: String(finiteNumber("lng", params?.lng)),
+    });
+    if (params.radius_km !== undefined) qs.set("radius_km", String(finiteNumber("radius_km", params.radius_km)));
+    if (params.limit !== undefined) qs.set("limit", String(finiteNumber("limit", params.limit)));
+    return this.#request(`/lots/search?${qs}`);
+  }
+
+  /** POST /sessions. */
+  async createSession(params) {
+    const body = { lot_id: params.lot_id };
+    if (params.plate !== undefined) body.plate = params.plate;
+    if (params.test_card !== undefined) body.test_card = params.test_card;
+    return this.#request("/sessions", { method: "POST", body: JSON.stringify(body) });
+  }
+
+  /** GET /sessions/{sessionId}. */
+  async getSession(sessionId) {
+    return this.#request(`/sessions/${encodeURIComponent(sessionId)}`);
+  }
+
+  /** POST /sessions/end. */
+  async endSession(params) {
+    return this.#request("/sessions/end", {
+      method: "POST",
+      body: JSON.stringify({ session_id: params.session_id, session_code: params.session_code }),
+    });
+  }
+
+  /** GET /health. */
+  async health() {
+    return this.#request("/health");
+  }
+}
+
+export { ParkGraphClient as ParkGraph };
+export default ParkGraphClient;

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@parkgraph/agent-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "Typed TypeScript client for the Park Graph parking API: search lots, book, check and end parking sessions from any agent framework.",
+  "homepage": "https://parkgraph.com/developers/sdk",
+  "license": "MIT",
+  "author": "Park Graph (https://parkgraph.com)",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "types.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "parking",
+    "park-graph",
+    "sdk",
+    "ai-agents",
+    "langchain",
+    "typescript"
+  ]
+}

package/types.d.ts

@@ -0,0 +1,224 @@
+// Generated from agents/openai/openapi.yaml (Park Graph API 1.4.0) by lib/release/sdk-types.ts.
+// Do not edit by hand: change the spec, then run `pnpm --filter @workspace/park-graph run sdk:types`.
+
+export interface Lot {
+  id: string;
+  name: string;
+  slug: string;
+  address: string;
+  city: string;
+  state: string;
+  /** Lot latitude (WGS 84). Lots without a valid point are left out of results. */
+  latitude: number;
+  /** Lot longitude (WGS 84). */
+  longitude: number;
+  /** Same as latitude, for map libraries. */
+  lat: number;
+  /** Same as longitude, for map libraries. */
+  lng: number;
+  total_spaces: number;
+  lot_type: "surface" | "garage" | "underground" | "rooftop" | "valet" | "street";
+  distance_km?: number;
+  /** Whether the lot owner has completed property verification */
+  verified?: boolean;
+  availability: {
+    total_spaces: number;
+    active_sessions: number;
+    available_spaces: number;
+    occupancy_pct: number;
+    is_full: boolean;
+  };
+  pricing: {
+    base_rate: number;
+    rate_unit: "hour" | "day" | "flat";
+    max_daily_rate: number | null;
+    currency: string;
+  } | null;
+}
+
+export interface Health {
+  status: "ok" | "degraded" | "error";
+  /** The API (OpenAPI spec) version */
+  version: string;
+  commit?: string;
+  environment?: string;
+  timestamp?: string;
+  services?: Record<string, string>;
+  error?: ErrorBody;
+}
+
+export interface ErrorBody {
+  code?: string;
+  message?: string;
+  request_id?: string;
+}
+
+/** The price the driver is charged, from the same engine as the driver page, reservations and agent tools. Amounts are integer cents (USD). */
+export interface Quote {
+  duration_hours: number;
+  currency: string;
+  /** flat while a flat event price applies */
+  rate_unit: "hour" | "day" | "flat";
+  base_rate_cents: number;
+  /** Multiplier applied to the base rate (1 when no surge applies) */
+  multiplier: number;
+  effective_rate_cents: number;
+  max_daily_cents: number | null;
+  total_cents: number;
+  capped_at_daily_max: boolean;
+  surge: Surge;
+}
+
+/** Present while an event, Surge today or a dynamic rule raises the price (Pro and Enterprise lots only). */
+export type Surge = {
+  active?: boolean;
+  /** The owner's event name, or "Surge active" */
+  label?: string;
+  kind?: "event" | "surge_today" | "busy_lot" | "peak" | "weekend" | "stacked";
+  multiplier?: number;
+  /** The owner's flat event price, when that is what applies */
+  event_price_cents?: number | null;
+  /** Which of the lot's limits held the price, if any */
+  bound?: "floor" | "cap" | "daily_max" | null;
+  description?: string;
+} | null;
+
+export interface Session {
+  id: string;
+  session_code: string;
+  short_code: string;
+  lot_id: string;
+  status: "active" | "completed" | "expired" | "cancelled";
+  started_at: string;
+  rate: number;
+  rate_unit: string;
+  estimated_amount: number;
+  quote: Quote;
+  payment_intent_id: string | null;
+  client_secret: string | null;
+}
+
+export interface SessionDetail {
+  id: string;
+  session_code: string;
+  short_code: string;
+  lot_id: string;
+  vehicle_plate: string | null;
+  status: string;
+  started_at: string;
+  ended_at: string | null;
+  rate_at_start: number;
+  rate_unit: string;
+  effective_rate?: number;
+  subtotal?: number | null;
+  platform_fee?: number | null;
+  owner_payout?: number | null;
+  payment_status: string;
+  expected_end?: string | null;
+  extended_count?: number;
+  source?: string;
+  created_at?: string;
+}
+
+export interface SessionRefund {
+  /** The session's id (a UUID, or a sess_ id from /reserve/confirm). */
+  session_id?: string;
+  type?: "full" | "partial";
+  refunded_cents?: number;
+  fee_refunded_cents?: number;
+  owner_reversed_cents?: number;
+  replayed?: boolean;
+  payments?: Array<{
+    payment_intent_id?: string;
+    kind?: "session" | "extension";
+    amount_cents?: number;
+    fee_refunded_cents?: number;
+    owner_reversed_cents?: number;
+    refund_id?: string | null;
+  }>;
+}
+
+export interface SessionReceipt {
+  id: string;
+  status: string;
+  started_at: string;
+  ended_at: string;
+  duration_hours: number;
+  subtotal: number;
+  platform_fee: number;
+  owner_payout: number;
+  payment_status: string;
+}
+
+/** Query parameters of GET /lots/search. */
+export interface SearchParkingParams {
+  /** Latitude of the search center */
+  lat: number;
+  /** Longitude of the search center */
+  lng: number;
+  /** Search radius in kilometers */
+  radius_km?: number;
+  /** Maximum results to return */
+  limit?: number;
+}
+
+/** Successful response of GET /lots/search. */
+export interface SearchParkingResponse {
+  lots: Array<Lot>;
+  /** One-line answer an assistant can quote. The MCP search_lots tool returns the same field. */
+  summary: string;
+  meta: {
+    lat: number;
+    lng: number;
+    radius_km: number;
+    count: number;
+  };
+}
+
+/** Successful response of GET /health. */
+export type GetHealthResponse = Health;
+
+/** JSON body of POST /sessions. */
+export interface CreateSessionRequest {
+  /** Parking lot UUID from search results */
+  lot_id: string;
+  /** Vehicle license plate */
+  plate?: string;
+  /** Sandbox only (pk_test_ keys; a live key gets 400). The Stripe test card the authorization runs on, default 4242 4242 4242 4242. 4000 0000 0000 0002 answers 402 CARD_DECLINED; 4000 0000 0000 3220 creates the session with payment_status requires_action (3D Secure required). */
+  test_card?: "4242 4242 4242 4242" | "4000 0000 0000 0002" | "4000 0000 0000 3220";
+}
+
+/** Successful response of POST /sessions. */
+export interface CreateSessionResponse {
+  session: Session;
+}
+
+/** Successful response of GET /sessions/{sessionId}. */
+export interface GetSessionResponse {
+  session: SessionDetail;
+}
+
+/** JSON body of POST /sessions/end. */
+export interface EndSessionRequest {
+  /** Session UUID */
+  session_id: string;
+  /** Session code for verification */
+  session_code: string;
+}
+
+/** Successful response of POST /sessions/end. */
+export interface EndSessionResponse {
+  session: SessionReceipt;
+}
+
+/** JSON body of POST /sessions/{sessionId}/refund. */
+export interface RefundSessionRequest {
+  /** Cents to give back. Omit for a full refund. */
+  amount_cents?: number;
+  reason?: "requested_by_customer" | "duplicate" | "fraudulent";
+}
+
+/** Successful response of POST /sessions/{sessionId}/refund. */
+export interface RefundSessionResponse {
+  refund?: SessionRefund;
+}