hellosign.go

package hellosign

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"reflect"
	"strconv"
	"strings"
)

const (
	baseURL string = "https://api.hellosign.com/v3/"
)

// Client contains APIKey and optional http.client
type Client struct {
	APIKey     string
	ClientID   string
	BaseURL    string
	HTTPClient *http.Client
}

// CreationRequest contains the request parameters for create_embedded
type CreationRequest struct {
	TestMode              bool                  `form_field:"test_mode"`
	ClientID              string                `form_field:"client_id"`
	FileURL               []string              `form_field:"file_url"`
	File                  []string              `form_field:"file"`
	Title                 string                `form_field:"title"`
	Subject               string                `form_field:"subject"`
	Message               string                `form_field:"message"`
	SigningRedirectURL    string                `form_field:"signing_redirect_url"`
	Signers               []Signer              `form_field:"signers"`
	Attachments           []Attachment          `form_field:"attachments"`
	CustomFields          []CustomField         `form_field:"custom_fields"`
	CCEmailAddresses      []string              `form_field:"cc_email_addresses"`
	UseTextTags           bool                  `form_field:"use_text_tags"`
	HideTextTags          bool                  `form_field:"hide_text_tags"`
	Metadata              map[string]string     `form_field:"metadata"`
	AllowDecline          bool                  `form_field:"allow_decline"`
	AllowReassign         bool                  `form_field:"allow_reassign"`
	FormFieldsPerDocument [][]DocumentFormField `form_field:"form_fields_per_document"`
	// FieldOptions map[string]string `form_field:"field_options"``
}

type Signer struct {
	Name  string `field:"name"`
	Email string `field:"email_address"`
	Order int    `field:"order"`
	Pin   string `field:"pin"`
}

type DocumentFormField struct {
	APIId    string `json:"api_id"`
	Name     string `json:"name"`
	Type     string `json:"type"`
	X        int    `json:"x"`
	Y        int    `json:"y"`
	Width    int    `json:"width"`
	Height   int    `json:"height"`
	Required bool   `json:"required"`
	Signer   int    `json:"signer"`
}

type Attachment struct {
	Name         string `field:"name"`
	Instructions string `field:"instructions"`
	SignerIndex  int    `field:"signer_index"`
	Required     bool   `field:"required"`
}

type SignatureRequestResponse struct {
	SignatureRequest *SignatureRequest `json:"signature_request"`
}

type SignatureRequest struct {
	TestMode              bool                     `json:"test_mode"`               // Whether this is a test signature request. Test requests have no legal value. Defaults to 0.
	SignatureRequestID    string                   `json:"signature_request_id"`    // The id of the SignatureRequest.
	RequesterEmailAddress string                   `json:"requester_email_address"` // The email address of the initiator of the SignatureRequest.
	Title                 string                   `json:"title"`                   // The title the specified Account uses for the SignatureRequest.
	OriginalTitle         string                   `json:"original_title"`          // Default Label for account.
	Subject               string                   `json:"subject"`                 // The subject in the email that was initially sent to the signers.
	Message               string                   `json:"message"`                 // The custom message in the email that was initially sent to the signers.
	Metadata              map[string]interface{}   `json:"metadata"`                // The metadata attached to the signature request.
	CreatedAt             int                      `json:"created_at"`              // Time the signature request was created.
	IsComplete            bool                     `json:"is_complete"`             // Whether or not the SignatureRequest has been fully executed by all signers.
	IsDeclined            bool                     `json:"is_declined"`             // Whether or not the SignatureRequest has been declined by a signer.
	HasError              bool                     `json:"has_error"`               // Whether or not an error occurred (either during the creation of the SignatureRequest or during one of the signings).
	FilesURL              string                   `json:"files_url"`               // The URL where a copy of the request's documents can be downloaded.
	SigningURL            string                   `json:"signing_url"`             // The URL where a signer, after authenticating, can sign the documents. This should only be used by users with existing HelloSign accounts as they will be required to log in before signing.
	DetailsURL            string                   `json:"details_url"`             // The URL where the requester and the signers can view the current status of the SignatureRequest.
	CCEmailAddress        []*string                `json:"cc_email_addresses"`      // A list of email addresses that were CCed on the SignatureRequest. They will receive a copy of the final PDF once all the signers have signed.
	SigningRedirectURL    string                   `json:"signing_redirect_url"`    // The URL you want the signer redirected to after they successfully sign.
	CustomFields          []map[string]interface{} `json:"custom_fields"`           // An array of Custom Field objects containing the name and type of each custom field.
	ResponseData          []*ResponseData          `json:"response_data"`           // An array of form field objects containing the name, value, and type of each textbox or checkmark field filled in by the signers.
	Signatures            []*Signature             `json:"signatures"`              // An array of signature objects, 1 for each signer.
	Warnings              []*Warning               `json:"warnings"`                // An array of warning objects.
}

