@hodela/site 0.2.0 → 0.3.0

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/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

@@ -6,7 +6,7 @@
 //   • 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/server/files.d.ts

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

package/dist/server/files.js

@@ -7,10 +7,10 @@
 // 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 { createHodelaFileClient } from "../file-client.js";
 import { getRequestUrl } from "@tanstack/react-start/server";
 import { serverEnv } from "./env.js";
-export { describeFileError, HodelaFileError } from "@hodela/file-js";
+export { describeFileError, HodelaFileError } from "../file-client.js";
 export function files() {
     const apiUrl = serverEnv("HODELA_API_URL");
     const apiKey = serverEnv("HODELA_API_KEY");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hodela/site",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "files": [
     "dist",
@@ -86,6 +86,14 @@
     "./testing/cloudflare-workers": {
       "types": "./dist/testing/cloudflare-workers.d.ts",
       "import": "./dist/testing/cloudflare-workers.js"
+    },
+    "./email-client": {
+      "types": "./dist/email-client.d.ts",
+      "import": "./dist/email-client.js"
+    },
+    "./file-client": {
+      "types": "./dist/file-client.d.ts",
+      "import": "./dist/file-client.js"
     }
   },
   "scripts": {
@@ -120,10 +128,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@hodela/email-js": "0.1.1",
-    "@hodela/file-js": "0.1.0"
-  },
   "peerDependenciesMeta": {
     "drizzle-orm": {
       "optional": true