claude-plugin-wordpress-manager 1.4.0 → 1.7.0

package/skills/wp-headless/references/frontend-integration.md

@@ -0,0 +1,331 @@
+# Frontend Integration
+
+Use this file when connecting a JavaScript frontend framework to a headless WordPress backend.
+
+## Next.js integration
+
+### Data fetching (App Router)
+
+```js
+// lib/wordpress.js
+const WP_URL = process.env.NEXT_PUBLIC_WP_URL || 'https://wp.example.com';
+
+export async function getPosts(page = 1, perPage = 10) {
+    const res = await fetch(
+        `${WP_URL}/wp-json/wp/v2/posts?page=${page}&per_page=${perPage}&_embed`,
+        { next: { revalidate: 60 } } // ISR: revalidate every 60 seconds
+    );
+    if (!res.ok) throw new Error('Failed to fetch posts');
+    return {
+        posts: await res.json(),
+        totalPages: Number(res.headers.get('X-WP-TotalPages')),
+    };
+}
+
+export async function getPost(slug) {
+    const res = await fetch(
+        `${WP_URL}/wp-json/wp/v2/posts?slug=${slug}&_embed`,
+        { next: { revalidate: 60 } }
+    );
+    const posts = await res.json();
+    return posts[0] || null;
+}
+
+export async function getPage(slug) {
+    const res = await fetch(
+        `${WP_URL}/wp-json/wp/v2/pages?slug=${slug}&_embed`,
+        { next: { revalidate: 300 } }
+    );
+    const pages = await res.json();
+    return pages[0] || null;
+}
+```
+
+### Page components
+
+```jsx
+// app/blog/page.js
+import { getPosts } from '@/lib/wordpress';
+
+export default async function BlogPage() {
+    const { posts } = await getPosts();
+
+    return (
+        <main>
+            <h1>Blog</h1>
+            {posts.map((post) => (
+                <article key={post.id}>
+                    <h2>
+                        <a href={`/blog/${post.slug}`}>{post.title.rendered}</a>
+                    </h2>
+                    <div dangerouslySetInnerHTML={{ __html: post.excerpt.rendered }} />
+                </article>
+            ))}
+        </main>
+    );
+}
+
+// app/blog/[slug]/page.js
+import { getPost, getPosts } from '@/lib/wordpress';
+import { notFound } from 'next/navigation';
+
+export async function generateStaticParams() {
+    const { posts } = await getPosts(1, 100);
+    return posts.map((post) => ({ slug: post.slug }));
+}
+
+export default async function PostPage({ params }) {
+    const post = await getPost(params.slug);
+    if (!post) notFound();
+
+    return (
+        <article>
+            <h1>{post.title.rendered}</h1>
+            <div dangerouslySetInnerHTML={{ __html: post.content.rendered }} />
+        </article>
+    );
+}
+```
+
+### ISR (Incremental Static Regeneration)
+
+```js
+// Revalidate on demand via webhook (see webhooks.md)
+// app/api/revalidate/route.js
+import { revalidatePath } from 'next/cache';
+
+export async function POST(request) {
+    const secret = request.headers.get('x-revalidate-secret');
+    if (secret !== process.env.REVALIDATE_SECRET) {
+        return Response.json({ error: 'Invalid secret' }, { status: 401 });
+    }
+
+    const { path } = await request.json();
+    revalidatePath(path);
+    return Response.json({ revalidated: true });
+}
+```
+
+## Nuxt 3 integration
+
+### Composable
+
+```js
+// composables/useWordPress.js
+export function useWordPress() {
+    const config = useRuntimeConfig();
+    const wpUrl = config.public.wpUrl;
+
+    async function getPosts(page = 1) {
+        return useFetch(`${wpUrl}/wp-json/wp/v2/posts`, {
+            params: { page, per_page: 10, _embed: true },
+        });
+    }
+
+    async function getPost(slug) {
+        const { data } = await useFetch(`${wpUrl}/wp-json/wp/v2/posts`, {
+            params: { slug, _embed: true },
+        });
+        return data.value?.[0] || null;
+    }
+
+    return { getPosts, getPost };
+}
+```
+
+### nuxt.config.ts
+
+```ts
+export default defineNuxtConfig({
+    runtimeConfig: {
+        public: {
+            wpUrl: process.env.WP_URL || 'https://wp.example.com',
+        },
+    },
+    routeRules: {
+        '/blog/**': { isr: 60 }, // Revalidate every 60s
+        '/': { isr: 300 },
+    },
+});
+```
+
+## Astro integration
+
+### Data fetching
+
+```astro
+---
+// src/pages/blog/[slug].astro
+import Layout from '@/layouts/Layout.astro';
+
+export async function getStaticPaths() {
+    const res = await fetch(`${import.meta.env.WP_URL}/wp-json/wp/v2/posts?per_page=100`);
+    const posts = await res.json();
+
+    return posts.map((post) => ({
+        params: { slug: post.slug },
+        props: { post },
+    }));
+}
+
+const { post } = Astro.props;
+---
+
+<Layout title={post.title.rendered}>
+    <article>
+        <h1 set:html={post.title.rendered} />
+        <div set:html={post.content.rendered} />
+    </article>
+</Layout>
+```
+
+## WPGraphQL with frontend frameworks
+
+### Apollo Client (React/Next.js)
+
+```js
+// lib/apollo.js
+import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client';
+
+const client = new ApolloClient({
+    link: new HttpLink({
+        uri: `${process.env.NEXT_PUBLIC_WP_URL}/graphql`,
+    }),
+    cache: new InMemoryCache(),
+});
+
+export default client;
+```
+
+### urql (lightweight alternative)
+
+```js
+import { Client, cacheExchange, fetchExchange } from 'urql';
+
+const client = new Client({
+    url: `${process.env.NEXT_PUBLIC_WP_URL}/graphql`,
+    exchanges: [cacheExchange, fetchExchange],
+});
+```
+
+## Rendering WordPress content
+
+### Sanitizing HTML content
+
+```jsx
+// React: dangerouslySetInnerHTML (ensure source is trusted)
+<div dangerouslySetInnerHTML={{ __html: post.content.rendered }} />
+
+// With DOMPurify for extra safety
+import DOMPurify from 'isomorphic-dompurify';
+
+function WPContent({ html }) {
+    const clean = DOMPurify.sanitize(html, {
+        ADD_TAGS: ['iframe'],
+        ADD_ATTR: ['allow', 'allowfullscreen', 'frameborder', 'scrolling'],
+    });
+    return <div dangerouslySetInnerHTML={{ __html: clean }} />;
+}
+```
+
+### Handling WordPress images
+
+```jsx
+// Replace WordPress image URLs with optimized versions
+function optimizeImages(html, wpUrl) {
+    // Replace with Next.js Image optimization
+    return html.replace(
+        /src="([^"]*wp-content\/uploads\/[^"]*)"/g,
+        (match, url) => `src="/_next/image?url=${encodeURIComponent(url)}&w=1200&q=80"`
+    );
+}
+```
+
+### WordPress blocks in React
+
+```jsx
+// Parse block content into React components
+function renderBlock(block) {
+    switch (block.blockName) {
+        case 'core/paragraph':
+            return <p dangerouslySetInnerHTML={{ __html: block.innerHTML }} />;
+        case 'core/heading':
+            return <h2 dangerouslySetInnerHTML={{ __html: block.innerHTML }} />;
+        case 'core/image':
+            return <figure dangerouslySetInnerHTML={{ __html: block.innerHTML }} />;
+        default:
+            return <div dangerouslySetInnerHTML={{ __html: block.innerHTML }} />;
+    }
+}
+```
+
+## SEO in headless WordPress
+
+### Yoast SEO integration
+
+```js
+// Fetch Yoast data from REST API
+// Requires Yoast SEO plugin (adds yoast_head to REST responses)
+export async function getPostSEO(slug) {
+    const res = await fetch(
+        `${WP_URL}/wp-json/wp/v2/posts?slug=${slug}&_fields=yoast_head_json`
+    );
+    const posts = await res.json();
+    return posts[0]?.yoast_head_json || {};
+}
+```
+
+```jsx
+// app/blog/[slug]/page.js
+export async function generateMetadata({ params }) {
+    const seo = await getPostSEO(params.slug);
+    return {
+        title: seo.title,
+        description: seo.description,
+        openGraph: {
+            title: seo.og_title,
+            description: seo.og_description,
+            images: seo.og_image ? [{ url: seo.og_image[0].url }] : [],
+        },
+    };
+}
+```
+
+## Preview mode
+
+```js
+// app/api/preview/route.js (Next.js)
+import { draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+export async function GET(request) {
+    const { searchParams } = new URL(request.url);
+    const secret = searchParams.get('secret');
+    const slug = searchParams.get('slug');
+
+    if (secret !== process.env.WP_PREVIEW_SECRET) {
+        return Response.json({ error: 'Invalid secret' }, { status: 401 });
+    }
+
+    draftMode().enable();
+    redirect(`/blog/${slug}`);
+}
+```
+
+## Verification
+
+```bash
+# Test REST API from frontend origin
+curl -H "Origin: https://app.example.com" \
+  https://wp.example.com/wp-json/wp/v2/posts?per_page=1
+
+# Test _embed returns featured images
+curl -s "https://wp.example.com/wp-json/wp/v2/posts?_embed&per_page=1" | \
+  jq '.[0]._embedded["wp:featuredmedia"][0].source_url'
+
+# Test ISR revalidation
+curl -X POST https://app.example.com/api/revalidate \
+  -H "Content-Type: application/json" \
+  -H "x-revalidate-secret: YOUR_SECRET" \
+  -d '{"path": "/blog/hello-world"}'
+```

