From 023f6e2fa44ba18cfd857e66c7659284740e661c Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Mon, 19 Jan 2026 00:12:43 +0100
Subject: [PATCH] docs(ai): document onPayload callback

---
 packages/ai/README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/packages/ai/README.md b/packages/ai/README.md
index 1c72b820..6ffd8798 100644
--- a/packages/ai/README.md
+++ b/packages/ai/README.md
@@ -598,6 +598,20 @@ context.messages.push({ role: 'user', content: 'Please continue' });
 const continuation = await complete(model, context);
 ```
 
+### Debugging Provider Payloads
+
+Use the `onPayload` callback to inspect the request payload sent to the provider. This is useful for debugging request formatting issues or provider validation errors.
+
+```typescript
+const response = await complete(model, context, {
+  onPayload: (payload) => {
+    console.log('Provider payload:', JSON.stringify(payload, null, 2));
+  }
+});
+```
+
+The callback is supported by `stream`, `complete`, `streamSimple`, and `completeSimple`.
+
 ## APIs, Models, and Providers
 
 The library implements 4 API interfaces, each with its own streaming function and options: