@readpress/wp-blog 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Virgiliu Diaconu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @readpress/wp-blog
+
+A minimal, read-only WordPress blog adapter for modern web apps.
+
+- Fetch and search posts, plus authors, categories, and tags
+- Supports drafts/private posts with auth
+- Framework-agnostic core with Next.js App Router docs and examples
+- Read-only by design
+
+## Requirements
+
+- Node.js 18+
+- WordPress REST API enabled (default in WordPress)
+
+## Installation
+
+```bash
+npm install @readpress/wp-blog
+```
+
+## Configuration
+
+Required:
+
+```env
+WP_URL=https://example.com
+```
+
+## Quick start
+See docs/quickstart.mdx
+
+## Examples
+- `examples/nextjs-blog`
+- `examples/gutenberg-blocks-tailwind`
+- `examples/nextjs-post-components`

package/dist/chunk-QKYYHVDQ.mjs

@@ -0,0 +1,105 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+
+// src/domain/placeholders.ts
+var DEFAULT_NAMESPACE = "wpapp";
+var DEFAULT_MAX_PROPS_LENGTH = 1e4;
+var PLACEHOLDER_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_-]*$/;
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizeNamespace(value) {
+  const trimmed = value == null ? void 0 : value.trim();
+  if (!trimmed) {
+    return DEFAULT_NAMESPACE;
+  }
+  return trimmed;
+}
+function normalizeMaxPropsLength(value) {
+  if (!value || !Number.isInteger(value) || value <= 0) {
+    return DEFAULT_MAX_PROPS_LENGTH;
+  }
+  return value;
+}
+function parseProps(rawProps, maxPropsLength) {
+  const trimmed = rawProps == null ? void 0 : rawProps.trim();
+  if (!trimmed) {
+    return {};
+  }
+  if (trimmed.length > maxPropsLength) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch (e) {
+    return null;
+  }
+}
+function parseContentPlaceholders(contentHtml, options = {}) {
+  if (!contentHtml) {
+    return [{ type: "html", html: "" }];
+  }
+  const namespace = normalizeNamespace(options.namespace);
+  const maxPropsLength = normalizeMaxPropsLength(options.maxPropsLength);
+  const markerRegex = new RegExp(
+    `<!--\\s*${escapeRegex(namespace)}:([A-Za-z][A-Za-z0-9_-]*)(?:\\s+([\\s\\S]*?))?\\s*-->`,
+    "g"
+  );
+  const parts = [];
+  let cursor = 0;
+  let match;
+  while ((match = markerRegex.exec(contentHtml)) !== null) {
+    const [fullMatch, rawName, rawProps] = match;
+    const matchIndex = match.index;
+    if (matchIndex > cursor) {
+      parts.push({ type: "html", html: contentHtml.slice(cursor, matchIndex) });
+    }
+    const name = rawName == null ? void 0 : rawName.trim();
+    const props = parseProps(rawProps, maxPropsLength);
+    if (!name || !PLACEHOLDER_NAME_REGEX.test(name) || !props) {
+      parts.push({ type: "html", html: fullMatch });
+      cursor = markerRegex.lastIndex;
+      continue;
+    }
+    parts.push({
+      type: "placeholder",
+      name,
+      props
+    });
+    cursor = markerRegex.lastIndex;
+  }
+  if (cursor < contentHtml.length) {
+    parts.push({ type: "html", html: contentHtml.slice(cursor) });
+  }
+  if (parts.length === 0) {
+    return [{ type: "html", html: contentHtml }];
+  }
+  return parts;
+}
+
+export {
+  __spreadValues,
+  __spreadProps,
+  parseContentPlaceholders
+};

package/dist/index.d.mts