package/skills/wp-headless/references/headless-auth.md

@@ -0,0 +1,286 @@
+# Headless Authentication
+
+Use this file when implementing authentication for decoupled WordPress frontends.
+
+## Authentication methods comparison
+
+| Method | Use case | Security | Complexity |
+|--------|----------|----------|-----------|
+| Application Passwords | Server-to-server, CI/CD | Good | Low |
+| JWT (plugin) | SPA authentication | Good | Medium |
+| Cookie-based (same domain) | Subdomain frontends | Good | Low |
+| OAuth 2.0 | Third-party apps | Best | High |
+| Nonce + Cookie | Same-origin AJAX | Good | Low (but not for headless) |
+
+## Application Passwords (WordPress 5.6+)
+
+Best for: server-side requests, build-time data fetching, CI/CD pipelines.
+
+### Setup
+
+Users → Profile → Application Passwords → Add New
+
+### Usage
+
+```bash
+# Basic Auth with application password
+curl -u "username:xxxx xxxx xxxx xxxx xxxx xxxx" \
+  https://site.com/wp-json/wp/v2/posts
+
+# Base64 encoded
+curl -H "Authorization: Basic $(echo -n 'username:xxxx xxxx xxxx xxxx' | base64)" \
+  https://site.com/wp-json/wp/v2/posts
+```
+
+### In Next.js (server-side)
+
+```js
+// lib/wordpress.js
+const WP_URL = process.env.WORDPRESS_URL;
+const WP_AUTH = Buffer.from(
+    `${process.env.WP_USER}:${process.env.WP_APP_PASSWORD}`
+).toString('base64');
+
+export async function fetchWP(endpoint, options = {}) {
+    const res = await fetch(`${WP_URL}/wp-json/wp/v2/${endpoint}`, {
+        ...options,
+        headers: {
+            'Authorization': `Basic ${WP_AUTH}`,
+            'Content-Type': 'application/json',
+            ...options.headers,
+        },
+    });
+    if (!res.ok) throw new Error(`WP API error: ${res.status}`);
+    return res.json();
+}
+```
+
+### Restrict application passwords
+
+```php
+// Only allow application passwords for specific roles
+add_filter('wp_is_application_passwords_available_for_user', function($available, $user) {
+    return in_array('administrator', $user->roles);
+}, 10, 2);
+```
+
+## JWT Authentication
+
+Best for: SPA (React/Vue) with user login, client-side authenticated requests.
+
+### Plugin setup
+
+```bash
+wp plugin install jwt-authentication-for-wp-rest-api --activate
+```
+
+Add to `wp-config.php`:
+```php
+define('JWT_AUTH_SECRET_KEY', 'your-secret-key-at-least-32-chars-long');
+define('JWT_AUTH_CORS_ENABLE', true);
+```
+
+Add to `.htaccess`:
+```apache
+RewriteEngine On
+RewriteCond %{HTTP:Authorization} ^(.*)
+RewriteRule .* - [E=HTTP_AUTHORIZATION:%1]
+```
+
+### Token flow
+
+```js
+// 1. Get token
+const loginRes = await fetch('https://site.com/wp-json/jwt-auth/v1/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        username: 'user@example.com',
+        password: 'password',
+    }),
+});
+const { token, user_display_name } = await loginRes.json();
+
+// 2. Use token for authenticated requests
+const postsRes = await fetch('https://site.com/wp-json/wp/v2/posts', {
+    headers: {
+        'Authorization': `Bearer ${token}`,
+    },
+});
+
+// 3. Validate token (optional)
+const validateRes = await fetch('https://site.com/wp-json/jwt-auth/v1/token/validate', {
+    method: 'POST',
+    headers: {
+        'Authorization': `Bearer ${token}`,
+    },
+});
+```
+
+### Token storage (frontend)
+
+```js
+// Store in httpOnly cookie (recommended for SSR frameworks)
+// Set via API route, not client-side JavaScript
+
+// For SPAs: store in memory (most secure for client-side)
+let authToken = null;
+
+function setToken(token) {
+    authToken = token; // Lost on page refresh — that's OK for security
+}
+
+function getToken() {
+    return authToken;
+}
+
+// AVOID: localStorage (XSS vulnerable)
+// localStorage.setItem('token', token); // DON'T DO THIS
+```
+
+### Refresh token pattern
+
+```js
+class AuthManager {
+    constructor() {
+        this.token = null;
+        this.refreshToken = null;
+    }
+
+    async login(username, password) {
+        const res = await fetch('/wp-json/jwt-auth/v1/token', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ username, password }),
+        });
+        const data = await res.json();
+        this.token = data.token;
+        return data;
+    }
+
+    async authenticatedFetch(url, options = {}) {
+        let res = await fetch(url, {
+            ...options,
+            headers: {
+                ...options.headers,
+                'Authorization': `Bearer ${this.token}`,
+            },
+        });
+
+        // Token expired — re-authenticate
+        if (res.status === 403) {
+            // Redirect to login or use refresh token
+            throw new Error('Session expired. Please log in again.');
+        }
+
+        return res;
+    }
+}
+```
+
+## WPGraphQL authentication
+
+```graphql
+# Login mutation (with wp-graphql-jwt-authentication plugin)
+mutation Login($username: String!, $password: String!) {
+  login(input: { username: $username, password: $password }) {
+    authToken
+    refreshToken
+    user {
+      id
+      name
+      email
+    }
+  }
+}
+
+# Refresh token
+mutation RefreshToken($token: String!) {
+  refreshJwtAuthToken(input: { jwtRefreshToken: $token }) {
+    authToken
+  }
+}
+```
+
+## Next.js authentication pattern
+
+### API route for login
+
+```js
+// pages/api/login.js (Next.js)
+export default async function handler(req, res) {
+    if (req.method !== 'POST') return res.status(405).end();
+
+    const { username, password } = req.body;
+
+    const wpRes = await fetch(`${process.env.WP_URL}/wp-json/jwt-auth/v1/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ username, password }),
+    });
+
+    if (!wpRes.ok) {
+        return res.status(401).json({ error: 'Invalid credentials' });
+    }
+
+    const { token } = await wpRes.json();
+
+    // Set httpOnly cookie (not accessible via JavaScript)
+    res.setHeader('Set-Cookie', [
+        `wp_token=${token}; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=86400`,
+    ]);
+
+    return res.status(200).json({ success: true });
+}
+```
+
+### Middleware for protected routes
+
+```js
+// middleware.js (Next.js)
+import { NextResponse } from 'next/server';
+
+export function middleware(request) {
+    const token = request.cookies.get('wp_token')?.value;
+
+    if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+        return NextResponse.redirect(new URL('/login', request.url));
+    }
+
+    return NextResponse.next();
+}
+
+export const config = {
+    matcher: ['/dashboard/:path*', '/profile/:path*'],
+};
+```
+
+## Security checklist
+
+- [ ] Never store JWT in localStorage (XSS risk)
+- [ ] Use httpOnly cookies for token storage when possible
+- [ ] Set short token expiry (15 min) with refresh tokens
+- [ ] Use HTTPS for all API requests
+- [ ] Validate tokens server-side on every request
+- [ ] Implement CORS properly (see `cors-config.md`)
+- [ ] Rate-limit login endpoints
+- [ ] Use strong JWT secret key (32+ characters)
+- [ ] Disable XML-RPC if not needed
+
+## Verification
+
+```bash
+# Test application password
+curl -u "admin:xxxx xxxx xxxx xxxx" https://site.com/wp-json/wp/v2/users/me
+
+# Test JWT token
+TOKEN=$(curl -s -X POST https://site.com/wp-json/jwt-auth/v1/token \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"password"}' | jq -r '.token')
+
+curl -H "Authorization: Bearer $TOKEN" https://site.com/wp-json/wp/v2/users/me
+
+# Verify unauthenticated access is blocked
+curl -s -o /dev/null -w "%{http_code}" https://site.com/wp-json/wp/v2/users
+# Should return 401 if REST API is restricted
+```