diff --git a/.release-please-manifest.json b/.release-please-manifest.json index e52c9a17..f73b9f9a 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "5.18.0" + ".": "5.18.1" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index e2794c72..48e48092 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 134 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-b053468fefe6d757f86f3233ebbc52d80329ed2a6e7a6740fee01e4028a4c3b9.yml -openapi_spec_hash: 416835e693de0fe19945be90a787d3f3 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/courier/courier-5c878919b3df530781ebcd4ab1cda83606304da75c53fe0817d4c725d5bbbe73.yml +openapi_spec_hash: dd37022222543ff064200e65e4b82f59 config_hash: 8d28dbeabe9d4dcc7d5b8c021a4cbbd7 diff --git a/CHANGELOG.md b/CHANGELOG.md index a61f5895..370f3eff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog +## 5.18.1 (2026-07-25) + +Full Changelog: [v5.18.0...v5.18.1](https://github.com/trycourier/courier-csharp/compare/v5.18.0...v5.18.1) + +### Bug Fixes + +* **client:** tolerate JSON null in required untyped fields and prefer more specific union variants ([a5395b3](https://github.com/trycourier/courier-csharp/commit/a5395b32bc046944b3cbac22367645beab24f779)) + + +### Documentation + +* **openapi:** describe user topic-preference fields explicitly ([#172](https://github.com/trycourier/courier-csharp/issues/172)) ([7a0f629](https://github.com/trycourier/courier-csharp/commit/7a0f629f65ccaad8b5ca3b1a85dbc57d459da31b)) +* **openapi:** rewrite operation descriptions for agents and SEO ([#174](https://github.com/trycourier/courier-csharp/issues/174)) ([e22f43f](https://github.com/trycourier/courier-csharp/commit/e22f43f8050b6b71e58c5996e2e591cba57c15be)) + ## 5.18.0 (2026-07-23) Full Changelog: [v5.17.0...v5.18.0](https://github.com/trycourier/courier-csharp/compare/v5.17.0...v5.18.0) diff --git a/src/TryCourier.Tests/Core/JsonDictionaryTest.cs b/src/TryCourier.Tests/Core/JsonDictionaryTest.cs index 8b901c62..c46e49e7 100644 --- a/src/TryCourier.Tests/Core/JsonDictionaryTest.cs +++ b/src/TryCourier.Tests/Core/JsonDictionaryTest.cs @@ -206,6 +206,43 @@ public void GetNotNullStruct_ThrowsWhenTypeInvalid() Assert.Contains("'text' must be of type", exception.Message); } + [Fact] + public void GetNotAbsentElement_ReturnsValue() + { + var dict = new JsonDictionary(); + dict.Set("age", 30); + + var age = dict.GetNotAbsentElement("age"); + + Assert.Equal(30, age.GetInt32()); + } + + [Fact] + public void GetNotAbsentElement_ThrowsWhenKeyAbsent() + { + var dict = new JsonDictionary(); + + var exception = Assert.Throws(() => + dict.GetNotAbsentElement("missing") + ); + Assert.Contains("'missing' cannot be absent", exception.Message); + } + + [Fact] + public void GetNotAbsentElement_ReturnsNullElementWhenValueIsNull() + { + var dict = new JsonDictionary( + new Dictionary + { + ["nullable"] = JsonSerializer.SerializeToElement(null), + } + ); + + var element = dict.GetNotAbsentElement("nullable"); + + Assert.Equal(JsonValueKind.Null, element.ValueKind); + } + [Fact] public void GetNullableClass_ReturnsValueWhenPresent() { diff --git a/src/TryCourier.Tests/Core/MultipartJsonDictionaryTest.cs b/src/TryCourier.Tests/Core/MultipartJsonDictionaryTest.cs index 16b23535..8e63cc1a 100644 --- a/src/TryCourier.Tests/Core/MultipartJsonDictionaryTest.cs +++ b/src/TryCourier.Tests/Core/MultipartJsonDictionaryTest.cs @@ -1,6 +1,7 @@ using System; using System.Collections.Frozen; using System.Collections.Generic; +using System.Text.Json; using TryCourier.Core; using TryCourier.Exceptions; @@ -205,6 +206,43 @@ public void GetNotNullStruct_ThrowsWhenTypeInvalid() Assert.Contains("'text' must be of type", exception.Message); } + [Fact] + public void GetNotAbsentElement_ReturnsValue() + { + var dict = new MultipartJsonDictionary(); + dict.Set("age", 30); + + var age = dict.GetNotAbsentElement("age"); + + Assert.Equal(30, age.GetInt32()); + } + + [Fact] + public void GetNotAbsentElement_ThrowsWhenKeyAbsent() + { + var dict = new MultipartJsonDictionary(); + + var exception = Assert.Throws(() => + dict.GetNotAbsentElement("missing") + ); + Assert.Contains("'missing' cannot be absent", exception.Message); + } + + [Fact] + public void GetNotAbsentElement_ReturnsNullElementWhenValueIsNull() + { + var dict = new MultipartJsonDictionary( + new Dictionary + { + ["nullable"] = MultipartJsonSerializer.SerializeToElement(null), + } + ); + + var element = dict.GetNotAbsentElement("nullable"); + + Assert.Equal(JsonValueKind.Null, element.ValueKind); + } + [Fact] public void GetNullableClass_ReturnsValueWhenPresent() { diff --git a/src/TryCourier/Core/JsonDictionary.cs b/src/TryCourier/Core/JsonDictionary.cs index 11ada2db..e547aa58 100644 --- a/src/TryCourier/Core/JsonDictionary.cs +++ b/src/TryCourier/Core/JsonDictionary.cs @@ -149,6 +149,22 @@ public T GetNotNullStruct(string key) return deserialized; } + /// + /// Gets the raw JSON element for a key that must be present, without rejecting JSON null. + /// + /// Used for values of unknown type, which can be any JSON value including null. A JSON + /// null is returned as a whose ValueKind is + /// Null. + /// + public JsonElement GetNotAbsentElement(string key) + { + if (!_rawData.TryGetValue(key, out JsonElement element)) + { + throw new CourierInvalidDataException($"'{key}' cannot be absent"); + } + return element; + } + public override string ToString() => JsonSerializer.Serialize( FriendlyJsonPrinter.PrintValue(this._rawData), diff --git a/src/TryCourier/Core/MultipartJsonDictionary.cs b/src/TryCourier/Core/MultipartJsonDictionary.cs index d5b70f81..1a77aa76 100644 --- a/src/TryCourier/Core/MultipartJsonDictionary.cs +++ b/src/TryCourier/Core/MultipartJsonDictionary.cs @@ -152,6 +152,22 @@ public T GetNotNullStruct(string key) return deserialized; } + /// + /// Gets the raw JSON element for a key that must be present, without rejecting JSON null. + /// + /// Used for values of unknown type, which can be any JSON value including null. A JSON + /// null is returned as a whose ValueKind is + /// Null. + /// + public JsonElement GetNotAbsentElement(string key) + { + if (!_rawData.TryGetValue(key, out MultipartJsonElement element)) + { + throw new CourierInvalidDataException($"'{key}' cannot be absent"); + } + return element.Json; + } + public override string ToString() => JsonSerializer.Serialize( FriendlyJsonPrinter.PrintValue(this._rawData), diff --git a/src/TryCourier/Models/Audiences/AudienceDeleteParams.cs b/src/TryCourier/Models/Audiences/AudienceDeleteParams.cs index 93f5a293..5455e94e 100644 --- a/src/TryCourier/Models/Audiences/AudienceDeleteParams.cs +++ b/src/TryCourier/Models/Audiences/AudienceDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Audiences; /// -/// Deletes the specified audience. +/// Deletes an audience permanently, so update any caller sending to it by audience +/// id first. Those sends fail once the audience is gone. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Audiences/AudienceListMembersParams.cs b/src/TryCourier/Models/Audiences/AudienceListMembersParams.cs index 0dd5cc48..6b36af80 100644 --- a/src/TryCourier/Models/Audiences/AudienceListMembersParams.cs +++ b/src/TryCourier/Models/Audiences/AudienceListMembersParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Audiences; /// -/// Get list of members of an audience. +/// Returns the users currently matching an audience filter, with paging. Membership +/// is recalculated, so results shift as profiles change. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Audiences/AudienceListParams.cs b/src/TryCourier/Models/Audiences/AudienceListParams.cs index e60ff83b..e3bdd9f9 100644 --- a/src/TryCourier/Models/Audiences/AudienceListParams.cs +++ b/src/TryCourier/Models/Audiences/AudienceListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Audiences; /// -/// Get the audiences associated with the authorization token. +/// Returns the audiences in the workspace with paging. Audiences are filter-based +/// groups that recalculate as user profiles change. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Audiences/AudienceRetrieveParams.cs b/src/TryCourier/Models/Audiences/AudienceRetrieveParams.cs index 4426a78b..f5eb3d91 100644 --- a/src/TryCourier/Models/Audiences/AudienceRetrieveParams.cs +++ b/src/TryCourier/Models/Audiences/AudienceRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Audiences; /// -/// Returns the specified audience by id. +/// Returns one audience with its name, description, and the filter and AND or OR +/// operator that decide which users belong to it. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Audiences/AudienceUpdateParams.cs b/src/TryCourier/Models/Audiences/AudienceUpdateParams.cs index 1b7a6566..ae7180dd 100644 --- a/src/TryCourier/Models/Audiences/AudienceUpdateParams.cs +++ b/src/TryCourier/Models/Audiences/AudienceUpdateParams.cs @@ -12,7 +12,8 @@ namespace TryCourier.Models.Audiences; /// -/// Creates or updates audience. +/// Creates or replaces an audience from a filter and an AND or OR operator. Membership +/// recalculates automatically as profiles change. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/AuditEvents/AuditEventListParams.cs b/src/TryCourier/Models/AuditEvents/AuditEventListParams.cs index ec901418..c872ea0d 100644 --- a/src/TryCourier/Models/AuditEvents/AuditEventListParams.cs +++ b/src/TryCourier/Models/AuditEvents/AuditEventListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.AuditEvents; /// -/// Fetch the list of audit events +/// Returns the workspace's audit event log with cursor paging. Each event records +/// the actor, target, source, type, and timestamp of a change. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/AuditEvents/AuditEventRetrieveParams.cs b/src/TryCourier/Models/AuditEvents/AuditEventRetrieveParams.cs index 7f0f4d2f..e0ad888d 100644 --- a/src/TryCourier/Models/AuditEvents/AuditEventRetrieveParams.cs +++ b/src/TryCourier/Models/AuditEvents/AuditEventRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.AuditEvents; /// -/// Fetch a specific audit event by ID. +/// Returns one audit event by id, including the actor who performed it, the target +/// they changed, the source, the event type, and a timestamp. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Auth/AuthIssueTokenParams.cs b/src/TryCourier/Models/Auth/AuthIssueTokenParams.cs index aa76d1dc..7e528bf2 100644 --- a/src/TryCourier/Models/Auth/AuthIssueTokenParams.cs +++ b/src/TryCourier/Models/Auth/AuthIssueTokenParams.cs @@ -10,7 +10,8 @@ namespace TryCourier.Models.Auth; /// -/// Returns a new access token. +/// Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply +/// the scope and an expires_in duration, both required. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Automations/AutomationListParams.cs b/src/TryCourier/Models/Automations/AutomationListParams.cs index 04f34c61..f8933ad6 100644 --- a/src/TryCourier/Models/Automations/AutomationListParams.cs +++ b/src/TryCourier/Models/Automations/AutomationListParams.cs @@ -11,7 +11,8 @@ namespace TryCourier.Models.Automations; /// -/// Get the list of automations. +/// Lists the workspace's saved automation templates, each with its id and a cursor +/// for paging to the next page of results. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Automations/Invoke/InvokeInvokeAdHocParams.cs b/src/TryCourier/Models/Automations/Invoke/InvokeInvokeAdHocParams.cs index e87771a3..6f76b188 100644 --- a/src/TryCourier/Models/Automations/Invoke/InvokeInvokeAdHocParams.cs +++ b/src/TryCourier/Models/Automations/Invoke/InvokeInvokeAdHocParams.cs @@ -13,9 +13,8 @@ namespace TryCourier.Models.Automations.Invoke; /// -/// Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a -/// series of automation steps. For information about what steps are available, checkout -/// the ad hoc automation guide [here](https://www.courier.com/docs/automations/steps/). +/// Runs a series of automation steps supplied inline, without a saved template, +/// and returns a runId. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that @@ -740,7 +739,10 @@ JsonSerializerOptions options var element = JsonSerializer.Deserialize(ref reader, options); try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize( + element, + options + ); if (deserialized != null) { deserialized.Validate(); @@ -754,7 +756,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -768,7 +770,10 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize( + element, + options + ); if (deserialized != null) { deserialized.Validate(); @@ -782,10 +787,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( - element, - options - ); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -799,7 +801,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -813,10 +815,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( - element, - options - ); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -830,7 +829,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); diff --git a/src/TryCourier/Models/Automations/Invoke/InvokeInvokeByTemplateParams.cs b/src/TryCourier/Models/Automations/Invoke/InvokeInvokeByTemplateParams.cs index 2babbfa7..a073194a 100644 --- a/src/TryCourier/Models/Automations/Invoke/InvokeInvokeByTemplateParams.cs +++ b/src/TryCourier/Models/Automations/Invoke/InvokeInvokeByTemplateParams.cs @@ -10,7 +10,8 @@ namespace TryCourier.Models.Automations.Invoke; /// -/// Invoke an automation run from an automation template. +/// Starts an automation run from a saved template for one recipient, with optional +/// data and profile, and returns a runId. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Brands/BrandCreateParams.cs b/src/TryCourier/Models/Brands/BrandCreateParams.cs index 2d0fb4ea..516c22eb 100644 --- a/src/TryCourier/Models/Brands/BrandCreateParams.cs +++ b/src/TryCourier/Models/Brands/BrandCreateParams.cs @@ -10,8 +10,8 @@ namespace TryCourier.Models.Brands; /// -/// Create a new brand. Requires `name` and `settings` (with at least `colors.primary` -/// and `colors.secondary`). +/// Creates a brand from a name and settings, including primary and secondary colors. +/// Brands supply the logo, colors, and styling that templates render with. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Brands/BrandDeleteParams.cs b/src/TryCourier/Models/Brands/BrandDeleteParams.cs index 212e8352..690f2d4f 100644 --- a/src/TryCourier/Models/Brands/BrandDeleteParams.cs +++ b/src/TryCourier/Models/Brands/BrandDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Brands; /// -/// Delete a brand by brand ID. +/// Deletes a brand by id. Reassign any template or tenant that references it before +/// deleting to keep their styling intact. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Brands/BrandListParams.cs b/src/TryCourier/Models/Brands/BrandListParams.cs index e7e85c04..f2bb2090 100644 --- a/src/TryCourier/Models/Brands/BrandListParams.cs +++ b/src/TryCourier/Models/Brands/BrandListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Brands; /// -/// Get the list of brands. +/// Lists the workspace's brands. Every entry carries its name, styling settings, +/// snippets, and published version. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Brands/BrandRetrieveParams.cs b/src/TryCourier/Models/Brands/BrandRetrieveParams.cs index 94189a52..7e416561 100644 --- a/src/TryCourier/Models/Brands/BrandRetrieveParams.cs +++ b/src/TryCourier/Models/Brands/BrandRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Brands; /// -/// Fetch a specific brand by brand ID. +/// Returns one brand by id, including its colors, logo and styling settings, Handlebars +/// snippets, and published version. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Brands/BrandUpdateParams.cs b/src/TryCourier/Models/Brands/BrandUpdateParams.cs index 3142478a..ed84c4f7 100644 --- a/src/TryCourier/Models/Brands/BrandUpdateParams.cs +++ b/src/TryCourier/Models/Brands/BrandUpdateParams.cs @@ -10,7 +10,8 @@ namespace TryCourier.Models.Brands; /// -/// Replace an existing brand with the supplied values. +/// Replaces a brand with the values you supply, so send the complete settings and +/// snippets rather than only the fields you want changed. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Digests/Schedules/ScheduleListInstancesParams.cs b/src/TryCourier/Models/Digests/Schedules/ScheduleListInstancesParams.cs index 82ed68df..1274a950 100644 --- a/src/TryCourier/Models/Digests/Schedules/ScheduleListInstancesParams.cs +++ b/src/TryCourier/Models/Digests/Schedules/ScheduleListInstancesParams.cs @@ -9,9 +9,8 @@ namespace TryCourier.Models.Digests.Schedules; /// -/// List the digest instances for a schedule. Each instance represents the events -/// accumulated for a single user against the schedule, and can be used to monitor -/// digest accumulation before the digest is released. +/// Returns the digest instances for a schedule, one per user, with cursor paging. +/// Use it to see what has accumulated before a digest releases. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Expo.cs b/src/TryCourier/Models/Expo.cs index 07bcc3e8..84141651 100644 --- a/src/TryCourier/Models/Expo.cs +++ b/src/TryCourier/Models/Expo.cs @@ -211,7 +211,7 @@ JsonSerializerOptions options var element = JsonSerializer.Deserialize(ref reader, options); try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -225,7 +225,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); diff --git a/src/TryCourier/Models/Inbound/InboundTrackEventParams.cs b/src/TryCourier/Models/Inbound/InboundTrackEventParams.cs index 76f7e1b1..9f10b0e7 100644 --- a/src/TryCourier/Models/Inbound/InboundTrackEventParams.cs +++ b/src/TryCourier/Models/Inbound/InboundTrackEventParams.cs @@ -12,7 +12,8 @@ namespace TryCourier.Models.Inbound; /// -/// Courier Track Event +/// Records an inbound event that can trigger a journey. Requires an event name, a +/// messageId you generate, a type, and a properties object. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/CancelJourneyResponse.cs b/src/TryCourier/Models/Journeys/CancelJourneyResponse.cs index 2dda5c84..89af240a 100644 --- a/src/TryCourier/Models/Journeys/CancelJourneyResponse.cs +++ b/src/TryCourier/Models/Journeys/CancelJourneyResponse.cs @@ -233,7 +233,7 @@ JsonSerializerOptions options var element = JsonSerializer.Deserialize(ref reader, options); try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -247,7 +247,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); diff --git a/src/TryCourier/Models/Journeys/JourneyArchiveParams.cs b/src/TryCourier/Models/Journeys/JourneyArchiveParams.cs index abb56fb0..3e9a9cf0 100644 --- a/src/TryCourier/Models/Journeys/JourneyArchiveParams.cs +++ b/src/TryCourier/Models/Journeys/JourneyArchiveParams.cs @@ -9,8 +9,8 @@ namespace TryCourier.Models.Journeys; /// -/// Archive a journey. Archived journeys cannot be invoked. Existing journey runs -/// continue to completion. +/// Archives a journey so it can no longer be invoked. Runs already in flight continue +/// to completion, so archiving never strands a user mid-sequence. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/JourneyCancelParams.cs b/src/TryCourier/Models/Journeys/JourneyCancelParams.cs index c95abda6..7bab8a92 100644 --- a/src/TryCourier/Models/Journeys/JourneyCancelParams.cs +++ b/src/TryCourier/Models/Journeys/JourneyCancelParams.cs @@ -10,12 +10,8 @@ namespace TryCourier.Models.Journeys; /// -/// Cancel journey runs. The request body must include EXACTLY ONE of `cancelation_token` -/// (cancels every run associated with the token) or `run_id` (cancels a single tenant-scoped -/// run). Supplying both or neither returns a `400`. A `run_id` that does not match -/// a run for the tenant returns `404`. Cancelation is idempotent: a run that has -/// already finished (`PROCESSED`/`ERROR`) or was already `CANCELED` is left unchanged -/// and its current status is returned. +/// Cancels in-flight journey runs, either every run sharing a cancelation token or +/// one run by id. Use it to stop a sequence when the event resolves. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/JourneyCreateParams.cs b/src/TryCourier/Models/Journeys/JourneyCreateParams.cs index 96d5ab8a..cca7053a 100644 --- a/src/TryCourier/Models/Journeys/JourneyCreateParams.cs +++ b/src/TryCourier/Models/Journeys/JourneyCreateParams.cs @@ -11,11 +11,8 @@ namespace TryCourier.Models.Journeys; /// -/// Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to publish -/// on create. Send nodes are not allowed on `POST`. The standard flow is: create -/// the journey shell here, add notification templates with `POST /journeys/{templateId}/templates`, -/// then wire them into the journey with `PUT /journeys/{templateId}`. Call `POST -/// /journeys/{templateId}/publish` to publish a draft after the fact. +/// Creates a journey from a set of nodes, in draft state unless you pass a published +/// state. Send nodes cannot be included until their templates exist. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/JourneyInvokeParams.cs b/src/TryCourier/Models/Journeys/JourneyInvokeParams.cs index a18412f2..c2af70b2 100644 --- a/src/TryCourier/Models/Journeys/JourneyInvokeParams.cs +++ b/src/TryCourier/Models/Journeys/JourneyInvokeParams.cs @@ -10,8 +10,8 @@ namespace TryCourier.Models.Journeys; /// -/// Invoke a journey by id or alias to start a new run. The response includes a `runId` -/// identifying the run. +/// Starts a journey run for one user and returns a runId. Runs execute asynchronously, +/// so the response arrives before any message is sent. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/JourneyListParams.cs b/src/TryCourier/Models/Journeys/JourneyListParams.cs index 5480fa74..0eee10e5 100644 --- a/src/TryCourier/Models/Journeys/JourneyListParams.cs +++ b/src/TryCourier/Models/Journeys/JourneyListParams.cs @@ -11,7 +11,8 @@ namespace TryCourier.Models.Journeys; /// -/// Get the list of journeys. +/// Lists the workspace's journeys, each carrying a name, state, and enabled flag. +/// Paged by cursor. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/JourneyListVersionsParams.cs b/src/TryCourier/Models/Journeys/JourneyListVersionsParams.cs index 0719accf..dc282d7c 100644 --- a/src/TryCourier/Models/Journeys/JourneyListVersionsParams.cs +++ b/src/TryCourier/Models/Journeys/JourneyListVersionsParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Journeys; /// -/// List published versions of a journey, ordered most recent first. +/// Lists a journey's published versions, most recent first, so you have a version +/// id to roll back to. Paged by cursor. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/JourneyNode.cs b/src/TryCourier/Models/Journeys/JourneyNode.cs index 85a873e9..d418b85d 100644 --- a/src/TryCourier/Models/Journeys/JourneyNode.cs +++ b/src/TryCourier/Models/Journeys/JourneyNode.cs @@ -838,10 +838,7 @@ JsonSerializerOptions options var element = JsonSerializer.Deserialize(ref reader, options); try { - var deserialized = JsonSerializer.Deserialize( - element, - options - ); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -855,10 +852,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( - element, - options - ); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -872,7 +866,10 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize( + element, + options + ); if (deserialized != null) { deserialized.Validate(); @@ -886,7 +883,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( + var deserialized = JsonSerializer.Deserialize( element, options ); @@ -903,7 +900,10 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize( + element, + options + ); if (deserialized != null) { deserialized.Validate(); @@ -917,7 +917,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( + var deserialized = JsonSerializer.Deserialize( element, options ); @@ -934,7 +934,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( + var deserialized = JsonSerializer.Deserialize( element, options ); @@ -951,7 +951,10 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize( + element, + options + ); if (deserialized != null) { deserialized.Validate(); @@ -965,10 +968,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( - element, - options - ); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -982,7 +982,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( + var deserialized = JsonSerializer.Deserialize( element, options ); @@ -999,7 +999,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -1013,7 +1013,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -1027,7 +1027,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -1041,7 +1041,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); diff --git a/src/TryCourier/Models/Journeys/JourneyPublishParams.cs b/src/TryCourier/Models/Journeys/JourneyPublishParams.cs index 5112909a..532a918a 100644 --- a/src/TryCourier/Models/Journeys/JourneyPublishParams.cs +++ b/src/TryCourier/Models/Journeys/JourneyPublishParams.cs @@ -10,9 +10,8 @@ namespace TryCourier.Models.Journeys; /// -/// Publish the current draft as a new version. Body is optional; pass `{ "version": -/// "vN" }` to roll back to a prior version instead. Returns 404 if the journey has -/// no draft to publish. +/// Publishes a journey's current draft as a new version, making it live for new +/// runs. Pass a version instead to roll back to an earlier one. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/JourneyReplaceParams.cs b/src/TryCourier/Models/Journeys/JourneyReplaceParams.cs index 792a6d56..984e2fa0 100644 --- a/src/TryCourier/Models/Journeys/JourneyReplaceParams.cs +++ b/src/TryCourier/Models/Journeys/JourneyReplaceParams.cs @@ -11,10 +11,8 @@ namespace TryCourier.Models.Journeys; /// -/// Replace the journey draft. Updates the working draft only; call `POST /journeys/{templateId}/publish` -/// to make it live, or pass `state: "PUBLISHED"` in this request to publish immediately. -/// Send-node `template` ids must already exist and be scoped to this journey, and -/// node ids must not be claimed by another journey. +/// Replaces a journey's working draft, leaving the published version live until you +/// publish. Reach for this when editing a journey already running. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/Templates/TemplateArchiveParams.cs b/src/TryCourier/Models/Journeys/Templates/TemplateArchiveParams.cs index 63a5013c..5480a6b5 100644 --- a/src/TryCourier/Models/Journeys/Templates/TemplateArchiveParams.cs +++ b/src/TryCourier/Models/Journeys/Templates/TemplateArchiveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Journeys.Templates; /// -/// Archive the journey-scoped notification template. Archived templates cannot be sent. +/// Archives one journey's notification template, preventing further sends. Detach +/// any send node referencing it beforehand. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/Templates/TemplateListVersionsParams.cs b/src/TryCourier/Models/Journeys/Templates/TemplateListVersionsParams.cs index 54aab566..33d9a846 100644 --- a/src/TryCourier/Models/Journeys/Templates/TemplateListVersionsParams.cs +++ b/src/TryCourier/Models/Journeys/Templates/TemplateListVersionsParams.cs @@ -9,8 +9,8 @@ namespace TryCourier.Models.Journeys.Templates; /// -/// List published versions of the journey-scoped notification template, ordered most -/// recent first. +/// Lists the published versions of a template that belongs to a journey, most recent +/// first. Paged by cursor. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/Templates/TemplatePublishParams.cs b/src/TryCourier/Models/Journeys/Templates/TemplatePublishParams.cs index 99f4f473..f5006149 100644 --- a/src/TryCourier/Models/Journeys/Templates/TemplatePublishParams.cs +++ b/src/TryCourier/Models/Journeys/Templates/TemplatePublishParams.cs @@ -10,8 +10,8 @@ namespace TryCourier.Models.Journeys.Templates; /// -/// Publish the current draft of the journey-scoped notification template as a new -/// version. Optionally roll back to a prior version by passing `{ "version": "vN" }`. +/// Publishes a journey-scoped template's draft as a new version. Pass a version +/// instead to roll back the template to an earlier publish. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/Templates/TemplateReplaceParams.cs b/src/TryCourier/Models/Journeys/Templates/TemplateReplaceParams.cs index d33dccc3..d6bfbad4 100644 --- a/src/TryCourier/Models/Journeys/Templates/TemplateReplaceParams.cs +++ b/src/TryCourier/Models/Journeys/Templates/TemplateReplaceParams.cs @@ -13,7 +13,8 @@ namespace TryCourier.Models.Journeys.Templates; /// -/// Replace the journey-scoped notification template draft. +/// Replaces the draft content of one journey's notification template. Publish it +/// before send nodes referencing it render the change. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/Templates/TemplateRetrieveContentParams.cs b/src/TryCourier/Models/Journeys/Templates/TemplateRetrieveContentParams.cs index c84c53e1..f71ef0cb 100644 --- a/src/TryCourier/Models/Journeys/Templates/TemplateRetrieveContentParams.cs +++ b/src/TryCourier/Models/Journeys/Templates/TemplateRetrieveContentParams.cs @@ -9,10 +9,8 @@ namespace TryCourier.Models.Journeys.Templates; /// -/// Retrieve the elemental content of a journey-scoped notification template. The -/// response contains the versioned elements along with their content checksums, -/// which can be used to detect changes between versions. Pass `?version=draft` (default -/// `published`) to retrieve the working draft, or `?version=vN` for a historical version. +/// Returns the Elemental elements and version of a journey-scoped template's content. +/// Compare versions to see what changed between publishes. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Journeys/Templates/TemplateRetrieveParams.cs b/src/TryCourier/Models/Journeys/Templates/TemplateRetrieveParams.cs index 41de3ef5..7400e0e6 100644 --- a/src/TryCourier/Models/Journeys/Templates/TemplateRetrieveParams.cs +++ b/src/TryCourier/Models/Journeys/Templates/TemplateRetrieveParams.cs @@ -9,8 +9,8 @@ namespace TryCourier.Models.Journeys.Templates; /// -/// Fetch a journey-scoped notification template by id. Pass `?version=draft` (default -/// `published`) to retrieve the working draft, or `?version=vN` for a historical version. +/// Returns a journey's own notification template with its name, brand, subscription +/// topic, and content. Defaults to the published version. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Lists/ListDeleteParams.cs b/src/TryCourier/Models/Lists/ListDeleteParams.cs index 7ca2753c..1c71cd67 100644 --- a/src/TryCourier/Models/Lists/ListDeleteParams.cs +++ b/src/TryCourier/Models/Lists/ListDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Lists; /// -/// Delete a list by list ID. +/// Deletes a list, halting sends that target it. A previously deleted list can be +/// brought back with the companion restore endpoint. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Lists/ListListParams.cs b/src/TryCourier/Models/Lists/ListListParams.cs index 8607c94f..c6988e1b 100644 --- a/src/TryCourier/Models/Lists/ListListParams.cs +++ b/src/TryCourier/Models/Lists/ListListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Lists; /// -/// Returns all of the lists, with the ability to filter based on a pattern. +/// Returns the workspace's lists, filterable by a pattern to fetch a subset such +/// as every regional list. Paged by cursor. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Lists/ListRestoreParams.cs b/src/TryCourier/Models/Lists/ListRestoreParams.cs index 8ff9be3c..7470c414 100644 --- a/src/TryCourier/Models/Lists/ListRestoreParams.cs +++ b/src/TryCourier/Models/Lists/ListRestoreParams.cs @@ -10,7 +10,8 @@ namespace TryCourier.Models.Lists; /// -/// Restore a previously deleted list. +/// Restores a previously deleted list along with its subscribers, so a list removed +/// by mistake can be brought back rather than rebuilt. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Lists/ListRetrieveParams.cs b/src/TryCourier/Models/Lists/ListRetrieveParams.cs index f9c2c8b8..a1a6745b 100644 --- a/src/TryCourier/Models/Lists/ListRetrieveParams.cs +++ b/src/TryCourier/Models/Lists/ListRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Lists; /// -/// Returns a list based on the list ID provided. +/// Returns one list by id with its name and created and updated timestamps. Fetch +/// its subscribers separately with the subscriptions endpoint. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Lists/ListUpdateParams.cs b/src/TryCourier/Models/Lists/ListUpdateParams.cs index 64fcf486..6e4870aa 100644 --- a/src/TryCourier/Models/Lists/ListUpdateParams.cs +++ b/src/TryCourier/Models/Lists/ListUpdateParams.cs @@ -10,7 +10,8 @@ namespace TryCourier.Models.Lists; /// -/// Create or replace an existing list with the supplied values. +/// Creates or replaces a list from a name and preferences. Subscribers are managed +/// through the separate subscriptions endpoints. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Lists/Subscriptions/SubscriptionListParams.cs b/src/TryCourier/Models/Lists/Subscriptions/SubscriptionListParams.cs index 95570cb2..0ac43521 100644 --- a/src/TryCourier/Models/Lists/Subscriptions/SubscriptionListParams.cs +++ b/src/TryCourier/Models/Lists/Subscriptions/SubscriptionListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Lists.Subscriptions; /// -/// Get the list's subscriptions. +/// Returns the users subscribed to a list with paging, each with the preferences +/// recorded for that subscription. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Lists/Subscriptions/SubscriptionSubscribeUserParams.cs b/src/TryCourier/Models/Lists/Subscriptions/SubscriptionSubscribeUserParams.cs index 8c793a69..c2e5a393 100644 --- a/src/TryCourier/Models/Lists/Subscriptions/SubscriptionSubscribeUserParams.cs +++ b/src/TryCourier/Models/Lists/Subscriptions/SubscriptionSubscribeUserParams.cs @@ -10,8 +10,8 @@ namespace TryCourier.Models.Lists.Subscriptions; /// -/// Subscribe a user to an existing list (note: if the List does not exist, it will -/// be automatically created). +/// Subscribes one user to a list, creating the list if it does not yet exist. Optional +/// preferences apply to this subscription only. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Lists/Subscriptions/SubscriptionUnsubscribeUserParams.cs b/src/TryCourier/Models/Lists/Subscriptions/SubscriptionUnsubscribeUserParams.cs index 620f4242..183ffa93 100644 --- a/src/TryCourier/Models/Lists/Subscriptions/SubscriptionUnsubscribeUserParams.cs +++ b/src/TryCourier/Models/Lists/Subscriptions/SubscriptionUnsubscribeUserParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Lists.Subscriptions; /// -/// Delete a subscription to a list by list ID and user ID. +/// Removes one user's subscription to a list, addressed by list id and user id. +/// The user's profile and other subscriptions are separate resources. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Messages/MessageCancelParams.cs b/src/TryCourier/Models/Messages/MessageCancelParams.cs index c2ea2e3e..d5260add 100644 --- a/src/TryCourier/Models/Messages/MessageCancelParams.cs +++ b/src/TryCourier/Models/Messages/MessageCancelParams.cs @@ -9,10 +9,8 @@ namespace TryCourier.Models.Messages; /// -/// Cancel a message that is currently in the process of being delivered. A well-formatted -/// API call to the cancel message API will return either `200` status code for a -/// successful cancellation or `409` status code for an unsuccessful cancellation. -/// Both cases will include the actual message record in the response body (see details below). +/// Cancels a message that is still in the delivery pipeline and returns the message +/// record with its resulting canceled or failed status. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Messages/MessageContentParams.cs b/src/TryCourier/Models/Messages/MessageContentParams.cs index 4006899b..0941a4c9 100644 --- a/src/TryCourier/Models/Messages/MessageContentParams.cs +++ b/src/TryCourier/Models/Messages/MessageContentParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Messages; /// -/// Get message content +/// Returns the rendered content Courier delivered for a message, broken out per +/// channel, to confirm what the recipient received. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Messages/MessageHistoryParams.cs b/src/TryCourier/Models/Messages/MessageHistoryParams.cs index e3d52ca5..91454aba 100644 --- a/src/TryCourier/Models/Messages/MessageHistoryParams.cs +++ b/src/TryCourier/Models/Messages/MessageHistoryParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Messages; /// -/// Fetch the array of events of a message you've previously sent. +/// Returns the ordered event history for a sent message, one entry per status transition +/// with its timestamp. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Messages/MessageListParams.cs b/src/TryCourier/Models/Messages/MessageListParams.cs index 9f0d3408..4a2a9d87 100644 --- a/src/TryCourier/Models/Messages/MessageListParams.cs +++ b/src/TryCourier/Models/Messages/MessageListParams.cs @@ -10,7 +10,8 @@ namespace TryCourier.Models.Messages; /// -/// Fetch the statuses of messages you've previously sent. +/// Returns previously sent messages, most recent first, each carrying its status, +/// recipient, channel, and provider. Paged by cursor. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Messages/MessageResendParams.cs b/src/TryCourier/Models/Messages/MessageResendParams.cs index ba1c23ba..fbf359fe 100644 --- a/src/TryCourier/Models/Messages/MessageResendParams.cs +++ b/src/TryCourier/Models/Messages/MessageResendParams.cs @@ -9,10 +9,8 @@ namespace TryCourier.Models.Messages; /// -/// Resend a previously sent message. The original send request is loaded from storage -/// and a brand-new send is enqueued for the same recipient and content, producing -/// a **new** `messageId` — the original message is not modified. Throttled by a per-message -/// rate limit; a repeat inside the limit window returns `429 Too Many Requests`. +/// Resends a previously sent message to the same recipient and content, returning +/// a new messageId. The original send request is not modified. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Messages/MessageRetrieveParams.cs b/src/TryCourier/Models/Messages/MessageRetrieveParams.cs index ee51e5f7..a077519f 100644 --- a/src/TryCourier/Models/Messages/MessageRetrieveParams.cs +++ b/src/TryCourier/Models/Messages/MessageRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Messages; /// -/// Fetch the status of a message you've previously sent. +/// Returns a sent message's status, recipient, event, and per-provider delivery +/// detail, with timestamps for enqueued, sent, delivered, opened, and clicked. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/MsTeams.cs b/src/TryCourier/Models/MsTeams.cs index d514a7bc..ead8302f 100644 --- a/src/TryCourier/Models/MsTeams.cs +++ b/src/TryCourier/Models/MsTeams.cs @@ -369,7 +369,10 @@ JsonSerializerOptions options var element = JsonSerializer.Deserialize(ref reader, options); try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize( + element, + options + ); if (deserialized != null) { deserialized.Validate(); @@ -383,7 +386,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -397,7 +400,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -411,10 +414,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( - element, - options - ); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -428,7 +428,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize( + var deserialized = JsonSerializer.Deserialize( element, options ); diff --git a/src/TryCourier/Models/Notifications/Checks/CheckDeleteParams.cs b/src/TryCourier/Models/Notifications/Checks/CheckDeleteParams.cs index 3e3d4156..9cd9bba1 100644 --- a/src/TryCourier/Models/Notifications/Checks/CheckDeleteParams.cs +++ b/src/TryCourier/Models/Notifications/Checks/CheckDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Notifications.Checks; /// -/// Cancel a submission for a notification template. +/// Cancels a pending template submission, withdrawing it from the approval workflow. +/// The template stays in draft and can be resubmitted later. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/Checks/CheckListParams.cs b/src/TryCourier/Models/Notifications/Checks/CheckListParams.cs index 4fec2f71..d75f5eef 100644 --- a/src/TryCourier/Models/Notifications/Checks/CheckListParams.cs +++ b/src/TryCourier/Models/Notifications/Checks/CheckListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Notifications.Checks; /// -/// Retrieve the submission checks for a notification template. +/// Returns the approval checks recorded for a template submission, each with its +/// pass or fail result. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/Checks/CheckUpdateParams.cs b/src/TryCourier/Models/Notifications/Checks/CheckUpdateParams.cs index d82a968c..f73410a6 100644 --- a/src/TryCourier/Models/Notifications/Checks/CheckUpdateParams.cs +++ b/src/TryCourier/Models/Notifications/Checks/CheckUpdateParams.cs @@ -11,7 +11,8 @@ namespace TryCourier.Models.Notifications.Checks; /// -/// Replace the submission checks for a notification template. +/// Replaces the approval checks on a template submission with the complete set supplied +/// in the request body. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationArchiveParams.cs b/src/TryCourier/Models/Notifications/NotificationArchiveParams.cs index ced8325b..254b11b5 100644 --- a/src/TryCourier/Models/Notifications/NotificationArchiveParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationArchiveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Notifications; /// -/// Archive a notification template. +/// Archives a notification template, preventing new sends from referencing it. The +/// template stays retrievable for its version history. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationDuplicateParams.cs b/src/TryCourier/Models/Notifications/NotificationDuplicateParams.cs index 894c3b44..8dd495bd 100644 --- a/src/TryCourier/Models/Notifications/NotificationDuplicateParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationDuplicateParams.cs @@ -9,12 +9,8 @@ namespace TryCourier.Models.Notifications; /// -/// Duplicate a notification template. Creates a standalone copy within the same workspace -/// and environment, with " COPY" appended to the title. The copy clones the source -/// draft's tags, brand, subscription topic, routing strategy, channels, and content, -/// and is always created as a standalone template (it is not linked to any journey -/// or broadcast, even if the source was). Templates that are scoped to a journey -/// or a broadcast cannot be duplicated through this endpoint. +/// Copies a notification template within the same workspace and environment, appending +/// " COPY" to the title. The copy is standalone and independently editable. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationListParams.cs b/src/TryCourier/Models/Notifications/NotificationListParams.cs index e77c5547..2e10f10b 100644 --- a/src/TryCourier/Models/Notifications/NotificationListParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Notifications; /// -/// List notification templates in your workspace. +/// Lists the workspace's notification templates. Each carries a name, tags, brand, +/// routing, and its draft or published state. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationListVersionsParams.cs b/src/TryCourier/Models/Notifications/NotificationListVersionsParams.cs index 77cee6cb..5df0a350 100644 --- a/src/TryCourier/Models/Notifications/NotificationListVersionsParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationListVersionsParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Notifications; /// -/// List versions of a notification template. +/// Returns a notification template's published versions, most recent first, for +/// comparison or rollback. Paged. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationPutContentParams.cs b/src/TryCourier/Models/Notifications/NotificationPutContentParams.cs index 3e6c3acc..dfaecf5d 100644 --- a/src/TryCourier/Models/Notifications/NotificationPutContentParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationPutContentParams.cs @@ -12,8 +12,8 @@ namespace TryCourier.Models.Notifications; /// -/// Replace the elemental content of a notification template. Overwrites all elements -/// in the template with the provided content. Only supported for V2 (elemental) templates. +/// Replaces all Elemental content in a template, overwriting every existing element. +/// Supported for V2 templates only, not V1 blocks and channels. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationPutElementParams.cs b/src/TryCourier/Models/Notifications/NotificationPutElementParams.cs index 1c27f47e..fbc86bd0 100644 --- a/src/TryCourier/Models/Notifications/NotificationPutElementParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationPutElementParams.cs @@ -11,8 +11,8 @@ namespace TryCourier.Models.Notifications; /// -/// Update a single element within a notification template. Only supported for V2 -/// (elemental) templates. +/// Replaces one Elemental element in a template, addressed by its element id. Supported +/// for V2 templates only, not V1 blocks and channels. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationPutLocaleParams.cs b/src/TryCourier/Models/Notifications/NotificationPutLocaleParams.cs index ed3434b8..97e36ea7 100644 --- a/src/TryCourier/Models/Notifications/NotificationPutLocaleParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationPutLocaleParams.cs @@ -12,8 +12,8 @@ namespace TryCourier.Models.Notifications; /// -/// Set locale-specific content overrides for a notification template. Each element -/// override must reference an existing element by ID. Only supported for V2 (elemental) templates. +/// Sets locale-specific content overrides for a template. Each override must reference +/// an element that already exists in the default content. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationReplaceParams.cs b/src/TryCourier/Models/Notifications/NotificationReplaceParams.cs index 64d44043..3449ecfa 100644 --- a/src/TryCourier/Models/Notifications/NotificationReplaceParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationReplaceParams.cs @@ -12,7 +12,8 @@ namespace TryCourier.Models.Notifications; /// -/// Replace a notification template. All fields are required. +/// Replaces a notification template in full, so send every field rather than only +/// the ones you want changed. Publish separately to make it live. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Notifications/NotificationRetrieveContentParams.cs b/src/TryCourier/Models/Notifications/NotificationRetrieveContentParams.cs index 8db8c34e..986780cd 100644 --- a/src/TryCourier/Models/Notifications/NotificationRetrieveContentParams.cs +++ b/src/TryCourier/Models/Notifications/NotificationRetrieveContentParams.cs @@ -9,9 +9,8 @@ namespace TryCourier.Models.Notifications; /// -/// Retrieve the content of a notification template. The response shape depends on -/// whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use -/// the `version` query parameter to select draft, published, or a specific historical version. +/// Returns a template's content and checksum. V2 templates return Elemental elements, +/// while V1 templates return blocks and channels instead. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Profiles/Lists/ListDeleteParams.cs b/src/TryCourier/Models/Profiles/Lists/ListDeleteParams.cs index 0730da8a..2d191dff 100644 --- a/src/TryCourier/Models/Profiles/Lists/ListDeleteParams.cs +++ b/src/TryCourier/Models/Profiles/Lists/ListDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Profiles.Lists; /// -/// Removes all list subscriptions for given user. +/// Removes every list subscription for a user at once. Their profile and preferences +/// are untouched, so this only affects list-targeted sends. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Profiles/Lists/ListRetrieveParams.cs b/src/TryCourier/Models/Profiles/Lists/ListRetrieveParams.cs index 50659cfd..a8323c94 100644 --- a/src/TryCourier/Models/Profiles/Lists/ListRetrieveParams.cs +++ b/src/TryCourier/Models/Profiles/Lists/ListRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Profiles.Lists; /// -/// Returns the subscribed lists for a specified user. +/// Returns the lists a user is subscribed to, with paging. Use it to check what a +/// recipient will receive before sending to a list. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Profiles/Lists/ListSubscribeParams.cs b/src/TryCourier/Models/Profiles/Lists/ListSubscribeParams.cs index af5ab689..774b129c 100644 --- a/src/TryCourier/Models/Profiles/Lists/ListSubscribeParams.cs +++ b/src/TryCourier/Models/Profiles/Lists/ListSubscribeParams.cs @@ -11,8 +11,8 @@ namespace TryCourier.Models.Profiles.Lists; /// -/// Subscribes the given user to one or more lists. If the list does not exist, it -/// will be created. +/// Subscribes a user to one or more lists, creating any list that does not yet exist. +/// Optional preferences apply to each subscription. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Profiles/ProfileCreateParams.cs b/src/TryCourier/Models/Profiles/ProfileCreateParams.cs index b69e6046..6e8657e9 100644 --- a/src/TryCourier/Models/Profiles/ProfileCreateParams.cs +++ b/src/TryCourier/Models/Profiles/ProfileCreateParams.cs @@ -10,8 +10,8 @@ namespace TryCourier.Models.Profiles; /// -/// Merge the supplied values with an existing profile or create a new profile if -/// one doesn't already exist. +/// Merges the supplied values into a user's profile, creating it if absent and leaving +/// any key you omit untouched. Prefer this for everyday writes. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Profiles/ProfileDeleteParams.cs b/src/TryCourier/Models/Profiles/ProfileDeleteParams.cs index c21a2313..7b0aedb3 100644 --- a/src/TryCourier/Models/Profiles/ProfileDeleteParams.cs +++ b/src/TryCourier/Models/Profiles/ProfileDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Profiles; /// -/// Deletes the specified user profile. +/// Deletes a user's profile and stored contact details. List subscriptions and preferences +/// are separate resources, so remove those too if required. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Profiles/ProfileReplaceParams.cs b/src/TryCourier/Models/Profiles/ProfileReplaceParams.cs index b4105e4c..375482dc 100644 --- a/src/TryCourier/Models/Profiles/ProfileReplaceParams.cs +++ b/src/TryCourier/Models/Profiles/ProfileReplaceParams.cs @@ -10,11 +10,8 @@ namespace TryCourier.Models.Profiles; /// -/// When using `PUT`, be sure to include all the key-value pairs required by the -/// recipient's profile. Any key-value pairs that exist in the profile but fail -/// to be included in the `PUT` request will be removed from the profile. Remember, -/// a `PUT` update is a full replacement of the data. For partial updates, use the -/// [Patch](https://www.courier.com/docs/reference/profiles/patch/) request. +/// Overwrites a user profile in full, removing any key absent from the request body. +/// Use the patch endpoint when changing a single field. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Profiles/ProfileRetrieveParams.cs b/src/TryCourier/Models/Profiles/ProfileRetrieveParams.cs index d491533b..180e8930 100644 --- a/src/TryCourier/Models/Profiles/ProfileRetrieveParams.cs +++ b/src/TryCourier/Models/Profiles/ProfileRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Profiles; /// -/// Returns the specified user profile. +/// Returns a user's stored profile and preferences, including the email address, +/// phone number, and push tokens Courier can reach them on. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Profiles/ProfileUpdateParams.cs b/src/TryCourier/Models/Profiles/ProfileUpdateParams.cs index 288e55fa..6abd8641 100644 --- a/src/TryCourier/Models/Profiles/ProfileUpdateParams.cs +++ b/src/TryCourier/Models/Profiles/ProfileUpdateParams.cs @@ -12,7 +12,8 @@ namespace TryCourier.Models.Profiles; /// -/// Update a profile +/// Applies a JSON Patch to a user profile, adding, removing, or replacing individual +/// fields without sending the whole object. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Providers/Catalog/CatalogListParams.cs b/src/TryCourier/Models/Providers/Catalog/CatalogListParams.cs index 60e1ca6f..7a5deb58 100644 --- a/src/TryCourier/Models/Providers/Catalog/CatalogListParams.cs +++ b/src/TryCourier/Models/Providers/Catalog/CatalogListParams.cs @@ -9,9 +9,8 @@ namespace TryCourier.Models.Providers.Catalog; /// -/// Returns the catalog of available provider types with their display names, descriptions, -/// and configuration schema fields (snake_case, with `type` and `required`). Providers -/// with no configurable schema return only `provider`, `name`, and `description`. +/// Returns the provider types Courier supports, each with a display name, description, +/// and the configuration fields it requires. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Providers/ProviderCreateParams.cs b/src/TryCourier/Models/Providers/ProviderCreateParams.cs index 8639231a..a511af97 100644 --- a/src/TryCourier/Models/Providers/ProviderCreateParams.cs +++ b/src/TryCourier/Models/Providers/ProviderCreateParams.cs @@ -10,8 +10,8 @@ namespace TryCourier.Models.Providers; /// -/// Create a new provider configuration. The `provider` field must be a known Courier -/// provider key (see catalog). +/// Configures a provider integration from a Courier provider key and its settings. +/// Check the catalog endpoint for the schema each provider expects. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Providers/ProviderDeleteParams.cs b/src/TryCourier/Models/Providers/ProviderDeleteParams.cs index 75cc0b5d..9cf3f032 100644 --- a/src/TryCourier/Models/Providers/ProviderDeleteParams.cs +++ b/src/TryCourier/Models/Providers/ProviderDeleteParams.cs @@ -9,8 +9,8 @@ namespace TryCourier.Models.Providers; /// -/// Delete a provider configuration. Returns 409 if the provider is still referenced -/// by routing or notifications. +/// Deletes a provider configuration, which fails while routing strategies or templates +/// still reference it. Update those references first. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Providers/ProviderListParams.cs b/src/TryCourier/Models/Providers/ProviderListParams.cs index 5560a4e1..2ab102d0 100644 --- a/src/TryCourier/Models/Providers/ProviderListParams.cs +++ b/src/TryCourier/Models/Providers/ProviderListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Providers; /// -/// List configured provider integrations for the current workspace. Supports cursor-based pagination. +/// Lists the provider integrations configured in the workspace, one entry per channel +/// and provider key with its alias and settings. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Providers/ProviderRetrieveParams.cs b/src/TryCourier/Models/Providers/ProviderRetrieveParams.cs index 823bea52..f9d3b2e5 100644 --- a/src/TryCourier/Models/Providers/ProviderRetrieveParams.cs +++ b/src/TryCourier/Models/Providers/ProviderRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Providers; /// -/// Fetch a single provider configuration by ID. +/// Returns one configured provider by id, including its channel, provider key, alias, +/// title, and current settings. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Providers/ProviderUpdateParams.cs b/src/TryCourier/Models/Providers/ProviderUpdateParams.cs index 58f05611..d2d8c3cc 100644 --- a/src/TryCourier/Models/Providers/ProviderUpdateParams.cs +++ b/src/TryCourier/Models/Providers/ProviderUpdateParams.cs @@ -10,11 +10,8 @@ namespace TryCourier.Models.Providers; /// -/// Replace an existing provider configuration. The `provider` key is required and -/// determines which provider-specific settings schema is applied. All other fields -/// are optional — omitted fields are cleared from the stored configuration (this -/// is a full replacement, not a partial merge). Changing the provider type for an -/// existing configuration is not supported. +/// Replaces a provider's configuration in full, clearing any field you omit rather +/// than merging it. Send the complete settings object. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Requests/RequestArchiveParams.cs b/src/TryCourier/Models/Requests/RequestArchiveParams.cs index 808a53bf..5062cb28 100644 --- a/src/TryCourier/Models/Requests/RequestArchiveParams.cs +++ b/src/TryCourier/Models/Requests/RequestArchiveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Requests; /// -/// Archive message +/// Archives a send request by its request id. Use it to remove test sends or superseded +/// requests from the message list without deleting them. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/RoutingStrategies/RoutingStrategyListNotificationsParams.cs b/src/TryCourier/Models/RoutingStrategies/RoutingStrategyListNotificationsParams.cs index c0e056f0..1dce5adb 100644 --- a/src/TryCourier/Models/RoutingStrategies/RoutingStrategyListNotificationsParams.cs +++ b/src/TryCourier/Models/RoutingStrategies/RoutingStrategyListNotificationsParams.cs @@ -9,8 +9,8 @@ namespace TryCourier.Models.RoutingStrategies; /// -/// List notification templates associated with a routing strategy. Includes template -/// metadata only, not full content. +/// Returns the notification templates using a routing strategy, with paging. Check +/// this before changing a strategy that templates depend on. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/RoutingStrategies/RoutingStrategyRetrieveParams.cs b/src/TryCourier/Models/RoutingStrategies/RoutingStrategyRetrieveParams.cs index d3f80da0..adbfbfb0 100644 --- a/src/TryCourier/Models/RoutingStrategies/RoutingStrategyRetrieveParams.cs +++ b/src/TryCourier/Models/RoutingStrategies/RoutingStrategyRetrieveParams.cs @@ -9,8 +9,8 @@ namespace TryCourier.Models.RoutingStrategies; /// -/// Retrieve a routing strategy by ID. Returns the full entity including routing -/// content and metadata. +/// Returns one routing strategy by id with its name, tags, channels, and the routing +/// rules that decide provider order and fallback. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Send/SendMessageParams.cs b/src/TryCourier/Models/Send/SendMessageParams.cs index b29b2ee5..bec39bba 100644 --- a/src/TryCourier/Models/Send/SendMessageParams.cs +++ b/src/TryCourier/Models/Send/SendMessageParams.cs @@ -13,7 +13,8 @@ namespace TryCourier.Models.Send; /// -/// Send a message to one or more recipients. +/// Sends a message to one or more recipients and returns a requestId. Courier routes +/// it to email, SMS, push, chat, or in-app based on your rules. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that @@ -2012,7 +2013,7 @@ JsonSerializerOptions options var element = JsonSerializer.Deserialize(ref reader, options); try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2040,7 +2041,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2054,7 +2055,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2068,7 +2069,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2082,7 +2083,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2096,7 +2097,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2110,7 +2111,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2625,7 +2626,7 @@ JsonSerializerOptions options var element = JsonSerializer.Deserialize(ref reader, options); try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2653,7 +2654,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2667,7 +2668,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2681,7 +2682,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2695,7 +2696,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2709,7 +2710,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); @@ -2723,7 +2724,7 @@ JsonSerializerOptions options try { - var deserialized = JsonSerializer.Deserialize(element, options); + var deserialized = JsonSerializer.Deserialize(element, options); if (deserialized != null) { deserialized.Validate(); diff --git a/src/TryCourier/Models/Tenants/Preferences/Items/ItemDeleteParams.cs b/src/TryCourier/Models/Tenants/Preferences/Items/ItemDeleteParams.cs index 576b7841..4ff84230 100644 --- a/src/TryCourier/Models/Tenants/Preferences/Items/ItemDeleteParams.cs +++ b/src/TryCourier/Models/Tenants/Preferences/Items/ItemDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Tenants.Preferences.Items; /// -/// Remove Default Preferences For Topic +/// Removes a tenant's default preference for one subscription topic, addressed by +/// tenant id and topic id. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/Preferences/Items/ItemUpdateParams.cs b/src/TryCourier/Models/Tenants/Preferences/Items/ItemUpdateParams.cs index f2d0140d..1aaf3303 100644 --- a/src/TryCourier/Models/Tenants/Preferences/Items/ItemUpdateParams.cs +++ b/src/TryCourier/Models/Tenants/Preferences/Items/ItemUpdateParams.cs @@ -13,7 +13,8 @@ namespace TryCourier.Models.Tenants.Preferences.Items; /// -/// Create or Replace Default Preferences For Topic +/// Sets a tenant's default opt-in status for one subscription topic, which applies +/// to every member unless a user sets their own override. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/Templates/TemplateDeleteParams.cs b/src/TryCourier/Models/Tenants/Templates/TemplateDeleteParams.cs index 8660854e..65fa9f11 100644 --- a/src/TryCourier/Models/Tenants/Templates/TemplateDeleteParams.cs +++ b/src/TryCourier/Models/Tenants/Templates/TemplateDeleteParams.cs @@ -9,12 +9,8 @@ namespace TryCourier.Models.Tenants.Templates; /// -/// Deletes the tenant's notification template with the given `template_id`. -/// -/// Returns **204 No Content** with an empty body on success. -/// -/// Returns **404** if there is no template with this ID for the tenant, including -/// a second `DELETE` after a successful removal. +/// Deletes a tenant's notification template by id. Sends for that tenant then use +/// the workspace template registered under the same id. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/Templates/TemplateListParams.cs b/src/TryCourier/Models/Tenants/Templates/TemplateListParams.cs index 0e4900bd..41e203dc 100644 --- a/src/TryCourier/Models/Tenants/Templates/TemplateListParams.cs +++ b/src/TryCourier/Models/Tenants/Templates/TemplateListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Tenants.Templates; /// -/// List Templates in Tenant +/// Lists a tenant's notification templates, each carrying its version and published +/// timestamp. Paged. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/Templates/TemplatePublishParams.cs b/src/TryCourier/Models/Tenants/Templates/TemplatePublishParams.cs index 95357fde..b44c7284 100644 --- a/src/TryCourier/Models/Tenants/Templates/TemplatePublishParams.cs +++ b/src/TryCourier/Models/Tenants/Templates/TemplatePublishParams.cs @@ -10,10 +10,8 @@ namespace TryCourier.Models.Tenants.Templates; /// -/// Publishes a specific version of a notification template for a tenant. -/// -/// The template must already exist in the tenant's notification map. If no -/// version is specified, defaults to publishing the "latest" version. +/// Publishes a version of a tenant's notification template, making it the content +/// that tenant's sends render from until you publish another. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/Templates/TemplateReplaceParams.cs b/src/TryCourier/Models/Tenants/Templates/TemplateReplaceParams.cs index 4e5ec26f..853899df 100644 --- a/src/TryCourier/Models/Tenants/Templates/TemplateReplaceParams.cs +++ b/src/TryCourier/Models/Tenants/Templates/TemplateReplaceParams.cs @@ -10,13 +10,8 @@ namespace TryCourier.Models.Tenants.Templates; /// -/// Creates or updates a notification template for a tenant. -/// -/// If the template already exists for the tenant, it will be updated (200). -/// Otherwise, a new template is created (201). -/// -/// Optionally publishes the template immediately if the `published` flag is -/// set to true. +/// Creates or updates a notification template scoped to one tenant, letting a tenant +/// override the content the workspace template would send. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/Templates/TemplateRetrieveParams.cs b/src/TryCourier/Models/Tenants/Templates/TemplateRetrieveParams.cs index 0a3acb2d..987ce692 100644 --- a/src/TryCourier/Models/Tenants/Templates/TemplateRetrieveParams.cs +++ b/src/TryCourier/Models/Tenants/Templates/TemplateRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Tenants.Templates; /// -/// Get a Template in Tenant +/// Returns a tenant's notification template with its content, version, and created, +/// updated, and published timestamps. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/Templates/Versions/VersionRetrieveParams.cs b/src/TryCourier/Models/Tenants/Templates/Versions/VersionRetrieveParams.cs index 5bb277d4..c3c6efd0 100644 --- a/src/TryCourier/Models/Tenants/Templates/Versions/VersionRetrieveParams.cs +++ b/src/TryCourier/Models/Tenants/Templates/Versions/VersionRetrieveParams.cs @@ -9,11 +9,8 @@ namespace TryCourier.Models.Tenants.Templates.Versions; /// -/// Fetches a specific version of a tenant template. -/// -/// Supports the following version formats: - `latest` - The most recent version -/// of the template - `published` - The currently published version - `v{version}` -/// - A specific version (e.g., "v1", "v2", "v1.0.0") +/// Returns one version of a tenant template, addressed by version number or by latest, +/// with its content and publish timestamp. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/TenantDeleteParams.cs b/src/TryCourier/Models/Tenants/TenantDeleteParams.cs index 9e0febc3..27a78e00 100644 --- a/src/TryCourier/Models/Tenants/TenantDeleteParams.cs +++ b/src/TryCourier/Models/Tenants/TenantDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Tenants; /// -/// Delete a Tenant +/// Deletes a tenant. Its members' workspace-level profiles and preferences live +/// outside the tenant and are managed separately. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/TenantListParams.cs b/src/TryCourier/Models/Tenants/TenantListParams.cs index dad60cc6..80bbc833 100644 --- a/src/TryCourier/Models/Tenants/TenantListParams.cs +++ b/src/TryCourier/Models/Tenants/TenantListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Tenants; /// -/// Get a List of Tenants +/// Lists the workspace's tenants, each carrying a name, parent tenant, properties, +/// and default preferences. Paged. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/TenantListUsersParams.cs b/src/TryCourier/Models/Tenants/TenantListUsersParams.cs index b4def1e4..ae43fa0f 100644 --- a/src/TryCourier/Models/Tenants/TenantListUsersParams.cs +++ b/src/TryCourier/Models/Tenants/TenantListUsersParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Tenants; /// -/// Get Users in Tenant +/// Returns the users belonging to a tenant with cursor paging. Use it to see who +/// a tenant-scoped send will reach. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/TenantRetrieveParams.cs b/src/TryCourier/Models/Tenants/TenantRetrieveParams.cs index d0a0ff12..d42a5579 100644 --- a/src/TryCourier/Models/Tenants/TenantRetrieveParams.cs +++ b/src/TryCourier/Models/Tenants/TenantRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Tenants; /// -/// Get a Tenant +/// Returns one tenant with its name, parent tenant id, default preferences, properties, +/// and the user profile applied to its members. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Tenants/TenantUpdateParams.cs b/src/TryCourier/Models/Tenants/TenantUpdateParams.cs index 6f7d0683..cae7b780 100644 --- a/src/TryCourier/Models/Tenants/TenantUpdateParams.cs +++ b/src/TryCourier/Models/Tenants/TenantUpdateParams.cs @@ -10,7 +10,8 @@ namespace TryCourier.Models.Tenants; /// -/// Create or Replace a Tenant +/// Creates or replaces a tenant from a name, parent, brand, properties, and default +/// preferences supplied in the request body. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Translations/TranslationRetrieveParams.cs b/src/TryCourier/Models/Translations/TranslationRetrieveParams.cs index 7d9bcc12..ba2a9f9b 100644 --- a/src/TryCourier/Models/Translations/TranslationRetrieveParams.cs +++ b/src/TryCourier/Models/Translations/TranslationRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Translations; /// -/// Get translations by locale +/// Returns the translation strings stored for one domain and locale, for use in localized +/// notification content. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Translations/TranslationUpdateParams.cs b/src/TryCourier/Models/Translations/TranslationUpdateParams.cs index af0f3445..e6bfd9fe 100644 --- a/src/TryCourier/Models/Translations/TranslationUpdateParams.cs +++ b/src/TryCourier/Models/Translations/TranslationUpdateParams.cs @@ -10,7 +10,8 @@ namespace TryCourier.Models.Translations; /// -/// Update a translation +/// Uploads the translation strings for one domain and locale. Courier uses them +/// to render localized content for recipients in that locale. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Preferences/PreferenceBulkReplaceParams.cs b/src/TryCourier/Models/Users/Preferences/PreferenceBulkReplaceParams.cs index efc20e2b..f480b444 100644 --- a/src/TryCourier/Models/Users/Preferences/PreferenceBulkReplaceParams.cs +++ b/src/TryCourier/Models/Users/Preferences/PreferenceBulkReplaceParams.cs @@ -13,23 +13,8 @@ namespace TryCourier.Models.Users.Preferences; /// -/// Replace a user's complete set of preference overrides in a single request. The -/// topics in the request body become the recipient's entire set of overrides: listed -/// topics are created or updated, and every existing override that is not included -/// in the body is reset to its topic default. Submitting an empty `topics` array -/// is a valid clear-all that resets every existing override. -/// -/// This operation is validation-atomic (all-or-nothing): structural validation -/// fails fast with a single `400`, and if any topic is semantically invalid (an unknown -/// topic, a `REQUIRED` topic that cannot be opted out, or a custom routing request -/// that is not available on the workspace's plan) the request returns a single `400` -/// aggregating every failure in `errors` and writes nothing. On success it returns -/// `200` with `items` (the complete resulting override set) and `deleted` (the ids -/// of the overrides that were reset to default). -/// -/// Every `topic_id` in the response — in `items`, `deleted`, and any `errors` -/// — is returned in Courier's canonical topic id form, regardless of the form supplied -/// in the request. +/// Replaces a user's entire set of preference overrides. Any topic you leave out +/// is reset to its default, so send the full set rather than a subset. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Preferences/PreferenceBulkUpdateParams.cs b/src/TryCourier/Models/Users/Preferences/PreferenceBulkUpdateParams.cs index b0124542..9a9f17ba 100644 --- a/src/TryCourier/Models/Users/Preferences/PreferenceBulkUpdateParams.cs +++ b/src/TryCourier/Models/Users/Preferences/PreferenceBulkUpdateParams.cs @@ -13,20 +13,8 @@ namespace TryCourier.Models.Users.Preferences; /// -/// Additively create or update a user's preferences for one or more subscription -/// topics in a single request. Only the topics included in the request body are -/// created or updated; any existing overrides for topics not listed are left untouched. -/// -/// Structural validation of the request body fails fast with a single `400`. -/// Beyond that, each topic is processed independently (partial-success, not all-or-nothing): -/// valid topics are written and returned in `items`, while topics that cannot be -/// applied are collected in `errors` with a per-topic `reason` (for example an unknown -/// topic, a `REQUIRED` topic that cannot be opted out, a custom routing request that -/// is not available on the workspace's plan, or a write failure). The request therefore -/// returns `200` with both lists whenever the body is structurally valid. -/// -/// Every `topic_id` in the response — in both `items` and `errors` — is returned -/// in Courier's canonical topic id form, regardless of the form supplied in the request. +/// Adds or updates a user's preferences for several subscription topics at once. +/// Topics you leave out keep whatever they were set to before. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Preferences/PreferenceDeleteTopicParams.cs b/src/TryCourier/Models/Users/Preferences/PreferenceDeleteTopicParams.cs index a840d1b3..c0a9aa7a 100644 --- a/src/TryCourier/Models/Users/Preferences/PreferenceDeleteTopicParams.cs +++ b/src/TryCourier/Models/Users/Preferences/PreferenceDeleteTopicParams.cs @@ -9,9 +9,8 @@ namespace TryCourier.Models.Users.Preferences; /// -/// Remove a user's preferences for a specific subscription topic, resetting the topic -/// to its effective default. This operation is idempotent: deleting a preference -/// that does not exist succeeds with no error. +/// Removes a user's override for one subscription topic, resetting it to the effective +/// default from the tenant or workspace. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Preferences/PreferenceRetrieveParams.cs b/src/TryCourier/Models/Users/Preferences/PreferenceRetrieveParams.cs index 066c769b..2aca1f3b 100644 --- a/src/TryCourier/Models/Users/Preferences/PreferenceRetrieveParams.cs +++ b/src/TryCourier/Models/Users/Preferences/PreferenceRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Preferences; /// -/// Fetch all user preferences. +/// Returns a user's preference overrides with paging, one entry per subscription +/// topic they have set a choice for. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Preferences/PreferenceRetrieveTopicParams.cs b/src/TryCourier/Models/Users/Preferences/PreferenceRetrieveTopicParams.cs index 01bea209..8196137f 100644 --- a/src/TryCourier/Models/Users/Preferences/PreferenceRetrieveTopicParams.cs +++ b/src/TryCourier/Models/Users/Preferences/PreferenceRetrieveTopicParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Preferences; /// -/// Fetch user preferences for a specific subscription topic. +/// Returns a user's opt-in status and channel choices for one subscription topic, +/// or the effective default if they have set no override. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Preferences/PreferenceUpdateOrCreateTopicParams.cs b/src/TryCourier/Models/Users/Preferences/PreferenceUpdateOrCreateTopicParams.cs index cda1a612..d345c3dd 100644 --- a/src/TryCourier/Models/Users/Preferences/PreferenceUpdateOrCreateTopicParams.cs +++ b/src/TryCourier/Models/Users/Preferences/PreferenceUpdateOrCreateTopicParams.cs @@ -12,7 +12,8 @@ namespace TryCourier.Models.Users.Preferences; /// -/// Update or Create user preferences for a specific subscription topic. +/// Sets a user's opt-in status and channel choices for one subscription topic, overriding +/// the tenant default for that topic only. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that @@ -193,6 +194,10 @@ public override int GetHashCode() )] public sealed record class PreferenceUpdateOrCreateTopicParamsTopic : JsonModel { + /// + /// The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level + /// default, not a user choice; the API rejects opting a user out of a REQUIRED topic. + /// public required ApiEnum Status { get @@ -204,7 +209,8 @@ public required ApiEnum Status } /// - /// The Channels a user has chosen to receive notifications through for this topic + /// The channels to deliver this topic on when has_custom_routing is true. One + /// or more of: direct_message, email, push, sms, webhook, inbox. /// public IReadOnlyList>? CustomRouting { @@ -224,6 +230,10 @@ public IReadOnlyList>? CustomRouting } } + /// + /// Set to true to route this topic to the channels in custom_routing instead + /// of the topic's default routing. + /// public bool? HasCustomRouting { get diff --git a/src/TryCourier/Models/Users/Preferences/TopicPreference.cs b/src/TryCourier/Models/Users/Preferences/TopicPreference.cs index 99bd7d3c..ff92caee 100644 --- a/src/TryCourier/Models/Users/Preferences/TopicPreference.cs +++ b/src/TryCourier/Models/Users/Preferences/TopicPreference.cs @@ -11,6 +11,10 @@ namespace TryCourier.Models.Users.Preferences; [JsonConverter(typeof(JsonModelConverter))] public sealed record class TopicPreference : JsonModel { + /// + /// The topic's default status, returned on reads. It applies whenever the user + /// has no override of their own (status equals this value). + /// public required ApiEnum DefaultStatus { get @@ -23,6 +27,11 @@ public required ApiEnum DefaultStatus init { this._rawData.Set("default_status", value); } } + /// + /// The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect + /// the user's own choice; REQUIRED is a topic-level default set in the preferences + /// editor, not a user choice. + /// public required ApiEnum Status { get @@ -33,6 +42,9 @@ public required ApiEnum Status init { this._rawData.Set("status", value); } } + /// + /// The unique identifier of the subscription topic this preference applies to. + /// public required string TopicID { get @@ -43,6 +55,9 @@ public required string TopicID init { this._rawData.Set("topic_id", value); } } + /// + /// The display name of the subscription topic, returned on reads. + /// public required string TopicName { get @@ -54,7 +69,9 @@ public required string TopicName } /// - /// The Channels a user has chosen to receive notifications through for this topic + /// The channels the user has chosen to receive this topic on, present only when + /// has_custom_routing is true. One or more of: direct_message, email, push, + /// sms, webhook, inbox. /// public IReadOnlyList>? CustomRouting { @@ -74,6 +91,10 @@ public IReadOnlyList>? CustomRouting } } + /// + /// Whether the user has chosen specific delivery channels for this topic (listed + /// in custom_routing) rather than the topic's default routing. + /// public bool? HasCustomRouting { get diff --git a/src/TryCourier/Models/Users/Tenants/TenantAddMultipleParams.cs b/src/TryCourier/Models/Users/Tenants/TenantAddMultipleParams.cs index 09c39cec..a37814fb 100644 --- a/src/TryCourier/Models/Users/Tenants/TenantAddMultipleParams.cs +++ b/src/TryCourier/Models/Users/Tenants/TenantAddMultipleParams.cs @@ -12,9 +12,8 @@ namespace TryCourier.Models.Users.Tenants; /// -/// This endpoint is used to add a user to multiple tenants in one call. A custom -/// profile can also be supplied for each tenant. This profile will be merged with -/// the user's main profile when sending to the user with that tenant. +/// Adds a user to several tenants in one call, each optionally with a per-tenant +/// profile that overrides their workspace profile. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tenants/TenantAddSingleParams.cs b/src/TryCourier/Models/Users/Tenants/TenantAddSingleParams.cs index 371bbc70..3ed7fff8 100644 --- a/src/TryCourier/Models/Users/Tenants/TenantAddSingleParams.cs +++ b/src/TryCourier/Models/Users/Tenants/TenantAddSingleParams.cs @@ -10,10 +10,8 @@ namespace TryCourier.Models.Users.Tenants; /// -/// This endpoint is used to add a single tenant. -/// -/// A custom profile can also be supplied with the tenant. This profile will -/// be merged with the user's main profile when sending to the user with that tenant. +/// Adds a user to one tenant, optionally with a tenant-specific profile that overrides +/// their workspace profile for sends in that tenant. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tenants/TenantListParams.cs b/src/TryCourier/Models/Users/Tenants/TenantListParams.cs index 2455c309..f7557ab2 100644 --- a/src/TryCourier/Models/Users/Tenants/TenantListParams.cs +++ b/src/TryCourier/Models/Users/Tenants/TenantListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Tenants; /// -/// Returns a paginated list of user tenant associations. +/// Returns the tenants a user belongs to, with cursor paging. A user can belong +/// to many tenants, each with its own profile and preferences. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tenants/TenantRemoveAllParams.cs b/src/TryCourier/Models/Users/Tenants/TenantRemoveAllParams.cs index 8295784c..d8cd876b 100644 --- a/src/TryCourier/Models/Users/Tenants/TenantRemoveAllParams.cs +++ b/src/TryCourier/Models/Users/Tenants/TenantRemoveAllParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Tenants; /// -/// Removes a user from any tenants they may have been associated with. +/// Removes a user from every tenant they belong to in one call. Their workspace-level +/// profile is a separate resource. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tenants/TenantRemoveSingleParams.cs b/src/TryCourier/Models/Users/Tenants/TenantRemoveSingleParams.cs index 98ff0877..3213dfd5 100644 --- a/src/TryCourier/Models/Users/Tenants/TenantRemoveSingleParams.cs +++ b/src/TryCourier/Models/Users/Tenants/TenantRemoveSingleParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Tenants; /// -/// Removes a user from the supplied tenant. +/// Removes a user from one tenant. Their other tenant memberships and workspace +/// profile are managed through separate endpoints. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tokens/TokenAddMultipleParams.cs b/src/TryCourier/Models/Users/Tokens/TokenAddMultipleParams.cs index 894b816e..584d8759 100644 --- a/src/TryCourier/Models/Users/Tokens/TokenAddMultipleParams.cs +++ b/src/TryCourier/Models/Users/Tokens/TokenAddMultipleParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Tokens; /// -/// Adds multiple tokens to a user and overwrites matching existing tokens. +/// Registers several device tokens for a user in one call, overwriting any stored +/// token with a matching value. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tokens/TokenAddSingleParams.cs b/src/TryCourier/Models/Users/Tokens/TokenAddSingleParams.cs index d1f93a14..33ce7f1c 100644 --- a/src/TryCourier/Models/Users/Tokens/TokenAddSingleParams.cs +++ b/src/TryCourier/Models/Users/Tokens/TokenAddSingleParams.cs @@ -12,7 +12,8 @@ namespace TryCourier.Models.Users.Tokens; /// -/// Adds a single token to a user and overwrites a matching existing token. +/// Registers one device token for a user against a provider key, overwriting the +/// token if it already exists. Push sends resolve tokens per user. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tokens/TokenDeleteParams.cs b/src/TryCourier/Models/Users/Tokens/TokenDeleteParams.cs index 579881d3..c489f20f 100644 --- a/src/TryCourier/Models/Users/Tokens/TokenDeleteParams.cs +++ b/src/TryCourier/Models/Users/Tokens/TokenDeleteParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Tokens; /// -/// Delete User Token +/// Deletes one device token for a user, addressed by the token value, so push sends +/// no longer target that device. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tokens/TokenListParams.cs b/src/TryCourier/Models/Users/Tokens/TokenListParams.cs index 191edb95..a73bcba0 100644 --- a/src/TryCourier/Models/Users/Tokens/TokenListParams.cs +++ b/src/TryCourier/Models/Users/Tokens/TokenListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Tokens; /// -/// Gets all tokens available for a :user_id +/// Returns every device token registered for a user, each with its provider key, +/// status, and expiry date. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tokens/TokenRetrieveParams.cs b/src/TryCourier/Models/Users/Tokens/TokenRetrieveParams.cs index af6ad5ff..8ee74cf6 100644 --- a/src/TryCourier/Models/Users/Tokens/TokenRetrieveParams.cs +++ b/src/TryCourier/Models/Users/Tokens/TokenRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.Users.Tokens; /// -/// Get single token available for a `:token` +/// Returns one device token with its provider key, status and status reason, expiry +/// date, and any properties stored alongside it. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/Users/Tokens/TokenUpdateParams.cs b/src/TryCourier/Models/Users/Tokens/TokenUpdateParams.cs index 236509f7..209181ed 100644 --- a/src/TryCourier/Models/Users/Tokens/TokenUpdateParams.cs +++ b/src/TryCourier/Models/Users/Tokens/TokenUpdateParams.cs @@ -12,7 +12,8 @@ namespace TryCourier.Models.Users.Tokens; /// -/// Apply a JSON Patch (RFC 6902) to the specified token. +/// Applies a JSON Patch to a device token, changing its status, expiry, or properties +/// without re-registering it. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/WorkspacePreferences/Topics/TopicArchiveParams.cs b/src/TryCourier/Models/WorkspacePreferences/Topics/TopicArchiveParams.cs index c3023488..955c648d 100644 --- a/src/TryCourier/Models/WorkspacePreferences/Topics/TopicArchiveParams.cs +++ b/src/TryCourier/Models/WorkspacePreferences/Topics/TopicArchiveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.WorkspacePreferences.Topics; /// -/// Archive a topic and remove it from its workspace preference. Same 404 rules as GET. +/// Archives a subscription topic and removes it from its workspace preference, addressed +/// by section id and topic id. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/WorkspacePreferences/Topics/TopicCreateParams.cs b/src/TryCourier/Models/WorkspacePreferences/Topics/TopicCreateParams.cs index 842e67cb..d17f17f3 100644 --- a/src/TryCourier/Models/WorkspacePreferences/Topics/TopicCreateParams.cs +++ b/src/TryCourier/Models/WorkspacePreferences/Topics/TopicCreateParams.cs @@ -13,8 +13,8 @@ namespace TryCourier.Models.WorkspacePreferences.Topics; /// -/// Create a subscription preference topic inside a workspace preference. Fails with -/// 404 if the workspace preference does not exist. The topic id is generated and returned. +/// Creates a subscription topic inside a workspace preference. The default status +/// sets whether users start opted in, opted out, or required. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/WorkspacePreferences/Topics/TopicListParams.cs b/src/TryCourier/Models/WorkspacePreferences/Topics/TopicListParams.cs index ab954f94..864179c5 100644 --- a/src/TryCourier/Models/WorkspacePreferences/Topics/TopicListParams.cs +++ b/src/TryCourier/Models/WorkspacePreferences/Topics/TopicListParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.WorkspacePreferences.Topics; /// -/// List the topics in a workspace preference. +/// Returns the subscription topics inside a workspace preference, each with its default +/// status and routing options. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/WorkspacePreferences/Topics/TopicRetrieveParams.cs b/src/TryCourier/Models/WorkspacePreferences/Topics/TopicRetrieveParams.cs index 76690b5d..dfd217c4 100644 --- a/src/TryCourier/Models/WorkspacePreferences/Topics/TopicRetrieveParams.cs +++ b/src/TryCourier/Models/WorkspacePreferences/Topics/TopicRetrieveParams.cs @@ -9,9 +9,8 @@ namespace TryCourier.Models.WorkspacePreferences.Topics; /// -/// Retrieve a topic within a workspace preference. Returns 404 if the workspace -/// preference does not exist, the topic does not exist, or the topic belongs to -/// a different workspace preference. +/// Returns one subscription topic with its default status, routing options, allowed +/// preferences, and unsubscribe header setting. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceCreateParams.cs b/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceCreateParams.cs index 37f27fa8..a63355d0 100644 --- a/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceCreateParams.cs +++ b/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceCreateParams.cs @@ -11,8 +11,8 @@ namespace TryCourier.Models.WorkspacePreferences; /// -/// Create a workspace preference. The workspace preference id is generated and returned. -/// Topics are created inside a workspace preference via POST /preferences/sections/{section_id}/topics. +/// Creates a workspace preference and returns its generated id. Add subscription +/// topics to it afterwards with the topics endpoint. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceListParams.cs b/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceListParams.cs index 58e66e4a..bfc9629a 100644 --- a/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceListParams.cs +++ b/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceListParams.cs @@ -9,8 +9,8 @@ namespace TryCourier.Models.WorkspacePreferences; /// -/// List the workspace's preferences. Each workspace preference embeds its topics. -/// Scoped to the workspace of the API key. +/// Returns the workspace's preferences, each embedding its subscription topics, routing +/// options, and whether custom routing is allowed. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferencePublishParams.cs b/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferencePublishParams.cs index 78a1e382..e7c6879a 100644 --- a/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferencePublishParams.cs +++ b/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferencePublishParams.cs @@ -10,9 +10,8 @@ namespace TryCourier.Models.WorkspacePreferences; /// -/// Publish the workspace's preferences page. Takes a snapshot of every workspace -/// preference with its topics under a new published version, making the current state -/// visible on the hosted preferences page (non-draft). +/// Publishes the workspace preference page, snapshotting every preference and topic, +/// and returns the page id and a preview URL. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceRetrieveParams.cs b/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceRetrieveParams.cs index b72cc114..221a9670 100644 --- a/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceRetrieveParams.cs +++ b/src/TryCourier/Models/WorkspacePreferences/WorkspacePreferenceRetrieveParams.cs @@ -9,7 +9,8 @@ namespace TryCourier.Models.WorkspacePreferences; /// -/// Retrieve a workspace preference by id, including its topics. +/// Returns one workspace preference by id, including its subscription topics, routing +/// options, and custom routing flag. /// /// NOTE: Do not inherit from this type outside the SDK unless you're okay with /// breaking changes in non-major versions. We may add new methods in the future that diff --git a/src/TryCourier/Services/Automations/IInvokeService.cs b/src/TryCourier/Services/Automations/IInvokeService.cs index 75e66dd8..ea0f23f6 100644 --- a/src/TryCourier/Services/Automations/IInvokeService.cs +++ b/src/TryCourier/Services/Automations/IInvokeService.cs @@ -28,10 +28,8 @@ public interface IInvokeService IInvokeService WithOptions(Func modifier); /// - /// Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a - /// series of automation steps. For information about what steps are available, - /// checkout the ad hoc automation guide - /// [here](https://www.courier.com/docs/automations/steps/). + /// Runs a series of automation steps supplied inline, without a saved template, and + /// returns a runId. /// Task InvokeAdHoc( InvokeInvokeAdHocParams parameters, @@ -39,7 +37,8 @@ Task InvokeAdHoc( ); /// - /// Invoke an automation run from an automation template. + /// Starts an automation run from a saved template for one recipient, with optional + /// data and profile, and returns a runId. /// Task InvokeByTemplate( InvokeInvokeByTemplateParams parameters, diff --git a/src/TryCourier/Services/Digests/IScheduleService.cs b/src/TryCourier/Services/Digests/IScheduleService.cs index 6b6880d0..94d516d0 100644 --- a/src/TryCourier/Services/Digests/IScheduleService.cs +++ b/src/TryCourier/Services/Digests/IScheduleService.cs @@ -28,9 +28,8 @@ public interface IScheduleService IScheduleService WithOptions(Func modifier); /// - /// List the digest instances for a schedule. Each instance represents the events - /// accumulated for a single user against the schedule, and can be used to monitor - /// digest accumulation before the digest is released. + /// Returns the digest instances for a schedule, one per user, with cursor paging. + /// Use it to see what has accumulated before a digest releases. /// Task ListInstances( ScheduleListInstancesParams parameters, diff --git a/src/TryCourier/Services/IAudienceService.cs b/src/TryCourier/Services/IAudienceService.cs index 34572c09..52ecf34b 100644 --- a/src/TryCourier/Services/IAudienceService.cs +++ b/src/TryCourier/Services/IAudienceService.cs @@ -27,7 +27,8 @@ public interface IAudienceService IAudienceService WithOptions(Func modifier); /// - /// Returns the specified audience by id. + /// Returns one audience with its name, description, and the filter and AND or OR + /// operator that decide which users belong to it. /// Task Retrieve( AudienceRetrieveParams parameters, @@ -42,7 +43,8 @@ Task Retrieve( ); /// - /// Creates or updates audience. + /// Creates or replaces an audience from a filter and an AND or OR operator. + /// Membership recalculates automatically as profiles change. /// Task Update( AudienceUpdateParams parameters, @@ -57,7 +59,8 @@ Task Update( ); /// - /// Get the audiences associated with the authorization token. + /// Returns the audiences in the workspace with paging. Audiences are filter-based + /// groups that recalculate as user profiles change. /// Task List( AudienceListParams? parameters = null, @@ -65,7 +68,8 @@ Task List( ); /// - /// Deletes the specified audience. + /// Deletes an audience permanently, so update any caller sending to it by audience + /// id first. Those sends fail once the audience is gone. /// Task Delete(AudienceDeleteParams parameters, CancellationToken cancellationToken = default); @@ -77,7 +81,8 @@ Task Delete( ); /// - /// Get list of members of an audience. + /// Returns the users currently matching an audience filter, with paging. Membership + /// is recalculated, so results shift as profiles change. /// Task ListMembers( AudienceListMembersParams parameters, diff --git a/src/TryCourier/Services/IAuditEventService.cs b/src/TryCourier/Services/IAuditEventService.cs index 47756347..4b386f56 100644 --- a/src/TryCourier/Services/IAuditEventService.cs +++ b/src/TryCourier/Services/IAuditEventService.cs @@ -27,7 +27,8 @@ public interface IAuditEventService IAuditEventService WithOptions(Func modifier); /// - /// Fetch a specific audit event by ID. + /// Returns one audit event by id, including the actor who performed it, the target + /// they changed, the source, the event type, and a timestamp. /// Task Retrieve( AuditEventRetrieveParams parameters, @@ -42,7 +43,8 @@ Task Retrieve( ); /// - /// Fetch the list of audit events + /// Returns the workspace's audit event log with cursor paging. Each event records + /// the actor, target, source, type, and timestamp of a change. /// Task List( AuditEventListParams? parameters = null, diff --git a/src/TryCourier/Services/IAuthService.cs b/src/TryCourier/Services/IAuthService.cs index f3a5b7d1..2250f316 100644 --- a/src/TryCourier/Services/IAuthService.cs +++ b/src/TryCourier/Services/IAuthService.cs @@ -27,7 +27,8 @@ public interface IAuthService IAuthService WithOptions(Func modifier); /// - /// Returns a new access token. + /// Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply + /// the scope and an expires_in duration, both required. /// Task IssueToken( AuthIssueTokenParams parameters, diff --git a/src/TryCourier/Services/IAutomationService.cs b/src/TryCourier/Services/IAutomationService.cs index 63c9f66e..9500b6e7 100644 --- a/src/TryCourier/Services/IAutomationService.cs +++ b/src/TryCourier/Services/IAutomationService.cs @@ -30,7 +30,8 @@ public interface IAutomationService IInvokeService Invoke { get; } /// - /// Get the list of automations. + /// Lists the workspace's saved automation templates, each with its id and a cursor + /// for paging to the next page of results. /// Task List( AutomationListParams? parameters = null, diff --git a/src/TryCourier/Services/IBrandService.cs b/src/TryCourier/Services/IBrandService.cs index 06f1873c..c68e7732 100644 --- a/src/TryCourier/Services/IBrandService.cs +++ b/src/TryCourier/Services/IBrandService.cs @@ -27,13 +27,14 @@ public interface IBrandService IBrandService WithOptions(Func modifier); /// - /// Create a new brand. Requires `name` and `settings` (with at least - /// `colors.primary` and `colors.secondary`). + /// Creates a brand from a name and settings, including primary and secondary + /// colors. Brands supply the logo, colors, and styling that templates render with. /// Task Create(BrandCreateParams parameters, CancellationToken cancellationToken = default); /// - /// Fetch a specific brand by brand ID. + /// Returns one brand by id, including its colors, logo and styling settings, + /// Handlebars snippets, and published version. /// Task Retrieve( BrandRetrieveParams parameters, @@ -48,7 +49,8 @@ Task Retrieve( ); /// - /// Replace an existing brand with the supplied values. + /// Replaces a brand with the values you supply, so send the complete settings and + /// snippets rather than only the fields you want changed. /// Task Update(BrandUpdateParams parameters, CancellationToken cancellationToken = default); @@ -60,7 +62,8 @@ Task Update( ); /// - /// Get the list of brands. + /// Lists the workspace's brands. Every entry carries its name, styling settings, + /// snippets, and published version. /// Task List( BrandListParams? parameters = null, @@ -68,7 +71,8 @@ Task List( ); /// - /// Delete a brand by brand ID. + /// Deletes a brand by id. Reassign any template or tenant that references it before + /// deleting to keep their styling intact. /// Task Delete(BrandDeleteParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/Services/IInboundService.cs b/src/TryCourier/Services/IInboundService.cs index 699ffa74..44ad4081 100644 --- a/src/TryCourier/Services/IInboundService.cs +++ b/src/TryCourier/Services/IInboundService.cs @@ -27,7 +27,8 @@ public interface IInboundService IInboundService WithOptions(Func modifier); /// - /// Courier Track Event + /// Records an inbound event that can trigger a journey. Requires an event name, a + /// messageId you generate, a type, and a properties object. /// Task TrackEvent( InboundTrackEventParams parameters, diff --git a/src/TryCourier/Services/IJourneyService.cs b/src/TryCourier/Services/IJourneyService.cs index fe71abaa..237a55d6 100644 --- a/src/TryCourier/Services/IJourneyService.cs +++ b/src/TryCourier/Services/IJourneyService.cs @@ -30,12 +30,8 @@ public interface IJourneyService ITemplateService Templates { get; } /// - /// Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to - /// publish on create. Send nodes are not allowed on `POST`. The standard flow is: - /// create the journey shell here, add notification templates with `POST - /// /journeys/{templateId}/templates`, then wire them into the journey with `PUT - /// /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to publish a - /// draft after the fact. + /// Creates a journey from a set of nodes, in draft state unless you pass a + /// published state. Send nodes cannot be included until their templates exist. /// Task Create( JourneyCreateParams parameters, @@ -59,7 +55,8 @@ Task Retrieve( ); /// - /// Get the list of journeys. + /// Lists the workspace's journeys, each carrying a name, state, and enabled flag. + /// Paged by cursor. /// Task List( JourneyListParams? parameters = null, @@ -67,8 +64,8 @@ Task List( ); /// - /// Archive a journey. Archived journeys cannot be invoked. Existing journey runs - /// continue to completion. + /// Archives a journey so it can no longer be invoked. Runs already in flight + /// continue to completion, so archiving never strands a user mid-sequence. /// Task Archive(JourneyArchiveParams parameters, CancellationToken cancellationToken = default); @@ -80,12 +77,8 @@ Task Archive( ); /// - /// Cancel journey runs. The request body must include EXACTLY ONE of - /// `cancelation_token` (cancels every run associated with the token) or `run_id` - /// (cancels a single tenant-scoped run). Supplying both or neither returns a `400`. - /// A `run_id` that does not match a run for the tenant returns `404`. Cancelation - /// is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was - /// already `CANCELED` is left unchanged and its current status is returned. + /// Cancels in-flight journey runs, either every run sharing a cancelation token or + /// one run by id. Use it to stop a sequence when the event resolves. /// Task Cancel( JourneyCancelParams parameters, @@ -93,8 +86,8 @@ Task Cancel( ); /// - /// Invoke a journey by id or alias to start a new run. The response includes a - /// `runId` identifying the run. + /// Starts a journey run for one user and returns a runId. Runs execute + /// asynchronously, so the response arrives before any message is sent. /// Task Invoke( JourneyInvokeParams parameters, @@ -109,7 +102,8 @@ Task Invoke( ); /// - /// List published versions of a journey, ordered most recent first. + /// Lists a journey's published versions, most recent first, so you have a version + /// id to roll back to. Paged by cursor. /// Task ListVersions( JourneyListVersionsParams parameters, @@ -124,9 +118,8 @@ Task ListVersions( ); /// - /// Publish the current draft as a new version. Body is optional; pass `{ "version": - /// "vN" }` to roll back to a prior version instead. Returns 404 if the journey has - /// no draft to publish. + /// Publishes a journey's current draft as a new version, making it live for new + /// runs. Pass a version instead to roll back to an earlier one. /// Task Publish( JourneyPublishParams parameters, @@ -141,11 +134,8 @@ Task Publish( ); /// - /// Replace the journey draft. Updates the working draft only; call `POST - /// /journeys/{templateId}/publish` to make it live, or pass `state: "PUBLISHED"` in - /// this request to publish immediately. Send-node `template` ids must already exist - /// and be scoped to this journey, and node ids must not be claimed by another - /// journey. + /// Replaces a journey's working draft, leaving the published version live until you + /// publish. Reach for this when editing a journey already running. /// Task Replace( JourneyReplaceParams parameters, diff --git a/src/TryCourier/Services/IListService.cs b/src/TryCourier/Services/IListService.cs index 0f4c35db..4a381e7b 100644 --- a/src/TryCourier/Services/IListService.cs +++ b/src/TryCourier/Services/IListService.cs @@ -30,7 +30,8 @@ public interface IListService ISubscriptionService Subscriptions { get; } /// - /// Returns a list based on the list ID provided. + /// Returns one list by id with its name and created and updated timestamps. Fetch + /// its subscribers separately with the subscriptions endpoint. /// Task Retrieve( ListRetrieveParams parameters, @@ -45,7 +46,8 @@ Task Retrieve( ); /// - /// Create or replace an existing list with the supplied values. + /// Creates or replaces a list from a name and preferences. Subscribers are managed + /// through the separate subscriptions endpoints. /// Task Update(ListUpdateParams parameters, CancellationToken cancellationToken = default); @@ -57,7 +59,8 @@ Task Update( ); /// - /// Returns all of the lists, with the ability to filter based on a pattern. + /// Returns the workspace's lists, filterable by a pattern to fetch a subset such as + /// every regional list. Paged by cursor. /// Task List( ListListParams? parameters = null, @@ -65,7 +68,8 @@ Task List( ); /// - /// Delete a list by list ID. + /// Deletes a list, halting sends that target it. A previously deleted list can be + /// brought back with the companion restore endpoint. /// Task Delete(ListDeleteParams parameters, CancellationToken cancellationToken = default); @@ -77,7 +81,8 @@ Task Delete( ); /// - /// Restore a previously deleted list. + /// Restores a previously deleted list along with its subscribers, so a list removed + /// by mistake can be brought back rather than rebuilt. /// Task Restore(ListRestoreParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/Services/IMessageService.cs b/src/TryCourier/Services/IMessageService.cs index 84b79629..45d609fb 100644 --- a/src/TryCourier/Services/IMessageService.cs +++ b/src/TryCourier/Services/IMessageService.cs @@ -27,7 +27,8 @@ public interface IMessageService IMessageService WithOptions(Func modifier); /// - /// Fetch the status of a message you've previously sent. + /// Returns a sent message's status, recipient, event, and per-provider delivery + /// detail, with timestamps for enqueued, sent, delivered, opened, and clicked. /// Task Retrieve( MessageRetrieveParams parameters, @@ -42,7 +43,8 @@ Task Retrieve( ); /// - /// Fetch the statuses of messages you've previously sent. + /// Returns previously sent messages, most recent first, each carrying its status, + /// recipient, channel, and provider. Paged by cursor. /// Task List( MessageListParams? parameters = null, @@ -50,11 +52,8 @@ Task List( ); /// - /// Cancel a message that is currently in the process of being delivered. A - /// well-formatted API call to the cancel message API will return either `200` - /// status code for a successful cancellation or `409` status code for an - /// unsuccessful cancellation. Both cases will include the actual message record in - /// the response body (see details below). + /// Cancels a message that is still in the delivery pipeline and returns the message + /// record with its resulting canceled or failed status. /// Task Cancel( MessageCancelParams parameters, @@ -69,7 +68,8 @@ Task Cancel( ); /// - /// Get message content + /// Returns the rendered content Courier delivered for a message, broken out per + /// channel, to confirm what the recipient received. /// Task Content( MessageContentParams parameters, @@ -84,7 +84,8 @@ Task Content( ); /// - /// Fetch the array of events of a message you've previously sent. + /// Returns the ordered event history for a sent message, one entry per status + /// transition with its timestamp. /// Task History( MessageHistoryParams parameters, @@ -99,11 +100,8 @@ Task History( ); /// - /// Resend a previously sent message. The original send request is loaded from - /// storage and a brand-new send is enqueued for the same recipient and content, - /// producing a **new** `messageId` — the original message is not modified. - /// Throttled by a per-message rate limit; a repeat inside the limit window returns - /// `429 Too Many Requests`. + /// Resends a previously sent message to the same recipient and content, returning a + /// new messageId. The original send request is not modified. /// Task Resend( MessageResendParams parameters, diff --git a/src/TryCourier/Services/INotificationService.cs b/src/TryCourier/Services/INotificationService.cs index 2a1d4e0d..720164f3 100644 --- a/src/TryCourier/Services/INotificationService.cs +++ b/src/TryCourier/Services/INotificationService.cs @@ -55,7 +55,8 @@ Task Retrieve( ); /// - /// List notification templates in your workspace. + /// Lists the workspace's notification templates. Each carries a name, tags, brand, + /// routing, and its draft or published state. /// Task List( NotificationListParams? parameters = null, @@ -63,7 +64,8 @@ Task List( ); /// - /// Archive a notification template. + /// Archives a notification template, preventing new sends from referencing it. The + /// template stays retrievable for its version history. /// Task Archive( NotificationArchiveParams parameters, @@ -78,12 +80,9 @@ Task Archive( ); /// - /// Duplicate a notification template. Creates a standalone copy within the same - /// workspace and environment, with " COPY" appended to the title. The copy clones - /// the source draft's tags, brand, subscription topic, routing strategy, channels, - /// and content, and is always created as a standalone template (it is not linked to - /// any journey or broadcast, even if the source was). Templates that are scoped to - /// a journey or a broadcast cannot be duplicated through this endpoint. + /// Copies a notification template within the same workspace and environment, + /// appending " COPY" to the title. The copy is standalone and independently + /// editable. /// Task Duplicate( NotificationDuplicateParams parameters, @@ -98,7 +97,8 @@ Task Duplicate( ); /// - /// List versions of a notification template. + /// Returns a notification template's published versions, most recent first, for + /// comparison or rollback. Paged. /// Task ListVersions( NotificationListVersionsParams parameters, @@ -129,9 +129,8 @@ Task Publish( ); /// - /// Replace the elemental content of a notification template. Overwrites all - /// elements in the template with the provided content. Only supported for V2 - /// (elemental) templates. + /// Replaces all Elemental content in a template, overwriting every existing + /// element. Supported for V2 templates only, not V1 blocks and channels. /// Task PutContent( NotificationPutContentParams parameters, @@ -146,8 +145,8 @@ Task PutContent( ); /// - /// Update a single element within a notification template. Only supported for V2 - /// (elemental) templates. + /// Replaces one Elemental element in a template, addressed by its element id. + /// Supported for V2 templates only, not V1 blocks and channels. /// Task PutElement( NotificationPutElementParams parameters, @@ -162,9 +161,8 @@ Task PutElement( ); /// - /// Set locale-specific content overrides for a notification template. Each element - /// override must reference an existing element by ID. Only supported for V2 - /// (elemental) templates. + /// Sets locale-specific content overrides for a template. Each override must + /// reference an element that already exists in the default content. /// Task PutLocale( NotificationPutLocaleParams parameters, @@ -179,7 +177,8 @@ Task PutLocale( ); /// - /// Replace a notification template. All fields are required. + /// Replaces a notification template in full, so send every field rather than only + /// the ones you want changed. Publish separately to make it live. /// Task Replace( NotificationReplaceParams parameters, @@ -194,10 +193,8 @@ Task Replace( ); /// - /// Retrieve the content of a notification template. The response shape depends on - /// whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use - /// the `version` query parameter to select draft, published, or a specific - /// historical version. + /// Returns a template's content and checksum. V2 templates return Elemental + /// elements, while V1 templates return blocks and channels instead. /// Task RetrieveContent( NotificationRetrieveContentParams parameters, diff --git a/src/TryCourier/Services/IProfileService.cs b/src/TryCourier/Services/IProfileService.cs index 61548923..35bdae42 100644 --- a/src/TryCourier/Services/IProfileService.cs +++ b/src/TryCourier/Services/IProfileService.cs @@ -30,8 +30,8 @@ public interface IProfileService Profiles::IListService Lists { get; } /// - /// Merge the supplied values with an existing profile or create a new profile if - /// one doesn't already exist. + /// Merges the supplied values into a user's profile, creating it if absent and + /// leaving any key you omit untouched. Prefer this for everyday writes. /// Task Create( ProfileCreateParams parameters, @@ -46,7 +46,8 @@ Task Create( ); /// - /// Returns the specified user profile. + /// Returns a user's stored profile and preferences, including the email address, + /// phone number, and push tokens Courier can reach them on. /// Task Retrieve( ProfileRetrieveParams parameters, @@ -61,7 +62,8 @@ Task Retrieve( ); /// - /// Update a profile + /// Applies a JSON Patch to a user profile, adding, removing, or replacing + /// individual fields without sending the whole object. /// Task Update(ProfileUpdateParams parameters, CancellationToken cancellationToken = default); @@ -73,7 +75,8 @@ Task Update( ); /// - /// Deletes the specified user profile. + /// Deletes a user's profile and stored contact details. List subscriptions and + /// preferences are separate resources, so remove those too if required. /// Task Delete(ProfileDeleteParams parameters, CancellationToken cancellationToken = default); @@ -85,11 +88,8 @@ Task Delete( ); /// - /// When using `PUT`, be sure to include all the key-value pairs required by the - /// recipient's profile. Any key-value pairs that exist in the profile but fail to be - /// included in the `PUT` request will be removed from the profile. Remember, a - /// `PUT` update is a full replacement of the data. For partial updates, use the [Patch](https://www.courier.com/docs/reference/profiles/patch/) - /// request. + /// Overwrites a user profile in full, removing any key absent from the request + /// body. Use the patch endpoint when changing a single field. /// Task Replace( ProfileReplaceParams parameters, diff --git a/src/TryCourier/Services/IProviderService.cs b/src/TryCourier/Services/IProviderService.cs index fe25d1d1..45fd3745 100644 --- a/src/TryCourier/Services/IProviderService.cs +++ b/src/TryCourier/Services/IProviderService.cs @@ -30,8 +30,8 @@ public interface IProviderService ICatalogService Catalog { get; } /// - /// Create a new provider configuration. The `provider` field must be a known - /// Courier provider key (see catalog). + /// Configures a provider integration from a Courier provider key and its settings. + /// Check the catalog endpoint for the schema each provider expects. /// Task Create( ProviderCreateParams parameters, @@ -39,7 +39,8 @@ Task Create( ); /// - /// Fetch a single provider configuration by ID. + /// Returns one configured provider by id, including its channel, provider key, + /// alias, title, and current settings. /// Task Retrieve( ProviderRetrieveParams parameters, @@ -54,11 +55,8 @@ Task Retrieve( ); /// - /// Replace an existing provider configuration. The `provider` key is required and - /// determines which provider-specific settings schema is applied. All other fields - /// are optional — omitted fields are cleared from the stored configuration (this is - /// a full replacement, not a partial merge). Changing the provider type for an - /// existing configuration is not supported. + /// Replaces a provider's configuration in full, clearing any field you omit rather + /// than merging it. Send the complete settings object. /// Task Update( ProviderUpdateParams parameters, @@ -73,8 +71,8 @@ Task Update( ); /// - /// List configured provider integrations for the current workspace. Supports - /// cursor-based pagination. + /// Lists the provider integrations configured in the workspace, one entry per + /// channel and provider key with its alias and settings. /// Task List( ProviderListParams? parameters = null, @@ -82,8 +80,8 @@ Task List( ); /// - /// Delete a provider configuration. Returns 409 if the provider is still referenced - /// by routing or notifications. + /// Deletes a provider configuration, which fails while routing strategies or + /// templates still reference it. Update those references first. /// Task Delete(ProviderDeleteParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/Services/IRequestService.cs b/src/TryCourier/Services/IRequestService.cs index 5f5664d5..64ae4ce2 100644 --- a/src/TryCourier/Services/IRequestService.cs +++ b/src/TryCourier/Services/IRequestService.cs @@ -27,7 +27,8 @@ public interface IRequestService IRequestService WithOptions(Func modifier); /// - /// Archive message + /// Archives a send request by its request id. Use it to remove test sends or + /// superseded requests from the message list without deleting them. /// Task Archive(RequestArchiveParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/Services/IRoutingStrategyService.cs b/src/TryCourier/Services/IRoutingStrategyService.cs index d28066fd..c52a28ef 100644 --- a/src/TryCourier/Services/IRoutingStrategyService.cs +++ b/src/TryCourier/Services/IRoutingStrategyService.cs @@ -36,8 +36,8 @@ Task Create( ); /// - /// Retrieve a routing strategy by ID. Returns the full entity including routing - /// content and metadata. + /// Returns one routing strategy by id with its name, tags, channels, and the + /// routing rules that decide provider order and fallback. /// Task Retrieve( RoutingStrategyRetrieveParams parameters, @@ -78,8 +78,8 @@ Task Archive( ); /// - /// List notification templates associated with a routing strategy. Includes - /// template metadata only, not full content. + /// Returns the notification templates using a routing strategy, with paging. Check + /// this before changing a strategy that templates depend on. /// Task ListNotifications( RoutingStrategyListNotificationsParams parameters, diff --git a/src/TryCourier/Services/ISendService.cs b/src/TryCourier/Services/ISendService.cs index 86009c33..3fadf4a1 100644 --- a/src/TryCourier/Services/ISendService.cs +++ b/src/TryCourier/Services/ISendService.cs @@ -27,7 +27,8 @@ public interface ISendService ISendService WithOptions(Func modifier); /// - /// Send a message to one or more recipients. + /// Sends a message to one or more recipients and returns a requestId. Courier + /// routes it to email, SMS, push, chat, or in-app based on your rules. /// Task Message( SendMessageParams parameters, diff --git a/src/TryCourier/Services/ITenantService.cs b/src/TryCourier/Services/ITenantService.cs index 93b2add7..82df655f 100644 --- a/src/TryCourier/Services/ITenantService.cs +++ b/src/TryCourier/Services/ITenantService.cs @@ -32,7 +32,8 @@ public interface ITenantService ITemplateService Templates { get; } /// - /// Get a Tenant + /// Returns one tenant with its name, parent tenant id, default preferences, + /// properties, and the user profile applied to its members. /// Task Retrieve( TenantRetrieveParams parameters, @@ -47,7 +48,8 @@ Task Retrieve( ); /// - /// Create or Replace a Tenant + /// Creates or replaces a tenant from a name, parent, brand, properties, and default + /// preferences supplied in the request body. /// Task Update( TenantUpdateParams parameters, @@ -62,7 +64,8 @@ Task Update( ); /// - /// Get a List of Tenants + /// Lists the workspace's tenants, each carrying a name, parent tenant, properties, + /// and default preferences. Paged. /// Task List( TenantListParams? parameters = null, @@ -70,7 +73,8 @@ Task List( ); /// - /// Delete a Tenant + /// Deletes a tenant. Its members' workspace-level profiles and preferences live + /// outside the tenant and are managed separately. /// Task Delete(TenantDeleteParams parameters, CancellationToken cancellationToken = default); @@ -82,7 +86,8 @@ Task Delete( ); /// - /// Get Users in Tenant + /// Returns the users belonging to a tenant with cursor paging. Use it to see who a + /// tenant-scoped send will reach. /// Task ListUsers( TenantListUsersParams parameters, diff --git a/src/TryCourier/Services/ITranslationService.cs b/src/TryCourier/Services/ITranslationService.cs index a4c1037c..b5bac350 100644 --- a/src/TryCourier/Services/ITranslationService.cs +++ b/src/TryCourier/Services/ITranslationService.cs @@ -27,7 +27,8 @@ public interface ITranslationService ITranslationService WithOptions(Func modifier); /// - /// Get translations by locale + /// Returns the translation strings stored for one domain and locale, for use in + /// localized notification content. /// Task Retrieve( TranslationRetrieveParams parameters, @@ -42,7 +43,8 @@ Task Retrieve( ); /// - /// Update a translation + /// Uploads the translation strings for one domain and locale. Courier uses them to + /// render localized content for recipients in that locale. /// Task Update(TranslationUpdateParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/Services/IWorkspacePreferenceService.cs b/src/TryCourier/Services/IWorkspacePreferenceService.cs index 188ef703..19d84411 100644 --- a/src/TryCourier/Services/IWorkspacePreferenceService.cs +++ b/src/TryCourier/Services/IWorkspacePreferenceService.cs @@ -30,9 +30,8 @@ public interface IWorkspacePreferenceService ITopicService Topics { get; } /// - /// Create a workspace preference. The workspace preference id is generated and - /// returned. Topics are created inside a workspace preference via POST - /// /preferences/sections/{section_id}/topics. + /// Creates a workspace preference and returns its generated id. Add subscription + /// topics to it afterwards with the topics endpoint. /// Task Create( WorkspacePreferenceCreateParams parameters, @@ -40,7 +39,8 @@ Task Create( ); /// - /// Retrieve a workspace preference by id, including its topics. + /// Returns one workspace preference by id, including its subscription topics, + /// routing options, and custom routing flag. /// Task Retrieve( WorkspacePreferenceRetrieveParams parameters, @@ -55,8 +55,8 @@ Task Retrieve( ); /// - /// List the workspace's preferences. Each workspace preference embeds its topics. - /// Scoped to the workspace of the API key. + /// Returns the workspace's preferences, each embedding its subscription topics, + /// routing options, and whether custom routing is allowed. /// Task List( WorkspacePreferenceListParams? parameters = null, @@ -80,9 +80,8 @@ Task Archive( ); /// - /// Publish the workspace's preferences page. Takes a snapshot of every workspace - /// preference with its topics under a new published version, making the current - /// state visible on the hosted preferences page (non-draft). + /// Publishes the workspace preference page, snapshotting every preference and + /// topic, and returns the page id and a preview URL. /// Task Publish( WorkspacePreferencePublishParams? parameters = null, diff --git a/src/TryCourier/Services/Journeys/ITemplateService.cs b/src/TryCourier/Services/Journeys/ITemplateService.cs index 13a6b8df..7d01b67c 100644 --- a/src/TryCourier/Services/Journeys/ITemplateService.cs +++ b/src/TryCourier/Services/Journeys/ITemplateService.cs @@ -45,9 +45,8 @@ Task Create( ); /// - /// Fetch a journey-scoped notification template by id. Pass `?version=draft` - /// (default `published`) to retrieve the working draft, or `?version=vN` for a - /// historical version. + /// Returns a journey's own notification template with its name, brand, subscription + /// topic, and content. Defaults to the published version. /// Task Retrieve( TemplateRetrieveParams parameters, @@ -78,8 +77,8 @@ Task List( ); /// - /// Archive the journey-scoped notification template. Archived templates cannot be - /// sent. + /// Archives one journey's notification template, preventing further sends. Detach + /// any send node referencing it beforehand. /// Task Archive(TemplateArchiveParams parameters, CancellationToken cancellationToken = default); @@ -91,8 +90,8 @@ Task Archive( ); /// - /// List published versions of the journey-scoped notification template, ordered - /// most recent first. + /// Lists the published versions of a template that belongs to a journey, most + /// recent first. Paged by cursor. /// Task ListVersions( TemplateListVersionsParams parameters, @@ -107,9 +106,8 @@ Task ListVersions( ); /// - /// Publish the current draft of the journey-scoped notification template as a new - /// version. Optionally roll back to a prior version by passing `{ "version": "vN" - /// }`. + /// Publishes a journey-scoped template's draft as a new version. Pass a version + /// instead to roll back the template to an earlier publish. /// Task Publish(TemplatePublishParams parameters, CancellationToken cancellationToken = default); @@ -153,7 +151,8 @@ Task PutLocale( ); /// - /// Replace the journey-scoped notification template draft. + /// Replaces the draft content of one journey's notification template. Publish it + /// before send nodes referencing it render the change. /// Task Replace( TemplateReplaceParams parameters, @@ -168,11 +167,8 @@ Task Replace( ); /// - /// Retrieve the elemental content of a journey-scoped notification template. The - /// response contains the versioned elements along with their content checksums, - /// which can be used to detect changes between versions. Pass `?version=draft` - /// (default `published`) to retrieve the working draft, or `?version=vN` for a - /// historical version. + /// Returns the Elemental elements and version of a journey-scoped template's + /// content. Compare versions to see what changed between publishes. /// Task RetrieveContent( TemplateRetrieveContentParams parameters, diff --git a/src/TryCourier/Services/Lists/ISubscriptionService.cs b/src/TryCourier/Services/Lists/ISubscriptionService.cs index 615206dd..7d84785e 100644 --- a/src/TryCourier/Services/Lists/ISubscriptionService.cs +++ b/src/TryCourier/Services/Lists/ISubscriptionService.cs @@ -27,7 +27,8 @@ public interface ISubscriptionService ISubscriptionService WithOptions(Func modifier); /// - /// Get the list's subscriptions. + /// Returns the users subscribed to a list with paging, each with the preferences + /// recorded for that subscription. /// Task List( SubscriptionListParams parameters, @@ -71,8 +72,8 @@ Task Subscribe( ); /// - /// Subscribe a user to an existing list (note: if the List does not exist, it will - /// be automatically created). + /// Subscribes one user to a list, creating the list if it does not yet exist. + /// Optional preferences apply to this subscription only. /// Task SubscribeUser( SubscriptionSubscribeUserParams parameters, @@ -87,7 +88,8 @@ Task SubscribeUser( ); /// - /// Delete a subscription to a list by list ID and user ID. + /// Removes one user's subscription to a list, addressed by list id and user id. The + /// user's profile and other subscriptions are separate resources. /// Task UnsubscribeUser( SubscriptionUnsubscribeUserParams parameters, diff --git a/src/TryCourier/Services/Notifications/ICheckService.cs b/src/TryCourier/Services/Notifications/ICheckService.cs index 6b5191de..0c041154 100644 --- a/src/TryCourier/Services/Notifications/ICheckService.cs +++ b/src/TryCourier/Services/Notifications/ICheckService.cs @@ -27,7 +27,8 @@ public interface ICheckService ICheckService WithOptions(Func modifier); /// - /// Replace the submission checks for a notification template. + /// Replaces the approval checks on a template submission with the complete set + /// supplied in the request body. /// Task Update( CheckUpdateParams parameters, @@ -42,7 +43,8 @@ Task Update( ); /// - /// Retrieve the submission checks for a notification template. + /// Returns the approval checks recorded for a template submission, each with its + /// pass or fail result. /// Task List( CheckListParams parameters, @@ -57,7 +59,8 @@ Task List( ); /// - /// Cancel a submission for a notification template. + /// Cancels a pending template submission, withdrawing it from the approval + /// workflow. The template stays in draft and can be resubmitted later. /// Task Delete(CheckDeleteParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/Services/Profiles/IListService.cs b/src/TryCourier/Services/Profiles/IListService.cs index 8a08c9de..6eb0a789 100644 --- a/src/TryCourier/Services/Profiles/IListService.cs +++ b/src/TryCourier/Services/Profiles/IListService.cs @@ -27,7 +27,8 @@ public interface IListService IListService WithOptions(Func modifier); /// - /// Returns the subscribed lists for a specified user. + /// Returns the lists a user is subscribed to, with paging. Use it to check what a + /// recipient will receive before sending to a list. /// Task Retrieve( ListRetrieveParams parameters, @@ -42,7 +43,8 @@ Task Retrieve( ); /// - /// Removes all list subscriptions for given user. + /// Removes every list subscription for a user at once. Their profile and + /// preferences are untouched, so this only affects list-targeted sends. /// Task Delete( ListDeleteParams parameters, @@ -57,8 +59,8 @@ Task Delete( ); /// - /// Subscribes the given user to one or more lists. If the list does not exist, it - /// will be created. + /// Subscribes a user to one or more lists, creating any list that does not yet + /// exist. Optional preferences apply to each subscription. /// Task Subscribe( ListSubscribeParams parameters, diff --git a/src/TryCourier/Services/Providers/ICatalogService.cs b/src/TryCourier/Services/Providers/ICatalogService.cs index de1313a6..f0359582 100644 --- a/src/TryCourier/Services/Providers/ICatalogService.cs +++ b/src/TryCourier/Services/Providers/ICatalogService.cs @@ -27,10 +27,8 @@ public interface ICatalogService ICatalogService WithOptions(Func modifier); /// - /// Returns the catalog of available provider types with their display names, - /// descriptions, and configuration schema fields (snake_case, with `type` and - /// `required`). Providers with no configurable schema return only `provider`, - /// `name`, and `description`. + /// Returns the provider types Courier supports, each with a display name, + /// description, and the configuration fields it requires. /// Task List( CatalogListParams? parameters = null, diff --git a/src/TryCourier/Services/Tenants/ITemplateService.cs b/src/TryCourier/Services/Tenants/ITemplateService.cs index 809ba561..b523a2b7 100644 --- a/src/TryCourier/Services/Tenants/ITemplateService.cs +++ b/src/TryCourier/Services/Tenants/ITemplateService.cs @@ -31,7 +31,8 @@ public interface ITemplateService IVersionService Versions { get; } /// - /// Get a Template in Tenant + /// Returns a tenant's notification template with its content, version, and created, + /// updated, and published timestamps. /// Task Retrieve( TemplateRetrieveParams parameters, @@ -46,7 +47,8 @@ Task Retrieve( ); /// - /// List Templates in Tenant + /// Lists a tenant's notification templates, each carrying its version and published + /// timestamp. Paged. /// Task List( TemplateListParams parameters, @@ -61,12 +63,8 @@ Task List( ); /// - /// Deletes the tenant's notification template with the given `template_id`. - /// - /// Returns **204 No Content** with an empty body on success. - /// - /// Returns **404** if there is no template with this ID for the tenant, - /// including a second `DELETE` after a successful removal. + /// Deletes a tenant's notification template by id. Sends for that tenant then use + /// the workspace template registered under the same id. /// Task Delete(TemplateDeleteParams parameters, CancellationToken cancellationToken = default); @@ -78,10 +76,8 @@ Task Delete( ); /// - /// Publishes a specific version of a notification template for a tenant. - /// - /// The template must already exist in the tenant's notification map. If no - /// version is specified, defaults to publishing the "latest" version. + /// Publishes a version of a tenant's notification template, making it the content + /// that tenant's sends render from until you publish another. /// Task Publish( TemplatePublishParams parameters, @@ -96,13 +92,8 @@ Task Publish( ); /// - /// Creates or updates a notification template for a tenant. - /// - /// If the template already exists for the tenant, it will be updated (200). - /// Otherwise, a new template is created (201). - /// - /// Optionally publishes the template immediately if the `published` flag is - /// set to true. + /// Creates or updates a notification template scoped to one tenant, letting a + /// tenant override the content the workspace template would send. /// Task Replace( TemplateReplaceParams parameters, diff --git a/src/TryCourier/Services/Tenants/Preferences/IItemService.cs b/src/TryCourier/Services/Tenants/Preferences/IItemService.cs index ccf9968b..347033fe 100644 --- a/src/TryCourier/Services/Tenants/Preferences/IItemService.cs +++ b/src/TryCourier/Services/Tenants/Preferences/IItemService.cs @@ -27,7 +27,8 @@ public interface IItemService IItemService WithOptions(Func modifier); /// - /// Create or Replace Default Preferences For Topic + /// Sets a tenant's default opt-in status for one subscription topic, which applies + /// to every member unless a user sets their own override. /// Task Update(ItemUpdateParams parameters, CancellationToken cancellationToken = default); @@ -39,7 +40,8 @@ Task Update( ); /// - /// Remove Default Preferences For Topic + /// Removes a tenant's default preference for one subscription topic, addressed by + /// tenant id and topic id. /// Task Delete(ItemDeleteParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/Services/Tenants/Templates/IVersionService.cs b/src/TryCourier/Services/Tenants/Templates/IVersionService.cs index 77598031..49df0aad 100644 --- a/src/TryCourier/Services/Tenants/Templates/IVersionService.cs +++ b/src/TryCourier/Services/Tenants/Templates/IVersionService.cs @@ -28,11 +28,8 @@ public interface IVersionService IVersionService WithOptions(Func modifier); /// - /// Fetches a specific version of a tenant template. - /// - /// Supports the following version formats: - `latest` - The most recent - /// version of the template - `published` - The currently published version - - /// `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0") + /// Returns one version of a tenant template, addressed by version number or by + /// latest, with its content and publish timestamp. /// Task Retrieve( VersionRetrieveParams parameters, diff --git a/src/TryCourier/Services/Users/IPreferenceService.cs b/src/TryCourier/Services/Users/IPreferenceService.cs index 0c11a5d0..e2771ab1 100644 --- a/src/TryCourier/Services/Users/IPreferenceService.cs +++ b/src/TryCourier/Services/Users/IPreferenceService.cs @@ -27,7 +27,8 @@ public interface IPreferenceService IPreferenceService WithOptions(Func modifier); /// - /// Fetch all user preferences. + /// Returns a user's preference overrides with paging, one entry per subscription + /// topic they have set a choice for. /// Task Retrieve( PreferenceRetrieveParams parameters, @@ -42,24 +43,8 @@ Task Retrieve( ); /// - /// Replace a user's complete set of preference overrides in a single request. The - /// topics in the request body become the recipient's entire set of overrides: - /// listed topics are created or updated, and every existing override that is not - /// included in the body is reset to its topic default. Submitting an empty `topics` - /// array is a valid clear-all that resets every existing override. - /// - /// This operation is validation-atomic (all-or-nothing): structural - /// validation fails fast with a single `400`, and if any topic is semantically - /// invalid (an unknown topic, a `REQUIRED` topic that cannot be opted out, or a - /// custom routing request that is not available on the workspace's plan) the - /// request returns a single `400` aggregating every failure in `errors` and writes - /// nothing. On success it returns `200` with `items` (the complete resulting - /// override set) and `deleted` (the ids of the overrides that were reset to - /// default). - /// - /// Every `topic_id` in the response — in `items`, `deleted`, and any `errors` - /// — is returned in Courier's canonical topic id form, regardless of the form - /// supplied in the request. + /// Replaces a user's entire set of preference overrides. Any topic you leave out is + /// reset to its default, so send the full set rather than a subset. /// Task BulkReplace( PreferenceBulkReplaceParams parameters, @@ -74,23 +59,8 @@ Task BulkReplace( ); /// - /// Additively create or update a user's preferences for one or more subscription - /// topics in a single request. Only the topics included in the request body are - /// created or updated; any existing overrides for topics not listed are left - /// untouched. - /// - /// Structural validation of the request body fails fast with a single `400`. - /// Beyond that, each topic is processed independently (partial-success, not - /// all-or-nothing): valid topics are written and returned in `items`, while topics - /// that cannot be applied are collected in `errors` with a per-topic `reason` (for - /// example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom - /// routing request that is not available on the workspace's plan, or a write - /// failure). The request therefore returns `200` with both lists whenever the body - /// is structurally valid. - /// - /// Every `topic_id` in the response — in both `items` and `errors` — is - /// returned in Courier's canonical topic id form, regardless of the form supplied - /// in the request. + /// Adds or updates a user's preferences for several subscription topics at once. + /// Topics you leave out keep whatever they were set to before. /// Task BulkUpdate( PreferenceBulkUpdateParams parameters, @@ -105,9 +75,8 @@ Task BulkUpdate( ); /// - /// Remove a user's preferences for a specific subscription topic, resetting the - /// topic to its effective default. This operation is idempotent: deleting a - /// preference that does not exist succeeds with no error. + /// Removes a user's override for one subscription topic, resetting it to the + /// effective default from the tenant or workspace. /// Task DeleteTopic( PreferenceDeleteTopicParams parameters, @@ -122,7 +91,8 @@ Task DeleteTopic( ); /// - /// Fetch user preferences for a specific subscription topic. + /// Returns a user's opt-in status and channel choices for one subscription topic, + /// or the effective default if they have set no override. /// Task RetrieveTopic( PreferenceRetrieveTopicParams parameters, @@ -137,7 +107,8 @@ Task RetrieveTopic( ); /// - /// Update or Create user preferences for a specific subscription topic. + /// Sets a user's opt-in status and channel choices for one subscription topic, + /// overriding the tenant default for that topic only. /// Task UpdateOrCreateTopic( PreferenceUpdateOrCreateTopicParams parameters, diff --git a/src/TryCourier/Services/Users/ITenantService.cs b/src/TryCourier/Services/Users/ITenantService.cs index 00e2f849..530c7bb0 100644 --- a/src/TryCourier/Services/Users/ITenantService.cs +++ b/src/TryCourier/Services/Users/ITenantService.cs @@ -27,7 +27,8 @@ public interface ITenantService ITenantService WithOptions(Func modifier); /// - /// Returns a paginated list of user tenant associations. + /// Returns the tenants a user belongs to, with cursor paging. A user can belong to + /// many tenants, each with its own profile and preferences. /// Task List( TenantListParams parameters, @@ -42,9 +43,8 @@ Task List( ); /// - /// This endpoint is used to add a user to multiple tenants in one call. A custom - /// profile can also be supplied for each tenant. This profile will be merged with the - /// user's main profile when sending to the user with that tenant. + /// Adds a user to several tenants in one call, each optionally with a per-tenant + /// profile that overrides their workspace profile. /// Task AddMultiple( TenantAddMultipleParams parameters, @@ -59,10 +59,8 @@ Task AddMultiple( ); /// - /// This endpoint is used to add a single tenant. - /// - /// A custom profile can also be supplied with the tenant. This profile will be - /// merged with the user's main profile when sending to the user with that tenant. + /// Adds a user to one tenant, optionally with a tenant-specific profile that + /// overrides their workspace profile for sends in that tenant. /// Task AddSingle(TenantAddSingleParams parameters, CancellationToken cancellationToken = default); @@ -74,7 +72,8 @@ Task AddSingle( ); /// - /// Removes a user from any tenants they may have been associated with. + /// Removes a user from every tenant they belong to in one call. Their + /// workspace-level profile is a separate resource. /// Task RemoveAll(TenantRemoveAllParams parameters, CancellationToken cancellationToken = default); @@ -86,7 +85,8 @@ Task RemoveAll( ); /// - /// Removes a user from the supplied tenant. + /// Removes a user from one tenant. Their other tenant memberships and workspace + /// profile are managed through separate endpoints. /// Task RemoveSingle( TenantRemoveSingleParams parameters, diff --git a/src/TryCourier/Services/Users/ITokenService.cs b/src/TryCourier/Services/Users/ITokenService.cs index 6568eb23..73a68468 100644 --- a/src/TryCourier/Services/Users/ITokenService.cs +++ b/src/TryCourier/Services/Users/ITokenService.cs @@ -27,7 +27,8 @@ public interface ITokenService ITokenService WithOptions(Func modifier); /// - /// Get single token available for a `:token` + /// Returns one device token with its provider key, status and status reason, expiry + /// date, and any properties stored alongside it. /// Task Retrieve( TokenRetrieveParams parameters, @@ -42,7 +43,8 @@ Task Retrieve( ); /// - /// Apply a JSON Patch (RFC 6902) to the specified token. + /// Applies a JSON Patch to a device token, changing its status, expiry, or + /// properties without re-registering it. /// Task Update(TokenUpdateParams parameters, CancellationToken cancellationToken = default); @@ -54,7 +56,8 @@ Task Update( ); /// - /// Gets all tokens available for a :user_id + /// Returns every device token registered for a user, each with its provider key, + /// status, and expiry date. /// Task List( TokenListParams parameters, @@ -69,7 +72,8 @@ Task List( ); /// - /// Delete User Token + /// Deletes one device token for a user, addressed by the token value, so push sends + /// no longer target that device. /// Task Delete(TokenDeleteParams parameters, CancellationToken cancellationToken = default); @@ -81,7 +85,8 @@ Task Delete( ); /// - /// Adds multiple tokens to a user and overwrites matching existing tokens. + /// Registers several device tokens for a user in one call, overwriting any stored + /// token with a matching value. /// Task AddMultiple( TokenAddMultipleParams parameters, @@ -96,7 +101,8 @@ Task AddMultiple( ); /// - /// Adds a single token to a user and overwrites a matching existing token. + /// Registers one device token for a user against a provider key, overwriting the + /// token if it already exists. Push sends resolve tokens per user. /// Task AddSingle(TokenAddSingleParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/Services/WorkspacePreferences/ITopicService.cs b/src/TryCourier/Services/WorkspacePreferences/ITopicService.cs index 1f91a7a4..2b959ee4 100644 --- a/src/TryCourier/Services/WorkspacePreferences/ITopicService.cs +++ b/src/TryCourier/Services/WorkspacePreferences/ITopicService.cs @@ -28,9 +28,8 @@ public interface ITopicService ITopicService WithOptions(Func modifier); /// - /// Create a subscription preference topic inside a workspace preference. Fails with - /// 404 if the workspace preference does not exist. The topic id is generated and - /// returned. + /// Creates a subscription topic inside a workspace preference. The default status + /// sets whether users start opted in, opted out, or required. /// Task Create( TopicCreateParams parameters, @@ -45,9 +44,8 @@ Task Create( ); /// - /// Retrieve a topic within a workspace preference. Returns 404 if the workspace - /// preference does not exist, the topic does not exist, or the topic belongs to a - /// different workspace preference. + /// Returns one subscription topic with its default status, routing options, allowed + /// preferences, and unsubscribe header setting. /// Task Retrieve( TopicRetrieveParams parameters, @@ -62,7 +60,8 @@ Task Retrieve( ); /// - /// List the topics in a workspace preference. + /// Returns the subscription topics inside a workspace preference, each with its + /// default status and routing options. /// Task List( TopicListParams parameters, @@ -77,8 +76,8 @@ Task List( ); /// - /// Archive a topic and remove it from its workspace preference. Same 404 rules as - /// GET. + /// Archives a subscription topic and removes it from its workspace preference, + /// addressed by section id and topic id. /// Task Archive(TopicArchiveParams parameters, CancellationToken cancellationToken = default); diff --git a/src/TryCourier/TryCourier.csproj b/src/TryCourier/TryCourier.csproj index 935810f3..fd8b782a 100644 --- a/src/TryCourier/TryCourier.csproj +++ b/src/TryCourier/TryCourier.csproj @@ -3,7 +3,7 @@ Courier C# TryCourier - 5.18.0 + 5.18.1 The official .NET library for the Courier API. Library README.md