@tanstack/ai-octane 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -31,7 +31,9 @@ import:
31
31
  ```ts
32
32
  // before
33
33
  import { useChat } from '@tanstack/ai-react'
34
+ ```
34
35
 
36
+ ```ts
35
37
  // after
36
38
  import { useChat } from '@tanstack/ai-octane'
37
39
  ```
@@ -57,37 +59,42 @@ pnpm add @tanstack/ai-octane @tanstack/ai @tanstack/ai-client octane
57
59
  ```tsx
58
60
  import { useState } from 'octane'
59
61
  import { useChat } from '@tanstack/ai-octane'
62
+ import type { ChatFetcher } from '@tanstack/ai-octane'
60
63
 
61
- export function Chat() @{
64
+ declare const myFetcher: ChatFetcher
65
+
66
+ export function Chat() {
62
67
  const [input, setInput] = useState('')
63
68
  const chat = useChat({
64
69
  fetcher: myFetcher,
65
70
  threadId: 'support-42',
66
71
  })
67
72
 
68
- <div>
69
- @for (const message of chat.messages; key message.id) {
70
- <p>
71
- {message.role}:
72
- {message.parts
73
- .filter((part) => part.type === 'text')
74
- .map((part) => part.content)
75
- .join('')}
76
- </p>
77
- }
78
- <input
79
- value={input}
80
- onInput={(event) => setInput(event.currentTarget.value)}
81
- />
82
- <button
83
- onClick={() => {
84
- void chat.sendMessage(input)
85
- setInput('')
86
- }}
87
- >
88
- Send
89
- </button>
90
- </div>
73
+ return (
74
+ <div>
75
+ {chat.messages.map((message) => (
76
+ <p key={message.id}>
77
+ {message.role}:
78
+ {message.parts
79
+ .filter((part) => part.type === 'text')
80
+ .map((part) => part.content)
81
+ .join('')}
82
+ </p>
83
+ ))}
84
+ <input
85
+ value={input}
86
+ onInput={(event) => setInput(event.currentTarget.value)}
87
+ />
88
+ <button
89
+ onClick={() => {
90
+ void chat.sendMessage(input)
91
+ setInput('')
92
+ }}
93
+ >
94
+ Send
95
+ </button>
96
+ </div>
97
+ )
91
98
  }
92
99
  ```
93
100
 
@@ -99,10 +106,10 @@ synthetic `onChange`.
99
106
  ## API
100
107
 
101
108
  The adapter includes `useChat`, `useRealtimeChat`, `useMcpAppBridge`,
102
- `useGeneration`, `useGenerateImage`, `useGenerateAudio`, `useGenerateSpeech`,
103
- `useGenerateVideo`, `useTranscription`, `useSummarize`, and
104
- `useAudioRecorder`. It also re-exports all 30 `@tanstack/ai-client`
105
- convenience helpers and types (`fetchServerSentEvents`, `fetchHttpStream`,
109
+ `useGeneration`, `useGenerateImage`, `useGenerate3DModel` (experimental),
110
+ `useGenerateAudio`, `useGenerateSpeech`, `useGenerateVideo`, `useTranscription`,
111
+ `useSummarize`, and `useAudioRecorder`. It also re-exports all 30
112
+ `@tanstack/ai-client` convenience helpers and types (`fetchServerSentEvents`, `fetchHttpStream`,
106
113
  `xhrServerSentEvents`, `xhrHttpStream`, `stream`, `rpcStream`,
107
114
  `createChatClientOptions`, `createMcpAppBridge`, and their associated types)
108
115
  unchanged, mirroring the `@tanstack/ai-react` index.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tanstack/ai-octane",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Octane bindings for TanStack AI streaming chat, structured outputs, and media generation.",
5
5
  "author": "Dominic Gannaway",
6
6
  "license": "MIT",
@@ -48,23 +48,23 @@
48
48
  ],
49
49
  "//lint": "The .tsrx.d.ts companions are generated declaration emits of the .tsrx implementations, so they are not hand-formatted and are excluded from lint rather than edited in place (a regeneration would undo any fix).",
50
50
  "dependencies": {
51
- "@tanstack/ai-client": "^1.0.0"
51
+ "@tanstack/ai-client": "^1.2.0"
52
52
  },
