tiptapify 0.2.4 → 0.2.6

package/src/extensions/components/ai/backend.test.ts

@@ -0,0 +1,314 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { TiptapifyAiEditorContext, TiptapifyAiRequest, TiptapifyAiStream } from '@tiptapify/types/editor'
+
+import { buildAiBackendRequest, createAiBackendProvider, DEFAULT_AI_INSTRUCTION } from './backend'
+
+function createContext(overrides: Partial<TiptapifyAiEditorContext> = {}): TiptapifyAiEditorContext {
+  return {
+    prompt: 'Improve this text',
+    selectedText: '',
+    text: '',
+    html: '',
+    json: {},
+    mode: 'insert',
+    ...overrides,
+  }
+}
+
+function createRequest(overrides: Partial<TiptapifyAiRequest> = {}): TiptapifyAiRequest {
+  return {
+    messages: [
+      { role: 'system', content: 'Be concise' },
+      { role: 'user', content: 'Improve this text' },
+    ],
+    ...overrides,
+  }
+}
+
+function createStream() {
+  const controller = new AbortController()
+  const chunks: string[] = []
+  const reasoning: string[] = []
+
+  const stream: TiptapifyAiStream = {
+    signal: controller.signal,
+    onChunk: (chunk: string) => chunks.push(chunk),
+    onReasoning: (chunk: string) => reasoning.push(chunk),
+  }
+
+  return { stream, chunks, reasoning, controller }
+}
+
+function createSseBody(lines: string[], { failAfter = -1 } = {}) {
+  let index = 0
+
+  return {
+    getReader() {
+      return {
+        async read() {
+          if (failAfter >= 0 && index > failAfter) {
+            throw new DOMException('The operation was aborted', 'AbortError')
+          }
+
+          index += 1
+
+          if (index <= lines.length) {
+            return { done: false, value: new TextEncoder().encode(lines[index - 1]) }
+          }
+
+          return { done: true, value: undefined }
+        },
+      }
+    },
+  } as unknown as ReadableStream<Uint8Array>
+}
+
+function createResponse(init: { status?: number, body?: string, sse?: string[], sseFailAfter?: number } = {}) {
+  const status = init.status ?? 200
+
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    body: init.sse ? createSseBody(init.sse, { failAfter: init.sseFailAfter }) : null,
+    text: async () => (init.body ?? ''),
+  } as unknown as Response
+}
+
+let fetchCalls: Array<{ url: string, init: RequestInit | undefined }>
+let responseToReturn: Response | null
+
+beforeEach(() => {
+  fetchCalls = []
+  responseToReturn = null
+
+  vi.stubGlobal('fetch', vi.fn(async (url: string, init: RequestInit) => {
+    fetchCalls.push({ url, init })
+
+    return responseToReturn as Response
+  }))
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('buildAiBackendRequest', () => {
+  it('always sends prompt and instruction', () => {
+    const payload = buildAiBackendRequest(createRequest(), createContext())
+
+    expect(payload).toEqual({
+      prompt: 'Improve this text',
+      instruction: 'Be concise',
+    })
+  })
+
+  it('falls back to the default instruction when there is no system message', () => {
+    const request = createRequest({ messages: [{ role: 'user', content: 'x' }] })
+
+    expect(buildAiBackendRequest(request, createContext()).instruction).toBe(DEFAULT_AI_INSTRUCTION)
+  })
+
+  it('sends optional fields only when they are set', () => {
+    const payload = buildAiBackendRequest(
+      createRequest({ model: 'gpt-4.1-mini', stream: true, enable_thinking: true, reasoning_effort: 'high' }),
+      createContext(),
+    )
+
+    expect(payload).toEqual({
+      prompt: 'Improve this text',
+      instruction: 'Be concise',
+      model: 'gpt-4.1-mini',
+      stream: true,
+      thinking: true,
+      reasoning_effort: 'high',
+    })
+  })
+
+  it('omits thinking when it is not enabled', () => {
+    const payload = buildAiBackendRequest(createRequest({ enable_thinking: false }), createContext())
+
+    expect(payload.thinking).toBeUndefined()
+  })
+
+  it('omits reasoning_effort for default or non-string values', () => {
+    expect(buildAiBackendRequest(createRequest({ reasoning_effort: 'default' }), createContext()).reasoning_effort).toBeUndefined()
+    expect(buildAiBackendRequest(createRequest({ reasoning_effort: 5 }), createContext()).reasoning_effort).toBeUndefined()
+  })
+})
+
+describe('createAiBackendProvider', () => {
+  it('posts the minimal payload as JSON to the endpoint', async () => {
+    responseToReturn = createResponse({ body: JSON.stringify({ content: 'Done' }) })
+    const provider = createAiBackendProvider({ endpoint: '/api/ai/generate' })
+
+    await provider(createRequest({ model: 'gpt-4.1-mini', stream: true }), createContext())
+
+    expect(fetchCalls).toHaveLength(1)
+    expect(fetchCalls[0].url).toBe('/api/ai/generate')
+    const init = fetchCalls[0].init as RequestInit
+
+    expect(init.method).toBe('POST')
+    expect((init.headers as Record<string, string>)['Content-Type']).toBe('application/json')
+    expect(JSON.parse(init.body as string)).toEqual({
+      prompt: 'Improve this text',
+      instruction: 'Be concise',
+      model: 'gpt-4.1-mini',
+      stream: true,
+    })
+  })
+
+  it('returns a JSON response body', async () => {
+    responseToReturn = createResponse({ body: JSON.stringify({ content: 'Done' }) })
+    const result = await createAiBackendProvider({ endpoint: '/api' })(createRequest(), createContext())
+
+    expect(result).toEqual({ content: 'Done' })
+  })
+
+  it('returns a plain text response body', async () => {
+    responseToReturn = createResponse({ body: 'Plain answer' })
+    const result = await createAiBackendProvider({ endpoint: '/api' })(createRequest(), createContext())
+
+    expect(result).toBe('Plain answer')
+  })
+
+  it('throws the backend error message on a non-OK response', async () => {
+    responseToReturn = createResponse({ status: 500, body: JSON.stringify({ error: 'Model is busy' }) })
+    const provider = createAiBackendProvider({ endpoint: '/api' })
+
+    await expect(provider(createRequest(), createContext())).rejects.toThrow('Model is busy')
+  })
+
+  it('throws a status error when the error body is not JSON', async () => {
+    responseToReturn = createResponse({ status: 502 })
+    const provider = createAiBackendProvider({ endpoint: '/api' })
+
+    await expect(provider(createRequest(), createContext())).rejects.toThrow('Request failed with status 502')
+  })
+
+  it('sends static headers and the tokenProvider token as Bearer', async () => {
+    responseToReturn = createResponse({ body: 'ok' })
+    const provider = createAiBackendProvider({
+      endpoint: '/api',
+      headers: { 'X-Api-Key': 'key' },
+      tokenProvider: () => 'secret',
+    })
+
+    await provider(createRequest(), createContext())
+    const headers = (fetchCalls[0].init as RequestInit).headers as Record<string, string>
+
+    expect(headers['Content-Type']).toBe('application/json')
+    expect(headers['X-Api-Key']).toBe('key')
+    expect(headers.Authorization).toBe('Bearer secret')
+  })
+
+  it('keeps a static Authorization header over the tokenProvider token', async () => {
+    responseToReturn = createResponse({ body: 'ok' })
+    const provider = createAiBackendProvider({
+      endpoint: '/api',
+      headers: { Authorization: 'Token abc' },
+      tokenProvider: () => 'secret',
+    })
+
+    await provider(createRequest(), createContext())
+    const headers = (fetchCalls[0].init as RequestInit).headers as Record<string, string>
+
+    expect(headers.Authorization).toBe('Token abc')
+  })
+
+  it('streams OpenAI-style SSE deltas into onChunk/onReasoning', async () => {
+    responseToReturn = createResponse({
+      sse: [
+        'data: {"choices":[{"delta":{"reasoning_content":"Let me"}}]}\n',
+        'data: {"choices":[{"delta":{"reasoning_content":" think"}}]}\n',
+        'data: {"choices":[{"delta":{"content":"Hello"}}]}\n',
+        'data: {"choices":[{"delta":{"content":" world"}}]}\n',
+        'data: [DONE]\n',
+      ],
+    })
+    const { stream, chunks, reasoning } = createStream()
+    const provider = createAiBackendProvider({ endpoint: '/api' })
+    const result = await provider(createRequest({ stream: true }), createContext(), stream)
+
+    expect(chunks).toEqual(['Hello', ' world'])
+    expect(reasoning).toEqual(['Let me', ' think'])
+    expect(result).toEqual({ content: 'Hello world' })
+    expect((fetchCalls[0].init as RequestInit).signal).toBe(stream.signal)
+  })
+
+  it('accepts the simple { type, data } chunk format', async () => {
+    responseToReturn = createResponse({
+      sse: [
+        'data: {"type":"reasoning","data":"plan"}\n',
+        'data: {"type":"content","data":"One "}\n',
+        'data: {"type":"content","data":"two"}\n',
+      ],
+    })
+    const { stream, chunks, reasoning } = createStream()
+    const result = await createAiBackendProvider({ endpoint: '/api' })(createRequest({ stream: true }), createContext(), stream)
+
+    expect(chunks).toEqual(['One ', 'two'])
+    expect(reasoning).toEqual(['plan'])
+    expect(result).toEqual({ content: 'One two' })
+  })
+
+  it('treats plain-text data lines as content chunks', async () => {
+    responseToReturn = createResponse({
+      sse: [
+        'data: Hello \n',
+        'data: world\n',
+      ],
+    })
+    const { stream, chunks } = createStream()
+    const result = await createAiBackendProvider({ endpoint: '/api' })(createRequest({ stream: true }), createContext(), stream)
+
+    expect(chunks).toEqual(['Hello ', 'world'])
+    expect(result).toEqual({ content: 'Hello world' })
+  })
+
+  it('reassembles chunks split across reader reads', async () => {
+    responseToReturn = createResponse({
+      sse: [
+        'data: {"choices":[{"delta":{"conte',
+        'nt":"Hel"}}]}\n',
+        'data: {"choices":[{"delta":{"content":"lo"}}]}\n',
+        'data: [DONE]\n',
+      ],
+    })
+    const { stream, chunks } = createStream()
+    const result = await createAiBackendProvider({ endpoint: '/api' })(createRequest({ stream: true }), createContext(), stream)
+
+    expect(chunks).toEqual(['Hel', 'lo'])
+    expect(result).toEqual({ content: 'Hello' })
+  })
+
+  it('keeps partially streamed content when the request is aborted', async () => {
+    responseToReturn = createResponse({ sse: ['data: {"choices":[{"delta":{"content":"Part"}}]}\n'], sseFailAfter: 0 })
+    const { stream, chunks } = createStream()
+    const provider = createAiBackendProvider({ endpoint: '/api' })
+    const result = await provider(createRequest({ stream: true }), createContext(), stream)
+
+    expect(chunks).toEqual(['Part'])
+    expect(result).toEqual({ content: 'Part' })
+  })
+
+  it('falls back to a plain body when the backend ignores stream', async () => {
+    responseToReturn = createResponse({ sse: ['{"content":"Full answer"}\n'] })
+    const { stream } = createStream()
+    const result = await createAiBackendProvider({ endpoint: '/api' })(createRequest({ stream: true }), createContext(), stream)
+
+    expect(result).toEqual({ content: 'Full answer' })
+  })
+
+  it('returns empty content when only reasoning was streamed', async () => {
+    responseToReturn = createResponse({
+      sse: [
+        'data: {"choices":[{"delta":{"reasoning_content":"think"}}]}\n',
+        'data: [DONE]\n',
+      ],
+    })
+    const { stream } = createStream()
+    const result = await createAiBackendProvider({ endpoint: '/api' })(createRequest({ stream: true }), createContext(), stream)
+
+    expect(result).toEqual({ content: '' })
+  })
+})

package/src/extensions/components/ai/backend.ts

@@ -0,0 +1,303 @@
+import {
+  TiptapifyAiBackendProviderOptions,
+  TiptapifyAiBackendRequest,
+  TiptapifyAiEditorContext,
+  TiptapifyAiOpenAiResponse,
+  TiptapifyAiProvider,
+  TiptapifyAiReasoningEffort,
+  TiptapifyAiRequest,
+  TiptapifyAiResponse,
+  TiptapifyAiStream,
+  TiptapifyAiTokenProvider,
+} from '@tiptapify/types/editor'
+
+/**
+ * The instruction used when the AI options do not set a `systemPrompt`.
+ * Shared between the dialog's default messages and the backend provider
+ * (the `instruction` field of the backend payload).
+ */
+export const DEFAULT_AI_INSTRUCTION = 'You are an AI writing assistant inside a rich text editor. Return only the final text to insert.'
+
+/**
+ * Builds the minimal backend payload from the OpenAI-compatible request the
+ * dialog assembles.
+ *
+ * `prompt` (the user's request) and `instruction` (the system prompt, or the
+ * built-in default) are always present. `stream`, `thinking`,
+ * `reasoning_effort`, and `model` are included only when they are set.
+ */
+export function buildAiBackendRequest(request: TiptapifyAiRequest, context: TiptapifyAiEditorContext): TiptapifyAiBackendRequest {
+  const systemMessage = request.messages.find(message => message.role === 'system')
+  const payload: TiptapifyAiBackendRequest = {
+    prompt: context.prompt,
+    instruction: typeof systemMessage?.content === 'string' ? systemMessage.content : DEFAULT_AI_INSTRUCTION,
+  }
+
+  if (request.model) {
+    payload.model = request.model
+  }
+
+  if (request.stream === true) {
+    payload.stream = true
+  }
+
+  if (request.enable_thinking === true) {
+    payload.thinking = true
+  }
+
+  const reasoningEffort = request.reasoning_effort
+  if (typeof reasoningEffort === 'string' && reasoningEffort !== '' && reasoningEffort !== 'default') {
+    payload.reasoning_effort = reasoningEffort as TiptapifyAiReasoningEffort
+  }
+
+  return payload
+}
+
+/**
+ * Creates a `TiptapifyAiProvider` that posts the minimal payload
+ * (`prompt` + `instruction` + optional fields) to a backend LLM endpoint.
+ *
+ * The response is lenient: a plain string, a `{ content }` object, or an
+ * OpenAI-compatible `choices` payload are all accepted. When the request has
+ * `stream: true`, the body is read as an SSE stream (`data:` lines,
+ * terminated by `data: [DONE]`); OpenAI-style deltas
+ * (`choices[0].delta.content` / `.reasoning_content`), a simple
+ * `{ type: 'content' | 'reasoning', data }` chunk, a flat
+ * `{ content, reasoning_content }` chunk, and plain-text `data` lines are
+ * all accepted.
+ */
+export function createAiBackendProvider(options: TiptapifyAiBackendProviderOptions): TiptapifyAiProvider {
+  const { endpoint, headers, tokenProvider } = options
+
+  return async function aiBackendProvider(request, context, stream) {
+    const payload = buildAiBackendRequest(request, context)
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: await buildBackendHeaders(headers, tokenProvider),
+      body: JSON.stringify(payload),
+      signal: stream?.signal,
+    })
+
+    if (!response.ok) {
+      throw await createBackendError(response)
+    }
+
+    if (payload.stream !== true || !response.body) {
+      return parseBackendResponse(await response.text())
+    }
+
+    const { content, raw, aborted } = await readSseBody(response.body, stream)
+
+    if (aborted) {
+      // The user stopped the request — keep what has been streamed so far
+      return { content }
+    }
+
+    // Lenient: the backend may ignore `stream` and answer with a plain body
+    if (content === '' && raw.trim() !== '') {
+      const trimmedRaw = raw.trim()
+      try {
+        return JSON.parse(trimmedRaw)
+      } catch {
+        if (!trimmedRaw.includes('data:')) {
+          return trimmedRaw
+        }
+      }
+    }
+
+    return { content }
+  }
+}
+
+async function buildBackendHeaders(headers: Record<string, string> | undefined, tokenProvider?: TiptapifyAiTokenProvider): Promise<Record<string, string>> {
+  const result: Record<string, string> = {
+    'Content-Type': 'application/json',
+    ...headers,
+  }
+
+  if (tokenProvider && !result.Authorization) {
+    const token = await tokenProvider()
+    if (token) {
+      result.Authorization = `Bearer ${token}`
+    }
+  }
+
+  return result
+}
+
+async function createBackendError(response: Response): Promise<Error> {
+  const body = await response.text()
+  let message = body
+
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>
+    const error = parsed.error
+
+    if (typeof error === 'string') {
+      message = error
+    } else if (error && typeof error === 'object' && typeof (error as Record<string, unknown>).message === 'string') {
+      message = (error as Record<string, unknown>).message as string
+    } else if (typeof parsed.message === 'string') {
+      message = parsed.message
+    }
+  } catch {
+    // Keep the raw body
+  }
+
+  return new Error(message || `Request failed with status ${response.status}`)
+}
+
+function parseBackendResponse(text: string): TiptapifyAiResponse | TiptapifyAiOpenAiResponse | string {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+type SseReadResult = {
+  content: string,
+  raw: string,
+  aborted: boolean,
+}
+
+async function readSseBody(body: ReadableStream<Uint8Array>, stream?: TiptapifyAiStream): Promise<SseReadResult> {
+  const result: SseReadResult = { content: '', raw: '', aborted: false }
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) {
+        break
+      }
+
+      const chunk = decoder.decode(value, { stream: true })
+      result.raw += chunk
+      buffer += chunk
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+
+      for (const line of lines) {
+        result.content += parseSseLine(line, stream)
+      }
+    }
+
+    const tail = decoder.decode()
+    if (tail) {
+      result.raw += tail
+      buffer += tail
+    }
+
+    if (buffer) {
+      result.content += parseSseLine(buffer, stream)
+    }
+  } catch (error) {
+    if (stream?.signal.aborted || isAbortError(error)) {
+      result.aborted = true
+      return result
+    }
+    throw error
+  }
+
+  return result
+}
+
+/**
+ * Parses a single SSE line and forwards its content/reasoning chunks to the
+ * stream callbacks. Returns the portion dispatched as content so the caller
+ * can accumulate the full response.
+ */
+function parseSseLine(line: string, stream?: TiptapifyAiStream): string {
+  const trimmed = line.replace(/\r$/, '')
+
+  if (!trimmed.startsWith('data:')) {
+    return ''
+  }
+
+  const data = trimmed.slice(5).trimStart()
+
+  if (data === '' || data.trim() === '[DONE]') {
+    return ''
+  }
+
+  let payload: unknown
+
+  try {
+    payload = JSON.parse(data)
+  } catch {
+    // A plain-text data line is a content chunk
+    if (stream) {
+      stream.onChunk(data)
+    }
+    return data
+  }
+
+  if (typeof payload === 'string') {
+    if (stream) {
+      stream.onChunk(payload)
+    }
+    return payload
+  }
+
+  if (typeof payload !== 'object' || payload === null) {
+    return ''
+  }
+
+  const record = payload as Record<string, unknown>
+
+  // Simple chunk format: { type: 'content' | 'reasoning', data: '...' }
+  if (typeof record.data === 'string') {
+    if (record.type === 'reasoning') {
+      if (stream) {
+        stream.onReasoning(record.data)
+      }
+      return ''
+    }
+
+    if (stream) {
+      stream.onChunk(record.data)
+    }
+    return record.data
+  }
+
+  // OpenAI-compatible chunk: choices[0].delta.content / .reasoning_content
+  const choice = Array.isArray(record.choices) ? record.choices[0] : null
+  const delta = choice !== null && typeof choice === 'object' ? (choice as Record<string, unknown>).delta : undefined
+
+  if (delta && typeof delta === 'object' && delta !== null) {
+    const deltaRecord = delta as Record<string, unknown>
+    let content = ''
+
+    if (typeof deltaRecord.reasoning_content === 'string' && deltaRecord.reasoning_content !== '') {
+      stream?.onReasoning(deltaRecord.reasoning_content)
+    }
+
+    if (typeof deltaRecord.content === 'string' && deltaRecord.content !== '') {
+      stream?.onChunk(deltaRecord.content)
+      content = deltaRecord.content
+    }
+
+    return content
+  }
+
+  // Flat chunk format: { content, reasoning_content }
+  let content = ''
+
+  if (typeof record.reasoning_content === 'string' && record.reasoning_content !== '') {
+    stream?.onReasoning(record.reasoning_content)
+  }
+
+  if (typeof record.content === 'string' && record.content !== '') {
+    stream?.onChunk(record.content)
+    content = record.content
+  }
+
+  return content
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'AbortError'
+}

