@whooshbang/contracts 2.4.0 → 2.6.0

package/dist/generated/whooshbang-v1.d.ts

@@ -5,7 +5,7 @@
 /**
  * Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.
  */
-export type WhooshBangV1ContractDocument = OrganizationProjection | Teammate | TeammateCollection | TeammateAccessRequest | InviteTeammateRequest | CloseOrganizationRequest | OrganizationClosureResult | CreateProjectRequest | Project | UpdateProjectRequest | PrivacyMode | ProjectCollection | RecipientCopyOverrideCollection | UpdateRecipientCopyOverrideRequest | CreateApiCredentialRequest | RotateApiCredentialRequest | ApiCredential | ApiCredentialCollection | ApiCredentialSecretReveal | ApiCredentialRotation | CreateOrganizationCredentialRequest | RotateOrganizationCredentialRequest | OrganizationCredential | OrganizationCredentialCollection | OrganizationCredentialSecretReveal | OrganizationCredentialRotation | CreateCustomerEndpointRequest | CustomerEndpoint | CustomerEndpointCollection | CustomerEndpointMutationResult | CustomerEndpointAttemptCollection | CustomerEndpointVerificationChallenge | CreateSubscriptionLinkRequest | SubscriptionLink | CreateMessageRequest | Message | Problem | IdempotencyKey | ProviderCapabilitiesCollection | ProviderInstallationCollection | EmailDomainCollection | CreateEmailDomainRequest | CreateEmailBindingImportRequest | EmailBindingImportJob | ConnectionProviderCollection | ChannelConnection | ChannelConnectionCollection | CreateChannelConnectionRequest | UpdateChannelConnectionRequest | RotateChannelConnectionCredentialRequest | NotifierConnectionCollection | AttachNotifierConnectionRequest | ConnectionTest | ConnectionTestCollection | CreateConnectionTestRequest | CustomerApplicationManifest | ProjectRecipientExperience | UpdateProjectRecipientExperienceRequest | RecipientBrandLogoUpload | NotificationImageAsset | EnvironmentRecipientExperience | UpdateEnvironmentRecipientExperienceRequest | SubscriberChannelSettings | AcknowledgeEmailRemediationRequest | CreateRecipientSessionRequest | CreateRecipientSessionResponse | RecipientSession | CreateProviderHandoffRequest | ProviderHandoff | RecipientHandoffCompletion | SetPreferredBindingRequest | PreferredBinding | CreateSubscriberRequest | UpdateSubscriberRequest | SubscriberCollection | Subscriber | SubscriberDataExport | CreateSubscriberGroupRequest | SubscriberGroup | SubscriberGroupCollection | SubscriberGroupMembership | SubscriberGroupMembershipCollection | CreateGroupBroadcastRequest | GroupBroadcast | AssertEmailConsentRequest | BindingSummary | UsageReport | MessageListEntry | MessageListPage | MessageDeliveryTimelineEntry | RetainedMessageContent | MessageDeliveryHistory | InteractionTimelineEntry | InteractionTimeline | UpdateEmailSenderRequest | CustomerEventDeliveryAttempt | CustomerEventDeliveryHistory | DeliveryHolds | MachineClientOperations | MachineClientOperationsList | RecipientCopyCatalogue | MessageNotificationImage | BillingAccount | BillingCard | CardSetup | CreateCreditPurchaseRequest | CreditPurchase | BillingInvoice | BillingInvoiceCollection | UpdateBillingReceiptEmailRequest | BillingEntitlements | SubscriptionSelection1 | ProjectAttribution | UpdateProjectAttributionRequest | BillingProjectSlots | AssignBillingProjectSlotsRequest | UpdateAutoTopUpSettingsRequest | AutoTopUpSettings | SubscriptionChange | ConfirmSubscriptionChangeRequest | Operator | OperatorCollection | OperatorResolution | CreateOperatorMessageRequest | OperatorMessageResult | OperatorBroadcastRecipient | OperatorBroadcast | OperatorPreferences | OperatorConnectRequest | WhoAmI;
+export type WhooshBangV1ContractDocument = OrganizationProjection | Teammate | TeammateCollection | TeammateAccessRequest | InviteTeammateRequest | CloseOrganizationRequest | OrganizationClosureResult | CreateProjectRequest | Project | UpdateProjectRequest | PrivacyMode | ProjectCollection | RecipientCopyOverrideCollection | UpdateRecipientCopyOverrideRequest | CreateApiCredentialRequest | RotateApiCredentialRequest | ApiCredential | ApiCredentialCollection | ApiCredentialSecretReveal | ApiCredentialRotation | CreateOrganizationCredentialRequest | RotateOrganizationCredentialRequest | OrganizationCredential | OrganizationCredentialCollection | OrganizationCredentialSecretReveal | OrganizationCredentialRotation | CreateCustomerEndpointRequest | CustomerEndpoint | CustomerEndpointCollection | CustomerEndpointMutationResult | CustomerEndpointAttemptCollection | CustomerEndpointVerificationChallenge | CreateSubscriptionLinkRequest | SubscriptionLink | CreateMessageRequest | Message | Problem | IdempotencyKey | ProviderCapabilitiesCollection | ProviderInstallationCollection | EmailDomainCollection | CreateEmailDomainRequest | CreateEmailBindingImportRequest | EmailBindingImportJob | ConnectionProviderCollection | ChannelConnection | ChannelConnectionCollection | CreateChannelConnectionRequest | UpdateChannelConnectionRequest | RotateChannelConnectionCredentialRequest | NotifierConnectionCollection | AttachNotifierConnectionRequest | ConnectionTest | ConnectionTestCollection | CreateConnectionTestRequest | CustomerApplicationManifest | ProjectRecipientExperience | UpdateProjectRecipientExperienceRequest | RecipientBrandLogoUpload | NotificationImageAsset | EnvironmentRecipientExperience | UpdateEnvironmentRecipientExperienceRequest | SubscriberChannelSettings | AcknowledgeEmailRemediationRequest | CreateRecipientSessionRequest | CreateRecipientSessionResponse | RecipientSession | CreateProviderHandoffRequest | ProviderHandoff | RecipientHandoffCompletion | SetPreferredBindingRequest | PreferredBinding | CreateSubscriberRequest | UpdateSubscriberRequest | SubscriberCollection | Subscriber | SubscriberDataExport | CreateSubscriberGroupRequest | SubscriberGroup | SubscriberGroupCollection | SubscriberGroupMembership | SubscriberGroupMembershipCollection | CreateGroupBroadcastRequest | GroupBroadcast | AssertEmailConsentRequest | BindingSummary | UsageReport | MessageListEntry | MessageListPage | MessageDeliveryTimelineEntry | RetainedMessageContent | MessageDeliveryHistory | InteractionTimelineEntry | InteractionTimeline | UpdateEmailSenderRequest | CustomerEventDeliveryAttempt | CustomerEventDeliveryHistory | DeliveryHolds | MachineClientOperations | MachineClientOperationsList | RecipientCopyCatalogue | MessageNotificationImage | BillingAccount | BillingCard | CardSetup | CreateCreditPurchaseRequest | CreditPurchase | BillingInvoice | BillingInvoiceCollection | UpdateBillingReceiptEmailRequest | BillingEntitlements | SubscriptionSelection1 | ProjectAttribution | UpdateProjectAttributionRequest | BillingProjectSlots | AssignBillingProjectSlotsRequest | UpdateAutoTopUpSettingsRequest | AutoTopUpSettings | SubscriptionChange | ConfirmSubscriptionChangeRequest | Operator | OperatorCollection | OperatorResolution | CreateOperatorMessageRequest | OperatorMessageResult | OperatorBroadcastRecipient | OperatorBroadcast | OperatorPreferences | OperatorConnectRequest | WhoAmI | BillingPromotions | BillingPromotion | RedeemBillingPromotionRequest | CanonicalCreateMessageRequest | CanonicalCreateGroupBroadcastRequest | CanonicalCreateOperatorMessageRequest;
 /**
  * An opaque identifier. Its shape, ordering, and embedded content are not public promises.
  */
