@vigilkids/cms-client 0.1.3 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-06-03
+
+### Added
+
+- Added `searchArticles` for published article search through the CMS Public API.
+- Added `ArticleSearchParams` and `ArticleSearchResultItem` public types.
+- Added article list sorting parameters through `ArticleListParams.sort_by` and `ArticleListParams.sort_order`.
+- Added sitemap route metadata, hreflang route parameters, and `SitemapImageEntry` image metadata types.
+
+### Changed
+
+- Included `CHANGELOG.md` in the published package contents.
+
+## [0.1.2] - 2026-03-26
+
+### Added
+
+- `last_published_at` field to `ArticleListItem` type (aligns with backend `DeliveryArticleListItem`)
+
+## [0.1.0] - 2026-03-23
+
+### Added
+
+- ESLint flat config (`@antfu/eslint-config`) + Prettier
+
+### Changed
+
+- Codebase formatted with Prettier (singleQuote, no semi, printWidth 100)
+
+## [0.0.1] - 2025-03-23
+
+### Added
+
+- CMS API client with typed request/response interfaces
+- Article delivery API (getBySlug, list, categories, sitemap)
+- Preview token validation
+- Webhook payload types for content events
+- TypeScript-first with full type exports

package/README.md

@@ -1,6 +1,6 @@
 # @vigilkids/cms-client
 
-TypeScript HTTP client for the OneX CMS delivery API. Framework-agnostic — works with any HTTP client (fetch, axios, etc.).
+Framework-agnostic TypeScript client for the OneX CMS Public API. It provides a typed fetch-based client for published CMS content, sitemap data, redirects, comments, authors, series, and server-side webhook signature verification.
 
 ## Install
 
@@ -8,36 +8,177 @@ TypeScript HTTP client for the OneX CMS delivery API. Framework-agnostic — wor
 pnpm add @vigilkids/cms-client
 ```
 
-## Usage
+## Configuration
+
+The `baseUrl` must point at the CMS Public API root that serves `/articles`, `/search`, `/sitemap`, and the other delivery endpoints.
+
+```typescript
+import { createCmsClient } from '@vigilkids/cms-client'
+
+export const cms = createCmsClient({
+  baseUrl: 'https://api.example.com/api/v1/cms',
+  productCode: 'example-product',
+  defaultLocale: 'en',
+  timeout: 10_000,
+})
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `baseUrl` | Yes | CMS Public API base URL. |
+| `productCode` | No | Adds `X-Product-Code` to each request. |
+| `defaultLocale` | No | Locale automatically added to GET requests when no locale is provided. Defaults to `en`. |
+| `previewToken` | No | Adds `X-Preview-Token` to each request. |
+| `fetch` | No | Custom fetch-compatible implementation. Defaults to `globalThis.fetch`. |
+| `timeout` | No | Request timeout in milliseconds. Defaults to `10000`. |
+| `headers` | No | Additional request headers merged into each request. |
+
+## Articles
+
+Use `getArticles`, `getArticle`, and `searchArticles` for published article delivery.
+
+```typescript
+import { createCmsClient } from '@vigilkids/cms-client'
+
+const cms = createCmsClient({
+  baseUrl: 'https://api.example.com/api/v1/cms',
+  defaultLocale: 'en',
+})
+
+export async function loadArticles(): Promise<void> {
+  const articlePage = await cms.getArticles({
+    page: 1,
+    page_size: 10,
+    sort_by: 'last_published_at',
+    sort_order: 'desc',
+  })
+
+  const article = await cms.getArticle('getting-started', 'en')
+
+  const searchPage = await cms.searchArticles({
+    q: 'privacy',
+    locale: 'en',
+    page: 1,
+    page_size: 5,
+  })
+
+  console.log(articlePage.pagination.total, article.title, searchPage.data.length)
+}
+```
+
+Related article and taxonomy helpers are available when the consuming app needs more content context.
 
 ```typescript
 import { createCmsClient } from '@vigilkids/cms-client'
 
 const cms = createCmsClient({
-  baseUrl: 'https://api.example.com',
-  productCode: 'visiva',
+  baseUrl: 'https://api.example.com/api/v1/cms',
+  defaultLocale: 'en',
 })
 
-// Fetch article by slug
-const article = await cms.getArticleBySlug('my-article', { locale: 'en' })
+export async function loadArticleContext(slug: string): Promise<void> {
+  const related = await cms.getRelatedArticles(slug, { limit: 3, locale: 'en' })
+  const categories = await cms.getCategories()
 
-// List articles
-const { data, pagination } = await cms.listArticles({ page: 1, pageSize: 20 })
+  console.log(related.map(article => article.slug), categories.length)
+}
 ```
 
