@ecomcx/ecomweb-theme-sdk 1.28.0 → 1.29.0

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { PostContentDoc, CommentPage, Menu, Post, ResolveResult, Site, Term, WidgetInstance } from "./types.js";
+import type { Author, PostContentDoc, CommentPage, Media, Menu, Post, ResolveResult, Site, Term, WidgetInstance } from "./types.js";
 /**
  * Client gọi Public API của CMS (dùng next-fetch-kit: chạy được cả SSR lẫn CSR,
  * tự gộp request trùng trong cùng một lần render, timeout + retry khi lỗi mạng).
@@ -86,10 +86,21 @@ export interface PostQuery {
     sticky?: boolean;
     /** Kèm nội dung đầy đủ (post.content). Mặc định không — danh sách chỉ cần tiêu đề, sapo, ảnh, giúp trang nhẹ và nhanh. */
     withContent?: boolean;
+    /**
+     * `relevance` = theo độ khớp với `search` (trang tìm kiếm dùng mặc định); `rand` = ngẫu nhiên (kết quả vẫn được
+     * cache, đổi khi cache hết hạn hoặc nội dung đổi).
+     */
     page?: number;
     perPage?: number;
-    orderBy?: "date" | "title" | "modified" | "menu_order" | "comment_count";
+    orderBy?: "date" | "title" | "modified" | "menu_order" | "comment_count" | "id" | "slug" | "rand" | "relevance";
     order?: "asc" | "desc";
+    /** Ngày đăng từ (gồm cả mốc), ISO-8601 hoặc Date — vd sự kiện / tin tức từ đầu năm học. */
+    after?: string | Date;
+    /** Ngày đăng trước (không gồm mốc). */
+    before?: string | Date;
+    /** Năm đăng (UTC); kèm `month` 1–12 để lấy một tháng — trang lưu trữ. */
+    year?: number;
+    month?: number;
     /**
      * Sắp xếp theo một khoá meta đã khai báo `filterable` (vd `"gia"`, `"job_deadline"`) — thay cho `orderBy`.
      * Khoá chưa khai báo trả 422 (không có chỉ mục thì sắp xếp phải quét toàn bảng).
@@ -102,6 +113,95 @@ export declare const getPosts: ({ withContent, ...q }?: PostQuery) => Promise<{
     page: number;
     totalPages: number;
 }>;
+/** Một trang của danh sách công khai (term, tác giả, media). */
+export interface ListPage<T> {
+    items: T[];
+    total: number;
+    page: number;
+    totalPages: number;
+}
+/** Một giá trị facet: slug term (facet phân loại) hoặc giá trị meta, kèm số bài. */
+export interface FacetValue {
+    value: string;
+    count: number;
+    termId?: number | null;
+    name?: string | null;
+    parentId?: number | null;
+}
+export interface FacetResult {
+    total: number;
+    facets: Record<string, FacetValue[]>;
+}
+/**
+ * Đếm số bài theo từng giá trị (bộ lọc có số đếm: "Khoa CNTT (12)") trên đúng tập bài mà {@link getPosts} trả về với
+ * cùng điều kiện. `facets`: tên phân loại công khai ("category") và/hoặc `"meta:khoá"` (khoá khai báo `filterable`).
+ * Tối đa 5 facet × 100 giá trị, đếm trong PostgreSQL.
+ * @example const { facets } = await getFacets(["khoa", "meta:hoc-ky"], { type: "khoa-hoc", taxQuery })
+ */
+export declare function getFacets(facets: string[], query?: Omit<PostQuery, "page" | "perPage" | "withContent" | "orderBy" | "order" | "orderByMeta">): Promise<FacetResult>;
+export interface TermQuery {
+    taxonomy: string;
+    locale?: string;
+    /** Tìm theo tên, không phân biệt dấu. */
+    search?: string;
+    /** Chỉ term con trực tiếp của term này; 0 = chỉ term gốc. */
+    parent?: number;
+    include?: number[];
+    exclude?: number[];
+    hideEmpty?: boolean;
+    /** Chỉ term có meta khoá này (và đúng giá trị nếu có metaValue). */
+    metaKey?: string;
+    metaValue?: string;
+    orderBy?: "name" | "slug" | "count" | "id";
+    order?: "asc" | "desc";
+    /** perPage 1–500 (mặc định 100). */
+    page?: number;
+    perPage?: number;
+    /** Tham số thêm cho plugin (filter terms.query đọc trong Query). */
+    params?: Record<string, string>;
+}
+/** Danh sách term có phân trang, lọc theo cha / từ khoá / meta, sắp xếp — bản đầy đủ của {@link getTerms}. */
+export declare const queryTerms: ({ params, ...q }: TermQuery) => Promise<ListPage<Term>>;
+export interface AuthorQuery {
+    locale?: string;
+    /** Tìm theo tên hiển thị, không phân biệt dấu. */
+    search?: string;
+    include?: number[];
+    exclude?: number[];
+    /** Lọc theo meta công khai (khoá khai báo `UserMeta` Public), vd metaKey "khoa". Khoá không công khai → 422. */
+    metaKey?: string;
+    metaValue?: string;
+    orderBy?: "name" | "post_count" | "id";
+    order?: "asc" | "desc";
+    /** perPage 1–100 (mặc định 20). */
+    page?: number;
+    perPage?: number;
+    /** Tham số thêm cho plugin (filter authors.query), vd plugin danh bạ thêm vai trò "giang-vien". */
+    params?: Record<string, string>;
+}
+/**
+ * Danh sách tác giả công khai (trang "Đội ngũ", danh bạ): mặc định thành viên có bài đã đăng; plugin mở rộng qua
+ * filter authors.query. Chỉ có tên, slug, ảnh, tiểu sử, meta công khai — không bao giờ có email.
+ */
+export declare const getAuthors: ({ params, ...q }?: AuthorQuery) => Promise<ListPage<Author>>;
+export interface MediaQuery {
+    /** Tìm theo tiêu đề, alt, chú thích, tên file — không phân biệt dấu. */
+    search?: string;
+    /** Tiền tố kiểu file: "image/", "video/", "application/pdf". */
+    mime?: string;
+    folder?: number;
+    include?: number[];
+    exclude?: number[];
+    orderBy?: "date" | "title" | "id" | "size";
+    order?: "asc" | "desc";
+    /** perPage 1–100 (mặc định 20). */
+    page?: number;
+    perPage?: number;
+    /** Tham số thêm cho plugin (filter media.query). */
+    params?: Record<string, string>;
+}
+/** Danh sách media (thư viện ảnh, tài liệu tải về) — plugin giới hạn / mở rộng qua filter media.query. */
+export declare const getMedia: ({ params, ...q }?: MediaQuery) => Promise<ListPage<Media>>;
 export declare const getPost: (type: string, slug: string, locale?: string) => Promise<Post | null>;
 export declare const getTerms: (taxonomy: string, hideEmpty?: boolean, locale?: string) => Promise<Term[]>;
 /** Cookie giữ token bản nháp của Trình dựng (website đang ở chế độ xem trước). */
