@hodela/site 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,7 @@
+# @hodela/site
+
+Mã chạy chung của website Hodela, để starter không phải chép vào từng website (cập nhật bằng cách nâng phiên bản gói).
+
+Subpath: `access` (PIN, danh sách IP, chặn bot, badge), `analytics`, `sql-split` (bộ tách câu lệnh migration, nền tảng cũng dùng), `admin-token`, `session-cookie`, `customer-auth`, `mailer`, `seo`.
+
+Quy ước: thay đổi phải tương thích ngược (mọi website dùng chung một bản trong image build). Test nằm cạnh mã (`pnpm --filter @hodela/site test`). Lộ trình chuyển nốt phần còn lại của starter: `docs/development.md`.

package/dist/admin.functions.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export declare const adminStatus: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, Promise<{
+    configured: boolean;
+    authed: boolean;
+}>>;
+export declare const adminLogin: import("@tanstack/react-start").RequiredFetcher<undefined, z.ZodObject<{
+    password: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    password: string;
+}, {
+    password: string;
+}>, Promise<{
+    ok: boolean;
+    reason?: "not_configured" | "locked" | "wrong";
+}>>;
+export declare const adminLogout: import("@tanstack/react-start").OptionalFetcher<undefined, undefined, Promise<{
+    ok: true;
+}>>;

package/dist/admin.functions.js

@@ -0,0 +1,17 @@
+// Server function cho khu vực quản lý (dùng bởi <AdminGate>/useAdminSession). Hodela quản lý file này: không sửa.
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
+import { adminConfigured, isAdmin, loginAdmin } from "./server/admin.js";
+export const adminStatus = createServerFn({ method: "GET" }).handler(async () => {
+    return { configured: adminConfigured(), authed: await isAdmin() };
+});
+export const adminLogin = createServerFn({ method: "POST" })
+    .validator(z.object({ password: z.string().min(1).max(200) }))
+    .handler(async ({ data }) => {
+    return loginAdmin(data.password);
+});
+export const adminLogout = createServerFn({ method: "POST" }).handler(async () => {
+    const { logoutAdmin } = await import("./server/admin.js");
+    logoutAdmin();
+    return { ok: true };
+});

package/dist/customer-auth.js

@@ -1,5 +1,5 @@
 // Tài khoản của KHÁCH HÀNG cuối (khác khu vực quản lý của chủ web): băm mật khẩu và mã phiên. Thuần, kiểm thử được.
-// Hodela quản lý file này: không sửa. Dùng qua "@/lib/customer-auth.server".
+// Dùng qua "@hodela/site/server/customer-auth".
 const enc = new TextEncoder();
 // Cloudflare Workers giới hạn PBKDF2 tối đa 100.000 vòng.
 const ITERATIONS = 100_000;

