wp-astrojs-integration 0.1.0

package/README.md

@@ -0,0 +1,466 @@
+# WordPress Astro.js Integration
+
+Fast and better WordPress integration for Astro.js with live loaders, static loaders, client API, and full Gutenberg block support.
+
+## Features
+
+- **Live Loaders**: Real-time data fetching from WordPress REST API (server-side rendering)
+- **Static Loaders**: Build-time data fetching for static site generation
+- **WordPress Client**: Direct runtime API access for dynamic content
+- **Gutenberg Support**: Automatic block styles loading for proper rendering
+- **TypeScript First**: Fully typed with extensible schemas
+- **Easy Extension**: Simple API for adding custom ACF fields, post types, and taxonomies
+- **Optimized Images**: Responsive image component with srcset support
+
+## Installation
+
+```bash
+npm install wp-astrojs-integration
+```
+
+## Quick Start
+
+### Option 1: Live Collections (Server-Side Rendering)
+
+Use live loaders for SSR or when you need real-time data:
+
+```typescript
+// src/live.config.ts
+import { defineLiveCollection } from 'astro:content';
+import {
+  wordPressPostLoader,
+  wordPressPageLoader,
+  wordPressCategoryLoader,
+  postSchema,
+  pageSchema,
+  categorySchema,
+} from 'wp-astrojs-integration';
+
+const WORDPRESS_BASE_URL = import.meta.env.PUBLIC_WORDPRESS_BASE_URL;
+
+const posts = defineLiveCollection({
+  loader: wordPressPostLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: postSchema,
+});
+
+const pages = defineLiveCollection({
+  loader: wordPressPageLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: pageSchema,
+});
+
+const categories = defineLiveCollection({
+  loader: wordPressCategoryLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: categorySchema,
+});
+
+export const collections = { posts, pages, categories };
+```
+
+### Option 2: Static Collections (Build-Time Only)
+
+Use static loaders for fully static site generation:
+
+```typescript
+// src/content.config.ts
+import { defineCollection } from 'astro:content';
+import {
+  wordPressPostStaticLoader,
+  wordPressPageStaticLoader,
+  wordPressCategoryStaticLoader,
+  postSchema,
+  pageSchema,
+  categorySchema,
+} from 'wp-astrojs-integration';
+
+const WORDPRESS_BASE_URL = import.meta.env.PUBLIC_WORDPRESS_BASE_URL;
+
+const posts = defineCollection({
+  loader: wordPressPostStaticLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: postSchema,
+});
+
+const pages = defineCollection({
+  loader: wordPressPageStaticLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: pageSchema,
+});
+
+const categories = defineCollection({
+  loader: wordPressCategoryStaticLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: categorySchema,
+});
+
+export const collections = { posts, pages, categories };
+```
+
+### Environment Variable
+
+Create `.env`:
+
+```env
+PUBLIC_WORDPRESS_BASE_URL=https://your-wordpress-site.com
+```
+
+### Using in Pages
+
+```astro
+---
+// For live collections
+import { getLiveEntry } from 'astro:content';
+import WPContent from 'wp-astrojs-integration/components/WPContent.astro';
+import WPImage from 'wp-astrojs-integration/components/WPImage.astro';
+
+const { slug } = Astro.params;
+const { entry: post } = await getLiveEntry('posts', { slug });
+
+const featuredMedia = post.data._embedded?.['wp:featuredmedia']?.[0];
+---
+
+<article>
+  {featuredMedia && (
+    <WPImage media={featuredMedia} loading="eager" />
+  )}
+  
+  <h1 set:html={post.data.title.rendered} />
+  
+  <WPContent 
+    content={post.data.content.rendered}
+    baseUrl={import.meta.env.PUBLIC_WORDPRESS_BASE_URL}
+  />
+</article>
+```
+
+```astro
+---
+// For static collections
+import { getCollection, getEntry } from 'astro:content';
+import WPContent from 'wp-astrojs-integration/components/WPContent.astro';
+
+const { slug } = Astro.params;
+const post = await getEntry('posts', slug);
+---
+
+<article>
+  <h1 set:html={post.data.title.rendered} />
+  
+  <WPContent 
+    content={post.data.content.rendered}
+    baseUrl={import.meta.env.PUBLIC_WORDPRESS_BASE_URL}
+  />
+</article>
+```
+
+## Extending with Custom Fields
+
+### Custom ACF Fields
+
+Extend the default schemas with your ACF fields:
+
+```typescript
+import { postSchema } from 'wp-astrojs-integration';
+import { z } from 'astro/zod';
+
+const customPostSchema = postSchema.extend({
+  acf: z.object({
+    video_url: z.string().optional(),
+    featured_color: z.string().optional(),
+    custom_field: z.string().optional(),
+  }).optional(),
+});
+
+const posts = defineLiveCollection({
+  loader: wordPressPostLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: customPostSchema,
+});
+```
+
+### Custom Post Types
+
+Create a custom post type loader:
+
+```typescript
+import { contentWordPressSchema } from 'wp-astrojs-integration';
+import { z } from 'astro/zod';
+
+const productSchema = contentWordPressSchema.extend({
+  acf: z.object({
+    price: z.number().optional(),
+    sku: z.string().optional(),
+  }).optional(),
+});
+
+// Use the base loader pattern for custom post types
+import { wordPressPostLoader } from 'wp-astrojs-integration';
+
+const products = defineLiveCollection({
+  loader: wordPressPostLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: productSchema,
+});
+```
+
+### Custom Taxonomies
+
+Extend category schema for custom taxonomies:
+
+```typescript
+import { categorySchema } from 'wp-astrojs-integration';
+
+const customCategorySchema = categorySchema.extend({
+  acf: z.object({
+    color: z.string().optional(),
+    icon: z.string().optional(),
+  }).optional(),
+});
+
+const categories = defineLiveCollection({
+  loader: wordPressCategoryLoader({ baseUrl: WORDPRESS_BASE_URL }),
+  schema: customCategorySchema,
+});
+```
+
+## Components
+
+### WPContent
+
+Renders WordPress Gutenberg content with automatic block styles loading:
+
+```astro
+---
+import WPContent from 'wp-astrojs-integration/components/WPContent.astro';
+---
+
+<WPContent 
+  content={post.data.content.rendered}
+  baseUrl={import.meta.env.PUBLIC_WORDPRESS_BASE_URL}
+  class="custom-class"
+  loadBlockStyles={true}
+/>
+```
+
+**Props:**
+- `content` (string, required): Rendered HTML from WordPress
+- `baseUrl` (string, required): WordPress site URL
+- `class` (string): Additional CSS classes
+- `loadBlockStyles` (boolean): Load Gutenberg block styles (default: true)
+
+### WPImage
+
+Optimized responsive images with srcset support:
+
+```astro
+---
+import WPImage from 'wp-astrojs-integration/components/WPImage.astro';
+---
+
+<!-- With embedded media -->
+<WPImage media={featuredMedia} loading="eager" />
+
+<!-- With media ID -->
+<WPImage 
+  mediaId={123} 
+  baseUrl={import.meta.env.PUBLIC_WORDPRESS_BASE_URL}
+  loading="lazy"
+/>
+```
+
+**Props:**
+- `media` (object): Pre-loaded media data from `_embedded`
+- `mediaId` (number): WordPress media ID
+- `baseUrl` (string): Required if using `mediaId`
+- `class` (string): CSS classes
+- `loading` ('lazy' | 'eager'): Image loading strategy
+- `width` (number): Custom width
+- `height` (number): Custom height
+- `sizes` (string): Responsive sizes attribute
+
+## WordPress Client (Runtime API)
+
+For runtime data fetching:
+
+```typescript
+import { WordPressClient } from 'wp-astrojs-integration';
+
+const wp = new WordPressClient({ baseUrl: 'https://your-wordpress-site.com' });
+
+// Get posts
+const posts = await wp.getPosts();
+const post = await wp.getPostBySlug('my-post');
+
+// Get pages
+const pages = await wp.getPages();
+const page = await wp.getPageBySlug('about');
+
+// Get media
+const media = await wp.getMedia();
+const image = await wp.getMediaItem(123);
+
+// Get categories and tags
+const categories = await wp.getCategories();
+const tags = await wp.getTags();
+```
+
+### With Authentication
+
+For endpoints requiring authentication (e.g., `/settings`, `/users/me`):
+
+```typescript
+import { WordPressClient } from 'wp-astrojs-integration';
+
+const wp = new WordPressClient({
+  baseUrl: 'https://your-wordpress-site.com',
+  auth: {
+    username: 'your-username',
+    password: 'your-application-password'
+  }
+});
+
+// Get WordPress site settings (requires auth)
+const settings = await wp.getSettings();
+console.log(settings.title, settings.description);
+
+// Get current authenticated user
+const currentUser = await wp.getCurrentUser();
+console.log(currentUser.name, currentUser.email);
+
+// Check if credentials are valid
+const isValid = await wp.isAuthenticated();
+```
+
+### Astro Middleware Authentication Example
+
+Use the WordPress client in Astro middleware to protect routes with WordPress authentication:
+
+```typescript
+// src/middleware.ts
+import { defineMiddleware } from 'astro:middleware';
+import { WordPressClient } from 'wp-astrojs-integration';
+
+const WORDPRESS_BASE_URL = import.meta.env.PUBLIC_WORDPRESS_BASE_URL;
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  // Only protect /admin routes
+  if (!context.url.pathname.startsWith('/admin')) {
+    return next();
+  }
+
+  // Get credentials from Authorization header (Basic Auth)
+  const authHeader = context.request.headers.get('Authorization');
+  if (!authHeader?.startsWith('Basic ')) {
+    return new Response('Authentication required', {
+      status: 401,
+      headers: { 'WWW-Authenticate': 'Basic realm="Admin Area"' }
+    });
+  }
+
+  // Decode credentials
+  const base64Credentials = authHeader.slice(6);
+  const credentials = atob(base64Credentials);
+  const [username, password] = credentials.split(':');
+
+  // Verify against WordPress
+  const wp = new WordPressClient({
+    baseUrl: WORDPRESS_BASE_URL,
+    auth: { username, password }
+  });
+
+  const isAuthenticated = await wp.isAuthenticated();
+  if (!isAuthenticated) {
+    return new Response('Invalid credentials', {
+      status: 401,
+      headers: { 'WWW-Authenticate': 'Basic realm="Admin Area"' }
+    });
+  }
+
+  // Store user in locals for use in routes
+  const user = await wp.getCurrentUser();
+  context.locals.user = user;
+
+  return next();
+});
+```
+
+Then access the authenticated user in your protected routes:
+
+```astro
+---
+// src/pages/admin/index.astro
+const user = Astro.locals.user;
+---
+<h1>Welcome, {user.name}!</h1>
+```
+
+## API Reference
+
+### Live Loaders (for `defineLiveCollection`)
+
+Use these for server-side rendering or real-time data:
+
+- `wordPressPostLoader(config)`: Live loader for posts
+- `wordPressPageLoader(config)`: Live loader for pages
+- `wordPressMediaLoader(config)`: Live loader for media
+- `wordPressCategoryLoader(config)`: Live loader for categories/taxonomies
+
+### Static Loaders (for `defineCollection`)
+
+Use these for static site generation (build-time only):
+
+- `wordPressPostStaticLoader(config)`: Static loader for posts
+- `wordPressPageStaticLoader(config)`: Static loader for pages
+- `wordPressMediaStaticLoader(config)`: Static loader for media
+- `wordPressCategoryStaticLoader(config)`: Static loader for categories
+- `wordPressTagStaticLoader(config)`: Static loader for tags
+
+**Static Loader Config:**
+```typescript
+interface WordPressStaticLoaderConfig {
+  baseUrl: string;
+  perPage?: number;  // Items per page (default: 100)
+  params?: Record<string, string>;  // Additional query params
+}
+```
+
+### Schemas
+
+Default schemas for WordPress content:
+
+- `baseWordPressSchema`: Base fields for all content
+- `contentWordPressSchema`: Content-specific fields (posts/pages)
+- `postSchema`: WordPress posts
+- `pageSchema`: WordPress pages
+- `mediaSchema`: WordPress media
+- `categorySchema`: Categories and taxonomies
+- `embeddedMediaSchema`: Embedded media from `_embedded` field
+
+### Types
+
+TypeScript types inferred from schemas:
+
+- `WordPressPost`
+- `WordPressPage`
+- `WordPressMedia`
+- `WordPressCategory`
+- `WordPressTag`
+- `WordPressAuthor`
+- `WordPressEmbeddedMedia`
+
+## Live vs Static Loaders
+
+| Feature | Live Loaders | Static Loaders |
+|---------|-------------|----------------|
+| Data freshness | Real-time | Build-time snapshot |
+| Use case | SSR, dynamic content | SSG, static sites |
+| Performance | Fetches on each request | Fetches once at build |
+| Astro API | `defineLiveCollection` | `defineCollection` |
+| Content access | `getLiveEntry`, `getLiveCollection` | `getEntry`, `getCollection` |
+
+## Why This Package?
+
+- **Flexible**: Choose between live (SSR) and static (SSG) data fetching
+- **Type Safety**: Full TypeScript support with extensible schemas
+- **Gutenberg Ready**: Automatic block styles ensure proper rendering
+- **Easy Extension**: Simple API for custom fields and post types
+- **Modern Workflow**: Works seamlessly with Astro's content collections
+- **Optimized**: Responsive images, efficient caching, and minimal overhead
+
+## License
+
+MIT