@@ -117,8 +217,13 @@ export declare const getPattern: (id: number) => Promise<PostContentDoc | null>;
 export declare const getMenu: (location: string, locale?: string) => Promise<Menu | null>;
 export declare const getMenuById: (id: number) => Promise<Menu | null>;
 export declare const getWidgets: (area: string, locale?: string) => Promise<WidgetInstance[]>;
-/** Bình luận đã duyệt theo trang (số mỗi trang, thứ tự: Cài đặt › Thảo luận). */
-export declare const getComments: (postId: number, page?: number) => Promise<CommentPage>;
+/**
+ * Bình luận đã duyệt theo trang (số mỗi trang, thứ tự: Cài đặt › Thảo luận).
+ * Bài có mật khẩu (core >= 1.15): CMS chỉ trả bình luận khi có token mở khoá — unlock = giá trị cookie cms-unlock (không cache).
+ */
+export declare const getComments: (postId: number, page?: number, unlock?: string) => Promise<CommentPage>;
+/** Cookie mở khoá bài có mật khẩu của request hiện tại (server component); ngoài request → undefined. */
+export declare function requestUnlock(): Promise<string | undefined>;
 export declare const getArchives: (locale?: string) => Promise<{
     year: number;
     month: number;

package/dist/api.js

@@ -121,7 +121,7 @@ export const getPosts = async ({ withContent, ...q } = {}) => {
     // hợp đồng (api/theme-sdk.txt) nên thêm tên vào tham số là đổi một dòng đã ký (CI coi là phá hợp đồng).
     const { taxQuery, metaQuery, ...rest } = q;
     return cmsFetch("/posts", { tags: ["posts"], query: clean({
-            ...rest,
+            ...postQueryParams(rest),
             // Bộ lọc phức tạp đi dạng JSON — core phân tích và áp thẳng vào câu SQL (không lọc bằng bộ nhớ).
             taxQuery: taxQuery?.length ? JSON.stringify(taxQuery) : undefined,
             metaQuery: metaQuery?.clauses?.length ? JSON.stringify(metaQuery) : undefined,
@@ -130,6 +130,36 @@ export const getPosts = async ({ withContent, ...q } = {}) => {
         }) });
 };
 const loc = async (locale) => locale ?? (await getRequestLocale());
+/** Tham số đơn giản của PostQuery → query string (Date → ISO). */
+function postQueryParams(q) {
+    const iso = (d) => (d instanceof Date ? d.toISOString() : d);
+    return { ...q, after: iso(q.after), before: iso(q.before) };
+}
+/**
+ * Đếm số bài theo từng giá trị (bộ lọc có số đếm: "Khoa CNTT (12)") trên đúng tập bài mà {@link getPosts} trả về với
+ * cùng điều kiện. `facets`: tên phân loại công khai ("category") và/hoặc `"meta:khoá"` (khoá khai báo `filterable`).
+ * Tối đa 5 facet × 100 giá trị, đếm trong PostgreSQL.
+ * @example const { facets } = await getFacets(["khoa", "meta:hoc-ky"], { type: "khoa-hoc", taxQuery })
+ */
+export async function getFacets(facets, query = {}) {
+    const { taxQuery, metaQuery, ...rest } = query;
+    return cmsFetch("/posts/facets", { tags: ["posts"], query: clean({
+            ...postQueryParams(rest),
+            facets: facets.join(","),
+            taxQuery: taxQuery?.length ? JSON.stringify(taxQuery) : undefined,
+            metaQuery: metaQuery?.clauses?.length ? JSON.stringify(metaQuery) : undefined,
+            locale: rest.locale ?? (await getRequestLocale()),
+        }) });
+}
+/** Danh sách term có phân trang, lọc theo cha / từ khoá / meta, sắp xếp — bản đầy đủ của {@link getTerms}. */
+export const queryTerms = async ({ params, ...q }) => cmsFetch("/terms", { tags: ["terms"], query: clean({ ...params, ...q, locale: await loc(q.locale) }) });
+/**
+ * Danh sách tác giả công khai (trang "Đội ngũ", danh bạ): mặc định thành viên có bài đã đăng; plugin mở rộng qua
+ * filter authors.query. Chỉ có tên, slug, ảnh, tiểu sử, meta công khai — không bao giờ có email.
+ */
+export const getAuthors = async ({ params, ...q } = {}) => cmsFetch("/authors", { tags: ["authors"], query: clean({ ...params, ...q, locale: await loc(q.locale) }) });
+/** Danh sách media (thư viện ảnh, tài liệu tải về) — plugin giới hạn / mở rộng qua filter media.query. */
+export const getMedia = async ({ params, ...q } = {}) => cmsFetch("/media", { tags: ["media"], query: clean({ ...params, ...q }) });
 export const getPost = async (type, slug, locale) => cmsFetch(`/posts/${type}/${encodeURIComponent(slug)}`, { tags: ["posts"], query: clean({ locale: await loc(locale) }) }).catch(() => null);
 export const getTerms = async (taxonomy, hideEmpty = true, locale) => cmsFetch(`/terms/${taxonomy}`, { tags: ["terms"], query: clean({ hideEmpty, locale: await loc(locale) }) });
 /** Cookie giữ token bản nháp của Trình dựng (website đang ở chế độ xem trước). */
@@ -155,7 +185,22 @@ export const getPattern = (id) => cmsFetch(`/patterns/${id}`, { tags: ["patterns
 export const getMenu = async (location, locale) => cmsFetch(`/menus/${location}`, { tags: ["menus"], query: clean({ locale: await loc(locale) }) });
 export const getMenuById = (id) => cmsFetch(`/menus/id/${id}`, { tags: ["menus"] });
 export const getWidgets = async (area, locale) => cmsFetch(`/widgets/${area}`, { tags: ["widgets"], query: clean({ locale: await loc(locale) }) });
-/** Bình luận đã duyệt theo trang (số mỗi trang, thứ tự: Cài đặt › Thảo luận). */
-export const getComments = (postId, page = 1) => cmsFetch(`/comments/${postId}`, { tags: [`comments:${postId}`], query: page > 1 ? { page } : undefined });
+/**
+ * Bình luận đã duyệt theo trang (số mỗi trang, thứ tự: Cài đặt › Thảo luận).
+ * Bài có mật khẩu (core >= 1.15): CMS chỉ trả bình luận khi có token mở khoá — unlock = giá trị cookie cms-unlock (không cache).
+ */
+export const getComments = (postId, page = 1, unlock) => cmsFetch(`/comments/${postId}`, {
+    tags: [`comments:${postId}`], noStore: !!unlock, query: page > 1 ? { page } : undefined, headers: unlock ? { [UNLOCK_HEADER]: unlock } : undefined,
+});
+/** Cookie mở khoá bài có mật khẩu của request hiện tại (server component); ngoài request → undefined. */
+export async function requestUnlock() {
+    try {
+        const { cookies } = await import("next/headers");
+        return (await cookies()).get(UNLOCK_COOKIE)?.value;
+    }
+    catch {
+        return undefined;
+    }
+}
 export const getArchives = async (locale) => cmsFetch("/archives", { tags: ["posts"], query: clean({ locale: await loc(locale) }) });
 export const getLanguages = () => cmsFetch("/languages", { tags: ["site"] });

package/dist/components.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { getArchives, getComments, getMenu, getMenuById, getPosts, getSite, getTerms, getWidgets } from "./api.js";
+import { getArchives, getComments, getMenu, getMenuById, getPosts, getSite, getTerms, getWidgets, requestUnlock } from "./api.js";
 import { findWidget, getSlotItems } from "./runtime.js";
 import { cx, formatDate, pageLink, pageLinkWithQuery } from "./utils.js";
 import { Img } from "./image.js";
@@ -134,7 +134,8 @@ export async function Comments({ post, title }) {
         return null;
     if (post.passwordProtected && !post.content)
         return null; // bài có mật khẩu: ẩn bình luận tới khi mở khoá
-    const [site, page, t] = await Promise.all([getSite(), getComments(post.id), getT()]);
+    const unlock = post.passwordProtected ? await requestUnlock() : undefined;
+    const [site, page, t] = await Promise.all([getSite(), getComments(post.id, 1, unlock), getT()]);
     const comments = page?.items ?? [];
     const dateSite = { dateFormat: site.dateFormat, timezone: site.timezone, locale: site.locale };
     title ??= t("comments.title");

package/dist/types.d.ts

@@ -11,6 +11,12 @@ export interface Author {
     slug: string;
     avatarUrl?: string | null;
     bio?: string | null;
+    /** Meta công khai của thành viên (plugin khai báo `UserMeta` Public), vd `{ khoa: "cntt" }`. */
+    meta?: JsonObject;
+    /** Số bài đã đăng — chỉ có trong danh sách {@link getAuthors}. */
+    postCount?: number | null;
+    /** Dữ liệu plugin thêm qua filter api.author.response. */
+    extra?: JsonObject;
 }
 export interface MediaSize {
     url: string;
@@ -34,6 +40,8 @@ export interface Media {
     /** Điểm lấy nét 0–1 (object-position). */
     focalX?: number | null;
     focalY?: number | null;
+    title?: string;
+    createdAt?: string;
 }
 export interface Term {
     id: number;
@@ -285,6 +293,20 @@ export interface ThemeManifest {
     }>;
     /** Nguồn ngoài website theme cần nạp (CSP): { "style-src": ["https://fonts.googleapis.com"], "font-src": ["https://fonts.gstatic.com"] }. */
     csp?: Partial<Record<"script-src" | "style-src" | "img-src" | "font-src" | "connect-src" | "frame-src" | "media-src" | "worker-src" | "form-action", string[]>>;
+    /**
+     * Kiểu nội dung của theme (CMS ≥ 1.15, như plugin.json — giống functions.php của WordPress):
+     * { "su-kien": { "label": "Sự kiện", "rewriteSlug": "su-kien", "taxonomies": ["khoa"] } }.
+     * Đăng ký khi theme (hoặc theme con) đang dùng; không đè kiểu của core/plugin.
+     */
+    postTypes?: Record<string, Record<string, JsonValue>>;
+    /** Phân loại của theme: { "khoa": { "label": "Khoa", "hierarchical": true, "postTypes": ["su-kien"] } }. */
+    taxonomies?: Record<string, Record<string, JsonValue>>;
+    /** Meta bài của theme: { "ngay-bat-dau": { "filterable": true, "indexType": "date" } } — lọc/sắp xếp/facet được. */
+    postMeta?: Record<string, Record<string, JsonValue>>;
+    /** Meta thành viên: { "hoc-vi": { "public": true } } — hiện trong hồ sơ tác giả (Author.meta). */
+    userMeta?: Record<string, {
+        public?: boolean;
+    }>;
     [key: string]: unknown;
 }
 type Loader<T> = () => Promise<{
@@ -435,6 +457,14 @@ export interface FilterMap {
     "sitemap.entries": (entries: SitemapEntry[], ctx: {
         site: Site;
     }) => SitemapEntry[] | Promise<SitemapEntry[]>;
+    /**
+     * Đổi thứ tự / thêm tên template trước khi theme chọn (core ≥ 1.15) — vd plugin "Sự kiện" thêm "plugin-su-kien" lên đầu
+     * cho kiểu nội dung của nó và khai báo template đó trong `definePlugin({ templates })`. Theme có template trùng tên vẫn thắng.
+     */
+    "template.hierarchy": (templates: string[], ctx: {
+        site: Site;
+        data: ResolveResult;
+    }) => string[] | Promise<string[]>;
     /** Thêm/bớt class của thẻ <body> (vd "logged-in", "has-promo-bar") */
     "body.class": (classes: string[], ctx: {
         site: Site;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecomcx/ecomweb-theme-sdk",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "SDK để viết theme và phần frontend của plugin cho Ecomweb",
   "type": "module",
   "main": "./dist/index.js",