@plasius/ai 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -20,6 +20,22 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
+## [1.0.4] - 2026-02-21
+
+- **Added**
+  - Add a typed chatbot API client (`chatWithAI`, `getChatbotUsage`) for `/ai/chatbot`.
+  - Add `ChatbotApiError` with HTTP status/code/usage metadata for auth and quota handling.
+  - Add CSRF bootstrap support (GET-first cookie hydration, then `x-csrf-token` on POST).
+
+- **Changed**
+  - Export chatbot client utilities from the package root.
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [1.0.3] - 2026-02-12
 
 - **Added**
@@ -54,7 +70,7 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 
 ---
 
-[Unreleased]: https://github.com/Plasius-LTD/ai/compare/v1.0.3...HEAD
+[Unreleased]: https://github.com/Plasius-LTD/ai/compare/v1.0.4...HEAD
 
 ## [1.0.0] - 2026-02-11
 
@@ -70,3 +86,4 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 [1.0.3]: https://github.com/Plasius-LTD/ai/releases/tag/v1.0.3
+[1.0.4]: https://github.com/Plasius-LTD/ai/releases/tag/v1.0.4

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./platform/index.js";
+export * from "./lib/chatWithAI.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -1 +1,2 @@
 export * from "./platform/index.js";
+export * from "./lib/chatWithAI.js";

package/dist/lib/chatWithAI.d.ts

@@ -1,2 +1,42 @@
-export {};
+export type ChatRole = "system" | "user" | "assistant";
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+export interface ChatWithAIRequest {
+    message: string;
+    history?: ChatMessage[];
+    systemPrompt?: string;
+}
+export interface ChatbotUsage {
+    limit: number;
+    used: number;
+    remaining: number;
+    exhausted: boolean;
+}
+export interface ChatbotResponse {
+    reply: string;
+    model: string;
+    usage: ChatbotUsage;
+}
+export interface ChatbotUsageResponse {
+    usage: ChatbotUsage;
+}
+export interface ChatWithAIClientOptions {
+    endpoint?: string;
+    credentials?: RequestCredentials;
+    fetchFn?: typeof fetch;
+    authHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    csrfCookieName?: string;
+    csrfHeaderName?: string;
+    bootstrapCsrf?: boolean;
+}
+export declare class ChatbotApiError extends Error {
+    status: number;
+    code?: string;
+    usage?: ChatbotUsage;
+    constructor(status: number, message: string, code?: string, usage?: ChatbotUsage);
+}
+export declare function getChatbotUsage(options?: ChatWithAIClientOptions): Promise<ChatbotUsageResponse>;
+export declare function chatWithAI(request: ChatWithAIRequest, options?: ChatWithAIClientOptions): Promise<ChatbotResponse>;
 //# sourceMappingURL=chatWithAI.d.ts.map

