docuseal 0.1.2 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fd66438a5ff8a1c6e320d4481a8d93c2103ade62303b6a9c9e5e7648efcb59c
-  data.tar.gz: 58ef168c6f51af33c7fee7c68caf5f443f20e7000a1d21718adda2585fe9733e
+  metadata.gz: df6cd59df11dcce0c5c2197072bbe147fd5547452f9cd8f4843adc70acfd3ab2
+  data.tar.gz: 23fe9247d7d9b90c170fdcdd6305cd66c990644674d22cf54cbf437c8444777d
 SHA512:
-  metadata.gz: 4bf980bedcea969ecbfd7a9878867126e4023b801127c0fcc33e9c776d0e46777d2fbc97e78254a45d422d1fb8a03fc3cd69b95700581aec57687a446aa160ab
-  data.tar.gz: 42638043365a9821f0bbdc8458b3691e7fde74ec7b406f9f946f87b7c5332b5c6d9ab0a4d6a27ae16ed4ad09c2b184517b0f83aee044dde9cedb79982b00f41f
+  metadata.gz: b3ac3d6203f31ec7c954aee6eef92d0d07bbf6c2c4b56dfee31cb93f365c4c17289484d2efd832868051b099eeae0124ca343057da2ba95fc226437a36eec290
+  data.tar.gz: d0444f297d866a07be0c104058eda775f05af1c0eb80159b8759390240c33efe1cf4b22d4b815b6f68d1f2dd478390b8512c68efc3a51e98fc025496901f671e

data/README.md

@@ -1,255 +1,373 @@
-# Docuseal API Connector
+# DocuSeal Ruby
 
-<a href="https://codecov.io/github/moraki-finance/docuseal" >
- <img src="https://codecov.io/github/moraki-finance/docuseal/graph/badge.svg?token=SKTT14JJGV"/>
-</a>
+The DocuSeal Ruby library provides seamless integration with the DocuSeal API, allowing developers to interact with DocuSeal's electronic signature and document management features directly within Ruby applications. This library is designed to simplify API interactions and provide tools for efficient implementation.
 