+## Sitemap
+
+Use `getSitemap` to retrieve CMS-managed sitemap entries, including optional route parameters, hreflang entries, and image metadata.
+
+```typescript
+import type { SitemapEntry } from '@vigilkids/cms-client'
+import { createCmsClient } from '@vigilkids/cms-client'
+
+const cms = createCmsClient({
+  baseUrl: 'https://api.example.com/api/v1/cms',
+  defaultLocale: 'en',
+})
+
+export async function loadSitemap(): Promise<SitemapEntry[]> {
+  const entries = await cms.getSitemap('en')
+  return entries.filter(entry => entry.loc.startsWith('https://'))
+}
+```
+
+## Webhook Verification
+
+Import webhook helpers from the webhook entry point. Verification uses HMAC-SHA256 and expects a signature formatted as `sha256=<hex>`.
+
+```typescript
+import type { RevalidatePayload } from '@vigilkids/cms-client'
+import { verifyWebhookSignature } from '@vigilkids/cms-client/webhook'
+
+export function parseCmsWebhook(
+  rawBody: string,
+  signature: string,
+  secret: string,
+): RevalidatePayload {
+  const verified = verifyWebhookSignature({
+    rawBody,
+    signature,
+    secret,
+  })
+
+  if (!verified) {
+    throw new Error('Invalid CMS webhook signature')
+  }
+
+  return JSON.parse(rawBody) as RevalidatePayload
+}
+```
+
+## Client Methods
+
+| Area | Methods |
+|------|---------|
+| Articles | `getArticles`, `getArticle`, `getRelatedArticles`, `searchArticles` |
+| Authors | `getAuthorsPage`, `getAuthors`, `getAuthor`, `getAuthorArticlesPage`, `getAuthorArticles` |
+| Categories | `getCategories` |
+| Comments | `getComments`, `createComment` |
+| Sitemap, redirects, series | `getSitemap`, `getRedirects`, `getSeries` |
+
 ## Exports
 
 | Entry Point | Import | Content |
 |-------------|--------|---------|
-| Main | `@vigilkids/cms-client` | Client factory and API methods |
-| Types | `@vigilkids/cms-client/types` | Request/response type definitions |
-| Webhook | `@vigilkids/cms-client/webhook` | Webhook payload types and validation |
+| Main | `@vigilkids/cms-client` | `CmsClient`, `createCmsClient`, `CmsApiError`, `CmsClientConfig`, and all public request/response types |
+| Types | `@vigilkids/cms-client/types` | Public CMS request/response type definitions |
+| Webhook | `@vigilkids/cms-client/webhook` | `verifyWebhookSignature` and `VerifyWebhookOptions` |
+
+## Error Handling
+
+`CmsApiError` is thrown for non-2xx API responses.
+
+```typescript
+import { CmsApiError, createCmsClient } from '@vigilkids/cms-client'
+
+const cms = createCmsClient({
+  baseUrl: 'https://api.example.com/api/v1/cms',
+})
+
+export async function loadRequiredArticle(slug: string): Promise<string> {
+  try {
+    const article = await cms.getArticle(slug)
+    return article.title
+  }
+  catch (error) {
+    if (error instanceof CmsApiError && error.isNotFound) {
+      return 'Article not found'
+    }
+    throw error
+  }
+}
+```
 
 ## Compatibility
 
-- Node.js ≥ 18
-- ESM only
-- TypeScript ≥ 5.0
+- ESM package.
+- Main client requires a fetch-compatible runtime. Node.js 18+ provides `globalThis.fetch`; other runtimes can pass `fetch` in the client configuration.
+- `@vigilkids/cms-client/webhook` uses Node.js `crypto` and `Buffer`, so signature verification should run in a server runtime.
+- TypeScript declarations are included with the package.
 
 ## License
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { ArticleListParams, Paginated, ArticleListItem, ArticleDetail, PaginationParams, Author, CategoryNode, Comment, CreateCommentPayload, SitemapEntry, RedirectRule, Series } from './types.mjs';
-export { HreflangEntry, ListResponse, LocalizedString, OgMeta, PaginationMeta, RevalidatePayload, SeoMeta, TwitterMeta, WebhookEventType } from './types.mjs';
+import { ArticleListParams, Paginated, ArticleListItem, ArticleDetail, ArticleSearchParams, ArticleSearchResultItem, PaginationParams, Author, CategoryNode, Comment, CreateCommentPayload, SitemapEntry, RedirectRule, Series } from './types.mjs';
+export { HreflangEntry, ListResponse, LocalizedString, OgMeta, PaginationMeta, RevalidatePayload, SeoMeta, SitemapImageEntry, TwitterMeta, WebhookEventType } from './types.mjs';
 
 /** CMS 客户端配置 */
 interface CmsClientConfig {
@@ -33,6 +33,8 @@ declare class CmsClient {
         limit?: number;
         locale?: string;
     }): Promise<ArticleListItem[]>;