package/dist/lib/chatWithAI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chatWithAI.d.ts","sourceRoot":"","sources":["../../src/lib/chatWithAI.ts"],"names":[],"mappings":""}
+{"version":3,"file":"chatWithAI.d.ts","sourceRoot":"","sources":["../../src/lib/chatWithAI.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,WAAW,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAYD,qBAAa,eAAgB,SAAQ,KAAK;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,YAAY,CAAC;gBAET,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY;CAOjF;AAuID,wBAAsB,eAAe,CACnC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,eAAe,CAAC,CAoC1B"}

package/dist/lib/chatWithAI.js

@@ -1 +1,170 @@
-export {};
+const DEFAULT_ENDPOINT = "/ai/chatbot";
+const DEFAULT_CSRF_COOKIE_NAME = "csrf-token";
+const DEFAULT_CSRF_HEADER_NAME = "x-csrf-token";
+export class ChatbotApiError extends Error {
+    constructor(status, message, code, usage) {
+        super(message);
+        this.name = "ChatbotApiError";
+        this.status = status;
+        this.code = code;
+        this.usage = usage;
+    }
+}
+function resolveFetch(fetchFn) {
+    const resolved = fetchFn ?? (typeof fetch !== "undefined" ? fetch : undefined);
+    if (!resolved) {
+        throw new Error("No fetch implementation available for chatWithAI.");
+    }
+    return resolved;
+}
+async function resolveAuthHeaders(authHeaders) {
+    if (!authHeaders)
+        return undefined;
+    if (typeof authHeaders === "function") {
+        return await authHeaders();
+    }
+    return authHeaders;
+}
+function readCookie(cookieName) {
+    if (typeof document === "undefined" || typeof document.cookie !== "string") {
+        return undefined;
+    }
+    const entries = document.cookie.split(";").map((part) => part.trim());
+    const match = entries.find((entry) => entry.startsWith(`${cookieName}=`));
+    if (!match)
+        return undefined;
+    const [, value = ""] = match.split("=");
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+async function parseResponseBody(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return await response.json();
+    }
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function ensureCsrfToken(fetcher, endpoint, options, headers) {
+    const csrfCookieName = options.csrfCookieName ?? DEFAULT_CSRF_COOKIE_NAME;
+    const existingToken = readCookie(csrfCookieName);
+    if (existingToken || options.bootstrapCsrf === false) {
+        return existingToken;
+    }
+    await fetcher(endpoint, {
+        method: "GET",
+        credentials: options.credentials ?? "include",
+        headers,
+    });
+    return readCookie(csrfCookieName);
+}
+function normalizeError(status, body) {
+    const payload = body && typeof body === "object" ? body : undefined;
+    const message = payload?.message ||
+        (status === 401
+            ? "You must be signed in to use chatbot."
+            : "Chatbot request failed.");
+    return new ChatbotApiError(status, message, payload?.error, payload?.usage);
+}
+function buildUsage(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const maybe = payload;
+    const limit = maybe.limit;
+    const used = maybe.used;
+    const remaining = maybe.remaining;
+    const exhausted = maybe.exhausted;
+    if (typeof limit !== "number" ||
+        typeof used !== "number" ||
+        typeof remaining !== "number" ||
+        typeof exhausted !== "boolean") {
+        return undefined;
+    }
+    return { limit, used, remaining, exhausted };
+}
+function mapToChatbotResponse(body) {
+    if (!body || typeof body !== "object") {
+        throw new Error("Invalid chatbot response payload.");
+    }
+    const payload = body;
+    const reply = payload.reply;
+    const model = payload.model;
+    const usage = buildUsage(payload.usage);
+    if (typeof reply !== "string" || typeof model !== "string" || !usage) {
+        throw new Error("Invalid chatbot response payload.");
+    }
+    return { reply, model, usage };
+}
+function mapToChatbotUsageResponse(body) {
+    if (!body || typeof body !== "object") {
+        throw new Error("Invalid chatbot usage payload.");
+    }
+    const payload = body;
+    const usage = buildUsage(payload.usage);
+    if (!usage) {
+        throw new Error("Invalid chatbot usage payload.");
+    }
+    return { usage };
+}
+export async function getChatbotUsage(options = {}) {
+    const fetcher = resolveFetch(options.fetchFn);
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    const authHeaders = await resolveAuthHeaders(options.authHeaders);
+    const response = await fetcher(endpoint, {
+        method: "GET",
+        credentials: options.credentials ?? "include",
+        headers: {
+            Accept: "application/json",
+            ...(authHeaders ?? {}),
+        },
+    });
+    const body = await parseResponseBody(response);
+    if (!response.ok) {
+        throw normalizeError(response.status, body);
+    }
+    return mapToChatbotUsageResponse(body);
+}
+export async function chatWithAI(request, options = {}) {
+    const fetcher = resolveFetch(options.fetchFn);
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    const authHeaders = await resolveAuthHeaders(options.authHeaders);
+    const baseHeaders = {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...(authHeaders ?? {}),
+    };
+    const csrfToken = await ensureCsrfToken(fetcher, endpoint, options, baseHeaders);
+    const csrfHeaderName = options.csrfHeaderName ?? DEFAULT_CSRF_HEADER_NAME;
+    const headers = csrfToken
+        ? {
+            ...baseHeaders,
+            [csrfHeaderName]: csrfToken,
+        }
+        : baseHeaders;
+    const response = await fetcher(endpoint, {
+        method: "POST",
+        credentials: options.credentials ?? "include",
+        headers,
+        body: JSON.stringify({
+            message: request.message,
+            history: request.history ?? [],
+            systemPrompt: request.systemPrompt,
+        }),
+    });
+    const body = await parseResponseBody(response);
+    if (!response.ok) {
+        throw normalizeError(response.status, body);
+    }
+    return mapToChatbotResponse(body);
+}

package/dist-cjs/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./platform/index.js";
+export * from "./lib/chatWithAI.js";
 //# sourceMappingURL=index.d.ts.map

package/dist-cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/dist-cjs/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./platform/index.js"), exports);
+__exportStar(require("./lib/chatWithAI.js"), exports);

package/dist-cjs/lib/chatWithAI.d.ts

@@ -1 +1,42 @@
+export type ChatRole = "system" | "user" | "assistant";
+export interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+export interface ChatWithAIRequest {
+    message: string;
+    history?: ChatMessage[];
+    systemPrompt?: string;
+}
+export interface ChatbotUsage {
+    limit: number;
+    used: number;
+    remaining: number;
+    exhausted: boolean;
+}
+export interface ChatbotResponse {
+    reply: string;
+    model: string;
+    usage: ChatbotUsage;
+}
+export interface ChatbotUsageResponse {
+    usage: ChatbotUsage;
+}
+export interface ChatWithAIClientOptions {
+    endpoint?: string;
+    credentials?: RequestCredentials;
+    fetchFn?: typeof fetch;
+    authHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    csrfCookieName?: string;
+    csrfHeaderName?: string;
+    bootstrapCsrf?: boolean;
+}
+export declare class ChatbotApiError extends Error {
+    status: number;
+    code?: string;
+    usage?: ChatbotUsage;
+    constructor(status: number, message: string, code?: string, usage?: ChatbotUsage);
+}
+export declare function getChatbotUsage(options?: ChatWithAIClientOptions): Promise<ChatbotUsageResponse>;
+export declare function chatWithAI(request: ChatWithAIRequest, options?: ChatWithAIClientOptions): Promise<ChatbotResponse>;
 //# sourceMappingURL=chatWithAI.d.ts.map

package/dist-cjs/lib/chatWithAI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chatWithAI.d.ts","sourceRoot":"","sources":["../../src/lib/chatWithAI.ts"],"names":[],"mappings":""}
+{"version":3,"file":"chatWithAI.d.ts","sourceRoot":"","sources":["../../src/lib/chatWithAI.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,WAAW,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAYD,qBAAa,eAAgB,SAAQ,KAAK;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,YAAY,CAAC;gBAET,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY;CAOjF;AAuID,wBAAsB,eAAe,CACnC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,eAAe,CAAC,CAoC1B"}

package/dist-cjs/lib/chatWithAI.js

@@ -1 +1,176 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatbotApiError = void 0;
+exports.getChatbotUsage = getChatbotUsage;
+exports.chatWithAI = chatWithAI;
+const DEFAULT_ENDPOINT = "/ai/chatbot";
+const DEFAULT_CSRF_COOKIE_NAME = "csrf-token";
+const DEFAULT_CSRF_HEADER_NAME = "x-csrf-token";
+class ChatbotApiError extends Error {
+    constructor(status, message, code, usage) {
+        super(message);
+        this.name = "ChatbotApiError";
+        this.status = status;
+        this.code = code;
+        this.usage = usage;
+    }
+}
+exports.ChatbotApiError = ChatbotApiError;
+function resolveFetch(fetchFn) {
+    const resolved = fetchFn ?? (typeof fetch !== "undefined" ? fetch : undefined);
+    if (!resolved) {
+        throw new Error("No fetch implementation available for chatWithAI.");
+    }
+    return resolved;
+}
+async function resolveAuthHeaders(authHeaders) {
+    if (!authHeaders)
+        return undefined;
+    if (typeof authHeaders === "function") {
+        return await authHeaders();
+    }
+    return authHeaders;
+}
+function readCookie(cookieName) {
+    if (typeof document === "undefined" || typeof document.cookie !== "string") {
+        return undefined;
+    }
+    const entries = document.cookie.split(";").map((part) => part.trim());
+    const match = entries.find((entry) => entry.startsWith(`${cookieName}=`));
+    if (!match)
+        return undefined;
+    const [, value = ""] = match.split("=");
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+async function parseResponseBody(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return await response.json();
+    }
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function ensureCsrfToken(fetcher, endpoint, options, headers) {
+    const csrfCookieName = options.csrfCookieName ?? DEFAULT_CSRF_COOKIE_NAME;
+    const existingToken = readCookie(csrfCookieName);
+    if (existingToken || options.bootstrapCsrf === false) {
+        return existingToken;
+    }
+    await fetcher(endpoint, {
+        method: "GET",
+        credentials: options.credentials ?? "include",
+        headers,
+    });
+    return readCookie(csrfCookieName);
+}
+function normalizeError(status, body) {
+    const payload = body && typeof body === "object" ? body : undefined;
+    const message = payload?.message ||
+        (status === 401
+            ? "You must be signed in to use chatbot."
+            : "Chatbot request failed.");
+    return new ChatbotApiError(status, message, payload?.error, payload?.usage);
+}
+function buildUsage(payload) {
+    if (!payload || typeof payload !== "object")
+        return undefined;
+    const maybe = payload;
+    const limit = maybe.limit;
+    const used = maybe.used;
+    const remaining = maybe.remaining;
+    const exhausted = maybe.exhausted;
+    if (typeof limit !== "number" ||
+        typeof used !== "number" ||
+        typeof remaining !== "number" ||
+        typeof exhausted !== "boolean") {
+        return undefined;
+    }
+    return { limit, used, remaining, exhausted };
+}
+function mapToChatbotResponse(body) {
+    if (!body || typeof body !== "object") {
+        throw new Error("Invalid chatbot response payload.");
+    }
+    const payload = body;
+    const reply = payload.reply;
+    const model = payload.model;
+    const usage = buildUsage(payload.usage);
+    if (typeof reply !== "string" || typeof model !== "string" || !usage) {
+        throw new Error("Invalid chatbot response payload.");
+    }
+    return { reply, model, usage };
+}
+function mapToChatbotUsageResponse(body) {
+    if (!body || typeof body !== "object") {
+        throw new Error("Invalid chatbot usage payload.");
+    }
+    const payload = body;
+    const usage = buildUsage(payload.usage);
+    if (!usage) {
+        throw new Error("Invalid chatbot usage payload.");
+    }
+    return { usage };
+}
+async function getChatbotUsage(options = {}) {
+    const fetcher = resolveFetch(options.fetchFn);
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    const authHeaders = await resolveAuthHeaders(options.authHeaders);
+    const response = await fetcher(endpoint, {
+        method: "GET",
+        credentials: options.credentials ?? "include",
+        headers: {
+            Accept: "application/json",
+            ...(authHeaders ?? {}),
+        },
+    });
+    const body = await parseResponseBody(response);
+    if (!response.ok) {
+        throw normalizeError(response.status, body);
+    }
+    return mapToChatbotUsageResponse(body);
+}
+async function chatWithAI(request, options = {}) {
+    const fetcher = resolveFetch(options.fetchFn);
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    const authHeaders = await resolveAuthHeaders(options.authHeaders);
+    const baseHeaders = {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...(authHeaders ?? {}),
+    };
+    const csrfToken = await ensureCsrfToken(fetcher, endpoint, options, baseHeaders);
+    const csrfHeaderName = options.csrfHeaderName ?? DEFAULT_CSRF_HEADER_NAME;
+    const headers = csrfToken
+        ? {
+            ...baseHeaders,
+            [csrfHeaderName]: csrfToken,
+        }
+        : baseHeaders;
+    const response = await fetcher(endpoint, {
+        method: "POST",
+        credentials: options.credentials ?? "include",
+        headers,
+        body: JSON.stringify({
+            message: request.message,
+            history: request.history ?? [],
+            systemPrompt: request.systemPrompt,
+        }),
+    });
+    const body = await parseResponseBody(response);
+    if (!response.ok) {
+        throw normalizeError(response.status, body);
+    }
+    return mapToChatbotResponse(body);
+}

package/docs/adrs/index.md

@@ -0,0 +1,5 @@
+# ADR Index
+
+- [ADR-0001: Standalone @plasius/ai Package Scope](./adr-0001-ai-package-scope.md)
+- [ADR-0002: Public Repository Governance Baseline](./adr-0002-public-repo-governance.md)
+- [ADR-0003: Contracts-First Documentation Baseline](./adr-0003-contracts-first-documentation.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/ai",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Plasius AI functions providing chatbot, text-to-speech, speech-to-text, and AI-generated images and videos",
   "keywords": [
     "chatbot",

package/src/index.ts

@@ -1 +1,2 @@
 export * from "./platform/index.js";
+export * from "./lib/chatWithAI.js";

package/src/lib/chatWithAI.ts

@@ -0,0 +1,260 @@
+export type ChatRole = "system" | "user" | "assistant";
+
+export interface ChatMessage {
+  role: ChatRole;
+  content: string;
+}
+
+export interface ChatWithAIRequest {
+  message: string;
+  history?: ChatMessage[];
+  systemPrompt?: string;
+}
+
+export interface ChatbotUsage {
+  limit: number;
+  used: number;
+  remaining: number;
+  exhausted: boolean;
+}
+
+export interface ChatbotResponse {
+  reply: string;
+  model: string;
+  usage: ChatbotUsage;
+}
+
+export interface ChatbotUsageResponse {
+  usage: ChatbotUsage;
+}
+
+export interface ChatWithAIClientOptions {
+  endpoint?: string;
+  credentials?: RequestCredentials;
+  fetchFn?: typeof fetch;
+  authHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  csrfCookieName?: string;
+  csrfHeaderName?: string;
+  bootstrapCsrf?: boolean;
+}
+
+interface ErrorBody {
+  error?: string;
+  message?: string;
+  usage?: ChatbotUsage;
+}
+
+const DEFAULT_ENDPOINT = "/ai/chatbot";
+const DEFAULT_CSRF_COOKIE_NAME = "csrf-token";
+const DEFAULT_CSRF_HEADER_NAME = "x-csrf-token";
+
+export class ChatbotApiError extends Error {
+  status: number;
+  code?: string;
+  usage?: ChatbotUsage;
+
+  constructor(status: number, message: string, code?: string, usage?: ChatbotUsage) {
+    super(message);
+    this.name = "ChatbotApiError";
+    this.status = status;
+    this.code = code;
+    this.usage = usage;
+  }
+}
+
+function resolveFetch(fetchFn?: typeof fetch): typeof fetch {
+  const resolved = fetchFn ?? (typeof fetch !== "undefined" ? fetch : undefined);
+  if (!resolved) {
+    throw new Error("No fetch implementation available for chatWithAI.");
+  }
+  return resolved;
+}
+
+async function resolveAuthHeaders(
+  authHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>)
+): Promise<HeadersInit | undefined> {
+  if (!authHeaders) return undefined;
+  if (typeof authHeaders === "function") {
+    return await authHeaders();
+  }
+  return authHeaders;
+}
+
+function readCookie(cookieName: string): string | undefined {
+  if (typeof document === "undefined" || typeof document.cookie !== "string") {
+    return undefined;
+  }
+
+  const entries = document.cookie.split(";").map((part) => part.trim());
+  const match = entries.find((entry) => entry.startsWith(`${cookieName}=`));
+  if (!match) return undefined;
+
+  const [, value = ""] = match.split("=");
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+async function parseResponseBody(response: Response): Promise<unknown> {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return await response.json();
+  }
+
+  const text = await response.text();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+async function ensureCsrfToken(
+  fetcher: typeof fetch,
+  endpoint: string,
+  options: ChatWithAIClientOptions,
+  headers: HeadersInit
+): Promise<string | undefined> {
+  const csrfCookieName = options.csrfCookieName ?? DEFAULT_CSRF_COOKIE_NAME;
+  const existingToken = readCookie(csrfCookieName);
+  if (existingToken || options.bootstrapCsrf === false) {
+    return existingToken;
+  }
+
+  await fetcher(endpoint, {
+    method: "GET",
+    credentials: options.credentials ?? "include",
+    headers,
+  });
+
+  return readCookie(csrfCookieName);
+}
+
+function normalizeError(status: number, body: unknown): ChatbotApiError {
+  const payload = body && typeof body === "object" ? (body as ErrorBody) : undefined;
+  const message =
+    payload?.message ||
+    (status === 401
+      ? "You must be signed in to use chatbot."
+      : "Chatbot request failed.");
+
+  return new ChatbotApiError(status, message, payload?.error, payload?.usage);
+}
+
+function buildUsage(payload: unknown): ChatbotUsage | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  const maybe = payload as Record<string, unknown>;
+  const limit = maybe.limit;
+  const used = maybe.used;
+  const remaining = maybe.remaining;
+  const exhausted = maybe.exhausted;
+
+  if (
+    typeof limit !== "number" ||
+    typeof used !== "number" ||
+    typeof remaining !== "number" ||
+    typeof exhausted !== "boolean"
+  ) {
+    return undefined;
+  }
+
+  return { limit, used, remaining, exhausted };
+}
+
+function mapToChatbotResponse(body: unknown): ChatbotResponse {
+  if (!body || typeof body !== "object") {
+    throw new Error("Invalid chatbot response payload.");
+  }
+
+  const payload = body as Record<string, unknown>;
+  const reply = payload.reply;
+  const model = payload.model;
+  const usage = buildUsage(payload.usage);
+
+  if (typeof reply !== "string" || typeof model !== "string" || !usage) {
+    throw new Error("Invalid chatbot response payload.");
+  }
+
+  return { reply, model, usage };
+}
+
+function mapToChatbotUsageResponse(body: unknown): ChatbotUsageResponse {
+  if (!body || typeof body !== "object") {
+    throw new Error("Invalid chatbot usage payload.");
+  }
+
+  const payload = body as Record<string, unknown>;
+  const usage = buildUsage(payload.usage);
+  if (!usage) {
+    throw new Error("Invalid chatbot usage payload.");
+  }
+
+  return { usage };
+}
+
+export async function getChatbotUsage(
+  options: ChatWithAIClientOptions = {}
+): Promise<ChatbotUsageResponse> {
+  const fetcher = resolveFetch(options.fetchFn);
+  const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+  const authHeaders = await resolveAuthHeaders(options.authHeaders);
+  const response = await fetcher(endpoint, {
+    method: "GET",
+    credentials: options.credentials ?? "include",
+    headers: {
+      Accept: "application/json",
+      ...(authHeaders ?? {}),
+    },
+  });
+
+  const body = await parseResponseBody(response);
+  if (!response.ok) {
+    throw normalizeError(response.status, body);
+  }
+
+  return mapToChatbotUsageResponse(body);
+}
+
+export async function chatWithAI(
+  request: ChatWithAIRequest,
+  options: ChatWithAIClientOptions = {}
+): Promise<ChatbotResponse> {
+  const fetcher = resolveFetch(options.fetchFn);
+  const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+  const authHeaders = await resolveAuthHeaders(options.authHeaders);
+  const baseHeaders: HeadersInit = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    ...(authHeaders ?? {}),
+  };
+
+  const csrfToken = await ensureCsrfToken(fetcher, endpoint, options, baseHeaders);
+  const csrfHeaderName = options.csrfHeaderName ?? DEFAULT_CSRF_HEADER_NAME;
+  const headers = csrfToken
+    ? {
+        ...baseHeaders,
+        [csrfHeaderName]: csrfToken,
+      }
+    : baseHeaders;
+
+  const response = await fetcher(endpoint, {
+    method: "POST",
+    credentials: options.credentials ?? "include",
+    headers,
+    body: JSON.stringify({
+      message: request.message,
+      history: request.history ?? [],
+      systemPrompt: request.systemPrompt,
+    }),
+  });
+
+  const body = await parseResponseBody(response);
+  if (!response.ok) {
+    throw normalizeError(response.status, body);
+  }
+
+  return mapToChatbotResponse(body);
+}