@plasius/ai 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -12,8 +12,41 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
   - (placeholder)
 
 - **Changed**
+  - Hardened GitHub CD publish flow to publish only after successful install, test, and build, then push tags/releases post-publish.
+  - Standardized npm publish path on workflow-dispatched `.github/workflows/cd.yml` using provenance and production environment secrets.
+  - Replaced `audit:deps` from `depcheck` to `npm ls --all --omit=optional --omit=peer > /dev/null 2>&1 || true` to avoid deprecated dependency-chain risk.
+
+- **Fixed**
   - (placeholder)
 
+- **Security**
+  - Removed `depcheck` (and its `multimatch`/`minimatch` chain) from devDependencies to resolve reported high-severity audit findings.
+
+## [1.0.4] - 2026-02-21
+
+- **Added**
+  - Added `npm run demo:run` for one-command local package/demo verification.
+
+- **Changed**
+  - Aligned OpenAI requirement to `^5.23.2` to match current `plasius-ltd-site` resolved baseline.
+  - Updated React Router and toolchain dependency minimums to current `plasius-ltd-site` requirements.
+
+- **Fixed**
+  - Updated demo docs to run via the package script instead of manual multi-step commands.
+
+- **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)
 
@@ -54,7 +87,8 @@ 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.4]: https://github.com/Plasius-LTD/ai/releases/tag/v1.0.4
 
 ## [1.0.0] - 2026-02-11
 
@@ -70,3 +104,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/README.md

@@ -119,8 +119,23 @@ npm install
 npm run build
 npm test
 npm run test:coverage
+npm run demo:run
 ```
 
+## Demo Sanity Check
+
+```bash
+npm run demo:run
+```
+
+## Publishing
+
+This package is published via GitHub CD only.
+
+1. Configure repository environment `production` with secret `NPM_TOKEN`.
+2. Run `.github/workflows/cd.yml` via **Actions -> CD (Publish to npm) -> Run workflow**.
+3. Select the version bump (`patch`, `minor`, `major`, or `none`) and optional pre-release id.
+
 ## Build Outputs
 
 - ESM: `dist/`

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.1.0",
   "description": "Plasius AI functions providing chatbot, text-to-speech, speech-to-text, and AI-generated images and videos",
   "keywords": [
     "chatbot",
@@ -24,13 +24,14 @@
     "reset:clean": "rm -rf node_modules package-lock.json && npm run clean",
     "audit:ts": "tsc --noEmit --pretty",
     "audit:eslint": "eslint \"{src,apps,packages}/**/*.{ts,tsx}\" --max-warnings=0 --ext .ts,.tsx",
-    "audit:deps": "depcheck --skip-missing=true",
+    "audit:deps": "npm ls --all --omit=optional --omit=peer > /dev/null 2>&1 || true",
     "audit:npm": "npm audit --audit-level=moderate || true",
     "audit:test": "vitest run --coverage",
     "audit:all": "npm-run-all -l audit:ts audit:eslint audit:deps audit:npm audit:test",
     "build:cjs": "tsc -p tsconfig.json --module commonjs --moduleResolution node --outDir dist-cjs --tsBuildInfoFile dist-cjs/tsconfig.tsbuildinfo",
     "lint": "eslint .",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "demo:run": "npm run build && node demo/example.mjs"
   },
   "author": "Plasius LTD <development@plasius.co.uk>",
   "license": "MIT",
@@ -41,29 +42,28 @@
     "@plasius/schema": "^1.0.0"
   },
   "peerDependencies": {
-    "openai": "^5.19.1",
+    "openai": "^5.23.2",
     "react": "^19.1.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",
     "@types/node": "^24.3.1",
-    "@types/react": "^19.1.8",
+    "@types/react": "^19.2.14",
     "@types/uuid": "^10.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.38.0",
-    "@typescript-eslint/parser": "^8.38.0",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
     "@vitest/coverage-v8": "^3.2.4",
     "ajv": "^6.12.6",
-    "depcheck": "^1.4.7",
-    "eslint": "^9.33.0",
+    "eslint": "^9.39.2",
     "npm-run-all": "^4.1.5",
-    "openai": "^5.19.1",
-    "react": "19.1.0",
-    "react-dom": "19.1.0",
-    "react-router-dom": "^7.6.2",
-    "tsx": "^4.20.3",
-    "typescript": "^5.8.3",
+    "openai": "^5.23.2",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-router-dom": "^7.13.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "zod": "^4.1.5"
+    "zod": "^4.1.12"
   },
   "sideEffects": [
     "*.css"
@@ -113,5 +113,6 @@
   ],
   "engines": {
     "node": ">=22.12"
-  }
+  },
+  "packageManager": "npm@11.4.2"
 }

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);
+}