package/dist/client/auth.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Basic authentication credentials for WordPress API
+ */
+export interface BasicAuthCredentials {
+    username: string;
+    password: string;
+}
+/**
+ * Creates Basic Auth header from credentials
+ */
+export declare function createBasicAuthHeader(credentials: BasicAuthCredentials): string;

package/dist/client/auth.js

@@ -0,0 +1,7 @@
+/**
+ * Creates Basic Auth header from credentials
+ */
+export function createBasicAuthHeader(credentials) {
+    const encoded = btoa(`${credentials.username}:${credentials.password}`);
+    return `Basic ${encoded}`;
+}

package/dist/client/categories.d.ts

@@ -0,0 +1,39 @@
+import type { WordPressCategory } from '../schemas';
+import type { FetchResult } from './index';
+import type { CategoriesFilter, PaginatedResponse } from './types';
+/**
+ * Categories API methods factory
+ * Creates type-safe methods for fetching WordPress categories with filtering and pagination
+ */
+export declare function createCategoriesMethods(fetchAPI: <T>(endpoint: string, params?: Record<string, string>) => Promise<T>, fetchAPIPaginated: <T>(endpoint: string, params?: Record<string, string>) => Promise<FetchResult<T>>): {
+    /**
+     * Gets categories with optional filtering (single page, max 100 items)
+     *
+     * @param filter - Filter options (hideEmpty, parent, include, exclude, search, etc.)
+     * @returns Array of categories matching the filter criteria
+     */
+    getCategories(filter?: CategoriesFilter): Promise<WordPressCategory[]>;
+    /**
+     * Gets ALL categories by automatically paginating through all pages
+     * Use this for static site generation to ensure all content is fetched
+     *
+     * @param filter - Filter options (hideEmpty, parent, include, exclude, search, etc.)
+     * @returns Array of all categories matching the filter criteria
+     */
+    getAllCategories(filter?: Omit<CategoriesFilter, "page">): Promise<WordPressCategory[]>;
+    /**
+     * Gets categories with pagination metadata
+     *
+     * @param filter - Filter options including pagination (perPage, page)
+     * @returns Paginated response with categories and total counts
+     */
+    getCategoriesPaginated(filter?: CategoriesFilter): Promise<PaginatedResponse<WordPressCategory>>;
+    /**
+     * Gets a single category by ID
+     */
+    getCategory(id: number): Promise<WordPressCategory>;
+    /**
+     * Gets a single category by slug
+     */
+    getCategoryBySlug(slug: string): Promise<WordPressCategory | undefined>;
+};

