DEVX-8749: Add Verify v2 Custom Templates (#318)

* Adding Templates and Template Fragments to Verify2 implementation
Vonage · Oct 24, 2024 · 131be52 · 131be52
1 parent 68ff52b
commit 131be52
Show file tree

Hide file tree

Showing 11 changed files with 520 additions and 1 deletion.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,3 +1,7 @@
+# 7.28.0
+
+* Adds templates and template fragments to the Verify v2 implementation. [#318](https://github.com/Vonage/vonage-ruby-sdk/pull/318)
+
 # 7.27.1
 
 * Fixes a bug with setting options on the HTTP client. [#319](https://github.com/Vonage/vonage-ruby-sdk/pull/319)

diff --git a/README.md b/README.md
@@ -488,6 +488,66 @@ if code_check.http_response.code == '200'
 end
 ```
 
+### Working with Verify Custom Templates and Template Fragments
+
+Verify custom templates allow you to customize the message sent to deliver an OTP to your users, rather than using the default Vonage templates. See the [Template Management Guide document](https://developer.vonage.com/en/verify/guides/custom-templates) for more information.
+
+#### Templates
+
+```ruby
+# Get a list of all templates
+template_list = verify.templates.list
+
+# Get details of a specific template
+template = verify.templates.info(template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9')
+
+# Create a new template
+verify.templates.create(name: 'my-template')
+
+# Update an existing template
+verify.templates.update(
+  template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+  name: 'my-updated-template'
+)
+
+# Delete a template
+verify.templates.delete(template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9')
+```
+
+#### Template Fragments
+
+```ruby
+# Get a list of template fragments for a specific template
+template_fragment_list = verify.template_fragments.list(template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9')
+
+# Get details of a specific template fragment
+template_fragment = verify.template_fragments.info(
+  template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+  template_fragment_id: 'c70f446e-997a-4313-a081-60a02a31dc19'
+)
+
+# Create a new template fragement
+verify.template_fragments.create(
+  template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+  channel: 'sms',
+  locale: 'en-gb',
+  text: 'Your code is: ${code}'
+)
+
+# Update an existing template fragment
+verify.template_fragments.update(
+  template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+  template_fragment_id: 'c70f446e-997a-4313-a081-60a02a31dc1',
+  text: 'Your one-time code is: ${code}'
+)
+
+# Delete a template fragment
+verify.template_fragments.delete(
+  template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+  template_fragment_id: 'c70f446e-997a-4313-a081-60a02a31dc19'
+)
+```
+
 ## Voice API
 
 The [Vonage Voice API](The [Vonage Verify API v2](https://developer.vonage.com/en/verify/verify-v2/overview) allows you to automate voice interactions by creating calls, streaming audio, playing text to speech, playing DTMF tones, and other actions. See the Vonage Developer Documentation for a [complete API reference](https://developer.vonage.com/en/api/voice) listing all the Voice API capabilities.

diff --git a/lib/vonage/verify2.rb b/lib/vonage/verify2.rb
@@ -96,5 +96,17 @@ def workflow
     def workflow_builder
       WorkflowBuilder.itself
     end
+
+    # @return [Templates]
+    # Returns existing or instantiates a new Vonage::Verify2::Templates object
+    def templates
+      @templates ||= Templates.new(@config)
+    end
+
+    # @return [TemplateFragments]
+    # Returns existing or instantiates a new Vonage::Verify2::Templates object
+    def template_fragments
+      @template_fragments ||= TemplateFragments.new(@config)
+    end
   end
 end
diff --git a/lib/vonage/verify2/template_fragments.rb b/lib/vonage/verify2/template_fragments.rb
@@ -0,0 +1,125 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Verify2::TemplateFragments < Namespace
+    CHANNELS = ['sms', 'voice'].freeze
+
+    self.authentication = BearerToken
+
+    self.request_body = JSON
+
+    # Get a list of of template fragments for a specific template.
+    #
+    # @example
+    #   template_fragment_list = client.verify2.template_fragments.list(template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9')
+    #
+    # @param [required, String] :template_id. The ID of the template for which to retreive the fragments
+    #
+    # @param [optional, Integer] :page_size. The amount of template fragments to list per page
+    #
+    # @param [optional, Integer] :page. The page number to retrieve
+    #
+    # @return [ListResponse]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#listTemplateFragments
+    def list(template_id:, **params)
+      request("/v2/verify/templates/#{template_id}/template_fragments", params: params, response_class: ListResponse)
+    end
+
+    # Get details of a specific template fragment.
+    #
+    # @example
+    #   template_fragment = client.verify2.template_fragments.info(
+    #                         template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+    #                         template_fragment_id: 'c70f446e-997a-4313-a081-60a02a31dc19'
+    #                       )
+    #
+    # @param [required, String] :template_id. The ID of the template for which to retreive the fragment
+    #
+    # @param [required, String] :template_fragment_id. The ID of the fragment to be retreived
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#getTemplateFragment
+    def info(template_id:, template_fragment_id:)
+      request("/v2/verify/templates/#{template_id}/template_fragments/#{template_fragment_id}")
+    end
+
+    # Create a new template fragment.
+    #
+    # @example
+    #   client.verify2.template_fragments.create(
+    #                         template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+    #                         channel: 'sms',
+    #                         locale: 'en-gb',
+    #                         text: 'Your code is: ${code}'
+    #                       )
+    #
+    # @param [required, String] :template_id. The ID of the template for which to create the fragment
+    #
+    # @param [required, String] :channel. The verification channel for which to create the fragment. Must be one of 'sms' or 'voice'
+    #
+    # @param [required, String] :locale. The locale for which to create the fragment.
+    #
+    # @param [required, String] :text. The text to be used in the template fragment.
+    #   There are 4 reserved variables available to use as part of the text: ${code}, ${brand}, ${time-limit} and ${time-limit-unit}
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#addTemplateFragmentToTemplate
+    def create(template_id:, channel:, locale:, text:)
+      raise ArgumentError, "Invalid 'channel' #{channel}. Must be one of #{CHANNELS.join(', ')}" unless CHANNELS.include?(channel)
+      request(
+        "/v2/verify/templates/#{template_id}/template_fragments",
+        params: {
+          channel: channel,
+          locale: locale,
+          text: text
+        },
+        type: Post)
+    end
+
+    # Update an existing template fragment.
+    #
+    # @example
+    #   client.verify2.template_fragments.update(
+    #                         template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+    #                         template_fragment_id: 'c70f446e-997a-4313-a081-60a02a31dc19',
+    #                         text: 'Your one-time code is: ${code}'
+    #                       )
+    #
+    # @param [required, String] :template_id. The ID of the template with which the fragment to be updated is associated
+    #
+    # @param [required, String] :template_fragment_id. The ID of the fragment to be updated
+    #
+    # @param [required, String] :text. The text to be used in the template fragment.
+    #   There are 4 reserved variables available to use as part of the text: ${code}, ${brand}, ${time-limit} and ${time-limit-unit}
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#updateTemplateFragment
+    def update(template_id:, template_fragment_id:, text:)
+      request("/v2/verify/templates/#{template_id}/template_fragments/#{template_fragment_id}", params: {text: text}, type: Patch)
+    end
+
+    # Delete a template fragment.
+    #
+    # @example
+    #   client.verify2.template_fragments.delete(
+    #                         template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9',
+    #                         template_fragment_id: 'c70f446e-997a-4313-a081-60a02a31dc19'
+    #                       )
+    #
+    # @param [required, String] :template_id. The ID of the template with which the fragment to be deleted is associated
+    #
+    # @param [required, String] :template_fragment_id. The ID of the fragment to be deleted
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#deleteTemplateFragment
+    def delete(template_id:, template_fragment_id:)
+      request("/v2/verify/templates/#{template_id}/template_fragments/#{template_fragment_id}", type: Delete)
+    end
+  end
+end
diff --git a/lib/vonage/verify2/template_fragments/list_response.rb b/lib/vonage/verify2/template_fragments/list_response.rb
@@ -0,0 +1,11 @@
+# typed: true
+
+class Vonage::Verify2::TemplateFragments::ListResponse < Vonage::Response
+  include Enumerable
+
+  def each
+    return enum_for(:each) unless block_given?
+
+    @entity._embedded.template_fragments.each { |item| yield item }
+  end
+end
diff --git a/lib/vonage/verify2/templates.rb b/lib/vonage/verify2/templates.rb
@@ -0,0 +1,86 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Verify2::Templates < Namespace
+    self.authentication = BearerToken
+
+    self.request_body = JSON
+
+    # Get a list of all templates.
+    #
+    # @example
+    #   template_list = client.verify2.templates.list
+    #
+    # @param [optional, Integer] :page_size. The amount of templates to list per page
+    #
+    # @param [optional, Integer] :page. The page number to retrieve
+    #
+    # @return [ListResponse]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#listTemplates
+    def list(**params)
+      request('/v2/verify/templates', params: params, response_class: ListResponse)
+    end
+
+    # Get details of a specific template.
+    #
+    # @example
+    #   template = client.verify2.templates.info(template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9')
+    #
+    # @param [required, String] :template_id. The ID of the template to be retreived
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#getTemplate
+    def info(template_id:)
+      request('/v2/verify/templates/' + template_id)
+    end
+
+    # Create a new template.
+    #
+    # @example
+    #   client.verify2.templates.create(name: 'my-template')
+    #
+    # @param [required, String] :name. The name of the template. The following characters are permitted: [A-Z a-z 0-9 _ -]
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#createTemplate
+    def create(name:)
+      request('/v2/verify/templates', params: { name: name }, type: Post)
+    end
+
+    # Update an existing template.
+    #
+    # @example
+    #   client.verify2.templates.update(template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9', name: 'my-updated-template')
+    #
+    # @param [required, String] :template_id. The ID of the template to be updated
+    #
+    # @param [optional, String] :name. The name of the template. The following characters are permitted: [A-Z a-z 0-9 _ -]
+    #
+    # @param [optional, Boolean] :is_default. Whether the template is the default template for a specific locale/channel combination
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#updateTemplate
+    def update(template_id:, **params)
+      request('/v2/verify/templates/' + template_id, params: params, type: Patch)
+    end
+
+    # Delete a template.
+    #
+    # @example
+    #   client.verify2.templates.delete(template_id: '8f35a1a7-eb2f-4552-8fdf-fffdaee41bc9')
+    #
+    # @param [required, String] :template_id. The ID of the template to be deleted
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/verify.v2#deleteTemplate
+    def delete(template_id:)
+      request('/v2/verify/templates/' + template_id, type: Delete)
+    end
+  end
+end
diff --git a/lib/vonage/verify2/templates/list_response.rb b/lib/vonage/verify2/templates/list_response.rb
@@ -0,0 +1,11 @@
+# typed: true
+
+class Vonage::Verify2::Templates::ListResponse < Vonage::Response
+  include Enumerable
+
+  def each
+    return enum_for(:each) unless block_given?
+
+    @entity._embedded.templates.each { |item| yield item }
+  end
+end
diff --git a/lib/vonage/version.rb b/lib/vonage/version.rb
@@ -1,5 +1,5 @@
 # typed: strong
 
 module Vonage
-  VERSION = '7.27.1'
+  VERSION = '7.28.0'
 end