talizen 0.1.3 → 0.2.0

package/README.md

@@ -14,78 +14,89 @@ The package is designed to hold the platform-level APIs that frontend projects u
 npm install talizen
 ```
 
+or use esm.sh
+
+```
+{
+  "imports": {
+    "talizen": "https://esm.sh/talizen@0.1.4"
+    "talizen/": "https://esm.sh/talizen@0.1.4/"
+  }
+}
+```
+
 ## Usage
 
 ### Configure the client
 
 ```ts
-import { setTalizenConfig } from "talizen/core"
+import { setTalizenConfig } from "talizen/core";
 
 setTalizenConfig({
   baseUrl: "https://www.talizen.com",
   onFileUploadProcess(key, process) {
-    console.log(key, process)
+    console.log(key, process);
   },
-})
+});
 ```
 
 ### List CMS content
 
 ```ts
-import { listContents, type BaseCmsItem } from "talizen/cms"
+import { listContents, type BaseCmsItem } from "talizen/cms";
 
 interface Blog extends BaseCmsItem {
-  readonly __cmsKey: "blogs"
+  readonly __cmsKey: "blogs";
   body: {
-    title?: string
-    content?: string
-  }
+    title?: string;
+    content?: string;
+  };
 }
 
 const result = await listContents<Blog>("blogs", {
   limit: 10,
   orderBy: "-created_at",
-})
+});
 
-console.log(result.list)
-console.log(result.total)
+console.log(result.list);
+console.log(result.total);
 ```
 
 ### Get a single CMS content item
 
 ```ts
-import { getContent, type BaseCmsItem } from "talizen/cms"
+import { getContent, type BaseCmsItem } from "talizen/cms";
 
 interface Blog extends BaseCmsItem {
-  readonly __cmsKey: "blogs"
+  readonly __cmsKey: "blogs";
   body: {
-    title?: string
-  }
+    title?: string;
+  };
 }
 
-const blog = await getContent<Blog>("blogs", "hello-world")
+const blog = await getContent<Blog>("blogs", "hello-world");
 ```
 
 ### Get CMS collection metadata
 
 ```ts
-import { getContentCollection } from "talizen/cms"
+import { getContentCollection } from "talizen/cms";
 
-const collection = await getContentCollection("blogs")
+const collection = await getContentCollection("blogs");
 
-console.log(collection?.title)
-console.log(collection?.jsonSchema)
+console.log(collection?.title);
+console.log(collection?.jsonSchema);
 ```
 
 ### Submit a form
 
 ```ts
-import { submitForm } from "talizen/form"
+import { submitForm } from "talizen/form";
 
 await submitForm("contact-form", {
   email: "hi@talizen.com",
   message: "Hello from the website",
-})
+});
 ```
 
 When a `File` object appears in the payload, `submitForm()` will:
@@ -118,3 +129,21 @@ git tag v0.0.8
 git push origin main
 git push origin v0.0.8
 ```
+
+## Development
+
+```bash
+bun run dev
+```
+
+This will build the package and start a development server at http://localhost:8787.
+
+Use the development server in your project:
+
+```json
+{
+  "imports": {
+    "talizen/form": "http://localhost:8787/form.js"
+  }
+}
+```

package/captcha-ui.d.ts

@@ -0,0 +1,37 @@
+export interface CaptchaChallenge {
+    token: string;
+    type: "slide";
+    master_img: string;
+    tile_img: string;
+    width: number;
+    height: number;
+    tile_width: number;
+    tile_height: number;
+    tile_x: number;
+    tile_y: number;
+}
+export interface CaptchaUiTheme {
+    zIndex?: number;
+    width?: number;
+    title?: string;
+    subtitle?: string;
+    cancelText?: string;
+    sliderText?: string;
+    retryText?: string;
+}
+export interface CaptchaVerifyResult {
+    token: string;
+    x: number;
+    y: number;
+}
+export interface CaptchaVerificationFlowOptions<T> {
+    initialCaptcha: CaptchaChallenge;
+    refreshCaptcha: () => Promise<CaptchaChallenge>;
+    signal?: AbortSignal;
+    shouldRetry: (error: unknown) => boolean;
+    theme?: CaptchaUiTheme;
+    verify: (result: CaptchaVerifyResult) => Promise<T>;
+}
+export declare function shouldRetryCaptchaSubmit(error: unknown, shouldTriggerCaptcha: (error: unknown) => boolean): boolean;
+export declare function buildCaptchaAnswer(x: number, y: number): string;
+export declare function runCaptchaVerification<T>(options: CaptchaVerificationFlowOptions<T>): Promise<T>;

package/captcha-ui.js

