@hodela/site 0.1.0 → 0.2.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/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/mailer.js

@@ -1,5 +1,5 @@
 // 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.

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";

package/dist/server/admin.d.ts

@@ -0,0 +1,10 @@
+/** Đã có mật khẩu quản lý hợp lệ (≥ 6 ký tự) chưa. Chưa có thì khu vực quản lý bị khóa hoàn toàn. */
+export declare function adminConfigured(): boolean;
+export declare function isAdmin(): Promise<boolean>;
+/** Ném lỗi UNAUTHORIZED nếu người gọi không phải chủ website. Gọi ở đầu mọi handler quản lý. */
+export declare function assertAdmin(): Promise<void>;
+export declare function loginAdmin(input: string): Promise<{
+    ok: boolean;
+    reason?: "not_configured" | "locked" | "wrong";
+}>;
+export declare function logoutAdmin(): void;

package/dist/server/admin.js

@@ -0,0 +1,61 @@
+// Chỉ chạy trên server. Khu vực quản lý của chủ website: mật khẩu do chủ web đặt (biến ADMIN_PASSWORD),
+// phiên ký bằng HODELA_SESSION_SECRET do Hodela cấp. Hodela quản lý file này: không sửa.
+//
+// Dùng trong server function: `await assertAdmin()` ở đầu MỌI handler đọc/sửa dữ liệu riêng tư
+// (đơn hàng, liên hệ, thông tin khách...). Logic phiên phía giao diện: <AdminGate> và useAdminSession() ở "@hodela/site/react" (mẫu giao diện: admin-login, admin-layout).
+import { getCookie, getRequestIP, setCookie } from "@tanstack/react-start/server";
+import { serverEnv } from "./env.js";
+import { sessionCookie } from "./session-cookie.js";
+import { passwordFingerprint, safeEqual, signAdminToken, verifyAdminToken } from "../admin-token.js";
+const COOKIE = "hodela_admin";
+const SESSION_MS = 12 * 60 * 60 * 1000;
+const MAX_FAILS = 6;
+const FAIL_WINDOW_MS = 10 * 60 * 1000;
+const fails = new Map();
+function password() {
+    const p = serverEnv("ADMIN_PASSWORD");
+    return p && p.length >= 6 ? p : undefined;
+}
+function secret(pw) {
+    return serverEnv("HODELA_SESSION_SECRET") ?? `dev-${pw}`;
+}
+/** Đã có mật khẩu quản lý hợp lệ (≥ 6 ký tự) chưa. Chưa có thì khu vực quản lý bị khóa hoàn toàn. */
+export function adminConfigured() {
+    return password() !== undefined;
+}
+export async function isAdmin() {
+    const pw = password();
+    if (!pw)
+        return false;
+    const s = secret(pw);
+    return verifyAdminToken(s, await passwordFingerprint(s, pw), getCookie(COOKIE), Date.now());
+}
+/** Ném lỗi UNAUTHORIZED nếu người gọi không phải chủ website. Gọi ở đầu mọi handler quản lý. */
+export async function assertAdmin() {
+    if (!(await isAdmin()))
+        throw new Error("UNAUTHORIZED");
+}
+export async function loginAdmin(input) {
+    const pw = password();
+    if (!pw)
+        return { ok: false, reason: "not_configured" };
+    const key = getRequestIP({ xForwardedFor: true }) ?? "unknown";
+    const now = Date.now();
+    const rec = fails.get(key);
+    if (rec && now - rec.first < FAIL_WINDOW_MS && rec.count >= MAX_FAILS)
+        return { ok: false, reason: "locked" };
+    const s = secret(pw);
+    if (!(await safeEqual(s, input, pw))) {
+        const fresh = !rec || now - rec.first >= FAIL_WINDOW_MS;
+        fails.set(key, { count: fresh ? 1 : rec.count + 1, first: fresh ? now : rec.first });
+        await new Promise((r) => setTimeout(r, 400));
+        return { ok: false, reason: "wrong" };
+    }
+    fails.delete(key);
+    const token = await signAdminToken(s, await passwordFingerprint(s, pw), now + SESSION_MS);
+    setCookie(COOKIE, token, sessionCookie(SESSION_MS / 1000));
+    return { ok: true };
+}
+export function logoutAdmin() {
+    setCookie(COOKIE, "", sessionCookie(0));
+}

package/dist/server/customer-auth.d.ts