+    /** 搜索已发布文章 */
+    searchArticles(params: ArticleSearchParams): Promise<Paginated<ArticleSearchResultItem>>;
     /** 获取作者分页列表 */
     getAuthorsPage(options?: {
         locale?: string;
@@ -84,5 +86,5 @@ declare class CmsApiError extends Error {
     get isUnauthorized(): boolean;
 }
 
-export { ArticleDetail, ArticleListItem, ArticleListParams, Author, CategoryNode, CmsApiError, CmsClient, Comment, CreateCommentPayload, Paginated, PaginationParams, RedirectRule, Series, SitemapEntry, createCmsClient };
+export { ArticleDetail, ArticleListItem, ArticleListParams, ArticleSearchParams, ArticleSearchResultItem, Author, CategoryNode, CmsApiError, CmsClient, Comment, CreateCommentPayload, Paginated, PaginationParams, RedirectRule, Series, SitemapEntry, createCmsClient };
 export type { CmsClientConfig };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ArticleListParams, Paginated, ArticleListItem, ArticleDetail, PaginationParams, Author, CategoryNode, Comment, CreateCommentPayload, SitemapEntry, RedirectRule, Series } from './types.js';
-export { HreflangEntry, ListResponse, LocalizedString, OgMeta, PaginationMeta, RevalidatePayload, SeoMeta, TwitterMeta, WebhookEventType } from './types.js';
+import { ArticleListParams, Paginated, ArticleListItem, ArticleDetail, ArticleSearchParams, ArticleSearchResultItem, PaginationParams, Author, CategoryNode, Comment, CreateCommentPayload, SitemapEntry, RedirectRule, Series } from './types.js';
+export { HreflangEntry, ListResponse, LocalizedString, OgMeta, PaginationMeta, RevalidatePayload, SeoMeta, SitemapImageEntry, TwitterMeta, WebhookEventType } from './types.js';
 
 /** CMS 客户端配置 */
 interface CmsClientConfig {
@@ -33,6 +33,8 @@ declare class CmsClient {
         limit?: number;
         locale?: string;
     }): Promise<ArticleListItem[]>;
+    /** 搜索已发布文章 */
+    searchArticles(params: ArticleSearchParams): Promise<Paginated<ArticleSearchResultItem>>;
     /** 获取作者分页列表 */
     getAuthorsPage(options?: {
         locale?: string;
@@ -84,5 +86,5 @@ declare class CmsApiError extends Error {
     get isUnauthorized(): boolean;
 }
 
-export { ArticleDetail, ArticleListItem, ArticleListParams, Author, CategoryNode, CmsApiError, CmsClient, Comment, CreateCommentPayload, Paginated, PaginationParams, RedirectRule, Series, SitemapEntry, createCmsClient };
+export { ArticleDetail, ArticleListItem, ArticleListParams, ArticleSearchParams, ArticleSearchResultItem, Author, CategoryNode, CmsApiError, CmsClient, Comment, CreateCommentPayload, Paginated, PaginationParams, RedirectRule, Series, SitemapEntry, createCmsClient };
 export type { CmsClientConfig };

package/dist/index.mjs

@@ -32,6 +32,23 @@ function parseApiErrorEnvelope(body) {
   }
   return null;
 }
+function normalizeListResponse(body, endpoint) {
+  if (Array.isArray(body)) {
+    return body;
+  }
+  if (typeof body === "object" && body !== null && "data" in body) {
+    const data = body.data;
+    if (Array.isArray(data)) {
+      return data;
+    }
+  }
+  throw new CmsApiError(
+    500,
+    "INVALID_LIST_RESPONSE",
+    `CMS API returned invalid list response for ${endpoint}`,
+    body
+  );
+}
 class CmsClient {
   config;
   fetchFn;
@@ -54,12 +71,21 @@ class CmsClient {
   }
   /** 获取相关文章 */
   async getRelatedArticles(slug, options) {
+    const endpoint = `/articles/${encodeURIComponent(slug)}/related`;
     const result = await this.request(
       "GET",
-      `/articles/${encodeURIComponent(slug)}/related`,
+      endpoint,
       options
     );
-    return result.data;
+    return normalizeListResponse(result, endpoint);
+  }
+  /** 搜索已发布文章 */
+  async searchArticles(params) {
+    return this.request(
+      "GET",
+      "/search",
+      params
+    );
   }
   // ─── 作者 ───────────────────────────────────────────
   /** 获取作者分页列表 */
@@ -69,7 +95,7 @@ class CmsClient {
   /** 获取所有作者 */
   async getAuthors(options) {
     const result = await this.getAuthorsPage(options);
-    return result.data;
+    return normalizeListResponse(result, "/authors");
   }
   /** 获取作者详情 */
   async getAuthor(slug, locale) {
@@ -86,13 +112,19 @@ class CmsClient {
   /** 获取作者的文章列表 */
   async getAuthorArticles(slug, options) {
     const result = await this.getAuthorArticlesPage(slug, options);
-    return result.data;
+    return normalizeListResponse(
+      result,
+      `/authors/${encodeURIComponent(slug)}/articles`
+    );
   }
   // ─── 分类 ───────────────────────────────────────────
   /** 获取分类树 */
   async getCategories() {
-    const result = await this.request("GET", "/categories");
-    return result.data;
+    const result = await this.request(
+      "GET",
+      "/categories"
+    );
+    return normalizeListResponse(result, "/categories");
   }
   // ─── 评论 ───────────────────────────────────────────
   /** 获取文章评论树 */
@@ -111,13 +143,20 @@ class CmsClient {
   // ─── Sitemap / 重定向 / 系列 ──────────────────────
   /** 获取 Sitemap 条目 */
   async getSitemap(locale) {
-    const result = await this.request("GET", "/sitemap", { locale });
-    return result.data;
+    const result = await this.request(
+      "GET",
+      "/sitemap",
+      { locale }
+    );
+    return normalizeListResponse(result, "/sitemap");
   }
   /** 获取重定向规则 */
   async getRedirects() {
-    const result = await this.request("GET", "/redirects");
-    return result.data;
+    const result = await this.request(
+      "GET",
+      "/redirects"
+    );
+    return normalizeListResponse(result, "/redirects");
   }
   /** 获取文章系列 */
   async getSeries(slug, locale) {

package/dist/types.d.mts

@@ -81,6 +81,29 @@ interface ArticleListParams extends PaginationParams {
     category_slug?: string;
     tag?: string;
     is_pinned?: boolean;
+    sort_by?: string;
+    sort_order?: 'asc' | 'desc';
+}
+/** 文章搜索查询参数 */
+interface ArticleSearchParams extends PaginationParams {
+    locale?: string;
+    q: string;
+}
+/** 文章搜索结果项 */
+interface ArticleSearchResultItem {
+    article_id: number;
+    title: string;
+    excerpt?: string;
+    slug: string;
+    score: number;
+    category_slug?: string;
+    featured_image_url?: string;
+    featured_image_alt?: string;
+    published_at?: string | null;
+    last_published_at?: string | null;
+    reading_time_minutes?: number;
+    tags?: string[];
+    authors?: Author[];
 }
 /** SEO 元信息 */
 interface SeoMeta {
@@ -157,14 +180,23 @@ interface Series {
 interface HreflangEntry {
     lang: string;
     href: string;
+    route_params?: Record<string, string | number | boolean | null | undefined>;
+}
+/** Sitemap 图片条目 */
+interface SitemapImageEntry {
+    loc: string;
+    title?: string;
 }
 /** Sitemap 条目 (Go: delivery.SitemapEntryResponse) */
 interface SitemapEntry {
     loc: string;
+    resource_type?: string;
+    route_params?: Record<string, string | number | boolean | null | undefined>;
     last_mod: string;
     change_freq: string;
     priority: number;
     hreflang?: HreflangEntry[];
+    images?: SitemapImageEntry[];
 }
 
 /** Webhook 事件类型 */
@@ -177,4 +209,4 @@ interface RevalidatePayload {
     category_slug?: string;
 }
 
-export type { ArticleDetail, ArticleListItem, ArticleListParams, Author, CategoryNode, Comment, CreateCommentPayload, HreflangEntry, ListResponse, LocalizedString, OgMeta, Paginated, PaginationMeta, PaginationParams, RedirectRule, RevalidatePayload, SeoMeta, Series, SitemapEntry, TwitterMeta, WebhookEventType };
+export type { ArticleDetail, ArticleListItem, ArticleListParams, ArticleSearchParams, ArticleSearchResultItem, Author, CategoryNode, Comment, CreateCommentPayload, HreflangEntry, ListResponse, LocalizedString, OgMeta, Paginated, PaginationMeta, PaginationParams, RedirectRule, RevalidatePayload, SeoMeta, Series, SitemapEntry, SitemapImageEntry, TwitterMeta, WebhookEventType };

package/dist/types.d.ts

@@ -81,6 +81,29 @@ interface ArticleListParams extends PaginationParams {
     category_slug?: string;
     tag?: string;
     is_pinned?: boolean;
+    sort_by?: string;
+    sort_order?: 'asc' | 'desc';
+}
+/** 文章搜索查询参数 */
+interface ArticleSearchParams extends PaginationParams {
+    locale?: string;
+    q: string;
+}
+/** 文章搜索结果项 */
+interface ArticleSearchResultItem {
+    article_id: number;
+    title: string;
+    excerpt?: string;
+    slug: string;
+    score: number;
+    category_slug?: string;
+    featured_image_url?: string;
+    featured_image_alt?: string;
+    published_at?: string | null;
+    last_published_at?: string | null;
+    reading_time_minutes?: number;
+    tags?: string[];
+    authors?: Author[];
 }
 /** SEO 元信息 */
 interface SeoMeta {
@@ -157,14 +180,23 @@ interface Series {
 interface HreflangEntry {
     lang: string;
     href: string;
+    route_params?: Record<string, string | number | boolean | null | undefined>;
+}
+/** Sitemap 图片条目 */
+interface SitemapImageEntry {
+    loc: string;
+    title?: string;
 }
 /** Sitemap 条目 (Go: delivery.SitemapEntryResponse) */
 interface SitemapEntry {
     loc: string;
+    resource_type?: string;
+    route_params?: Record<string, string | number | boolean | null | undefined>;
     last_mod: string;
     change_freq: string;
     priority: number;
     hreflang?: HreflangEntry[];
+    images?: SitemapImageEntry[];
 }
 
 /** Webhook 事件类型 */
@@ -177,4 +209,4 @@ interface RevalidatePayload {
     category_slug?: string;
 }
 
-export type { ArticleDetail, ArticleListItem, ArticleListParams, Author, CategoryNode, Comment, CreateCommentPayload, HreflangEntry, ListResponse, LocalizedString, OgMeta, Paginated, PaginationMeta, PaginationParams, RedirectRule, RevalidatePayload, SeoMeta, Series, SitemapEntry, TwitterMeta, WebhookEventType };
+export type { ArticleDetail, ArticleListItem, ArticleListParams, ArticleSearchParams, ArticleSearchResultItem, Author, CategoryNode, Comment, CreateCommentPayload, HreflangEntry, ListResponse, LocalizedString, OgMeta, Paginated, PaginationMeta, PaginationParams, RedirectRule, RevalidatePayload, SeoMeta, Series, SitemapEntry, SitemapImageEntry, TwitterMeta, WebhookEventType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vigilkids/cms-client",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Framework-agnostic TypeScript client for OnEx CMS Public API",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -20,7 +20,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "sideEffects": false,
   "scripts": {
@@ -34,7 +35,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/1yhy/onex.git",
+    "url": "git+https://github.com/vigikids/onex.git",
     "directory": "packages/cms-client"
   },
   "devDependencies": {