type CustomField struct {
	Name     string      `json:"name"`     // The name of the Custom Field.
	Type     string      `json:"type"`     // The type of this Custom Field. Only 'text' and 'checkbox' are currently supported.
	Value    interface{} `json:"value"`    // A text string for text fields or true/false for checkbox fields
	Required bool        `json:"required"` // A boolean value denoting if this field is required.
	ApiID    string      `json:"api_id"`   // The unique ID for this field.
	Editor   *string     `json:"editor"`   // The name of the Role that is able to edit this field.
}

type ResponseData struct {
	ApiID       string `json:"api_id"`       // The unique ID for this field.
	SignatureID string `json:"signature_id"` // The ID of the signature to which this response is linked.
	Name        string `json:"name"`         // The name of the form field.
	Value       string `json:"value"`        // The value of the form field.
	Required    bool   `json:"required"`     // A boolean value denoting if this field is required.
	Type        string `json:"type"`         // The type of this form field. See field types
}

type Signature struct {
	SignatureID        string  `json:"signature_id"`         // Signature identifier.
	SignerEmailAddress string  `json:"signer_email_address"` // The email address of the signer.
	SignerName         string  `json:"signer_name"`          // The name of the signer.
	Order              int     `json:"order"`                // If signer order is assigned this is the 0-based index for this signer.
	StatusCode         string  `json:"status_code"`          // The current status of the signature. eg: awaiting_signature, signed, declined
	DeclineReason      string  `json:"decline_reason"`       // The reason provided by the signer for declining the request.
	SignedAt           int     `json:"signed_at"`            // Time that the document was signed or null.
	LastViewedAt       int     `json:"last_viewed_at"`       // The time that the document was last viewed by this signer or null.
	LastRemindedAt     int     `json:"last_reminded_at"`     // The time the last reminder email was sent to the signer or null.
	HasPin             bool    `json:"has_pin"`              // Boolean to indicate whether this signature requires a PIN to access.
	ReassignedBy       string  `json:"reassigned_by"`        // Email address of original signer who reassigned to this signer.
	ReassignmentReason string  `json:"reassignment_reason"`  // Reason provided by original signer who reassigned to this signer.
	Error              *string `json:"error"`                // Error message pertaining to this signer, or null.
}

type Warning struct {
	Message string `json:"warning_msg"`
	Name    string `json:"warning_name"`
}

type ListResponse struct {
	ListInfo          *ListInfo           `json:"list_info"`
	SignatureRequests []*SignatureRequest `json:"signature_requests"`
}

type ListInfo struct {
	NumPages   int `json:"num_pages"`   // Total number of pages available
	NumResults int `json:"num_results"` // Total number of objects available
	Page       int `json:"page"`        // Number of the page being returned
	PageSize   int `json:"page_size"`   // Objects returned per page
}

type DataUriResponse struct {
	DataUri string `json:"data_uri"`
}

type FileResponse struct {
	FileUrl   string `json:"file_url"`
	ExpiresAt int    `json:"expires_at"`
}