@@ -0,0 +1,11 @@
+export { hashPassword, passwordProblem, verifyPassword } from "../customer-auth.js";
+export declare function startCustomerSession(customerId: string): Promise<void>;
+export declare function endCustomerSession(): void;
+/** Id khách đang đăng nhập, hoặc null. Luôn kiểm tra chữ ký; id này vẫn phải được đối chiếu với database khi cần. */
+export declare function currentCustomerId(): Promise<string | null>;
+/**
+ * Chặn dò mật khẩu: gọi trước khi kiểm tra mật khẩu (`tooManyLoginAttempts()`), và `recordLoginFailure()` khi sai.
+ * Giới hạn theo IP trong bộ nhớ của instance; đủ để chặn dò đơn giản, không thay cho việc dùng mật khẩu mạnh.
+ */
+export declare function tooManyLoginAttempts(): boolean;
+export declare function recordLoginFailure(): void;

package/dist/server/customer-auth.js

@@ -0,0 +1,45 @@
+// Chỉ chạy trên server. Phiên đăng nhập của khách hàng cuối. Hodela quản lý file này: không sửa.
+//
+// Mẫu dùng (bảng `customers` do bạn tạo trong db/migrations, cột password_hash lưu kết quả hashPassword):
+//   register: kiểm tra email chưa tồn tại → hashPassword → INSERT vào database → startCustomerSession(id)
+//   login   : SELECT theo email → verifyPassword → startCustomerSession(id)   (sai thì báo chung "Email hoặc mật khẩu không đúng")
+//   trang cần đăng nhập: const id = await currentCustomerId(); if (!id) → yêu cầu đăng nhập
+import { getCookie, getRequestIP, setCookie } from "@tanstack/react-start/server";
+import { serverEnv } from "./env.js";
+import { sessionCookie } from "./session-cookie.js";
+import { signCustomerToken, verifyCustomerToken } from "../customer-auth.js";
+export { hashPassword, passwordProblem, verifyPassword } from "../customer-auth.js";
+const COOKIE = "hodela_customer";
+const SESSION_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_FAILS = 8;
+const FAIL_WINDOW_MS = 10 * 60 * 1000;
+const fails = new Map();
+function secret() {
+    return serverEnv("HODELA_SESSION_SECRET") ?? "dev-customer-session";
+}
+export async function startCustomerSession(customerId) {
+    const token = await signCustomerToken(secret(), customerId, Date.now() + SESSION_MS);
+    setCookie(COOKIE, token, sessionCookie(SESSION_MS / 1000));
+}
+export function endCustomerSession() {
+    setCookie(COOKIE, "", sessionCookie(0));
+}
+/** Id khách đang đăng nhập, hoặc null. Luôn kiểm tra chữ ký; id này vẫn phải được đối chiếu với database khi cần. */
+export async function currentCustomerId() {
+    return verifyCustomerToken(secret(), getCookie(COOKIE), Date.now());
+}
+/**
+ * Chặn dò mật khẩu: gọi trước khi kiểm tra mật khẩu (`tooManyLoginAttempts()`), và `recordLoginFailure()` khi sai.
+ * Giới hạn theo IP trong bộ nhớ của instance; đủ để chặn dò đơn giản, không thay cho việc dùng mật khẩu mạnh.
+ */
+export function tooManyLoginAttempts() {
+    const rec = fails.get(getRequestIP({ xForwardedFor: true }) ?? "unknown");
+    return Boolean(rec && Date.now() - rec.first < FAIL_WINDOW_MS && rec.count >= MAX_FAILS);
+}
+export function recordLoginFailure() {
+    const key = getRequestIP({ xForwardedFor: true }) ?? "unknown";
+    const now = Date.now();
+    const rec = fails.get(key);
+    const fresh = !rec || now - rec.first >= FAIL_WINDOW_MS;
+    fails.set(key, { count: fresh ? 1 : rec.count + 1, first: fresh ? now : rec.first });
+}

package/dist/server/db.d.ts

