@verdocs/js-sdk 4.2.136 → 4.2.148

package/dist/index.mjs

@@ -885,6 +885,11 @@ var globalThis$1 = /*@__PURE__*/getDefaultExportFromCjs(globalThis_1);
  * const {access_token} = await Auth.authenticate({ client_id: '...', client_secret: '...', grant_type:'client_credentials' });
  * VerdocsEndpoint.getDefault().setAuthToken(access_token);
  * ```
+ *
+ * @group Authentication
+ * @api POST /v2/oauth2/token Authenticate
+ * @apiBody string(format: 'uuid') id The ID of the envelope to retrieve.
+ * @apiSuccess IAuthenticateResponse . The detailed metadata for the envelope requested
  */
 const authenticate = (endpoint, params) => endpoint.api //
     .post('/v2/oauth2/token', params)
@@ -1502,18 +1507,42 @@ class VerdocsEndpoint {
  * const request: ICreateEnvelopeRequest = {template_id: 'd2338742-f3a1-465b-8592-806587413cc1', name: 'Bill of Sale', roles: [role1, role2]};
  * const {id, recipients} = await Envelopes.createEnvelope(VerdocsEndpoint.getDefault(), request);
  * ```
+ *
+ * @group Envelopes
+ * @api POST /v2/envelopes Create Envelope
+ * @apiBody string(format:uuid) template_id The template to base the new Envelope from
+ * @apiBody array(items:ICreateEnvelopeRecipient) recipients A list of recipients to include in the workflow. Must specify one recipient to match each template Role.
+ * @apiBody string name? Override the name of the envelope (defaults to the template name).
+ * @apiBody string description? Override the description of the envelope (defaults to the template description).
+ * @apiBody array(items:IEnvelopeField) fields? Provide default values for fields in the envelope. Note that only "name", "role_name", and "default" should be set in this array.
+ * @apiBody boolean no_contact? If set to true, no email or SMS messages will be sent to any recipients.
+ * @apiBody integer(min: 0) initial_reminder? Override the template initial-reminder setting.
+ * @apiBody integer(min: 0) followup_reminders? Override the template initial-reminder setting.
+ * @apiSuccess IEnvelope . The newly-created envelope.
  */
 const createEnvelope = async (endpoint, request) => endpoint.api //
     .post('/v2/envelopes', request)
     .then((r) => r.data);
 /**
- * Get all metadata for an Envelope.
+ * Get all metadata for an envelope. Note that when called by non-creators (e.g. Recipients)
+ * this will return only the **metadata** the caller is allowed to view.
+ *
+ * @group Envelopes
+ * @api GET /v2/envelopes/:id Get Envelope Details
+ * @apiParam string(format: 'uuid') id The ID of the envelope to retrieve.
+ * @apiSuccess IEnvelope . The detailed metadata for the envelope requested
  */
 const getEnvelope = async (endpoint, envelopeId) => endpoint.api //
     .get(`/v2/envelopes/${envelopeId}`)
     .then((r) => r.data);
 /**
- * Get an Envelope Document
+ * Get all metadata for an envelope document. Note that when called by non-creators (e.g. Recipients)
+ * this will return only the **metadata** the caller is allowed to view.
+ *
+ * @group Envelopes
+ * @api GET /envelopes/:id Get Envelope Details
+ * @apiParam string(format: 'uuid') id The ID of the document to retrieve.
+ * @apiSuccess IEnvelopeDocument . The detailed metadata for the document requested
  */
 const getEnvelopeDocument = async (endpoint, envelopeId, documentId) => endpoint.api //
     .get(`/envelopes/${envelopeId}/envelope_documents/${documentId}`)