package/dist/email-client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Gửi email từ website Hodela qua API nền tảng. Nền tảng giữ khóa nhà cung cấp mail, kiểm quyền và
+ * giới hạn tần suất theo website; mã website chỉ cần `HODELA_API_URL` + `HODELA_API_KEY` (do Hodela cấp).
+ */
+export type SendEmailInput = {
+    /** Một hoặc tối đa 5 người nhận. */
+    to: string | string[];
+    subject: string;
+    /** Cần ít nhất một trong `text` hoặc `html`. */
+    text?: string | undefined;
+    html?: string | undefined;
+    /** Người nhận bấm "Trả lời" sẽ gửi về địa chỉ này (ví dụ email khách trong form liên hệ). */
+    replyTo?: string | undefined;
+    /** Gửi lại cùng khóa trong 24 giờ không tạo thêm thư (an toàn khi thử lại). */
+    idempotencyKey?: string | undefined;
+};
+/** `suppressed`: mọi người nhận đã từng trả thư về hoặc báo spam nên không gửi. */
+export type SendEmailResult = {
+    id: string;
+    status: "sent" | "duplicate" | "suppressed";
+};
+export type EmailLogEntry = {
+    recipient: string;
+    subject: string;
+    status: "pending" | "sent" | "failed" | "bounced" | "complained" | (string & {});
+    error: string | null;
+    createdAt: string;
+};
+export type EmailErrorCode = "not_configured" | "unauthorized" | "disabled" | "invalid_request" | "rate_limited" | "unavailable" | "network";
+export declare class HodelaEmailError extends Error {
+    readonly code: EmailErrorCode;
+    readonly status: number | null;
+    /** Số giây nên chờ trước khi thử lại (khi `code` là rate_limited). */
+    readonly retryAfterSec: number | null;
+    constructor(code: EmailErrorCode, message: string, opts?: {
+        status?: number | undefined;
+        retryAfterSec?: number | undefined;
+    });
+}
+export type HodelaEmailClientOptions = {
+    apiUrl: string | undefined;
+    apiKey: string | undefined;
+    /** Mặc định `fetch` toàn cục. */
+    fetch?: typeof fetch | undefined;
+    timeoutMs?: number | undefined;
+};
+export declare function validateSendInput(input: SendEmailInput): string | null;
+export declare function createHodelaEmailClient(options: HodelaEmailClientOptions): {
+    /** Thư gần đây của website (mới nhất trước, tối đa 100): người nhận, tiêu đề, trạng thái; không có nội dung thư. */
+    logs(limit?: number): Promise<EmailLogEntry[]>;
+    /** Ném `HodelaEmailError` khi thất bại; mã gọi nên bắt lỗi để không làm hỏng việc chính (lưu form/đơn hàng). */
+    send(input: SendEmailInput): Promise<SendEmailResult>;
+};
+/** Gửi một thư với cấu hình lấy từ env của website. */
+export declare function sendEmail(input: SendEmailInput, options: HodelaEmailClientOptions): Promise<SendEmailResult>;

package/dist/email-client.js

