Add AI Gateway client and chat hook

Author: IzumiSy

.changeset/warm-pans-learn.md

@@ -0,0 +1,12 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Add a low-level AI Gateway client and a simple text-only chat hook for AppShell.
+
+```tsx
+import { createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";
+
+const aiClient = createAIGatewayClient({ gatewayUri, authClient });
+const { messages, sendMessage, stop } = useAIChat({ client: aiClient, model: "gpt-5-mini" });
+```

docs/api/create-ai-gateway-client.md

@@ -0,0 +1,93 @@
+---
+title: createAIGatewayClient
+description: Create a low-level AI Gateway client that reuses AppShell authentication
+---
+
+# createAIGatewayClient
+
+Creates a small AI Gateway transport client for text-only chat completions.
+
+## Signature
+
+```typescript
+function createAIGatewayClient(config: {
+  gatewayUri: string;
+  authClient: AuthClient;
+}): AIGatewayClient;
+```
+
+## Parameters
+
+### `gatewayUri`
+
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** Base URL of the AI Gateway
+
+### `authClient`
+
+- **Type:** `AuthClient`
+- **Required:** Yes
+- **Description:** Auth client used for authenticated requests via `authClient.fetch(...)`
+
+## Return Value
+
+```typescript
+interface AIGatewayClient {
+  chatCompletionStream(request: AIGatewayChatRequest): AsyncGenerator<string, void, unknown>;
+}
+```
+
+The generator yields text deltas. Concatenate them to build the assistant response.
+
+## Related Types
+
+```typescript
+interface AIGatewayChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+interface AIGatewayChatRequest {
+  model: string;
+  messages: AIGatewayChatMessage[];
+  signal?: AbortSignal;
+}
+```
+
+## Usage
+
+```typescript
+import { createAuthClient, createAIGatewayClient } from "@tailor-platform/app-shell";
+
+const authClient = createAuthClient({
+  clientId: "your-client-id",
+  appUri: "https://xyz.erp.dev",
+});
+
+const aiClient = createAIGatewayClient({
+  gatewayUri: "https://your-ai-gateway.example.com",
+  authClient,
+});
+
+const deltas: string[] = [];
+for await (const delta of aiClient.chatCompletionStream({
+  model: "gpt-5-mini",
+  messages: [{ role: "user", content: "Hello" }],
+})) {
+  deltas.push(delta);
+}
+
+console.log(deltas.join(""));
+```
+
+## Notes
+
+- Non-Gemini models are consumed as streaming SSE responses
+- `gemini-*` models are consumed as JSON responses and yielded once
+- The public API is intentionally text-only
+
+## Related
+
+- [Authentication Concept](../concepts/authentication.md)
+- [useAIChat](./use-ai-chat.md)

docs/api/use-ai-chat.md

@@ -0,0 +1,106 @@
+---
+title: useAIChat
+description: Simple text-only chat hook for AI Gateway
+---
+
+# useAIChat
+
+React hook for simple text-only chat on top of `createAIGatewayClient`.
+
+## Signature
+
+```typescript
+const useAIChat: (config: { client: AIGatewayClient; model: string }) => {
+  messages: AIChatMessage[];
+  status: "ready" | "submitted" | "streaming" | "error";
+  error?: Error;
+  sendMessage: (message: { text: string } | string) => Promise<void>;
+  stop: () => void;
+};
+```
+
+## Return Value
+
+### `messages`
+
+```typescript
+interface AIChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+}
+```
+
+### `status`
+
+- **Type:** `"ready" | "submitted" | "streaming" | "error"`
+- **Description:** Current request state
+
+### `error`
+
+- **Type:** `Error | undefined`
+- **Description:** Last request error, if any
+
+### `sendMessage()`
+
+- **Type:** `(message: { text: string } | string) => Promise<void>`
+- **Description:** Appends a user message and streams the assistant response
+
+### `stop()`
+
+- **Type:** `() => void`
+- **Description:** Aborts the current request if one is in progress
+
+## Usage
+
+```tsx
+import { createAuthClient, createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";
+
+const authClient = createAuthClient({
+  clientId: "your-client-id",
+  appUri: "https://xyz.erp.dev",
+});
+
+const aiClient = createAIGatewayClient({
+  gatewayUri: "https://your-ai-gateway.example.com",
+  authClient,
+});
+
+export function ChatScreen() {
+  const { messages, sendMessage, status, stop, error } = useAIChat({
+    client: aiClient,
+    model: "gpt-5-mini",
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.role}: {message.content}
+        </div>
+      ))}
+
+      <button
+        onClick={() => sendMessage("Hello")}
+        disabled={status === "submitted" || status === "streaming"}
+      >
+        Send
+      </button>
+      <button onClick={stop} disabled={status !== "submitted" && status !== "streaming"}>
+        Stop
+      </button>
+      {error ? <div>{error.message}</div> : null}
+    </div>
+  );
+}
+```
+
+## Notes
+
+- The hook is intentionally text-only
+- System prompts and custom history shaping should use the low-level client directly
+- `stop()` keeps any already-streamed assistant text
+
+## Related
+
+- [createAIGatewayClient](./create-ai-gateway-client.md)

docs/concepts/authentication.md

@@ -154,6 +154,46 @@ function App() {
 }
 ```
 
+### Using `createAIGatewayClient` with AI Gateway
+
+`createAIGatewayClient` reuses the same authenticated fetch path as the rest of AppShell. Requests go through `authClient.fetch`, so DPoP proof generation and token refresh stay in the auth layer.
+
+```tsx
+import { createAuthClient, createAIGatewayClient, useAIChat } from "@tailor-platform/app-shell";
+
+const authClient = createAuthClient({
+  clientId: "your-client-id",
+  appUri: "https://xyz.erp.dev",
+});
+
+const aiClient = createAIGatewayClient({
+  gatewayUri: "https://your-ai-gateway.example.com",
+  authClient,
+});
+
+function ChatScreen() {
+  const { messages, sendMessage, status, stop } = useAIChat({
+    client: aiClient,
+    model: "gpt-5-mini",
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.role}: {message.content}
+        </div>
+      ))}
+
+      <button onClick={() => sendMessage("Hello")}>Send</button>
+      <button onClick={stop} disabled={status !== "submitted" && status !== "streaming"}>
+        Stop
+      </button>
+    </div>
+  );
+}
+```
+
 ### `AuthClientConfig`
 
 | Property      | Type     | Required | Description                                                |