@@ -1521,6 +1550,15 @@ const getEnvelopeDocument = async (endpoint, envelopeId, documentId) => endpoint
 /**
  * Get a pre-signed download link for an Envelope Document. This link expires quickly, so it should
  * be accessed immediately and never shared. Content-Disposition will be set to "download".
+ *
+ * @group Envelopes
+ * @api GET /envelopes/:envelope_id/envelope_documents/:document_id Preview, Download, or Link to a Document
+ * @apiParam string(format: 'uuid') envelope_id The ID of the envelope to retrieve.
+ * @apiParam string(format: 'uuid') document_id The ID of the document to retrieve.
+ * @apiQuery boolean download? Set to true to generate a download link (content-disposition: download).
+ * @apiQuery boolean preview? Set to true to generate a preview link (content-disposition: inline).
+ * @apiQuery boolean file? Set to true to return the raw binary BLOB data of the file rather than a link.
+ * @apiSuccess string . The generated link.
  */
 const getDocumentDownloadLink = async (endpoint, envelopeId, documentId) => endpoint.api //
     .get(`/envelopes/${envelopeId}/envelope_documents/${documentId}?download=true`)
@@ -1534,6 +1572,12 @@ const getDocumentPreviewLink = async (endpoint, envelopeId, documentId) => endpo
     .then((r) => r.data);
 /**
  * Cancel an Envelope.
+ *
+ * @group Envelopes
+ * @api PUT /v2/envelopes/:id Cancel envelope
+ * @apiParam string(format: 'uuid') id The ID of the envelope to cancel.
+ * @apiBody string(enum: 'cancel') action The action to perform (currently only "cancel" is supported).
+ * @apiSuccess IEnvelope . The updated envelope.
  */
 const cancelEnvelope = async (endpoint, envelopeId) => endpoint.api //
     .put(`/v2/envelopes/${envelopeId}`, { action: 'cancel' })