@@ -0,0 +1,20 @@
+import type { MySqlDatabase } from "drizzle-orm/mysql-core";
+import type { PgDatabase } from "drizzle-orm/pg-core";
+import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+export type Dialect = "sqlite" | "postgres" | "mysql";
+export type DbFor<D extends Dialect> = D extends "postgres" ? PgDatabase<any, any, any> : D extends "mysql" ? MySqlDatabase<any, any, any, any> : BaseSQLiteDatabase<"async", any, any>;
+/** Dialect đang được cấu hình cho website này. Viết schema bằng đúng dialect này. */
+export declare function databaseDialect(): Dialect;
+/** Gọi một lần trong `src/lib/db.server.ts` của website; trả về `getDb` và `databaseDialect` đã gắn migration của website đó. */
+export declare function createDbAccess(files: Record<string, string>): {
+    getDb: typeof getDb;
+    databaseDialect: typeof databaseDialect;
+};
+/**
+ * Trả về đối tượng Drizzle đã kết nối. Gọi một lần trong mỗi server function (đừng giữ ở biến module:
+ * kết nối TCP không dùng lại giữa các request trên Cloudflare Workers).
+ *
+ *   const db = await getDb();                 // sqlite: D1 hoặc libsql
+ *   const db = await getDb<"postgres">();     // khi website dùng Postgres
+ */
+export declare function getDb<D extends Dialect = "sqlite">(): Promise<DbFor<D>>;

package/dist/server/db.js

