pawplacer-sdk/README.md

PawPlacer API SDK for JavaScript/TypeScript

# PawPlacer SDK

Official JavaScript/TypeScript SDK for the PawPlacer API.

## Installation

```bash
npm install @pawplacer/sdk
# or
yarn add @pawplacer/sdk
# or
pnpm add @pawplacer/sdk
```

## Quick Start

```typescript
import { PawPlacerClient } from '@pawplacer/sdk';

const client = new PawPlacerClient({
  apiUrl: 'https://api.pawplacer.com',
  apiKey: 'your-api-key-here', // or use accessToken for OAuth
  cache: {
    enabled: true, // defaults to true
    ttl: 5 * 60 * 1000, // 5 minutes (default)
  }
});

// List available pets
const pets = await client.pets.list({
  species: 'dog',
  status: 'available',
  limit: 20,
});

// Get a specific pet
const pet = await client.pets.get('pet-id');

// Create a new pet
const newPet = await client.pets.create({
  name: 'Buddy',
  species: 'dog',
  breeds: ['Labrador Retriever'],
  sex: 'male',
  age_category: 'adult',
});
```

## Authentication

The SDK supports two authentication methods:

### API Key Authentication
```typescript
const client = new PawPlacerClient({
  apiUrl: 'https://api.pawplacer.com',
  apiKey: 'your-api-key',
});
```

### Bearer Token Authentication
```typescript
const client = new PawPlacerClient({
  apiUrl: 'https://api.pawplacer.com',
  accessToken: 'your-bearer-token',
});
```

## API Reference

### Pets API

#### List Pets
```typescript
const response = await client.pets.list({
  limit: 20,
  offset: 0,
  species: 'cat',
  status: 'available',
  search: 'tabby',
  sortBy: 'name',
  sortOrder: 'asc',
  is_published: true,
  is_featured: false,
});

// Returns: PaginatedResponse<Pet>
```

#### Get Pet
```typescript
const pet = await client.pets.get('pet-id');
```

#### Create Pet
```typescript
const pet = await client.pets.create({
  name: 'Luna',
  species: 'cat',
  breeds: ['Siamese'],
  sex: 'female',
  age_category: 'young',
  size: 'small',
  adoption_fee: 150,
  description: 'Sweet and playful kitten',
  temperaments: ['playful', 'affectionate'],
  is_published: true,
});
```

#### Update Pet
```typescript
const updatedPet = await client.pets.update('pet-id', {
  adoption_status: 'pending',
  notes: 'Application in review',
});
```

#### Delete Pet
```typescript
await client.pets.delete('pet-id');
```

#### Upload Pet Image
```typescript
const file = new File(['...'], 'photo.jpg', { type: 'image/jpeg' });
const upload = await client.pets.uploadImage('pet-id', file);
```

#### Search Pets
```typescript
const results = await client.pets.search('golden retriever puppy');
```

#### Get Featured Pets
```typescript
const featured = await client.pets.getFeatured(10);
```

#### Export Pets
```typescript
// Export as CSV
const csvBlob = await client.pets.export('csv', {
  species: 'dog',
  status: 'available',
});

// Export as JSON
const jsonBlob = await client.pets.export('json');
```

#### Batch Update Pets
```typescript
const updated = await client.pets.batchUpdate(
  ['pet-id-1', 'pet-id-2'],
  { status: 'adopted' }
);
```

## Caching

The SDK includes built-in caching to reduce server load and improve performance:

```typescript
// Configure caching
const client = new PawPlacerClient({
  apiUrl: 'https://api.pawplacer.com',
  apiKey: 'your-api-key',
  cache: {
    enabled: true, // Enable/disable caching (default: true)
    ttl: 10 * 60 * 1000, // Cache TTL in milliseconds (default: 5 minutes)
  }
});

// Manual cache management
client.clearCache(); // Clear all cache
client.invalidateCache('pets:list:'); // Clear specific cache pattern

// Caching behavior:
// - GET requests are cached automatically
// - POST/PUT/PATCH/DELETE requests invalidate relevant cache entries
// - Search results are cached for 2 minutes
// - List/Featured/Status queries use the configured TTL
```

## Error Handling

The SDK throws errors for failed requests:

```typescript
try {
  const pet = await client.pets.get('invalid-id');
} catch (error) {
  if (error.response?.status === 404) {
    console.error('Pet not found');
  } else {
    console.error('An error occurred:', error.message);
  }
}
```

## TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

```typescript
import type { Pet, PetCreateInput, PaginatedResponse } from '@pawplacer/sdk';
```

## License

MIT