package/src/extensions/components/ai/charLimit.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import { Document } from '@tiptap/extension-document'
+import { Editor } from '@tiptap/vue-3'
+import { Paragraph } from '@tiptap/extension-paragraph'
+import { Text } from '@tiptap/extension-text'
+
+import { exceedsLimit } from './charLimit'
+
+function createDoc(content: string) {
+  const editor = new Editor({
+    content,
+    extensions: [Document, Paragraph, Text],
+  })
+
+  return { doc: editor.state.doc, destroy: () => editor.destroy() }
+}
+
+describe('exceedsLimit', () => {
+  it('is false when the text fits the budget', () => {
+    const { doc, destroy } = createDoc('<p>hello</p>') // 5 characters, budget 5
+
+    expect(exceedsLimit('abcd', { doc, limit: 10, mode: 'insert' })).toBe(false)
+
+    destroy()
+  })
+
+  it('is true when the text would exceed the limit', () => {
+    const { doc, destroy } = createDoc('<p>hello</p>') // 5 characters, budget 5
+
+    expect(exceedsLimit('abcdefgh', { doc, limit: 10, mode: 'insert' })).toBe(true)
+    expect(exceedsLimit('abcdefgh', { doc, limit: 10, mode: 'append' })).toBe(true)
+
+    destroy()
+  })
+
+  it('accounts for the freed range in replace mode', () => {
+    const { doc, destroy } = createDoc('<p>hello</p>') // 5 characters
+
+    // Replacing "hello" (1..6) frees 5 characters → budget 10, "1234567890" fits
+    expect(exceedsLimit('1234567890', { doc, limit: 10, mode: 'replace', range: { from: 1, to: 6 } })).toBe(false)
+
+    // Without the range the same text would exceed the limit
+    expect(exceedsLimit('1234567890', { doc, limit: 10, mode: 'insert' })).toBe(true)
+
+    destroy()
+  })
+
+  it('is true when the document is already at the limit', () => {
+    const { doc, destroy } = createDoc('<p>1234567890</p>') // 10 characters, budget 0
+
+    expect(exceedsLimit('x', { doc, limit: 10, mode: 'insert' })).toBe(true)
+
+    destroy()
+  })
+})

package/src/extensions/components/ai/charLimit.ts

@@ -0,0 +1,30 @@
+import type { Node } from '@tiptap/pm/model'
+import type { TiptapifyAiMode } from '@tiptapify/types/editor'
+
+export type CharLimitOptions = {
+  doc: Node
+  limit: number
+  mode: TiptapifyAiMode
+  range?: { from: number, to: number } | null
+}
+
+/**
+ * Whether inserting `text` would push the document past `limit` characters,
+ * counted the same way as the CharacterCount extension (textSize mode, default
+ * counter: the length of the document text with a single space per block boundary).
+ *
+ * In replace mode the characters of the selected `range` are freed by the
+ * removal that precedes the insert, so they are added back to the budget.
+ */
+export function exceedsLimit(text: string, options: CharLimitOptions): boolean {
+  const { doc, limit, mode, range } = options
+  const currentChars = doc.textBetween(0, doc.content.size, undefined, ' ').length
+
+  let removedChars = 0
+  if (mode === 'replace' && range) {
+    removedChars = doc.textBetween(range.from, range.to, undefined, ' ').length
+  }
+
+  const budget = limit - currentChars + removedChars
+  return text.length > budget
+}