-[![Tests](https://github.com/moraki-finance/docuseal/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/moraki-finance/docuseal/actions/workflows/main.yml)
+## Documentation
 
-A lightweight API connector for docuseal. Docuseal API docs: https://www.docuseal.co/docs/api
-
-:warning: The extracted API objects don't do input parameters validations. It's a simple faraday wrapper that allows you to send as many inputs as you want. The docuseal API might fail when passing a wrong set of parameters.
+Detailed documentation is available at [DocuSeal API Docs](https://www.docuseal.com/docs/api).
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+To install the library, run:
 
-    $ bundle add docuseal
+```sh
+gem install docuseal
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### Bundler
 
-    $ gem install docuseal
+Add the library to your Gemfile for projects using Bundler:
+
+```ruby
+gem 'docuseal'
+```
 
 ## Usage
 
-### Setup
+### Configuration
+
+Set up the library with your DocuSeal API key based on your deployment. Retrieve your API key from the appropriate location:
 
-You'll need to set the Docuseal API key in the configuration.
+#### Global Cloud
 
-```rb
-Docuseal.configure do |config|
-  config.api_key = "{DOCUSEAL_API_KEY}"
-end
+API keys for the global cloud can be obtained from your [Global DocuSeal Console](https://console.docuseal.com/api).
+
+```ruby
+require 'docuseal'
+
+Docuseal.key = 'your_api_key_here'
 ```
 
-You can also set some other configurations like:
+#### EU Cloud
+
+API keys for the EU cloud can be obtained from your [EU DocuSeal Console](https://console.docuseal.eu/api).
+
+```ruby
+require 'docuseal'
 
-```rb
-Docuseal.configure do |config|
-  config.api_key = "{DOCUSEAL_API_KEY}"
+Docuseal.key = 'your_api_key_here'
+Docuseal.url = 'https://api.docuseal.eu'
+```
+
+#### On-Premise
 
-  # Set the docuseal API request timeout, the default is 120 seconds
-  config.request_timeout = 20
+For on-premise installations, API keys can be retrieved from the API settings page of your deployed application, e.g., https://yourdocusealapp.com/settings/api.
 
-  # Set extra headers that will get attached to every docuseal api request.
-  # Useful for observability tools like Helicone: https://www.helicone.ai/
-  config.global_headers = {
-    "Helicone-Auth": "Bearer HELICONE_API_KEY"
-    "helicone-stream-force-format" => "true",
-  }
+```ruby
+require 'docuseal'
 
-  # Set the base_uri to use the docuseal EU servers if you're account was registered there.
-  # The default is https://api.docuseal.co/
-  config.base_uri = "https://api.docuseal.eu/"
-end
+Docuseal.key = 'your_api_key_here'
+Docuseal.url = 'https://yourdocusealapp.com/api'
 ```
 
-### Submissions
+## API Methods
+
+### list_submissions(params)
 
-#### List
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#list-all-submissions)
 
-Reference: https://www.docuseal.co/docs/api#list-all-submissions
+Provides the ability to retrieve a list of available submissions.
 
-```rb
-submissions = Docuseal::Submission.list
+
+```ruby
+Docuseal.list_submissions(limit: 10)
 ```
 
-#### Find
+### get_submission(id)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#get-a-submission)
 
-Reference: https://www.docuseal.co/docs/api#get-a-submission
+Provides the functionality to retrieve information about a submission.
 
-```rb
-submission = Docuseal::Submission.find(1)
+
+```ruby
+Docuseal.get_submission(1001)
 ```
 
-#### Create
+### create_submission(data)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#create-a-submission)
+
+This API endpoint allows you to create signature requests (submissions) for a document template and send them to the specified submitters (signers).
+
+**Related Guides:**<br>
+[Send documents for signature via API](https://www.docuseal.com/guides/send-documents-for-signature-via-api)
+[Pre-fill PDF document form fields with API](https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api)
 
-Reference: https://www.docuseal.co/docs/api#create-a-submission
 
-```rb
-submission = Docuseal::Submission.create(
+```ruby
+Docuseal.create_submission({
   template_id: 1000001,
   send_email: true,
-  submitters: [{role: 'First Party', email: 'john.doe@example.com'}]
-)
+  submitters: [
+    {
+      role: "First Party",
+      email: "john.doe@example.com"
+    }
+  ]
+})
 ```
 
-#### Create From Email
+### create_submission_from_emails(data)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#create-submissions-from-emails)
+
+This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools.
 
-Reference: https://www.docuseal.co/docs/api#create-submissions-from-emails
 
-```rb
-submission = Docuseal::Submission.create(
-  from: :emails,
+```ruby
+Docuseal.create_submission_from_emails({
   template_id: 1000001,
-  emails: 'hi@docuseal.co, example@docuseal.co'
-)
+  emails: "hi@docuseal.com, example@docuseal.com"
+})
 ```
 
-#### Archive
+### archive_submission(id)
 
-Reference: https://www.docuseal.co/docs/api#archive-a-submission
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#archive-a-submission)
 
-```rb
-submission = Docuseal::Submission.archive(1)
+Allows you to archive a submission.
+
+
+```ruby
+Docuseal.archive_submission(1001)
 ```
 
-### Submitters
+### list_submitters(params)
 
-#### List
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#list-all-submitters)
 
-Reference: https://www.docuseal.co/docs/api#list-all-submitters
+Provides the ability to retrieve a list of submitters.
 
-```rb
-submitters = Docuseal::Submitter.list
+
+```ruby
+Docuseal.list_submitters(limit: 10)
 ```
 
-#### Find
+### get_submitter(id)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#get-a-submitter)
+
+Provides the functionality to retrieve information about a submitter.
+
+
+```ruby
+Docuseal.get_submitter(500001)
+```
+
+### update_submitter(id, data)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#update-a-submitter)
+
+Provides allows you to update submitter details, pre-fill or update field values and re-send emails.
+
+**Related Guides:**<br>
+[Automatically sign documents via API](https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api#automatically_sign_documents_via_api)
 
-Reference: https://www.docuseal.co/docs/api#get-a-submitter
 
-```rb
-submitter = Docuseal::Submitter.find(1)
+```ruby
+Docuseal.update_submitter(500001, {
+  email: "john.doe@example.com",
+  fields: [
+    {
+      name: "First Name",
+      default_value: "Acme"
+    }
+  ]
+})
 ```
 
-#### Update
+### list_templates(params)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#list-all-templates)
+
+Provides the ability to retrieve a list of available document templates.
 
-Reference: https://www.docuseal.co/docs/api#update-a-submitter
 
-```rb
-submitter = Docuseal::Submitter.update(1,
-  email: 'john.doe@example.com',
-  fields: [{name: 'First Name', default_value: 'Acme'}]
-)
+```ruby
+Docuseal.list_templates(limit: 10)
 ```
 
-### Templates
+### get_template(id)
 
-#### List
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#get-a-template)
 
-Reference: https://www.docuseal.co/docs/api#list-all-templates
+Provides the functionality to retrieve information about a document template.
 
-```rb
-templates = Docuseal::Template.list
+
+```ruby
+Docuseal.get_template(1000001)
 ```
 
-#### Find
+### create_template_from_docx(data)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#create-a-template-from-word-docx)
+
+Provides the functionality to create a fillable document template for existing Microsoft Word document. Use `{{Field Name;role=Signer1;type=date}}` text tags to define fillable fields in the document. See [https://www.docuseal.com/examples/fieldtags.docx](https://www.docuseal.com/examples/fieldtags.docx) for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
+
+**Related Guides:**<br>
+[Use embedded text field tags to create a fillable form](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form)
 
-Reference: https://www.docuseal.co/docs/api#get-a-template
 
-```rb
-template = Docuseal::Template.find(1)
+```ruby
+Docuseal.create_template_from_docx({
+  name: "Test DOCX",
+  documents: [
+    {
+      name: "string",
+      file: "base64"
+    }
+  ]
+})
 ```
 
-#### Create From DOCX
+### create_template_from_html(data)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#create-a-template-from-html)
 
-Reference: https://www.docuseal.co/docs/api#create-a-template-from-word-docx
+Provides the functionality to seamlessly generate a PDF document template by utilizing the provided HTML content while incorporating pre-defined fields.
 
-```rb
-template = Docuseal::Template.create(
-  from: :docx,
-  name: 'Demo DOCX',
-  documents: [{ name: 'Demo DOCX', file: 'base64' }]
-)
+**Related Guides:**<br>
+[Create PDF document fillable form with HTML](https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api)
+
+
+```ruby
+Docuseal.create_template_from_html({
+  html: "<p>Lorem Ipsum is simply dummy text of the
+<text-field
+  name=\"Industry\"
+  role=\"First Party\"
+  required=\"false\"
+  style=\"width: 80px; height: 16px; display: inline-block; margin-bottom: -4px\">
+</text-field>
+and typesetting industry</p>
+",
+  name: "Test Template"
+})
 ```
 
-#### Create From HTML
+### merge_templates(data)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#merge-templates)
+
+Allows you to merge multiple templates with documents and fields into a new combined template.
 
-Reference: https://www.docuseal.co/docs/api#create-a-template-from-html
 
-```rb
-template = Docuseal::Template.create(
-  from: :html,
-  html: '<p>Lorem Ipsum is simply dummy text of the\n<text-field\n  name="Industry"\n  role="First Party"\n  required="false"\n  style="width: 80px; height: 16px; display: inline-block; margin-bottom: -4px">\n</text-field>\nand typesetting industry</p>\n',
-  name: 'Test Template'
-)
+```ruby
+Docuseal.merge_templates({
+  template_ids: [
+    321,
+    432
+  ],
+  name: "Merged Template"
+})
 ```
 
-#### Create From PDF
+### create_template_from_pdf(data)
 
-Reference: https://www.docuseal.co/docs/api#create-a-template-from-existing-pdf
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#create-a-template-from-existing-pdf)
 
-```rb
-template = Docuseal::Template.create(
-  from: :pdf,
-  name: 'Test PDF',
+Provides the functionality to create a fillable document template for existing PDF file. Use `{{Field Name;role=Signer1;type=date}}` text tags to define fillable fields in the document. See [https://www.docuseal.com/examples/fieldtags.pdf](https://www.docuseal.com/examples/fieldtags.pdf) for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
+
+**Related Guides:**<br>
+[Use embedded text field tags to create a fillable form](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form)
+
+
+```ruby
+Docuseal.create_template_from_pdf({
+  name: "Test PDF",
   documents: [
     {
-      name: 'string',
-      file: 'base64',
-      fields: [{name: 'string', areas: [{x: 0, y: 0, w: 0, h: 0, page: 0}]}]
+      name: "string",
+      file: "base64",
+      fields: [
+        {
+          name: "string",
+          areas: [
+            {
+              x: 0,
+              y: 0,
+              w: 0,
+              h: 0,
+              page: 1
+            }
+          ]
+        }
+      ]
     }
   ]
-)
+})
 ```
 
-#### Clone
+### clone_template(id, data)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#clone-a-template)
+
+Allows you to clone existing template into a new template.
 
-Reference: https://www.docuseal.co/docs/api#clone-a-template
 
-```rb
-template = Docuseal::Template.clone(1,
-  name: 'Clone of Test',
-)
+```ruby
+Docuseal.clone_template(1000001, {
+  name: "Cloned Template"
+})
 ```
 
-#### Update
+### update_template(id, data)
 
-Reference: https://www.docuseal.co/docs/api#update-a-template
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#update-a-template)
 
-```rb
-template = Docuseal::Template.update(1,
-  name: 'New Document Name',
-  folder_name: 'New Folder'
-)
+Provides the functionality to move a document template to a different folder and update the name of the template.
+
+
+```ruby
+Docuseal.update_template(1000001, {
+  name: "New Document Name",
+  folder_name: "New Folder"
+})
 ```
 
-#### Update Documents
+### update_template_documents(id, data)
+
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#update-template-documents)
+
+Allows you to add, remove or replace documents in the template with provided PDF/DOCX file or HTML content.
 
-Reference: https://www.docuseal.co/docs/api#update-template-documents
 
-```rb
-template = Docuseal::Template.update_documents(1,
-  documents: [{file: 'base64'}]
-)
+```ruby
+Docuseal.update_template_documents(1000001, {
+  documents: [
+    {
+      file: "string"
+    }
+  ]
+})
 ```
 
-#### Archive
+### archive_template(id)
 
-Reference: https://www.docuseal.co/docs/api#archive-a-template
+[Documentation](https://www.docuseal.com/docs/api?lang=ruby#archive-a-template)
 
-```rb
-template = Docuseal::Template.archive(1)
+Allows you to archive a document template.
+
+
+```ruby
+Docuseal.archive_template(1000001)
 ```
 
-## Development
+### Configuring Timeouts
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment:
+Set timeouts to avoid hanging requests:
 
-```bash
-$ DOCUSEAL_API_KEY={YOUR API KEY} DOCUSEAL_BASE_URI={YOUR BASE URI} bin/console
+```ruby
+Docuseal.open_timeout = 70
+Docuseal.read_timeout = 90
 ```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Support
 
-## Contributing
+For feature requests or bug reports, visit our [GitHub Issues page](https://github.com/docusealco/docuseal-ruby/issues).
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/moraki-finance/docuseal. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/moraki-finance/docuseal/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Docuseal project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/docuseal/blob/main/CODE_OF_CONDUCT.md).

data/lib/docuseal/api.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Docuseal
+  class Api
+    Error = Class.new(StandardError)
+
+    attr_reader :http
+
+    def initialize(config)
+      @http = Http.new(config)
+    end
+
+    def list_templates(params = {})
+      http.get('/templates', params)
+    end
+
+    def get_template(id, params = {})
+      http.get("/templates/#{id}", params)
+    end
+
+    def create_template_from_docx(data)
+      http.post('/templates/docx', data)
+    end
+
+    def create_template_from_html(data)
+      http.post('/templates/html', data)
+    end
+
+    def create_template_from_pdf(data)
+      http.post('/templates/pdf', data)
+    end
+
+    def merge_templates(data)
+      http.post('/templates/merge', data)
+    end
+
+    def clone_template(id, data)
+      http.post("/templates/#{id}/clone", data)
+    end
+
+    def update_template(id, data)
+      http.put("/templates/#{id}", data)
+    end
+
+    def update_template_documents(id, data)
+      http.put("/templates/#{id}/documents", data)
+    end
+
+    def archive_template(id)
+      http.delete("/templates/#{id}")
+    end
+
+    def permanently_delete_template(id)
+      http.delete("/templates/#{id}", { permanently: true })
+    end
+
+    def list_submissions(params = {})
+      http.get('/submissions', params)
+    end
+
+    def get_submission(id, params = {})
+      http.get("/submissions/#{id}", params)
+    end
+
+    def create_submission(data)
+      http.post('/submissions/init', data)
+    end
+
+    def create_submission_from_emails(data)
+      http.post('/submissions/emails', data)
+    end
+
+    def archive_submission(id)
+      http.delete("/submissions/#{id}")
+    end
+
+    def permanently_delete_submission(id)
+      http.delete("/submissions/#{id}", { permanently: true })
+    end
+
+    def list_submitters(params = {})
+      http.get('/submitters', params)
+    end
+
+    def get_submitter(id, params = {})
+      http.get("/submitters/#{id}", params)
+    end
+
+    def update_submitter(id, data)
+      http.put("/submitters/#{id}", data)
+    end
+  end
+end