@@ -0,0 +1,133 @@
+// Chỉ chạy trên server (đuôi .server.ts). Import trong handler của createServerFn hoặc server route.
+//
+// Kết nối database cho website. Dùng Drizzle ORM; file này chỉ chọn driver theo CẤU HÌNH:
+//   - Mặc định: D1 của Hodela (binding PROJECT_DB, dialect sqlite).
+//   - Chủ web đổi sang database của họ trong Cài đặt → Cơ sở dữ liệu: Hodela đặt DATABASE_URL
+//     (postgresql://…, mysql://…, libsql://… ?authToken=…) và HODELA_DB_DIALECT.
+// Mã nguồn của website KHÔNG đổi khi đổi URL hoặc đổi nhà cung cấp trong cùng dialect.
+// Đổi dialect (sqlite ↔ postgres ↔ mysql) cần viết lại schema, vì mỗi dialect có kiểu bảng riêng.
+import { env } from "cloudflare:workers";
+import { splitSqlStatements } from "../sql-split.js";
+import { sql } from "drizzle-orm";
+/* eslint-enable @typescript-eslint/no-explicit-any */
+function text(name) {
+    const v = env[name];
+    return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+function dialectFromUrl(url) {
+    if (/^postgres(ql)?:/i.test(url))
+        return "postgres";
+    if (/^mysql2?:/i.test(url))
+        return "mysql";
+    return "sqlite";
+}
+/** Dialect đang được cấu hình cho website này. Viết schema bằng đúng dialect này. */
+export function databaseDialect() {
+    const configured = text("HODELA_DB_DIALECT");
+    if (configured === "postgres" || configured === "mysql" || configured === "sqlite") {
+        return configured;
+    }
+    const url = text("DATABASE_URL");
+    return url ? dialectFromUrl(url) : "sqlite";
+}
+// Migration của website được đóng gói vào bundle lúc build: `src/lib/db.server.ts` của website chạy `import.meta.glob("/db/migrations/*.sql")`
+// rồi đưa vào `createDbAccess`. Với D1, Hodela áp trước mỗi lần build. Với database ngoài, website tự áp lúc chạy (một lần mỗi instance).
+let migrationFiles = {};
+/** Gọi một lần trong `src/lib/db.server.ts` của website; trả về `getDb` và `databaseDialect` đã gắn migration của website đó. */
+export function createDbAccess(files) {
+    migrationFiles = files;
+    return { getDb, databaseDialect };
+}
+function migrations() {
+    return Object.entries(migrationFiles)
+        .map(([path, body]) => ({ name: path.split("/").pop() ?? path, sql: body }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+async function sha256(textValue) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(textValue));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function execute(db, dialect, query) {
+    if (dialect === "sqlite") {
+        const out = await db.all(query);
+        return Array.isArray(out) ? out : [];
+    }
+    const out = await db.execute(query);
+    if (dialect === "mysql")
+        return Array.isArray(out?.[0]) ? out[0] : [];
+    return Array.isArray(out) ? out : (out?.rows ?? []);
+}
+let migrated;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function runMigrations(db, dialect) {
+    const files = migrations();
+    if (files.length === 0)
+        return;
+    await execute(db, dialect, sql.raw("CREATE TABLE IF NOT EXISTS _hodela_migrations (name VARCHAR(255) PRIMARY KEY, checksum VARCHAR(64) NOT NULL)"));
+    const rows = (await execute(db, dialect, sql.raw("SELECT name, checksum FROM _hodela_migrations")));
+    const applied = new Map(rows.map((r) => [r.name, r.checksum]));
+    for (const file of files) {
+        const checksum = await sha256(file.sql);
+        const prior = applied.get(file.name);
+        if (prior !== undefined) {
+            if (prior !== checksum) {
+                throw new Error(`Migration ${file.name} đã áp rồi nhưng nội dung bị sửa. Tạo file migration mới thay vì sửa file cũ.`);
+            }
+            continue;
+        }
+        for (const statement of splitSqlStatements(file.sql, dialect)) {
+            await execute(db, dialect, sql.raw(statement.sql));
+        }
+        await execute(db, dialect, sql.raw(`INSERT INTO _hodela_migrations (name, checksum) VALUES ('${file.name.replace(/'/g, "''")}', '${checksum}')`));
+    }
+}
+/**
+ * Trả về đối tượng Drizzle đã kết nối. Gọi một lần trong mỗi server function (đừng giữ ở biến module:
+ * kết nối TCP không dùng lại giữa các request trên Cloudflare Workers).
+ *
+ *   const db = await getDb();                 // sqlite: D1 hoặc libsql
+ *   const db = await getDb<"postgres">();     // khi website dùng Postgres
+ */
+export async function getDb() {
+    const url = text("DATABASE_URL");
+    const dialect = databaseDialect();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let db;
+    if (!url) {
+        const d1 = env["PROJECT_DB"];
+        if (!d1) {
+            throw new Error("Website chưa có database. Thêm file db/migrations/0001_*.sql để Hodela tạo database, hoặc cấu hình database của bạn trong Cài đặt → Cơ sở dữ liệu.");
+        }
+        const { drizzle } = await import("drizzle-orm/d1");
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        db = drizzle(d1);
+    }
+    else if (dialect === "postgres") {
+        const { default: postgres } = await import("postgres");
+        const { drizzle } = await import("drizzle-orm/postgres-js");
+        db = drizzle(postgres(url, { max: 1, prepare: false }));
+    }
+    else if (dialect === "mysql") {
+        const mysql = await import("mysql2/promise");
+        const { drizzle } = await import("drizzle-orm/mysql2");
+        db = drizzle(mysql.createPool(url));
+    }
+    else {
+        const { createClient } = await import("@libsql/client/web");
+        const { drizzle } = await import("drizzle-orm/libsql/web");
+        const parsed = new URL(url);
+        const authToken = parsed.searchParams.get("authToken") ?? undefined;
+        parsed.searchParams.delete("authToken");
+        db = drizzle(createClient({ url: parsed.toString().replace(/\?$/, ""), ...(authToken ? { authToken } : {}) }));
+    }
+    // D1 mặc định: Hodela đã áp migration lúc build. Database ngoài: website tự áp.
+    if (url) {
+        migrated ??= runMigrations(db, dialect).catch((error) => {
+            migrated = undefined;
+            throw error;
+        });
+        await migrated;
+    }
+    return db;
+}

package/dist/server/entry.d.ts

@@ -0,0 +1,4 @@
+import "./error-capture.js";
+export declare function createHodelaServerEntry(loadServerEntry: () => Promise<unknown>): {
+    fetch(request: Request, env: unknown, ctx: unknown): Promise<Response>;
+};

package/dist/server/entry.js

@@ -0,0 +1,97 @@
+// Điểm vào worker của website: PIN/IP/chặn bot trước khi chạy ứng dụng, chèn analytics và badge sau khi chạy, trang lỗi thống nhất.
+// `src/server.ts` của website chỉ gọi `createHodelaServerEntry(() => import("@tanstack/react-start/server-entry"))`.
+import "./error-capture.js";
+import { consumeLastCapturedError } from "./error-capture.js";
+import { badgeHtml, enforceAccess, parseAccessConfig } from "../access.js";
+import { analyticsHeadSnippet, parseAnalyticsConfig } from "../analytics.js";
+import { renderErrorPage } from "../error-page.js";
+// h3 swallows in-handler throws into a normal 500 Response with body
+// {"unhandled":true,"message":"HTTPError"} — try/catch alone never fires for those.
+async function normalizeCatastrophicSsrResponse(response) {
+    if (response.status < 500)
+        return response;
+    const contentType = response.headers.get("content-type") ?? "";
+    if (!contentType.includes("application/json"))
+        return response;
+    const body = await response.clone().text();
+    if (!isH3SwallowedErrorBody(body))
+        return response;
+    console.error(consumeLastCapturedError() ?? new Error(`h3 swallowed SSR error: ${body}`));
+    return new Response(renderErrorPage(), {
+        status: 500,
+        headers: { "content-type": "text/html; charset=utf-8" },
+    });
+}
+function isH3SwallowedErrorBody(body) {
+    try {
+        const payload = JSON.parse(body);
+        return payload.unhandled === true && payload.message === "HTTPError";
+    }
+    catch {
+        return false;
+    }
+}
+// Mã đo lường và badge chủ web bật/được áp trong cài đặt: chỉ chèn khi đã xuất bản, không chèn ở bản xem trước.
+function withInjections(response, env) {
+    const bindings = (env ?? {});
+    if (bindings["HODELA_ENV"] !== "production")
+        return response;
+    const type = response.headers.get("content-type") ?? "";
+    if (!type.includes("text/html"))
+        return response;
+    const snippet = analyticsHeadSnippet(parseAnalyticsConfig(bindings["HODELA_ANALYTICS"]));
+    const badge = badgeHtml(parseAccessConfig(bindings["HODELA_ACCESS"]));
+    const Rewriter = globalThis.HTMLRewriter;
+    if ((!snippet && !badge) || !Rewriter)
+        return response;
+    let rewriter = new Rewriter();
+    if (snippet) {
+        rewriter = rewriter.on("head", {
+            element(el) {
+                el.append(snippet, { html: true });
+            },
+        });
+    }
+    if (badge) {
+        rewriter = rewriter.on("body", {
+            element(el) {
+                el.append(badge, { html: true });
+            },
+        });
+    }
+    return rewriter.transform(response);
+}
+// PIN, danh sách IP và chặn bot của site đã xuất bản; chặn trước khi chạy ứng dụng.
+async function blockedByAccess(request, env) {
+    const bindings = (env ?? {});
+    if (bindings["HODELA_ENV"] !== "production")
+        return null;
+    const secret = typeof bindings["HODELA_SESSION_SECRET"] === "string" ? bindings["HODELA_SESSION_SECRET"] : "";
+    return enforceAccess(request, parseAccessConfig(bindings["HODELA_ACCESS"]), secret);
+}
+export function createHodelaServerEntry(loadServerEntry) {
+    let serverEntryPromise;
+    const getServerEntry = () => {
+        serverEntryPromise ??= loadServerEntry().then((m) => (m.default ?? m));
+        return serverEntryPromise;
+    };
+    return {
+        async fetch(request, env, ctx) {
+            try {
+                const blocked = await blockedByAccess(request, env);
+                if (blocked)
+                    return blocked;
+                const handler = await getServerEntry();
+                const response = await handler.fetch(request, env, ctx);
+                return withInjections(await normalizeCatastrophicSsrResponse(response), env);
+            }
+            catch (error) {
+                console.error(error);
+                return new Response(renderErrorPage(), {
+                    status: 500,
+                    headers: { "content-type": "text/html; charset=utf-8" },
+                });
+            }
+        },
+    };
+}

package/dist/server/env.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Biến môi trường do chủ web cấu hình trong Cài đặt → Environments (ví dụ RESEND_API_KEY).
+ * Trả về undefined nếu chưa cấu hình: code phải chạy được khi thiếu, đừng hardcode giá trị.
+ */
+export declare function serverEnv(name: string): string | undefined;
+/** "preview" khi xem thử trong editor, "production" khi đã xuất bản. */
+export declare function hodelaEnv(): "preview" | "production";

package/dist/server/env.js

@@ -0,0 +1,14 @@
+// Chỉ chạy trên server (đuôi .server.ts). Import trong handler của createServerFn hoặc server route.
+import { env } from "cloudflare:workers";
+/**
+ * Biến môi trường do chủ web cấu hình trong Cài đặt → Environments (ví dụ RESEND_API_KEY).
+ * Trả về undefined nếu chưa cấu hình: code phải chạy được khi thiếu, đừng hardcode giá trị.
+ */
+export function serverEnv(name) {
+    const value = env[name];
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/** "preview" khi xem thử trong editor, "production" khi đã xuất bản. */
+export function hodelaEnv() {
+    return env["HODELA_ENV"] === "production" ? "production" : "preview";
+}

package/dist/server/error-capture.d.ts

@@ -0,0 +1,2 @@
+export declare function describeError(error: unknown): string;
+export declare function consumeLastCapturedError(): unknown;

package/dist/server/error-capture.js

@@ -0,0 +1,72 @@
+// Captures the original Error out-of-band so server.ts can recover the stack
+// when h3 has already swallovwed the throw into a generic 500 Response.
+let lastCapturedError;
+const TTL_MS = 5_000;
+function record(error) {
+    lastCapturedError = { error, at: Date.now() };
+}
+// h3's HTTPError serializes to {"status":500,"unhandled":true,"message":"HTTPError"} —
+// no stack, no cause — so a plain console.error(error) reaches the log pipeline with
+// the failure detail stripped. Expand Error-like args into a string that keeps the
+// message, stack, and the full cause chain.
+const CAUSE_DEPTH_LIMIT = 5;
+const DESCRIPTION_LENGTH_LIMIT = 8_000;
+export function describeError(error) {
+    const parts = [];
+    let current = error;
+    for (let depth = 0; depth < CAUSE_DEPTH_LIMIT && current != null; depth++) {
+        if (!(current instanceof Error)) {
+            parts.push(typeof current === "string" ? current : safeStringify(current));
+            break;
+        }
+        const label = depth === 0 ? "" : "caused by: ";
+        const status = describeStatus(current);
+        parts.push(`${label}${current.stack ?? `${current.name}: ${current.message}`}${status}`);
+        current = current.cause;
+    }
+    return parts.join("\n").slice(0, DESCRIPTION_LENGTH_LIMIT);
+}
+function describeStatus(error) {
+    const { status, statusCode } = error;
+    const value = status ?? statusCode;
+    return typeof value === "number" ? ` (status ${value})` : "";
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function isErrorLike(value) {
+    return value instanceof Error;
+}
+// Wrap console.error so errors logged by any layer — including h3's internal
+// unhandled-error logging, which this file cannot hook directly — are both
+// recorded for consumeLastCapturedError and expanded before serialization.
+const originalConsoleError = console.error.bind(console);
+console.error = (...args) => {
+    const expanded = args.map((arg) => {
+        if (!isErrorLike(arg))
+            return arg;
+        record(arg);
+        return describeError(arg);
+    });
+    originalConsoleError(...expanded);
+};
+if (typeof globalThis.addEventListener === "function") {
+    globalThis.addEventListener("error", (event) => record(event.error ?? event));
+    globalThis.addEventListener("unhandledrejection", (event) => record(event.reason));
+}
+export function consumeLastCapturedError() {
+    if (!lastCapturedError)
+        return undefined;
+    if (Date.now() - lastCapturedError.at > TTL_MS) {
+        lastCapturedError = undefined;
+        return undefined;
+    }
+    const { error } = lastCapturedError;
+    lastCapturedError = undefined;
+    return error;
+}

package/dist/server/files.d.ts

@@ -0,0 +1,17 @@
+export { describeFileError, HodelaFileError } from "@hodela/file-js";
+export declare function files(): {
+    put(body: import("@hodela/file-js").FileBody, opts?: import("@hodela/file-js").PutFileOptions): Promise<import("@hodela/file-js").PutFileResult>;
+    get: (id: string) => Promise<import("@hodela/file-js").HodelaFile>;
+    list: (opts?: {
+        limit?: number;
+        before?: string;
+    }) => Promise<{
+        data: import("@hodela/file-js").HodelaFile[];
+        nextBefore: string | null;
+    }>;
+    usage: () => Promise<import("@hodela/file-js").FileUsage>;
+    signedUrl: (id: string, opts?: {
+        ttlSec?: number;
+    }) => Promise<import("@hodela/file-js").SignedUrl>;
+    delete(id: string): Promise<void>;
+};

package/dist/server/files.js

@@ -0,0 +1,21 @@
+// Chỉ chạy trên server. Hodela quản lý file này: không sửa. Dùng trong server function:
+//
+//   import { files } from "@hodela/site/server/files";
+//   const saved = await files().put(file);          // file: File lấy từ FormData
+//   // saved.url dùng thẳng trong <img src> hoặc <a href>, lưu vào database cạnh bản ghi.
+//
+// Cùng một đoạn mã chạy ở mọi nơi:
+//   • Hodela (xem thử và đã xuất bản): kho file của nền tảng (R2) qua HODELA_API_URL / HODELA_API_KEY do Hodela cấp.
+//   • Máy dev (`pnpm dev`, không có hai biến trên): plugin Vite ghi ảnh vào public/hodela-media (@hodela/dev).
+import { createHodelaFileClient } from "@hodela/file-js";
+import { getRequestUrl } from "@tanstack/react-start/server";
+import { serverEnv } from "./env.js";
+export { describeFileError, HodelaFileError } from "@hodela/file-js";
+export function files() {
+    const apiUrl = serverEnv("HODELA_API_URL");
+    const apiKey = serverEnv("HODELA_API_KEY");
+    if (apiUrl && apiKey)
+        return createHodelaFileClient({ apiUrl, apiKey });
+    // Không có khóa của Hodela: đang chạy ở máy dev, dùng kho giả lập của Vite dev server (cùng origin với trang đang mở).
+    return createHodelaFileClient({ apiUrl: `${getRequestUrl().origin}/__hodela/dev`, apiKey: "dev" });
+}

package/dist/server/mailer.d.ts

@@ -0,0 +1,10 @@
+import { createMailer, type MailProvider } from "../mailer.js";
+export { escapeMailHtml, type MailInput, type MailProvider, type MailResult } from "../mailer.js";
+export declare const sendMail: ReturnType<typeof createMailer>["sendMail"];
+export declare const recentMail: ReturnType<typeof createMailer>["recentMail"];
+export declare const notifyOwner: ReturnType<typeof createMailer>["notifyOwner"];
+/** Cho giao diện quản lý biết thông báo email đang bật hay tắt (không lộ khóa). */
+export declare function mailStatus(): {
+    provider: MailProvider;
+    notifyEmail: string | null;
+};

package/dist/server/mailer.js

@@ -0,0 +1,16 @@
+// Chỉ chạy trên server. Hodela quản lý file này: không sửa. Xem giải thích trong "../mailer.js".
+//
+//   import { notifyOwner, sendMail } from "@hodela/site/server/mailer";
+//   // Sau khi ĐÃ lưu dữ liệu vào database (không await lỗi, không để lỗi mail làm hỏng đơn):
+//   await notifyOwner({ subject: "Đơn hàng mới #123", text: "...", replyTo: khach.email });
+import { createMailer, mailProvider } from "../mailer.js";
+import { hodelaEnv, serverEnv } from "./env.js";
+export { escapeMailHtml } from "../mailer.js";
+const mailer = () => createMailer({ env: serverEnv, mode: hodelaEnv() });
+export const sendMail = (input) => mailer().sendMail(input);
+export const recentMail = (limit) => mailer().recentMail(limit);
+export const notifyOwner = (input) => mailer().notifyOwner(input);
+/** Cho giao diện quản lý biết thông báo email đang bật hay tắt (không lộ khóa). */
+export function mailStatus() {
+    return { provider: mailProvider(serverEnv), notifyEmail: serverEnv("NOTIFY_EMAIL") ?? null };
+}

package/dist/server/session-cookie.d.ts

@@ -0,0 +1,2 @@
+import { type SessionCookieOptions } from "../session-cookie.js";
+export declare function sessionCookie(maxAgeSeconds: number): SessionCookieOptions;

package/dist/server/session-cookie.js

@@ -0,0 +1,7 @@
+// Chỉ chạy trên server. Gắn thuộc tính cookie phiên (xem session-cookie.ts) theo request hiện tại. Hodela quản lý file này: không sửa.
+import { getRequestUrl } from "@tanstack/react-start/server";
+import { hodelaEnv } from "./env.js";
+import { sessionCookieOptions } from "../session-cookie.js";
+export function sessionCookie(maxAgeSeconds) {
+    return sessionCookieOptions(hodelaEnv(), getRequestUrl(), maxAgeSeconds);
+}

package/dist/start.d.ts

@@ -0,0 +1,2 @@
+/** `src/start.ts` của website: `export const startInstance = createHodelaStart();` */
+export declare const createHodelaStart: () => import("@tanstack/react-start").StartInstance<[], import("@tanstack/router-core").SSROption, readonly [import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>, import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>], []>;

package/dist/start.js

@@ -0,0 +1,27 @@
+import { createStart, createCsrfMiddleware, createMiddleware, } from "@tanstack/react-start";
+import { renderErrorPage } from "./error-page.js";
+const errorMiddleware = createMiddleware().server(async ({ next }) => {
+    try {
+        return await next();
+    }
+    catch (error) {
+        if (error != null && typeof error === "object" && "statusCode" in error) {
+            throw error;
+        }
+        console.error(error);
+        return new Response(renderErrorPage(), {
+            status: 500,
+            headers: { "content-type": "text/html; charset=utf-8" },
+        });
+    }
+});
+// Start installs this automatically when src/start.ts is absent; defining the
+// file opts out, so re-add it explicitly to keep server functions protected
+// from cross-site requests.
+const csrfMiddleware = createCsrfMiddleware({
+    filter: (ctx) => ctx.handlerType === "serverFn",
+});
+/** `src/start.ts` của website: `export const startInstance = createHodelaStart();` */
+export const createHodelaStart = () => createStart(() => ({
+    requestMiddleware: [errorMiddleware, csrfMiddleware],
+}));

package/dist/testing/cloudflare-workers.d.ts

@@ -0,0 +1 @@
+export declare const env: Record<string, unknown>;

package/dist/testing/cloudflare-workers.js

@@ -0,0 +1,3 @@
+// Bản thay `cloudflare:workers` cho test (vitest chạy trên Node nên không có module ảo này).
+// vitest.config.ts của website: `resolve.alias["cloudflare:workers"]` trỏ vào file này và `test.server.deps.inline: [/@hodela\/site/]`.
+export const env = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hodela/site",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "files": [
     "dist",
@@ -38,6 +38,54 @@
     "./seo": {
       "types": "./dist/seo.d.ts",
       "import": "./dist/seo.js"
+    },
+    "./admin-functions": {
+      "types": "./dist/admin.functions.d.ts",
+      "import": "./dist/admin.functions.js"
+    },
+    "./start": {
+      "types": "./dist/start.d.ts",
+      "import": "./dist/start.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./server/env": {
+      "types": "./dist/server/env.d.ts",
+      "import": "./dist/server/env.js"
+    },
+    "./server/session-cookie": {
+      "types": "./dist/server/session-cookie.d.ts",
+      "import": "./dist/server/session-cookie.js"
+    },
+    "./server/admin": {
+      "types": "./dist/server/admin.d.ts",
+      "import": "./dist/server/admin.js"
+    },
+    "./server/customer-auth": {
+      "types": "./dist/server/customer-auth.d.ts",
+      "import": "./dist/server/customer-auth.js"
+    },
+    "./server/mailer": {
+      "types": "./dist/server/mailer.d.ts",
+      "import": "./dist/server/mailer.js"
+    },
+    "./server/files": {
+      "types": "./dist/server/files.d.ts",
+      "import": "./dist/server/files.js"
+    },
+    "./server/db": {
+      "types": "./dist/server/db.d.ts",
+      "import": "./dist/server/db.js"
+    },
+    "./server/entry": {
+      "types": "./dist/server/entry.d.ts",
+      "import": "./dist/server/entry.js"
+    },
+    "./testing/cloudflare-workers": {
+      "types": "./dist/testing/cloudflare-workers.d.ts",
+      "import": "./dist/testing/cloudflare-workers.js"
     }
   },
   "scripts": {
@@ -46,14 +94,26 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@tanstack/react-start": ">=1.100.0"
+    "@tanstack/react-router": ">=1.100.0",
+    "@tanstack/react-start": ">=1.100.0",
+    "drizzle-orm": ">=0.39.0",
+    "react": ">=19.0.0",
+    "zod": ">=3.25.0"
   },
   "devDependencies": {
+    "@libsql/client": "^0.18.0",
+    "@tanstack/react-router": "1.170.46",
     "@tanstack/react-start": "1.169.4",
     "@types/node": "^22.16.5",
+    "@types/react": "^19.2.0",
+    "drizzle-orm": "^0.39.1",
+    "mysql2": "^3.24.6",
+    "postgres": "^4.0.0",
+    "react": "^19.2.0",
     "typescript": "^5.8.3",
     "vite": "^8.3.5",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "zod": "^3.25.76"
   },
   "description": "Mã chạy chung của website Hodela (truy cập, analytics, phiên quản trị, tài khoản khách, email, SEO, tách SQL). Starter dùng gói này thay vì chép mã vào từng website.",
   "license": "MIT",
@@ -61,6 +121,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@hodela/email-js": "0.1.1"
+    "@hodela/email-js": "0.1.1",
+    "@hodela/file-js": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    }
   }
 }