npm package: @pindownai/client-js
Description: Official TypeScript/JavaScript client for the Pindown.ai API with built-in rate limiting
Author: Pindown.ai
Latest version: 1.1.0

# @pindownai/client-js

Official TypeScript/JavaScript client for the [Pindown.ai](https://pindown.ai) API.

## Features

- ✅ **Full TypeScript support** with IntelliSense
- ✅ **All 36 API endpoints** (Pins, Pinboards, Datasets, Blocks, Collaborators)
- ✅ **Built-in client-side rate limiting** with automatic token tracking
- ✅ **Organized by API** - Clean folder structure (pins/, pinboards/, datasets/, etc.)
- ✅ **Works everywhere** - Node.js, browsers, edge runtimes
- ✅ **Dual format** - ESM and CommonJS support
- ✅ **Zero dependencies** - Only uses native fetch API

## Installation

```bash
npm install @pindownai/client-js
```

## Quick Start

```typescript
import { PindownClient } from '@pindownai/client-js'

const client = new PindownClient({
  apiKey: 'pk_live_...'
  // Tier is auto-detected from server!
})

// Create a pin
const pin = await client.pins.create({
  metadata: {
    title: 'My First Pin'
  }
})

console.log(`Pin created: ${pin.id}`)

// Check your tier
console.log(`Your tier: ${client.getTier()}`)

// Check rate limits
const info = client.getRateLimitInfo()
if (info) {
  console.log(`Used: ${info.minute.used}/${info.minute.limit} tokens`)
}
```

## API Reference

### Pins API (`client.pins`)

```typescript
// Create pin
await client.pins.create({
  metadata: {
    title: 'My Pin'
  }
})

// Create with permissions
await client.pins.create({
  is_public: true,
  allow_comments: true,
  metadata: {
    title: 'Public Pin',
    tags: ['docs']
  }
})

// CRUD operations
await client.pins.get(pinId)
await client.pins.list()
await client.pins.update(pinId, {
  metadata: { title: 'Updated Title' }
})
await client.pins.delete(pinId)
await client.pins.share(pinId, {
  is_public: true,
  allow_comments: true
})
```

### Pinboards API (`client.pinboards`)

```typescript
// Create & manage pinboards
await client.pinboards.create({
  title: 'Dashboard',
  tags: ['analytics']
})
await client.pinboards.get(boardId)
await client.pinboards.list()
await client.pinboards.update(boardId, {
  title: 'New Title'
})
await client.pinboards.delete(boardId)

// Manage pins in pinboard
await client.pinboards.addPin(boardId, {
  pin_id: pinId
})
await client.pinboards.removePin(boardId, pinId)
await client.pinboards.updateLayout(boardId, {
  layout: { [pinId]: { x: 0, y: 0, w: 2, h: 1 } }
})
await client.pinboards.share(boardId, {
  is_public: true,
  allow_comments: true
})

// Custom roles
await client.pinboards.createRole(boardId, {
  name: 'VIP',
  color: '#FFD700'
})
await client.pinboards.listRoles(boardId)
await client.pinboards.assignUserRoles(boardId, userId, {
  roleIds: ['role-123']
})
await client.pinboards.setPinRoleRequirements(boardId, pinId, {
  roleIds: ['role-123']
})
```

### Datasets API (`client.datasets`)

```typescript
// Create JSON dataset
await client.datasets.create({
  name: 'Sales',
  type: 'json',
  data: { revenue: 125000, customers: 450 }
})

// Create markdown dataset
await client.datasets.create({
  name: 'Config',
  type: 'markdown',
  data: '# Company\nAcme Corp'
})

// CRUD operations
await client.datasets.get(datasetId)
await client.datasets.list()
await client.datasets.update(datasetId, {
  data: { revenue: 150000 }
})
await client.datasets.delete(datasetId)

// Share dataset
await client.datasets.inviteCollaborator(datasetId, {
  email: 'user@example.com',
  role: 'editor'
})
```

### Blocks API (`client.blocks`)

```typescript
await client.blocks.create(pinId, {
  title: 'Header',
  type: 'markdown',
  template: '# Title',
  order: 1
})
await client.blocks.get(pinId, blockId)
await client.blocks.list(pinId)
await client.blocks.update(pinId, blockId, {
  title: 'Updated Header',
  template: '# Updated'
})
await client.blocks.delete(pinId, blockId)
```

### Collaborators API (`client.collaborators`)

```typescript
// Pin collaborators
await client.collaborators.listForPin(pinId)
await client.collaborators.inviteToPin(pinId, { email: '...', role: 'editor' })
await client.collaborators.updatePinRole(pinId, userId, { role: 'viewer' })
await client.collaborators.removeFromPin(pinId, userId)
await client.collaborators.getPinPermissions(pinId)

// Pinboard collaborators
await client.collaborators.listForPinboard(boardId)
await client.collaborators.inviteToPinboard(boardId, { email: '...', role: 'editor' })
await client.collaborators.updatePinboardRole(boardId, userId, { role: 'viewer' })
await client.collaborators.removeFromPinboard(boardId, userId)
await client.collaborators.getPinboardPermissions(boardId)
```


## Documentation

Full API documentation: [docs.pindown.ai](https://docs.pindown.ai)

## Support

- Discord: [discord.gg/pindown](https://discord.gg/bDuUNBq5eS)
- Documentation: [docs.pindown.ai](https://docs.pindown.ai)

## License

MIT