@@ -1548,32 +1592,68 @@ const getEnvelopeFile = async (endpoint, envelopeId, documentId) => endpoint.api
     .then((r) => r.data);
 /**
  * Update an envelope. Currently, only reminder settings may be changed.
+ *
+ * @group Envelopes
+ * @api PATCH /v2/envelopes/:id Update Envelope
+ * @apiParam string(format: 'uuid') id The ID of the envelope to update.
+ * @apiBody IEnvelope . Set of fields to update. Omit (leave undefined) any fields that should not be changed.
+ * @apiSuccess IEnvelope . A copy of the newly-updated envelope.
  */
 const updateEnvelope = async (endpoint, envelopeId, params) => endpoint.api //
     .patch(`/v2/envelopes/${envelopeId}`, params)
     .then((r) => r.data);
 /**
  * Update a Document field. Typically called during the signing process as a Recipient fills in fields.
+ *
+ * @group Envelopes
+ * @api PUT /envelopes/:envelope_id/fields/:field_name Update Envelope Field
+ * @apiParam string(format: 'uuid') envelope_id The ID of the envelope to retrieve.
+ * @apiParam string field_name The name of the field to update. Be sure to URL-encode the value.
+ * @apiBody IEnvelopeFieldSettings . Set of properties to update. Leave undefined any properties that should not be changed.
+ * @apiSuccess IEnvelope . A copy of the newly-updated field.
  */
 const updateEnvelopeField = async (endpoint, envelopeId, fieldName, value) => endpoint.api //
     .put(`/envelopes/${envelopeId}/fields/${fieldName}`, value)
     .then((r) => r.data);
 /**
- * Update a Document signature field. Signature fields are ID-driven. Call `Document.createSignature()` first to create a
- * signature for a Recipient, then call `Documents.updateDocumentFieldSignature()` to attach it to a field.
+ * Apply a signature to a signature field. Signature fields are ID-driven. Call `createSignature()`
+ * first to create a signature for a Recipient, then call `updateEnvelopeFieldSignature()` to
+ * attach it to a field.
+ *
+ * @group Envelopes
+ * @api PUT /envelopes/:envelope_id/fields/:field_name/signature/:signature_id Update Envelope
+ * @apiParam string(format: 'uuid') envelope_id The ID of the envelope to update.
+ * @apiParam string field_name The name of the field to update. Be sure to URL-encode the value.
+ * @apiParam string(format: 'uuid') signature_id The ID of the signature to attach.
+ * @apiSuccess IEnvelopeFieldSettings . A copy of the newly-updated field.
  */
 const updateEnvelopeFieldSignature = async (endpoint, envelopeId, fieldName, signatureId) => endpoint.api //
     .put(`/envelopes/${envelopeId}/fields/${fieldName}/signature/${signatureId}`)
     .then((r) => r.data);
 /**
- * Update a Document signature field. Signature fields are ID-driven. Call `Document.createSignature()` first to create a
- * signature for a Recipient, then call `Documents.updateDocumentFieldSignature()` to attach it to a field.
+ * Apply an initial to an initials field. Initial fields are ID-driven. Call `createInitial()`
+ * first to create an initial block for a Recipient, then call `supdateEnvelopeFieldInitials()` to
+ * attach it to a field.
+ *
+ * @group Envelopes
+ * @api PUT /envelopes/:envelope_id/fields/:field_name/initial/:initial_id Update Envelope
+ * @apiParam string(format: 'uuid') envelope_id The ID of the envelope to update.
+ * @apiParam string field_name The name of the field to update. Be sure to URL-encode the value.
+ * @apiParam string(format: 'uuid') initial_id The ID of the initial block to attach.
+ * @apiSuccess IEnvelopeFieldSettings . A copy of the newly-updated field.
  */
 const updateEnvelopeFieldInitials = async (endpoint, envelopeId, fieldName, initialId) => endpoint.api //
     .put(`/envelopes/${envelopeId}/fields/${fieldName}/initial/${initialId}`)
     .then((r) => r.data);
 /**
- * Upload an attachment.
+ * Upload an attachment to an attachment field
+ *
+ * @group Envelopes
+ * @api PUT /envelopes/:envelope_id/fields/:field_name Upload or Delete Attachment
+ * @apiParam string(format: 'uuid') envelope_id The ID of the envelope to update.
+ * @apiParam string field_name The name of the field to update. Be sure to URL-encode the value.
+ * @apiBody string document The file to attach. Must contain standard File object fields. If omitted, the attachment will be deleted instead.
+ * @apiSuccess IEnvelopeFieldSettings . A copy of the newly-updated field.
  */
 const uploadEnvelopeFieldAttachment = async (endpoint, envelopeId, fieldName, file, onUploadProgress) => {
     const formData = new FormData();
@@ -1590,7 +1670,9 @@ const uploadEnvelopeFieldAttachment = async (endpoint, envelopeId, fieldName, fi
         .then((r) => r.data);
 };
 /**
- * Delete an attachment.
+ * Delete an attachment. Note that this is not a DELETE endpoint because the field itself is not
+ * being deleted. Instead, it is a similar operation to uploading a new attachment, but the
+ * omission of the attachment signals the server to delete the current entry.
  */
 const deleteEnvelopeFieldAttachment = async (endpoint, envelopeId, fieldName) => {
     const formData = new FormData();
@@ -1600,7 +1682,13 @@ const deleteEnvelopeFieldAttachment = async (endpoint, envelopeId, fieldName) =>
         .then((r) => r.data);
 };
 /**
- * Get the attached file for an attachment field (if any)
+ * Get the attached file for an attachment field (if any).
+ *
+ * @group Envelopes
+ * @api GET /envelopes/:envelope_id/fields/:field_name/document Download attachment in binary format
+ * @apiParam string(format: 'uuid') envelope_id The ID of the envelope to retrieve.
+ * @apiParam string field_name The name of the field from which to download the attachment.
+ * @apiSuccess string . The file binary data.
  */
 const getFieldAttachment = async (endpoint, envelopeId, fieldName) => endpoint.api //
     .get(`/envelopes/${envelopeId}/fields/${fieldName}/document`, { responseType: 'blob' })
@@ -1609,6 +1697,13 @@ const getFieldAttachment = async (endpoint, envelopeId, fieldName) => endpoint.a
  * Get a display URI for a given page in a file attached to an envelope document. These pages are rendered server-side
  * into PNG resources suitable for display in IMG tags although they may be used elsewhere. Note that these are intended
  * for DISPLAY ONLY, are not legally binding documents, and do not contain any encoded metadata from participants.
+ *
+ * @group Envelopes
+ * @api GET /v2/envelope-documnets/page-image/:document_id/:variant/:page Get Document Page Display URI
+ * @apiParam string(format: 'uuid') document_id The ID of the document to retrieve.
+ * @apiParam string(enum: 'original'|'filled') variant The variant of the document to retrieve.
+ * @apiParam integer page The page number to retrieve
+ * @apiSuccess string . The page display URI. Note that this is a signed URL with a short expiration. It should be used immediately and never databased or cached.
  */
 const getEnvelopeDocumentPageDisplayUri = async (endpoint, documentId, page, variant = 'original') => endpoint.api.get(`/v2/envelope-documents/page-image/${documentId}/${variant}/${page}`, { timeout: 20000 }).then((r) => r.data);
 /**
@@ -1619,6 +1714,24 @@ const getEnvelopeDocumentPageDisplayUri = async (endpoint, documentId, page, var
  *
  * const {count, envelopes} = await getEnvelopes((VerdocsEndpoint.getDefault(), { q: 'test' });
  * ```
+ *
+ * @group Envelopes
+ * @api GET /v2/envelopes List Envelopes
+ * @apiQuery string q? Match envelopes whose name contains this string
+ * @apiQuery string(enum: 'inbox' | 'sent' | 'action' | 'waiting' | 'completed') view? Request pre-defined view. `inbox` returns envelopes where action is required by the caller. `sent` returns envelopes created by the caller. `action` returns envelopes where action is required by the caller. `waiting` returns envelopes where action is required by anyone. `completed` returns envelopes where all actions are complete.
+ * @apiQuery array(items: 'complete' | 'pending' | 'in progress' | 'declined' | 'canceled') status? Match envelopes in one of the specified states.
+ * @apiQuery boolean(default: false) include_org? If true, include organizations-shared envelopes
+ * @apiQuery string(format: uuid) template_id? Match envelopes created from the specified template ID
+ * @apiQuery string(format: date-time) created_before? Match envelopes created before this date
+ * @apiQuery string(format: date-time) created_after? Match envelopes created after this date
+ * @apiQuery string(enum: 'name' | 'created_at' | 'updated_at' | 'canceled_at' | 'status') sort_by? Return results sorted by this criteria
+ * @apiQuery boolean ascending? Set true/false to override the sort direction. Note that the default depends on `sort_by`. Date-based sorts default to descending, while name and status default to ascending.
+ * @apiQuery integer(default: 20) rows? Limit the number of rows returned
+ * @apiQuery integer(default: 0) page? Specify which page of results to return
+ * @apiSuccess integer(format: int32) count The total number of records matching the query, helpful for pagination
+ * @apiSuccess integer(format: int32) rows The number of rows returned in this response page
+ * @apiSuccess integer(format: int32) page The page number of this response
+ * @apiSuccess array(items: IEnvelope) envelopes List of envelopes found
  */
 const getEnvelopes = (endpoint, params) => endpoint.api //
     .get('/v2/envelopes', { params })
@@ -1629,6 +1742,11 @@ const getEnvelopes = (endpoint, params) => endpoint.api //
  * an initials block to be used for all initials fields in the document. Thus, this is typically called one time to
  * create and store an initials block. Thereafter, the ID of the initials block may be re-used for each initials field
  * to be "stamped" by the user.
+ *
+ * @group Signatures and Initials
+ * @api POST /initials Create Initial Block
+ * @apiBody string initial Blob containing initials image to store.
+ * @apiSuccess IInitial . The newly-created initial block.
  */
 const createInitials = (endpoint, name, initials) => {
     const data = new FormData();
@@ -1664,12 +1782,24 @@ const submitKbaIdentity = (endpoint, envelope_id, role_name, identity) => endpoi
  * Submit an identity response to a KBA challenge. Answers should be submitted in the same order as
  * the challenges were listed in `IRecipientKbaStepChallenge.questions`.
  */
-const submitKbaChallengeResponse = (endpoint, envelope_id, role_name, response) => endpoint.api //
-    .post(`/v2/kba/response`, { envelope_id, role_name, response })
+const submitKbaChallengeResponse = (endpoint, envelope_id, role_name, responses) => endpoint.api //
+    .post(`/v2/kba/response`, { envelope_id, role_name, responses })
     .then((r) => r.data);
 
 /**
- * Update a recipient's status block
+ * Update a recipient's status.
+ *
+ * @group Recipients
+ * @api PUT /envelopes/:envelope_id/recipients/:role_name Update Recipient Status
+ * @apiParam string(format:uuid) envelope_id The envelope to operate on.
+ * @apiParam string role_name The role to adjust.
+ * @apiBody string(enum:'submit'|'decline'|'owner_update'|'update'|'prepare') action The action to take. Adjusts the status, and may also perform other operations.
+ * @apiBody string first_name? Ignored unless action is 'owner_update' or 'update'. The new owner's or recipient's first name.
+ * @apiBody string last_name? Ignored unless action is 'owner_update' or 'update'. The new owner's or recipient's last name.
+ * @apiBody string email? Ignored unless action is 'owner_update'. The new owner's email address.
+ * @apiBody boolean agreed? Ignored unless action is 'update'. Set to true to accept the e-signing disclosures.
+ * @apiBody array(items:IRecipient) recipients? Ignored unless action is 'prepare'. A list of recipients and their fields to set defaults for.
+ * @apiSuccess IRecipient . The updated Recipient.
  */
 const updateRecipient = async (endpoint, envelope_id, role_name, params) => endpoint.api //
     .put(`/envelopes/${envelope_id}/recipients/${role_name}`, params)
@@ -1700,10 +1830,17 @@ const envelopeRecipientUpdateName = (endpoint, envelopeId, roleName, first_name,
 const envelopeRecipientPrepare = (endpoint, envelopeId, roleName, recipients) => updateRecipient(endpoint, envelopeId, roleName, { action: 'prepare', recipients });
 /**
  * Begin a signing session for an Envelope. This path requires an invite code, and should generally
- * be called with a NON-default endpoint to avoid conflicting with any active user session the user
+ * be called with a NON-default Endpoint to avoid conflicting with any active user session the user
  * may have. To initiate in-person signing by an authenticated user (e.g. self-signing), call
  * getInPersonLink() instead. The response from that call includes both a link for direct signing
  * via a Web browser as well as an in-person access_key. That access_key.key may be used here as well.
+ *
+ * @group Recipients
+ * @api POST /v2/sign/unauth/:envelope_id/:role_name/:key Start Signing Session
+ * @apiParam string(format:uuid) envelope_id The envelope to operate on.
+ * @apiParam string role_name The role to request.
+ * @apiParam string key Access key generated by the envelope creator or email/SMS invite.
+ * @apiSuccess ISignerTokenResponse . Signing session token and envelope/recipient metadata.
  */
 const startSigningSession = async (endpoint, envelope_id, role_name, key) => {
     return endpoint.api //
@@ -1714,7 +1851,18 @@ const startSigningSession = async (endpoint, envelope_id, role_name, key) => {
     });
 };
 /**
- * Get an in-person signing link.
+ * Get an in-person signing link. Must be called by the owner/creator of the envelope. The response
+ * also includes the raw access key that may be used to directly initiate a signing session (see
+ * `startSigningSession`) as well as an access token representing a valid signing session for
+ * immediate use in embeds or other applications. Note that in-person signing is considered a
+ * lower-security operation than authenticated signing, and the final envelope certificate will
+ * reflect this.
+ *
+ * @group Recipients
+ * @api POST /v2/sign/in-person/:envelope_id/:role_name Get In-Person Signing Link
+ * @apiParam string(format:uuid) envelope_id The envelope to operate on.
+ * @apiParam string role_name The role to request.
+ * @apiSuccess IInPersonLinkResponse . Signing session token and envelope/recipient metadata.
  */
 const getInPersonLink = (endpoint, envelope_id, role_name) => endpoint.api //
     .post(`/v2/sign/in-person/${envelope_id}/${encodeURIComponent(role_name)}`)
@@ -1726,7 +1874,17 @@ const sendDelegate = (endpoint, envelopeId, roleName) => endpoint.api //
     .post(`/envelopes/${envelopeId}/recipients/${encodeURIComponent(roleName)}`)
     .then((r) => r.data);
 /**
- * Resend a recipient's invitation.
+ * Resend a recipient's invitation. NOTE: User interfaces should rate-limit this operation to
+ * avoid spamming recipients. Excessive use of this endpoint may result in Verdocs rate-limiting
+ * the calling application to prevent abuse. This endpoint will return a 200 OK even if the
+ * no_contact flag is set on the envelope (in which case the call will be ignored).
+ *
+ * @group Recipients
+ * @api PUT /v2/envelopes/:envelope_id/recipients/:role_name Resend Invitation
+ * @apiParam string(format:uuid) envelope_id The envelope to operate on.
+ * @apiParam string role_name The role to operate on.
+ * @apiBody string(enum:'resend') action The operation to perform.
+ * @apiSuccess string . Success message.
  */
 const resendInvitation = (endpoint, envelopeId, roleName) => endpoint.api //
     .put(`/v2/envelopes/${envelopeId}/recipients/${encodeURIComponent(roleName)}`, { action: 'resend' })
@@ -1810,6 +1968,12 @@ const getNextRecipient = (envelope) => {
  * a signature block to be used for all signature fields in the document. Thus, this is typically called one time to
  * create and store a signature block. Thereafter, the ID of the signature block may be re-used for each signature field
  * to be "stamped" by the user.
+ *
+ * @group Signatures and Initials
+ * @api POST /signatures Create Signature Block
+ *
+ * @apiBody string signature Blob containing signature image to store.
+ * @apiSuccess ISignature . The newly-created signature block.
  */
 const createSignature = (endpoint, name, signature) => {
     const data = new FormData();
@@ -1819,19 +1983,34 @@ const createSignature = (endpoint, name, signature) => {
         .then((r) => r.data);
 };
 /**
- * Get the availbable signatures for a user.
+ * Get the available signatures for a user.
+ *
+ * @group Signatures and Initials
+ * @api GET /signatures Create Signature Block
+ *
+ * @apiSuccess array(items:ISignature) . A list of signatures previously stored for the user.
  */
 const getSignatures = (endpoint) => endpoint.api //
     .get('/signatures')
     .then((r) => r.data);
 /**
  * Get a user's signature by ID.
+ *
+ * @group Signatures and Initials
+ * @api GET /signatures/:id Delete Signature Block
+ * @apiParam string(format: 'uuid') id The ID of the signature to delete.
+ * @apiSuccess ISignature . The signature metadata requested.
  */
 const getSignature = (endpoint, signatureId) => endpoint.api //
     .get(`/signatures/${signatureId}`)
     .then((r) => r.data);
 /**
  * Delete a user's signature.
+ *
+ * @group Signatures and Initials
+ * @api DELETE /signatures/:id Delete Signature Block
+ * @apiParam string(format: 'uuid') id The ID of the signature to delete.
+ * @apiSuccess string . OK
  */
 const deleteSignature = (endpoint, signatureId) => endpoint.api //
     .delete(`/signatures/${signatureId}`)
@@ -2744,6 +2923,21 @@ const getAllTags = (endpoint) => endpoint.api //
  * await getTemplates((VerdocsEndpoint.getDefault(), { is_creator: true });
  * await getTemplates((VerdocsEndpoint.getDefault(), { is_organization: true });
  * ```
+ *
+ * @group Templates
+ * @api GET /v2/templates Get Templates
+ * @apiQuery string q? Find templates whose names/descriptions contain the specified query string
+ * @apiQuery boolean is_starred? If true, returns only templates with at least one "star".
+ * @apiQuery boolean is_creator? If true, returns only templates that the caller created.
+ * @apiQuery string(enum: 'private_shared' | 'private' | 'shared' | 'public') visibility? Return only templates with the specified visibility.
+ * @apiQuery string(enum: 'created_at' | 'updated_at' | 'name' | 'last_used_at' | 'counter' | 'star_counter') sort_by? Return results sorted by this criteria
+ * @apiQuery boolean ascending? Set true/false to override the sort direction. Note that the default depends on `sort_by`. Date-based sorts default to descending, while name defaults to ascending.
+ * @apiQuery integer(default: 20) rows? Limit the number of rows returned
+ * @apiQuery integer(default: 0) page? Specify which page of results to return
+ * @apiSuccess integer(format: int32) count The total number of records matching the query, helpful for pagination
+ * @apiSuccess integer(format: int32) rows The number of rows returned in this response page
+ * @apiSuccess integer(format: int32) page The page number of this response
+ * @apiSuccess array(items: ITemplate) templates List of templates found
  */
 const getTemplates = (endpoint, params) => endpoint.api //
     .get('/v2/templates', { params })