@@ -0,0 +1,78 @@
+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-BDmCnhFG.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-BDmCnhFG.mjs';
+
+type WpClientErrorCode = "INVALID_CONFIG" | "INVALID_INPUT" | "REQUEST_FAILED" | "INVALID_RESPONSE";
+interface WpApiErrorDetails {
+    wpCode?: string;
+    wpMessage?: string;
+    wpData?: unknown;
+}
+/**
+ * Error thrown by the WordPress adapter for config, input, request, or response failures.
+ */
+declare class WpClientError extends Error {
+    readonly code: WpClientErrorCode;
+    readonly status?: number;
+    readonly wpCode?: string;
+    readonly wpMessage?: string;
+    readonly wpData?: unknown;
+    constructor(code: WpClientErrorCode, message: string, status?: number, details?: WpApiErrorDetails);
+}
+
+/**
+ * Parses placeholder comments from HTML content.
+ *
+ * Marker format:
+ * - <!-- wpapp:cta {"title":"..."} -->
+ * - <!-- wpapp:newsletter -->
+ *
+ * Invalid placeholders are left as normal HTML content.
+ */
+declare function parseContentPlaceholders(contentHtml: string, options?: PlaceholderParseOptions): WpContentPart[];
+
+/**
+ * Creates an explicit WordPress blog client with the provided options.
+ */
+declare function createWpBlogClient(clientOptions?: WpClientOptions): WpBlogClient;
+/**
+ * Fetches published posts using a lazily created env-based default client.
+ */
+declare function getPosts<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined>(params?: GetPostsParams<TSelect>): Promise<PostListResult<SelectFields<BlogPostSummary, TSelect>>>;
+/**
+ * Searches published posts using the default client.
+ */
+declare function searchPosts<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined>(params: SearchPostsParams<TSelect>): Promise<PostListResult<SelectFields<BlogPostSummary, TSelect>>>;
+/**
+ * Fetches a single published post by slug using the default client.
+ */
+declare function 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 using the default client.
+ */
+declare function getPostById<TSelect extends readonly BlogPostField[] | undefined = undefined>(id: number, params?: GetPostParams<TSelect>): Promise<SelectFields<BlogPost, TSelect> | null>;
+/**
+ * Executes a raw request against REST.
+ */
+declare function queryRaw<TData = unknown>(params: QueryRawParams): Promise<TData>;
+/**
+ * Executes a raw GraphQL request using the default client.
+ */
+declare function queryGraphql<TData = unknown>(params: QueryGraphqlParams): Promise<QueryGraphqlResult<TData>>;
+/**
+ * Fetches categories from the default client.
+ */
+declare function getCategories(params?: GetTermsParams): Promise<BlogTerm[]>;
+/**
+ * Fetches tags from the default client.
+ */
+declare function getTags(params?: GetTermsParams): Promise<BlogTerm[]>;
+/**
+ * Fetches authors from the default client.
+ */
+declare function getAuthors(params?: GetAuthorsParams): Promise<WpAuthor[]>;
+/**
+ * Fetches a single author by ID from the default client.
+ */
+declare function getAuthorById(id: number): Promise<WpAuthor | null>;
+
+export { BlogPost, BlogPostField, BlogPostSummary, BlogPostSummaryField, BlogTerm, GetAuthorsParams, GetPostParams, GetPostsParams, GetTermsParams, PlaceholderParseOptions, PostListResult, QueryGraphqlParams, QueryGraphqlResult, QueryRawParams, SearchPostsParams, SelectFields, type WpApiErrorDetails, WpAuthor, WpBlogClient, WpClientError, type WpClientErrorCode, WpClientOptions, WpContentPart, createWpBlogClient, getAuthorById, getAuthors, getCategories, getPostById, getPostBySlug, getPosts, getTags, parseContentPlaceholders, queryGraphql, queryRaw, searchPosts };

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+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-BDmCnhFG.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-BDmCnhFG.js';
+
+type WpClientErrorCode = "INVALID_CONFIG" | "INVALID_INPUT" | "REQUEST_FAILED" | "INVALID_RESPONSE";
+interface WpApiErrorDetails {
+    wpCode?: string;
+    wpMessage?: string;
+    wpData?: unknown;
+}
+/**
+ * Error thrown by the WordPress adapter for config, input, request, or response failures.
+ */
+declare class WpClientError extends Error {
+    readonly code: WpClientErrorCode;
+    readonly status?: number;
+    readonly wpCode?: string;
+    readonly wpMessage?: string;
+    readonly wpData?: unknown;
+    constructor(code: WpClientErrorCode, message: string, status?: number, details?: WpApiErrorDetails);
+}
+
+/**
+ * Parses placeholder comments from HTML content.
+ *
+ * Marker format:
+ * - <!-- wpapp:cta {"title":"..."} -->
+ * - <!-- wpapp:newsletter -->
+ *
+ * Invalid placeholders are left as normal HTML content.
+ */
+declare function parseContentPlaceholders(contentHtml: string, options?: PlaceholderParseOptions): WpContentPart[];
+
+/**
+ * Creates an explicit WordPress blog client with the provided options.
+ */
+declare function createWpBlogClient(clientOptions?: WpClientOptions): WpBlogClient;
+/**
+ * Fetches published posts using a lazily created env-based default client.
+ */
+declare function getPosts<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined>(params?: GetPostsParams<TSelect>): Promise<PostListResult<SelectFields<BlogPostSummary, TSelect>>>;
+/**
+ * Searches published posts using the default client.
+ */
+declare function searchPosts<TSelect extends readonly BlogPostSummaryField[] | undefined = undefined>(params: SearchPostsParams<TSelect>): Promise<PostListResult<SelectFields<BlogPostSummary, TSelect>>>;
+/**
+ * Fetches a single published post by slug using the default client.
+ */
+declare function 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 using the default client.
+ */
+declare function getPostById<TSelect extends readonly BlogPostField[] | undefined = undefined>(id: number, params?: GetPostParams<TSelect>): Promise<SelectFields<BlogPost, TSelect> | null>;
+/**
+ * Executes a raw request against REST.
+ */
+declare function queryRaw<TData = unknown>(params: QueryRawParams): Promise<TData>;
+/**
+ * Executes a raw GraphQL request using the default client.
+ */
+declare function queryGraphql<TData = unknown>(params: QueryGraphqlParams): Promise<QueryGraphqlResult<TData>>;
+/**
+ * Fetches categories from the default client.
+ */
+declare function getCategories(params?: GetTermsParams): Promise<BlogTerm[]>;
+/**
+ * Fetches tags from the default client.
+ */
+declare function getTags(params?: GetTermsParams): Promise<BlogTerm[]>;
+/**
+ * Fetches authors from the default client.
+ */
+declare function getAuthors(params?: GetAuthorsParams): Promise<WpAuthor[]>;
+/**
+ * Fetches a single author by ID from the default client.
+ */
+declare function getAuthorById(id: number): Promise<WpAuthor | null>;
+
+export { BlogPost, BlogPostField, BlogPostSummary, BlogPostSummaryField, BlogTerm, GetAuthorsParams, GetPostParams, GetPostsParams, GetTermsParams, PlaceholderParseOptions, PostListResult, QueryGraphqlParams, QueryGraphqlResult, QueryRawParams, SearchPostsParams, SelectFields, type WpApiErrorDetails, WpAuthor, WpBlogClient, WpClientError, type WpClientErrorCode, WpClientOptions, WpContentPart, createWpBlogClient, getAuthorById, getAuthors, getCategories, getPostById, getPostBySlug, getPosts, getTags, parseContentPlaceholders, queryGraphql, queryRaw, searchPosts };