Add ConnectorTriggerPayload helper for reading trigger callbacks (#190)

CHANGELOG.md

@@ -13,6 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
      the same content into release_notes.md for NuGet packaging. Do NOT put HTML
      comments in release_notes.md — it is packed verbatim into <releaseNotes>. -->
 
+### Added
+
+- **`ConnectorTriggerPayload` helper to read trigger callbacks** — turns a raw Connector Namespace trigger callback (`string` or `Stream`) into a typed payload or decoded file bytes without per-function boilerplate. `Read<TPayload>` / `ReadAsync<TPayload>` deserialize metadata triggers (e.g. OneDrive `OnNewFilesV2`) with case-insensitive property matching, so camelCase wire fields bind correctly instead of silently yielding all-`null` items. `TryReadBinaryContent` / `ReadBinaryContentAsync` decode binary-content triggers (e.g. OneDrive `OnNewFileV2`), whose body is a base64 string. The `Stream` overloads read the caller-owned stream without closing it and enforce a generous, overridable body-size limit (`DefaultMaxBodySizeBytes`, 100 MB); `TryReadBinaryContent` returns `false` (rather than throwing) on malformed JSON. ([#190](https://github.com/Azure/Connectors-NET-SDK/issues/190))
+
+### Changed
+
+- **`TriggerCallbackBodyConverter<T>` now throws an actionable error for binary-content bodies** — when a binary-content trigger callback (a JSON string body, e.g. OneDrive `OnNewFileV2`) is deserialized into a metadata payload type, the error now explains the cause and points to `ConnectorTriggerPayload.TryReadBinaryContent` / `ReadBinaryContentAsync` instead of failing with a generic token-mismatch message. ([#190](https://github.com/Azure/Connectors-NET-SDK/issues/190))
+
 ## [0.12.0-preview.1] - 2026-06-02
 
 ### Breaking Changes

README.md

@@ -151,11 +151,21 @@ Authentication uses Azure.Core `TokenCredential` directly — any credential fro
 | `ConnectorJsonSerializer` | JSON serialization with connector conventions |
 | `JsonConverters` | Custom converters for connector types |
 
+### Triggers
+
+| Component | Description |
+|-----------|-------------|
+| `TriggerCallbackPayload<T>` / `TriggerCallbackBody<T>` | Typed envelope for connector trigger callbacks; normalizes batch and single-item shapes into `Body.Value` |
+| `ConnectorTriggerPayload` | Helpers to read a raw trigger callback (`string`/`Stream`) into a typed payload (`Read`/`ReadAsync`) or decoded binary file bytes (`TryReadBinaryContent`/`ReadBinaryContentAsync`), with case-insensitive matching and a bounded read |
+
+See [docs/triggers.md](docs/triggers.md) for the trigger architecture, payload shapes, and end-to-end usage.
+
 ## Documentation
 
 - [docs/concepts.md](docs/concepts.md) - Key concepts, terminology, and architecture
 - [GENERATION.md](GENERATION.md) - How to generate connector code
 - [docs/connection-setup.md](docs/connection-setup.md) - Setting up connections for local testing
+- [docs/triggers.md](docs/triggers.md) - Trigger architecture, typed payloads, and the `ConnectorTriggerPayload` reader
 - [ROADMAP.md](ROADMAP.md) - Connector generation progress and lessons learned
 - [Azure/Connectors-NET-Samples](https://github.com/Azure/Connectors-NET-Samples) - Full working samples (Azure Functions, triggers, etc.)
 

docs/triggers.md

@@ -107,6 +107,33 @@ Use the typed class directly to deserialize callbacks:
 var payload = JsonSerializer.Deserialize<Office365OnNewEmailTriggerPayload>(callbackJson);
 ```
 
+### Reading callbacks with `ConnectorTriggerPayload`
+
+`ConnectorTriggerPayload` (in the `Azure.Connectors.Sdk` namespace) removes the boilerplate of reading a callback body — bounded read, case-insensitive deserialization, and binary-vs-metadata discrimination — so a trigger handler can go straight from the request body to a typed payload:
+
+```csharp
+// Metadata triggers (e.g. OnNewFilesV2) — string or Stream overloads
+var payload = await ConnectorTriggerPayload
+    .ReadAsync<OneDriveForBusinessOnNewFilesTriggerPayload>(request.Body, cancellationToken: cancellationToken)
+    .ConfigureAwait(continueOnCapturedContext: false);
+
+foreach (var file in payload?.Body?.Value ?? Array.Empty<BlobMetadata>())
+{
+    // file.Id, file.Name, file.Path, file.Size ...
+}
+```
+
+Property matching is **case-insensitive**, so callbacks whose wire fields are camelCase bind correctly instead of silently producing all-`null` items. The stream overloads read the caller-owned stream without closing it and enforce a generous body-size limit (`ConnectorTriggerPayload.DefaultMaxBodySizeBytes`, 100 MB, overridable per call). For **binary-content** triggers (see below), use `TryReadBinaryContent` / `ReadBinaryContentAsync`, which decode the base64 `{"body":"<base64>"}` shape into file bytes:
+
+```csharp
+// Binary-content triggers (e.g. OnNewFileV2)
+byte[]? fileBytes = await ConnectorTriggerPayload
+    .ReadBinaryContentAsync(request.Body, cancellationToken: cancellationToken)
+    .ConfigureAwait(continueOnCapturedContext: false);
+```
+
+If a binary-content (string) body is read into a metadata payload type, deserialization throws an actionable `JsonException` that points to the binary-content helpers.
+
 ## Trigger Operation Constants
 
 Each connector exposes a `{Connector}TriggerOperations` static class with the operation name strings: