v1.3.1: Add tag API coverage

Author: billm950

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to the `assinafy` Ruby gem are documented here.
 
+## 1.3.1
+
+### Added
+
+- `Client#tags` and `Resources::TagResource` for the documented workspace tag
+  endpoints.
+- Document tag helpers on `Resources::DocumentResource`: `list_tags`,
+  `replace_tags`, `append_tags`, and `detach_tag`.
+
+### Fixed
+
+- Assignment signer payloads now preserve the documented `step` field for
+  sequential signing.
+
 ## 1.3.0
 
 ### Added

README.md

@@ -89,7 +89,7 @@ client = Assinafy::Client.new(
 
 ## Resources
 
-The eight resource accessors on `Assinafy::Client` cover every documented endpoint:
+The nine resource accessors on `Assinafy::Client` cover every documented endpoint:
 
 | Accessor                    | What it covers                                                 |
 | --------------------------- | -------------------------------------------------------------- |
@@ -99,6 +99,7 @@ The eight resource accessors on `Assinafy::Client` cover every documented endpoi
 | `client.signer_documents`   | Signer-authenticated multi-document operations                 |
 | `client.assignments`        | Create/sign/decline/resend/estimate assignments                |
 | `client.templates`          | Template CRUD                                                  |
+| `client.tags`               | Workspace tags                                                 |
 | `client.fields`             | Field definitions + validation + type catalog                  |
 | `client.webhooks`           | Subscription, event-type catalog, dispatch history, retries    |
 | `client.webhook_verifier`   | Optional HMAC-SHA256 verifier for signed deliveries            |
@@ -133,6 +134,10 @@ client.documents.delete('document-id')
 client.documents.verify('signature-hash')
 client.documents.public_info('document-id')
 client.documents.send_token('document-id', recipient: 'alice@example.com', channel: 'email')
+client.documents.list_tags('document-id')
+client.documents.replace_tags('document-id', ['Contracts', '2026-Q1'])
+client.documents.append_tags('document-id', ['Urgent'])
+client.documents.detach_tag('document-id', 'tag-id')
 
 # Template-driven creation
 client.documents.create_from_template(
@@ -183,7 +188,7 @@ client.signers.download_signature(signer_access_code: 'code', type: 'signature')
 client.assignments.create(
   'document-id',
   method:         'virtual',
-  signers:        [{ id: 'signer-1', verification_method: 'Email', notification_methods: ['Email'] }],
+  signers:        [{ id: 'signer-1', verification_method: 'Email', notification_methods: ['Email'], step: 1 }],
   message:        'Please sign',
   expires_at:     '2026-12-31T23:59:00Z',
   copy_receivers: ['cc-signer-id']
@@ -236,6 +241,16 @@ client.templates.create(name: 'My template', message: 'Please sign')
 client.templates.update('template-id', name: 'Renamed template')
 ```
 
+### Tags
+
+```ruby
+client.tags.list(search: 'contract')
+client.tags.create(name: 'Contracts', color: 'ff8800')
+client.tags.update('tag-id', name: 'Sales Contracts', color: nil)
+client.tags.delete('tag-id')              # fails with 409 if the tag is in use
+client.tags.delete('tag-id', force: true) # detaches from documents/templates first
+```
+
 ### Fields
 
 ```ruby

assinafy.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary     = 'Ruby SDK for the Assinafy digital signature API'
   spec.description = 'Ruby SDK for Assinafy. Covers the documented authentication, ' \
-                     'document, signer, assignment, webhook, template, and field APIs, plus the high-level ' \
+                     'document, signer, assignment, webhook, template, tag, and field APIs, plus the high-level ' \
                      'upload_and_request_signatures helper.'
   spec.homepage    = 'https://github.com/assinafy/ruby-sdk'
   spec.license     = 'MIT'
@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.files         = Dir['lib/**/*.rb', 'CHANGELOG.md', 'LICENSE', 'README.md']
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'faraday', '>= 1.10', '< 3.0'
+  spec.add_dependency 'faraday', '>= 2.14.2', '< 3.0'
   spec.add_dependency 'faraday-multipart', '>= 1.0', '< 2.0'
 
   spec.add_development_dependency 'bundler-audit', '~> 0.9'

lib/assinafy.rb

@@ -18,5 +18,6 @@
 require_relative 'assinafy/resources/webhook_resource'
 require_relative 'assinafy/resources/template_resource'
 require_relative 'assinafy/resources/field_resource'
+require_relative 'assinafy/resources/tag_resource'
 require_relative 'assinafy/support/webhook_verifier'
 require_relative 'assinafy/client'

lib/assinafy/client.rb

@@ -31,6 +31,8 @@ class Client
     attr_reader :templates
     # @return [Resources::FieldResource]
     attr_reader :fields
+    # @return [Resources::TagResource]
+    attr_reader :tags
     # @return [Support::WebhookVerifier]
     attr_reader :webhook_verifier
 
@@ -65,6 +67,7 @@ def initialize(api_key: nil, token: nil, account_id: nil,
       @webhooks         = Resources::WebhookResource.new(@connection, account_id, @logger)
       @templates        = Resources::TemplateResource.new(@connection, account_id, @logger)
       @fields           = Resources::FieldResource.new(@connection, account_id, @logger)
+      @tags             = Resources::TagResource.new(@connection, account_id, @logger)
       @webhook_verifier = Support::WebhookVerifier.new(webhook_secret)
     end
 

lib/assinafy/resources/assignment_resource.rb

@@ -22,7 +22,7 @@ class << self
         # shape the API expects. Accepts:
         #
         # - `signers: ['id1', 'id2']` — bare IDs
-        # - `signers: [{ id:, verification_method:, notification_methods: }]`
+        # - `signers: [{ id:, verification_method:, notification_methods:, step: }]`
         # - Legacy `signer_ids:`/`signerIds:` arrays of IDs
         #
         # @param payload [Hash]
@@ -88,6 +88,7 @@ def hash_signer_ref(ref, options)
           normalised[:id]                   = id                        if id
           normalised[:verification_method]  = r[:verification_method]   if r[:verification_method]
           normalised[:notification_methods] = r[:notification_methods]  if r[:notification_methods]
+          normalised[:step]                 = r[:step]                  unless r[:step].nil?
 
           return normalised if id.is_a?(String) && !id.empty?
           return normalised.tap { |h| h.delete(:id) } if options[:allow_signers_without_id]

lib/assinafy/resources/document_resource.rb

@@ -286,6 +286,73 @@ def send_token(document_id, recipient:, channel:)
         end
       end
 
+      # List tags attached to a document.
+      #
+      # @param document_id [String]
+      # @param account_id_override [String, nil]
+      # @return [Array<Hash>]
+      # @see GET /accounts/{account_id}/documents/{document_id}/tags
+      def list_tags(document_id, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        doc_id = require_id(document_id, 'Document ID')
+
+        call('Failed to list document tags') do
+          http_get("accounts/#{acc_id}/documents/#{doc_id}/tags")
+        end
+      end
+
+      # Replace the document's full tag set. Passing an empty array detaches
+      # all tags from the document.
+      #
+      # @param document_id [String]
+      # @param tags [Array<String>] tag names
+      # @param account_id_override [String, nil]
+      # @return [Array<Hash>]
+      # @see PUT /accounts/{account_id}/documents/{document_id}/tags
+      def replace_tags(document_id, tags, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        doc_id = require_id(document_id, 'Document ID')
+
+        call('Failed to replace document tags') do
+          http_put("accounts/#{acc_id}/documents/#{doc_id}/tags",
+                   body_params(tags: tag_names(tags, allow_empty: true)))
+        end
+      end
+
+      # Attach additional tags to a document without removing existing tags.
+      #
+      # @param document_id [String]
+      # @param tags [Array<String>] tag names
+      # @param account_id_override [String, nil]
+      # @return [Array<Hash>]
+      # @see POST /accounts/{account_id}/documents/{document_id}/tags
+      def append_tags(document_id, tags, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        doc_id = require_id(document_id, 'Document ID')
+
+        call('Failed to append document tags') do
+          http_post("accounts/#{acc_id}/documents/#{doc_id}/tags",
+                    body_params(tags: tag_names(tags)))
+        end
+      end
+
+      # Detach a single tag from a document. The tag itself is not deleted.
+      #
+      # @param document_id [String]
+      # @param tag_id [String]
+      # @param account_id_override [String, nil]
+      # @return [Hash]
+      # @see DELETE /accounts/{account_id}/documents/{document_id}/tags/{tag_id}
+      def detach_tag(document_id, tag_id, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        doc_id = require_id(document_id, 'Document ID')
+        tid    = require_id(tag_id, 'Tag ID')
+
+        call('Failed to detach document tag') do
+          http_delete("accounts/#{acc_id}/documents/#{doc_id}/tags/#{tid}")
+        end
+      end
+
       # Convenience: true when the document is `certificated`, or when the
       # embedded assignment summary reports all signers complete.
       #
@@ -372,6 +439,24 @@ def template_body(signers_or_payload, options = {})
         body_params(body)
       end
 
+      def tag_names(tags, allow_empty: false)
+        unless tags.is_a?(Array)
+          raise ValidationError.new('Tags must be an Array')
+        end
+
+        if tags.empty? && !allow_empty
+          raise ValidationError.new('Tags must be a non-empty Array')
+        end
+
+        tags.each do |tag|
+          next unless tag.to_s.strip.empty?
+
+          raise ValidationError.new('Tag names cannot be empty')
+        end
+
+        tags
+      end
+
       def artifact_type(artifact_name)
         value = require_id(artifact_name, 'Artifact name').to_s
         return value if ARTIFACT_TYPES.include?(value)

lib/assinafy/resources/tag_resource.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Assinafy
+  module Resources
+    # Workspace-scoped tag management.
+    #
+    # Tags are labels that can be attached to documents and templates for
+    # filtering and organization.
+    #
+    # See https://api.assinafy.com.br/v1/docs#tag for the full
+    # documentation of these endpoints.
+    class TagResource < BaseResource
+      # List tags in the workspace.
+      #
+      # @param params [Hash] query parameters (`search`, `page`, `per_page`)
+      # @param account_id_override [String, nil]
+      # @return [Hash{Symbol=>Array,Hash}] `{ data: [...], meta: { ... } }`
+      # @see GET /accounts/{account_id}/tags
+      def list(params = {}, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+
+        call_list('Failed to list tags') do
+          http_get("accounts/#{acc_id}/tags", params)
+        end
+      end
+
+      # Create a tag in the workspace.
+      #
+      # @param payload [Hash]
+      # @option payload [String] :name  required tag display name
+      # @option payload [String, nil] :color optional 6-character hex color
+      # @param account_id_override [String, nil]
+      # @return [Hash]
+      # @see POST /accounts/{account_id}/tags
+      def create(payload, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        body   = tag_payload(payload, require_name: true)
+
+        call('Failed to create tag') do
+          http_post("accounts/#{acc_id}/tags", body)
+        end
+      end
+
+      # Update a tag's name and/or color.
+      #
+      # @param tag_id [String]
+      # @param payload [Hash]
+      # @option payload [String] :name optional new name
+      # @option payload [String, nil] :color optional new color; nil clears it
+      # @param account_id_override [String, nil]
+      # @return [Hash]
+      # @see PUT /accounts/{account_id}/tags/{tag_id}
+      def update(tag_id, payload, account_id_override = nil)
+        acc_id = account_id(account_id_override)
+        tid    = require_id(tag_id, 'Tag ID')
+        body   = tag_payload(payload, require_name: false)
+
+        call('Failed to update tag') do
+          http_put("accounts/#{acc_id}/tags/#{tid}", body)
+        end
+      end
+
+      # Delete a tag. Pass `force: true` to detach it from documents and
+      # templates before deletion, matching the documented query parameter.
+      #
+      # @param tag_id [String]
+      # @param account_id_override [String, nil]
+      # @param force [Boolean]
+      # @return [Hash]
+      # @see DELETE /accounts/{account_id}/tags/{tag_id}
+      def delete(tag_id, account_id_override = nil, force: false)
+        acc_id = account_id(account_id_override)
+        tid    = require_id(tag_id, 'Tag ID')
+        params = force ? { force: true } : {}
+
+        call('Failed to delete tag') do
+          http_delete("accounts/#{acc_id}/tags/#{tid}", params)
+        end
+      end
+
+      private
+
+      def tag_payload(payload, require_name:)
+        raw  = require_payload(payload, 'Tag payload')
+        body = body_params(raw)
+        name = body['name']
+
+        body['color'] = nil if explicit_nil_color?(raw)
+
+        if require_name && name.to_s.strip.empty?
+          raise ValidationError.new('Tag name is required')
+        end
+
+        body
+      end
+
+      def explicit_nil_color?(payload)
+        (payload.key?(:color) && payload[:color].nil?) ||
+          (payload.key?('color') && payload['color'].nil?)
+      end
+    end
+  end
+end

lib/assinafy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Assinafy
-  VERSION = '1.3.0'
+  VERSION = '1.3.1'
 end

spec/api_coverage_spec.rb

@@ -85,6 +85,14 @@
        'DocumentResource#public_info'],
       ['PUT',    '/public/documents/{document_id}/send-token',
        'DocumentResource#send_token'],
+      ['GET',    '/accounts/{account_id}/documents/{document_id}/tags',
+       'DocumentResource#list_tags'],
+      ['PUT',    '/accounts/{account_id}/documents/{document_id}/tags',
+       'DocumentResource#replace_tags'],
+      ['POST',   '/accounts/{account_id}/documents/{document_id}/tags',
+       'DocumentResource#append_tags'],
+      ['DELETE', '/accounts/{account_id}/documents/{document_id}/tags/{tag_id}',
+       'DocumentResource#detach_tag'],
 
       # Templates
       ['GET',    '/accounts/{account_id}/templates',
@@ -96,6 +104,16 @@
       ['PUT',    '/accounts/{account_id}/templates/{template_id}',
        'TemplateResource#update'],
 
+      # Tags
+      ['GET',    '/accounts/{account_id}/tags',
+       'TagResource#list'],
+      ['POST',   '/accounts/{account_id}/tags',
+       'TagResource#create'],
+      ['PUT',    '/accounts/{account_id}/tags/{tag_id}',
+       'TagResource#update'],
+      ['DELETE', '/accounts/{account_id}/tags/{tag_id}',
+       'TagResource#delete'],
+
       # Assignments
       ['POST',   '/documents/{documentId}/assignments',
        'AssignmentResource#create'],