@vigilkids/cms-client 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.3.1] - 2026-06-05
+
+### Added
+
+- Added `RedirectRule.priority` for CMS delivery redirect ordering metadata.
+
+## [0.3.0] - 2026-06-03
+
+### Added
+
+- Added localized category SEO, Open Graph, and Twitter Card metadata map types.
+- Added category node metadata fields for CMS taxonomy landing pages.
+
 ## [0.2.0] - 2026-06-03
 
 ### Added

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 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';
+export { HreflangEntry, ListResponse, LocalizedOgMetaMap, LocalizedSeoMetaMap, LocalizedString, LocalizedTwitterMetaMap, OgMeta, PaginationMeta, RevalidatePayload, SeoMeta, SitemapImageEntry, TwitterMeta, WebhookEventType } from './types.mjs';
+export { BuildRoutePathOptions, BuildRouteUrlOptions, DEFAULT_ROUTE_RESOURCES, ResolvedRouteLocalePolicy, ResolvedRoutePolicy, RouteLocalePolicy, RouteParams, RoutePolicy, RoutePolicyConfig, RouteResourceDefaults, RouteResources, buildRoutePath, buildRouteUrl, extractRouteParams, extractSourceRouteParams, formatRoutePolicy, hasCustomArticleRoute, isRoutePolicy, mergeRouteParams, resolveRoutePolicy } from './routes.mjs';
 
 /** CMS 客户端配置 */
 interface CmsClientConfig {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 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';
+export { HreflangEntry, ListResponse, LocalizedOgMetaMap, LocalizedSeoMetaMap, LocalizedString, LocalizedTwitterMetaMap, OgMeta, PaginationMeta, RevalidatePayload, SeoMeta, SitemapImageEntry, TwitterMeta, WebhookEventType } from './types.js';
+export { BuildRoutePathOptions, BuildRouteUrlOptions, DEFAULT_ROUTE_RESOURCES, ResolvedRouteLocalePolicy, ResolvedRoutePolicy, RouteLocalePolicy, RouteParams, RoutePolicy, RoutePolicyConfig, RouteResourceDefaults, RouteResources, buildRoutePath, buildRouteUrl, extractRouteParams, extractSourceRouteParams, formatRoutePolicy, hasCustomArticleRoute, isRoutePolicy, mergeRouteParams, resolveRoutePolicy } from './routes.js';
 
 /** CMS 客户端配置 */
 interface CmsClientConfig {

package/dist/index.mjs

@@ -1,3 +1,5 @@
+export { DEFAULT_ROUTE_RESOURCES, buildRoutePath, buildRouteUrl, extractRouteParams, extractSourceRouteParams, formatRoutePolicy, hasCustomArticleRoute, isRoutePolicy, mergeRouteParams, resolveRoutePolicy } from './routes.mjs';
+
 const DEFAULT_CONFIG = {
   defaultLocale: "en",
   timeout: 1e4

package/dist/routes.d.mts

@@ -0,0 +1,54 @@
+type RouteParams = Record<string, string | number | boolean | null | undefined>;
+interface RouteResources {
+    index?: string;
+    category?: string;
+    article?: string;
+    author?: string;
+    [resource: string]: string | undefined;
+}
+interface RouteLocalePolicy {
+    defaultLocale?: string;
+    prefixes?: Record<string, string>;
+    includeDefaultLocale?: boolean;
+}
+interface RoutePolicy {
+    resources?: RouteResources;
+    sourceResources?: RouteResources;
+    locale?: RouteLocalePolicy;
+}
+interface RoutePolicyConfig {
+    defaultLocale?: string;
+    localePrefixes?: Record<string, string>;
+    routes?: RoutePolicy;
+}
+interface BuildRoutePathOptions {
+    includeLocale?: boolean;
+}
+interface BuildRouteUrlOptions extends BuildRoutePathOptions {
+}
+interface ResolvedRouteLocalePolicy {
+    defaultLocale: string;
+    prefixes: Record<string, string>;
+    includeDefaultLocale: boolean;
+}
+type RouteResourceDefaults = RouteResources & Required<Pick<RouteResources, 'article' | 'author' | 'category' | 'index'>>;
+interface ResolvedRoutePolicy {
+    resources: RouteResourceDefaults;
+    sourceResources: RouteResourceDefaults;
+    locale: ResolvedRouteLocalePolicy;
+}
+declare const DEFAULT_ROUTE_RESOURCES: RouteResourceDefaults;
+declare function resolveRoutePolicy(config?: RoutePolicyConfig): ResolvedRoutePolicy;
+declare function buildRoutePath(policy: RoutePolicy, resource: string, params?: RouteParams, options?: BuildRoutePathOptions): string;
+declare function buildRouteUrl(baseUrl: string, policy: null | RoutePolicy | undefined, resource: string, params?: RouteParams, options?: BuildRouteUrlOptions): string;
+declare function isRoutePolicy(value: unknown): value is RoutePolicy;
+declare function hasCustomArticleRoute(policy?: null | RoutePolicy): boolean;
+declare function formatRoutePolicy(policy?: null | RoutePolicy): string;
+declare function extractRouteParams(pattern: string, path: string): RouteParams | null;
+declare function extractSourceRouteParams(policy: RoutePolicy, resource: string, path: string): RouteParams | null;
+declare function mergeRouteParams(left: RouteParams | null | undefined, right: RouteParams | null | undefined): {
+    [x: string]: string | number | boolean | null | undefined;
+};
+
+export { DEFAULT_ROUTE_RESOURCES, buildRoutePath, buildRouteUrl, extractRouteParams, extractSourceRouteParams, formatRoutePolicy, hasCustomArticleRoute, isRoutePolicy, mergeRouteParams, resolveRoutePolicy };
+export type { BuildRoutePathOptions, BuildRouteUrlOptions, ResolvedRouteLocalePolicy, ResolvedRoutePolicy, RouteLocalePolicy, RouteParams, RoutePolicy, RoutePolicyConfig, RouteResourceDefaults, RouteResources };

package/dist/routes.d.ts

@@ -0,0 +1,54 @@
+type RouteParams = Record<string, string | number | boolean | null | undefined>;
+interface RouteResources {
+    index?: string;
+    category?: string;
+    article?: string;
+    author?: string;
+    [resource: string]: string | undefined;
+}
+interface RouteLocalePolicy {
+    defaultLocale?: string;
+    prefixes?: Record<string, string>;
+    includeDefaultLocale?: boolean;
+}
+interface RoutePolicy {
+    resources?: RouteResources;
+    sourceResources?: RouteResources;
+    locale?: RouteLocalePolicy;
+}
+interface RoutePolicyConfig {
+    defaultLocale?: string;
+    localePrefixes?: Record<string, string>;
+    routes?: RoutePolicy;
+}
+interface BuildRoutePathOptions {
+    includeLocale?: boolean;
+}
+interface BuildRouteUrlOptions extends BuildRoutePathOptions {
+}
+interface ResolvedRouteLocalePolicy {
+    defaultLocale: string;
+    prefixes: Record<string, string>;
+    includeDefaultLocale: boolean;
+}
+type RouteResourceDefaults = RouteResources & Required<Pick<RouteResources, 'article' | 'author' | 'category' | 'index'>>;
+interface ResolvedRoutePolicy {
+    resources: RouteResourceDefaults;
+    sourceResources: RouteResourceDefaults;
+    locale: ResolvedRouteLocalePolicy;
+}
+declare const DEFAULT_ROUTE_RESOURCES: RouteResourceDefaults;
+declare function resolveRoutePolicy(config?: RoutePolicyConfig): ResolvedRoutePolicy;
+declare function buildRoutePath(policy: RoutePolicy, resource: string, params?: RouteParams, options?: BuildRoutePathOptions): string;
+declare function buildRouteUrl(baseUrl: string, policy: null | RoutePolicy | undefined, resource: string, params?: RouteParams, options?: BuildRouteUrlOptions): string;
+declare function isRoutePolicy(value: unknown): value is RoutePolicy;
+declare function hasCustomArticleRoute(policy?: null | RoutePolicy): boolean;
+declare function formatRoutePolicy(policy?: null | RoutePolicy): string;
+declare function extractRouteParams(pattern: string, path: string): RouteParams | null;
+declare function extractSourceRouteParams(policy: RoutePolicy, resource: string, path: string): RouteParams | null;
+declare function mergeRouteParams(left: RouteParams | null | undefined, right: RouteParams | null | undefined): {
+    [x: string]: string | number | boolean | null | undefined;
+};
+
+export { DEFAULT_ROUTE_RESOURCES, buildRoutePath, buildRouteUrl, extractRouteParams, extractSourceRouteParams, formatRoutePolicy, hasCustomArticleRoute, isRoutePolicy, mergeRouteParams, resolveRoutePolicy };
+export type { BuildRoutePathOptions, BuildRouteUrlOptions, ResolvedRouteLocalePolicy, ResolvedRoutePolicy, RouteLocalePolicy, RouteParams, RoutePolicy, RoutePolicyConfig, RouteResourceDefaults, RouteResources };

package/dist/routes.mjs

@@ -0,0 +1,147 @@
+const DEFAULT_ROUTE_RESOURCES = {
+  index: "/",
+  category: "/{category_slug}",
+  article: "/{category_slug}/{slug}",
+  author: "/authors/{slug}"
+};
+function trimSlashes(value) {
+  return value.replace(/^\/+|\/+$/g, "");
+}
+function normalizePath(path) {
+  const clean = path.split("?")[0]?.split("#")[0] ?? "";
+  const withSlash = clean.startsWith("/") ? clean : `/${clean}`;
+  const collapsed = withSlash.replace(/\/{2,}/g, "/");
+  if (collapsed.length > 1) return collapsed.replace(/\/+$/g, "");
+  return collapsed;
+}
+function encodePathValue(value) {
+  return encodeURIComponent(String(value));
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringRecord(value) {
+  if (!isPlainObject(value)) return false;
+  return Object.values(value).every((item) => typeof item === "string");
+}
+function localePrefix(locale, policy) {
+  if (!locale) return "";
+  if (locale === policy.defaultLocale && !policy.includeDefaultLocale) return "";
+  const prefix = policy.prefixes[locale] ?? locale.toLowerCase();
+  return `/${trimSlashes(prefix)}`;
+}
+function mergeResources(resources) {
+  return {
+    ...DEFAULT_ROUTE_RESOURCES,
+    ...resources ?? {}
+  };
+}
+function resolveRoutePolicy(config) {
+  const routes = config?.routes ?? {};
+  const defaultLocale = routes.locale?.defaultLocale ?? config?.defaultLocale ?? "en";
+  const prefixes = {
+    ...config?.localePrefixes ?? {},
+    ...routes.locale?.prefixes ?? {}
+  };
+  return {
+    resources: mergeResources(routes.resources),
+    sourceResources: mergeResources(routes.sourceResources),
+    locale: {
+      defaultLocale,
+      prefixes,
+      includeDefaultLocale: routes.locale?.includeDefaultLocale ?? false
+    }
+  };
+}
+function buildRoutePath(policy, resource, params = {}, options = {}) {
+  const resolvedPolicy = resolveRoutePolicy({ routes: policy });
+  const pattern = resolvedPolicy.resources[resource];
+  if (!pattern) {
+    throw new Error(`CMS route pattern is not configured for resource '${resource}'`);
+  }
+  const path = normalizePath(
+    pattern.replace(/\{(\w+)\}/g, (_, key) => {
+      const value = params[key];
+      if (value === void 0 || value === null || value === "") {
+        throw new Error(`CMS route parameter '${key}' is required for resource '${resource}'`);
+      }
+      return encodePathValue(value);
+    })
+  );
+  if (!options.includeLocale) return path;
+  return normalizePath(`${localePrefix(String(params.locale ?? ""), resolvedPolicy.locale)}${path}`);
+}
+function buildRouteUrl(baseUrl, policy, resource, params = {}, options = {}) {
+  const path = buildRoutePath(policy ?? {}, resource, params, options);
+  const normalizedBaseUrl = baseUrl.replace(/\/+$/g, "");
+  return normalizedBaseUrl ? `${normalizedBaseUrl}${path}` : path;
+}
+function isRoutePolicy(value) {
+  if (!isPlainObject(value)) return false;
+  const { locale, resources, sourceResources } = value;
+  if (resources !== void 0 && !isStringRecord(resources)) return false;
+  if (sourceResources !== void 0 && !isStringRecord(sourceResources)) return false;
+  if (locale !== void 0) {
+    if (!isPlainObject(locale)) return false;
+    if (locale.defaultLocale !== void 0 && typeof locale.defaultLocale !== "string") return false;
+    if (locale.includeDefaultLocale !== void 0 && typeof locale.includeDefaultLocale !== "boolean")
+      return false;
+    if (locale.prefixes !== void 0 && !isStringRecord(locale.prefixes)) return false;
+  }
+  return true;
+}
+function hasCustomArticleRoute(policy) {
+  return resolveRoutePolicy({ routes: policy ?? void 0 }).resources.article !== DEFAULT_ROUTE_RESOURCES.article;
+}
+function formatRoutePolicy(policy) {
+  return JSON.stringify(resolveRoutePolicy({ routes: policy ?? void 0 }), null, 2);
+}
+function extractRouteParams(pattern, path) {
+  const keys = [];
+  const source = normalizePath(pattern);
+  let expression = "^";
+  for (let index = 0; index < source.length; index++) {
+    const char = source[index];
+    if (char === "{") {
+      const closeIndex = source.indexOf("}", index);
+      if (closeIndex > index) {
+        const key = source.slice(index + 1, closeIndex);
+        keys.push(key);
+        expression += "([^/]+)";
+        index = closeIndex;
+        continue;
+      }
+    }
+    expression += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  expression += "$";
+  const match = normalizePath(path).match(new RegExp(expression));
+  if (!match) return null;
+  const params = {};
+  for (let index = 0; index < keys.length; index++) {
+    const raw = match[index + 1];
+    if (raw) params[keys[index]] = decodeURIComponent(raw);
+  }
+  return params;
+}
+function extractSourceRouteParams(policy, resource, path) {
+  const resolvedPolicy = resolveRoutePolicy({ routes: policy });
+  const candidates = [
+    resolvedPolicy.sourceResources[resource],
+    resolvedPolicy.resources[resource],
+    DEFAULT_ROUTE_RESOURCES[resource]
+  ].filter((pattern) => Boolean(pattern));
+  for (const pattern of candidates) {
+    const params = extractRouteParams(pattern, path);
+    if (params) return params;
+  }
+  return null;
+}
+function mergeRouteParams(left, right) {
+  return {
+    ...left ?? {},
+    ...right ?? {}
+  };
+}
+
+export { DEFAULT_ROUTE_RESOURCES, buildRoutePath, buildRouteUrl, extractRouteParams, extractSourceRouteParams, formatRoutePolicy, hasCustomArticleRoute, isRoutePolicy, mergeRouteParams, resolveRoutePolicy };

package/dist/types.d.mts

@@ -1,3 +1,5 @@
+export { BuildRoutePathOptions, ResolvedRouteLocalePolicy, ResolvedRoutePolicy, RouteLocalePolicy, RouteParams, RoutePolicy, RoutePolicyConfig, RouteResourceDefaults, RouteResources } from './routes.mjs';
+
 /** 作者信息 (Go: delivery.DeliveryAuthorResponse) */
 interface Author {
     id: number;
@@ -6,6 +8,9 @@ interface Author {
     slug: string;
     avatar_url?: string;
     bio?: string;
+    seo_meta?: Partial<SeoMeta>;
+    og_meta?: Partial<OgMeta>;
+    twitter_meta?: Partial<TwitterMeta>;
     available_locales?: string[];
     localized_slugs?: Record<string, string>;
 }
@@ -129,12 +134,21 @@ interface TwitterMeta {
     image: string | null;
 }
 
+/** 本地化 SEO 元信息 */
+type LocalizedSeoMetaMap = Record<string, Partial<SeoMeta>>;
+/** 本地化 Open Graph 元信息 */
+type LocalizedOgMetaMap = Record<string, Partial<OgMeta>>;
+/** 本地化 Twitter Card 元信息 */
+type LocalizedTwitterMetaMap = Record<string, Partial<TwitterMeta>>;
 /** 分类树节点 (Go: delivery.CategoryNodeResponse) */
 interface CategoryNode {
     id: number;
     slug: string;
     name: LocalizedString;
     description: LocalizedString;
+    seo_meta?: LocalizedSeoMetaMap;
+    og_meta?: LocalizedOgMetaMap;
+    twitter_meta?: LocalizedTwitterMetaMap;
     article_count: number;
     article_counts?: Record<string, number>;
     children?: CategoryNode[];
@@ -165,6 +179,7 @@ interface RedirectRule {
     destination_path: string;
     status_code: number;
     match_type: string;
+    priority: number;
 }
 
 /** 文章系列 (Go: delivery.DeliverySeriesResponse) */
@@ -209,4 +224,4 @@ interface RevalidatePayload {
     category_slug?: string;
 }
 
-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 };
+export type { ArticleDetail, ArticleListItem, ArticleListParams, ArticleSearchParams, ArticleSearchResultItem, Author, CategoryNode, Comment, CreateCommentPayload, HreflangEntry, ListResponse, LocalizedOgMetaMap, LocalizedSeoMetaMap, LocalizedString, LocalizedTwitterMetaMap, OgMeta, Paginated, PaginationMeta, PaginationParams, RedirectRule, RevalidatePayload, SeoMeta, Series, SitemapEntry, SitemapImageEntry, TwitterMeta, WebhookEventType };

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+export { BuildRoutePathOptions, ResolvedRouteLocalePolicy, ResolvedRoutePolicy, RouteLocalePolicy, RouteParams, RoutePolicy, RoutePolicyConfig, RouteResourceDefaults, RouteResources } from './routes.js';
+
 /** 作者信息 (Go: delivery.DeliveryAuthorResponse) */
 interface Author {
     id: number;
@@ -6,6 +8,9 @@ interface Author {
     slug: string;
     avatar_url?: string;
     bio?: string;
+    seo_meta?: Partial<SeoMeta>;
+    og_meta?: Partial<OgMeta>;
+    twitter_meta?: Partial<TwitterMeta>;
     available_locales?: string[];
     localized_slugs?: Record<string, string>;
 }
@@ -129,12 +134,21 @@ interface TwitterMeta {
     image: string | null;
 }
 
+/** 本地化 SEO 元信息 */
+type LocalizedSeoMetaMap = Record<string, Partial<SeoMeta>>;
+/** 本地化 Open Graph 元信息 */
+type LocalizedOgMetaMap = Record<string, Partial<OgMeta>>;
+/** 本地化 Twitter Card 元信息 */
+type LocalizedTwitterMetaMap = Record<string, Partial<TwitterMeta>>;
 /** 分类树节点 (Go: delivery.CategoryNodeResponse) */
 interface CategoryNode {
     id: number;
     slug: string;
     name: LocalizedString;
     description: LocalizedString;
+    seo_meta?: LocalizedSeoMetaMap;
+    og_meta?: LocalizedOgMetaMap;
+    twitter_meta?: LocalizedTwitterMetaMap;
     article_count: number;
     article_counts?: Record<string, number>;
     children?: CategoryNode[];
@@ -165,6 +179,7 @@ interface RedirectRule {
     destination_path: string;
     status_code: number;
     match_type: string;
+    priority: number;
 }
 
 /** 文章系列 (Go: delivery.DeliverySeriesResponse) */
@@ -209,4 +224,4 @@ interface RevalidatePayload {
     category_slug?: string;
 }
 
-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 };
+export type { ArticleDetail, ArticleListItem, ArticleListParams, ArticleSearchParams, ArticleSearchResultItem, Author, CategoryNode, Comment, CreateCommentPayload, HreflangEntry, ListResponse, LocalizedOgMetaMap, LocalizedSeoMetaMap, LocalizedString, LocalizedTwitterMetaMap, OgMeta, Paginated, PaginationMeta, PaginationParams, RedirectRule, RevalidatePayload, SeoMeta, Series, SitemapEntry, SitemapImageEntry, TwitterMeta, WebhookEventType };

package/package.json

@@ -1,10 +1,26 @@
 {
   "name": "@vigilkids/cms-client",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Framework-agnostic TypeScript client for OnEx CMS Public API",
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "routes": [
+        "./dist/routes.d.ts"
+      ],
+      "types": [
+        "./dist/types.d.ts"
+      ],
+      "webhook": [
+        "./dist/webhook.d.ts"
+      ],
+      "*": [
+        "./dist/index.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,6 +30,10 @@
       "types": "./dist/types.d.ts",
       "import": "./dist/types.mjs"
     },
+    "./routes": {
+      "types": "./dist/routes.d.ts",
+      "import": "./dist/routes.mjs"
+    },
     "./webhook": {
       "types": "./dist/webhook.d.ts",
       "import": "./dist/webhook.mjs"