type ErrorResponse struct {
	Error    *Error    `json:"error"`
	Warnings []Warning `json:"warnings"`
}

type Error struct {
	Message string `json:"error_msg"`
	Name    string `json:"error_name"`
}

type EmbeddedResponse struct {
	Embedded *SignURLResponse `json:"embedded"`
}

type SignURLResponse struct {
	SignURL   string `json:"sign_url"`   // URL of the signature page to display in the embedded iFrame.
	ExpiresAt int    `json:"expires_at"` // When the link expires.
}

func (m *Client) WithHTTPClient(httpClient *http.Client) *Client {
	m.HTTPClient = httpClient

	return m
}

// CreateEmbeddedSignatureRequest creates a new embedded signature
func (m *Client) createSignatureRequest(ctx context.Context, path string, request CreationRequest) (*SignatureRequest, error) {
	params, writer, err := m.marshalMultipartRequest(request)
	if err != nil {
		return nil, err
	}

	response, err := m.post(ctx, path, params, *writer)
	if err != nil {
		return nil, err
	}

	return m.sendSignatureRequest(response)
}

// CreateSignatureRequest creates non-embedded signature request.
func (m *Client) CreateSignatureRequest(ctx context.Context, request CreationRequest) (*SignatureRequest, error) {
	return m.createSignatureRequest(ctx, "signature_request/send", request)
}

// CreateEmbeddedSignatureRequest creates a new embedded signature
func (m *Client) CreateEmbeddedSignatureRequest(ctx context.Context, request CreationRequest) (*SignatureRequest, error) {
	return m.createSignatureRequest(ctx, "signature_request/create_embedded", request)
}

// GetSignatureRequest - Gets a SignatureRequest that includes the current status for each signer.
func (m *Client) GetSignatureRequest(ctx context.Context, signatureRequestID string) (*SignatureRequest, error) {
	path := fmt.Sprintf("signature_request/%s", signatureRequestID)
	response, err := m.get(ctx, path)
	if err != nil {
		return nil, err
	}
	return m.sendSignatureRequest(response)
}

// GetEmbeddedSignURL - Retrieves an embedded signing object.
func (m *Client) GetEmbeddedSignURL(ctx context.Context, signatureRequestID string) (*SignURLResponse, error) {
	path := fmt.Sprintf("embedded/sign_url/%s", signatureRequestID)
	response, err := m.get(ctx, path)
	if err != nil {
		return nil, err
	}

	data := &EmbeddedResponse{}
	err = json.NewDecoder(response.Body).Decode(data)
	if err != nil {
		return nil, err
	}

	return data.Embedded, nil
}

func (m *Client) SaveFile(ctx context.Context, signatureRequestID, fileType, destFilePath string) (os.FileInfo, error) {
	byteArray, err := m.GetFiles(ctx, signatureRequestID, fileType)

	out, err := os.Create(destFilePath)
	if err != nil {
		return nil, err
	}
	_, _ = out.Write(byteArray)
	_ = out.Close()

	info, err := os.Stat(destFilePath)
	if err != nil {
		return nil, err
	}
	return info, nil
}

// GetPDF - Obtain a copy of the current pdf specified by the signature_request_id parameter.
func (m *Client) GetPDF(ctx context.Context, signatureRequestID string) ([]byte, error) {
	return m.GetFiles(ctx, signatureRequestID, "pdf")
}

// GetFiles - Obtain a copy of the current documents specified by the signature_request_id parameter.
// signatureRequestID - The id of the SignatureRequest to retrieve.
// fileType - Set to "pdf" for a single merged document or "zip" for a collection of individual documents.
func (m *Client) GetFiles(ctx context.Context, signatureRequestID, fileType string) ([]byte, error) {
	path := fmt.Sprintf("signature_request/files/%s", signatureRequestID)

	var params bytes.Buffer
	writer := multipart.NewWriter(&params)

	signatureIDField, err := writer.CreateFormField("file_type")
	if err != nil {
		return nil, err
	}
	signatureIDField.Write([]byte(fileType))

	emailField, err := writer.CreateFormField("get_url")
	if err != nil {
		return nil, err
	}
	emailField.Write([]byte("false"))

	response, err := m.request(ctx, "GET", path, &params, *writer)
	if err != nil {
		return nil, err
	}

	defer response.Body.Close()

	data, err := io.ReadAll(response.Body)
	if err != nil {
		return nil, err
	}

	return data, nil
}

// GetFilesAsDataURI - Obtain a copy of the current documents specified by the signature_request_id parameter.
// Returns a JSON object with a data_uri representing the base64 encoded file (PDFs only).
func (m *Client) GetFilesAsDataURI(ctx context.Context, signatureRequestID string) (DataUriResponse, error) {
	path := fmt.Sprintf("signature_request/files_as_data_uri/%s", signatureRequestID)

	var params bytes.Buffer
	writer := multipart.NewWriter(&params)

	response, err := m.request(ctx, "GET", path, &params, *writer)
	if err != nil {
		return DataUriResponse{}, err
	}

	defer response.Body.Close()

	dataResponse := DataUriResponse{}
	err = json.NewDecoder(response.Body).Decode(&dataResponse)
	if err != nil {
		return DataUriResponse{}, err
	}

	return dataResponse, err
}

// GetFilesAsFileURL - Obtain a copy of the current documents specified by the signature_request_id parameter.
// Returns a JSON object with a url to the file (PDFs only).
func (m *Client) GetFilesAsFileURL(ctx context.Context, signatureRequestID string) (FileResponse, error) {
	path := fmt.Sprintf("signature_request/files_as_file_url/%s", signatureRequestID)

	var params bytes.Buffer
	writer := multipart.NewWriter(&params)

	response, err := m.request(ctx, "GET", path, &params, *writer)
	if err != nil {
		return FileResponse{}, err
	}

	defer response.Body.Close()

	fileResponse := FileResponse{}
	err = json.NewDecoder(response.Body).Decode(&fileResponse)
	if err != nil {
		return FileResponse{}, err
	}

	return fileResponse, err
}

// ListSignatureRequests - Lists the SignatureRequests (both inbound and outbound) that you have access to.
func (m *Client) ListSignatureRequests(ctx context.Context) (*ListResponse, error) {
	path := fmt.Sprintf("signature_request/list")
	response, err := m.get(ctx, path)
	if err != nil {
		return nil, err
	}

	defer response.Body.Close()

	listResponse := &ListResponse{}
	err = json.NewDecoder(response.Body).Decode(listResponse)
	if err != nil {
		return nil, err
	}

	return listResponse, err
}

// UpdateSignatureRequest - Update an email address on a signature request.
func (m *Client) UpdateSignatureRequest(ctx context.Context, signatureRequestID string, signatureID string, email string) (*SignatureRequest, error) {
	path := fmt.Sprintf("signature_request/update/%s", signatureRequestID)

	var params bytes.Buffer
	writer := multipart.NewWriter(&params)

	signatureIDField, err := writer.CreateFormField("signature_id")
	if err != nil {
		return nil, err
	}
	signatureIDField.Write([]byte(signatureID))

	emailField, err := writer.CreateFormField("email_address")
	if err != nil {
		return nil, err
	}
	emailField.Write([]byte(email))

	response, err := m.post(ctx, path, &params, *writer)
	if err != nil {
		return nil, err
	}

	return m.sendSignatureRequest(response)
}

// CancelSignatureRequest - Cancels an incomplete signature request. This action is not reversible.
func (m *Client) CancelSignatureRequest(ctx context.Context, signatureRequestID string) (*http.Response, error) {
	path := fmt.Sprintf("signature_request/cancel/%s", signatureRequestID)

	response, err := m.nakedPost(ctx, path)
	if err != nil {
		return nil, err
	}

	return response, err
}

