Initial commit

2025-11-30 08:50:26 +08:00
commit 0e81d24079
7 changed files with 3879 additions and 0 deletions
--- a/skills/hashnode-api/SKILL.md
+++ b/skills/hashnode-api/SKILL.md
@@ -0,0 +1,429 @@
+---
+name: hashnode-api
+description: Hashnode GraphQL API documentation for creating, managing, and querying blogs, posts, publications, and user data on the Hashnode platform
+---
+
+# Hashnode API Skill
+
+Comprehensive assistance with the Hashnode GraphQL API for blog management, content creation, and user interaction on the Hashnode platform.
+
+## When to Use This Skill
+
+This skill should be triggered when:
+- Building integrations with Hashnode blogs or publications
+- Querying Hashnode posts, users, or publication data
+- Creating, publishing, or managing blog posts via API
+- Implementing authentication with Hashnode Personal Access Tokens
+- Working with GraphQL queries or mutations for Hashnode
+- Debugging Hashnode API responses or error codes
+- Setting up pagination (cursor-based or offset-based) for Hashnode data
+- Implementing newsletter subscriptions, comments, or user interactions
+- Migrating from the legacy Hashnode API to the new GQL endpoint
+
+## Key Concepts
+
+### API Endpoint
+All Hashnode API requests go through a single GraphQL endpoint:
+- **Endpoint:** `https://gql.hashnode.com` (POST only)
+- **Playground:** Visit the same URL in a browser to explore the API
+- **Legacy API:** `https://api.hashnode.com` is discontinued - migrate to new endpoint
+
+### Authentication
+- Most queries work without authentication
+- Sensitive fields (drafts, email, etc.) require authentication
+- All mutations require authentication
+- **Authentication method:** Add `Authorization` header with your Personal Access Token (PAT)
+- **Get your PAT:** https://hashnode.com/settings/developer → "Generate New Token"
+
+### Rate Limits
+- **Queries:** 20,000 requests per minute
+- **Mutations:** 500 requests per minute
+
+### Caching
+- Almost all query responses are cached on the Edge
+- Cache is automatically purged when you mutate data
+- Check cache status in playground (bottom right: HIT/MISS)
+- **Important:** Always request the `id` field to avoid stale data
+
+### Error Codes
+Common GraphQL error codes:
+- `GRAPHQL_VALIDATION_FAILED` - Invalid query structure
+- `UNAUTHENTICATED` - Missing or invalid auth token
+- `FORBIDDEN` - Insufficient permissions
+- `BAD_USER_INPUT` - Invalid input data
+- `NOT_FOUND` - Resource doesn't exist
+
+## Quick Reference
+
+### 1. Fetch Publication Details
+
+```graphql
+query Publication {
+  publication(host: "blog.developerdao.com") {
+    id
+    isTeam
+    title
+    about {
+      markdown
+    }
+  }
+}
+```
+
+Get basic information about a publication by its hostname.
+
+### 2. Fetch Recent Blog Posts
+
+```graphql
+query Publication {
+  publication(host: "blog.developerdao.com") {
+    id
+    isTeam
+    title
+    posts(first: 10) {
+      edges {
+        node {
+          id
+          title
+          brief
+          url
+        }
+      }
+      pageInfo {
+        endCursor
+        hasNextPage
+      }
+    }
+  }
+}
+```
+
+Retrieve the latest 10 posts from a publication with cursor-based pagination support.
+
+### 3. Fetch a Single Article by Slug
+
+```graphql
+query Publication {
+  publication(host: "blog.developerdao.com") {
+    id
+    post(slug: "the-developers-guide-to-chainlink-vrf-foundry-edition") {
+      id
+      title
+      content {
+        markdown
+        html
+      }
+    }
+  }
+}
+```
+
+Get full content of a specific article using its slug and publication hostname.
+
+### 4. Cursor-Based Pagination (Infinite Scroll)
+
+```graphql
+query Publication {
+  publication(host: "blog.developerdao.com") {
+    id
+    posts(
+      first: 10
+      after: "NjQxZTc4NGY0M2NiMzc2YjAyNzNkMzU4XzIwMjMtMDMtMjVUMDQ6Mjc6NTkuNjQxWg=="
+    ) {
+      edges {
+        node {
+          id
+          title
+          brief
+          url
+        }
+      }
+      pageInfo {
+        endCursor
+        hasNextPage
+      }
+    }
+  }
+}
+```
+
+Use `endCursor` from previous response as `after` parameter to fetch next page.
+
+### 5. Offset-Based Pagination (Traditional Pages)
+
+```graphql
+query Followers {
+  user(username: "SandroVolpicella") {
+    id
+    followers(pageSize: 10, page: 1) {
+      nodes {
+        id
+        username
+      }
+      pageInfo {
+        hasNextPage
+        hasPreviousPage
+        previousPage
+        nextPage
+      }
+    }
+  }
+}
+```
+
+Navigate between pages using explicit page numbers.
+
+### 6. Get Entity Count (Series Count Example)
+
+```graphql
+query SeriesCount {
+  publication(host: "engineering.hashnode.com") {
+    id
+    seriesList(first: 0) {
+      totalDocuments
+    }
+  }
+}
+```
+
+Result:
+```json
+{
+  "data": {
+    "publication": {
+      "seriesList": {
+        "totalDocuments": 3
+      }
+    }
+  }
+}
+```
+
+Use `totalDocuments` field to get counts without fetching all data.
+
+### 7. Fetch Posts from a Series
+
+```graphql
+query Publication {
+  publication(host: "lo-victoria.com") {
+    id
+    series(slug: "graphql") {
+      id
+      name
+      posts(first: 10) {
+        edges {
+          node {
+            id
+            title
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Get all posts belonging to a specific series.
+
+### 8. Fetch Static Pages
+
+```graphql
+query Publication {
+  publication(host: "lo-victoria.com") {
+    id
+    staticPages(first: 10) {
+      edges {
+        node {
+          id
+          title
+          slug
+        }
+      }
+    }
+  }
+}
+```
+
+Retrieve custom static pages like "About", "Contact", etc.
+
+### 9. Fetch Single Static Page
+
+```graphql
+query Publication {
+  publication(host: "lo-victoria.com") {
+    id
+    staticPage(slug: "about") {
+      id
+      title
+      content {
+        markdown
+      }
+    }
+  }
+}
+```
+
+Get content of a specific static page by slug.
+
+### 10. Authentication Example - Get Drafts (Requires Auth)
+
+```graphql
+query Publication($first: Int!, $host: String) {
+  publication(host: $host) {
+    id
+    drafts(first: $first) {
+      edges {
+        node {
+          id
+          title
+        }
+      }
+    }
+  }
+}
+```
+
+**Headers:**
+```json
+{
+  "Authorization": "your-personal-access-token-here"
+}
+```
+
+Variables:
+```json
+{
+  "first": 10,
+  "host": "your-blog-host.hashnode.dev"
+}
+```
+
+Drafts can only be queried by the publication owner with valid authentication.
+
+## Reference Files
+
+This skill includes comprehensive documentation in `references/`:
+
+- **api.md** - Complete Hashnode GraphQL API documentation including:
+  - GQL Playground overview
+  - Caching behavior and best practices
+  - Rate limits and authentication
+  - Status codes and error handling
+  - Pagination methods (cursor-based and offset-based)
+  - Migration guide from legacy API
+  - Query and mutation examples
+  - Full list of available queries and mutations
+
+Use the reference files for detailed information about specific API features, error handling patterns, and advanced query techniques.
+
+## Working with This Skill
+
+### For Beginners
+Start by understanding the core concepts above, then explore:
+1. **API Endpoint:** Test queries in the playground at https://gql.hashnode.com
+2. **Authentication:** Generate your PAT at https://hashnode.com/settings/developer
+3. **Basic Queries:** Try fetching publication details and blog posts first
+4. **Pagination:** Start with cursor-based pagination for simple infinite scroll
+
+### For Intermediate Users
+Focus on:
+1. **Authentication flows:** Implement PAT-based auth in your application
+2. **Error handling:** Handle GraphQL error codes properly
+3. **Pagination strategies:** Choose between cursor-based and offset-based based on your UI needs
+4. **Caching considerations:** Always request `id` fields to avoid stale data
+5. **Content extraction:** Work with both markdown and HTML content formats
+
+### For Advanced Users
+Explore:
+1. **Mutations:** Publishing posts, managing drafts, updating content
+2. **Complex queries:** Nested queries with multiple levels (publication → series → posts)
+3. **Batch operations:** Optimize API calls with GraphQL field selection
+4. **Webhook integration:** Handle Hashnode webhook events
+5. **Rate limit optimization:** Implement efficient request batching
+
+### Navigation Tips
+- **Start broad → go deep:** Begin with publication queries, then drill into specific posts/series
+- **Check authentication:** If you get `UNAUTHENTICATED` errors, verify your PAT is in the Authorization header
+- **Test in playground:** Use https://gql.hashnode.com to test queries before implementing
+- **Monitor cache:** Watch cache HIT/MISS status to optimize your queries
+- **Read error messages:** GraphQL errors include helpful details in the `extensions.code` field
+
+## Common Use Cases
+
+### Building a Blog Frontend
+1. Fetch publication metadata
+2. Get post list with pagination
+3. Display individual posts by slug
+4. Implement series/category navigation
+5. Show static pages (about, contact)
+
+### Content Management Dashboard
+1. Authenticate with PAT
+2. List and manage drafts
+3. Publish/update posts
+4. Schedule content
+5. Monitor analytics
+
+### Newsletter Integration
+1. Subscribe/unsubscribe users
+2. Fetch subscriber counts
+3. Manage email preferences
+4. Track engagement metrics
+
+### Migration from Legacy API
+1. Update endpoint from `api.hashnode.com` to `gql.hashnode.com`
+2. Convert REST calls to GraphQL queries
+3. Update authentication mechanism (check docs)
+4. Adjust pagination from old format to cursor/offset-based
+5. Update error handling for new error codes
+
+## Resources
+
+### Official Documentation
+- **API Docs:** https://apidocs.hashnode.com
+- **Playground:** https://gql.hashnode.com
+- **Discord:** Join for updates and community support
+- **GraphQL Guide:** freeCodeCamp's beginner-friendly GraphQL guide
+
+### references/
+The `api.md` reference file contains:
+- Complete API specification
+- All available queries and mutations
+- Detailed parameter descriptions
+- Authentication requirements
+- Code examples with proper syntax
+- Links to original documentation
+- Comprehensive error code reference
+
+## Important Notes
+
+- **Always request the `id` field** on objects to avoid stale cached data
+- **Rate limits are generous** but respect them for production apps
+- **Cache behavior:** Most responses are cached; mutations automatically purge related cache
+- **Breaking changes are rare** and announced well in advance on Discord
+- **Legacy API is shut down** - use `gql.hashnode.com` only
+
+## Troubleshooting
+
+### Getting UNAUTHENTICATED errors?
+- Verify your Personal Access Token is valid
+- Check the `Authorization` header is set correctly
+- Ensure you're requesting fields that require auth (drafts, email, etc.)
+
+### Not seeing latest data?
+- Always request the `id` field to avoid stale cached data
+- Check if response is HIT/MISS in playground
+
+### Query validation failed?
+- Verify your GraphQL syntax in the playground first
+- Check required parameters are provided
+- Ensure field names match the schema
+
+### Rate limit reached?
+- Queries: 20k/min is very generous - optimize your queries
+- Mutations: 500/min limit - batch operations where possible
+- Use caching on your end to reduce API calls
+
+## Updating
+
+This skill was automatically generated from official Hashnode documentation. To refresh with updated documentation, regenerate the skill using the latest docs from https://apidocs.hashnode.com.