Install the PawPlacer SDK from npm for the fastest path to our public API: https://www.npmjs.com/package/pawplacer-sdk.
The package is TypeScript-first—the client and every helper ship with rich typings so editors surface the exact payload shape returned by our Supabase functions. It wraps the public endpoints, handles retries, memoized caching, and validates required fields before sending create requests.
Security reminder: Instantiate the client on the server. The SDK throws if it detects a browser environment unless you explicitly pass
allowBrowser: true(NEVER DO THIS outside local development).
Why use the SDK?
- Typed responses – the
Petinterface mirrors theget_public_petsresponse so you always know which fields are available. - Smart caching – in-memory memoization refreshes results on a schedule you choose while staying within rate limits.
- Retry & error parsing – transient failures are retried automatically and JSON error payloads are attached to thrown errors as
apiError. - Server guardrails – the client refuses to instantiate in a browser by default to protect your API keys.
Installation
npm install pawplacer-sdk
# or
yarn add pawplacer-sdk
# or
bun add pawplacer-sdk
No extra @types package is required—the SDK bundles its own declarations.
Track release history in the packaged CHANGELOG.md file (also linked from the npm README).
Integration checklist
- Generate an API key in Settings -> API.
- Store it in server-only environment variables (never client-exposed values).
- Instantiate
PawPlacerClienton the server. - Use
client.pets.list(...)/client.pets.getById(...)for reads. - Use
client.pets.getCustomFields()before sendingcustom_field_dataduring creates.
Quick start
import { PawPlacerClient } from "pawplacer-sdk";
const client = new PawPlacerClient({
apiUrl: process.env.PAWPLACER_API_URL ?? "https://pawplacer.com",
apiKey: process.env.PAWPLACER_API_KEY,
cache: {
enabled: true,
refreshFrequency: 180, // minutes
},
});
const pets = await client.pets.list({ status: "available", species: "dog", limit: 12 });
const fields = await client.pets.getCustomFields();
const created = await client.pets.create({
name: "Max",
species: "dog",
age_category: "young",
sex: "male",
size: "medium",
status: "available",
health: "good",
show_public: true,
adoption_fee: 250,
breed: ["Labrador Retriever"],
good_with: ["families", "kids"],
temperaments: ["playful", "social"],
});
cache.refreshFrequency is expressed in minutes. Leave it undefined to keep the 3-hour default.
Configuration options
| Option | Description |
|---|---|
apiUrl | Base URL of the PawPlacer API (defaults to production). |
apiKey | Server-side API key. Required for all non-public operations. |
timeout | Request timeout in milliseconds (default 30000). |
retryLimit / retryBackoffLimit | Control ky's retry strategy for transient failures. |
debug | Enables verbose logging ([PawPlacer SDK] …). |
allowBrowser | Opt-in to browser usage. Leave false to protect credentials. NEVER DO THIS on production. |
cache | Toggle memoization and choose how often cached results refresh. |
Available helpers
| Method | Summary |
|---|---|
client.pets.list(params?) | Paginated list of public pets with optional filters. |
client.pets.get(id) / client.pets.getById(id) | Fetch a single public pet by ID. |
client.pets.getCustomFields() | Retrieve valid field_key values for custom_field_data. |
client.pets.create(payload) | Create a pet (validates required fields before calling the API). |
client.pets.findMany(params?, limit?) | Convenience helper that returns just the data array. |
Endpoint mapping
| SDK method | Endpoint |
|---|---|
client.pets.list(...) | GET /api/pets |
client.pets.getById(...) | GET /api/pets/{petId} |
client.pets.getCustomFields() | GET /api/pets/custom-fields |
client.pets.create(...) | POST /api/pets |
The returned Pet type reflects the full public payload, including tags, custom_field_data, and resolved relationship names like primary_veterinarian.
client.pets.list(...) also supports updated_since (ISO-8601) for incremental sync pulls.
Need something more advanced? Import RequestManager or CacheManager from pawplacer-sdk to build custom integrations while reusing the memoization layer.
Prefer another language/runtime? Use the OpenAPI contract at https://pawplacer.com/openapi/public-api-v1.yaml to generate clients outside JavaScript/TypeScript.
Examples
sdk/examples/basic-usage.ts– CLI script that demonstrates listing, fetching, creating, and searching petssdk/examples/full-app.tsx– Next.js App Router playground showing server actions wired topawplacer-sdk
Copy whichever example fits your stack and adapt the filters or payloads to suit your workflow.