// RemoveSignatureRequestAccess - Removes your access to a completed signature request.
func (m *Client) RemoveSignatureRequestAccess(ctx context.Context, signatureRequestID string) (*http.Response, error) {
	path := fmt.Sprintf("signature_request/remove/%s", signatureRequestID)

	response, err := m.nakedPost(ctx, path)
	if err != nil {
		return nil, err
	}

	return response, err
}

// Private Methods

func (m *Client) marshalMultipartRequest(
	request CreationRequest) (*bytes.Buffer, *multipart.Writer, error) {

	var b bytes.Buffer
	w := multipart.NewWriter(&b)

	structType := reflect.TypeOf(request)
	val := reflect.ValueOf(request)

	for i := 0; i < val.NumField(); i++ {

		valueField := val.Field(i)
		f := valueField.Interface()
		val := reflect.ValueOf(f)
		field := structType.Field(i)
		fieldTag := field.Tag.Get("form_field")

		switch val.Kind() {
		case reflect.Map:
			for k, v := range request.Metadata {
				formField, err := w.CreateFormField(fmt.Sprintf("metadata[%v]", k))
				if err != nil {
					return nil, nil, err
				}
				formField.Write([]byte(v))
			}
		case reflect.Slice:
			switch fieldTag {
			case "signers":
				for i, signer := range request.Signers {
					email, err := w.CreateFormField(fmt.Sprintf("signers[%v][email_address]", i))
					if err != nil {
						return nil, nil, err
					}
					email.Write([]byte(signer.Email))

					name, err := w.CreateFormField(fmt.Sprintf("signers[%v][name]", i))
					if err != nil {
						return nil, nil, err
					}
					name.Write([]byte(signer.Name))

					if signer.Order != 0 {
						order, err := w.CreateFormField(fmt.Sprintf("signers[%v][order]", i))
						if err != nil {
							return nil, nil, err
						}
						order.Write([]byte(strconv.Itoa(signer.Order)))
					}

					if signer.Pin != "" {
						pin, err := w.CreateFormField(fmt.Sprintf("signers[%v][pin]", i))
						if err != nil {
							return nil, nil, err
						}
						pin.Write([]byte(signer.Pin))
					}
				}
			case "attachments":
				for i, attachment := range request.Attachments {

					if attachment.Name != "" {
						name, err := w.CreateFormField(fmt.Sprintf("attachments[%v][name]", i))
						if err != nil {
							return nil, nil, err
						}
						name.Write([]byte(attachment.Name))
					}
					if attachment.Instructions != "" {
						text, err := w.CreateFormField(fmt.Sprintf("attachments[%v][instructions]", i))
						if err != nil {
							return nil, nil, err
						}
						text.Write([]byte(attachment.Instructions))
					}

					order, err := w.CreateFormField(fmt.Sprintf("attachments[%v][signer_index]", i))
					if err != nil {
						return nil, nil, err
					}
					order.Write([]byte(strconv.Itoa(attachment.SignerIndex)))

					if attachment.Required {
						required, err := w.CreateFormField(fmt.Sprintf("attachments[%v][required]", i))
						if err != nil {
							return nil, nil, err
						}
						required.Write([]byte(strconv.Itoa(1)))
					}
				}

			case "cc_email_addresses":
				for k, v := range request.CCEmailAddresses {
					formField, err := w.CreateFormField(fmt.Sprintf("cc_email_addresses[%v]", k))
					if err != nil {
						return nil, nil, err
					}
					formField.Write([]byte(v))
				}
			case "form_fields_per_document":
				if len(request.FormFieldsPerDocument) > 0 {
					formField, err := w.CreateFormField(fieldTag)
					if err != nil {
						return nil, nil, err
					}
					ffpdJSON, err := json.Marshal(request.FormFieldsPerDocument)
					if err != nil {
						return nil, nil, err
					}
					formField.Write([]byte(ffpdJSON))
				}
			case "file":
				for i, path := range request.File {
					file, _ := os.Open(path)

					formField, err := w.CreateFormFile(fmt.Sprintf("file[%v]", i), file.Name())
					if err != nil {
						return nil, nil, err
					}
					_, err = io.Copy(formField, file)
				}
			case "file_url":
				for i, fileURL := range request.FileURL {
					formField, err := w.CreateFormField(fmt.Sprintf("file_url[%v]", i))
					if err != nil {
						return nil, nil, err
					}
					formField.Write([]byte(fileURL))
				}
			}
		case reflect.Bool:
			formField, err := w.CreateFormField(fieldTag)
			if err != nil {
				return nil, nil, err
			}
			formField.Write([]byte(m.boolToIntString(val.Bool())))
		default:
			if val.String() != "" {
				formField, err := w.CreateFormField(fieldTag)
				if err != nil {
					return nil, nil, err
				}
				formField.Write([]byte(val.String()))
			}
		}
	}

	w.Close()
	return &b, w, nil
}

