@pindownai/client-js

Official TypeScript/JavaScript client for the 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

npm install @pindownai/client-js

Quick Start

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)

// 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)

// 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)

// 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: '[email protected]',
  role: 'editor'
})

Blocks API (client.blocks)

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)

// 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

Support

• Discord: discord.gg/pindown
• Documentation: docs.pindown.ai

License

MIT