@@ -328,7 +328,7 @@ export type CreateSubscriptionLinkRequest = {
      * @minItems 1
      * @maxItems 1
      */
-    channels: [Channel];
+    channels?: [Channel];
     /**
      * An opaque identifier. Its shape, ordering, and embedded content are not public promises.
      */
@@ -529,8 +529,17 @@ export type ProblemCode = "authentication_required" | "credential_invalid" | "sc
  */
 export type CreateMessageRequest = {
     [k: string]: unknown;
-} & {
-    to: MessageTarget;
+} & ({
+    content: MessageContentInput;
+    [k: string]: unknown;
+} | {
+    /**
+     * Options infer select; otherwise confirm. Typed replies require type: input. Omit expiry for 24 hours.
+     */
+    interaction: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
+    [k: string]: unknown;
+}) & {
+    to: MessageTarget | OpaqueIdentifier;
     notifier_id?: OpaqueIdentifier;
     /**
      * Optional routing override. Simulator delivery and the reserved test: subscriber prefix are test-environment-only; live requests are refused with 400 request_invalid. Omit for connection delivery, or for the reserved test-environment simulator default.
@@ -540,7 +549,7 @@ export type CreateMessageRequest = {
      * Optional channel connection to send through, from the environment's connections. The subscriber must be connected through it; the service never substitutes another connection or provider. A connection the subscriber has not connected through is refused as `subscriber_not_connected` when they are connected through another, and as an unchosen send would be (`subscriber_unbound` or `preferred_binding_unavailable`) when no connected channel can take the message. Omitted, the service chooses: the subscriber's preferred channel when they set one, otherwise the default connection when they are connected there, otherwise the connection they connected through most recently. The accepted message's `binding.connection_id` records the connection used. Implies `delivery_target: connection`.
      */
     connection_id?: OpaqueIdentifier;
-    content: MessageContent;
+    content?: MessageContentInput;
     /**
      * An RFC 3339 timestamp with a UTC offset. The server is authoritative.
      */
@@ -548,7 +557,7 @@ export type CreateMessageRequest = {
     correlation_id?: string;
     metadata?: Metadata;
     /**
-     * Send-time interaction. Choose expires_in_seconds or expires_at; omit both for 24 hours from server acceptance. Idempotent replays retain the original resolved deadline.
+     * Options infer select; otherwise confirm. Typed replies require type: input. Omit expiry for 24 hours.
      */
     interaction?: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
     /**
@@ -556,7 +565,7 @@ export type CreateMessageRequest = {
      */
     purpose?: "service" | "marketing";
 };
-export type MessageContent = TextContent | DocumentContent;
+export type MessageContentInput = string | TextContentInput | DocumentContentInput;
 /**
  * An opaque immutable version identity for one environment-owned notification image.
  */
@@ -1014,7 +1023,7 @@ export type Problem1 = {
     [k: string]: unknown;
 } | {
     type?: "https://whooshbang.flowxo.com/problems/idempotency_key_required";
-    title?: "Idempotency key required";
+    title?: "Invalid idempotency key" | "Idempotency key required";
     status?: 400;
     code?: "idempotency_key_required";
     retryable?: false;
@@ -2306,10 +2315,11 @@ export type CreateConnectionTestRequest = {
     text?: string;
     content?: MessageContent;
     /**
-     * Send-time interaction. Choose expires_in_seconds or expires_at; omit both for 24 hours from server acceptance. Idempotent replays retain the original resolved deadline.
+     * Options infer select; otherwise confirm. Typed replies require type: input. Omit expiry for 24 hours.
      */
     interaction?: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
 };
+export type MessageContent = TextContent | DocumentContent;
 /**
  * An opaque identifier for one normalized project-owned recipient brand logo.
  */
@@ -2379,6 +2389,10 @@ export type RecipientHandoffCompletion = {
  * A named IANA time-zone identifier. Numeric offsets, abbreviations and display labels are invalid; recognized aliases normalize to the runtime's canonical identifier before persistence. Providers may leave it absent.
  */
 export type TimeZone = string;
+/**
+ * A stable, case-sensitive subscriber group key. Existing keys are preserved exactly.
+ */
+export type GroupKey = string;
 /**
  * An environment-scoped static group. Deletion is terminal and reserves the immutable key for history.
  */
@@ -2392,7 +2406,7 @@ export type SubscriberGroup = {
     id: OpaqueIdentifier;
     project_id: OpaqueIdentifier;
     environment: Environment;
-    key: DeveloperKey;
+    key: GroupKey;
     display_name: string;
     description?: string;
     status: "active" | "archived";
@@ -2410,7 +2424,7 @@ export type SubscriberGroupMembership = {
     [k: string]: unknown;
 } & {
     group_id: OpaqueIdentifier;
-    group_key: DeveloperKey;
+    group_key: GroupKey;
     subscriber_id: OpaqueIdentifier;
     /**
      * What to call the subscriber, resolved as on the subscriber's `name`: your display name, otherwise the channel's own name where the privacy setting keeps it. Absent when there is neither.
@@ -2424,14 +2438,47 @@ export type SubscriberGroupMembership = {
     updated_at: Timestamp;
     diagnostic_id: DiagnosticId;
 };
+/**
+ * Creates one group broadcast using the existing ordinary message envelope. The group target comes only from the path.
+ */
+export type CreateGroupBroadcastRequest = ({
+    content: MessageContentInput;
+    [k: string]: unknown;
+} | {
+    /**
+     * Options infer select; otherwise confirm. Typed replies require type: input. Omit expiry for 24 hours.
+     */
+    interaction: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
+    [k: string]: unknown;
+}) & {
+    notifier_id?: OpaqueIdentifier;
+    content?: MessageContentInput;
+    /**
+     * An RFC 3339 timestamp with a UTC offset. The server is authoritative.
+     */
+    expires_at?: string;
+    correlation_id?: string;
+    metadata?: Metadata;
+    /**
+     * Options infer select; otherwise confirm. Typed replies require type: input. Omit expiry for 24 hours.
+     */
+    interaction?: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
+    /**
+     * Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch.
+     */
+    purpose?: "service" | "marketing";
+};
 /**
  * Assert prior consent or enroll an application-verified user for service email on an exact customer-owned connection. Revocation and sending restrictions always win.
  */
 export type AssertEmailConsentRequest = {
     subscriber_id: OpaqueIdentifier;
-    notifier_id: OpaqueIdentifier;
-    connection_id: OpaqueIdentifier;
-    domain_id: OpaqueIdentifier;
+    /**
+     * An opaque identifier. Its shape, ordering, and embedded content are not public promises.
+     */
+    notifier_id?: string;
+    connection_id?: OpaqueIdentifier;
+    domain_id?: OpaqueIdentifier;
     address: EmailAddress;
     consented: true;
     /**
@@ -2444,9 +2491,12 @@ export type AssertEmailConsentRequest = {
     source?: string;
 } | {
     subscriber_id: OpaqueIdentifier;
-    notifier_id: OpaqueIdentifier;
-    connection_id: OpaqueIdentifier;
-    domain_id: OpaqueIdentifier;
+    /**
+     * An opaque identifier. Its shape, ordering, and embedded content are not public promises.
+     */
+    notifier_id?: string;
+    connection_id?: OpaqueIdentifier;
+    domain_id?: OpaqueIdentifier;
     address: EmailAddress;
     /**
      * A bounded customer description of the service relationship. The authenticated asserting actor is recorded by the service, never accepted from this object.
@@ -2512,6 +2562,68 @@ export type MachineScopeSummary = [
     ("machine-messages:write" | "machine-messages:read" | "machine-events:read" | "machine-events:ack"),
     ("machine-messages:write" | "machine-messages:read" | "machine-events:read" | "machine-events:ack")
 ];
+/**
+ * Send to a teammate by exact name or operator ID, or use me. Omitted recipient means the verified authenticated human only. Shared and service credentials must name a recipient. Preferred channel, service-email billing and marketing restrictions still apply.
+ */
+export type CreateOperatorMessageRequest = ({
+    content: MessageContentInput;
+    [k: string]: unknown;
+} | {
+    /**
+     * Options infer select; otherwise confirm. Typed replies require type: input. Omit expiry for 24 hours.
+     */
+    interaction: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
+    [k: string]: unknown;
+}) & {
+    recipient?: string;
+    content?: MessageContentInput;
+    /**
+     * An RFC 3339 timestamp with a UTC offset. The server is authoritative.
+     */
+    expires_at?: string;
+    correlation_id?: string;
+    metadata?: Metadata;
+    /**
+     * Options infer select; otherwise confirm. Typed replies require type: input. Omit expiry for 24 hours.
+     */
+    interaction?: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
+    /**
+     * Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch.
+     */
+    purpose?: "service" | "marketing";
+};
+/**
+ * Creates one logical message for one subscriber and one resolved channel binding.
+ */
+export type CanonicalCreateMessageRequest = {
+    [k: string]: unknown;
+} & {
+    to: MessageTarget;
+    notifier_id?: OpaqueIdentifier;
+    /**
+     * The effective provider boundary selected for a message. Connection delivery uses the exact authorized environment connection; simulator delivery never calls a provider.
+     */
+    delivery_target?: "connection" | "simulator";
+    /**
+     * Optional channel connection to send through, from the environment's connections. The subscriber must be connected through it; the service never substitutes another connection or provider. A connection the subscriber has not connected through is refused as `subscriber_not_connected` when they are connected through another, and as an unchosen send would be (`subscriber_unbound` or `preferred_binding_unavailable`) when no connected channel can take the message. Omitted, the service chooses: the subscriber's preferred channel when they set one, otherwise the default connection when they are connected there, otherwise the connection they connected through most recently. The accepted message's `binding.connection_id` records the connection used. Implies `delivery_target: connection`.
+     */
+    connection_id?: OpaqueIdentifier;
+    content: MessageContent;
+    /**
+     * An RFC 3339 timestamp with a UTC offset. The server is authoritative.
+     */
+    expires_at?: string;
+    correlation_id?: string;
+    metadata?: Metadata;
+    /**
+     * Send-time interaction. Choose expires_in_seconds or expires_at; omit both for 24 hours from server acceptance. Idempotent replays retain the original resolved deadline.
+     */
+    interaction?: CanonicalConfirmInteractionSendRequest | CanonicalSelectInteractionSendRequest | CanonicalInputInteractionSendRequest;
+    /**
+     * Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch.
+     */
+    purpose?: "service" | "marketing";
+};
 /**
  * The current Clerk organization projected as a WhooshBang tenant. Clerk organization and user identifiers are not public fields.
  */
@@ -3108,7 +3220,7 @@ export interface CreateCustomerEndpointRequest {
      * @minItems 1
      * @maxItems 11
      */
-    event_types: [CustomerEventType] | [CustomerEventType, CustomerEventType] | [CustomerEventType, CustomerEventType, CustomerEventType] | [
+    event_types?: [CustomerEventType] | [CustomerEventType, CustomerEventType] | [CustomerEventType, CustomerEventType, CustomerEventType] | [
         CustomerEventType,
         CustomerEventType,
         CustomerEventType,
@@ -3358,11 +3470,8 @@ export interface EmailVerificationSummary {
     masked_address: string;
     expires_at: Timestamp;
 }
-export interface MessageTarget {
-    subscriber_id: OpaqueIdentifier;
-}
-export interface TextContent {
-    type: "text";
+export interface TextContentInput {
+    type?: "text";
     /**
      * Text format. Omitted means plain text. Markdown supports headings, paragraphs, emphasis, strong emphasis, code, lists, quotes and safe HTTP(S) links; raw HTML and remote images are never executed or fetched.
      */
@@ -3463,7 +3572,7 @@ export interface TextContent {
         StructuredTextSection,
         StructuredTextSection
     ];
-    image?: NotificationImage;
+    image?: NotificationImageInput;
 }
 export interface StructuredTextSection {
     /**
@@ -3478,9 +3587,9 @@ export interface StructuredTextSection {
 /**
  * One optional provider-neutral illustrative image. The notification content remains complete without the pixels.
  */
-export interface NotificationImage {
+export interface NotificationImageInput {
     asset_id: NotificationImageAssetId;
-    purpose: "illustration";
+    purpose?: "illustration";
     /**
      * Optional accessible description preserved by every adapter. Omit it for a decorative illustration; notification text must remain complete without the image.
      */
@@ -3489,8 +3598,8 @@ export interface NotificationImage {
 /**
  * An authoritative ordered portable notification document that every delivery adapter renders faithfully.
  */
-export interface DocumentContent {
-    type: "document";
+export interface DocumentContentInput {
+    type?: "document";
     /**
      * An optional semantic document title. The adapter chooses its native presentation.
      */
@@ -3502,7 +3611,7 @@ export interface DocumentContent {
      * @maxItems 24
      */
     blocks: [DocumentBlock, ...DocumentBlock[]];
-    image?: NotificationImage;
+    image?: NotificationImageInput;
 }
 /**
  * One prose section in an ordered portable document.
@@ -3828,14 +3937,8 @@ export interface DocumentDetailsBlock {
      */
     text: string;
 }
-/**
- * Bounded customer correlation data. Do not include secrets or personal data.
- */
-export interface Metadata {
-    [k: string]: MetadataValue;
-}
 export interface ConfirmInteractionSendRequest {
-    type: "confirm";
+    type?: "confirm";
     prompt: string;
     confirm_label?: string;
     deny_label?: string;
@@ -3853,30 +3956,117 @@ export interface ConfirmInteractionSendRequest {
     expires_in_seconds?: number;
 }
 export interface SelectInteractionSendRequest {
-    type: "select";
+    type?: "select";
     prompt: string;
     /**
      * @minItems 2
      * @maxItems 6
      */
-    options: [InteractionOption, InteractionOption] | [InteractionOption, InteractionOption, InteractionOption] | [
-        InteractionOption,
-        InteractionOption,
-        InteractionOption,
-        InteractionOption
-    ] | [
-        InteractionOption,
-        InteractionOption,
-        InteractionOption,
-        InteractionOption,
-        InteractionOption
-    ] | [
-        InteractionOption,
-        InteractionOption,
-        InteractionOption,
-        InteractionOption,
-        InteractionOption,
-        InteractionOption
+    options: [
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        })
+    ] | [
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        })
+    ] | [
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        })
+    ] | [
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        })
+    ] | [
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        }),
+        (string | {
+            label: string;
+            value?: string;
+            intent?: "accept" | "destructive" | "informational" | "neutral";
+        })
     ];
     /**
      * Absolute RFC3339 deadline with an explicit timezone and at most millisecond precision. At least 30 seconds after server acceptance. Mutually exclusive with expires_in_seconds.
@@ -3891,17 +4081,6 @@ export interface SelectInteractionSendRequest {
      */
     expires_in_seconds?: number;
 }
-export interface InteractionOption {
-    /**
-     * Opaque customer data. It is never interpreted as a command.
-     */
-    value: string;
-    label: string;
-    /**
-     * What choosing this option does, so a channel can present it accordingly. Describes consequence rather than appearance: a channel renders `accept` green where it can, `destructive` red, `informational` prominent, and `neutral` plainly. A channel that cannot colour a control ignores this and the option still renders. Omitted means `neutral`.
-     */
-    intent?: "accept" | "destructive" | "informational" | "neutral";
-}
 export interface InputInteractionSendRequest {
     type: "input";
     prompt: string;
@@ -3918,6 +4097,15 @@ export interface InputInteractionSendRequest {
      */
     expires_in_seconds?: number;
 }
+export interface MessageTarget {
+    subscriber_id: OpaqueIdentifier;
+}
+/**
+ * Bounded customer correlation data. Do not include secrets or personal data.
+ */
+export interface Metadata {
+    [k: string]: MetadataValue;
+}
 /**
  * Provenance carried by an ordinary message created during group expansion. The broadcast, message subscriber_id, and exact historical membership generation form the child uniqueness boundary.
  */
@@ -4981,6 +5169,139 @@ export interface ConnectionTestCollection {
     page_size?: ListPageSize;
     total?: ListTotal;
 }
+export interface TextContent {
+    type: "text";
+    /**
+     * Text format. Omitted means plain text. Markdown supports headings, paragraphs, emphasis, strong emphasis, code, lists, quotes and safe HTTP(S) links; raw HTML and remote images are never executed or fetched.
+     */
+    format?: "plain" | "markdown";
+    /**
+     * The complete notification content. This remains authoritative and sufficient when an adapter cannot render optional structure.
+     */
+    text: string;
+    /**
+     * An optional semantic title. The adapter chooses its native presentation.
+     */
+    title?: string;
+    /**
+     * Optional ordered semantic sections that enhance, but never replace, the complete text.
+     *
+     * @minItems 1
+     * @maxItems 12
+     */
+    sections?: [StructuredTextSection] | [StructuredTextSection, StructuredTextSection] | [StructuredTextSection, StructuredTextSection, StructuredTextSection] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ] | [
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection,
+        StructuredTextSection
+    ];
+    image?: NotificationImage;
+}
+/**
+ * One optional provider-neutral illustrative image. The notification content remains complete without the pixels.
+ */
+export interface NotificationImage {
+    asset_id: NotificationImageAssetId;
+    purpose: "illustration";
+    /**
+     * Optional accessible description preserved by every adapter. Omit it for a decorative illustration; notification text must remain complete without the image.
+     */
+    description?: string;
+}
+/**
+ * An authoritative ordered portable notification document that every delivery adapter renders faithfully.
+ */
+export interface DocumentContent {
+    type: "document";
+    /**
+     * An optional semantic document title. The adapter chooses its native presentation.
+     */
+    title?: string;
+    /**
+     * The complete portable document in exact authored order.
+     *
+     * @minItems 1
+     * @maxItems 24
+     */
+    blocks: [DocumentBlock, ...DocumentBlock[]];
+    image?: NotificationImage;
+}
 /**
  * The exact configuration an application the customer creates and owns is created from, as data rather than as a URL-encoded blob.
  *
@@ -6601,7 +6922,7 @@ export interface CreateSubscriberRequest {
     /**
      * @maxItems 50
      */
-    groups?: DeveloperKey[];
+    groups?: GroupKey[];
 }
 /**
  * Change subscriber display name, forced language or forced time zone. Null removes the corresponding override.
@@ -6716,7 +7037,7 @@ export interface Subscriber {
      *
      * @maxItems 200
      */
-    groups?: DeveloperKey[];
+    groups?: GroupKey[];
     /**
      * An RFC 3339 timestamp with a UTC offset. The server is authoritative.
      */
@@ -6789,8 +7110,8 @@ export interface SubscriberDataExportExcludedControllerData {
  * Creates one static, developer-managed subscriber group.
  */
 export interface CreateSubscriberGroupRequest {
-    key: DeveloperKey;
-    display_name: string;
+    key: GroupKey;
+    display_name?: string;
     description?: string;
 }
 export interface SubscriberGroupCollection {
@@ -6804,7 +7125,7 @@ export interface SubscriberGroupCollection {
     total?: ListTotal;
 }
 export interface SubscriberGroupMembershipCollection {
-    group_key: DeveloperKey;
+    group_key: GroupKey;
     membership_revision: number;
     /**
      * @maxItems 100
@@ -6815,24 +7136,6 @@ export interface SubscriberGroupMembershipCollection {
     page_size?: ListPageSize;
     total?: ListTotal;
 }
-/**
- * Creates one group broadcast using the existing ordinary message envelope. The group target comes only from the path.
- */
-export interface CreateGroupBroadcastRequest {
-    notifier_id?: OpaqueIdentifier;
-    content: MessageContent;
-    expires_at?: Timestamp;
-    correlation_id?: string;
-    metadata?: Metadata;
-    /**
-     * Send-time interaction. Choose expires_in_seconds or expires_at; omit both for 24 hours from server acceptance. Idempotent replays retain the original resolved deadline.
-     */
-    interaction?: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
-    /**
-     * Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch.
-     */
-    purpose?: "service" | "marketing";
-}
 /**
  * One durable acceptance against an exact group membership revision. Delivery remains represented by ordinary child messages.
  */
@@ -6845,7 +7148,7 @@ export interface GroupBroadcast {
     project_id: OpaqueIdentifier;
     environment: Environment;
     group_id: OpaqueIdentifier;
-    group_key: DeveloperKey;
+    group_key: GroupKey;
     audience_revision: number;
     status: "accepted" | "expanding" | "expanded" | "complete";
     aggregate: BroadcastAggregate;
@@ -6915,7 +7218,7 @@ export interface UsageBucket {
  * How many of a day's messages fall in one group. `key` is a `MessageState` when grouping by state, a `Channel` when grouping by channel, and a channel connection id when grouping by connection. Groups with no messages are omitted, and a list holds at most the 200 largest groups, largest first.
  */
 export interface UsageGroupCount {
-    key: string;
+    key: GroupKey;
     count: number;
 }
 /**
@@ -7027,6 +7330,17 @@ export interface SelectInteractionRequest {
      */
     correlation_id?: string;
 }
+export interface InteractionOption {
+    /**
+     * Opaque customer data. It is never interpreted as a command.
+     */
+    value: string;
+    label: string;
+    /**
+     * What choosing this option does, so a channel can present it accordingly. Describes consequence rather than appearance: a channel renders `accept` green where it can, `destructive` red, `informational` prominent, and `neutral` plainly. A channel that cannot colour a control ignores this and the option still renders. Omitted means `neutral`.
+     */
+    intent?: "accept" | "destructive" | "informational" | "neutral";
+}
 export interface InputInteractionRequest {
     type: "input";
     prompt: string;
@@ -8062,6 +8376,10 @@ export interface CardSetup {
  */
 export interface CreateCreditPurchaseRequest {
     purchase_cents: 500 | 1000 | 2500 | 5000 | 10000;
+    /**
+     * Optional. The card charge the customer approved: the pack price less any promotion shown to them. When it differs from what would be charged, the purchase is refused with credit_purchase_price_changed and nothing is charged.
+     */
+    approved_charge_usd?: string;
 }
 /**
  * A credit pack charged to the default card. paid means the credit is in the balance. requires_action means the card issuer asks the customer to confirm in the payment form using client_secret; reconcile afterwards. A failed purchase charged nothing; start a new one after updating the card.
@@ -8070,6 +8388,14 @@ export interface CreditPurchase {
     id: string;
     purchase_cents: 500 | 1000 | 2500 | 5000 | 10000;
     credit_usd: string;
+    /**
+     * What the card is charged: the pack price less any promotional discount. The pack's credit is unchanged.
+     */
+    charged_usd: string;
+    /**
+     * The promotional discount taken off the pack price, or 0.000000.
+     */
+    discount_usd: string;
     status: "processing" | "requires_action" | "paid" | "failed";
     failure: ("card_declined" | "authentication_failed") | null;
     client_secret: string | null;
@@ -8286,6 +8612,33 @@ export interface SubscriptionChange {
      * Compatibility field: new upgrades return 0.000000; starts and boundary changes return null. Historical quotes can retain their recorded unused-time credit. No new automatic unused-time refunds or offsets.
      */
     unused_time_credit_usd: string | null;
+    /**
+     * A promotion code's plan discount applied to this first plan or add-on purchase: charge_now_usd is already reduced by it, and the monthly charges keep it for its months. Null when no plan discount applies.
+     */
+    promotion: {
+        percent_off: number;
+        duration: "once" | "repeating";
+        months: number | null;
+        /**
+         * What the promotion takes off charge_now_usd.
+         */
+        discount_usd: string;
+    } | null;
+    /**
+     * A plan discount already running on the subscription, which keeps lowering the monthly charges after this change. It never reduces charge_now_usd. Null when none applies to the next monthly charge, and once a change is no longer a quote.
+     */
+    renewal_promotion: {
+        percent_off: number;
+        duration: "once" | "repeating";
+        /**
+         * What the next monthly charge for this selection comes to with the promotion: monthly_price_usd less its percentage.
+         */
+        renewal_price_usd: string;
+        /**
+         * When a repeating promotion stops applying. Null for a once promotion, which applies to the next monthly charge only.
+         */
+        ends_at: string | null;
+    } | null;
     effective_at: string | null;
     expires_at: string;
     /**
@@ -8340,27 +8693,6 @@ export interface OperatorResolution {
     outcome: "resolved" | "ambiguous" | "not_found";
     choices: Operator[];
 }
-/**
- * Send to a teammate by exact name or operator ID, or use me. Omitted recipient means the verified authenticated human only. Shared and service credentials must name a recipient. Preferred channel, service-email billing and marketing restrictions still apply.
- */
-export interface CreateOperatorMessageRequest {
-    recipient?: string;
-    content: MessageContent;
-    /**
-     * An RFC 3339 timestamp with a UTC offset. The server is authoritative.
-     */
-    expires_at?: string;
-    correlation_id?: string;
-    metadata?: Metadata;
-    /**
-     * Send-time interaction. Choose expires_in_seconds or expires_at; omit both for 24 hours from server acceptance. Idempotent replays retain the original resolved deadline.
-     */
-    interaction?: ConfirmInteractionSendRequest | SelectInteractionSendRequest | InputInteractionSendRequest;
-    /**
-     * Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch.
-     */
-    purpose?: "service" | "marketing";
-}
 /**
  * Readable acceptance or refusal. Accepted means queued, never proof of provider delivery.
  */
@@ -8445,14 +8777,200 @@ export interface WhoAmI {
     me?: Operator;
     detail: string;
 }
-export type RotateCustomerEndpointRequest = RotateApiCredentialRequest;
-/** Renames or redescribes an active group under its last observed row version. */
+/**
+ * An organization's promotions: rewards WhooshBang gave it and promotion codes it redeemed, newest first.
+ */
+export interface BillingPromotions {
+    /**
+     * Unexpired promotional message credit available now.
+     */
+    promotional_credit_usd: string;
+    /**
+     * Unexpired free shared emails available now.
+     */
+    free_shared_emails: number;
+    /**
+     * When the latest active branding promotion ends, if one is active.
+     */
+    branding_removed_until: string | null;
+    /**
+     * @maxItems 200
+     */
+    promotions: BillingPromotion[];
+}
+/**
+ * One promotion an organization holds. Promotional value has no cash value, is never refunded and cannot move to another organization.
+ */
+export interface BillingPromotion {
+    id: string;
+    /**
+     * `whooshbang` for a reward WhooshBang gave the organization directly; `code` for a promotion code the organization redeemed.
+     */
+    source: "whooshbang" | "code";
+    /**
+     * The promotion's name for a redeemed code. Null for a direct reward.
+     */
+    name: string | null;
+    /**
+     * `pending` is a credit pack discount carried by a payment still waiting for the customer's bank; it is not available to another purchase. `used` applies only to a discount that has been applied to a purchase or put on a plan. `revoked` means WhooshBang withdrew what remained.
+     */
+    status: "active" | "pending" | "expired" | "used" | "revoked";
+    starts_at: string;
+    /**
+     * When the benefit stops. Null for a discount, which ends when it is used or, for a plan discount, after its months.
+     */
+    ends_at: string | null;
+    /**
+     * When the promotion was used or withdrawn, if it was.
+     */
+    ended_at: string | null;
+    benefit: {
+        kind: "message_credit";
+        credit_usd: string;
+        remaining_usd: string;
+    } | {
+        kind: "shared_emails";
+        shared_emails: number;
+        remaining: number;
+    } | {
+        kind: "branding";
+    } | {
+        kind: "discount";
+        applies_to: "credit_packs" | "subscriptions";
+        percent_off: number | null;
+        amount_off_usd: string | null;
+        duration: "once" | "repeating";
+        months: number | null;
+    };
+}
+export interface RedeemBillingPromotionRequest {
+    /**
+     * The promotion code. Case, spaces, hyphens and underscores are ignored.
+     */
+    code: string;
+}
+export interface CanonicalConfirmInteractionSendRequest {
+    type: "confirm";
+    prompt: string;
+    confirm_label?: string;
+    deny_label?: string;
+    /**
+     * Absolute RFC3339 deadline with an explicit timezone and at most millisecond precision. At least 30 seconds after server acceptance. Mutually exclusive with expires_in_seconds.
+     */
+    expires_at?: string;
+    /**
+     * Caller-owned opaque correlation returned as data, never treated as execution authority.
+     */
+    correlation_id?: string;
+    /**
+     * Whole seconds from server acceptance. No fixed maximum; the resolved timestamp must be representable through year 9999. Mutually exclusive with expires_at. Omit both for 86400 seconds (24 hours).
+     */
+    expires_in_seconds?: number;
+}
+export interface CanonicalSelectInteractionSendRequest {
+    type: "select";
+    prompt: string;
+    /**
+     * @minItems 2
+     * @maxItems 6
+     */
+    options: [InteractionOption, InteractionOption] | [InteractionOption, InteractionOption, InteractionOption] | [
+        InteractionOption,
+        InteractionOption,
+        InteractionOption,
+        InteractionOption
+    ] | [
+        InteractionOption,
+        InteractionOption,
+        InteractionOption,
+        InteractionOption,
+        InteractionOption
+    ] | [
+        InteractionOption,
+        InteractionOption,
+        InteractionOption,
+        InteractionOption,
+        InteractionOption,
+        InteractionOption
+    ];
+    /**
+     * Absolute RFC3339 deadline with an explicit timezone and at most millisecond precision. At least 30 seconds after server acceptance. Mutually exclusive with expires_in_seconds.
+     */
+    expires_at?: string;
+    /**
+     * Caller-owned opaque correlation returned as data, never treated as execution authority.
+     */
+    correlation_id?: string;
+    /**
+     * Whole seconds from server acceptance. No fixed maximum; the resolved timestamp must be representable through year 9999. Mutually exclusive with expires_at. Omit both for 86400 seconds (24 hours).
+     */
+    expires_in_seconds?: number;
+}
+export interface CanonicalInputInteractionSendRequest {
+    type: "input";
+    prompt: string;
+    /**
+     * Absolute RFC3339 deadline with an explicit timezone and at most millisecond precision. At least 30 seconds after server acceptance. Mutually exclusive with expires_in_seconds.
+     */
+    expires_at?: string;
+    /**
+     * Caller-owned opaque correlation returned as data, never treated as execution authority.
+     */
+    correlation_id?: string;
+    /**
+     * Whole seconds from server acceptance. No fixed maximum; the resolved timestamp must be representable through year 9999. Mutually exclusive with expires_at. Omit both for 86400 seconds (24 hours).
+     */
+    expires_in_seconds?: number;
+}
+/**
+ * Creates one group broadcast using the existing ordinary message envelope. The group target comes only from the path.
+ */
+export interface CanonicalCreateGroupBroadcastRequest {
+    notifier_id?: OpaqueIdentifier;
+    content: MessageContent;
+    expires_at?: Timestamp;
+    correlation_id?: string;
+    metadata?: Metadata;
+    /**
+     * Send-time interaction. Choose expires_in_seconds or expires_at; omit both for 24 hours from server acceptance. Idempotent replays retain the original resolved deadline.
+     */
+    interaction?: CanonicalConfirmInteractionSendRequest | CanonicalSelectInteractionSendRequest | CanonicalInputInteractionSendRequest;
+    /**
+     * Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch.
+     */
+    purpose?: "service" | "marketing";
+}
+/**
+ * Send to a teammate by exact name or operator ID, or use me. Omitted recipient means the verified authenticated human only. Shared and service credentials must name a recipient. Preferred channel, service-email billing and marketing restrictions still apply.
+ */
+export interface CanonicalCreateOperatorMessageRequest {
+    recipient?: string;
+    content: MessageContent;
+    /**
+     * An RFC 3339 timestamp with a UTC offset. The server is authoritative.
+     */
+    expires_at?: string;
+    correlation_id?: string;
+    metadata?: Metadata;
+    /**
+     * Send-time interaction. Choose expires_in_seconds or expires_at; omit both for 24 hours from server acceptance. Idempotent replays retain the original resolved deadline.
+     */
+    interaction?: CanonicalConfirmInteractionSendRequest | CanonicalSelectInteractionSendRequest | CanonicalInputInteractionSendRequest;
+    /**
+     * Omitted means service. Marketing refuses service-only bindings before charging and at every delayed dispatch.
+     */
+    purpose?: "service" | "marketing";
+}
+export interface RotateCustomerEndpointRequest {
+    overlap_seconds?: number;
+}
+/** Renames or redescribes a group; an omitted version uses last write wins. */
 export type UpdateSubscriberGroupRequest = {
-    row_version: number;
+    row_version?: number;
     display_name: string;
     description?: string | null;
 } | {
-    row_version: number;
+    row_version?: number;
     display_name?: string;
     description: string | null;
 };