@readpress/wp-blog 1.0.8 → 1.0.10

package/README.md

@@ -4,8 +4,9 @@ A minimal, read-only headless WordPress blog adapter for modern web apps. Useful
 
 - Fetch posts, authors, categories, and tags; includes post search
 - Supports draft/private reads for preview flows with auth
-- Next.js App Router docs and examples, with a framework-agnostic core.
 - Read-only API (no write/update operations)
+- Next.js App Router docs and examples, with a framework-agnostic core
+- Docs ready for AI agent workflows (Codex, Cursor, Claude)
 
 ## Requirements
 
@@ -36,9 +37,10 @@ WP_REST_ENDPOINT=/wp-json/wp/v2/posts
 
 - Configure `rewriteLinks` so internal links in WordPress content stay inside your app routes (for example `/blog/...`) instead of sending users to raw WordPress URLs.
 - Configure `classNameMap` to replace class names in post HTML fetched from WordPress into your app (e.g., replace Gutenberg block class names with Tailwind classes in Next.js).
+- Use `transformPostContentHtml` when you need custom post HTML transforms (e.g., sanitization).
 
 ## Quick start
-See docs/quickstart.mdx
+See [docs/quickstart.mdx](./docs/quickstart.mdx)
 
 ## AI-ready docs
 
@@ -49,13 +51,13 @@ Recommended:
 - Or point your agent to the `docs/` folder in this repo on GitHub.
 
 ## Examples
-- `examples/nextjs-blog`
-- `examples/gutenberg-blocks-tailwind`
-- `examples/nextjs-post-components`
+- [examples/nextjs-blog](./examples/nextjs-blog/README.md)
+- [examples/gutenberg-blocks-tailwind](./examples/gutenberg-blocks-tailwind/README.md)
+- [examples/nextjs-post-components](./examples/nextjs-post-components/README.md)
 
 ## Advanced guides
 
-- Drafts and preview: `docs/guides/drafts-and-preview.mdx`
-- SEO in Next.js: `docs/recipes/seo-nextjs.mdx`
-- Link rewriting: `docs/content/link-rewriting.mdx`
-- Class mapping (custom class names): `docs/content/class-mapping.mdx`
+- Drafts and preview: [docs/guides/drafts-and-preview.mdx](./docs/guides/drafts-and-preview.mdx)
+- SEO in Next.js: [docs/recipes/seo-nextjs.mdx](./docs/recipes/seo-nextjs.mdx)
+- Link rewriting: [docs/content/link-rewriting.mdx](./docs/content/link-rewriting.mdx)
+- Class mapping (custom class names): [docs/content/class-mapping.mdx](./docs/content/class-mapping.mdx)

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { P as PlaceholderParseOptions, W as WpContentPart, a as WpClientOptions, b as WpBlogClient, c as WpAuthor, G as GetAuthorsParams, d as GetTermsParams, B as BlogTerm, e as BlogPostField, f as GetPostParams, S as SelectFields, g as BlogPost, h as BlogPostSummaryField, i as GetPostsParams, j as PostListResult, k as BlogPostSummary, Q as QueryGraphqlParams, l as QueryGraphqlResult, m as QueryRawParams, n as SearchPostsParams } from './types-D8A_jJkk.mjs';
-export { o as BlogAuthor, p as BlogTermOrder, q as BlogTextMode, C as ClassNameMap, r as ClassNameMapMode, s as ClassNameMapRule, t as ClassNameMapValue, H as HtmlContentPart, L as LinkRewriteContext, u as LinkRewriteRule, v as PaginationMeta, w as PlaceholderContentPart, x as PlaceholderProps, y as QueryRawRestInput, z as WpAuthConfig, A as WpAuthResolvedConfig, D as WpAuthType, E as WpEmbedded, F as WpFeaturedMedia, I as WpPost, J as WpRenderedField, K as WpTerm } from './types-D8A_jJkk.mjs';
+import { P as PlaceholderParseOptions, W as WpContentPart, a as WpClientOptions, b as WpBlogClient, c as WpAuthor, G as GetAuthorsParams, d as GetTermsParams, B as BlogTerm, e as BlogPostField, f as GetPostParams, S as SelectFields, g as BlogPost, h as BlogPostSummaryField, i as GetPostsParams, j as PostListResult, k as BlogPostSummary, Q as QueryGraphqlParams, l as QueryGraphqlResult, m as QueryRawParams, n as SearchPostsParams } from './types-B9QucQ0W.mjs';
+export { o as BlogAuthor, p as BlogTermOrder, q as BlogTextMode, C as ClassNameMap, r as ClassNameMapMode, s as ClassNameMapRule, t as ClassNameMapValue, H as HtmlContentPart, L as LinkRewriteContext, u as LinkRewriteRule, v as PaginationMeta, w as PlaceholderContentPart, x as PlaceholderProps, y as QueryRawRestInput, z as WpAuthConfig, A as WpAuthResolvedConfig, D as WpAuthType, E as WpEmbedded, F as WpFeaturedMedia, I as WpPost, J as WpRenderedField, K as WpTerm } from './types-B9QucQ0W.mjs';
 
 type WpClientErrorCode = "INVALID_CONFIG" | "INVALID_INPUT" | "REQUEST_FAILED" | "INVALID_RESPONSE";
 interface WpApiErrorDetails {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PlaceholderParseOptions, W as WpContentPart, a as WpClientOptions, b as WpBlogClient, c as WpAuthor, G as GetAuthorsParams, d as GetTermsParams, B as BlogTerm, e as BlogPostField, f as GetPostParams, S as SelectFields, g as BlogPost, h as BlogPostSummaryField, i as GetPostsParams, j as PostListResult, k as BlogPostSummary, Q as QueryGraphqlParams, l as QueryGraphqlResult, m as QueryRawParams, n as SearchPostsParams } from './types-D8A_jJkk.js';
