@pindownai/client-js 0.3.4 → 0.3.5

package/README.md

@@ -29,7 +29,13 @@ const client = new PindownClient({
 })
 
 // Create a pin
-const pin = await client.pins.createMarkdown('# Hello World')
+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()}`)
@@ -46,55 +52,125 @@ if (info) {
 ### Pins API (`client.pins`)
 
 ```typescript
-// Create pins
-await client.pins.create({ data_type: 'markdown', content: '# Hello' })
-await client.pins.createMarkdown('# Hello')
-await client.pins.createStatCard({ title: 'Users', value: 1250 })
-await client.pins.createTable({ columns: [...], rows: [...] })
-await client.pins.createEmbed('https://youtube.com/watch?v=...')
+// 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({ limit: 10, offset: 0 })
-await client.pins.update(pinId, { content: '# Updated' })
+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 })
+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' })
+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.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.addPin(boardId, {
+  pin_id: pinId
+})
 await client.pinboards.removePin(boardId, pinId)
-await client.pinboards.updateLayout(boardId, { layout: {...} })
-await client.pinboards.share(boardId, { is_public: true })
+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
-await client.datasets.create({ name: 'Sales', type: 'json', data: {...} })
+// 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: {...} })
+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, { name: 'Header', type: 'markdown', template: '# Title' })
+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, { template: '# Updated' })
+await client.blocks.update(pinId, blockId, {
+  title: 'Updated Header',
+  template: '# Updated'
+})
 await client.blocks.delete(pinId, blockId)
 ```
 
@@ -116,90 +192,6 @@ await client.collaborators.removeFromPinboard(boardId, userId)
 await client.collaborators.getPinboardPermissions(boardId)
 ```
 
-## Rate Limiting
-
-Your tier is **automatically detected** from the API server via the `X-RateLimit-Tier` header. The client tracks rate limits client-side and throws a `RateLimitError` **before** making requests that would exceed your tier's limits.
-
-```typescript
-// First request auto-detects your tier
-await client.pins.list()
-
-// Now you can check your tier
-console.log(`Your tier: ${client.getTier()}`) // e.g., "hobby"
-
-// Check current usage
-const info = client.getRateLimitInfo()
-if (info) {
-  console.log(`Minute: ${info.minute.used}/${info.minute.limit}`)
-  console.log(`Hour: ${info.hour.used}/${info.hour.limit}`)
-}
-
-// Client blocks requests that would exceed limits
-try {
-  await client.pins.create({...})
-} catch (error) {
-  if (error instanceof RateLimitError) {
-    console.log(`Rate limit exceeded: ${error.used}/${error.limit}`)
-    console.log(`Reset at: ${error.resetAt}`)
-  }
-}
-```
-
-### Tier Limits
-
-| Tier | Tokens/Minute | Tokens/Hour |
-|------|---------------|-------------|
-| Starter | - | 16 |
-| Hobby | 100 | 6,000 |
-| Pro | 400 | 24,000 |
-| Teams | 1,000 | 60,000 |
-| Agency | 4,000 | 240,000 |
-
-**Token Costs:**
-- Standard requests (GET, POST, PUT, DELETE): **1 token**
-- Invite/Share requests: **3 tokens** (email costs)
-- Batch operations: **3-10 tokens** (based on size)
-
-## Error Handling
-
-```typescript
-import {
-  AuthenticationError,
-  ForbiddenError,
-  NotFoundError,
-  ValidationError,
-  RateLimitError,
-  ServerError,
-  NetworkError
-} from '@pindown/api-client'
-
-try {
-  await client.pins.create({...})
-} catch (error) {
-  if (error instanceof RateLimitError) {
-    // Handle rate limit
-  } else if (error instanceof AuthenticationError) {
-    // Invalid API key
-  } else if (error instanceof ValidationError) {
-    // Invalid request data
-  }
-}
-```
-
-## Configuration
-
-```typescript
-const client = new PindownClient({
-  apiKey: 'pk_live_...',           // Required
-  tier: 'hobby',                   // Optional - auto-detected from server
-  baseURL: 'https://api.pindown.ai/v1', // Optional
-  enableRateLimitTracking: true,   // Optional (default: true)
-  maxRetries: 3,                   // Optional (default: 3)
-  timeout: 30000                   // Optional (default: 30s)
-})
-```
-
-**Note:** The `tier` parameter is optional and only for testing. In production, your tier is automatically detected from the server based on your API key.
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pindownai/client-js",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Official TypeScript/JavaScript client for the Pindown.ai API with built-in rate limiting",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",