@@ -0,0 +1,404 @@
+import { TalizenHttpError } from "./core.js";
+export function shouldRetryCaptchaSubmit(error, shouldTriggerCaptcha) {
+    if (shouldTriggerCaptcha(error)) {
+        return true;
+    }
+    if (!(error instanceof TalizenHttpError)) {
+        return false;
+    }
+    if (isCaptchaErrorBody(error)) {
+        return true;
+    }
+    return error.status >= 400 && error.status < 500;
+}
+export function buildCaptchaAnswer(x, y) {
+    return JSON.stringify({ x, y });
+}
+export function runCaptchaVerification(options) {
+    if (typeof document === "undefined") {
+        throw new Error("Talizen captcha UI requires browser DOM support.");
+    }
+    if (options.signal?.aborted) {
+        throw createAbortError();
+    }
+    return new Promise((resolve, reject) => {
+        const dialogTheme = resolveCaptchaDialogTheme(options.initialCaptcha, options.theme);
+        const elements = createCaptchaDialogElements(options.initialCaptcha, dialogTheme);
+        const { host, tile, slider, errorText, cancelButton } = elements;
+        let currentCaptcha = options.initialCaptcha;
+        let settled = false;
+        let verifying = false;
+        document.body.append(host);
+        const cleanup = () => {
+            host.removeEventListener("click", handleBackdropClick);
+            document.removeEventListener("keydown", handleKeydown);
+            slider.removeEventListener("input", updateTilePosition);
+            slider.removeEventListener("change", submit);
+            cancelButton.removeEventListener("click", cancel);
+            options.signal?.removeEventListener("abort", abort);
+            host.remove();
+        };
+        const settle = (callback) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            callback();
+        };
+        const updateTilePosition = () => {
+            tile.style.left = `${getSliderValue(slider)}px`;
+            setCaptchaErrorText(errorText);
+        };
+        const submit = async () => {
+            if (verifying) {
+                return;
+            }
+            verifying = true;
+            const x = getSliderValue(slider);
+            setCaptchaDialogDisabled(elements, true);
+            try {
+                const result = await options.verify({ token: currentCaptcha.token, x, y: currentCaptcha.tile_y });
+                settle(() => resolve(result));
+            }
+            catch (error) {
+                if (!options.shouldRetry(error)) {
+                    settle(() => reject(error));
+                    return;
+                }
+                try {
+                    currentCaptcha = await options.refreshCaptcha();
+                    updateCaptchaDialogCaptcha(elements, currentCaptcha, dialogTheme);
+                    setCaptchaErrorText(errorText, dialogTheme.retryText);
+                }
+                catch (refreshError) {
+                    settle(() => reject(refreshError));
+                    return;
+                }
+            }
+            finally {
+                verifying = false;
+                if (!settled) {
+                    setCaptchaDialogDisabled(elements, false);
+                    slider.focus();
+                }
+            }
+        };
+        const cancel = () => {
+            settle(() => reject(new Error("Talizen captcha verification was cancelled by user.")));
+        };
+        const abort = () => {
+            settle(() => reject(createAbortError()));
+        };
+        const handleBackdropClick = (event) => {
+            if (event.target === host) {
+                cancel();
+            }
+        };
+        const handleKeydown = (event) => {
+            if (event.key === "Escape") {
+                cancel();
+            }
+        };
+        slider.addEventListener("input", updateTilePosition);
+        slider.addEventListener("change", submit);
+        host.addEventListener("click", handleBackdropClick);
+        document.addEventListener("keydown", handleKeydown);
+        cancelButton.addEventListener("click", cancel);
+        options.signal?.addEventListener("abort", abort, { once: true });
+        updateTilePosition();
+        slider.focus();
+    });
+}
+function isCaptchaErrorBody(error) {
+    const code = String(error.bodyJson?.code ?? "").toLowerCase();
+    const message = String(error.bodyJson?.message ?? "").toLowerCase();
+    const body = error.body.toLowerCase();
+    return code.includes("captcha")
+        || code.includes("verify")
+        || message.includes("captcha")
+        || message.includes("验证")
+        || body.includes("captcha")
+        || body.includes("验证");
+}
+function resolveCaptchaDialogTheme(captcha, theme) {
+    const localeText = getCaptchaLocaleText();
+    return {
+        zIndex: theme?.zIndex ?? 9999,
+        hasCustomWidth: theme?.width != null,
+        width: theme?.width ?? getDefaultCaptchaDialogWidth(captcha),
+        title: theme?.title ?? localeText.title,
+        subtitle: theme?.subtitle ?? localeText.subtitle,
+        cancelText: theme?.cancelText ?? localeText.cancelText,
+        sliderText: theme?.sliderText ?? localeText.sliderText,
+        retryText: theme?.retryText ?? localeText.retryText,
+    };
+}
+function createCaptchaDialogElements(captcha, theme) {
+    const host = createStyledElement("div", {
+        position: "fixed",
+        inset: "0",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        background: "rgba(0, 0, 0, 0.4)",
+        zIndex: String(theme.zIndex),
+    });
+    const sliderClassName = "talizen-captcha-slider";
+    const sliderStyle = createCaptchaSliderStyle(sliderClassName);
+    const panel = createStyledElement("div", {
+        width: `${theme.width}px`,
+        maxWidth: "calc(100vw - 32px)",
+        background: "#ffffff",
+        borderRadius: "18px",
+        padding: "16px",
+        boxSizing: "border-box",
+        boxShadow: "0 24px 60px rgba(15,23,42,0.24)",
+        color: "#111827",
+    });
+    const title = createStyledElement("div", {
+        fontSize: "18px",
+        lineHeight: "26px",
+        fontWeight: "700",
+        marginBottom: "4px",
+    }, theme.title);
+    const subtitle = createStyledElement("div", {
+        fontSize: "14px",
+        lineHeight: "22px",
+        fontWeight: "600",
+        color: "#6b7280",
+        marginBottom: "12px",
+    }, theme.subtitle);
+    const stage = createCaptchaStage(captcha);
+    const sliderLabel = createStyledElement("div", {
+        fontSize: "14px",
+        lineHeight: "20px",
+        fontWeight: "600",
+        color: "#6b7280",
+        marginBottom: "8px",
+    }, theme.sliderText);
+    const slider = createCaptchaSlider(captcha, sliderClassName);
+    const errorText = createStyledElement("div", {
+        display: "none",
+        flex: "1",
+        fontSize: "13px",
+        lineHeight: "20px",
+        fontWeight: "500",
+        color: "#ef4444",
+    });
+    const actions = createStyledElement("div", {
+        display: "flex",
+        alignItems: "center",
+        gap: "12px",
+        justifyContent: "flex-start",
+        marginTop: "8px",
+    });
+    const cancelButton = createStyledElement("button", {
+        padding: "10px 18px",
+        border: "1px solid #e5e7eb",
+        background: "#ffffff",
+        borderRadius: "12px",
+        boxShadow: "0 1px 2px rgba(15,23,42,0.08)",
+        color: "#111827",
+        fontSize: "15px",
+        lineHeight: "20px",
+        fontWeight: "600",
+        cursor: "pointer",
+        marginLeft: "auto",
+    }, theme.cancelText);
+    cancelButton.type = "button";
+    actions.append(errorText, cancelButton);
+    panel.append(title, subtitle, stage.host, sliderLabel, slider, actions);
+    host.append(sliderStyle, panel);
+    return {
+        baseImage: stage.baseImage,
+        host,
+        panel,
+        stage: stage.host,
+        tile: stage.tile,
+        slider,
+        errorText,
+        cancelButton,
+    };
+}
+function createCaptchaStage(captcha) {
+    const host = createStyledElement("div", {
+        position: "relative",
+        width: `${captcha.width}px`,
+        height: `${captcha.height}px`,
+        maxWidth: "100%",
+        margin: "0 0 12px",
+        borderRadius: "12px",
+        overflow: "hidden",
+        background: "#f5f5f5",
+    });
+    const baseImage = createStyledElement("img", {
+        width: "100%",
+        height: "100%",
+        objectFit: "cover",
+    });
+    baseImage.src = captcha.master_img;
+    baseImage.draggable = false;
+    const tile = createStyledElement("img", {
+        position: "absolute",
+        top: `${captcha.tile_y}px`,
+        left: "0px",
+        width: `${captcha.tile_width}px`,
+        height: `${captcha.tile_height}px`,
+        pointerEvents: "none",
+    });
+    tile.src = captcha.tile_img;
+    tile.draggable = false;
+    host.append(baseImage, tile);
+    return { baseImage, host, tile };
+}
+function createCaptchaSlider(captcha, className) {
+    const slider = createStyledElement("input", {
+        width: "100%",
+        display: "block",
+        margin: "0",
+    });
+    slider.type = "range";
+    slider.className = className;
+    slider.min = "0";
+    slider.max = String(Math.max(0, captcha.width - captcha.tile_width));
+    slider.value = "0";
+    return slider;
+}
+function createCaptchaSliderStyle(className) {
+    const style = document.createElement("style");
+    style.textContent = `
+    .${className} {
+      appearance: none;
+      -webkit-appearance: none;
+      height: 40px;
+      background: transparent;
+      cursor: pointer;
+    }
+    .${className}:focus {
+      outline: none;
+    }
+    .${className}::-webkit-slider-runnable-track {
+      height: 12px;
+      border: 1px solid #d1d5db;
+      border-radius: 999px;
+      background: #f9fafb;
+      box-shadow: inset 0 1px 2px rgba(15,23,42,0.08);
+    }
+    .${className}::-webkit-slider-thumb {
+      -webkit-appearance: none;
+      width: 30px;
+      height: 30px;
+      margin-top: -10px;
+      border: 3px solid #ffffff;
+      border-radius: 999px;
+      background: #1677ff;
+      box-shadow: 0 4px 12px rgba(22,119,255,0.35);
+    }
+    .${className}::-moz-range-track {
+      height: 12px;
+      border: 1px solid #d1d5db;
+      border-radius: 999px;
+      background: #f9fafb;
+      box-shadow: inset 0 1px 2px rgba(15,23,42,0.08);
+    }
+    .${className}::-moz-range-thumb {
+      width: 24px;
+      height: 24px;
+      border: 3px solid #ffffff;
+      border-radius: 999px;
+      background: #1677ff;
+      box-shadow: 0 4px 12px rgba(22,119,255,0.35);
+    }
+    .${className}:disabled {
+      cursor: wait;
+      opacity: 0.72;
+    }
+  `;
+    return style;
+}
+function createStyledElement(tagName, styles, text) {
+    const element = document.createElement(tagName);
+    Object.assign(element.style, styles);
+    if (text != null) {
+        element.textContent = text;
+    }
+    return element;
+}
+function updateCaptchaDialogCaptcha(elements, captcha, theme) {
+    if (!theme.hasCustomWidth) {
+        elements.panel.style.width = `${getDefaultCaptchaDialogWidth(captcha)}px`;
+    }
+    elements.stage.style.width = `${captcha.width}px`;
+    elements.stage.style.height = `${captcha.height}px`;
+    elements.baseImage.src = captcha.master_img;
+    elements.tile.src = captcha.tile_img;
+    elements.tile.style.top = `${captcha.tile_y}px`;
+    elements.tile.style.left = "0px";
+    elements.tile.style.width = `${captcha.tile_width}px`;
+    elements.tile.style.height = `${captcha.tile_height}px`;
+    elements.slider.max = String(Math.max(0, captcha.width - captcha.tile_width));
+    elements.slider.value = "0";
+}
+function getDefaultCaptchaDialogWidth(captcha) {
+    return Math.max(captcha.width + 32, 320);
+}
+function setCaptchaDialogDisabled(elements, disabled) {
+    elements.slider.disabled = disabled;
+}
+function setCaptchaErrorText(element, message = "") {
+    element.textContent = message;
+    element.style.display = message === "" ? "none" : "block";
+}
+function getSliderValue(slider) {
+    return clampNumber(toSafeNumber(slider.value), toSafeNumber(slider.min), toSafeNumber(slider.max));
+}
+function toSafeNumber(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function clampNumber(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function getCaptchaLocaleText() {
+    const languages = typeof navigator === "undefined"
+        ? []
+        : [navigator.language, ...(navigator.languages ?? [])]
+            .filter((item) => typeof item === "string" && item !== "")
+            .map((item) => item.toLowerCase());
+    for (const language of languages) {
+        if (language.startsWith("en")) {
+            return {
+                title: "Complete security verification",
+                subtitle: "Drag the slider to move the puzzle into place",
+                cancelText: "Cancel",
+                sliderText: "Drag the slider to complete the puzzle",
+                retryText: "Verification failed, please try again.",
+            };
+        }
+        if (language.startsWith("zh")) {
+            return {
+                title: "请完成安全验证",
+                subtitle: "拖动滑块，将拼图移动到正确位置",
+                cancelText: "取消",
+                sliderText: "向右拖动滑块完成拼图",
+                retryText: "验证失败，请重试。",
+            };
+        }
+    }
+    return {
+        title: "Complete security verification",
+        subtitle: "Drag the slider to move the puzzle into place",
+        cancelText: "Cancel",
+        sliderText: "Drag the slider to complete the puzzle",
+        retryText: "Verification failed, please try again.",
+    };
+}
+function createAbortError() {
+    if (typeof DOMException === "function") {
+        return new DOMException("The operation was aborted.", "AbortError");
+    }
+    const error = new Error("The operation was aborted.");
+    error.name = "AbortError";
+    return error;
+}

package/core.d.ts

@@ -21,10 +21,29 @@ export interface TalizenClientConfig {
 export interface TalizenRequestOptions extends TalizenClientConfig {
     signal?: AbortSignal;
 }
+export interface TalizenErrorBody {
+    code?: number | string;
+    message?: string;
+}
 export declare function setTalizenConfig(config: TalizenClientConfig): void;
 export declare function getTalizenConfig(): TalizenClientConfig;
 declare global {
     var TalizenConfig: TalizenClientConfig | undefined;
 }
 export declare function resolveTalizenConfig(config?: TalizenRequestOptions): Required<Pick<TalizenClientConfig, "baseUrl" | "fetch">> & TalizenRequestOptions;
+export declare class TalizenHttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    readonly bodyJson: TalizenErrorBody | undefined;
+    readonly method: string | undefined;
+    readonly url: string | undefined;
+    constructor(status: number, statusText: string, body: string, bodyJson?: TalizenErrorBody, request?: TalizenErrorRequest);
+}
+export interface TalizenErrorRequest {
+    method?: string;
+    url?: string;
+}
 export declare function requestJson<T>(path: string, init?: RequestInit, config?: TalizenRequestOptions): Promise<T>;
+export declare function stripUrlQuery(url: string): string;
+export declare function normalizeRequestMethod(method: string | undefined): string;

package/core.js

@@ -33,6 +33,24 @@ function buildTalizenUrl(path, config) {
     const resolved = resolveTalizenConfig(config);
     return joinUrl(resolved.baseUrl, path);
 }
+export class TalizenHttpError extends Error {
+    status;
+    statusText;
+    body;
+    bodyJson;
+    method;
+    url;
+    constructor(status, statusText, body, bodyJson, request) {
+        super(formatTalizenRequestErrorMessage(status, statusText, body, request));
+        this.name = "TalizenHttpError";
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.bodyJson = bodyJson;
+        this.method = request?.method;
+        this.url = request?.url;
+    }
+}
 export async function requestJson(path, init, config) {
     const resolved = resolveTalizenConfig(config);
     const headers = new Headers(resolved.headers ?? {});
@@ -44,14 +62,20 @@ export async function requestJson(path, init, config) {
     if (init?.body != null && !headers.has("content-type")) {
         headers.set("content-type", "application/json");
     }
-    const response = await resolved.fetch(buildTalizenUrl(path, resolved), {
+    const requestUrl = buildTalizenUrl(path, resolved);
+    const request = {
+        method: normalizeRequestMethod(init?.method),
+        url: stripUrlQuery(requestUrl),
+    };
+    const response = await resolved.fetch(requestUrl, {
         ...init,
         headers,
         signal: resolved.signal,
     });
     if (!response.ok) {
         const text = await response.text();
-        throw new Error(`Talizen request failed: ${response.status} ${response.statusText} ${text}`.trim());
+        const bodyJson = parseTalizenErrorBody(text);
+        throw new TalizenHttpError(response.status, response.statusText, text, bodyJson, request);
     }
     const text = await response.text();
     if (text === "") {
@@ -59,6 +83,23 @@ export async function requestJson(path, init, config) {
     }
     return JSON.parse(text);
 }
+export function stripUrlQuery(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.search = "";
+        return parsed.toString();
+    }
+    catch {
+        return url.split("?")[0] ?? url;
+    }
+}
+export function normalizeRequestMethod(method) {
+    return (method ?? "GET").toUpperCase();
+}
+function formatTalizenRequestErrorMessage(status, statusText, body, request) {
+    const requestText = [request?.method, request?.url].filter(Boolean).join(" ");
+    return `Talizen request failed: ${requestText} ${status} ${statusText} ${body}`.replace(/\s+/g, " ").trim();
+}
 function getDefaultBaseUrl() {
     if (typeof window !== "undefined" && window.location?.origin) {
         return window.location.origin;
@@ -71,3 +112,29 @@ function getDefaultFetch() {
     }
     throw new Error("Talizen fetch implementation is required in the current runtime.");
 }
+function parseTalizenErrorBody(body) {
+    if (body === "") {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(body);
+        if (isTalizenErrorBody(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function isTalizenErrorBody(value) {
+    if (typeof value !== "object" || value == null) {
+        return false;
+    }
+    const record = value;
+    const code = record.code;
+    const message = record.message;
+    const isCodeValid = code === undefined || typeof code === "number" || typeof code === "string";
+    const isMessageValid = message === undefined || typeof message === "string";
+    return isCodeValid && isMessageValid;
+}

package/form.d.ts

@@ -1,6 +1,19 @@
+import { type CaptchaChallenge, type CaptchaUiTheme } from "./captcha-ui.js";
 import { type TalizenRequestOptions } from "./core.js";
+export type { CaptchaChallenge as FormCaptcha, CaptchaUiTheme as FormCaptchaUiTheme } from "./captcha-ui.js";
 export interface FormRecord {
     readonly __formKey?: string;
     [key: string]: unknown;
 }
-export declare function submitForm<T extends FormRecord>(keyOrToken: T["__formKey"] | string, payload: T, options?: TalizenRequestOptions): Promise<"ok">;
+export interface SubmitFormOptions extends TalizenRequestOptions {
+    captchaToken?: string;
+    captchaAnswer?: string;
+    captchaX?: number;
+    captchaY?: number;
+}
+export interface SubmitFormWithCaptchaOptions extends SubmitFormOptions {
+    shouldTriggerCaptcha?: (error: unknown) => boolean;
+    captchaUiTheme?: CaptchaUiTheme;
+}
+export declare function submitForm<T extends FormRecord>(keyOrToken: T["__formKey"] | string, payload: T, options?: SubmitFormWithCaptchaOptions): Promise<"ok">;
+export declare function getFormCaptcha(keyOrToken: string, options?: TalizenRequestOptions): Promise<CaptchaChallenge>;

package/form.js

@@ -1,14 +1,58 @@
-import { requestJson, resolveTalizenConfig } from "./core.js";
+import { buildCaptchaAnswer, runCaptchaVerification, shouldRetryCaptchaSubmit, } from "./captcha-ui.js";
+import { normalizeRequestMethod, requestJson, resolveTalizenConfig, stripUrlQuery, TalizenHttpError, } from "./core.js";
 export async function submitForm(keyOrToken, payload, options) {
     const formKey = getFormKey(keyOrToken);
     const data = await replaceFiles(formKey, payload, "", options);
+    try {
+        return await submitFormRequest(formKey, data, options);
+    }
+    catch (error) {
+        if (!shouldShowCaptcha(error, options)) {
+            throw error;
+        }
+    }
+    return runCaptchaVerification({
+        initialCaptcha: await getFormCaptcha(formKey, options),
+        signal: options?.signal,
+        theme: options?.captchaUiTheme,
+        refreshCaptcha: () => getFormCaptcha(formKey, options),
+        shouldRetry: (error) => shouldRetryCaptchaSubmit(error, (item) => shouldShowCaptcha(item, options)),
+        verify: (result) => submitFormRequest(formKey, data, {
+            ...options,
+            captchaToken: result.token,
+            captchaAnswer: buildCaptchaAnswer(result.x, result.y),
+            captchaX: result.x,
+            captchaY: result.y,
+        }),
+    });
+}
+function submitFormRequest(formKey, data, options) {
     return requestJson(`/form/${formKey}/submit`, {
         method: "POST",
         body: JSON.stringify({
             data,
+            captcha_token: options?.captchaToken,
+            captcha_answer: options?.captchaAnswer,
+            captcha_x: options?.captchaX,
+            captcha_y: options?.captchaY,
         }),
     }, options);
 }
+export async function getFormCaptcha(keyOrToken, options) {
+    const formKey = getFormKey(keyOrToken);
+    return requestJson(`/form/${formKey}/captcha`, {
+        method: "GET",
+    }, options);
+}
+function shouldShowCaptcha(error, options) {
+    return (options?.shouldTriggerCaptcha ?? isCaptchaRequiredError)(error);
+}
+function isCaptchaRequiredError(error) {
+    return error instanceof TalizenHttpError && isCaptchaRequiredCode(error.bodyJson?.code);
+}
+function isCaptchaRequiredCode(code) {
+    return code === 428 || code === "428";
+}
 function getFormKey(keyOrToken) {
     if (keyOrToken == null || keyOrToken === "") {
         throw new Error("Talizen form key is required.");
@@ -72,6 +116,10 @@ async function uploadToSignedUrl(target, file, fieldKey, options) {
     const resolved = resolveTalizenConfig(options);
     const headers = new Headers();
     const body = file;
+    const request = {
+        method: normalizeRequestMethod("PUT"),
+        url: stripUrlQuery(target.uploadUrl),
+    };
     if (file.type) {
         headers.set("content-type", file.type);
     }
@@ -83,7 +131,7 @@ async function uploadToSignedUrl(target, file, fieldKey, options) {
     });
     if (!response.ok) {
         const text = await response.text();
-        throw new Error(`Talizen file upload failed: ${response.status} ${response.statusText} ${text}`.trim());
+        throw new Error(formatUploadError(request, `${response.status} ${response.statusText} ${text}`));
     }
 }
 function uploadWithXhr(target, file, fieldKey, options) {
@@ -91,6 +139,10 @@ function uploadWithXhr(target, file, fieldKey, options) {
         const xhr = new XMLHttpRequest();
         const signal = options.signal;
         const body = file;
+        const request = {
+            method: normalizeRequestMethod("PUT"),
+            url: stripUrlQuery(target.uploadUrl ?? ""),
+        };
         xhr.open("PUT", target.uploadUrl ?? "");
         if (file.type) {
             xhr.setRequestHeader("content-type", file.type);
@@ -106,11 +158,11 @@ function uploadWithXhr(target, file, fieldKey, options) {
                 resolve();
                 return;
             }
-            reject(new Error(`Talizen file upload failed: ${xhr.status} ${xhr.statusText} ${xhr.responseText}`.trim()));
+            reject(new Error(formatUploadError(request, `${xhr.status} ${xhr.statusText} ${xhr.responseText}`)));
         };
         xhr.onerror = () => {
             cleanup();
-            reject(new Error("Talizen file upload failed: network error"));
+            reject(new Error(formatUploadError(request, "network error")));
         };
         xhr.onabort = () => {
             cleanup();
@@ -122,6 +174,9 @@ function uploadWithXhr(target, file, fieldKey, options) {
         xhr.send(body);
     });
 }
+function formatUploadError(request, detail) {
+    return `Talizen file upload failed: ${request.method} ${request.url} ${detail}`.replace(/\s+/g, " ").trim();
+}
 async function sha256(file) {
     const subtle = globalThis.crypto?.subtle;
     if (subtle == null) {

package/i18n.d.ts

@@ -0,0 +1,55 @@
+import * as React from "react";
+/**
+ * 当前语言运行时信息。由 Talizen 渲染引擎注入到 `globalThis.__TALIZEN_I18N__`
+ * （SSR 与浏览器端注入同一份，避免 hydration 不一致）。站点未开启多语言时为空。
+ */
+export interface LocaleRuntime {
+    /** 当前生效语言；站点未配置多语言时为 ""。 */
+    locale: string;
+    /** 站点配置的全部语言。 */
+    locales: string[];
+    /** 默认语言（其 URL 无前缀）。 */
+    defaultLocale: string;
+}
+declare global {
+    var __TALIZEN_I18N__: Partial<LocaleRuntime> | undefined;
+}
+/**
+ * 读取当前语言运行时信息（当前语言 / 全部语言 / 默认语言）。SSR 与客户端返回一致。
+ * 站点未开启多语言时 `locale === ""`。
+ *
+ * ```tsx
+ * const { locale, locales, defaultLocale } = useLocale()
+ * ```
+ */
+export declare function useLocale(): LocaleRuntime;
+/**
+ * 给站内路径加语言前缀（默认语言不加前缀）。不传 `locale` 时使用当前语言。
+ * 站外链接（协议 / 协议相对 URL）与页内锚点（`#...`）原样返回。
+ *
+ * ```ts
+ * localizedPath("/blog")        // zh 页面 → "/zh/blog"；默认语言 → "/blog"
+ * localizedPath("/about", "ja") // → "/ja/about"
+ * ```
+ */
+export declare function localizedPath(path: string, locale?: string): string;
+/** 记住用户显式语言选择的 Cookie 名（检测优先级：Cookie > Accept-Language > 默认）。 */
+export declare const LOCALE_COOKIE = "CREGHT_LOCALE";
+export type LinkProps = React.AnchorHTMLAttributes<HTMLAnchorElement> & {
+    href: string;
+    /**
+     * 指定则表示「切换到该语言」：`href` 用该语言前缀，并在点击时写 `CREGHT_LOCALE`
+     * Cookie 记住选择。不传则沿用当前语言（普通站内链接）。
+     */
+    locale?: string;
+};
+/**
+ * 语言感知的站内链接，替代裸 `<a>`：自动给 `href` 补当前语言前缀（默认语言不补）。
+ * 传 `locale` 表示语言切换（用该语言前缀，且点击时写 `CREGHT_LOCALE` 记住选择）。
+ *
+ * ```tsx
+ * <Link href="/blog">Blog</Link>            // 跟随当前语言：zh 页面 → /zh/blog
+ * <Link href="/" locale="ja">日本語</Link>  // 切到日文并记住
+ * ```
+ */
+export declare function Link(props: LinkProps): React.ReactElement;

package/i18n.js

@@ -0,0 +1,62 @@
+import * as React from "react";
+function readLocaleRuntime() {
+    const d = (typeof globalThis !== "undefined" ? globalThis.__TALIZEN_I18N__ : undefined) ?? {};
+    const locales = Array.isArray(d.locales) ? d.locales.filter((l) => typeof l === "string") : [];
+    return {
+        locale: typeof d.locale === "string" ? d.locale : "",
+        locales,
+        defaultLocale: typeof d.defaultLocale === "string" ? d.defaultLocale : (locales[0] ?? ""),
+    };
+}
+/**
+ * 读取当前语言运行时信息（当前语言 / 全部语言 / 默认语言）。SSR 与客户端返回一致。
+ * 站点未开启多语言时 `locale === ""`。
+ *
+ * ```tsx
+ * const { locale, locales, defaultLocale } = useLocale()
+ * ```
+ */
+export function useLocale() {
+    return readLocaleRuntime();
+}
+/**
+ * 给站内路径加语言前缀（默认语言不加前缀）。不传 `locale` 时使用当前语言。
+ * 站外链接（协议 / 协议相对 URL）与页内锚点（`#...`）原样返回。
+ *
+ * ```ts
+ * localizedPath("/blog")        // zh 页面 → "/zh/blog"；默认语言 → "/blog"
+ * localizedPath("/about", "ja") // → "/ja/about"
+ * ```
+ */
+export function localizedPath(path, locale) {
+    if (/^([a-z][a-z0-9+.-]*:)?\/\//i.test(path) || path.startsWith("#"))
+        return path;
+    const rt = readLocaleRuntime();
+    const target = locale ?? rt.locale;
+    if (!target || target === rt.defaultLocale)
+        return path;
+    const p = path.startsWith("/") ? path : `/${path}`;
+    return p === "/" ? `/${target}` : `/${target}${p}`;
+}
+/** 记住用户显式语言选择的 Cookie 名（检测优先级：Cookie > Accept-Language > 默认）。 */
+export const LOCALE_COOKIE = "CREGHT_LOCALE";
+/**
+ * 语言感知的站内链接，替代裸 `<a>`：自动给 `href` 补当前语言前缀（默认语言不补）。
+ * 传 `locale` 表示语言切换（用该语言前缀，且点击时写 `CREGHT_LOCALE` 记住选择）。
+ *
+ * ```tsx
+ * <Link href="/blog">Blog</Link>            // 跟随当前语言：zh 页面 → /zh/blog
+ * <Link href="/" locale="ja">日本語</Link>  // 切到日文并记住
+ * ```
+ */
+export function Link(props) {
+    const { href, locale, onClick, ...rest } = props;
+    const finalHref = localizedPath(href, locale);
+    const handleClick = (event) => {
+        if (locale && typeof document !== "undefined") {
+            document.cookie = `${LOCALE_COOKIE}=${encodeURIComponent(locale)}; path=/; max-age=31536000; samesite=lax`;
+        }
+        onClick?.(event);
+    };
+    return React.createElement("a", { ...rest, href: finalHref, onClick: handleClick });
+}

package/index.d.ts

@@ -1,6 +1,8 @@
 export * from "./core.js";
 export * from "./cms.js";
+export * from "./captcha-ui.js";
 export * from "./form.js";
+export * from "./i18n.js";
 type OneOrMany<T> = T | Array<T>;
 export interface MetadataTitle {
     default?: string;
@@ -71,3 +73,29 @@ export interface Metadata {
     openGraph?: OpenGraphMetadata | null;
     icons?: MetadataIcons | null;
 }
+/**
+ * A single site-level redirect rule, aligned with Next.js `redirects()` semantics.
+ *
+ * Declare rules in the `redirects` array of `talizen.config.ts`. A matching
+ * request is redirected before the page renders, so redirects take precedence
+ * over pages and `/public` files.
+ */
+export interface Redirect {
+    /**
+     * Source path to match. Supports exact matches (`/old-page`) and a trailing
+     * wildcard segment (`/blog/*`).
+     */
+    source: string;
+    /**
+     * Redirect target. May be an internal path (`/new-page`), a wildcard
+     * backreference (`/posts/*`), an absolute URL (`https://example.com/x`), or a
+     * protocol-relative URL (`//example.com/x`). Internal paths keep the original
+     * query string.
+     */
+    destination: string;
+    /**
+     * `true` issues a 308 permanent redirect (best for SEO); `false` issues a 307
+     * temporary redirect.
+     */
+    permanent: boolean;
+}

package/index.js

@@ -1,3 +1,5 @@
 export * from "./core.js";
 export * from "./cms.js";
+export * from "./captcha-ui.js";
 export * from "./form.js";
+export * from "./i18n.js";

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "talizen",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Talizen frontend SDK types for cms, form and core.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/talizen/talizen.git"
+  },
   "sideEffects": false,
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -20,9 +24,17 @@
       "types": "./cms.d.ts",
       "import": "./cms.js"
     },
+    "./captcha-ui": {
+      "types": "./captcha-ui.d.ts",
+      "import": "./captcha-ui.js"
+    },
     "./form": {
       "types": "./form.d.ts",
       "import": "./form.js"
+    },
+    "./i18n": {
+      "types": "./i18n.d.ts",
+      "import": "./i18n.js"
     }
   }
 }