package/dist/client/categories.js

@@ -0,0 +1,69 @@
+import { filterToParams } from './types';
+/**
+ * Categories API methods factory
+ * Creates type-safe methods for fetching WordPress categories with filtering and pagination
+ */
+export function createCategoriesMethods(fetchAPI, fetchAPIPaginated) {
+    return {
+        /**
+         * Gets categories with optional filtering (single page, max 100 items)
+         *
+         * @param filter - Filter options (hideEmpty, parent, include, exclude, search, etc.)
+         * @returns Array of categories matching the filter criteria
+         */
+        async getCategories(filter = {}) {
+            const params = filterToParams(filter);
+            return fetchAPI('/categories', params);
+        },
+        /**
+         * Gets ALL categories by automatically paginating through all pages
+         * Use this for static site generation to ensure all content is fetched
+         *
+         * @param filter - Filter options (hideEmpty, parent, include, exclude, search, etc.)
+         * @returns Array of all categories matching the filter criteria
+         */
+        async getAllCategories(filter = {}) {
+            const allCategories = [];
+            let page = 1;
+            let totalPages = 1;
+            do {
+                const params = filterToParams({ ...filter, page, perPage: 100 });
+                const result = await fetchAPIPaginated('/categories', params);
+                allCategories.push(...result.data);
+                totalPages = result.totalPages;
+                page++;
+            } while (page <= totalPages);
+            return allCategories;
+        },
+        /**
+         * Gets categories with pagination metadata
+         *
+         * @param filter - Filter options including pagination (perPage, page)
+         * @returns Paginated response with categories and total counts
+         */
+        async getCategoriesPaginated(filter = {}) {
+            const params = filterToParams(filter);
+            const result = await fetchAPIPaginated('/categories', params);
+            return {
+                data: result.data,
+                total: result.total,
+                totalPages: result.totalPages,
+                page: filter.page || 1,
+                perPage: filter.perPage || 100,
+            };
+        },
+        /**
+         * Gets a single category by ID
+         */
+        async getCategory(id) {
+            return fetchAPI(`/categories/${id}`);
+        },
+        /**
+         * Gets a single category by slug
+         */
+        async getCategoryBySlug(slug) {
+            const categories = await fetchAPI('/categories', { slug });
+            return categories[0];
+        },
+    };
+}