func (m *Client) get(ctx context.Context, path string) (*http.Response, error) {
	endpoint := fmt.Sprintf("%s%s", m.getEndpoint(), path)

	var b bytes.Buffer
	request, _ := http.NewRequestWithContext(ctx, "GET", endpoint, &b)
	request.SetBasicAuth(m.APIKey, "")

	response, err := m.getHTTPClient().Do(request)
	if err != nil {
		return nil, err
	}

	return response, err
}

func (m *Client) post(ctx context.Context, path string, params *bytes.Buffer, w multipart.Writer) (*http.Response, error) {
	return m.request(ctx, "POST", path, params, w)
}

func (m *Client) request(ctx context.Context, method string, path string, params *bytes.Buffer, w multipart.Writer) (*http.Response, error) {
	endpoint := fmt.Sprintf("%s%s", m.getEndpoint(), path)
	request, _ := http.NewRequestWithContext(ctx, method, endpoint, params)
	request.Header.Add("Content-Type", w.FormDataContentType())
	request.SetBasicAuth(m.APIKey, "")

	response, err := m.getHTTPClient().Do(request)
	if err != nil {
		return nil, err
	}

	if response.StatusCode >= 400 {
		msg := fmt.Sprintf("hellosign request failed with status %d", response.StatusCode)
		e := &ErrorResponse{}
		json.NewDecoder(response.Body).Decode(e)
		if e.Error != nil {
			msg = fmt.Sprintf("%s: %s", e.Error.Name, e.Error.Message)
		} else {
			messages := []string{}
			for _, w := range e.Warnings {
				messages = append(messages, fmt.Sprintf("%s: %s", w.Name, w.Message))
			}
			msg = strings.Join(messages, ", ")
		}

		return response, errors.New(msg)
	}

	return response, err
}

func (m *Client) nakedPost(ctx context.Context, path string) (*http.Response, error) {
	endpoint := fmt.Sprintf("%s%s", m.getEndpoint(), path)
	var b bytes.Buffer
	request, _ := http.NewRequestWithContext(ctx, "POST", endpoint, &b)
	request.SetBasicAuth(m.APIKey, "")

	response, err := m.getHTTPClient().Do(request)
	if err != nil {
		return nil, err
	}
	return response, err
}

func (m *Client) sendSignatureRequest(response *http.Response) (*SignatureRequest, error) {
	defer response.Body.Close()

	sigRequestResponse := &SignatureRequestResponse{}

	err := json.NewDecoder(response.Body).Decode(sigRequestResponse)

	sigRequest := sigRequestResponse.SignatureRequest

	return sigRequest, err
}

func (m *Client) getEndpoint() string {
	var url string
	if m.BaseURL != "" {
		url = m.BaseURL
	} else {
		url = baseURL
	}
	return url
}

func (m *Client) getHTTPClient() *http.Client {
	var httpClient *http.Client
	if m.HTTPClient != nil {
		httpClient = m.HTTPClient
	} else {
		httpClient = &http.Client{}
	}
	return httpClient
}

func (m *Client) boolToIntString(value bool) string {
	if value == true {
		return "1"
	}
	return "0"
}