From 7d7cb0568a88f3adc2cb303250e7fab3eab9ddf1 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:51:02 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 56 ++++ skills/threads-api/SKILL.md | 388 +++++++++++++++++++++++++ skills/threads-api/plugin.json | 15 + skills/threads-api/references/index.md | 7 + skills/threads-api/references/other.md | 11 + 7 files changed, 492 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/threads-api/SKILL.md create mode 100644 skills/threads-api/plugin.json create mode 100644 skills/threads-api/references/index.md create mode 100644 skills/threads-api/references/other.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..756dd05 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "threads-api", + "description": "Interacts with the Threads API.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Tim Green", + "email": "rawveg@gmail.com" + }, + "skills": [ + "./skills/threads-api" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..9d7c0cd --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# threads-api + +Interacts with the Threads API. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..9279f68 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,56 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:rawveg/skillsforge-marketplace:threads-api", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "03e34b67239d310509ac23eac3377a38cd31c78b", + "treeHash": "717b9cbe4d9e75085b7f659bbaa02ad1bb99ca8e00e415a19cfeeaa919fcd264", + "generatedAt": "2025-11-28T10:27:54.242402Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "threads-api", + "description": "Interacts with the Threads API." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "7950cd36f84961142c3cf5a00c9b101fda44ace6c07ab1d52c4b00e3714f90d9" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "ae87907935aa29b641d6b63cb10762c6bb15f5db6917e96580533000c2daf1f9" + }, + { + "path": "skills/threads-api/plugin.json", + "sha256": "eb04d492580c19e7387854afea0a65834c7dc0238f4e45fa3b75aee79172969a" + }, + { + "path": "skills/threads-api/SKILL.md", + "sha256": "0fdd50462ebff82fa07ceea4f61810d059fffca2ebf02853c888b48ed7e696e1" + }, + { + "path": "skills/threads-api/references/index.md", + "sha256": "b7eef2e34cd9a093146c40fca59c8ad070c273dd612cb2f3a06b9c90f80e2e5e" + }, + { + "path": "skills/threads-api/references/other.md", + "sha256": "e1c1ff18089b50410fea1343b6153832dce8ad57be8b42c3b4298305a5f0023a" + } + ], + "dirSha256": "717b9cbe4d9e75085b7f659bbaa02ad1bb99ca8e00e415a19cfeeaa919fcd264" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/threads-api/SKILL.md b/skills/threads-api/SKILL.md new file mode 100644 index 0000000..8045a54 --- /dev/null +++ b/skills/threads-api/SKILL.md @@ -0,0 +1,388 @@ +--- +name: threads-api +description: Threads API Documentation +--- + +# Threads API Skill + +Comprehensive assistance with Meta's Threads API development for building applications that integrate with the Threads social platform. + +## When to Use This Skill + +This skill should be triggered when you are: +- **Building Threads integrations** - Creating apps that post to or read from Threads +- **Implementing authentication** - Setting up OAuth flows for Threads API access +- **Working with media uploads** - Uploading images, videos, or carousel posts to Threads +- **Managing user content** - Publishing, retrieving, or managing Threads posts +- **Fetching analytics** - Retrieving insights and metrics for Threads content +- **Handling webhooks** - Processing real-time updates from Threads +- **Troubleshooting API errors** - Debugging authentication, rate limits, or API responses +- **Reading Threads profiles** - Fetching user profile data and posts + +## Quick Reference + +### Authentication - Getting an Access Token + +```javascript +// Step 1: Redirect user to authorization endpoint +const authUrl = `https://threads.net/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=threads_basic,threads_content_publish&response_type=code`; + +// Step 2: Exchange authorization code for access token +const response = await fetch('https://graph.threads.net/oauth/access_token', { + method: 'POST', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + body: new URLSearchParams({ + client_id: CLIENT_ID, + client_secret: CLIENT_SECRET, + grant_type: 'authorization_code', + redirect_uri: REDIRECT_URI, + code: authorizationCode + }) +}); + +const { access_token } = await response.json(); +``` + +### Publishing a Text Post + +```javascript +// Create a simple text post +const response = await fetch(`https://graph.threads.net/v1.0/me/threads`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Authorization': `Bearer ${accessToken}` + }, + body: JSON.stringify({ + media_type: 'TEXT', + text: 'Hello from Threads API! 🎉' + }) +}); + +const data = await response.json(); +console.log('Post ID:', data.id); +``` + +### Publishing an Image Post + +```python +import requests + +# Upload and publish an image +url = "https://graph.threads.net/v1.0/me/threads" +headers = {"Authorization": f"Bearer {access_token}"} + +data = { + "media_type": "IMAGE", + "image_url": "https://example.com/image.jpg", + "text": "Check out this image! #API" +} + +response = requests.post(url, headers=headers, json=data) +post_id = response.json()["id"] +print(f"Posted image with ID: {post_id}") +``` + +### Publishing a Video Post + +```javascript +// Step 1: Create a video container +const container = await fetch(`https://graph.threads.net/v1.0/me/threads`, { + method: 'POST', + headers: { 'Authorization': `Bearer ${accessToken}` }, + body: JSON.stringify({ + media_type: 'VIDEO', + video_url: 'https://example.com/video.mp4', + text: 'Check out this video!' + }) +}); + +const { id: containerId } = await container.json(); + +// Step 2: Publish the container +await fetch(`https://graph.threads.net/v1.0/me/threads_publish`, { + method: 'POST', + headers: { 'Authorization': `Bearer ${accessToken}` }, + body: JSON.stringify({ creation_id: containerId }) +}); +``` + +### Fetching User Profile + +```python +import requests + +# Get authenticated user's profile +url = f"https://graph.threads.net/v1.0/me" +headers = {"Authorization": f"Bearer {access_token}"} +params = { + "fields": "id,username,name,threads_profile_picture_url,threads_biography" +} + +response = requests.get(url, headers=headers, params=params) +profile = response.json() + +print(f"Username: {profile['username']}") +print(f"Bio: {profile['threads_biography']}") +``` + +### Fetching User's Threads + +```javascript +// Get user's recent threads with pagination +const response = await fetch( + `https://graph.threads.net/v1.0/me/threads?fields=id,text,timestamp,media_url&limit=25`, + { + headers: { 'Authorization': `Bearer ${accessToken}` } + } +); + +const { data, paging } = await response.json(); +data.forEach(thread => { + console.log(`${thread.timestamp}: ${thread.text}`); +}); + +// Use paging.next for next page +``` + +### Publishing a Carousel Post + +```python +import requests + +# Create a carousel with multiple images +url = "https://graph.threads.net/v1.0/me/threads" +headers = {"Authorization": f"Bearer {access_token}"} + +data = { + "media_type": "CAROUSEL", + "children": [ + {"media_type": "IMAGE", "image_url": "https://example.com/img1.jpg"}, + {"media_type": "IMAGE", "image_url": "https://example.com/img2.jpg"}, + {"media_type": "IMAGE", "image_url": "https://example.com/img3.jpg"} + ], + "text": "Swipe through these images! 📸" +} + +response = requests.post(url, headers=headers, json=data) +carousel_id = response.json()["id"] +``` + +### Retrieving Insights (Analytics) + +```javascript +// Get insights for a specific thread +const threadId = '123456789'; +const response = await fetch( + `https://graph.threads.net/v1.0/${threadId}/insights?metric=views,likes,replies,reposts`, + { + headers: { 'Authorization': `Bearer ${accessToken}` } + } +); + +const { data } = await response.json(); +data.forEach(metric => { + console.log(`${metric.name}: ${metric.values[0].value}`); +}); +``` + +### Error Handling Pattern + +```python +import requests + +def make_threads_request(url, access_token, method='GET', **kwargs): + """Robust error handling for Threads API requests""" + headers = kwargs.pop('headers', {}) + headers['Authorization'] = f"Bearer {access_token}" + + try: + response = requests.request(method, url, headers=headers, **kwargs) + response.raise_for_status() + return response.json() + + except requests.exceptions.HTTPError as e: + error_data = e.response.json() + error_code = error_data.get('error', {}).get('code') + error_msg = error_data.get('error', {}).get('message') + + if error_code == 190: + raise Exception(f"Invalid access token: {error_msg}") + elif error_code == 32: + raise Exception(f"Rate limit exceeded: {error_msg}") + else: + raise Exception(f"API Error {error_code}: {error_msg}") + + except requests.exceptions.RequestException as e: + raise Exception(f"Network error: {str(e)}") +``` + +## Key Concepts + +### Access Tokens and Permissions +- **Access Tokens**: OAuth 2.0 tokens required for all API requests +- **Scopes**: Define what your app can access (e.g., `threads_basic`, `threads_content_publish`, `threads_manage_insights`) +- **Token Expiration**: Long-lived tokens (60 days) and refresh tokens for extended access + +### Media Types +- **TEXT**: Simple text posts +- **IMAGE**: Single image with optional caption +- **VIDEO**: Single video with optional caption +- **CAROUSEL**: Multiple images or videos in a swipeable format + +### Publishing Flow +1. **Container Creation**: Create a media container with content +2. **Publishing**: Publish the container to make it visible +3. **Two-stage process**: Required for videos and carousels to allow processing time + +### Rate Limits +- Rate limits vary by endpoint and access level +- Standard rate limit: 200 calls per hour per user +- Monitor `X-Business-Use-Case-Usage` header in responses +- Implement exponential backoff for rate limit errors + +### Webhooks +- Real-time notifications for events like mentions, replies, or new followers +- Requires HTTPS endpoint for receiving notifications +- Must validate webhook signatures for security + +## Reference Files + +This skill includes comprehensive documentation in `references/`: + +- **other.md** - Complete Threads API documentation including: + - Authentication and authorization flows + - API endpoints reference + - Request/response formats + - Error codes and troubleshooting + - Best practices and guidelines + +Use the skill's reference files when you need detailed information about specific API endpoints, parameters, or advanced features. + +## Working with This Skill + +### For Beginners +Start by understanding the authentication flow - this is the foundation of all Threads API integrations. Focus on: +1. Setting up your Meta developer account and app +2. Implementing OAuth 2.0 authorization +3. Making your first API request to fetch user profile +4. Publishing a simple text post + +### For Intermediate Users +Build on the basics by exploring: +1. Media uploads (images and videos) +2. Carousel posts for multi-image content +3. Webhook integration for real-time updates +4. Error handling and retry logic +5. Rate limit management + +### For Advanced Users +Optimize your integration with: +1. Insights and analytics data +2. Batch operations for efficiency +3. Advanced content scheduling +4. Custom webhook event processing +5. Multi-account management + +### Navigation Tips +- **Quick Reference**: Use the code examples above for common tasks +- **Reference Files**: Dive into `references/other.md` for complete API documentation +- **Authentication First**: Always start with proper authentication setup +- **Test in Sandbox**: Use Meta's test users and sandbox environment during development + +## Common Workflows + +### Complete Post Publishing Flow +1. Obtain access token via OAuth flow +2. Create media container (if using images/videos) +3. Wait for container processing (for videos) +4. Publish the container +5. Retrieve post ID and insights + +### User Data Retrieval Flow +1. Authenticate user +2. Fetch user profile with required fields +3. Retrieve user's threads with pagination +4. Process and display content + +### Webhook Integration Flow +1. Set up HTTPS endpoint +2. Register webhook subscription +3. Validate webhook signatures +4. Process incoming events +5. Respond with 200 OK status + +## Best Practices + +1. **Security** + - Never expose access tokens in client-side code + - Always validate webhook signatures + - Use environment variables for sensitive data + - Implement token refresh before expiration + +2. **Performance** + - Cache API responses when appropriate + - Use batch requests for multiple operations + - Implement pagination for large result sets + - Monitor and respect rate limits + +3. **User Experience** + - Provide clear error messages to users + - Show loading states during API calls + - Handle network failures gracefully + - Request only necessary permissions + +4. **Content Publishing** + - Validate media URLs before uploading + - Check media format requirements + - Add appropriate error handling for failed uploads + - Consider using alt text for accessibility + +## Resources + +### Official Documentation +- Meta for Developers: https://developers.facebook.com/docs/threads +- API Reference: Available in `references/other.md` + +### Developer Tools +- Meta App Dashboard: Configure your app and manage permissions +- Graph API Explorer: Test API calls interactively +- Webhook Testing: Test webhook endpoints before production + +## Troubleshooting + +### Common Issues + +**Authentication Errors (Code 190)** +- Check access token validity +- Verify token hasn't expired +- Ensure correct permissions/scopes + +**Rate Limit Errors (Code 32)** +- Implement exponential backoff +- Monitor API usage +- Consider caching responses + +**Media Upload Failures** +- Verify media URL is publicly accessible +- Check file format and size requirements +- Ensure proper media_type parameter + +**Webhook Not Receiving Events** +- Verify endpoint is HTTPS +- Check webhook signature validation +- Ensure endpoint responds with 200 OK quickly + +## Notes + +- This skill was generated from Meta's official Threads API documentation +- The Threads API is part of Meta's Graph API family +- API features and endpoints may be updated by Meta - refer to official docs for latest changes +- Some features may require additional app review or permissions from Meta + +## Updating + +To refresh this skill with updated documentation: +1. Visit https://developers.facebook.com/docs/threads for the latest information +2. Re-run the documentation scraper with updated configuration +3. The skill will be rebuilt with current API information diff --git a/skills/threads-api/plugin.json b/skills/threads-api/plugin.json new file mode 100644 index 0000000..6bd064d --- /dev/null +++ b/skills/threads-api/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "threads-api", + "description": "Provides Threads API integration for Claude Code.", + "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": ["threads-api", "threads", "social media", "social media marketing", "Claude Code"], + "category": "productivity", + "strict": false +} diff --git a/skills/threads-api/references/index.md b/skills/threads-api/references/index.md new file mode 100644 index 0000000..9fd6bad --- /dev/null +++ b/skills/threads-api/references/index.md @@ -0,0 +1,7 @@ +# Threads-Api Documentation Index + +## Categories + +### Other +**File:** `other.md` +**Pages:** 1 diff --git a/skills/threads-api/references/other.md b/skills/threads-api/references/other.md new file mode 100644 index 0000000..15d58b2 --- /dev/null +++ b/skills/threads-api/references/other.md @@ -0,0 +1,11 @@ +# Threads-Api - Other + +**Pages:** 1 + +--- + +## Threads API - Documentation - Meta for Developers + +**URL:** https://developers.facebook.com/docs/threads + +---