diff --git a/.release-please-manifest.json b/.release-please-manifest.json index c032d311..f36ffd45 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "4.22.0" + ".": "4.22.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 83d3cc41..e3902121 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 4.22.1 (2026-07-25) + +Full Changelog: [v4.22.0...v4.22.1](https://github.com/trycourier/courier-java/compare/v4.22.0...v4.22.1) + +### Documentation + +* **openapi:** describe user topic-preference fields explicitly ([#172](https://github.com/trycourier/courier-java/issues/172)) ([1d09244](https://github.com/trycourier/courier-java/commit/1d09244b56cb1ed9c98e28365d7509cd9dbe0018)) +* **openapi:** rewrite operation descriptions for agents and SEO ([#174](https://github.com/trycourier/courier-java/issues/174)) ([3453be3](https://github.com/trycourier/courier-java/commit/3453be34b9c9713b88aa72e64c6fdfa3251a2fae)) + ## 4.22.0 (2026-07-23) Full Changelog: [v4.21.0...v4.22.0](https://github.com/trycourier/courier-java/compare/v4.21.0...v4.22.0) diff --git a/build.gradle.kts b/build.gradle.kts index bb83195c..d7ff0ef5 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -8,7 +8,7 @@ repositories { allprojects { group = "com.courier" - version = "4.22.0" // x-release-please-version + version = "4.22.1" // x-release-please-version } subprojects { diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceDeleteParams.kt index c5bbd9be..d7ff37d8 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceDeleteParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class AudienceDeleteParams private constructor( private val audienceId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListMembersParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListMembersParams.kt index a86de265..d2855958 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListMembersParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListMembersParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class AudienceListMembersParams private constructor( private val audienceId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListParams.kt index 73165b31..c0703bbd 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class AudienceListParams private constructor( private val cursor: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceRetrieveParams.kt index 5c20adef..7c276ad7 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class AudienceRetrieveParams private constructor( private val audienceId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceUpdateParams.kt index 246d1638..76a49fda 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/audiences/AudienceUpdateParams.kt @@ -21,7 +21,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Creates or updates audience. */ +/** + * Creates or replaces an audience from a filter and an AND or OR operator. Membership recalculates + * automatically as profiles change. + */ class AudienceUpdateParams private constructor( private val audienceId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventListParams.kt index ff1f1f54..91aa4bc4 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class AuditEventListParams private constructor( private val cursor: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventRetrieveParams.kt index 80eb8427..e6714cd9 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/auditevents/AuditEventRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class AuditEventRetrieveParams private constructor( private val auditEventId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/auth/AuthIssueTokenParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/auth/AuthIssueTokenParams.kt index b6ae485d..85f00e31 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/auth/AuthIssueTokenParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/auth/AuthIssueTokenParams.kt @@ -18,7 +18,10 @@ import com.fasterxml.jackson.annotation.JsonProperty import java.util.Collections import java.util.Objects -/** 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. + */ class AuthIssueTokenParams private constructor( private val body: Body, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/automations/AutomationListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/automations/AutomationListParams.kt index a72e9024..8a59e3b4 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/automations/AutomationListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/automations/AutomationListParams.kt @@ -13,7 +13,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class AutomationListParams private constructor( private val cursor: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeAdHocParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeAdHocParams.kt index 22e3716c..5ee0c5d9 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeAdHocParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeAdHocParams.kt @@ -35,9 +35,7 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class InvokeInvokeAdHocParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeByTemplateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeByTemplateParams.kt index 7aa2fcbe..60ad6226 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeByTemplateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/automations/invoke/InvokeInvokeByTemplateParams.kt @@ -21,7 +21,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class InvokeInvokeByTemplateParams private constructor( private val templateId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandCreateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandCreateParams.kt index f488e2f1..2eb9a752 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandCreateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandCreateParams.kt @@ -21,8 +21,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class BrandCreateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandDeleteParams.kt index ef2268cf..b3ceb53f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandDeleteParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class BrandDeleteParams private constructor( private val brandId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandListParams.kt index cbf57574..18a518d0 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Get the list of brands. */ +/** + * Lists the workspace's brands. Every entry carries its name, styling settings, snippets, and + * published version. + */ class BrandListParams private constructor( private val cursor: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandRetrieveParams.kt index 71b77c02..7200d97b 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Fetch a specific brand by brand ID. */ +/** + * Returns one brand by id, including its colors, logo and styling settings, Handlebars snippets, + * and published version. + */ class BrandRetrieveParams private constructor( private val brandId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandUpdateParams.kt index b4ebfb3d..005fa3d1 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/brands/BrandUpdateParams.kt @@ -20,7 +20,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class BrandUpdateParams private constructor( private val brandId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/digests/schedules/ScheduleListInstancesParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/digests/schedules/ScheduleListInstancesParams.kt index 2cb01798..814431fe 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/digests/schedules/ScheduleListInstancesParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/digests/schedules/ScheduleListInstancesParams.kt @@ -10,9 +10,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class ScheduleListInstancesParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/inbound/InboundTrackEventParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/inbound/InboundTrackEventParams.kt index 52c2c1e4..e32501f8 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/inbound/InboundTrackEventParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/inbound/InboundTrackEventParams.kt @@ -22,7 +22,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class InboundTrackEventParams private constructor( private val body: Body, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyArchiveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyArchiveParams.kt index ddb3f327..5655bbab 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyArchiveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyArchiveParams.kt @@ -12,8 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class JourneyArchiveParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCancelParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCancelParams.kt index 558cc4a1..68feb64a 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCancelParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCancelParams.kt @@ -9,11 +9,8 @@ import com.courier.core.http.QueryParams import java.util.Objects /** - * 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. */ class JourneyCancelParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCreateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCreateParams.kt index abe3e382..1dc5a9b2 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCreateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyCreateParams.kt @@ -10,11 +10,8 @@ import com.courier.core.http.QueryParams import java.util.Objects /** - * 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. */ class JourneyCreateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyInvokeParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyInvokeParams.kt index 817b5254..00bc1aa0 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyInvokeParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyInvokeParams.kt @@ -12,8 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class JourneyInvokeParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListParams.kt index 8392863d..7df522f6 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListParams.kt @@ -13,7 +13,9 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Get the list of journeys. */ +/** + * Lists the workspace's journeys, each carrying a name, state, and enabled flag. Paged by cursor. + */ class JourneyListParams private constructor( private val cursor: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListVersionsParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListVersionsParams.kt index 5531ac06..10350f99 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListVersionsParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyListVersionsParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class JourneyListVersionsParams private constructor( private val templateId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyPublishParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyPublishParams.kt index 8c07fd58..2e59accd 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyPublishParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyPublishParams.kt @@ -12,8 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class JourneyPublishParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyReplaceParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyReplaceParams.kt index 40365c98..15cbc68f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyReplaceParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/JourneyReplaceParams.kt @@ -12,10 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class JourneyReplaceParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateArchiveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateArchiveParams.kt index 0007b837..f10eb8d3 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateArchiveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateArchiveParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TemplateArchiveParams private constructor( private val templateId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateListVersionsParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateListVersionsParams.kt index ac5fe853..cebe3a52 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateListVersionsParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateListVersionsParams.kt @@ -11,7 +11,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TemplateListVersionsParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplatePublishParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplatePublishParams.kt index 4f47593b..e41cd5c4 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplatePublishParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplatePublishParams.kt @@ -14,8 +14,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TemplatePublishParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateReplaceParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateReplaceParams.kt index 7408ee81..7e180e1b 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateReplaceParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateReplaceParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TemplateReplaceParams private constructor( private val templateId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateRetrieveContentParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateRetrieveContentParams.kt index a099436e..ad93b2a9 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateRetrieveContentParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateRetrieveContentParams.kt @@ -11,10 +11,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TemplateRetrieveContentParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateRetrieveParams.kt index 7292132b..bc1a168e 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/journeys/templates/TemplateRetrieveParams.kt @@ -11,8 +11,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TemplateRetrieveParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListDeleteParams.kt index 130926e6..81077730 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListDeleteParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ListDeleteParams private constructor( private val listId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListListParams.kt index 37d0ffe8..280b217c 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ListListParams private constructor( private val cursor: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListRestoreParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListRestoreParams.kt index 24bc44c5..ed956399 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListRestoreParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListRestoreParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ListRestoreParams private constructor( private val listId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListRetrieveParams.kt index 2d4b2185..57ba41b2 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ListRetrieveParams private constructor( private val listId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListUpdateParams.kt index 775c573d..3d67e83b 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/lists/ListUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/lists/ListUpdateParams.kt @@ -21,7 +21,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ListUpdateParams private constructor( private val listId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionListParams.kt index ae9de70b..2b1bf571 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Get the list's subscriptions. */ +/** + * Returns the users subscribed to a list with paging, each with the preferences recorded for that + * subscription. + */ class SubscriptionListParams private constructor( private val listId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionSubscribeUserParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionSubscribeUserParams.kt index 4a3dbd43..d8d35454 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionSubscribeUserParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionSubscribeUserParams.kt @@ -22,8 +22,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class SubscriptionSubscribeUserParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionUnsubscribeUserParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionUnsubscribeUserParams.kt index d734eba6..273083f7 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionUnsubscribeUserParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/lists/subscriptions/SubscriptionUnsubscribeUserParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class SubscriptionUnsubscribeUserParams private constructor( private val listId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageCancelParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageCancelParams.kt index 0be7d4bf..8ec39cf6 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageCancelParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageCancelParams.kt @@ -12,10 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class MessageCancelParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageContentParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageContentParams.kt index 7411e191..318bc316 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageContentParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageContentParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Get message content */ +/** + * Returns the rendered content Courier delivered for a message, broken out per channel, to confirm + * what the recipient received. + */ class MessageContentParams private constructor( private val messageId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageHistoryParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageHistoryParams.kt index be3b33e0..00f211b0 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageHistoryParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageHistoryParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class MessageHistoryParams private constructor( private val messageId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageListParams.kt index f256c3d8..11c1c83d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageListParams.kt @@ -10,7 +10,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class MessageListParams private constructor( private val archived: Boolean?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageResendParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageResendParams.kt index 9b6b037c..61f43ab3 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageResendParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageResendParams.kt @@ -12,10 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class MessageResendParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageRetrieveParams.kt index 302f03f3..0bb8297f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/messages/MessageRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class MessageRetrieveParams private constructor( private val messageId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationArchiveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationArchiveParams.kt index d27b7f60..0e8a1c01 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationArchiveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationArchiveParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Archive a notification template. */ +/** + * Archives a notification template, preventing new sends from referencing it. The template stays + * retrievable for its version history. + */ class NotificationArchiveParams private constructor( private val id: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationDuplicateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationDuplicateParams.kt index 5352b9d3..d7dc4560 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationDuplicateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationDuplicateParams.kt @@ -12,11 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class NotificationDuplicateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationListParams.kt index 6e86a5b2..c5712925 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class NotificationListParams private constructor( private val cursor: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationListVersionsParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationListVersionsParams.kt index c0080835..0b59d31d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationListVersionsParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationListVersionsParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** List versions of a notification template. */ +/** + * Returns a notification template's published versions, most recent first, for comparison or + * rollback. Paged. + */ class NotificationListVersionsParams private constructor( private val id: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutContentParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutContentParams.kt index 7e5f8702..2521ecf2 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutContentParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutContentParams.kt @@ -12,8 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class NotificationPutContentParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutElementParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutElementParams.kt index 1b247d0d..b6e9e91b 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutElementParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutElementParams.kt @@ -12,8 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class NotificationPutElementParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutLocaleParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutLocaleParams.kt index 67978639..c721be33 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutLocaleParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationPutLocaleParams.kt @@ -12,8 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class NotificationPutLocaleParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationReplaceParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationReplaceParams.kt index 3a935803..f0106217 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationReplaceParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationReplaceParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class NotificationReplaceParams private constructor( private val id: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationRetrieveContentParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationRetrieveContentParams.kt index 81d3310c..414a45b0 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationRetrieveContentParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/NotificationRetrieveContentParams.kt @@ -10,9 +10,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class NotificationRetrieveContentParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckDeleteParams.kt index feff5bf4..8a5b2d37 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckDeleteParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class CheckDeleteParams private constructor( private val id: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckListParams.kt index 4b68d876..d0c2a984 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckListParams.kt @@ -10,7 +10,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Retrieve the submission checks for a notification template. */ +/** + * Returns the approval checks recorded for a template submission, each with its pass or fail + * result. + */ class CheckListParams private constructor( private val id: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckUpdateParams.kt index 59bc2067..205c934c 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/notifications/checks/CheckUpdateParams.kt @@ -23,7 +23,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class CheckUpdateParams private constructor( private val id: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileCreateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileCreateParams.kt index ef16cfcb..8c575d0d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileCreateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileCreateParams.kt @@ -22,8 +22,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class ProfileCreateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileDeleteParams.kt index 54d1c9bf..12f9c69b 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileDeleteParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ProfileDeleteParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileReplaceParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileReplaceParams.kt index 5d6cf5d4..54352e6b 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileReplaceParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileReplaceParams.kt @@ -22,10 +22,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class ProfileReplaceParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileRetrieveParams.kt index 7f57bbbc..e73f07ba 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ProfileRetrieveParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileUpdateParams.kt index 50244a27..3ee742d8 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/profiles/ProfileUpdateParams.kt @@ -22,7 +22,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Update a profile */ +/** + * Applies a JSON Patch to a user profile, adding, removing, or replacing individual fields without + * sending the whole object. + */ class ProfileUpdateParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListDeleteParams.kt index af7c820b..7d7890e1 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListDeleteParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ListDeleteParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListRetrieveParams.kt index 3cfcef63..bd246764 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ListRetrieveParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListSubscribeParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListSubscribeParams.kt index cc61977f..34b6c355 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListSubscribeParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/profiles/lists/ListSubscribeParams.kt @@ -24,7 +24,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class ListSubscribeParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderCreateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderCreateParams.kt index 5ab1a1f3..3fb506a6 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderCreateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderCreateParams.kt @@ -22,8 +22,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class ProviderCreateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderDeleteParams.kt index 3886c0b7..6ba5cbbe 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderDeleteParams.kt @@ -12,8 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class ProviderDeleteParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderListParams.kt index 32cbb849..a8f1060d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderListParams.kt @@ -10,8 +10,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class ProviderListParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderRetrieveParams.kt index ec283b1e..ad806d94 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Fetch a single provider configuration by ID. */ +/** + * Returns one configured provider by id, including its channel, provider key, alias, title, and + * current settings. + */ class ProviderRetrieveParams private constructor( private val id: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderUpdateParams.kt index beb70565..cbb67360 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/providers/ProviderUpdateParams.kt @@ -22,10 +22,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class ProviderUpdateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/providers/catalog/CatalogListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/providers/catalog/CatalogListParams.kt index c0e33e52..bfee2dc2 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/providers/catalog/CatalogListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/providers/catalog/CatalogListParams.kt @@ -10,9 +10,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class CatalogListParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/requests/RequestArchiveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/requests/RequestArchiveParams.kt index b02759f8..00143afd 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/requests/RequestArchiveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/requests/RequestArchiveParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class RequestArchiveParams private constructor( private val requestId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/routingstrategies/RoutingStrategyListNotificationsParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/routingstrategies/RoutingStrategyListNotificationsParams.kt index 5832e872..839bb3c5 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/routingstrategies/RoutingStrategyListNotificationsParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/routingstrategies/RoutingStrategyListNotificationsParams.kt @@ -10,8 +10,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class RoutingStrategyListNotificationsParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/routingstrategies/RoutingStrategyRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/routingstrategies/RoutingStrategyRetrieveParams.kt index a8ba8e13..62387815 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/routingstrategies/RoutingStrategyRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/routingstrategies/RoutingStrategyRetrieveParams.kt @@ -10,8 +10,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class RoutingStrategyRetrieveParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/send/SendMessageParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/send/SendMessageParams.kt index 82b300cc..9d909e86 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/send/SendMessageParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/send/SendMessageParams.kt @@ -50,7 +50,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class SendMessageParams private constructor( private val body: Body, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantDeleteParams.kt index 0ecabed1..ea03b554 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantDeleteParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Delete a Tenant */ +/** + * Deletes a tenant. Its members' workspace-level profiles and preferences live outside the tenant + * and are managed separately. + */ class TenantDeleteParams private constructor( private val tenantId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantListParams.kt index 16721c74..c6123a83 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Get a List of Tenants */ +/** + * Lists the workspace's tenants, each carrying a name, parent tenant, properties, and default + * preferences. Paged. + */ class TenantListParams private constructor( private val cursor: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantListUsersParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantListUsersParams.kt index df6831bd..33a818d9 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantListUsersParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantListUsersParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TenantListUsersParams private constructor( private val tenantId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantRetrieveParams.kt index 0c079ff3..2a3af2c2 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Get a Tenant */ +/** + * Returns one tenant with its name, parent tenant id, default preferences, properties, and the user + * profile applied to its members. + */ class TenantRetrieveParams private constructor( private val tenantId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantUpdateParams.kt index b576d2b1..b926e16d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/TenantUpdateParams.kt @@ -21,7 +21,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Create or Replace a Tenant */ +/** + * Creates or replaces a tenant from a name, parent, brand, properties, and default preferences + * supplied in the request body. + */ class TenantUpdateParams private constructor( private val tenantId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/preferences/items/ItemDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/preferences/items/ItemDeleteParams.kt index 2401f0d6..a07a182f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/preferences/items/ItemDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/preferences/items/ItemDeleteParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Remove Default Preferences For Topic */ +/** + * Removes a tenant's default preference for one subscription topic, addressed by tenant id and + * topic id. + */ class ItemDeleteParams private constructor( private val tenantId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/preferences/items/ItemUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/preferences/items/ItemUpdateParams.kt index c85d7eb2..239a1e8c 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/preferences/items/ItemUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/preferences/items/ItemUpdateParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class ItemUpdateParams private constructor( private val tenantId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateDeleteParams.kt index dec1acab..2eaf366a 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateDeleteParams.kt @@ -13,12 +13,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TemplateDeleteParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateListParams.kt index 0e14f4b7..1517b6f0 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** List Templates in Tenant */ +/** + * Lists a tenant's notification templates, each carrying its version and published timestamp. + * Paged. + */ class TemplateListParams private constructor( private val tenantId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplatePublishParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplatePublishParams.kt index 2c74d73a..f571d3e0 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplatePublishParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplatePublishParams.kt @@ -14,10 +14,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TemplatePublishParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateReplaceParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateReplaceParams.kt index a787cfc6..29cb9b3a 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateReplaceParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateReplaceParams.kt @@ -13,12 +13,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TemplateReplaceParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateRetrieveParams.kt index aef09cc4..c50255dd 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/TemplateRetrieveParams.kt @@ -10,7 +10,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Get a Template in Tenant */ +/** + * Returns a tenant's notification template with its content, version, and created, updated, and + * published timestamps. + */ class TemplateRetrieveParams private constructor( private val tenantId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/versions/VersionRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/versions/VersionRetrieveParams.kt index 194d20d4..5f4d1459 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/versions/VersionRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/tenants/templates/versions/VersionRetrieveParams.kt @@ -11,12 +11,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class VersionRetrieveParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/translations/TranslationRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/translations/TranslationRetrieveParams.kt index 3663abce..b72767fa 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/translations/TranslationRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/translations/TranslationRetrieveParams.kt @@ -10,7 +10,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Get translations by locale */ +/** + * Returns the translation strings stored for one domain and locale, for use in localized + * notification content. + */ class TranslationRetrieveParams private constructor( private val domain: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/translations/TranslationUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/translations/TranslationUpdateParams.kt index 2d302263..4b7f2c60 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/translations/TranslationUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/translations/TranslationUpdateParams.kt @@ -10,7 +10,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Update a translation */ +/** + * Uploads the translation strings for one domain and locale. Courier uses them to render localized + * content for recipients in that locale. + */ class TranslationUpdateParams private constructor( private val domain: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceBulkReplaceParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceBulkReplaceParams.kt index 6301994f..47d725cd 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceBulkReplaceParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceBulkReplaceParams.kt @@ -25,21 +25,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class PreferenceBulkReplaceParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceBulkUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceBulkUpdateParams.kt index 3f3b17a2..22f4c5eb 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceBulkUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceBulkUpdateParams.kt @@ -25,19 +25,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class PreferenceBulkUpdateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceDeleteTopicParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceDeleteTopicParams.kt index 914d8a82..742317dd 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceDeleteTopicParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceDeleteTopicParams.kt @@ -13,9 +13,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class PreferenceDeleteTopicParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceRetrieveParams.kt index cbf3e55d..2955ee91 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Fetch all user preferences. */ +/** + * Returns a user's preference overrides with paging, one entry per subscription topic they have set + * a choice for. + */ class PreferenceRetrieveParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceRetrieveTopicParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceRetrieveTopicParams.kt index f6151c31..ee4cd95f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceRetrieveTopicParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceRetrieveTopicParams.kt @@ -10,7 +10,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class PreferenceRetrieveTopicParams private constructor( private val userId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceUpdateOrCreateTopicParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceUpdateOrCreateTopicParams.kt index 71cdde9e..41607c8c 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceUpdateOrCreateTopicParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/PreferenceUpdateOrCreateTopicParams.kt @@ -24,7 +24,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class PreferenceUpdateOrCreateTopicParams private constructor( private val userId: String, @@ -479,13 +482,17 @@ private constructor( ) : this(status, customRouting, hasCustomRouting, mutableMapOf()) /** + * 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. + * * @throws CourierInvalidDataException if the JSON field has an unexpected type or is * unexpectedly missing or null (e.g. if the server responded with an unexpected value). */ fun status(): PreferenceStatus = status.getRequired("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. * * @throws CourierInvalidDataException if the JSON field has an unexpected type (e.g. if the * server responded with an unexpected value). @@ -494,6 +501,9 @@ private constructor( customRouting.getOptional("custom_routing") /** + * Set to true to route this topic to the channels in custom_routing instead of the topic's + * default routing. + * * @throws CourierInvalidDataException if the JSON field has an unexpected type (e.g. if the * server responded with an unexpected value). */ @@ -568,6 +578,10 @@ private constructor( additionalProperties = topic.additionalProperties.toMutableMap() } + /** + * 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. + */ fun status(status: PreferenceStatus) = status(JsonField.of(status)) /** @@ -579,7 +593,10 @@ private constructor( */ fun status(status: JsonField) = apply { this.status = 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. + */ fun customRouting(customRouting: List?) = customRouting(JsonField.ofNullable(customRouting)) @@ -610,6 +627,10 @@ private constructor( } } + /** + * Set to true to route this topic to the channels in custom_routing instead of the + * topic's default routing. + */ fun hasCustomRouting(hasCustomRouting: Boolean?) = hasCustomRouting(JsonField.ofNullable(hasCustomRouting)) diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/TopicPreference.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/TopicPreference.kt index e7f6720f..febea8dc 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/TopicPreference.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/preferences/TopicPreference.kt @@ -60,31 +60,42 @@ private constructor( ) /** + * The topic's default status, returned on reads. It applies whenever the user has no override + * of their own (status equals this value). + * * @throws CourierInvalidDataException if the JSON field has an unexpected type or is * unexpectedly missing or null (e.g. if the server responded with an unexpected value). */ fun defaultStatus(): PreferenceStatus = defaultStatus.getRequired("default_status") /** + * 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. + * * @throws CourierInvalidDataException if the JSON field has an unexpected type or is * unexpectedly missing or null (e.g. if the server responded with an unexpected value). */ fun status(): PreferenceStatus = status.getRequired("status") /** + * The unique identifier of the subscription topic this preference applies to. + * * @throws CourierInvalidDataException if the JSON field has an unexpected type or is * unexpectedly missing or null (e.g. if the server responded with an unexpected value). */ fun topicId(): String = topicId.getRequired("topic_id") /** + * The display name of the subscription topic, returned on reads. + * * @throws CourierInvalidDataException if the JSON field has an unexpected type or is * unexpectedly missing or null (e.g. if the server responded with an unexpected value). */ fun topicName(): String = topicName.getRequired("topic_name") /** - * 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. * * @throws CourierInvalidDataException if the JSON field has an unexpected type (e.g. if the * server responded with an unexpected value). @@ -93,6 +104,9 @@ private constructor( customRouting.getOptional("custom_routing") /** + * Whether the user has chosen specific delivery channels for this topic (listed in + * custom_routing) rather than the topic's default routing. + * * @throws CourierInvalidDataException if the JSON field has an unexpected type (e.g. if the * server responded with an unexpected value). */ @@ -197,6 +211,10 @@ private constructor( additionalProperties = topicPreference.additionalProperties.toMutableMap() } + /** + * The topic's default status, returned on reads. It applies whenever the user has no + * override of their own (status equals this value). + */ fun defaultStatus(defaultStatus: PreferenceStatus) = defaultStatus(JsonField.of(defaultStatus)) @@ -211,6 +229,11 @@ private constructor( this.defaultStatus = defaultStatus } + /** + * 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. + */ fun status(status: PreferenceStatus) = status(JsonField.of(status)) /** @@ -222,6 +245,7 @@ private constructor( */ fun status(status: JsonField) = apply { this.status = status } + /** The unique identifier of the subscription topic this preference applies to. */ fun topicId(topicId: String) = topicId(JsonField.of(topicId)) /** @@ -232,6 +256,7 @@ private constructor( */ fun topicId(topicId: JsonField) = apply { this.topicId = topicId } + /** The display name of the subscription topic, returned on reads. */ fun topicName(topicName: String) = topicName(JsonField.of(topicName)) /** @@ -243,7 +268,11 @@ private constructor( */ fun topicName(topicName: JsonField) = apply { this.topicName = 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. + */ fun customRouting(customRouting: List?) = customRouting(JsonField.ofNullable(customRouting)) @@ -274,6 +303,10 @@ private constructor( } } + /** + * Whether the user has chosen specific delivery channels for this topic (listed in + * custom_routing) rather than the topic's default routing. + */ fun hasCustomRouting(hasCustomRouting: Boolean?) = hasCustomRouting(JsonField.ofNullable(hasCustomRouting)) diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantAddMultipleParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantAddMultipleParams.kt index d8f89fd3..01ca7b76 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantAddMultipleParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantAddMultipleParams.kt @@ -24,9 +24,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TenantAddMultipleParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantAddSingleParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantAddSingleParams.kt index 9b70b75a..e4356b5f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantAddSingleParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantAddSingleParams.kt @@ -22,10 +22,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TenantAddSingleParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantListParams.kt index e802934b..6d545c4d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TenantListParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantRemoveAllParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantRemoveAllParams.kt index 8d03fca0..87b6bd4e 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantRemoveAllParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantRemoveAllParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TenantRemoveAllParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantRemoveSingleParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantRemoveSingleParams.kt index 6dd013cd..e06ef5f5 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantRemoveSingleParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tenants/TenantRemoveSingleParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TenantRemoveSingleParams private constructor( private val userId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenAddMultipleParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenAddMultipleParams.kt index 246c6d21..9554ca2e 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenAddMultipleParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenAddMultipleParams.kt @@ -11,7 +11,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TokenAddMultipleParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenAddSingleParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenAddSingleParams.kt index bec9977e..62fb2e2d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenAddSingleParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenAddSingleParams.kt @@ -32,7 +32,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TokenAddSingleParams private constructor( private val userId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenDeleteParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenDeleteParams.kt index 37772af8..439c4fc7 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenDeleteParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenDeleteParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** Delete User Token */ +/** + * Deletes one device token for a user, addressed by the token value, so push sends no longer target + * that device. + */ class TokenDeleteParams private constructor( private val userId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenListParams.kt index db7e379e..6898741e 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TokenListParams private constructor( private val userId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenRetrieveParams.kt index 9c36e828..1d7f0687 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenRetrieveParams.kt @@ -10,7 +10,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TokenRetrieveParams private constructor( private val userId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenUpdateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenUpdateParams.kt index b1425c5c..e8c749cf 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenUpdateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/users/tokens/TokenUpdateParams.kt @@ -22,7 +22,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TokenUpdateParams private constructor( private val userId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceCreateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceCreateParams.kt index 307c5947..5fc6230f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceCreateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceCreateParams.kt @@ -10,8 +10,8 @@ import com.courier.core.http.QueryParams import java.util.Objects /** - * 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. */ class WorkspacePreferenceCreateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceListParams.kt index df73392c..ba787dfa 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceListParams.kt @@ -8,8 +8,8 @@ import com.courier.core.http.QueryParams import java.util.Objects /** - * 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. */ class WorkspacePreferenceListParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferencePublishParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferencePublishParams.kt index 813d4925..7fe013ef 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferencePublishParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferencePublishParams.kt @@ -12,9 +12,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class WorkspacePreferencePublishParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceRetrieveParams.kt index bd38e278..a91f62e2 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/WorkspacePreferenceRetrieveParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class WorkspacePreferenceRetrieveParams private constructor( private val sectionId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicArchiveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicArchiveParams.kt index b63d6d10..7268aa62 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicArchiveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicArchiveParams.kt @@ -12,7 +12,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** 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. + */ class TopicArchiveParams private constructor( private val sectionId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicCreateParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicCreateParams.kt index aa4e0616..5640268a 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicCreateParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicCreateParams.kt @@ -13,8 +13,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TopicCreateParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicListParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicListParams.kt index 1a22b576..e1916e81 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicListParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicListParams.kt @@ -9,7 +9,10 @@ import java.util.Objects import java.util.Optional import kotlin.jvm.optionals.getOrNull -/** List the topics in a workspace preference. */ +/** + * Returns the subscription topics inside a workspace preference, each with its default status and + * routing options. + */ class TopicListParams private constructor( private val sectionId: String?, diff --git a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicRetrieveParams.kt b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicRetrieveParams.kt index a7d341df..2cda0964 100644 --- a/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicRetrieveParams.kt +++ b/courier-java-core/src/main/kotlin/com/courier/models/workspacepreferences/topics/TopicRetrieveParams.kt @@ -11,8 +11,8 @@ import java.util.Optional import kotlin.jvm.optionals.getOrNull /** - * 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. */ class TopicRetrieveParams private constructor( diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/AudienceServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/AudienceServiceAsync.kt index 8495e45b..90256817 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/AudienceServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/AudienceServiceAsync.kt @@ -32,7 +32,10 @@ interface AudienceServiceAsync { */ fun withOptions(modifier: Consumer): AudienceServiceAsync - /** 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. + */ fun retrieve(audienceId: String): CompletableFuture = retrieve(audienceId, AudienceRetrieveParams.none()) @@ -64,7 +67,10 @@ interface AudienceServiceAsync { fun retrieve(audienceId: String, requestOptions: RequestOptions): CompletableFuture = retrieve(audienceId, AudienceRetrieveParams.none(), requestOptions) - /** Creates or updates audience. */ + /** + * Creates or replaces an audience from a filter and an AND or OR operator. Membership + * recalculates automatically as profiles change. + */ fun update(audienceId: String): CompletableFuture = update(audienceId, AudienceUpdateParams.none()) @@ -99,7 +105,10 @@ interface AudienceServiceAsync { ): CompletableFuture = update(audienceId, AudienceUpdateParams.none(), requestOptions) - /** 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. + */ fun list(): CompletableFuture = list(AudienceListParams.none()) /** @see list */ @@ -117,7 +126,10 @@ interface AudienceServiceAsync { fun list(requestOptions: RequestOptions): CompletableFuture = list(AudienceListParams.none(), requestOptions) - /** 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. + */ fun delete(audienceId: String): CompletableFuture = delete(audienceId, AudienceDeleteParams.none()) @@ -149,7 +161,10 @@ interface AudienceServiceAsync { fun delete(audienceId: String, requestOptions: RequestOptions): CompletableFuture = delete(audienceId, AudienceDeleteParams.none(), requestOptions) - /** 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. + */ fun listMembers(audienceId: String): CompletableFuture = listMembers(audienceId, AudienceListMembersParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/AuditEventServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/AuditEventServiceAsync.kt index 6591ccde..aa18f1c9 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/AuditEventServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/AuditEventServiceAsync.kt @@ -26,7 +26,10 @@ interface AuditEventServiceAsync { */ fun withOptions(modifier: Consumer): AuditEventServiceAsync - /** 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. + */ fun retrieve(auditEventId: String): CompletableFuture = retrieve(auditEventId, AuditEventRetrieveParams.none()) @@ -61,7 +64,10 @@ interface AuditEventServiceAsync { ): CompletableFuture = retrieve(auditEventId, AuditEventRetrieveParams.none(), requestOptions) - /** 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. + */ fun list(): CompletableFuture = list(AuditEventListParams.none()) /** @see list */ diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/AuthServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/AuthServiceAsync.kt index 989b0dbd..4da00497 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/AuthServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/AuthServiceAsync.kt @@ -24,7 +24,10 @@ interface AuthServiceAsync { */ fun withOptions(modifier: Consumer): AuthServiceAsync - /** 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. + */ fun issueToken(params: AuthIssueTokenParams): CompletableFuture = issueToken(params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/AutomationServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/AutomationServiceAsync.kt index ba0eef9d..92ee8b8b 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/AutomationServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/AutomationServiceAsync.kt @@ -27,7 +27,10 @@ interface AutomationServiceAsync { fun invoke(): InvokeServiceAsync - /** 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. + */ fun list(): CompletableFuture = list(AutomationListParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/BrandServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/BrandServiceAsync.kt index 049c1b6b..cd7b88a5 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/BrandServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/BrandServiceAsync.kt @@ -31,8 +31,8 @@ interface BrandServiceAsync { fun withOptions(modifier: Consumer): BrandServiceAsync /** - * 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. */ fun create(params: BrandCreateParams): CompletableFuture = create(params, RequestOptions.none()) @@ -43,7 +43,10 @@ interface BrandServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** Fetch a specific brand by brand ID. */ + /** + * Returns one brand by id, including its colors, logo and styling settings, Handlebars + * snippets, and published version. + */ fun retrieve(brandId: String): CompletableFuture = retrieve(brandId, BrandRetrieveParams.none()) @@ -75,7 +78,10 @@ interface BrandServiceAsync { fun retrieve(brandId: String, requestOptions: RequestOptions): CompletableFuture = retrieve(brandId, BrandRetrieveParams.none(), requestOptions) - /** 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. + */ fun update(brandId: String, params: BrandUpdateParams): CompletableFuture = update(brandId, params, RequestOptions.none()) @@ -97,7 +103,10 @@ interface BrandServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** Get the list of brands. */ + /** + * Lists the workspace's brands. Every entry carries its name, styling settings, snippets, and + * published version. + */ fun list(): CompletableFuture = list(BrandListParams.none()) /** @see list */ @@ -115,7 +124,10 @@ interface BrandServiceAsync { fun list(requestOptions: RequestOptions): CompletableFuture = list(BrandListParams.none(), requestOptions) - /** 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. + */ fun delete(brandId: String): CompletableFuture = delete(brandId, BrandDeleteParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/InboundServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/InboundServiceAsync.kt index 40ff5e0a..27d211e7 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/InboundServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/InboundServiceAsync.kt @@ -24,7 +24,10 @@ interface InboundServiceAsync { */ fun withOptions(modifier: Consumer): InboundServiceAsync - /** 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. + */ fun trackEvent(params: InboundTrackEventParams): CompletableFuture = trackEvent(params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/JourneyServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/JourneyServiceAsync.kt index ca96cdd8..400f7a78 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/JourneyServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/JourneyServiceAsync.kt @@ -43,11 +43,8 @@ interface JourneyServiceAsync { fun templates(): TemplateServiceAsync /** - * 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. */ fun create(params: JourneyCreateParams): CompletableFuture = create(params, RequestOptions.none()) @@ -110,7 +107,10 @@ interface JourneyServiceAsync { ): CompletableFuture = retrieve(templateId, JourneyRetrieveParams.none(), requestOptions) - /** Get the list of journeys. */ + /** + * Lists the workspace's journeys, each carrying a name, state, and enabled flag. Paged by + * cursor. + */ fun list(): CompletableFuture = list(JourneyListParams.none()) /** @see list */ @@ -129,8 +129,8 @@ interface JourneyServiceAsync { list(JourneyListParams.none(), requestOptions) /** - * 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. */ fun archive(templateId: String): CompletableFuture = archive(templateId, JourneyArchiveParams.none()) @@ -164,12 +164,8 @@ interface JourneyServiceAsync { archive(templateId, JourneyArchiveParams.none(), requestOptions) /** - * 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. */ fun cancel(params: JourneyCancelParams): CompletableFuture = cancel(params, RequestOptions.none()) @@ -220,8 +216,8 @@ interface JourneyServiceAsync { cancel(byRunId, RequestOptions.none()) /** - * 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. */ fun invoke( templateId: String, @@ -246,7 +242,10 @@ interface JourneyServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun listVersions(templateId: String): CompletableFuture = listVersions(templateId, JourneyListVersionsParams.none()) @@ -284,8 +283,8 @@ interface JourneyServiceAsync { listVersions(templateId, JourneyListVersionsParams.none(), requestOptions) /** - * 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. */ fun publish(templateId: String): CompletableFuture = publish(templateId, JourneyPublishParams.none()) @@ -322,10 +321,8 @@ interface JourneyServiceAsync { publish(templateId, JourneyPublishParams.none(), requestOptions) /** - * 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. */ fun replace( templateId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/ListServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/ListServiceAsync.kt index 816071a3..c04f54c3 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/ListServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/ListServiceAsync.kt @@ -33,7 +33,10 @@ interface ListServiceAsync { fun subscriptions(): SubscriptionServiceAsync - /** 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. + */ fun retrieve(listId: String): CompletableFuture = retrieve(listId, ListRetrieveParams.none()) @@ -68,7 +71,10 @@ interface ListServiceAsync { ): CompletableFuture = retrieve(listId, ListRetrieveParams.none(), requestOptions) - /** 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. + */ fun update(listId: String, params: ListUpdateParams): CompletableFuture = update(listId, params, RequestOptions.none()) @@ -89,7 +95,10 @@ interface ListServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun list(): CompletableFuture = list(ListListParams.none()) /** @see list */ @@ -106,7 +115,10 @@ interface ListServiceAsync { fun list(requestOptions: RequestOptions): CompletableFuture = list(ListListParams.none(), requestOptions) - /** 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. + */ fun delete(listId: String): CompletableFuture = delete(listId, ListDeleteParams.none()) /** @see delete */ @@ -136,7 +148,10 @@ interface ListServiceAsync { fun delete(listId: String, requestOptions: RequestOptions): CompletableFuture = delete(listId, ListDeleteParams.none(), requestOptions) - /** 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. + */ fun restore(listId: String, params: ListRestoreParams): CompletableFuture = restore(listId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/MessageServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/MessageServiceAsync.kt index cb502b47..4ceffd57 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/MessageServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/MessageServiceAsync.kt @@ -34,7 +34,10 @@ interface MessageServiceAsync { */ fun withOptions(modifier: Consumer): MessageServiceAsync - /** 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. + */ fun retrieve(messageId: String): CompletableFuture = retrieve(messageId, MessageRetrieveParams.none()) @@ -70,7 +73,10 @@ interface MessageServiceAsync { ): CompletableFuture = retrieve(messageId, MessageRetrieveParams.none(), requestOptions) - /** 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. + */ fun list(): CompletableFuture = list(MessageListParams.none()) /** @see list */ @@ -89,10 +95,8 @@ interface MessageServiceAsync { list(MessageListParams.none(), requestOptions) /** - * 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. */ fun cancel(messageId: String): CompletableFuture = cancel(messageId, MessageCancelParams.none()) @@ -128,7 +132,10 @@ interface MessageServiceAsync { ): CompletableFuture = cancel(messageId, MessageCancelParams.none(), requestOptions) - /** Get message content */ + /** + * Returns the rendered content Courier delivered for a message, broken out per channel, to + * confirm what the recipient received. + */ fun content(messageId: String): CompletableFuture = content(messageId, MessageContentParams.none()) @@ -163,7 +170,10 @@ interface MessageServiceAsync { ): CompletableFuture = content(messageId, MessageContentParams.none(), requestOptions) - /** 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. + */ fun history(messageId: String): CompletableFuture = history(messageId, MessageHistoryParams.none()) @@ -199,10 +209,8 @@ interface MessageServiceAsync { history(messageId, MessageHistoryParams.none(), requestOptions) /** - * 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. */ fun resend(messageId: String): CompletableFuture = resend(messageId, MessageResendParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/NotificationServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/NotificationServiceAsync.kt index 795006ee..7dd08277 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/NotificationServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/NotificationServiceAsync.kt @@ -114,7 +114,10 @@ interface NotificationServiceAsync { ): CompletableFuture = retrieve(id, NotificationRetrieveParams.none(), requestOptions) - /** 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. + */ fun list(): CompletableFuture = list(NotificationListParams.none()) /** @see list */ @@ -132,7 +135,10 @@ interface NotificationServiceAsync { fun list(requestOptions: RequestOptions): CompletableFuture = list(NotificationListParams.none(), requestOptions) - /** Archive a notification template. */ + /** + * Archives a notification template, preventing new sends from referencing it. The template + * stays retrievable for its version history. + */ fun archive(id: String): CompletableFuture = archive(id, NotificationArchiveParams.none()) @@ -164,12 +170,8 @@ interface NotificationServiceAsync { archive(id, NotificationArchiveParams.none(), requestOptions) /** - * 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. */ fun duplicate(id: String): CompletableFuture = duplicate(id, NotificationDuplicateParams.none()) @@ -207,7 +209,10 @@ interface NotificationServiceAsync { ): CompletableFuture = duplicate(id, NotificationDuplicateParams.none(), requestOptions) - /** List versions of a notification template. */ + /** + * Returns a notification template's published versions, most recent first, for comparison or + * rollback. Paged. + */ fun listVersions(id: String): CompletableFuture = listVersions(id, NotificationListVersionsParams.none()) @@ -280,8 +285,8 @@ interface NotificationServiceAsync { publish(id, NotificationPublishParams.none(), requestOptions) /** - * 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. */ fun putContent( id: String, @@ -310,8 +315,8 @@ interface NotificationServiceAsync { ): CompletableFuture /** - * 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. */ fun putElement( elementId: String, @@ -340,8 +345,8 @@ interface NotificationServiceAsync { ): CompletableFuture /** - * 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. */ fun putLocale( localeId: String, @@ -369,7 +374,10 @@ interface NotificationServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun replace( id: String, params: NotificationReplaceParams, @@ -395,9 +403,8 @@ interface NotificationServiceAsync { ): CompletableFuture /** - * 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. */ fun retrieveContent(id: String): CompletableFuture = retrieveContent(id, NotificationRetrieveContentParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/ProfileServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/ProfileServiceAsync.kt index dfc3ed15..b5589f93 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/ProfileServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/ProfileServiceAsync.kt @@ -35,8 +35,8 @@ interface ProfileServiceAsync { fun lists(): ListServiceAsync /** - * 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. */ fun create( userId: String, @@ -61,7 +61,10 @@ interface ProfileServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun retrieve(userId: String): CompletableFuture = retrieve(userId, ProfileRetrieveParams.none()) @@ -96,7 +99,10 @@ interface ProfileServiceAsync { ): CompletableFuture = retrieve(userId, ProfileRetrieveParams.none(), requestOptions) - /** Update a profile */ + /** + * Applies a JSON Patch to a user profile, adding, removing, or replacing individual fields + * without sending the whole object. + */ fun update(userId: String, params: ProfileUpdateParams): CompletableFuture = update(userId, params, RequestOptions.none()) @@ -117,7 +123,10 @@ interface ProfileServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun delete(userId: String): CompletableFuture = delete(userId, ProfileDeleteParams.none()) @@ -149,11 +158,8 @@ interface ProfileServiceAsync { delete(userId, ProfileDeleteParams.none(), requestOptions) /** - * 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. */ fun replace( userId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/ProviderServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/ProviderServiceAsync.kt index de000978..acfb32af 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/ProviderServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/ProviderServiceAsync.kt @@ -34,8 +34,8 @@ interface ProviderServiceAsync { fun catalog(): CatalogServiceAsync /** - * 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. */ fun create(params: ProviderCreateParams): CompletableFuture = create(params, RequestOptions.none()) @@ -46,7 +46,10 @@ interface ProviderServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** Fetch a single provider configuration by ID. */ + /** + * Returns one configured provider by id, including its channel, provider key, alias, title, and + * current settings. + */ fun retrieve(id: String): CompletableFuture = retrieve(id, ProviderRetrieveParams.none()) @@ -78,10 +81,8 @@ interface ProviderServiceAsync { retrieve(id, ProviderRetrieveParams.none(), requestOptions) /** - * 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. */ fun update(id: String, params: ProviderUpdateParams): CompletableFuture = update(id, params, RequestOptions.none()) @@ -104,8 +105,8 @@ interface ProviderServiceAsync { ): CompletableFuture /** - * 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. */ fun list(): CompletableFuture = list(ProviderListParams.none()) @@ -125,8 +126,8 @@ interface ProviderServiceAsync { list(ProviderListParams.none(), requestOptions) /** - * 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. */ fun delete(id: String): CompletableFuture = delete(id, ProviderDeleteParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/RequestServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/RequestServiceAsync.kt index 22cab94b..9be2bf06 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/RequestServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/RequestServiceAsync.kt @@ -23,7 +23,10 @@ interface RequestServiceAsync { */ fun withOptions(modifier: Consumer): RequestServiceAsync - /** 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. + */ fun archive(requestId: String): CompletableFuture = archive(requestId, RequestArchiveParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/RoutingStrategyServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/RoutingStrategyServiceAsync.kt index 36c9f9c7..280a267e 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/RoutingStrategyServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/RoutingStrategyServiceAsync.kt @@ -65,8 +65,8 @@ interface RoutingStrategyServiceAsync { create(routingStrategyCreateRequest, RequestOptions.none()) /** - * 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. */ fun retrieve(id: String): CompletableFuture = retrieve(id, RoutingStrategyRetrieveParams.none()) @@ -160,8 +160,8 @@ interface RoutingStrategyServiceAsync { archive(id, RoutingStrategyArchiveParams.none(), requestOptions) /** - * 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. */ fun listNotifications(id: String): CompletableFuture = listNotifications(id, RoutingStrategyListNotificationsParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/SendServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/SendServiceAsync.kt index c9589665..91befdd9 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/SendServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/SendServiceAsync.kt @@ -24,7 +24,10 @@ interface SendServiceAsync { */ fun withOptions(modifier: Consumer): SendServiceAsync - /** 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. + */ fun message(params: SendMessageParams): CompletableFuture = message(params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/TenantServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/TenantServiceAsync.kt index df63b8f2..ea27e955 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/TenantServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/TenantServiceAsync.kt @@ -37,7 +37,10 @@ interface TenantServiceAsync { fun templates(): TemplateServiceAsync - /** Get a Tenant */ + /** + * Returns one tenant with its name, parent tenant id, default preferences, properties, and the + * user profile applied to its members. + */ fun retrieve(tenantId: String): CompletableFuture = retrieve(tenantId, TenantRetrieveParams.none()) @@ -69,7 +72,10 @@ interface TenantServiceAsync { fun retrieve(tenantId: String, requestOptions: RequestOptions): CompletableFuture = retrieve(tenantId, TenantRetrieveParams.none(), requestOptions) - /** Create or Replace a Tenant */ + /** + * Creates or replaces a tenant from a name, parent, brand, properties, and default preferences + * supplied in the request body. + */ fun update(tenantId: String, params: TenantUpdateParams): CompletableFuture = update(tenantId, params, RequestOptions.none()) @@ -91,7 +97,10 @@ interface TenantServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** Get a List of Tenants */ + /** + * Lists the workspace's tenants, each carrying a name, parent tenant, properties, and default + * preferences. Paged. + */ fun list(): CompletableFuture = list(TenantListParams.none()) /** @see list */ @@ -109,7 +118,10 @@ interface TenantServiceAsync { fun list(requestOptions: RequestOptions): CompletableFuture = list(TenantListParams.none(), requestOptions) - /** Delete a Tenant */ + /** + * Deletes a tenant. Its members' workspace-level profiles and preferences live outside the + * tenant and are managed separately. + */ fun delete(tenantId: String): CompletableFuture = delete(tenantId, TenantDeleteParams.none()) @@ -141,7 +153,10 @@ interface TenantServiceAsync { fun delete(tenantId: String, requestOptions: RequestOptions): CompletableFuture = delete(tenantId, TenantDeleteParams.none(), requestOptions) - /** 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. + */ fun listUsers(tenantId: String): CompletableFuture = listUsers(tenantId, TenantListUsersParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/TranslationServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/TranslationServiceAsync.kt index ded96302..904a7722 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/TranslationServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/TranslationServiceAsync.kt @@ -25,7 +25,10 @@ interface TranslationServiceAsync { */ fun withOptions(modifier: Consumer): TranslationServiceAsync - /** Get translations by locale */ + /** + * Returns the translation strings stored for one domain and locale, for use in localized + * notification content. + */ fun retrieve(locale: String, params: TranslationRetrieveParams): CompletableFuture = retrieve(locale, params, RequestOptions.none()) @@ -47,7 +50,10 @@ interface TranslationServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** Update a translation */ + /** + * Uploads the translation strings for one domain and locale. Courier uses them to render + * localized content for recipients in that locale. + */ fun update(locale: String, params: TranslationUpdateParams): CompletableFuture = update(locale, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/WorkspacePreferenceServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/WorkspacePreferenceServiceAsync.kt index e47246dc..67b85e27 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/WorkspacePreferenceServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/WorkspacePreferenceServiceAsync.kt @@ -38,8 +38,8 @@ interface WorkspacePreferenceServiceAsync { fun topics(): TopicServiceAsync /** - * 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. */ fun create( params: WorkspacePreferenceCreateParams @@ -69,7 +69,10 @@ interface WorkspacePreferenceServiceAsync { ): CompletableFuture = create(workspacePreferenceCreateRequest, RequestOptions.none()) - /** 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. + */ fun retrieve(sectionId: String): CompletableFuture = retrieve(sectionId, WorkspacePreferenceRetrieveParams.none()) @@ -107,8 +110,8 @@ interface WorkspacePreferenceServiceAsync { retrieve(sectionId, WorkspacePreferenceRetrieveParams.none(), requestOptions) /** - * 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. */ fun list(): CompletableFuture = list(WorkspacePreferenceListParams.none()) @@ -164,9 +167,8 @@ interface WorkspacePreferenceServiceAsync { archive(sectionId, WorkspacePreferenceArchiveParams.none(), requestOptions) /** - * 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. */ fun publish(): CompletableFuture = publish(WorkspacePreferencePublishParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/automations/InvokeServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/automations/InvokeServiceAsync.kt index 68d810c6..aace7b93 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/automations/InvokeServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/automations/InvokeServiceAsync.kt @@ -26,9 +26,8 @@ interface InvokeServiceAsync { fun withOptions(modifier: Consumer): InvokeServiceAsync /** - * 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. */ fun invokeAdHoc(params: InvokeInvokeAdHocParams): CompletableFuture = invokeAdHoc(params, RequestOptions.none()) @@ -39,7 +38,10 @@ interface InvokeServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun invokeByTemplate( templateId: String, params: InvokeInvokeByTemplateParams, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/digests/ScheduleServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/digests/ScheduleServiceAsync.kt index 92475a25..81914853 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/digests/ScheduleServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/digests/ScheduleServiceAsync.kt @@ -27,9 +27,8 @@ interface ScheduleServiceAsync { fun withOptions(modifier: Consumer): ScheduleServiceAsync /** - * 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. */ fun listInstances(scheduleId: String): CompletableFuture = listInstances(scheduleId, ScheduleListInstancesParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/journeys/TemplateServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/journeys/TemplateServiceAsync.kt index 663afc24..1209922e 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/journeys/TemplateServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/journeys/TemplateServiceAsync.kt @@ -67,8 +67,8 @@ interface TemplateServiceAsync { ): CompletableFuture /** - * 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. */ fun retrieve( notificationId: String, @@ -133,7 +133,10 @@ interface TemplateServiceAsync { ): CompletableFuture = list(templateId, TemplateListParams.none(), requestOptions) - /** 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. + */ fun archive(notificationId: String, params: TemplateArchiveParams): CompletableFuture = archive(notificationId, params, RequestOptions.none()) @@ -156,8 +159,8 @@ interface TemplateServiceAsync { ): CompletableFuture /** - * 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. */ fun listVersions( notificationId: String, @@ -186,8 +189,8 @@ interface TemplateServiceAsync { ): CompletableFuture /** - * 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. */ fun publish(notificationId: String, params: TemplatePublishParams): CompletableFuture = publish(notificationId, params, RequestOptions.none()) @@ -270,7 +273,10 @@ interface TemplateServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun replace( notificationId: String, params: TemplateReplaceParams, @@ -296,10 +302,8 @@ interface TemplateServiceAsync { ): CompletableFuture /** - * 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. */ fun retrieveContent( notificationId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/lists/SubscriptionServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/lists/SubscriptionServiceAsync.kt index c18d9413..2b5f6b93 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/lists/SubscriptionServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/lists/SubscriptionServiceAsync.kt @@ -29,7 +29,10 @@ interface SubscriptionServiceAsync { */ fun withOptions(modifier: Consumer): SubscriptionServiceAsync - /** Get the list's subscriptions. */ + /** + * Returns the users subscribed to a list with paging, each with the preferences recorded for + * that subscription. + */ fun list(listId: String): CompletableFuture = list(listId, SubscriptionListParams.none()) @@ -114,8 +117,8 @@ interface SubscriptionServiceAsync { ): CompletableFuture /** - * 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. */ fun subscribeUser( userId: String, @@ -140,7 +143,10 @@ interface SubscriptionServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun unsubscribeUser( userId: String, params: SubscriptionUnsubscribeUserParams, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/notifications/CheckServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/notifications/CheckServiceAsync.kt index 9470d9b3..0e2986d0 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/notifications/CheckServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/notifications/CheckServiceAsync.kt @@ -28,7 +28,10 @@ interface CheckServiceAsync { */ fun withOptions(modifier: Consumer): CheckServiceAsync - /** 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. + */ fun update( submissionId: String, params: CheckUpdateParams, @@ -52,7 +55,10 @@ interface CheckServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** Retrieve the submission checks for a notification template. */ + /** + * Returns the approval checks recorded for a template submission, each with its pass or fail + * result. + */ fun list(submissionId: String, params: CheckListParams): CompletableFuture = list(submissionId, params, RequestOptions.none()) @@ -74,7 +80,10 @@ interface CheckServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun delete(submissionId: String, params: CheckDeleteParams): CompletableFuture = delete(submissionId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/profiles/ListServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/profiles/ListServiceAsync.kt index b5fc9de1..5d984219 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/profiles/ListServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/profiles/ListServiceAsync.kt @@ -28,7 +28,10 @@ interface ListServiceAsync { */ fun withOptions(modifier: Consumer): ListServiceAsync - /** 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. + */ fun retrieve(userId: String): CompletableFuture = retrieve(userId, ListRetrieveParams.none()) @@ -63,7 +66,10 @@ interface ListServiceAsync { ): CompletableFuture = retrieve(userId, ListRetrieveParams.none(), requestOptions) - /** 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. + */ fun delete(userId: String): CompletableFuture = delete(userId, ListDeleteParams.none()) @@ -99,8 +105,8 @@ interface ListServiceAsync { delete(userId, ListDeleteParams.none(), requestOptions) /** - * 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. */ fun subscribe( userId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/providers/CatalogServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/providers/CatalogServiceAsync.kt index 601a3b65..9a43e966 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/providers/CatalogServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/providers/CatalogServiceAsync.kt @@ -25,9 +25,8 @@ interface CatalogServiceAsync { fun withOptions(modifier: Consumer): CatalogServiceAsync /** - * 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. */ fun list(): CompletableFuture = list(CatalogListParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/TemplateServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/TemplateServiceAsync.kt index 57af2f50..e86c8f42 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/TemplateServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/TemplateServiceAsync.kt @@ -35,7 +35,10 @@ interface TemplateServiceAsync { fun versions(): VersionServiceAsync - /** Get a Template in Tenant */ + /** + * Returns a tenant's notification template with its content, version, and created, updated, and + * published timestamps. + */ fun retrieve( templateId: String, params: TemplateRetrieveParams, @@ -60,7 +63,10 @@ interface TemplateServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** List Templates in Tenant */ + /** + * Lists a tenant's notification templates, each carrying its version and published timestamp. + * Paged. + */ fun list(tenantId: String): CompletableFuture = list(tenantId, TemplateListParams.none()) @@ -96,12 +102,8 @@ interface TemplateServiceAsync { list(tenantId, TemplateListParams.none(), requestOptions) /** - * 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. */ fun delete(templateId: String, params: TemplateDeleteParams): CompletableFuture = delete(templateId, params, RequestOptions.none()) @@ -125,10 +127,8 @@ interface TemplateServiceAsync { ): CompletableFuture /** - * 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. */ fun publish( templateId: String, @@ -156,12 +156,8 @@ interface TemplateServiceAsync { ): CompletableFuture /** - * 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. */ fun replace( templateId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/preferences/ItemServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/preferences/ItemServiceAsync.kt index 67da4bad..82c17203 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/preferences/ItemServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/preferences/ItemServiceAsync.kt @@ -24,7 +24,10 @@ interface ItemServiceAsync { */ fun withOptions(modifier: Consumer): ItemServiceAsync - /** 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. + */ fun update(topicId: String, params: ItemUpdateParams): CompletableFuture = update(topicId, params, RequestOptions.none()) @@ -46,7 +49,10 @@ interface ItemServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** Remove Default Preferences For Topic */ + /** + * Removes a tenant's default preference for one subscription topic, addressed by tenant id and + * topic id. + */ fun delete(topicId: String, params: ItemDeleteParams): CompletableFuture = delete(topicId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/templates/VersionServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/templates/VersionServiceAsync.kt index e03aed25..1c40d52c 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/templates/VersionServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/tenants/templates/VersionServiceAsync.kt @@ -25,12 +25,8 @@ interface VersionServiceAsync { fun withOptions(modifier: Consumer): VersionServiceAsync /** - * 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. */ fun retrieve( version: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/users/PreferenceServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/users/PreferenceServiceAsync.kt index 5b129471..18c38c84 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/users/PreferenceServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/users/PreferenceServiceAsync.kt @@ -34,7 +34,10 @@ interface PreferenceServiceAsync { */ fun withOptions(modifier: Consumer): PreferenceServiceAsync - /** Fetch all user preferences. */ + /** + * Returns a user's preference overrides with paging, one entry per subscription topic they have + * set a choice for. + */ fun retrieve(userId: String): CompletableFuture = retrieve(userId, PreferenceRetrieveParams.none()) @@ -71,21 +74,8 @@ interface PreferenceServiceAsync { retrieve(userId, PreferenceRetrieveParams.none(), requestOptions) /** - * 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. */ fun bulkReplace( userId: String, @@ -113,20 +103,8 @@ interface PreferenceServiceAsync { ): CompletableFuture /** - * 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. */ fun bulkUpdate( userId: String, @@ -154,9 +132,8 @@ interface PreferenceServiceAsync { ): CompletableFuture /** - * 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. */ fun deleteTopic( topicId: String, @@ -181,7 +158,10 @@ interface PreferenceServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun retrieveTopic( topicId: String, params: PreferenceRetrieveTopicParams, @@ -208,7 +188,10 @@ interface PreferenceServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun updateOrCreateTopic( topicId: String, params: PreferenceUpdateOrCreateTopicParams, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/users/TenantServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/users/TenantServiceAsync.kt index c0c2f924..660221d3 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/users/TenantServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/users/TenantServiceAsync.kt @@ -29,7 +29,10 @@ interface TenantServiceAsync { */ fun withOptions(modifier: Consumer): TenantServiceAsync - /** 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. + */ fun list(userId: String): CompletableFuture = list(userId, TenantListParams.none()) @@ -64,9 +67,8 @@ interface TenantServiceAsync { ): CompletableFuture = list(userId, TenantListParams.none(), requestOptions) /** - * 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. */ fun addMultiple(userId: String, params: TenantAddMultipleParams): CompletableFuture = addMultiple(userId, params, RequestOptions.none()) @@ -90,10 +92,8 @@ interface TenantServiceAsync { ): CompletableFuture /** - * 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. */ fun addSingle(tenantId: String, params: TenantAddSingleParams): CompletableFuture = addSingle(tenantId, params, RequestOptions.none()) @@ -116,7 +116,10 @@ interface TenantServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun removeAll(userId: String): CompletableFuture = removeAll(userId, TenantRemoveAllParams.none()) @@ -148,7 +151,10 @@ interface TenantServiceAsync { fun removeAll(userId: String, requestOptions: RequestOptions): CompletableFuture = removeAll(userId, TenantRemoveAllParams.none(), requestOptions) - /** 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. + */ fun removeSingle(tenantId: String, params: TenantRemoveSingleParams): CompletableFuture = removeSingle(tenantId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/users/TokenServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/users/TokenServiceAsync.kt index 9be42244..76382299 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/users/TokenServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/users/TokenServiceAsync.kt @@ -31,7 +31,10 @@ interface TokenServiceAsync { */ fun withOptions(modifier: Consumer): TokenServiceAsync - /** 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. + */ fun retrieve( token: String, params: TokenRetrieveParams, @@ -55,7 +58,10 @@ interface TokenServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun update(token: String, params: TokenUpdateParams): CompletableFuture = update(token, params, RequestOptions.none()) @@ -76,7 +82,10 @@ interface TokenServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun list(userId: String): CompletableFuture = list(userId, TokenListParams.none()) @@ -108,7 +117,10 @@ interface TokenServiceAsync { fun list(userId: String, requestOptions: RequestOptions): CompletableFuture = list(userId, TokenListParams.none(), requestOptions) - /** Delete User Token */ + /** + * Deletes one device token for a user, addressed by the token value, so push sends no longer + * target that device. + */ fun delete(token: String, params: TokenDeleteParams): CompletableFuture = delete(token, params, RequestOptions.none()) @@ -129,7 +141,10 @@ interface TokenServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** 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. + */ fun addMultiple(userId: String): CompletableFuture = addMultiple(userId, TokenAddMultipleParams.none()) @@ -161,7 +176,10 @@ interface TokenServiceAsync { fun addMultiple(userId: String, requestOptions: RequestOptions): CompletableFuture = addMultiple(userId, TokenAddMultipleParams.none(), requestOptions) - /** 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. + */ fun addSingle(token: String, params: TokenAddSingleParams): CompletableFuture = addSingle(token, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/async/workspacepreferences/TopicServiceAsync.kt b/courier-java-core/src/main/kotlin/com/courier/services/async/workspacepreferences/TopicServiceAsync.kt index 42214e08..e9061c65 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/async/workspacepreferences/TopicServiceAsync.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/async/workspacepreferences/TopicServiceAsync.kt @@ -31,8 +31,8 @@ interface TopicServiceAsync { fun withOptions(modifier: Consumer): TopicServiceAsync /** - * 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. */ fun create( sectionId: String, @@ -59,9 +59,8 @@ interface TopicServiceAsync { ): CompletableFuture /** - * 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. */ fun retrieve( topicId: String, @@ -89,7 +88,10 @@ interface TopicServiceAsync { requestOptions: RequestOptions = RequestOptions.none(), ): CompletableFuture - /** List the topics in a workspace preference. */ + /** + * Returns the subscription topics inside a workspace preference, each with its default status + * and routing options. + */ fun list(sectionId: String): CompletableFuture = list(sectionId, TopicListParams.none()) @@ -125,7 +127,10 @@ interface TopicServiceAsync { ): CompletableFuture = list(sectionId, TopicListParams.none(), requestOptions) - /** 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. + */ fun archive(topicId: String, params: TopicArchiveParams): CompletableFuture = archive(topicId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/AudienceService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/AudienceService.kt index 4b73b462..edf0689e 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/AudienceService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/AudienceService.kt @@ -32,7 +32,10 @@ interface AudienceService { */ fun withOptions(modifier: Consumer): AudienceService - /** 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. + */ fun retrieve(audienceId: String): Audience = retrieve(audienceId, AudienceRetrieveParams.none()) /** @see retrieve */ @@ -61,7 +64,10 @@ interface AudienceService { fun retrieve(audienceId: String, requestOptions: RequestOptions): Audience = retrieve(audienceId, AudienceRetrieveParams.none(), requestOptions) - /** Creates or updates audience. */ + /** + * Creates or replaces an audience from a filter and an AND or OR operator. Membership + * recalculates automatically as profiles change. + */ fun update(audienceId: String): AudienceUpdateResponse = update(audienceId, AudienceUpdateParams.none()) @@ -93,7 +99,10 @@ interface AudienceService { fun update(audienceId: String, requestOptions: RequestOptions): AudienceUpdateResponse = update(audienceId, AudienceUpdateParams.none(), requestOptions) - /** 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. + */ fun list(): AudienceListResponse = list(AudienceListParams.none()) /** @see list */ @@ -110,7 +119,10 @@ interface AudienceService { fun list(requestOptions: RequestOptions): AudienceListResponse = list(AudienceListParams.none(), requestOptions) - /** 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. + */ fun delete(audienceId: String) = delete(audienceId, AudienceDeleteParams.none()) /** @see delete */ @@ -134,7 +146,10 @@ interface AudienceService { fun delete(audienceId: String, requestOptions: RequestOptions) = delete(audienceId, AudienceDeleteParams.none(), requestOptions) - /** 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. + */ fun listMembers(audienceId: String): AudienceListMembersResponse = listMembers(audienceId, AudienceListMembersParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/AuditEventService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/AuditEventService.kt index da38d7a5..9c8940a0 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/AuditEventService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/AuditEventService.kt @@ -26,7 +26,10 @@ interface AuditEventService { */ fun withOptions(modifier: Consumer): AuditEventService - /** 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. + */ fun retrieve(auditEventId: String): AuditEvent = retrieve(auditEventId, AuditEventRetrieveParams.none()) @@ -57,7 +60,10 @@ interface AuditEventService { fun retrieve(auditEventId: String, requestOptions: RequestOptions): AuditEvent = retrieve(auditEventId, AuditEventRetrieveParams.none(), requestOptions) - /** 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. + */ fun list(): AuditEventListResponse = list(AuditEventListParams.none()) /** @see list */ diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/AuthService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/AuthService.kt index 6f732da0..003e3b1f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/AuthService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/AuthService.kt @@ -24,7 +24,10 @@ interface AuthService { */ fun withOptions(modifier: Consumer): AuthService - /** 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. + */ fun issueToken(params: AuthIssueTokenParams): AuthIssueTokenResponse = issueToken(params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/AutomationService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/AutomationService.kt index 8c6bf97d..79ba59f9 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/AutomationService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/AutomationService.kt @@ -27,7 +27,10 @@ interface AutomationService { fun invoke(): InvokeService - /** 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. + */ fun list(): AutomationTemplateListResponse = list(AutomationListParams.none()) /** @see list */ diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/BrandService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/BrandService.kt index 1200f4c1..885390b6 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/BrandService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/BrandService.kt @@ -31,8 +31,8 @@ interface BrandService { fun withOptions(modifier: Consumer): BrandService /** - * 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. */ fun create(params: BrandCreateParams): Brand = create(params, RequestOptions.none()) @@ -42,7 +42,10 @@ interface BrandService { requestOptions: RequestOptions = RequestOptions.none(), ): Brand - /** Fetch a specific brand by brand ID. */ + /** + * Returns one brand by id, including its colors, logo and styling settings, Handlebars + * snippets, and published version. + */ fun retrieve(brandId: String): Brand = retrieve(brandId, BrandRetrieveParams.none()) /** @see retrieve */ @@ -69,7 +72,10 @@ interface BrandService { fun retrieve(brandId: String, requestOptions: RequestOptions): Brand = retrieve(brandId, BrandRetrieveParams.none(), requestOptions) - /** 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. + */ fun update(brandId: String, params: BrandUpdateParams): Brand = update(brandId, params, RequestOptions.none()) @@ -89,7 +95,10 @@ interface BrandService { requestOptions: RequestOptions = RequestOptions.none(), ): Brand - /** Get the list of brands. */ + /** + * Lists the workspace's brands. Every entry carries its name, styling settings, snippets, and + * published version. + */ fun list(): BrandListResponse = list(BrandListParams.none()) /** @see list */ @@ -106,7 +115,10 @@ interface BrandService { fun list(requestOptions: RequestOptions): BrandListResponse = list(BrandListParams.none(), requestOptions) - /** 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. + */ fun delete(brandId: String) = delete(brandId, BrandDeleteParams.none()) /** @see delete */ diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/InboundService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/InboundService.kt index 664deb45..20a2f1b3 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/InboundService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/InboundService.kt @@ -24,7 +24,10 @@ interface InboundService { */ fun withOptions(modifier: Consumer): InboundService - /** 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. + */ fun trackEvent(params: InboundTrackEventParams): InboundTrackEventResponse = trackEvent(params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/JourneyService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/JourneyService.kt index d70d5f95..7ed8fb6c 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/JourneyService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/JourneyService.kt @@ -43,11 +43,8 @@ interface JourneyService { fun templates(): TemplateService /** - * 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. */ fun create(params: JourneyCreateParams): JourneyResponse = create(params, RequestOptions.none()) @@ -105,7 +102,10 @@ interface JourneyService { fun retrieve(templateId: String, requestOptions: RequestOptions): JourneyResponse = retrieve(templateId, JourneyRetrieveParams.none(), requestOptions) - /** Get the list of journeys. */ + /** + * Lists the workspace's journeys, each carrying a name, state, and enabled flag. Paged by + * cursor. + */ fun list(): JourneysListResponse = list(JourneyListParams.none()) /** @see list */ @@ -123,8 +123,8 @@ interface JourneyService { list(JourneyListParams.none(), requestOptions) /** - * 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. */ fun archive(templateId: String) = archive(templateId, JourneyArchiveParams.none()) @@ -153,12 +153,8 @@ interface JourneyService { archive(templateId, JourneyArchiveParams.none(), requestOptions) /** - * 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. */ fun cancel(params: JourneyCancelParams): CancelJourneyResponse = cancel(params, RequestOptions.none()) @@ -205,8 +201,8 @@ interface JourneyService { cancel(byRunId, RequestOptions.none()) /** - * 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. */ fun invoke(templateId: String, params: JourneyInvokeParams): JourneysInvokeResponse = invoke(templateId, params, RequestOptions.none()) @@ -229,7 +225,10 @@ interface JourneyService { requestOptions: RequestOptions = RequestOptions.none(), ): JourneysInvokeResponse - /** 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. + */ fun listVersions(templateId: String): JourneyVersionsListResponse = listVersions(templateId, JourneyListVersionsParams.none()) @@ -265,8 +264,8 @@ interface JourneyService { listVersions(templateId, JourneyListVersionsParams.none(), requestOptions) /** - * 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. */ fun publish(templateId: String): JourneyResponse = publish(templateId, JourneyPublishParams.none()) @@ -299,10 +298,8 @@ interface JourneyService { publish(templateId, JourneyPublishParams.none(), requestOptions) /** - * 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. */ fun replace(templateId: String, params: JourneyReplaceParams): JourneyResponse = replace(templateId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/ListService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/ListService.kt index b5fd0e55..5e071c69 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/ListService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/ListService.kt @@ -33,7 +33,10 @@ interface ListService { fun subscriptions(): SubscriptionService - /** 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. + */ fun retrieve(listId: String): SubscriptionList = retrieve(listId, ListRetrieveParams.none()) /** @see retrieve */ @@ -63,7 +66,10 @@ interface ListService { fun retrieve(listId: String, requestOptions: RequestOptions): SubscriptionList = retrieve(listId, ListRetrieveParams.none(), requestOptions) - /** 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. + */ fun update(listId: String, params: ListUpdateParams) = update(listId, params, RequestOptions.none()) @@ -80,7 +86,10 @@ interface ListService { /** @see update */ fun update(params: ListUpdateParams, requestOptions: RequestOptions = RequestOptions.none()) - /** 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. + */ fun list(): ListListResponse = list(ListListParams.none()) /** @see list */ @@ -97,7 +106,10 @@ interface ListService { fun list(requestOptions: RequestOptions): ListListResponse = list(ListListParams.none(), requestOptions) - /** 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. + */ fun delete(listId: String) = delete(listId, ListDeleteParams.none()) /** @see delete */ @@ -121,7 +133,10 @@ interface ListService { fun delete(listId: String, requestOptions: RequestOptions) = delete(listId, ListDeleteParams.none(), requestOptions) - /** 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. + */ fun restore(listId: String, params: ListRestoreParams) = restore(listId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/MessageService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/MessageService.kt index cefd97f3..ef0dbfe6 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/MessageService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/MessageService.kt @@ -34,7 +34,10 @@ interface MessageService { */ fun withOptions(modifier: Consumer): MessageService - /** 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. + */ fun retrieve(messageId: String): MessageRetrieveResponse = retrieve(messageId, MessageRetrieveParams.none()) @@ -66,7 +69,10 @@ interface MessageService { fun retrieve(messageId: String, requestOptions: RequestOptions): MessageRetrieveResponse = retrieve(messageId, MessageRetrieveParams.none(), requestOptions) - /** 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. + */ fun list(): MessageListResponse = list(MessageListParams.none()) /** @see list */ @@ -84,10 +90,8 @@ interface MessageService { list(MessageListParams.none(), requestOptions) /** - * 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. */ fun cancel(messageId: String): MessageDetails = cancel(messageId, MessageCancelParams.none()) @@ -117,7 +121,10 @@ interface MessageService { fun cancel(messageId: String, requestOptions: RequestOptions): MessageDetails = cancel(messageId, MessageCancelParams.none(), requestOptions) - /** Get message content */ + /** + * Returns the rendered content Courier delivered for a message, broken out per channel, to + * confirm what the recipient received. + */ fun content(messageId: String): MessageContentResponse = content(messageId, MessageContentParams.none()) @@ -149,7 +156,10 @@ interface MessageService { fun content(messageId: String, requestOptions: RequestOptions): MessageContentResponse = content(messageId, MessageContentParams.none(), requestOptions) - /** 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. + */ fun history(messageId: String): MessageHistoryResponse = history(messageId, MessageHistoryParams.none()) @@ -182,10 +192,8 @@ interface MessageService { history(messageId, MessageHistoryParams.none(), requestOptions) /** - * 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. */ fun resend(messageId: String): MessageResendResponse = resend(messageId, MessageResendParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/NotificationService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/NotificationService.kt index 85f2a049..1b0f9c16 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/NotificationService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/NotificationService.kt @@ -109,7 +109,10 @@ interface NotificationService { fun retrieve(id: String, requestOptions: RequestOptions): NotificationTemplateResponse = retrieve(id, NotificationRetrieveParams.none(), requestOptions) - /** 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. + */ fun list(): NotificationListResponse = list(NotificationListParams.none()) /** @see list */ @@ -127,7 +130,10 @@ interface NotificationService { fun list(requestOptions: RequestOptions): NotificationListResponse = list(NotificationListParams.none(), requestOptions) - /** Archive a notification template. */ + /** + * Archives a notification template, preventing new sends from referencing it. The template + * stays retrievable for its version history. + */ fun archive(id: String) = archive(id, NotificationArchiveParams.none()) /** @see archive */ @@ -155,12 +161,8 @@ interface NotificationService { archive(id, NotificationArchiveParams.none(), requestOptions) /** - * 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. */ fun duplicate(id: String): NotificationTemplateResponse = duplicate(id, NotificationDuplicateParams.none()) @@ -192,7 +194,10 @@ interface NotificationService { fun duplicate(id: String, requestOptions: RequestOptions): NotificationTemplateResponse = duplicate(id, NotificationDuplicateParams.none(), requestOptions) - /** List versions of a notification template. */ + /** + * Returns a notification template's published versions, most recent first, for comparison or + * rollback. Paged. + */ fun listVersions(id: String): NotificationTemplateVersionListResponse = listVersions(id, NotificationListVersionsParams.none()) @@ -259,8 +264,8 @@ interface NotificationService { publish(id, NotificationPublishParams.none(), requestOptions) /** - * 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. */ fun putContent( id: String, @@ -286,8 +291,8 @@ interface NotificationService { ): NotificationContentMutationResponse /** - * 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. */ fun putElement( elementId: String, @@ -313,8 +318,8 @@ interface NotificationService { ): NotificationContentMutationResponse /** - * 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. */ fun putLocale( localeId: String, @@ -339,7 +344,10 @@ interface NotificationService { requestOptions: RequestOptions = RequestOptions.none(), ): NotificationContentMutationResponse - /** 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. + */ fun replace(id: String, params: NotificationReplaceParams): NotificationTemplateResponse = replace(id, params, RequestOptions.none()) @@ -361,9 +369,8 @@ interface NotificationService { ): NotificationTemplateResponse /** - * 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. */ fun retrieveContent(id: String): NotificationRetrieveContentResponse = retrieveContent(id, NotificationRetrieveContentParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/ProfileService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/ProfileService.kt index 5b31ed8f..7a683662 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/ProfileService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/ProfileService.kt @@ -35,8 +35,8 @@ interface ProfileService { fun lists(): ListService /** - * 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. */ fun create(userId: String, params: ProfileCreateParams): ProfileCreateResponse = create(userId, params, RequestOptions.none()) @@ -58,7 +58,10 @@ interface ProfileService { requestOptions: RequestOptions = RequestOptions.none(), ): ProfileCreateResponse - /** 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. + */ fun retrieve(userId: String): ProfileRetrieveResponse = retrieve(userId, ProfileRetrieveParams.none()) @@ -89,7 +92,10 @@ interface ProfileService { fun retrieve(userId: String, requestOptions: RequestOptions): ProfileRetrieveResponse = retrieve(userId, ProfileRetrieveParams.none(), requestOptions) - /** Update a profile */ + /** + * Applies a JSON Patch to a user profile, adding, removing, or replacing individual fields + * without sending the whole object. + */ fun update(userId: String, params: ProfileUpdateParams) = update(userId, params, RequestOptions.none()) @@ -106,7 +112,10 @@ interface ProfileService { /** @see update */ fun update(params: ProfileUpdateParams, requestOptions: RequestOptions = RequestOptions.none()) - /** 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. + */ fun delete(userId: String) = delete(userId, ProfileDeleteParams.none()) /** @see delete */ @@ -131,11 +140,8 @@ interface ProfileService { delete(userId, ProfileDeleteParams.none(), requestOptions) /** - * 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. */ fun replace(userId: String, params: ProfileReplaceParams): ProfileReplaceResponse = replace(userId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/ProviderService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/ProviderService.kt index 77bd49e4..a838573d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/ProviderService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/ProviderService.kt @@ -34,8 +34,8 @@ interface ProviderService { fun catalog(): CatalogService /** - * 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. */ fun create(params: ProviderCreateParams): Provider = create(params, RequestOptions.none()) @@ -45,7 +45,10 @@ interface ProviderService { requestOptions: RequestOptions = RequestOptions.none(), ): Provider - /** Fetch a single provider configuration by ID. */ + /** + * Returns one configured provider by id, including its channel, provider key, alias, title, and + * current settings. + */ fun retrieve(id: String): Provider = retrieve(id, ProviderRetrieveParams.none()) /** @see retrieve */ @@ -75,10 +78,8 @@ interface ProviderService { retrieve(id, ProviderRetrieveParams.none(), requestOptions) /** - * 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. */ fun update(id: String, params: ProviderUpdateParams): Provider = update(id, params, RequestOptions.none()) @@ -100,8 +101,8 @@ interface ProviderService { ): Provider /** - * 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. */ fun list(): ProviderListResponse = list(ProviderListParams.none()) @@ -120,8 +121,8 @@ interface ProviderService { list(ProviderListParams.none(), requestOptions) /** - * 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. */ fun delete(id: String) = delete(id, ProviderDeleteParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/RequestService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/RequestService.kt index 080feee9..67b2968f 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/RequestService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/RequestService.kt @@ -23,7 +23,10 @@ interface RequestService { */ fun withOptions(modifier: Consumer): RequestService - /** 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. + */ fun archive(requestId: String) = archive(requestId, RequestArchiveParams.none()) /** @see archive */ diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/RoutingStrategyService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/RoutingStrategyService.kt index 3890fbb6..b135a7e1 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/RoutingStrategyService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/RoutingStrategyService.kt @@ -64,8 +64,8 @@ interface RoutingStrategyService { ): RoutingStrategyGetResponse = create(routingStrategyCreateRequest, RequestOptions.none()) /** - * 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. */ fun retrieve(id: String): RoutingStrategyGetResponse = retrieve(id, RoutingStrategyRetrieveParams.none()) @@ -151,8 +151,8 @@ interface RoutingStrategyService { archive(id, RoutingStrategyArchiveParams.none(), requestOptions) /** - * 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. */ fun listNotifications(id: String): AssociatedNotificationListResponse = listNotifications(id, RoutingStrategyListNotificationsParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/SendService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/SendService.kt index 92f9b3ec..42d89177 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/SendService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/SendService.kt @@ -24,7 +24,10 @@ interface SendService { */ fun withOptions(modifier: Consumer): SendService - /** 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. + */ fun message(params: SendMessageParams): SendMessageResponse = message(params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/TenantService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/TenantService.kt index 2e5beb42..27e32c90 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/TenantService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/TenantService.kt @@ -37,7 +37,10 @@ interface TenantService { fun templates(): TemplateService - /** Get a Tenant */ + /** + * Returns one tenant with its name, parent tenant id, default preferences, properties, and the + * user profile applied to its members. + */ fun retrieve(tenantId: String): Tenant = retrieve(tenantId, TenantRetrieveParams.none()) /** @see retrieve */ @@ -66,7 +69,10 @@ interface TenantService { fun retrieve(tenantId: String, requestOptions: RequestOptions): Tenant = retrieve(tenantId, TenantRetrieveParams.none(), requestOptions) - /** Create or Replace a Tenant */ + /** + * Creates or replaces a tenant from a name, parent, brand, properties, and default preferences + * supplied in the request body. + */ fun update(tenantId: String, params: TenantUpdateParams): Tenant = update(tenantId, params, RequestOptions.none()) @@ -86,7 +92,10 @@ interface TenantService { requestOptions: RequestOptions = RequestOptions.none(), ): Tenant - /** Get a List of Tenants */ + /** + * Lists the workspace's tenants, each carrying a name, parent tenant, properties, and default + * preferences. Paged. + */ fun list(): TenantListResponse = list(TenantListParams.none()) /** @see list */ @@ -103,7 +112,10 @@ interface TenantService { fun list(requestOptions: RequestOptions): TenantListResponse = list(TenantListParams.none(), requestOptions) - /** Delete a Tenant */ + /** + * Deletes a tenant. Its members' workspace-level profiles and preferences live outside the + * tenant and are managed separately. + */ fun delete(tenantId: String) = delete(tenantId, TenantDeleteParams.none()) /** @see delete */ @@ -127,7 +139,10 @@ interface TenantService { fun delete(tenantId: String, requestOptions: RequestOptions) = delete(tenantId, TenantDeleteParams.none(), requestOptions) - /** 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. + */ fun listUsers(tenantId: String): TenantListUsersResponse = listUsers(tenantId, TenantListUsersParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/TranslationService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/TranslationService.kt index 84676828..5e01b911 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/TranslationService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/TranslationService.kt @@ -25,7 +25,10 @@ interface TranslationService { */ fun withOptions(modifier: Consumer): TranslationService - /** Get translations by locale */ + /** + * Returns the translation strings stored for one domain and locale, for use in localized + * notification content. + */ fun retrieve(locale: String, params: TranslationRetrieveParams): String = retrieve(locale, params, RequestOptions.none()) @@ -46,7 +49,10 @@ interface TranslationService { requestOptions: RequestOptions = RequestOptions.none(), ): String - /** Update a translation */ + /** + * Uploads the translation strings for one domain and locale. Courier uses them to render + * localized content for recipients in that locale. + */ fun update(locale: String, params: TranslationUpdateParams) = update(locale, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/WorkspacePreferenceService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/WorkspacePreferenceService.kt index 49915266..82419fe7 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/WorkspacePreferenceService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/WorkspacePreferenceService.kt @@ -38,8 +38,8 @@ interface WorkspacePreferenceService { fun topics(): TopicService /** - * 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. */ fun create(params: WorkspacePreferenceCreateParams): WorkspacePreferenceGetResponse = create(params, RequestOptions.none()) @@ -68,7 +68,10 @@ interface WorkspacePreferenceService { ): WorkspacePreferenceGetResponse = create(workspacePreferenceCreateRequest, RequestOptions.none()) - /** 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. + */ fun retrieve(sectionId: String): WorkspacePreferenceGetResponse = retrieve(sectionId, WorkspacePreferenceRetrieveParams.none()) @@ -104,8 +107,8 @@ interface WorkspacePreferenceService { retrieve(sectionId, WorkspacePreferenceRetrieveParams.none(), requestOptions) /** - * 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. */ fun list(): WorkspacePreferenceListResponse = list(WorkspacePreferenceListParams.none()) @@ -157,9 +160,8 @@ interface WorkspacePreferenceService { archive(sectionId, WorkspacePreferenceArchiveParams.none(), requestOptions) /** - * 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. */ fun publish(): PublishPreferencesResponse = publish(WorkspacePreferencePublishParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/automations/InvokeService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/automations/InvokeService.kt index 88196cae..41f25629 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/automations/InvokeService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/automations/InvokeService.kt @@ -26,9 +26,8 @@ interface InvokeService { fun withOptions(modifier: Consumer): InvokeService /** - * 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. */ fun invokeAdHoc(params: InvokeInvokeAdHocParams): AutomationInvokeResponse = invokeAdHoc(params, RequestOptions.none()) @@ -39,7 +38,10 @@ interface InvokeService { requestOptions: RequestOptions = RequestOptions.none(), ): AutomationInvokeResponse - /** 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. + */ fun invokeByTemplate( templateId: String, params: InvokeInvokeByTemplateParams, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/digests/ScheduleService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/digests/ScheduleService.kt index 5774cb32..60255f92 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/digests/ScheduleService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/digests/ScheduleService.kt @@ -27,9 +27,8 @@ interface ScheduleService { fun withOptions(modifier: Consumer): ScheduleService /** - * 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. */ fun listInstances(scheduleId: String): DigestInstanceListResponse = listInstances(scheduleId, ScheduleListInstancesParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/journeys/TemplateService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/journeys/TemplateService.kt index e943ff65..af9507b1 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/journeys/TemplateService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/journeys/TemplateService.kt @@ -64,8 +64,8 @@ interface TemplateService { ): JourneyTemplateGetResponse /** - * 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. */ fun retrieve( notificationId: String, @@ -125,7 +125,10 @@ interface TemplateService { fun list(templateId: String, requestOptions: RequestOptions): JourneyTemplateListResponse = list(templateId, TemplateListParams.none(), requestOptions) - /** 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. + */ fun archive(notificationId: String, params: TemplateArchiveParams) = archive(notificationId, params, RequestOptions.none()) @@ -146,8 +149,8 @@ interface TemplateService { ) /** - * 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. */ fun listVersions( notificationId: String, @@ -174,8 +177,8 @@ interface TemplateService { ): NotificationTemplateVersionListResponse /** - * 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. */ fun publish(notificationId: String, params: TemplatePublishParams) = publish(notificationId, params, RequestOptions.none()) @@ -251,7 +254,10 @@ interface TemplateService { requestOptions: RequestOptions = RequestOptions.none(), ): NotificationContentMutationResponse - /** 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. + */ fun replace(notificationId: String, params: TemplateReplaceParams): JourneyTemplateGetResponse = replace(notificationId, params, RequestOptions.none()) @@ -274,10 +280,8 @@ interface TemplateService { ): JourneyTemplateGetResponse /** - * 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. */ fun retrieveContent( notificationId: String, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/lists/SubscriptionService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/lists/SubscriptionService.kt index 0cbaec9f..a34fb95d 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/lists/SubscriptionService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/lists/SubscriptionService.kt @@ -29,7 +29,10 @@ interface SubscriptionService { */ fun withOptions(modifier: Consumer): SubscriptionService - /** Get the list's subscriptions. */ + /** + * Returns the users subscribed to a list with paging, each with the preferences recorded for + * that subscription. + */ fun list(listId: String): SubscriptionListResponse = list(listId, SubscriptionListParams.none()) /** @see list */ @@ -103,8 +106,8 @@ interface SubscriptionService { ) /** - * 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. */ fun subscribeUser(userId: String, params: SubscriptionSubscribeUserParams) = subscribeUser(userId, params, RequestOptions.none()) @@ -126,7 +129,10 @@ interface SubscriptionService { requestOptions: RequestOptions = RequestOptions.none(), ) - /** 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. + */ fun unsubscribeUser(userId: String, params: SubscriptionUnsubscribeUserParams) = unsubscribeUser(userId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/notifications/CheckService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/notifications/CheckService.kt index 279716be..515bc8fc 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/notifications/CheckService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/notifications/CheckService.kt @@ -28,7 +28,10 @@ interface CheckService { */ fun withOptions(modifier: Consumer): CheckService - /** 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. + */ fun update(submissionId: String, params: CheckUpdateParams): CheckUpdateResponse = update(submissionId, params, RequestOptions.none()) @@ -50,7 +53,10 @@ interface CheckService { requestOptions: RequestOptions = RequestOptions.none(), ): CheckUpdateResponse - /** Retrieve the submission checks for a notification template. */ + /** + * Returns the approval checks recorded for a template submission, each with its pass or fail + * result. + */ fun list(submissionId: String, params: CheckListParams): CheckListResponse = list(submissionId, params, RequestOptions.none()) @@ -71,7 +77,10 @@ interface CheckService { requestOptions: RequestOptions = RequestOptions.none(), ): CheckListResponse - /** 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. + */ fun delete(submissionId: String, params: CheckDeleteParams) = delete(submissionId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/profiles/ListService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/profiles/ListService.kt index 895f377a..3800f78c 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/profiles/ListService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/profiles/ListService.kt @@ -28,7 +28,10 @@ interface ListService { */ fun withOptions(modifier: Consumer): ListService - /** 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. + */ fun retrieve(userId: String): ListRetrieveResponse = retrieve(userId, ListRetrieveParams.none()) /** @see retrieve */ @@ -58,7 +61,10 @@ interface ListService { fun retrieve(userId: String, requestOptions: RequestOptions): ListRetrieveResponse = retrieve(userId, ListRetrieveParams.none(), requestOptions) - /** 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. + */ fun delete(userId: String): ListDeleteResponse = delete(userId, ListDeleteParams.none()) /** @see delete */ @@ -88,8 +94,8 @@ interface ListService { delete(userId, ListDeleteParams.none(), requestOptions) /** - * 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. */ fun subscribe(userId: String, params: ListSubscribeParams): ListSubscribeResponse = subscribe(userId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/providers/CatalogService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/providers/CatalogService.kt index 79a3deef..49d2cee3 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/providers/CatalogService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/providers/CatalogService.kt @@ -25,9 +25,8 @@ interface CatalogService { fun withOptions(modifier: Consumer): CatalogService /** - * 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. */ fun list(): CatalogListResponse = list(CatalogListParams.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/TemplateService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/TemplateService.kt index e5174142..fe946927 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/TemplateService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/TemplateService.kt @@ -35,7 +35,10 @@ interface TemplateService { fun versions(): VersionService - /** Get a Template in Tenant */ + /** + * Returns a tenant's notification template with its content, version, and created, updated, and + * published timestamps. + */ fun retrieve( templateId: String, params: TemplateRetrieveParams, @@ -59,7 +62,10 @@ interface TemplateService { requestOptions: RequestOptions = RequestOptions.none(), ): BaseTemplateTenantAssociation - /** List Templates in Tenant */ + /** + * Lists a tenant's notification templates, each carrying its version and published timestamp. + * Paged. + */ fun list(tenantId: String): TemplateListResponse = list(tenantId, TemplateListParams.none()) /** @see list */ @@ -89,12 +95,8 @@ interface TemplateService { list(tenantId, TemplateListParams.none(), requestOptions) /** - * 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. */ fun delete(templateId: String, params: TemplateDeleteParams) = delete(templateId, params, RequestOptions.none()) @@ -113,10 +115,8 @@ interface TemplateService { fun delete(params: TemplateDeleteParams, requestOptions: RequestOptions = RequestOptions.none()) /** - * 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. */ fun publish( templateId: String, @@ -142,12 +142,8 @@ interface TemplateService { ): PostTenantTemplatePublishResponse /** - * 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. */ fun replace(templateId: String, params: TemplateReplaceParams): PutTenantTemplateResponse = replace(templateId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/preferences/ItemService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/preferences/ItemService.kt index 4691b482..363e8311 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/preferences/ItemService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/preferences/ItemService.kt @@ -24,7 +24,10 @@ interface ItemService { */ fun withOptions(modifier: Consumer): ItemService - /** 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. + */ fun update(topicId: String, params: ItemUpdateParams) = update(topicId, params, RequestOptions.none()) @@ -41,7 +44,10 @@ interface ItemService { /** @see update */ fun update(params: ItemUpdateParams, requestOptions: RequestOptions = RequestOptions.none()) - /** Remove Default Preferences For Topic */ + /** + * Removes a tenant's default preference for one subscription topic, addressed by tenant id and + * topic id. + */ fun delete(topicId: String, params: ItemDeleteParams) = delete(topicId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/templates/VersionService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/templates/VersionService.kt index bd8e9493..a8354bf2 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/templates/VersionService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/tenants/templates/VersionService.kt @@ -25,12 +25,8 @@ interface VersionService { fun withOptions(modifier: Consumer): VersionService /** - * 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. */ fun retrieve(version: String, params: VersionRetrieveParams): BaseTemplateTenantAssociation = retrieve(version, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/PreferenceService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/PreferenceService.kt index 79034d92..f9665485 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/PreferenceService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/PreferenceService.kt @@ -34,7 +34,10 @@ interface PreferenceService { */ fun withOptions(modifier: Consumer): PreferenceService - /** Fetch all user preferences. */ + /** + * Returns a user's preference overrides with paging, one entry per subscription topic they have + * set a choice for. + */ fun retrieve(userId: String): PreferenceRetrieveResponse = retrieve(userId, PreferenceRetrieveParams.none()) @@ -67,21 +70,8 @@ interface PreferenceService { retrieve(userId, PreferenceRetrieveParams.none(), requestOptions) /** - * 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. */ fun bulkReplace( userId: String, @@ -107,20 +97,8 @@ interface PreferenceService { ): PreferenceBulkReplaceResponse /** - * 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. */ fun bulkUpdate( userId: String, @@ -146,9 +124,8 @@ interface PreferenceService { ): PreferenceBulkUpdateResponse /** - * 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. */ fun deleteTopic(topicId: String, params: PreferenceDeleteTopicParams) = deleteTopic(topicId, params, RequestOptions.none()) @@ -170,7 +147,10 @@ interface PreferenceService { requestOptions: RequestOptions = RequestOptions.none(), ) - /** 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. + */ fun retrieveTopic( topicId: String, params: PreferenceRetrieveTopicParams, @@ -194,7 +174,10 @@ interface PreferenceService { requestOptions: RequestOptions = RequestOptions.none(), ): PreferenceRetrieveTopicResponse - /** 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. + */ fun updateOrCreateTopic( topicId: String, params: PreferenceUpdateOrCreateTopicParams, diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/TenantService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/TenantService.kt index 36782f1e..9c8cc554 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/TenantService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/TenantService.kt @@ -29,7 +29,10 @@ interface TenantService { */ fun withOptions(modifier: Consumer): TenantService - /** 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. + */ fun list(userId: String): TenantListResponse = list(userId, TenantListParams.none()) /** @see list */ @@ -59,9 +62,8 @@ interface TenantService { list(userId, TenantListParams.none(), requestOptions) /** - * 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. */ fun addMultiple(userId: String, params: TenantAddMultipleParams) = addMultiple(userId, params, RequestOptions.none()) @@ -83,10 +85,8 @@ interface TenantService { ) /** - * 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. */ fun addSingle(tenantId: String, params: TenantAddSingleParams) = addSingle(tenantId, params, RequestOptions.none()) @@ -107,7 +107,10 @@ interface TenantService { requestOptions: RequestOptions = RequestOptions.none(), ) - /** 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. + */ fun removeAll(userId: String) = removeAll(userId, TenantRemoveAllParams.none()) /** @see removeAll */ @@ -134,7 +137,10 @@ interface TenantService { fun removeAll(userId: String, requestOptions: RequestOptions) = removeAll(userId, TenantRemoveAllParams.none(), requestOptions) - /** 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. + */ fun removeSingle(tenantId: String, params: TenantRemoveSingleParams) = removeSingle(tenantId, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/TokenService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/TokenService.kt index 22130973..a8627f79 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/TokenService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/users/TokenService.kt @@ -31,7 +31,10 @@ interface TokenService { */ fun withOptions(modifier: Consumer): TokenService - /** 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. + */ fun retrieve(token: String, params: TokenRetrieveParams): TokenRetrieveResponse = retrieve(token, params, RequestOptions.none()) @@ -52,7 +55,10 @@ interface TokenService { requestOptions: RequestOptions = RequestOptions.none(), ): TokenRetrieveResponse - /** 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. + */ fun update(token: String, params: TokenUpdateParams) = update(token, params, RequestOptions.none()) @@ -69,7 +75,10 @@ interface TokenService { /** @see update */ fun update(params: TokenUpdateParams, requestOptions: RequestOptions = RequestOptions.none()) - /** 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. + */ fun list(userId: String): TokenListResponse = list(userId, TokenListParams.none()) /** @see list */ @@ -96,7 +105,10 @@ interface TokenService { fun list(userId: String, requestOptions: RequestOptions): TokenListResponse = list(userId, TokenListParams.none(), requestOptions) - /** Delete User Token */ + /** + * Deletes one device token for a user, addressed by the token value, so push sends no longer + * target that device. + */ fun delete(token: String, params: TokenDeleteParams) = delete(token, params, RequestOptions.none()) @@ -113,7 +125,10 @@ interface TokenService { /** @see delete */ fun delete(params: TokenDeleteParams, requestOptions: RequestOptions = RequestOptions.none()) - /** 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. + */ fun addMultiple(userId: String) = addMultiple(userId, TokenAddMultipleParams.none()) /** @see addMultiple */ @@ -142,7 +157,10 @@ interface TokenService { fun addMultiple(userId: String, requestOptions: RequestOptions) = addMultiple(userId, TokenAddMultipleParams.none(), requestOptions) - /** 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. + */ fun addSingle(token: String, params: TokenAddSingleParams) = addSingle(token, params, RequestOptions.none()) diff --git a/courier-java-core/src/main/kotlin/com/courier/services/blocking/workspacepreferences/TopicService.kt b/courier-java-core/src/main/kotlin/com/courier/services/blocking/workspacepreferences/TopicService.kt index b90d7c55..4e0a5456 100644 --- a/courier-java-core/src/main/kotlin/com/courier/services/blocking/workspacepreferences/TopicService.kt +++ b/courier-java-core/src/main/kotlin/com/courier/services/blocking/workspacepreferences/TopicService.kt @@ -31,8 +31,8 @@ interface TopicService { fun withOptions(modifier: Consumer): TopicService /** - * 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. */ fun create(sectionId: String, params: TopicCreateParams): WorkspacePreferenceTopicGetResponse = create(sectionId, params, RequestOptions.none()) @@ -56,9 +56,8 @@ interface TopicService { ): WorkspacePreferenceTopicGetResponse /** - * 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. */ fun retrieve( topicId: String, @@ -83,7 +82,10 @@ interface TopicService { requestOptions: RequestOptions = RequestOptions.none(), ): WorkspacePreferenceTopicGetResponse - /** List the topics in a workspace preference. */ + /** + * Returns the subscription topics inside a workspace preference, each with its default status + * and routing options. + */ fun list(sectionId: String): WorkspacePreferenceTopicListResponse = list(sectionId, TopicListParams.none()) @@ -118,7 +120,10 @@ interface TopicService { ): WorkspacePreferenceTopicListResponse = list(sectionId, TopicListParams.none(), requestOptions) - /** 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. + */ fun archive(topicId: String, params: TopicArchiveParams) = archive(topicId, params, RequestOptions.none())