Initial commit

2025-11-30 08:50:52 +08:00
commit cac7a950f2
10 changed files with 1084 additions and 0 deletions
--- a/skills/pinterest-api/SKILL.md
+++ b/skills/pinterest-api/SKILL.md
@@ -0,0 +1,476 @@
+---
+name: pinterest-api
+description: Pinterest API v5 Development - Authentication, Pins, Boards, Analytics
+---
+
+# Pinterest API Skill
+
+Comprehensive assistance with Pinterest API v5 development, including OAuth authentication, pin/board management, analytics, and API integration patterns.
+
+## When to Use This Skill
+
+This skill should be triggered when:
+- Implementing Pinterest OAuth 2.0 authentication flows
+- Creating, updating, or managing Pins and Boards via API
+- Integrating Pinterest analytics and metrics into applications
+- Building Pinterest API clients or SDKs
+- Working with Pinterest user account data
+- Debugging Pinterest API requests or responses
+- Implementing Pinterest sharing features in web/mobile apps
+- Setting up Pinterest business account integrations
+- Working with Pinterest ad account APIs
+
+## Key Concepts
+
+### Pinterest API v5 Overview
+- **Base URL**: `https://api.pinterest.com/v5/`
+- **Authentication**: OAuth 2.0 with access tokens
+- **Rate Limiting**: Token-based rate limits (varies by endpoint)
+- **Response Format**: JSON
+- **Required Headers**: `Authorization: Bearer {access_token}`
+
+### Core Resources
+- **Pins**: Individual pieces of content (images, videos) saved to Pinterest
+- **Boards**: Collections that organize Pins by theme or topic
+- **Sections**: Subsections within Boards for additional organization
+- **User Account**: Pinterest user profile and account information
+- **Ad Accounts**: Business accounts for advertising functionality
+
+### Access Levels
+- **Public Access**: Read-only access to public data
+- **User Authorization**: Full access to user's Pins, Boards, and account
+- **Business Access**: Additional analytics and ad account management (requires appropriate roles)
+
+## Quick Reference
+
+### OAuth 2.0 Authentication Flow
+
+#### Step 1: Generate Authorization URL
+```javascript
+// Redirect user to Pinterest authorization page
+const authUrl = `https://www.pinterest.com/oauth/?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&scope=boards:read,pins:read,user_accounts:read`;
+
+window.location.href = authUrl;
+```
+
+#### Step 2: Exchange Code for Access Token
+```bash
+# After user authorizes, exchange authorization code for access token
+curl -X POST https://api.pinterest.com/v5/oauth/token \
+  --header "Authorization: Basic {BASE64_ENCODED_CLIENT_CREDENTIALS}" \
+  --header "Content-Type: application/x-www-form-urlencoded" \
+  --data-urlencode "grant_type=authorization_code" \
+  --data-urlencode "code={AUTHORIZATION_CODE}" \
+  --data-urlencode "redirect_uri={REDIRECT_URI}"
+```
+
+**Base64 Encoding Client Credentials:**
+```bash
+# Encode client_id:client_secret
+echo -n "your_client_id:your_client_secret" | base64
+```
+
+**Response:**
+```json
+{
+  "access_token": "pina_ABC123...",
+  "token_type": "bearer",
+  "expires_in": 2592000,
+  "refresh_token": "DEF456...",
+  "scope": "boards:read,pins:read,user_accounts:read"
+}
+```
+
+### Pin Management
+
+#### Create a Pin
+```bash
+curl -X POST https://api.pinterest.com/v5/pins \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "link": "https://example.com/my-article",
+    "title": "My Amazing Pin Title",
+    "description": "Detailed description of the pin content",
+    "board_id": "123456789",
+    "media_source": {
+      "source_type": "image_url",
+      "url": "https://example.com/image.jpg"
+    }
+  }'
+```
+
+#### Get Pin Details
+```bash
+curl -X GET https://api.pinterest.com/v5/pins/{PIN_ID} \
+  -H "Authorization: Bearer {ACCESS_TOKEN}"
+```
+
+**Response:**
+```json
+{
+  "id": "987654321",
+  "created_at": "2025-01-15T10:30:00",
+  "link": "https://example.com/my-article",
+  "title": "My Amazing Pin Title",
+  "description": "Detailed description of the pin content",
+  "board_id": "123456789",
+  "media": {
+    "media_type": "image",
+    "images": {
+      "150x150": { "url": "...", "width": 150, "height": 150 },
+      "400x300": { "url": "...", "width": 400, "height": 300 },
+      "originals": { "url": "...", "width": 1200, "height": 800 }
+    }
+  }
+}
+```
+
+#### Update a Pin
+```bash
+curl -X PATCH https://api.pinterest.com/v5/pins/{PIN_ID} \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Updated Pin Title",
+    "description": "Updated description",
+    "link": "https://example.com/updated-link"
+  }'
+```
+
+#### Delete a Pin
+```bash
+curl -X DELETE https://api.pinterest.com/v5/pins/{PIN_ID} \
+  -H "Authorization: Bearer {ACCESS_TOKEN}"
+```
+
+### Board Management
+
+#### Create a Board
+```bash
+curl -X POST https://api.pinterest.com/v5/boards \
+  -H "Authorization: Bearer {ACCESS_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "My New Board",
+    "description": "A collection of my favorite ideas",
+    "privacy": "PUBLIC"
+  }'
+```
+
+**Privacy Options:** `PUBLIC`, `PROTECTED`, `SECRET`
+
+#### List User's Boards
+```bash
+curl -X GET https://api.pinterest.com/v5/boards \
+  -H "Authorization: Bearer {ACCESS_TOKEN}"
+```
+
+#### Get Board Pins
+```bash
+curl -X GET https://api.pinterest.com/v5/boards/{BOARD_ID}/pins \
+  -H "Authorization: Bearer {ACCESS_TOKEN}"
+```
+
+### User Account
+
+#### Get Current User Account
+```bash
+curl -X GET https://api.pinterest.com/v5/user_account \
+  -H "Authorization: Bearer {ACCESS_TOKEN}"
+```
+
+**Response:**
+```json
+{
+  "account_type": "BUSINESS",
+  "id": "123456789",
+  "username": "myusername",
+  "website_url": "https://example.com",
+  "profile_image": "https://i.pinimg.com/...",
+  "follower_count": 1500,
+  "following_count": 320,
+  "board_count": 25,
+  "pin_count": 450
+}
+```
+
+### Analytics
+
+#### Get Pin Analytics
+```bash
+curl -X GET "https://api.pinterest.com/v5/pins/{PIN_ID}/analytics?start_date=2025-01-01&end_date=2025-01-31&metric_types=IMPRESSION,SAVE,PIN_CLICK" \
+  -H "Authorization: Bearer {ACCESS_TOKEN}"
+```
+
+**Available Metrics:**
+- `IMPRESSION` - Number of times pin was shown
+- `SAVE` - Number of times pin was saved
+- `PIN_CLICK` - Number of clicks to pin destination
+- `OUTBOUND_CLICK` - Clicks to external website
+- `VIDEO_START` - Video plays started
+
+**Response:**
+```json
+{
+  "all": {
+    "daily_metrics": [
+      {
+        "date": "2025-01-01",
+        "data_status": "READY",
+        "metrics": {
+          "IMPRESSION": 1250,
+          "SAVE": 45,
+          "PIN_CLICK": 89
+        }
+      }
+    ]
+  }
+}
+```
+
+### Error Handling
+
+#### Common Error Response
+```json
+{
+  "code": 3,
+  "message": "Requested pin not found"
+}
+```
+
+**Common Error Codes:**
+- `1` - Invalid request parameters
+- `2` - Rate limit exceeded
+- `3` - Resource not found
+- `4` - Insufficient permissions
+- `8` - Invalid access token
+
+#### Python Error Handling Example
+```python
+import requests
+
+def create_pin(access_token, board_id, title, image_url):
+    url = "https://api.pinterest.com/v5/pins"
+    headers = {
+        "Authorization": f"Bearer {access_token}",
+        "Content-Type": "application/json"
+    }
+    data = {
+        "board_id": board_id,
+        "title": title,
+        "media_source": {
+            "source_type": "image_url",
+            "url": image_url
+        }
+    }
+
+    try:
+        response = requests.post(url, headers=headers, json=data)
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.HTTPError as e:
+        error_data = e.response.json()
+        print(f"Error {error_data.get('code')}: {error_data.get('message')}")
+        return None
+    except requests.exceptions.RequestException as e:
+        print(f"Request failed: {str(e)}")
+        return None
+```
+
+### JavaScript/Node.js Integration
+
+```javascript
+// Pinterest API Client Example
+class PinterestClient {
+  constructor(accessToken) {
+    this.accessToken = accessToken;
+    this.baseUrl = 'https://api.pinterest.com/v5';
+  }
+
+  async request(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const headers = {
+      'Authorization': `Bearer ${this.accessToken}`,
+      'Content-Type': 'application/json',
+      ...options.headers
+    };
+
+    const response = await fetch(url, {
+      ...options,
+      headers
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(`Pinterest API Error: ${error.message}`);
+    }
+
+    return response.json();
+  }
+
+  async createPin(boardId, title, imageUrl, description = '', link = '') {
+    return this.request('/pins', {
+      method: 'POST',
+      body: JSON.stringify({
+        board_id: boardId,
+        title: title,
+        description: description,
+        link: link,
+        media_source: {
+          source_type: 'image_url',
+          url: imageUrl
+        }
+      })
+    });
+  }
+
+  async getUserBoards() {
+    return this.request('/boards');
+  }
+
+  async getPinAnalytics(pinId, startDate, endDate) {
+    const params = new URLSearchParams({
+      start_date: startDate,
+      end_date: endDate,
+      metric_types: 'IMPRESSION,SAVE,PIN_CLICK'
+    });
+    return this.request(`/pins/${pinId}/analytics?${params}`);
+  }
+}
+
+// Usage
+const client = new PinterestClient('your_access_token');
+const pin = await client.createPin('board_id', 'Pin Title', 'https://example.com/image.jpg');
+```
+
+## Reference Files
+
+This skill includes comprehensive documentation in `references/`:
+
+- **api.md** - Complete Pinterest API v5 endpoint reference extracted from official documentation
+
+Use `view` to read reference files when detailed information about specific endpoints is needed.
+
+## Working with This Skill
+
+### For Beginners
+1. Start by understanding OAuth 2.0 authentication flow (see Quick Reference above)
+2. Get your API credentials from Pinterest Developer Portal
+3. Test authentication with curl commands before implementing in your application
+4. Use the provided Python/JavaScript examples as starting templates
+
+### For API Integration
+1. Implement OAuth flow to obtain access tokens
+2. Store refresh tokens securely for long-term access
+3. Use the Pin/Board management examples for CRUD operations
+4. Implement proper error handling for rate limits and API errors
+
+### For Analytics & Business Features
+1. Ensure you have appropriate business account access
+2. Use analytics endpoints to track Pin performance
+3. Aggregate metrics across date ranges for reporting
+4. Implement caching to avoid unnecessary API calls
+
+### Best Practices
+- **Token Security**: Never expose access tokens in client-side code or version control
+- **Rate Limiting**: Implement exponential backoff for rate limit errors
+- **Pagination**: Use cursor-based pagination for large result sets
+- **Webhooks**: Consider using webhooks for real-time updates instead of polling
+- **Scopes**: Request only the minimum OAuth scopes needed for your application
+
+## Common Patterns
+
+### Pagination
+```bash
+# Initial request
+curl -X GET "https://api.pinterest.com/v5/boards/{BOARD_ID}/pins?page_size=25" \
+  -H "Authorization: Bearer {ACCESS_TOKEN}"
+
+# Follow-up with bookmark from response
+curl -X GET "https://api.pinterest.com/v5/boards/{BOARD_ID}/pins?page_size=25&bookmark={BOOKMARK}" \
+  -H "Authorization: Bearer {ACCESS_TOKEN}"
+```
+
+### Bulk Operations
+```python
+# Create multiple pins efficiently
+def bulk_create_pins(access_token, board_id, pin_data_list):
+    results = []
+    for pin_data in pin_data_list:
+        result = create_pin(
+            access_token,
+            board_id,
+            pin_data['title'],
+            pin_data['image_url']
+        )
+        results.append(result)
+        time.sleep(0.5)  # Respect rate limits
+    return results
+```
+
+## Resources
+
+### Official Documentation
+- Pinterest API v5 Docs: https://developers.pinterest.com/docs/api/v5/
+- API Quickstart: https://github.com/pinterest/api-quickstart
+- OAuth Documentation: https://developers.pinterest.com/docs/getting-started/authentication/
+
+### OAuth Scopes
+Common scopes you'll need:
+- `boards:read` - Read board data
+- `boards:write` - Create/update boards
+- `pins:read` - Read pin data
+- `pins:write` - Create/update pins
+- `user_accounts:read` - Read user account data
+- `ads:read` - Read ad account analytics (business accounts)
+
+### Rate Limits
+- Pinterest implements per-user rate limiting
+- Typical limits: 1000 requests per hour per user
+- Rate limit headers in response:
+  - `X-RateLimit-Limit`
+  - `X-RateLimit-Remaining`
+  - `X-RateLimit-Reset`
+
+## Notes
+
+- Pinterest API v5 is the current version (as of 2025)
+- All endpoints require authentication via OAuth 2.0
+- Access tokens expire after 30 days
+- Use refresh tokens to obtain new access tokens
+- Business accounts have access to additional analytics features
+- Video pins require special handling compared to image pins
+- Some features require app review by Pinterest
+
+## Troubleshooting
+
+### "Invalid access token"
+- Verify token hasn't expired (30-day lifetime)
+- Use refresh token to obtain new access token
+- Check Authorization header format: `Bearer {token}`
+
+### "Insufficient permissions"
+- Verify OAuth scopes include required permissions
+- Business features require verified business account
+- Some operations require board/pin ownership
+
+### "Rate limit exceeded"
+- Implement exponential backoff
+- Cache responses when possible
+- Use webhooks instead of polling
+- Check `X-RateLimit-Reset` header for retry time
+
+### "Media upload failed"
+- Verify image URL is publicly accessible
+- Check image meets size requirements (max 10MB)
+- Ensure image format is supported (JPG, PNG, GIF)
+- For video, use video-specific endpoints
+
+## Updating
+
+This skill was generated from Pinterest's official API documentation. To get the latest API changes:
+1. Visit https://developers.pinterest.com/docs/api/v5/
+2. Check changelog for API updates
+3. Review deprecation notices
+4. Update OAuth scopes if new features added
--- a/skills/pinterest-api/plugin.json
+++ b/skills/pinterest-api/plugin.json
@@ -0,0 +1,15 @@
+{
+  "name": "pinterest-api",
+  "description": "Interacts with the Pinterest API.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Tim Green",
+    "email": "rawveg@gmail.com"
+  },
+  "homepage": "https://github.com/rawveg/claude-skills-marketplace",
+  "repository": "https://github.com/rawveg/claude-skills-marketplace",
+  "license": "MIT",
+  "keywords": ["pinterest-api", "pinterest", "social media", "social media marketing", "Claude Code"],
+  "category": "productivity",
+  "strict": false
+}
--- a/skills/pinterest-api/references/api.md
+++ b/skills/pinterest-api/references/api.md
--- a/skills/pinterest-api/references/index.md
+++ b/skills/pinterest-api/references/index.md
@@ -0,0 +1,7 @@
+# Pinterest-Api Documentation Index
+
+## Categories
+
+### Api
+**File:** `api.md`
+**Pages:** 1
--- a/skills/pinterest-api/references/llms-full.md
+++ b/skills/pinterest-api/references/llms-full.md
--- a/skills/pinterest-api/references/llms-small.md
+++ b/skills/pinterest-api/references/llms-small.md
--- a/skills/pinterest-api/references/llms.md
+++ b/skills/pinterest-api/references/llms.md