53
53
  "peerDependencies": {
54
54
  "octane": ">=0.12.0",
55
- "@tanstack/ai": "^1.0.0"
55
+ "@tanstack/ai": "^1.7.0"
56
56
  },
57
57
  "devDependencies": {
58
58
  "@octanejs/testing-library": "0.1.62",
59
59
  "@standard-schema/spec": "^1.1.0",
60
60
  "@tsrx/oxc": "0.20.0",
61
61
  "@types/node": "^24.10.1",
62
- "@vitest/coverage-v8": "4.1.10",
63
- "happy-dom": "^20.11.2",
62
+ "@vitest/coverage-v8": "4.1.12",
63
+ "happy-dom": "^20.14.6",
64
64
  "octane": "0.12.1",
65
- "vite": "^8.2.1",
65
+ "vite": "^8.3.8",
66
66
  "zod": "^4.2.0",
67
- "@tanstack/ai": "1.0.0"
67
+ "@tanstack/ai": "1.7.0"
68
68
  },
69
69
  "scripts": {
70
70
  "lint:fix": "oxlint src --type-aware --fix",
package/src/index.ts CHANGED
@@ -39,6 +39,11 @@ export type {
39
39
  UseGenerateImageOptions,
40
40
  UseGenerateImageReturn,
41
41
  } from './use-generate-image.tsrx'
42
+ export { useGenerate3DModel } from './use-generate-3d-model.tsrx'
43
+ export type {
44
+ UseGenerate3DModelOptions,
45
+ UseGenerate3DModelReturn,
46
+ } from './use-generate-3d-model.tsrx'
42
47
  export { useGenerateAudio } from './use-generate-audio.tsrx'
43
48
  export type {
44
49
  UseGenerateAudioOptions,
@@ -136,6 +141,7 @@ export {
136
141
  type InferChatMessages,
137
142
  type GenerationClientState,
138
143
  type ImageGenerateInput,
144
+ type Model3DGenerateInput,
139
145
  type AudioGenerateInput,
140
146
  type SpeechGenerateInput,
141
147
  type TranscriptionGenerateInput,
@@ -0,0 +1,143 @@
1
+ import { useGeneration } from './use-generation.tsrx'
2
+ import type { Model3DResult, StreamChunk } from '@tanstack/ai'
3
+ import type {
4
+ AIDevtoolsDisplayOptions,
5
+ ConnectConnectionAdapter,
6
+ GenerationClientState,
7
+ GenerationFetcher,
8
+ InferGenerationOutputFromReturn,
9
+ Model3DGenerateInput,
10
+ } from '@tanstack/ai-client'
11
+
12
+ /**
13
+ * Options for the useGenerate3DModel hook.
14
+ *
15
+ * @experimental 3D model generation is experimental. The shape can change in
16
+ * a minor release.
17
+ *
18
+ * @template TOutput - The output type after optional transform (defaults to Model3DResult)
19
+ */
20
+ export interface UseGenerate3DModelOptions<TOutput = Model3DResult> {
21
+ /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
22
+ connection?: ConnectConnectionAdapter
23
+ /** Direct async function for 3D model generation */
24
+ fetcher?: GenerationFetcher<Model3DGenerateInput, Model3DResult>
25
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
26
+ threadId: string
27
+ /** Additional body parameters to send with connect-based adapter requests */
28
+ body?: Record<string, any>
29
+ /** Display options for TanStack AI Devtools. */
30
+ devtools?: AIDevtoolsDisplayOptions
31
+ /**
32
+ * Callback when the 3D model is ready. Can optionally return a transformed value.
33
+ *
34
+ * - Return a non-null value to transform and store it as the result
35
+ * - Return `null` to keep the previous result unchanged
36
+ * - Return nothing (`void`) to store the raw result as-is
37
+ */
38
+ onResult?: (result: Model3DResult) => TOutput | null | void
39
+ /** Callback when an error occurs */
40
+ onError?: (error: Error) => void
41
+ /**
42
+ * Callback for each provider poll. `progress` is 0-100. `message` is the
43
+ * job state (`'pending'`, `'processing'` or `'completed'`).
44
+ */
45
+ onProgress?: (progress: number, message?: string) => void
46
+ /** Callback for each stream chunk (connect-based adapter mode only) */
47
+ onChunk?: (chunk: StreamChunk) => void
48
+ }
49
+
50
+ /**
51
+ * Return type for the useGenerate3DModel hook.
52
+ *
53
+ * @experimental 3D model generation is experimental. The shape can change in
54
+ * a minor release.
55
+ *
56
+ * @template TOutput - The output type (after optional transform)
57
+ */
58
+ export interface UseGenerate3DModelReturn<TOutput = Model3DResult> {
59
+ /** Start 3D model generation */
60
+ generate: (input: Model3DGenerateInput) => Promise<void>
61
+ /** The finished 3D model (url, format, files), or null */
62
+ result: TOutput | null
63
+ /** Whether generation is in progress */
64
+ isLoading: boolean
65
+ /** Current error, if any */
66
+ error: Error | undefined
67
+ /** Current state of the generation */
68
+ status: GenerationClientState
69
+ /** Abort the current generation */
70
+ stop: () => void
71
+ /** Clear result, error, and return to idle */
72
+ reset: () => void
73
+ }
74
+
75
+ /**
76
+ * Octane hook for generating 3D models (text-to-3D, image-to-3D, 3D-to-3D).
77
+ *
78
+ * Supports two transport modes:
79
+ * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)
80
+ * - **Fetcher** — Direct async function call
81
+ *
82
+ * The server streams a `generation:progress` event for each provider poll and
83
+ * one `generation:result` event with the finished model.
84
+ *
85
+ * @experimental 3D model generation is experimental. The shape can change in
86
+ * a minor release.
87
+ *
88
+ * @example
89
+ * ```tsx
90
+ * import { useGenerate3DModel } from '@tanstack/ai-octane'
91
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
92
+ *
93
+ * function ModelGenerator() {
94
+ * const { generate, result, isLoading, error } = useGenerate3DModel({
95
+ * threadId: 'hero-model',
96
+ * connection: fetchServerSentEvents('/api/3d-model'),
97
+ * onProgress: (progress, message) => console.log(progress, message),
98
+ * })
99
+ *
100
+ * return (
101
+ * <div>
102
+ * <button onClick={() => generate({ prompt: 'A low-poly fox' })}>
103
+ * Generate
104
+ * </button>
105
+ * {isLoading && <p>Generating...</p>}
106
+ * {error && <p>Error: {error.message}</p>}
107
+ * {result && <a href={result.url}>Download .{result.format}</a>}
108
+ * </div>
109
+ * )
110
+ * }
111
+ * ```
112
+ */
113
+ export function useGenerate3DModel<TTransformed = void>(
114
+ options: Omit<UseGenerate3DModelOptions, 'onResult'> & {
115
+ onResult?: (result: Model3DResult) => TTransformed
116
+ },
117
+ ): UseGenerate3DModelReturn<
118
+ InferGenerationOutputFromReturn<Model3DResult, TTransformed>
119
+ > {
120
+ const devtools = {
121
+ ...options.devtools,
122
+ // OCTANE DIVERGENCE: identify this binding as Octane (not 'react') in TanStack AI Devtools.
123
+ framework: 'octane',
124
+ hookName: 'useGenerate3DModel',
125
+ }
126
+ const { generate, result, isLoading, error, status, stop, reset } =
127
+ useGeneration<Model3DGenerateInput, Model3DResult, TTransformed>({
128
+ ...options,
129
+ devtools,
130
+ // 3D results are never persisted, even if an untyped caller sets it.
131
+ persistence: false,
132
+ })
133
+
134
+ return {
135
+ generate,
136
+ result,
137
+ isLoading,
138
+ error,
139
+ status,
140
+ stop,
141
+ reset,
142
+ }
143
+ }
@@ -0,0 +1,116 @@
1
+ // Declaration companion generated from use-generate-3d-model.tsrx.
2
+ import type { Model3DResult, StreamChunk } from '@tanstack/ai'
3
+ import type {
4
+ AIDevtoolsDisplayOptions,
5
+ ConnectConnectionAdapter,
6
+ GenerationClientState,
7
+ GenerationFetcher,
8
+ InferGenerationOutputFromReturn,
9
+ Model3DGenerateInput,
10
+ } from '@tanstack/ai-client'
11
+ /**
12
+ * Options for the useGenerate3DModel hook.
13
+ *
14
+ * @experimental 3D model generation is experimental. The shape can change in
15
+ * a minor release.
16
+ *
17
+ * @template TOutput - The output type after optional transform (defaults to Model3DResult)
18
+ */
19
+ export interface UseGenerate3DModelOptions<TOutput = Model3DResult> {
20
+ /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
21
+ connection?: ConnectConnectionAdapter
22
+ /** Direct async function for 3D model generation */
23
+ fetcher?: GenerationFetcher<Model3DGenerateInput, Model3DResult>
24
+ /** Stable scope for this generation. Also the wire and DevTools identity. */
25
+ threadId: string
26
+ /** Additional body parameters to send with connect-based adapter requests */
27
+ body?: Record<string, any>
28
+ /** Display options for TanStack AI Devtools. */
29
+ devtools?: AIDevtoolsDisplayOptions
30
+ /**
31
+ * Callback when the 3D model is ready. Can optionally return a transformed value.
32
+ *
33
+ * - Return a non-null value to transform and store it as the result
34
+ * - Return `null` to keep the previous result unchanged
35
+ * - Return nothing (`void`) to store the raw result as-is
36
+ */
37
+ onResult?: (result: Model3DResult) => TOutput | null | void
38
+ /** Callback when an error occurs */
39
+ onError?: (error: Error) => void
40
+ /**
41
+ * Callback for each provider poll. `progress` is 0-100. `message` is the
42
+ * job state (`'pending'`, `'processing'` or `'completed'`).
43
+ */
44
+ onProgress?: (progress: number, message?: string) => void
45
+ /** Callback for each stream chunk (connect-based adapter mode only) */
46
+ onChunk?: (chunk: StreamChunk) => void
47
+ }
48
+ /**
49
+ * Return type for the useGenerate3DModel hook.
50
+ *
51
+ * @experimental 3D model generation is experimental. The shape can change in
52
+ * a minor release.
53
+ *
54
+ * @template TOutput - The output type (after optional transform)
55
+ */
56
+ export interface UseGenerate3DModelReturn<TOutput = Model3DResult> {
57
+ /** Start 3D model generation */
58
+ generate: (input: Model3DGenerateInput) => Promise<void>
59
+ /** The finished 3D model (url, format, files), or null */
60
+ result: TOutput | null
61
+ /** Whether generation is in progress */
62
+ isLoading: boolean
63
+ /** Current error, if any */
64
+ error: Error | undefined
65
+ /** Current state of the generation */
66
+ status: GenerationClientState
67
+ /** Abort the current generation */
68
+ stop: () => void
69
+ /** Clear result, error, and return to idle */
70
+ reset: () => void
71
+ }
72
+ /**
73
+ * Octane hook for generating 3D models (text-to-3D, image-to-3D, 3D-to-3D).
74
+ *
75
+ * Supports two transport modes:
76
+ * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom)
77
+ * - **Fetcher** — Direct async function call
78
+ *
79
+ * The server streams a `generation:progress` event for each provider poll and
80
+ * one `generation:result` event with the finished model.
81
+ *
82
+ * @experimental 3D model generation is experimental. The shape can change in
83
+ * a minor release.
84
+ *
85
+ * @example
86
+ * ```tsx
87
+ * import { useGenerate3DModel } from '@tanstack/ai-octane'
88
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
89
+ *
90
+ * function ModelGenerator() {
91
+ * const { generate, result, isLoading, error } = useGenerate3DModel({
92
+ * threadId: 'hero-model',
93
+ * connection: fetchServerSentEvents('/api/3d-model'),
94
+ * onProgress: (progress, message) => console.log(progress, message),
95
+ * })
96
+ *
97
+ * return (
98
+ * <div>
99
+ * <button onClick={() => generate({ prompt: 'A low-poly fox' })}>
100
+ * Generate
101
+ * </button>
102
+ * {isLoading && <p>Generating...</p>}
103
+ * {error && <p>Error: {error.message}</p>}
104
+ * {result && <a href={result.url}>Download .{result.format}</a>}
105
+ * </div>
106
+ * )
107
+ * }
108
+ * ```
109
+ */
110
+ export declare function useGenerate3DModel<TTransformed = void>(
111
+ options: Omit<UseGenerate3DModelOptions, 'onResult'> & {
112
+ onResult?: (result: Model3DResult) => TTransformed
113
+ },
114
+ ): UseGenerate3DModelReturn<
115
+ InferGenerationOutputFromReturn<Model3DResult, TTransformed>
116
+ >