Class: Courier::Resources::Users::Preferences

Inherits:
Object
  • Object
show all
Defined in:
lib/courier/resources/users/preferences.rb,
sig/courier/resources/users/preferences.rbs

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Preferences

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Preferences.

Parameters:



242
243
244
 
# File 'lib/courier/resources/users/preferences.rb', line 242

def initialize(client:)
  @client = client
end

Instance Method Details

#bulk_replace(user_id, topics:, tenant_id: nil, request_options: {}) ⇒ Courier::Models::Users::PreferenceBulkReplaceResponse

Some parameter documentations has been truncated, see Models::Users::PreferenceBulkReplaceParams for more details.

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.

Parameters:

  • user_id (String) —

    Path param: A unique identifier associated with the user whose preferences you w

  • topics (Array<Courier::Models::Users::PreferenceBulkReplaceParams::Topic>) —

    Body param: The complete set of topic overrides for the user. Up to 50 topics ma

  • tenant_id (String, nil) —

    Query param: Replace the preferences of a user for this specific tenant context.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/courier/resources/users/preferences.rb', line 69

def bulk_replace(user_id, params)
  query_params = [:tenant_id]
  parsed, options = Courier::Users::PreferenceBulkReplaceParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :put,
    path: ["users/%1$s/preferences", user_id],
    query: query,
    body: parsed.except(*query_params),
    model: Courier::Models::Users::PreferenceBulkReplaceResponse,
    options: options
  )
end

#bulk_update(user_id, topics:, tenant_id: nil, request_options: {}) ⇒ Courier::Models::Users::PreferenceBulkUpdateResponse

Some parameter documentations has been truncated, see Models::Users::PreferenceBulkUpdateParams for more details.

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.

Parameters:

  • user_id (String) —

    Path param: A unique identifier associated with the user whose preferences you w

  • topics (Array<Courier::Models::Users::PreferenceBulkUpdateParams::Topic>) —

    Body param: The topics to create or update. Between 1 and 50 topics may be provi

  • tenant_id (String, nil) —

    Query param: Update the preferences of a user for this specific tenant context.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/courier/resources/users/preferences.rb', line 117

def bulk_update(user_id, params)
  query_params = [:tenant_id]
  parsed, options = Courier::Users::PreferenceBulkUpdateParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :post,
    path: ["users/%1$s/preferences", user_id],
    query: query,
    body: parsed.except(*query_params),
    model: Courier::Models::Users::PreferenceBulkUpdateResponse,
    options: options
  )
end

#delete_topic(topic_id, user_id:, tenant_id: nil, request_options: {}) ⇒ nil

Some parameter documentations has been truncated, see Models::Users::PreferenceDeleteTopicParams for more details.

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.

Parameters:

  • topic_id (String) —

    Path param: A unique identifier associated with a subscription topic.

  • user_id (String) —

    Path param: A unique identifier associated with the user whose preferences you w

  • tenant_id (String, nil) —

    Query param: Delete the preferences of a user for this specific tenant context.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/courier/resources/users/preferences.rb', line 151

def delete_topic(topic_id, params)
  parsed, options = Courier::Users::PreferenceDeleteTopicParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed)
  user_id =
    parsed.delete(:user_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :delete,
    path: ["users/%1$s/preferences/%2$s", user_id, topic_id],
    query: query,
    model: NilClass,
    options: options
  )
end

#retrieve(user_id, tenant_id: nil, request_options: {}) ⇒ Courier::Models::Users::PreferenceRetrieveResponse

Some parameter documentations has been truncated, see Models::Users::PreferenceRetrieveParams for more details.

Fetch all user preferences.

Parameters:

  • user_id (String) —

    A unique identifier associated with the user whose preferences you wish to retri

  • tenant_id (String, nil) —

    Query the preferences of a user for this specific tenant context.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/courier/resources/users/preferences.rb', line 23

def retrieve(user_id, params = {})
  parsed, options = Courier::Users::PreferenceRetrieveParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["users/%1$s/preferences", user_id],
    query: query,
    model: Courier::Models::Users::PreferenceRetrieveResponse,
    options: options
  )
end

#retrieve_topic(topic_id, user_id:, tenant_id: nil, request_options: {}) ⇒ Courier::Models::Users::PreferenceRetrieveTopicResponse

Some parameter documentations has been truncated, see Models::Users::PreferenceRetrieveTopicParams for more details.

Fetch user preferences for a specific subscription topic.

Parameters:

  • topic_id (String) —

    Path param: A unique identifier associated with a subscription topic.

  • user_id (String) —

    Path param: A unique identifier associated with the user whose preferences you w

  • tenant_id (String, nil) —

    Query param: Query the preferences of a user for this specific tenant context.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/courier/resources/users/preferences.rb', line 185

def retrieve_topic(topic_id, params)
  parsed, options = Courier::Users::PreferenceRetrieveTopicParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed)
  user_id =
    parsed.delete(:user_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["users/%1$s/preferences/%2$s", user_id, topic_id],
    query: query,
    model: Courier::Models::Users::PreferenceRetrieveTopicResponse,
    options: options
  )
end

#update_or_create_topic(topic_id, user_id:, topic:, tenant_id: nil, request_options: {}) ⇒ Courier::Models::Users::PreferenceUpdateOrCreateTopicResponse

Some parameter documentations has been truncated, see Models::Users::PreferenceUpdateOrCreateTopicParams for more details.

Update or Create user preferences for a specific subscription topic.

Parameters:

  • topic_id (String) —

    Path param: A unique identifier associated with a subscription topic.

  • user_id (String) —

    Path param: A unique identifier associated with the user whose preferences you w

  • topic (Courier::Models::Users::PreferenceUpdateOrCreateTopicParams::Topic) —

    Body param

  • tenant_id (String, nil) —

    Query param: Update the preferences of a user for this specific tenant context.

  • request_options (Courier::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/courier/resources/users/preferences.rb', line 221

def update_or_create_topic(topic_id, params)
  query_params = [:tenant_id]
  parsed, options = Courier::Users::PreferenceUpdateOrCreateTopicParams.dump_request(params)
  query = Courier::Internal::Util.encode_query_params(parsed.slice(*query_params))
  user_id =
    parsed.delete(:user_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :put,
    path: ["users/%1$s/preferences/%2$s", user_id, topic_id],
    query: query,
    body: parsed.except(*query_params),
    model: Courier::Models::Users::PreferenceUpdateOrCreateTopicResponse,
    options: options
  )
end