-export { o as BlogAuthor, p as BlogTermOrder, q as BlogTextMode, C as ClassNameMap, r as ClassNameMapMode, s as ClassNameMapRule, t as ClassNameMapValue, H as HtmlContentPart, L as LinkRewriteContext, u as LinkRewriteRule, v as PaginationMeta, w as PlaceholderContentPart, x as PlaceholderProps, y as QueryRawRestInput, z as WpAuthConfig, A as WpAuthResolvedConfig, D as WpAuthType, E as WpEmbedded, F as WpFeaturedMedia, I as WpPost, J as WpRenderedField, K as WpTerm } from './types-D8A_jJkk.js';
+import { P as PlaceholderParseOptions, W as WpContentPart, a as WpClientOptions, b as WpBlogClient, c as WpAuthor, G as GetAuthorsParams, d as GetTermsParams, B as BlogTerm, e as BlogPostField, f as GetPostParams, S as SelectFields, g as BlogPost, h as BlogPostSummaryField, i as GetPostsParams, j as PostListResult, k as BlogPostSummary, Q as QueryGraphqlParams, l as QueryGraphqlResult, m as QueryRawParams, n as SearchPostsParams } from './types-B9QucQ0W.js';
+export { o as BlogAuthor, p as BlogTermOrder, q as BlogTextMode, C as ClassNameMap, r as ClassNameMapMode, s as ClassNameMapRule, t as ClassNameMapValue, H as HtmlContentPart, L as LinkRewriteContext, u as LinkRewriteRule, v as PaginationMeta, w as PlaceholderContentPart, x as PlaceholderProps, y as QueryRawRestInput, z as WpAuthConfig, A as WpAuthResolvedConfig, D as WpAuthType, E as WpEmbedded, F as WpFeaturedMedia, I as WpPost, J as WpRenderedField, K as WpTerm } from './types-B9QucQ0W.js';
 
 type WpClientErrorCode = "INVALID_CONFIG" | "INVALID_INPUT" | "REQUEST_FAILED" | "INVALID_RESPONSE";
 interface WpApiErrorDetails {

package/dist/index.js

@@ -323,6 +323,16 @@ function resolveClassNameMap(options) {
   }
   return map;
 }