@@ -0,0 +1,108 @@
+/**
+ * Gửi email từ website Hodela qua API nền tảng. Nền tảng giữ khóa nhà cung cấp mail, kiểm quyền và
+ * giới hạn tần suất theo website; mã website chỉ cần `HODELA_API_URL` + `HODELA_API_KEY` (do Hodela cấp).
+ */
+export class HodelaEmailError extends Error {
+    code;
+    status;
+    /** Số giây nên chờ trước khi thử lại (khi `code` là rate_limited). */
+    retryAfterSec;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = "HodelaEmailError";
+        this.code = code;
+        this.status = opts.status ?? null;
+        this.retryAfterSec = opts.retryAfterSec ?? null;
+    }
+}
+const MAX_RECIPIENTS = 5;
+const EMAIL_RE = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
+export function validateSendInput(input) {
+    const to = Array.isArray(input.to) ? input.to : [input.to];
+    if (to.length === 0 || to.length > MAX_RECIPIENTS)
+        return `Cần từ 1 đến ${MAX_RECIPIENTS} người nhận.`;
+    if (to.some((a) => typeof a !== "string" || !EMAIL_RE.test(a.trim()) || a.length > 254))
+        return "Địa chỉ người nhận không hợp lệ.";
+    if (input.replyTo !== undefined && !EMAIL_RE.test(input.replyTo.trim()))
+        return "replyTo không hợp lệ.";
+    if (!input.subject.trim() || /[\r\n]/.test(input.subject) || input.subject.length > 200)
+        return "Tiêu đề trống, quá dài hoặc có xuống dòng.";
+    if (!input.text?.trim() && !input.html?.trim())
+        return "Cần nội dung text hoặc html.";
+    if ((input.text?.length ?? 0) > 100_000 || (input.html?.length ?? 0) > 200_000)
+        return "Nội dung quá dài.";
+    return null;
+}
+export function createHodelaEmailClient(options) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    function classify(res, body) {
+        const message = body?.error?.message ?? `API Hodela trả về HTTP ${res.status}.`;
+        if (res.status === 401)
+            return new HodelaEmailError("unauthorized", message, { status: 401 });
+        if (res.status === 403)
+            return new HodelaEmailError("disabled", message, { status: 403 });
+        if (res.status === 400 || res.status === 422)
+            return new HodelaEmailError("invalid_request", message, { status: res.status });
+        if (res.status === 429) {
+            const retry = Number(res.headers.get("retry-after"));
+            return new HodelaEmailError("rate_limited", message, { status: 429, retryAfterSec: Number.isFinite(retry) && retry > 0 ? retry : undefined });
+        }
+        return new HodelaEmailError("unavailable", message, { status: res.status });
+    }
+    return {
+        /** Thư gần đây của website (mới nhất trước, tối đa 100): người nhận, tiêu đề, trạng thái; không có nội dung thư. */
+        async logs(limit = 20) {
+            if (!options.apiUrl || !options.apiKey)
+                throw new HodelaEmailError("not_configured", "Website chưa được cấp HODELA_API_URL / HODELA_API_KEY.");
+            let res;
+            try {
+                res = await doFetch(`${options.apiUrl.replace(/\/+$/, "")}/v1/email/logs?limit=${encodeURIComponent(String(limit))}`, {
+                    headers: { authorization: `Bearer ${options.apiKey}` },
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (e) {
+                throw new HodelaEmailError("network", e instanceof Error ? e.message : "Không gọi được API Hodela.");
+            }
+            const body = (await res.json().catch(() => null));
+            if (res.ok && Array.isArray(body?.data))
+                return body.data;
+            throw classify(res, body);
+        },
+        /** Ném `HodelaEmailError` khi thất bại; mã gọi nên bắt lỗi để không làm hỏng việc chính (lưu form/đơn hàng). */
+        async send(input) {
+            if (!options.apiUrl || !options.apiKey) {
+                throw new HodelaEmailError("not_configured", "Website chưa được cấp HODELA_API_URL / HODELA_API_KEY.");
+            }
+            const invalid = validateSendInput(input);
+            if (invalid)
+                throw new HodelaEmailError("invalid_request", invalid);
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            let res;
+            try {
+                res = await doFetch(`${options.apiUrl.replace(/\/+$/, "")}/v1/email/send`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json", authorization: `Bearer ${options.apiKey}` },
+                    body: JSON.stringify({ ...input, to: Array.isArray(input.to) ? input.to : [input.to] }),
+                    signal: controller.signal,
+                });
+            }
+            catch (e) {
+                throw new HodelaEmailError("network", e instanceof Error ? e.message : "Không gọi được API Hodela.");
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            const body = (await res.json().catch(() => null));
+            if (res.ok && body?.id)
+                return { id: body.id, status: body.status === "duplicate" ? "duplicate" : body.status === "suppressed" ? "suppressed" : "sent" };
+            throw classify(res, body);
+        },
+    };
+}
+/** Gửi một thư với cấu hình lấy từ env của website. */
+export async function sendEmail(input, options) {
+    return createHodelaEmailClient(options).send(input);
+}

package/dist/error-page.d.ts

@@ -0,0 +1 @@
+export declare function renderErrorPage(): string;

package/dist/error-page.js

@@ -0,0 +1,30 @@
+export function renderErrorPage() {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>This page didn't load</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      body { font: 15px/1.5 system-ui, -apple-system, sans-serif; background: #fafafa; color: #111; display: grid; place-items: center; min-height: 100vh; margin: 0; padding: 1.5rem; }
+      .card { max-width: 28rem; width: 100%; text-align: center; padding: 2rem; }
+      h1 { font-size: 1.25rem; margin: 0 0 0.5rem; }
+      p { color: #4b5563; margin: 0 0 1.5rem; }
+      .actions { display: flex; gap: 0.5rem; justify-content: center; flex-wrap: wrap; }
+      a, button { padding: 0.5rem 1rem; border-radius: 0.375rem; font: inherit; cursor: pointer; text-decoration: none; border: 1px solid transparent; }
+      .primary { background: #111; color: #fff; }
+      .secondary { background: #fff; color: #111; border-color: #d1d5db; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>This page didn't load</h1>
+      <p>Something went wrong on our end. You can try refreshing or head back home.</p>
+      <div class="actions">
+        <button class="primary" onclick="location.reload()">Try again</button>
+        <a class="secondary" href="/">Go home</a>
+      </div>
+    </div>
+  </body>
+</html>`;
+}

package/dist/file-client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Lưu và phục vụ file của website Hodela qua API nền tảng. Nền tảng lo nơi lưu (R2), hạn mức dung lượng theo gói, kiểm tra loại file
+ * bằng nội dung và an toàn khi phục vụ; mã website chỉ cần `HODELA_API_URL` + `HODELA_API_KEY` (do Hodela cấp). Chỉ dùng ở server
+ * (server function, server route): khóa API không bao giờ được đưa xuống trình duyệt.
+ */
+export type FileVisibility = "public" | "private";
+export type HodelaFile = {
+    id: string;
+    name: string;
+    contentType: string;
+    /** Số byte. */
+    size: number;
+    visibility: FileVisibility;
+    createdAt: string;
+    /** Đường dẫn công khai trên chính tên miền của website (ví dụ `/_files/<sha256>/anh.png`), dùng thẳng trong `<img src>`. `null` với file riêng tư. */
+    url: string | null;
+};
+export type PutFileResult = HodelaFile & {
+    /** Nội dung đã có sẵn trong website nên không tốn thêm dung lượng. */
+    deduplicated: boolean;
+    /** SVG đã bị loại phần không an toàn. */
+    sanitized: boolean;
+};
+export type FileUsage = {
+    usedBytes: number;
+    files: number;
+    maxBytes: number;
+    maxFiles: number;
+    maxFileBytes: number;
+};
+export type SignedUrl = {
+    url: string;
+    expiresAt: string;
+};
+export type FileErrorCode = "not_configured" | "unauthorized" | "disabled" | "invalid_request" | "file_too_large" | "quota_exceeded" | "quota_files" | "unsupported_type" | "unsafe_file" | "not_found" | "rate_limited" | "unavailable" | "network";
+export declare class HodelaFileError extends Error {
+    readonly code: FileErrorCode;
+    readonly status: number | null;
+    /** Số giây nên chờ trước khi thử lại (khi `code` là rate_limited). */
+    readonly retryAfterSec: number | null;
+    constructor(code: FileErrorCode, message: string, opts?: {
+        status?: number;
+        retryAfterSec?: number;
+    });
+}
+export type HodelaFileClientOptions = {
+    apiUrl: string | undefined;
+    apiKey: string | undefined;
+    /** Mặc định `fetch` toàn cục. */
+    fetch?: typeof fetch | undefined;
+    /** Mặc định 10 giây cho thao tác thường, 60 giây cho tải lên. */
+    timeoutMs?: number | undefined;
+};
+export type PutFileOptions = {
+    /** Tên file (bắt buộc với dữ liệu không phải `File`). */
+    name?: string | undefined;
+    /** Mặc định `public`. File riêng tư chỉ tải được qua `signedUrl`. */
+    visibility?: FileVisibility | undefined;
+};
+export type FileBody = Blob | ArrayBuffer | Uint8Array;
+export declare function createHodelaFileClient(options: HodelaFileClientOptions): {
+    /**
+     * Lưu một file. Nhận `File`/`Blob` (lấy tên từ `File.name`), `ArrayBuffer` hoặc `Uint8Array` (cần `name`).
+     * Ném `HodelaFileError` (`file_too_large`, `quota_exceeded`, `unsupported_type`, `unsafe_file`...) để hiện thông báo cho người dùng.
+     */
+    put(body: FileBody, opts?: PutFileOptions): Promise<PutFileResult>;
+    get: (id: string) => Promise<HodelaFile>;
+    /** Mới nhất trước. Trang kế tiếp: truyền `nextBefore` của kết quả trước vào `before`. */
+    list: (opts?: {
+        limit?: number;
+        before?: string;
+    }) => Promise<{
+        data: HodelaFile[];
+        nextBefore: string | null;
+    }>;
+    /** Dung lượng đã dùng và hạn mức theo gói của chủ website. */
+    usage: () => Promise<FileUsage>;
+    /** URL tải file riêng tư, hết hạn sau `ttlSec` (mặc định 5 phút, tối đa 24 giờ). Chỉ đưa cho người được phép xem. */
+    signedUrl: (id: string, opts?: {
+        ttlSec?: number;
+    }) => Promise<SignedUrl>;
+    delete(id: string): Promise<void>;
+};
+/** Lưu một file với cấu hình lấy từ env của website. */
+export declare function putFile(body: FileBody, opts: PutFileOptions, client: HodelaFileClientOptions): Promise<PutFileResult>;
+/** Câu thông báo thân thiện cho người dùng cuối theo mã lỗi (có thể thay bằng câu của bạn). */
+export declare function describeFileError(error: unknown): string;

package/dist/file-client.js

@@ -0,0 +1,117 @@
+/**
+ * Lưu và phục vụ file của website Hodela qua API nền tảng. Nền tảng lo nơi lưu (R2), hạn mức dung lượng theo gói, kiểm tra loại file
+ * bằng nội dung và an toàn khi phục vụ; mã website chỉ cần `HODELA_API_URL` + `HODELA_API_KEY` (do Hodela cấp). Chỉ dùng ở server
+ * (server function, server route): khóa API không bao giờ được đưa xuống trình duyệt.
+ */
+export class HodelaFileError extends Error {
+    code;
+    status;
+    /** Số giây nên chờ trước khi thử lại (khi `code` là rate_limited). */
+    retryAfterSec;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = "HodelaFileError";
+        this.code = code;
+        this.status = opts.status ?? null;
+        this.retryAfterSec = opts.retryAfterSec ?? null;
+    }
+}
+const KNOWN_CODES = new Set(["invalid_request", "file_too_large", "quota_exceeded", "quota_files", "unsupported_type", "unsafe_file", "not_found", "rate_limited", "disabled", "unauthorized"]);
+export function createHodelaFileClient(options) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const base = () => {
+        if (!options.apiUrl || !options.apiKey)
+            throw new HodelaFileError("not_configured", "Website chưa được cấp HODELA_API_URL / HODELA_API_KEY.");
+        return options.apiUrl.replace(/\/+$/, "");
+    };
+    function classify(res, body) {
+        const message = body?.error?.message ?? `API Hodela trả về HTTP ${res.status}.`;
+        const code = body?.error?.code;
+        if (code && KNOWN_CODES.has(code)) {
+            const retry = Number(res.headers.get("retry-after"));
+            return new HodelaFileError(code, message, { status: res.status, ...(Number.isFinite(retry) && retry > 0 ? { retryAfterSec: retry } : {}) });
+        }
+        if (res.status === 401)
+            return new HodelaFileError("unauthorized", message, { status: 401 });
+        if (res.status === 403)
+            return new HodelaFileError("disabled", message, { status: 403 });
+        if (res.status === 404)
+            return new HodelaFileError("not_found", message, { status: 404 });
+        if (res.status === 413)
+            return new HodelaFileError("file_too_large", message, { status: 413 });
+        if (res.status === 415)
+            return new HodelaFileError("unsupported_type", message, { status: 415 });
+        if (res.status === 400 || res.status === 422)
+            return new HodelaFileError("invalid_request", message, { status: res.status });
+        if (res.status === 429) {
+            const retry = Number(res.headers.get("retry-after"));
+            return new HodelaFileError("rate_limited", message, { status: 429, ...(Number.isFinite(retry) && retry > 0 ? { retryAfterSec: retry } : {}) });
+        }
+        return new HodelaFileError("unavailable", message, { status: res.status });
+    }
+    async function request(path, init = {}) {
+        const root = base();
+        const { timeoutMs, ...rest } = init;
+        let res;
+        try {
+            res = await doFetch(`${root}${path}`, {
+                ...rest,
+                headers: { authorization: `Bearer ${options.apiKey}`, ...rest.headers },
+                signal: AbortSignal.timeout(timeoutMs ?? options.timeoutMs ?? 10_000),
+            });
+        }
+        catch (e) {
+            throw new HodelaFileError("network", e instanceof Error ? e.message : "Không gọi được API Hodela.");
+        }
+        const body = (await res.json().catch(() => null));
+        if (res.ok && body)
+            return body;
+        throw classify(res, body);
+    }
+    return {
+        /**
+         * Lưu một file. Nhận `File`/`Blob` (lấy tên từ `File.name`), `ArrayBuffer` hoặc `Uint8Array` (cần `name`).
+         * Ném `HodelaFileError` (`file_too_large`, `quota_exceeded`, `unsupported_type`, `unsafe_file`...) để hiện thông báo cho người dùng.
+         */
+        async put(body, opts = {}) {
+            const name = opts.name ?? (typeof File !== "undefined" && body instanceof File ? body.name : undefined);
+            if (!name?.trim())
+                throw new HodelaFileError("invalid_request", "Thiếu tên file.");
+            const payload = body instanceof Uint8Array ? body : body instanceof ArrayBuffer ? new Uint8Array(body) : body;
+            return request("/v1/files", {
+                method: "POST",
+                headers: { "x-file-name": encodeURIComponent(name), "x-file-visibility": opts.visibility ?? "public", "content-type": "application/octet-stream" },
+                body: payload,
+                timeoutMs: options.timeoutMs ?? 60_000,
+            });
+        },
+        get: (id) => request(`/v1/files/${encodeURIComponent(id)}`),
+        /** Mới nhất trước. Trang kế tiếp: truyền `nextBefore` của kết quả trước vào `before`. */
+        list: (opts = {}) => request(`/v1/files?limit=${encodeURIComponent(String(opts.limit ?? 50))}${opts.before ? `&before=${encodeURIComponent(opts.before)}` : ""}`),
+        /** Dung lượng đã dùng và hạn mức theo gói của chủ website. */
+        usage: () => request("/v1/files/usage"),
+        /** URL tải file riêng tư, hết hạn sau `ttlSec` (mặc định 5 phút, tối đa 24 giờ). Chỉ đưa cho người được phép xem. */
+        signedUrl: (id, opts = {}) => request(`/v1/files/${encodeURIComponent(id)}/signed-url`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ttlSec: opts.ttlSec }) }),
+        async delete(id) {
+            await request(`/v1/files/${encodeURIComponent(id)}`, { method: "DELETE" });
+        },
+    };
+}
+/** Lưu một file với cấu hình lấy từ env của website. */
+export function putFile(body, opts, client) {
+    return createHodelaFileClient(client).put(body, opts);
+}
+/** Câu thông báo thân thiện cho người dùng cuối theo mã lỗi (có thể thay bằng câu của bạn). */
+export function describeFileError(error) {
+    if (!(error instanceof HodelaFileError))
+        return "Không tải được file, thử lại sau.";
+    switch (error.code) {
+        case "file_too_large": return "File quá lớn.";
+        case "quota_exceeded": return "Đã hết dung lượng lưu trữ.";
+        case "quota_files": return "Đã đạt số file tối đa.";
+        case "unsupported_type": return "Loại file này chưa được hỗ trợ (ảnh, SVG, PDF, .txt, .csv).";
+        case "unsafe_file": return "File chứa nội dung không an toàn.";
+        case "rate_limited": return "Thao tác quá nhanh, thử lại sau ít phút.";
+        default: return "Không tải được file, thử lại sau.";
+    }
+}

package/dist/mailer.d.ts

@@ -1,4 +1,4 @@
-import { type EmailLogEntry } from "@hodela/email-js";
+import { type EmailLogEntry } from "./email-client.js";
 export type MailProvider = "hodela" | "resend" | "none";
 export type MailInput = {
     to: string | string[];

package/dist/mailer.js

@@ -1,12 +1,12 @@
 // Gửi email thông báo (form liên hệ, đơn hàng, lịch hẹn...). Thuần (nhận env vào) nên kiểm thử được.
-// Hodela quản lý file này: không sửa. Dùng qua "@/lib/mailer.server".
+// Dùng qua "@hodela/site/server/mailer".
 //
 // Cách gửi do chủ web chọn, suy ra từ biến môi trường (agent chỉ hỏi chủ web rồi xin đúng các biến này):
 //   • Gửi bằng Hodela     : đặt NOTIFY_EMAIL (hộp thư nhận thông báo). Hodela cấp sẵn HODELA_API_URL/HODELA_API_KEY.
 //   • Gửi bằng Resend riêng: đặt RESEND_API_KEY + MAIL_FROM (+ NOTIFY_EMAIL). Thư đi bằng tên miền của chủ web.
 //   • Không gửi email      : không đặt gì. Dữ liệu vẫn LUÔN được lưu vào database; chủ web xem ở khu vực quản lý.
 // Việc gửi thư không bao giờ ném lỗi và không bao giờ được chặn việc lưu dữ liệu.
-import { createHodelaEmailClient, HodelaEmailError } from "@hodela/email-js";
+import { createHodelaEmailClient, HodelaEmailError } from "./email-client.js";
 export function mailProvider(env) {
     if (env("RESEND_API_KEY") && env("MAIL_FROM"))
         return "resend";

package/dist/react/admin-gate.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+export type AdminLoginResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "wrong" | "locked";
+};
+export type AdminSession = {
+    /** `loading`: đang hỏi server; `signedOut`: chưa đăng nhập; `signedIn`: đã đăng nhập. */
+    state: "loading" | "signedOut" | "signedIn";
+    /** `false` khi chủ website chưa đặt biến ADMIN_PASSWORD: khu vực quản lý bị khóa, chưa ai đăng nhập được. */
+    configured: boolean;
+    /** Đang gửi yêu cầu đăng nhập hoặc đăng xuất. */
+    busy: boolean;
+    /** `wrong`: sai mật khẩu; `locked`: thử sai quá nhiều lần, chờ ít phút. */
+    login: (password: string) => Promise<AdminLoginResult>;
+    logout: () => Promise<void>;
+};
+/** Phiên quản trị hiện tại. Chỉ dùng bên trong <AdminGate> (cả trong `fallback` và `children`). */
+export declare function useAdminSession(): AdminSession;
+export declare function AdminGate({ children, fallback, loading }: {
+    children: ReactNode;
+    fallback: (session: AdminSession) => ReactNode;
+    loading?: ReactNode;
+}): import("react").JSX.Element;

package/dist/react/admin-gate.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Cổng đăng nhập cho khu vực quản lý của chủ website. Hodela quản lý file này: không sửa.
+//
+// File này chỉ giữ LOGIC phiên quản trị (không vẽ giao diện nào). Giao diện đăng nhập và khung trang do website tự quyết:
+//   • mẫu có sẵn, được phép sửa/thay: `@/components/admin-login` (form) và `@/components/admin-layout` (khung);
+//   • hoặc tự dựng giao diện riêng bằng `useAdminSession()`.
+//
+//   export const Route = createFileRoute("/admin")({
+//     component: () => (
+//       <AdminGate fallback={(session) => <AdminLogin session={session} />}>
+//         <AdminLayout title="Admin" nav={[{ to: "/admin", label: "Overview", exact: true }]}>
+//           <Outlet />
+//         </AdminLayout>
+//       </AdminGate>
+//     ),
+//   });
+//
+// Chỉ bọc giao diện; dữ liệu vẫn phải được bảo vệ bằng `await assertAdmin()` trong server function.
+import { useRouter } from "@tanstack/react-router";
+import { useServerFn } from "@tanstack/react-start";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { adminLogin, adminLogout, adminStatus } from "../admin.functions.js";
+const SessionContext = createContext(null);
+/** Phiên quản trị hiện tại. Chỉ dùng bên trong <AdminGate> (cả trong `fallback` và `children`). */
+// eslint-disable-next-line react-refresh/only-export-components
+export function useAdminSession() {
+    const session = useContext(SessionContext);
+    if (!session)
+        throw new Error("useAdminSession must be used inside <AdminGate>.");
+    return session;
+}
+export function AdminGate({ children, fallback, loading = null }) {
+    const status = useServerFn(adminStatus);
+    const loginFn = useServerFn(adminLogin);
+    const logoutFn = useServerFn(adminLogout);
+    const router = useRouter();
+    const [info, setInfo] = useState(null);
+    const [busy, setBusy] = useState(false);
+    const refresh = useCallback(() => status().then(setInfo).catch(() => setInfo({ configured: true, authed: false })), [status]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    const login = useCallback(async (password) => {
+        setBusy(true);
+        const result = await loginFn({ data: { password } }).catch(() => ({ ok: false, reason: "wrong" }));
+        await refresh();
+        // Đổi phiên thì dữ liệu route (loader) đã tải khi chưa đăng nhập phải tải lại.
+        if (result.ok)
+            await router.invalidate();
+        setBusy(false);
+        return result.ok ? { ok: true } : { ok: false, reason: result.reason === "locked" ? "locked" : "wrong" };
+    }, [loginFn, refresh, router]);
+    const logout = useCallback(async () => {
+        setBusy(true);
+        await logoutFn().catch(() => { });
+        await refresh();
+        await router.invalidate();
+        setBusy(false);
+    }, [logoutFn, refresh]);
+    const session = useMemo(() => ({ state: !info ? "loading" : info.authed ? "signedIn" : "signedOut", configured: info?.configured ?? true, busy, login, logout }), [info, busy, login, logout]);
+    return _jsx(SessionContext.Provider, { value: session, children: session.state === "loading" ? loading : session.state === "signedIn" ? children : fallback(session) });
+}

package/dist/react/error-reporting.d.ts

@@ -0,0 +1,21 @@
+type HodelaErrorOptions = {
+    mechanism?: "manual" | "onerror" | "unhandledrejection" | "react_error_boundary";
+    handled?: boolean;
+    severity?: "error" | "warning" | "info";
+};
+type HodelaEvents = {
+    track?: (event: string, properties?: Record<string, unknown>) => string | null;
+    captureException?: (error: unknown, context?: Record<string, unknown>, options?: HodelaErrorOptions) => void;
+};
+declare global {
+    interface Window {
+        __hodelaEvents?: HodelaEvents;
+        __hodelaReportRuntimeError?: (payload: {
+            message: string;
+            stack?: string;
+            filename?: string;
+        }) => void;
+    }
+}
+export declare function reportHodelaError(error: unknown, context?: Record<string, unknown>): void;
+export {};

package/dist/react/error-reporting.js

@@ -0,0 +1,43 @@
+export function reportHodelaError(error, context = {}) {
+    if (typeof window === "undefined")
+        return;
+    window.__hodelaEvents?.captureException?.(error, {
+        source: "react_error_boundary",
+        route: window.location.pathname,
+        ...context,
+    }, {
+        mechanism: "react_error_boundary",
+        handled: false,
+        severity: "error",
+    });
+    // Prod React does not rethrow boundary-caught errors to window.onerror, so the
+    // editor's telemetry never sees them. Forward to hodela.js's reporting hook,
+    // which is present only inside the editor preview.
+    const stack = error instanceof Error ? error.stack : undefined;
+    window.__hodelaReportRuntimeError?.({
+        message: describeThrown(error),
+        ...(stack !== undefined && { stack }),
+        filename: window.location.pathname,
+    });
+}
+const MAX_SERIALIZED_LENGTH = 2000;
+// Loaders and server fns throw raw Responses and plain objects (a Supabase
+// `{ message, code, details }`), which String() reduces to "[object ...]".
+function describeThrown(error) {
+    if (error instanceof Response) {
+        return `Response ${error.status}${error.url ? ` at ${error.url}` : ""}`;
+    }
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    const { message } = (error ?? {});
+    if (typeof message === "string" && message.length > 0)
+        return message;
+    try {
+        return (JSON.stringify(error)?.slice(0, MAX_SERIALIZED_LENGTH) ?? String(error));
+    }
+    catch {
+        return String(error);
+    }
+}

package/dist/react/index.d.ts

@@ -0,0 +1,2 @@
+export { AdminGate, useAdminSession, type AdminLoginResult, type AdminSession } from "./admin-gate.js";
+export { reportHodelaError } from "./error-reporting.js";

package/dist/react/index.js

@@ -0,0 +1,2 @@
+export { AdminGate, useAdminSession } from "./admin-gate.js";
+export { reportHodelaError } from "./error-reporting.js";