package/dist/client/index.d.ts

@@ -0,0 +1,102 @@
+import { type BasicAuthCredentials } from './auth';
+import { createPostsMethods } from './posts';
+import { createPagesMethods } from './pages';
+import { createMediaMethods } from './media';
+import { createCategoriesMethods } from './categories';
+import { createTagsMethods } from './tags';
+import { createUsersMethods } from './users';
+import { createSettingsMethods } from './settings';
+import type { PaginatedResponse } from './types';
+/**
+ * WordPress client configuration
+ */
+export interface WordPressClientConfig {
+    /** WordPress site URL (e.g., 'https://example.com') */
+    baseUrl: string;
+    /** Authentication credentials for all API requests */
+    auth?: BasicAuthCredentials;
+}
+/**
+ * Internal fetch result with pagination headers
+ */
+export interface FetchResult<T> {
+    data: T;
+    total: number;
+    totalPages: number;
+}
+/**
+ * WordPress API Client
+ * Provides direct access to WordPress REST API endpoints
+ * Used internally by loaders and available for runtime data fetching
+ *
+ * @example
+ * // Without auth
+ * const wp = new WordPressClient({ baseUrl: 'https://example.com' });
+ *
+ * @example
+ * // With auth
+ * const wp = new WordPressClient({
+ *   baseUrl: 'https://example.com',
+ *   auth: { username: 'admin', password: 'app-password' }
+ * });
+ */
+export declare class WordPressClient {
+    private baseUrl;
+    private apiBase;
+    private authHeader;
+    getPosts: ReturnType<typeof createPostsMethods>['getPosts'];
+    getAllPosts: ReturnType<typeof createPostsMethods>['getAllPosts'];
+    getPostsPaginated: ReturnType<typeof createPostsMethods>['getPostsPaginated'];
+    getPost: ReturnType<typeof createPostsMethods>['getPost'];
+    getPostBySlug: ReturnType<typeof createPostsMethods>['getPostBySlug'];
+    getPages: ReturnType<typeof createPagesMethods>['getPages'];
+    getAllPages: ReturnType<typeof createPagesMethods>['getAllPages'];
+    getPagesPaginated: ReturnType<typeof createPagesMethods>['getPagesPaginated'];
+    getPage: ReturnType<typeof createPagesMethods>['getPage'];
+    getPageBySlug: ReturnType<typeof createPagesMethods>['getPageBySlug'];
+    getMedia: ReturnType<typeof createMediaMethods>['getMedia'];
+    getAllMedia: ReturnType<typeof createMediaMethods>['getAllMedia'];
+    getMediaPaginated: ReturnType<typeof createMediaMethods>['getMediaPaginated'];
+    getMediaItem: ReturnType<typeof createMediaMethods>['getMediaItem'];
+    getMediaBySlug: ReturnType<typeof createMediaMethods>['getMediaBySlug'];
+    getImageUrl: ReturnType<typeof createMediaMethods>['getImageUrl'];
+    getCategories: ReturnType<typeof createCategoriesMethods>['getCategories'];
+    getAllCategories: ReturnType<typeof createCategoriesMethods>['getAllCategories'];
+    getCategoriesPaginated: ReturnType<typeof createCategoriesMethods>['getCategoriesPaginated'];
+    getCategory: ReturnType<typeof createCategoriesMethods>['getCategory'];
+    getCategoryBySlug: ReturnType<typeof createCategoriesMethods>['getCategoryBySlug'];
+    getTags: ReturnType<typeof createTagsMethods>['getTags'];
+    getAllTags: ReturnType<typeof createTagsMethods>['getAllTags'];
+    getTagsPaginated: ReturnType<typeof createTagsMethods>['getTagsPaginated'];
+    getTag: ReturnType<typeof createTagsMethods>['getTag'];
+    getTagBySlug: ReturnType<typeof createTagsMethods>['getTagBySlug'];
+    getUsers: ReturnType<typeof createUsersMethods>['getUsers'];
+    getAllUsers: ReturnType<typeof createUsersMethods>['getAllUsers'];
+    getUsersPaginated: ReturnType<typeof createUsersMethods>['getUsersPaginated'];
+    getUser: ReturnType<typeof createUsersMethods>['getUser'];
+    getCurrentUser: ReturnType<typeof createUsersMethods>['getCurrentUser'];
+    getSettings: ReturnType<typeof createSettingsMethods>['getSettings'];
+    constructor(config: WordPressClientConfig);
+    /**
+     * Checks if authentication is configured
+     */
+    hasAuth(): boolean;
+    /**
+     * Fetches data from WordPress REST API
+     * Auth header is automatically added if configured
+     *
+     * @param endpoint - API endpoint path (e.g., '/posts', '/settings')
+     * @param params - Query parameters to append to the request
+     */
+    fetchAPI<T>(endpoint: string, params?: Record<string, string>): Promise<T>;
+    /**
+     * Fetches data from WordPress REST API with pagination info
+     * Auth header is automatically added if configured
+     *
+     * @param endpoint - API endpoint path (e.g., '/posts', '/settings')
+     * @param params - Query parameters to append to the request
+     * @returns Object with data and pagination headers
+     */
+    fetchAPIPaginated<T>(endpoint: string, params?: Record<string, string>): Promise<FetchResult<T>>;
+}
+export type { PaginatedResponse };