+function resolveTransformPostContentHtml(options) {
+  const transform = options.transformPostContentHtml;
+  if (transform === void 0) {
+    return void 0;
+  }
+  if (typeof transform !== "function") {
+    throw new WpClientError("INVALID_CONFIG", "transformPostContentHtml must be a function.");
+  }
+  return transform;
+}
 function resolveClientOptions(options = {}) {
   var _a, _b, _c, _d, _e;
   const wpUrl = (_a = options.wpUrl) != null ? _a : readEnv("WP_URL");
@@ -346,6 +356,7 @@ function resolveClientOptions(options = {}) {
     auth: resolveAuth(options),
     rewriteLinks: resolveRewriteLinks(options),
     classNameMap: resolveClassNameMap(options),
+    transformPostContentHtml: resolveTransformPostContentHtml(options),
     fetchImpl,
     requestInit: options.requestInit
   };
@@ -1062,7 +1073,8 @@ function normalizePost(post, textMode = "plain", options) {
   const summary = normalizePostSummary(post, textMode);
   const rawContentHtml = (_b = (_a = post.content) == null ? void 0 : _a.rendered) != null ? _b : "";
   const rewrittenHtml = options ? rewriteContentLinks(rawContentHtml, options) : rawContentHtml;
-  const contentHtml = (options == null ? void 0 : options.classNameMap) && Object.keys(options.classNameMap).length > 0 ? transformContentClasses(rewrittenHtml, options.classNameMap) : rewrittenHtml;
+  const classTransformedContentHtml = (options == null ? void 0 : options.classNameMap) && Object.keys(options.classNameMap).length > 0 ? transformContentClasses(rewrittenHtml, options.classNameMap) : rewrittenHtml;
+  const contentHtml = (options == null ? void 0 : options.transformPostContentHtml) ? options.transformPostContentHtml(classTransformedContentHtml) : classTransformedContentHtml;
   return __spreadProps(__spreadValues({}, summary), {
     contentHtml
   });

package/dist/index.mjs

@@ -194,6 +194,16 @@ function resolveClassNameMap(options) {
   }
   return map;
 }
+function resolveTransformPostContentHtml(options) {
+  const transform = options.transformPostContentHtml;
+  if (transform === void 0) {
+    return void 0;
+  }
+  if (typeof transform !== "function") {
+    throw new WpClientError("INVALID_CONFIG", "transformPostContentHtml must be a function.");
+  }
+  return transform;
+}
 function resolveClientOptions(options = {}) {
   var _a, _b, _c, _d, _e;
   const wpUrl = (_a = options.wpUrl) != null ? _a : readEnv("WP_URL");
@@ -217,6 +227,7 @@ function resolveClientOptions(options = {}) {
     auth: resolveAuth(options),
     rewriteLinks: resolveRewriteLinks(options),
     classNameMap: resolveClassNameMap(options),
+    transformPostContentHtml: resolveTransformPostContentHtml(options),
     fetchImpl,
     requestInit: options.requestInit
   };
@@ -933,7 +944,8 @@ function normalizePost(post, textMode = "plain", options) {
   const summary = normalizePostSummary(post, textMode);
   const rawContentHtml = (_b = (_a = post.content) == null ? void 0 : _a.rendered) != null ? _b : "";
   const rewrittenHtml = options ? rewriteContentLinks(rawContentHtml, options) : rawContentHtml;
-  const contentHtml = (options == null ? void 0 : options.classNameMap) && Object.keys(options.classNameMap).length > 0 ? transformContentClasses(rewrittenHtml, options.classNameMap) : rewrittenHtml;
+  const classTransformedContentHtml = (options == null ? void 0 : options.classNameMap) && Object.keys(options.classNameMap).length > 0 ? transformContentClasses(rewrittenHtml, options.classNameMap) : rewrittenHtml;
+  const contentHtml = (options == null ? void 0 : options.transformPostContentHtml) ? options.transformPostContentHtml(classTransformedContentHtml) : classTransformedContentHtml;
   return __spreadProps(__spreadValues({}, summary), {
     contentHtml
   });

package/dist/react.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ComponentType } from 'react';
-import { W as WpContentPart } from './types-D8A_jJkk.mjs';
+import { W as WpContentPart } from './types-B9QucQ0W.mjs';
 
 type WpPlaceholderComponents = Record<string, ComponentType<Record<string, unknown>>>;
 interface WpContentProps {

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ComponentType } from 'react';
-import { W as WpContentPart } from './types-D8A_jJkk.js';
+import { W as WpContentPart } from './types-B9QucQ0W.js';
 
 type WpPlaceholderComponents = Record<string, ComponentType<Record<string, unknown>>>;
 interface WpContentProps {

package/dist/types-B9QucQ0W.d.mts

@@ -0,0 +1,249 @@
+interface WpRenderedField {
+    rendered: string;
+}
+interface WpFeaturedMedia {
+    source_url?: string;
+}
+interface WpTerm {
+    id: number;
+    slug?: string;
+    name?: string;
+    taxonomy?: string;
+    count?: number;
+}
+interface WpAuthor {
+    id: number;
+    name?: string;
+    slug?: string;
+    url?: string;
+    description?: string;
+    link?: string;
+    avatar_urls?: Record<string, string>;
+    [key: string]: unknown;
+}
+interface WpEmbedded {
+    "wp:featuredmedia"?: WpFeaturedMedia[];
+    "wp:term"?: WpTerm[][];
+    author?: WpAuthor[];
+}
+interface WpPost {
+    id: number;
+    slug: string;
+    link: string;
+    date: string;
+    modified: string;
+    title: WpRenderedField;
+    excerpt: WpRenderedField;
+    content: WpRenderedField;
+    _embedded?: WpEmbedded;
+}
+interface LinkRewriteContext {
+    href: string;
+    pathname: string;
+    search: string;
+    hash: string;
+}
+interface LinkRewriteRule {
+    source: string;
+    destination?: string;
+    action?: "ignore";
+    transform?: (context: LinkRewriteContext) => string;
+}
+type ClassNameMapMode = "append" | "replace" | "replace-all";
+interface ClassNameMapRule {
+    className: string;
+    mode?: ClassNameMapMode;
+}
+type ClassNameMapValue = string | ClassNameMapRule;
+type ClassNameMap = Record<string, ClassNameMapValue>;
+type PlaceholderProps = Record<string, unknown>;
+interface HtmlContentPart {
+    type: "html";
+    html: string;
+}
+interface PlaceholderContentPart {
+    type: "placeholder";
+    name: string;
+    props: PlaceholderProps;
+}
+type WpContentPart = HtmlContentPart | PlaceholderContentPart;
+interface PlaceholderParseOptions {
+    namespace?: string;
+    maxPropsLength?: number;
+}
+/**
+ * Normalized post shape returned by this package.
+ */
+interface BlogPostSummary {
+    id: number;
+    slug: string;
+    url: string;
+    date: string;
+    modified: string;
+    publishedDate: string;
+    updatedDate: string;
+    title: string;
+    excerpt: string;
+    featuredImageUrl: string | null;
+    author: BlogAuthor | null;
+    categories: BlogTerm[];
+    tags: BlogTerm[];
+}
+/**
+ * Full post shape returned by single-post methods.
+ */
+interface BlogPost extends BlogPostSummary {
+    contentHtml: string;
+}
+interface BlogTerm {
+    id: number;
+    slug: string;
+    name: string;
+    count: number;
+}
+type BlogAuthor = WpAuthor;
+type BlogTermOrder = "default" | "alphabetical" | "count";
+interface GetTermsParams {
+    order?: BlogTermOrder;
+}
+interface GetAuthorsParams {
+    page?: number;
+    perPage?: number;
+}
+type BlogTextMode = "plain" | "html";
+type BlogPostSummaryField = keyof BlogPostSummary;
+type BlogPostField = keyof BlogPost;
+type SelectFields<T, TSelect extends readonly (keyof T)[] | undefined> = TSelect extends readonly (keyof T)[] ? Pick<T, TSelect[number]> : T;
+/**
+ * Pagination metadata returned from list endpoints.
+ */
+interface PaginationMeta {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+}
+/**
+ * Response returned by getPosts.
+ */
+interface PostListResult<TItem = BlogPostSummary> {
+    items: TItem[];
+    pagination: PaginationMeta;
+}
+/**
+ * Optional pagination parameters for getPosts.
+ */
+interface GetPostsParams<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined> {
+    page?: number;
+    perPage?: number;
+    status?: "draft" | "private" | "publish" | "any";
+    categorySlug?: string;
+    tagSlug?: string;
+    textMode?: BlogTextMode;
+    select?: TSelect;
+}
+/**
+ * Parameters for searching published posts.
+ */
+interface SearchPostsParams<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined> extends GetPostsParams<TSelect> {
+    query: string;
+}
+/**
+ * Options for creating an explicit WordPress client.
+ */
+interface WpClientOptions {
+    wpUrl?: string;
+    endpoint?: string;
+    perPage?: number;
+    auth?: WpAuthConfig;
+    rewriteLinks?: LinkRewriteRule[];
+    classNameMap?: ClassNameMap;
+    transformPostContentHtml?: (html: string) => string;
+    fetchImpl?: typeof fetch;
+    requestInit?: RequestInit;
+}
+type WpAuthType = "none" | "basic" | "bearer" | "headers";
+interface WpAuthConfig {
+    type?: WpAuthType;
+    user?: string;
+    appPassword?: string;
+    token?: string;
+    headers?: Record<string, string>;
+}
+interface WpAuthResolvedConfig {
+    type: WpAuthType;
+    user?: string;
+    appPassword?: string;
+    token?: string;
+    headers?: Record<string, string>;
+}
+interface GetPostParams<TSelect extends readonly BlogPostField[] | undefined = undefined> {
+    status?: "draft" | "private" | "publish" | "any";
+    textMode?: BlogTextMode;
+    select?: TSelect;
+}
+interface QueryRawRestInput {
+    path: string;
+    params?: Record<string, string | number | boolean | null | undefined>;
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+interface QueryRawParams {
+    rest?: QueryRawRestInput;
+    authRequired?: boolean;
+}
+interface QueryGraphqlParams {
+    query: string;
+    variables?: Record<string, unknown>;
+}
+interface QueryGraphqlResult<TData = unknown> {
+    data?: TData;
+    errors?: Array<Record<string, unknown>>;
+}
+interface WpBlogClient {
+    /**
+     * Fetches a page of published WordPress posts.
+     */
+    getPosts<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined>(params?: GetPostsParams<TSelect>): Promise<PostListResult<SelectFields<BlogPostSummary, TSelect>>>;
+    /**
+     * Searches posts using the WordPress REST search parameter.
+     */
+    searchPosts<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined>(params: SearchPostsParams<TSelect>): Promise<PostListResult<SelectFields<BlogPostSummary, TSelect>>>;
+    /**
+     * Fetches a single post by slug, or null when not found.
+     */
+    getPostBySlug<TSelect extends readonly BlogPostField[] | undefined = undefined>(slug: string, params?: GetPostParams<TSelect>): Promise<SelectFields<BlogPost, TSelect> | null>;
+    /**
+     * Fetches a single published post by WordPress post ID, or null when not found.
+     */
+    getPostById<TSelect extends readonly BlogPostField[] | undefined = undefined>(id: number, params?: GetPostParams<TSelect>): Promise<SelectFields<BlogPost, TSelect> | null>;
+    /**
+     * Executes a raw request against REST for custom fields/shapes.
+     * Use this as an escape hatch for custom fields/shapes.
+     */
+    queryRaw<TData = unknown>(params: QueryRawParams): Promise<TData>;
+    /**
+     * Executes a raw GraphQL request.
+     * Uses WP_URL + endpoint and existing WP_AUTH_* auth config.
+     */
+    queryGraphql<TData = unknown>(params: QueryGraphqlParams): Promise<QueryGraphqlResult<TData>>;
+    /**
+     * Fetches blog categories for archive navigation/sidebars.
+     */
+    getCategories(params?: GetTermsParams): Promise<BlogTerm[]>;
+    /**
+     * Fetches blog tags for archive navigation/sidebars.
+     */
+    getTags(params?: GetTermsParams): Promise<BlogTerm[]>;
+    /**
+     * Fetches a page of WordPress authors.
+     */
+    getAuthors(params?: GetAuthorsParams): Promise<BlogAuthor[]>;
+    /**
+     * Fetches a single WordPress author by ID.
+     */
+    getAuthorById(id: number): Promise<BlogAuthor | null>;
+}
+
+export type { WpAuthResolvedConfig as A, BlogTerm as B, ClassNameMap as C, WpAuthType as D, WpEmbedded as E, WpFeaturedMedia as F, GetAuthorsParams as G, HtmlContentPart as H, WpPost as I, WpRenderedField as J, WpTerm as K, LinkRewriteContext as L, PlaceholderParseOptions as P, QueryGraphqlParams as Q, SelectFields as S, WpContentPart as W, WpClientOptions as a, WpBlogClient as b, WpAuthor as c, GetTermsParams as d, BlogPostField as e, GetPostParams as f, BlogPost as g, BlogPostSummaryField as h, GetPostsParams as i, PostListResult as j, BlogPostSummary as k, QueryGraphqlResult as l, QueryRawParams as m, SearchPostsParams as n, BlogAuthor as o, BlogTermOrder as p, BlogTextMode as q, ClassNameMapMode as r, ClassNameMapRule as s, ClassNameMapValue as t, LinkRewriteRule as u, PaginationMeta as v, PlaceholderContentPart as w, PlaceholderProps as x, QueryRawRestInput as y, WpAuthConfig as z };

package/dist/types-B9QucQ0W.d.ts

@@ -0,0 +1,249 @@
+interface WpRenderedField {
+    rendered: string;
+}
+interface WpFeaturedMedia {
+    source_url?: string;
+}
+interface WpTerm {
+    id: number;
+    slug?: string;
+    name?: string;
+    taxonomy?: string;
+    count?: number;
+}
+interface WpAuthor {
+    id: number;
+    name?: string;
+    slug?: string;
+    url?: string;
+    description?: string;
+    link?: string;
+    avatar_urls?: Record<string, string>;
+    [key: string]: unknown;
+}
+interface WpEmbedded {
+    "wp:featuredmedia"?: WpFeaturedMedia[];
+    "wp:term"?: WpTerm[][];
+    author?: WpAuthor[];
+}
+interface WpPost {
+    id: number;
+    slug: string;
+    link: string;
+    date: string;
+    modified: string;
+    title: WpRenderedField;
+    excerpt: WpRenderedField;
+    content: WpRenderedField;
+    _embedded?: WpEmbedded;
+}
+interface LinkRewriteContext {
+    href: string;
+    pathname: string;
+    search: string;
+    hash: string;
+}
+interface LinkRewriteRule {
+    source: string;
+    destination?: string;
+    action?: "ignore";
+    transform?: (context: LinkRewriteContext) => string;
+}
+type ClassNameMapMode = "append" | "replace" | "replace-all";
+interface ClassNameMapRule {
+    className: string;
+    mode?: ClassNameMapMode;
+}
+type ClassNameMapValue = string | ClassNameMapRule;
+type ClassNameMap = Record<string, ClassNameMapValue>;
+type PlaceholderProps = Record<string, unknown>;
+interface HtmlContentPart {
+    type: "html";
+    html: string;
+}
+interface PlaceholderContentPart {
+    type: "placeholder";
+    name: string;
+    props: PlaceholderProps;
+}
+type WpContentPart = HtmlContentPart | PlaceholderContentPart;
+interface PlaceholderParseOptions {
+    namespace?: string;
+    maxPropsLength?: number;
+}
+/**
+ * Normalized post shape returned by this package.
+ */
+interface BlogPostSummary {
+    id: number;
+    slug: string;
+    url: string;
+    date: string;
+    modified: string;
+    publishedDate: string;
+    updatedDate: string;
+    title: string;
+    excerpt: string;
+    featuredImageUrl: string | null;
+    author: BlogAuthor | null;
+    categories: BlogTerm[];
+    tags: BlogTerm[];
+}
+/**
+ * Full post shape returned by single-post methods.
+ */
+interface BlogPost extends BlogPostSummary {
+    contentHtml: string;
+}
+interface BlogTerm {
+    id: number;
+    slug: string;
+    name: string;
+    count: number;
+}
+type BlogAuthor = WpAuthor;
+type BlogTermOrder = "default" | "alphabetical" | "count";
+interface GetTermsParams {
+    order?: BlogTermOrder;
+}
+interface GetAuthorsParams {
+    page?: number;
+    perPage?: number;
+}
+type BlogTextMode = "plain" | "html";
+type BlogPostSummaryField = keyof BlogPostSummary;
+type BlogPostField = keyof BlogPost;
+type SelectFields<T, TSelect extends readonly (keyof T)[] | undefined> = TSelect extends readonly (keyof T)[] ? Pick<T, TSelect[number]> : T;
+/**
+ * Pagination metadata returned from list endpoints.
+ */
+interface PaginationMeta {
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+}
+/**
+ * Response returned by getPosts.
+ */
+interface PostListResult<TItem = BlogPostSummary> {
+    items: TItem[];
+    pagination: PaginationMeta;
+}
+/**
+ * Optional pagination parameters for getPosts.
+ */
+interface GetPostsParams<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined> {
+    page?: number;
+    perPage?: number;
+    status?: "draft" | "private" | "publish" | "any";
+    categorySlug?: string;
+    tagSlug?: string;
+    textMode?: BlogTextMode;
+    select?: TSelect;
+}
+/**
+ * Parameters for searching published posts.
+ */
+interface SearchPostsParams<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined> extends GetPostsParams<TSelect> {
+    query: string;
+}
+/**
+ * Options for creating an explicit WordPress client.
+ */
+interface WpClientOptions {
+    wpUrl?: string;
+    endpoint?: string;
+    perPage?: number;
+    auth?: WpAuthConfig;
+    rewriteLinks?: LinkRewriteRule[];
+    classNameMap?: ClassNameMap;
+    transformPostContentHtml?: (html: string) => string;
+    fetchImpl?: typeof fetch;
+    requestInit?: RequestInit;
+}
+type WpAuthType = "none" | "basic" | "bearer" | "headers";
+interface WpAuthConfig {
+    type?: WpAuthType;
+    user?: string;
+    appPassword?: string;
+    token?: string;
+    headers?: Record<string, string>;
+}
+interface WpAuthResolvedConfig {
+    type: WpAuthType;
+    user?: string;
+    appPassword?: string;
+    token?: string;
+    headers?: Record<string, string>;
+}
+interface GetPostParams<TSelect extends readonly BlogPostField[] | undefined = undefined> {
+    status?: "draft" | "private" | "publish" | "any";
+    textMode?: BlogTextMode;
+    select?: TSelect;
+}
+interface QueryRawRestInput {
+    path: string;
+    params?: Record<string, string | number | boolean | null | undefined>;
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+interface QueryRawParams {
+    rest?: QueryRawRestInput;
+    authRequired?: boolean;
+}
+interface QueryGraphqlParams {
+    query: string;
+    variables?: Record<string, unknown>;
+}
+interface QueryGraphqlResult<TData = unknown> {
+    data?: TData;
+    errors?: Array<Record<string, unknown>>;
+}
+interface WpBlogClient {
+    /**
+     * Fetches a page of published WordPress posts.
+     */
+    getPosts<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined>(params?: GetPostsParams<TSelect>): Promise<PostListResult<SelectFields<BlogPostSummary, TSelect>>>;
+    /**
+     * Searches posts using the WordPress REST search parameter.
+     */
+    searchPosts<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined>(params: SearchPostsParams<TSelect>): Promise<PostListResult<SelectFields<BlogPostSummary, TSelect>>>;
+    /**
+     * Fetches a single post by slug, or null when not found.
+     */
+    getPostBySlug<TSelect extends readonly BlogPostField[] | undefined = undefined>(slug: string, params?: GetPostParams<TSelect>): Promise<SelectFields<BlogPost, TSelect> | null>;
+    /**
+     * Fetches a single published post by WordPress post ID, or null when not found.
+     */
+    getPostById<TSelect extends readonly BlogPostField[] | undefined = undefined>(id: number, params?: GetPostParams<TSelect>): Promise<SelectFields<BlogPost, TSelect> | null>;
+    /**
+     * Executes a raw request against REST for custom fields/shapes.
+     * Use this as an escape hatch for custom fields/shapes.
+     */
+    queryRaw<TData = unknown>(params: QueryRawParams): Promise<TData>;
+    /**
+     * Executes a raw GraphQL request.
+     * Uses WP_URL + endpoint and existing WP_AUTH_* auth config.
+     */
+    queryGraphql<TData = unknown>(params: QueryGraphqlParams): Promise<QueryGraphqlResult<TData>>;
+    /**
+     * Fetches blog categories for archive navigation/sidebars.
+     */
+    getCategories(params?: GetTermsParams): Promise<BlogTerm[]>;
+    /**
+     * Fetches blog tags for archive navigation/sidebars.
+     */
+    getTags(params?: GetTermsParams): Promise<BlogTerm[]>;
+    /**
+     * Fetches a page of WordPress authors.
+     */
+    getAuthors(params?: GetAuthorsParams): Promise<BlogAuthor[]>;
+    /**
+     * Fetches a single WordPress author by ID.
+     */
+    getAuthorById(id: number): Promise<BlogAuthor | null>;
+}
+
+export type { WpAuthResolvedConfig as A, BlogTerm as B, ClassNameMap as C, WpAuthType as D, WpEmbedded as E, WpFeaturedMedia as F, GetAuthorsParams as G, HtmlContentPart as H, WpPost as I, WpRenderedField as J, WpTerm as K, LinkRewriteContext as L, PlaceholderParseOptions as P, QueryGraphqlParams as Q, SelectFields as S, WpContentPart as W, WpClientOptions as a, WpBlogClient as b, WpAuthor as c, GetTermsParams as d, BlogPostField as e, GetPostParams as f, BlogPost as g, BlogPostSummaryField as h, GetPostsParams as i, PostListResult as j, BlogPostSummary as k, QueryGraphqlResult as l, QueryRawParams as m, SearchPostsParams as n, BlogAuthor as o, BlogTermOrder as p, BlogTextMode as q, ClassNameMapMode as r, ClassNameMapRule as s, ClassNameMapValue as t, LinkRewriteRule as u, PaginationMeta as v, PlaceholderContentPart as w, PlaceholderProps as x, QueryRawRestInput as y, WpAuthConfig as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readpress/wp-blog",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "A minimal, read-only headless WordPress blog adapter for modern web apps",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -23,6 +23,8 @@
   "scripts": {
     "build": "tsup",
     "prepack": "npm run build",
+    "check:publish-version": "node scripts/check-publish-version.mjs",
+    "prepublishOnly": "npm run check:publish-version",
     "test": "npm run build && node --test test/*.test.mjs",
     "docs:api": "typedoc",
     "docs:api:clean": "rm -rf docs/reference && typedoc"