Skip to main content
Hooks let you react to lifecycle milestones and streaming updates emitted by SuperDoc AI. 
const ai = new AIActions(superdoc, {
  user,
  provider,
  onReady: ({ aiActions }) => console.log('AI ready', aiActions),
  onStreamingStart: () => console.log('Streaming started'),
  onStreamingPartialResult: ({ partialResult }) => updateLog(partialResult),
  onStreamingEnd: ({ fullResult }) => console.log('Stream finished', fullResult),
  onError: error => console.error('AI error', error),
});

​
Use cases

Hooks are ideal for:
  • Activity logs - Track all AI operations and results
  • Streaming UI - Update interface in real-time as text arrives
  • Progress indicators - Show loading states during operations
  • Error tracking - Centralize error reporting and monitoring
  • Analytics - Measure AI performance and usage patterns
  • Status badges - Display connection and readiness state

​
Available hooks

​
onReady

Called once the provider has been validated and the AI wrapper sets the editor user identity. Parameters:
​
context
object
required
Context object containing the AIActions instance
{ aiActions: AIActions }
Example: 
onReady: ({ aiActions }) => {
  console.log('AI is ready!');
  // Display "AI connected" badge
  // Kick off initial prompt
}

​
onStreamingStart

Fires immediately before the provider call begins streaming. No parameters. Example: 
onStreamingStart: () => {
  console.log('Starting to stream...');
  // Show loading indicator
  // Clear previous results
}

​
onStreamingPartialResult

Fires for each streaming chunk received from the provider. The partialResult accumulates all text received so far. Parameters:
​
context
object
required
Context object containing the accumulated result
{ partialResult: string }
Example: 
onStreamingPartialResult: ({ partialResult }) => {
  console.log('Received:', partialResult);
  // Update UI with latest text
  // Use diffing to show incremental tokens
}
The partialResult contains all accumulated text from the start of the stream, not just the latest chunk. Use diffing if you need to extract only the new content.

​
onStreamingEnd

Fires when streaming completes successfully. Receives the final result object. Parameters:
​
context
object
required
Context object containing the complete result
{ fullResult: unknown }  // Type varies: string for completions, Result for actions
Example: 
onStreamingEnd: ({ fullResult }) => {
  console.log('Streaming complete:', fullResult);
  // Hide loading indicator
  // Log final result
}

​
Hook execution order

For both streamCompletion() calls and ai.action.* helpers, hooks fire in this order:
  1. onStreamingStart - Before provider call
  2. onStreamingPartialResult - Multiple times during streaming
  3. onStreamingEnd - After completion
  4. onError - If an error occurs (instead of onStreamingEnd)

​
onError

Fired whenever an action or completion throws an error (network issues, invalid provider config, parser errors, etc.). Parameters:
​
error
Error
required
The error object that was thrown
Example: 
onError: (error) => {
  console.error('AI error:', error);
  // Log to error tracking service
  // Show user-friendly error message
}
Errors are re-thrown after the hook runs, so you can still use try/catch around actions while logging errors centrally.
Error handling pattern: 
const ai = new AIActions(superdoc, {
  user,
  provider,
  onError: error => captureException(error),  // Centralized logging
});

try {
  await ai.action.replace('Rewrite the conclusion');
} catch (error) {
  // Handle error in UI
  // Error already logged by onError hook
}