@verdocs/js-sdk
Version:
Isomorphic JS/TS SDK providing types and API wrappers for the Verdocs platform for Node and browser clients
1,348 lines • 163 kB
text/typescript
import { AxiosInstance } from "axios";
/**
* Create public templates. Public templates are still owned and managed by the creator,
* but may be searched for and used to create envelopes by other users.
*/
type TTemplatePermissionCreatePublic = "template:creator:create:public";
/**
* Create templates shared with other users of the same organization.
*/
type TTemplatePermissionCreateOrg = "template:creator:create:org";
/**
* Create templates private to the creator.
*/
type TTemplatePermissionCreatePersonal = "template:creator:create:personal";
/**
* Create templates private to the creator.
*/
type TTemplatePermissionDelete = "template:creator:delete";
/**
* Alter the visiiblity settings on a template.
*/
type TTemplatePermissionVisibility = "template:creator:visibility";
/**
* View templates shared by other members of the same organization. Those templates must also
* have `is_personal` set to false to be visible.
*/
type TTemplateMemberRead = "template:member:read";
/**
* Edit templates shared by other members of the same organization. Those templates must also
* have `is_personal` set to false to be editable.
*/
type TTemplateMemberWrite = "template:member:write";
/**
* Edit templates shared by other members of the same organization. Those templates must also
* have `is_personal` set to false to be editable.
*/
type TTemplateMemberDelete = "template:member:delete";
/**
* Edit templates shared by other members of the same organization. Those templates must also
* have `is_personal` set to false to be editable.
*/
type TTemplateMemberVisibility = "template:member:visibility";
type TTemplatePermission = TTemplatePermissionCreatePublic | TTemplatePermissionCreateOrg | TTemplatePermissionCreatePersonal | TTemplatePermissionDelete | TTemplatePermissionVisibility | TTemplateMemberRead | TTemplateMemberWrite | TTemplateMemberDelete | TTemplateMemberVisibility;
/**
* Grant the "owner" role to other organization members.
*/
type TAccountPermissionOwnerAdd = "owner:add";
/**
* Remove the "owner" role from other organization members.
*/
type TAccountPermissionOwnerRemove = "owner:remove";
/**
* Grant the "admin" role to other organization members.
*/
type TAccountPermissionAdminAdd = "admin:add";
/**
* Remove the "admin" role from other organization members.
*/
type TAccountPermissionAdminRemove = "admin:remove";
/**
* View the members of an organization.
*/
type TAccountPermissionMemberView = "member:view";
/**
* Grant the "member" role to other organization members.
*/
type TAccountPermissionMemberAdd = "member:add";
/**
* Remove the "member" role from other organization members.
*/
type TAccountPermissionMemberRemove = "member:remove";
type TAccountPermission = TAccountPermissionOwnerAdd | TAccountPermissionOwnerRemove | TAccountPermissionAdminAdd | TAccountPermissionAdminRemove | TAccountPermissionMemberAdd | TAccountPermissionMemberRemove | TAccountPermissionMemberView;
/**
* Create a new organization.
* @deprecated This is a system-wide setting and organization owners cannot prevent their
* members from listing other organizations that they may have separate profiles in.
*/
type TOrgPermissionCreate = "org:create";
/**
* View the organization.
*/
type TOrgPermissionView = "org:view";
/**
* Update the organization.
*/
type TOrgPermissionUpdate = "org:update";
/**
* Delete the organization.
*/
type TOrgPermissionDelete = "org:delete";
/**
* Transfer ownership of the organization. This primarily allows the holder to remove his/her own
* Owner role or add new Owners even if the holder is not one themselves. This is primarily intended
* to be used for reseller scenarios.
*/
type TOrgPermissionTransfer = "org:transfer";
/**
* List organizations.
* @deprecated This is a system-wide setting and organization owners cannot prevent their
* members from listing other organizations that they may have separate profiles in.
*/
type TOrgPermissionList = "org:list";
type TOrgPermission = TOrgPermissionCreate | TOrgPermissionView | TOrgPermissionUpdate | TOrgPermissionDelete | TOrgPermissionTransfer | TOrgPermissionList;
/**
* Create envelopes.
*/
type TEnvelopePermissionCreate = "envelope:create";
/**
* Cancel envelopes. This is a default permission for most users, but it may be removed for
* highly regulated environments where envelope activities must be audited, and should not
* be canceled.
*/
type TEnvelopePermissionCancel = "envelope:cancel";
/**
* View envelopes. This is a default permission for most users, but it may be removed for
* highly regulated environments where once sent, envelopes may only be viewed by specific
* users.
*/
type TEnvelopePermissionView = "envelope:view";
/**
* View envelopes created by other members of the same organization. By default, only templates
* having sharing settings controlled by their creators. Envelopes are usually private to the
* callers who created them. In some organizations it may be useful to have users who can see
* "all activity" by all organization members. This is particularly useful when applied to API
* keys to develop applications that can access all data across the organization.
*/
type TEnvelopePermissionOrg = "envelope:org:view";
type TEnvelopePermission = TEnvelopePermissionCreate | TEnvelopePermissionCancel | TEnvelopePermissionView | TEnvelopePermissionOrg;
/**
* Operation within Verdocs that users may perform.
*/
type TPermission = TTemplatePermission | TOrgPermission | TAccountPermission | TEnvelopePermission;
/**
* Roles provide access to groups of permissions. Note that for historical reasons there is some overlap in the
* use of the term "role". TRole refers to a user type. A "Role" (IRole) is a Template participant placeholder.
*/
type TRole = "contact" | "basic_user" | "member" | "admin" | "owner";
/**
* A map of the permissions each role confers.
*/
declare const RolePermissions: Record<TRole, TPermission[]>;
/**
* Confirm whether the user has all of the specified permissions.
*/
declare const userHasPermissions: (profile: IProfile | null | undefined, permissions: TPermission[]) => boolean;
/**
* A Signing Session connects a caller to a role within an envelope, and can be used only for calls related to signing that envelope.
*/
interface ISigningSession {
aud: string;
iss: string;
sub: string; // Verdocs access key ID
email: string;
iat: number;
exp: number;
["https://verdocs.com/session_type"]: "signing";
["https://verdocs.com/key_type"]: TAccessKeyType;
["https://verdocs.com/envelope_id"]: string;
["https://verdocs.com/role_name"]: string;
}
/**
* A User Session connects a caller to a Verdocs profile, and can be used for any operations that profile may perform.
*/
interface IUserSession {
jti: string;
aud: string;
iss: string;
sub: string; // Verdocs user_id
email: string;
iat: number;
exp: number;
["https://verdocs.com/session_type"]: "user";
["https://verdocs.com/profile_id"]: string;
["https://verdocs.com/organization_id"]: string;
["https://verdocs.com/global_admin"]: boolean;
}
interface IIdToken {
aud: string;
iss: string;
sub: string; // Verdocs user_id
email: string;
organization_id: string;
first_name: string;
last_name: string;
phone: string;
}
/**
* Verdocs supports two types of authenticated sessions: User and Signing. Both behave similarly and have similar
* properties, but signing sessions only have access to a small set of signing-related functions.
*/
type TSessionType = "user" | "signing";
/**
* Represents a possibly-authenticated session within Verdocs, either for signing or regular user-based operations.
*/
type TSession = IUserSession | ISigningSession | null;
/**
* An active authenticated session within Verdocs, either for signing or regular user-based operations.
*/
type TActiveSession = IUserSession | ISigningSession;
/////////////////////////////// NOTIFICATIONS /////////////////////////////
interface IChannel {
id: string;
channel_type: string;
event_name: string;
disabled_channels?: IDisabledChannel[];
}
interface IDisabledChannel {
channel_id: string;
profile_id: string;
profile?: IProfile;
channel?: IChannel;
}
interface INotification {
id: string;
profile_id: string;
event_name: string;
data: any;
read: boolean;
deleted: boolean;
message: string;
time: string;
profile?: IProfile;
}
//////////////////////////////////////// IAM //////////////////////////////
interface IApiKey {
client_id: string;
name: string;
organization_id: string;
profile_id: string;
global_admin: boolean;
client_secret?: string | null;
permission: TApiKeyPermission;
profile?: IProfile;
organization?: IOrganization;
}
interface IGroup {
id: string;
name: string;
organization_id: string;
permissions: TPermission[];
organization?: IOrganization;
profiles?: IGroupProfile[];
}
interface IGroupProfile {
group_id: string;
profile_id: string;
organization_id: string;
group?: IGroup;
profile?: IProfile;
organization?: IOrganization;
}
interface IOAuth2App {
id: string;
profile_id: string;
organization_id: string;
name: string;
client_id: string;
client_secret?: string | null;
redirect_uris: string;
origins: string;
friendly_name: string;
logo_uri: string;
public_key: string;
private_key: string;
created_at: string;
updated_at: string;
organization?: IOrganization;
profile?: IProfile;
}
interface IEntitlement {
id: string;
organization_id: string;
feature: TEntitlement;
contract_id?: string | null;
notes?: string | null;
starts_at: string;
ends_at: string;
monthly_max: number;
yearly_max: number;
created_at: string;
organization?: IOrganization;
}
interface IOrganization {
/** The unique ID of the organization */
id: string;
/** The organization's name. */
name: string;
address: string | null;
address2: string | null;
phone: string | null;
/** If the organization is a business, its name. Note that a business name can be different from an organization name. */
contact_email: string | null;
slug?: string | null;
/** Web site URL */
url?: string | null;
full_logo_url?: string | null;
thumbnail_url?: string | null;
primary_color?: string | null;
secondary_color?: string | null;
data?: Record<string, any> | null;
/** Creation date/time. */
created_at: string;
/** Last-update date/time. */
updated_at: string;
api_keys?: IApiKey[];
groups?: IGroup[];
oauth2_apps?: IOAuth2App[];
entitlements?: IEntitlement[];
organization_invitations?: IOrganizationInvitation[];
profiles?: IProfile[];
webhooks?: IWebhook[];
envelopes?: IEnvelope[];
templates?: ITemplate[];
group_profiles?: IGroupProfile[];
pending_webhooks?: IPendingWebhook[];
}
interface IOrganizationInvitation {
organization_id: string;
email: string;
first_name: string;
last_name: string;
status: "pending";
role: TRole;
generated_at: string;
token?: string | null;
organization?: IOrganization;
}
interface IPendingWebhook {
id: string;
webhook_id: string;
organization_id: string;
url: string;
body: any;
created_at: string;
delivered_at: string | null;
last_attempt_at: string | null;
last_status: number | null;
last_result: string | null;
webhook?: IWebhook;
organization?: IOrganization;
}
interface IProfile {
/** The unique ID of the profile */
id: string;
/**
* In Verdocs, a user may have multiple profiles. A user represents a single person. A profile
* represents that person within an organization. Some profiles may have no user atached, typically
* Contacts and Signers. This can change if that person registers for a user later.
*/
user_id: string | null;
/** The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of. */
organization_id: string;
first_name: string;
last_name: string;
email: string;
phone: string | null;
picture: string | null;
/** If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile. */
current: boolean;
permissions: TPermission[];
roles: TRole[];
// Creation date/time.
created_at: string;
// Last-update date/time.
updated_at: string;
user?: IUser;
organization?: IOrganization;
api_keys?: IApiKey[];
group_profiles?: IGroupProfile[];
groups?: IGroup[];
notifications?: INotification[];
oauth2_apps?: IOAuth2App[];
signatures?: ISignature[];
initials?: IInitial[];
}
interface IUser {
id: string;
email: string;
email_verified: boolean;
pass_hash?: string;
first_name: string | null;
last_name: string | null;
phone: string | null;
picture: string | null;
b2cId: string | null;
googleId: string | null;
appleId: string | null;
githubId?: string | null;
created_at: string;
updated_at: string;
}
interface IWebhookEvents {
envelope_created: boolean;
envelope_completed: boolean;
envelope_updated: boolean;
envelope_canceled: boolean;
template_created: boolean;
template_updated: boolean;
template_deleted: boolean;
template_used: boolean;
}
interface IWebhook {
id: string;
organization_id: string;
url: string;
active: boolean;
events: IWebhookEvents;
status: string | null;
last_success: string | null;
last_failure: string | null;
organization?: IOrganization;
pending_webhooks?: IPendingWebhook[];
}
//////////////////////////////// FORMS ////////////////////////////////////
interface IInPersonAccessKey {
id: string;
type: "in_person_link";
authentication?: string | null;
role_name: string;
envelope_id: string;
key: string;
expiration_date: string | null;
created_at: string;
first_used: string | null;
last_used: string | null;
envelope?: IEnvelope;
}
interface IInAppAccessKey {
id: string;
type: "in_app";
authentication?: string | null;
recipient_name: string;
envelope_id: string;
key: string;
expiration_date: string | null;
created_at: string;
first_used: string | null;
last_used: string | null;
envelope?: IEnvelope;
}
interface IEmailAccessKey {
id: string;
type: "email";
authentication?: string | null;
recipient_name: string;
envelope_id: string;
key: string;
expiration_date: string | null;
created_at: string;
first_used: string | null;
last_used: string | null;
envelope?: IEnvelope;
}
interface ISMSAccessKey {
id: string;
type: "sms";
authentication?: string | null;
recipient_name: string;
envelope_id: string;
key: string;
expiration_date: string | null;
created_at: string;
first_used: string | null;
last_used: string | null;
envelope?: IEnvelope;
}
type TAccessKey = IInPersonAccessKey | IInAppAccessKey | IEmailAccessKey | ISMSAccessKey;
/**
* An Envelope is a workflow wrapper that shepherds one or more Documents through the various recipients in a signing
* process.
*/
interface IEnvelope {
/** Unique identifier for the envelope (UUID) */
id: string;
/** Current status of the envelope. Note that 'complete', 'declined', and 'canceled' are immutable/permanent end states. */
status: TEnvelopeStatus;
/** ID of the envelope's creator. */
profile_id: string;
/** ID of the template from which the envelope was created. */
template_id: string | null;
/** ID of the organization to which the envelope belongs. */
organization_id: string;
/** Name of the envelope. By defaut, inherited from the envelope's template, but may be overridden when the envelope is created. */
name: string;
/** If set to true, no email or SMS messages will be sent to any of the envelope's recipients. */
no_contact?: boolean;
/** Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable. */
initial_reminder: number | null;
/** Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable. */
followup_reminders: number | null;
/** When the next reminder is scheduled to be sent. */
next_reminder: string | null;
/** Date/time when the envelope was created. */
created_at: string;
/** Date/time when the envelope was created. */
updated_at: string;
/** Date/time when the envelope was canceled, or null. */
canceled_at: string;
/** Defaults to 'private'. If set to 'shared', this envelope will be visible to other users in the same organization. Ignored for personal profiles. */
visibility: "private" | "shared";
search_key?: string | null;
/**
* Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Envelopes back to
* internal systems/applications.
*/
data?: Record<string, any> | null;
profile?: IProfile;
template?: ITemplate | null;
organization?: IOrganization;
access_keys?: TAccessKey[];
fields?: IEnvelopeField[];
history_entries?: IEnvelopeHistory[];
recipients: IRecipient[];
/** Documents attached to this envelope */
documents?: IEnvelopeDocument[] | null;
}
interface IEnvelopeDocument {
id: string;
envelope_id: string;
template_document_id: string | null;
order: number;
type: "attachment" | "certificate";
name: string;
pages: number;
mime: string;
size: number;
page_sizes: {
width: number;
height: number;
}[];
created_at: string;
updated_at: string;
}
interface IDropdownOption {
id: string;
label: string;
}
interface IEnvelopeField {
/** The ID of the envelope the field is for. */
envelope_id: string;
/** The ID of the document the field is for. */
document_id: string;
/** The machine name of the field, e.g. `Buyer-textbox-1` */
name: string;
/** The ID of the role in the recipients list, e.g. `Recipient 2` */
role_name: string;
/** The type of the field */
type: TFieldType;
/** If true, the field will be required */
required: boolean | null;
/** If true, the field will be not be editable by the participant(s). NOTE: Fields may not be both required and readonly. */
readonly: boolean | null;
/** @deprecated. Use top-level fields instead. */
settings: IEnvelopeFieldSettings | null;
validator: string | null;
/** If set, the placeholder/label for the field. */
label: string | null;
/** Not sent by the server. Used in the UI to identify prepared fields. */
prepared: boolean | null;
/** The 1-based page number the field is displayed on. "Self-placed" fields that the user must apply will be on page 0. */
page: number;
/** The X position of the field. */
x: number;
/** The Y position of the field. */
y: number;
/** The width of the field. */
width: number;
/** The height of the field. */
height: number;
/** The default value for the field. */
default: string | null;
/** The placeholder to show in the field. */
placeholder: string | null;
/** For text boxes, allows more than one line of text to be entered. */
multiline: boolean;
/** For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name. */
group: string | null;
/** For dropdowns, the options that are selectable. */
options: IDropdownOption[] | null;
value: string | null;
is_valid: boolean;
}
interface IEnvelopeFieldOptions {
/** The unique ID of the field */
id: string;
/** The X position of the field on the page. Self-placed fields will have an X value of 0. */
x: number;
/** The Y position of the field on the page. Self-placed fields will have an X value of 0. */
y: number;
/** For checkboxes, whether it is currently checked */
checked: boolean | null;
/** For radio buttons, whether it is currently selected */
selected: boolean | null;
/** The visible label for the field e.g. 'Not Applicable' */
value: string;
}
interface IEnvelopeFieldSettings {
type?: string;
x?: number;
y?: number;
width?: number;
height?: number;
value?: number | string;
/** If the field has been filled in, this contains the current value */
result?: any;
/** Text field settings */
leading?: number;
alignment?: number;
upperCase?: boolean;
/** Dropdowns, checkboxes, radio groups */
options?: IEnvelopeFieldOptions[];
/** Signatures and Initials, result will be "signed" */
base64?: string;
hash?: string;
ip_address?: string;
signature_id?: string;
signed_at?: string;
/** Checkbox settings */
minimum_checked?: number;
maximum_checked?: number;
}
interface IEnvelopeHistory {
id: string;
envelope_id: string;
role_name: string;
event: THistoryEvent;
event_detail: TEventDetail;
created_at: string;
envelope?: IEnvelope;
}
interface IInitial {
id: string | null;
profile_id: string;
created_at: string | null;
updated_at: string | null;
deleted_at: string | null;
profile?: IProfile;
}
interface IKbaPINRequired {
type: "pin";
}
interface IKBAQuestion {
type: string;
answer: string[];
prompt: string;
}
interface IRecipient {
/** Used only by the Web SDK during builder processes. Not stored in the backend. */
id?: string | null;
envelope_id: string;
role_name: string;
profile_id?: string | null;
status: TRecipientStatus;
first_name: string;
last_name: string;
/** @deprecated. Use first_name/last_name instead. */
full_name?: string | null;
email: string;
/** Phone number for SMS invites */
phone?: string | null;
/** Street address. Only used in KBA workflows. Combine two-line addresses into a single string. */
address?: string | null;
/** Zip code. Only used in KBA workflows. */
city?: string | null;
/** Zip code. Only used in KBA workflows. */
state?: string | null;
/** Zip code. Only used in KBA workflows. */
zip?: string | null;
/** @deprecated. Use dob instead. */
ssn_last_4?: string | null;
/** Date of birth. Only used in KBA workflows. */
dob?: string | null;
/**
* The sequence number indicates the order in which Recipients act. Multiple recipients may have the same sequence
* number, in which case they may act in parallel. (e.g. all Recipients at sequence 2 will receive invites once
* all Recipients at sequence 1 have signed.)
*/
sequence: number;
/**
* The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that
* recipients at the same level may act in parallel despite this value. However, it can often be useful to visually
* arrange recipients to match related business processes so this field allows for that.
*/
order: number;
type: TRecipientType;
delegator: boolean;
delegated_to: string | null;
message: string | null;
claimed: boolean;
agreed: boolean;
key_used_to_conclude?: string;
environment?: string;
created_at: string;
updated_at: string;
last_attempt_at?: string;
/**
* Only returned in creation/getEnvelopeById requests by the creator. May be used for in-person signing. Note that
* signing sessions started with this key will be marked as "In App" authenticated. For higher authentication levels,
* e.g. email, the signer must follow a link send via the appropriate channel (email).
*/
in_app_key?: string;
/**
* The next verification step that must be performed.
*/
auth_step?: TRecipientAuthStep | null;
/** The types of authentication/verification required for this recipient. */
auth_methods?: TRecipientAuthMethod[] | null;
/** The status of each auth method enabled. */
auth_method_states?: Record<TRecipientAuthMethod, "complete" | "failed" | "challenge" | "questions" | "differentiator" | null> | null;
/**
* If auth_method is set to "passcode" this is the passcode required. For security reasons, this
* field will only be visible to the creator of the envelope.
*/
passcode?: string | null;
/**
* If a KBA step requires the user to answer a challenge/differentiator question, the
* question(s) to ask.
*/
kba_questions?: IKBAQuestion[] | null;
envelope?: IEnvelope;
profile?: IProfile;
}
/**
* A placeholder for an individual recipient, CC, or other party in a signing flow. Roles may be "known" or "unknown."
* "Known" roles will have their email address supplied in the template which will get copied to envelopes created from
* it. This is used when a certain party will always be the same, e.g. a leasing agent counter-signing a lease.
* "Unknown" roles are dynamic, and will be filled in later when the envelope is created.
*/
interface IRole {
/** Used only by the Web SDK during builder processes. Not stored in the backend. */
id?: string | null;
template_id: string;
// The name of the recipient. Note that recipients do not have a separate ID - they are uniquely identified by name.
name: string;
type: TRecipientType;
full_name: string | null;
first_name: string | null;
last_name: string | null;
email: string | null;
phone: string | null;
message: string | null;
/**
* The sequence number indicates the order in which Roles act. Multiple roles may have the same sequence
* number, in which case they may act in parallel. (e.g. all Roles at sequence 2 will receive invites once
* all Recipients at sequence 1 have signed.)
*/
sequence: number;
/**
* The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that
* recipients at the same level may act in parallel despite this value. However, it can often be useful to visually
* arrange recipients to match related business processes so this field allows for that.
*/
order: number;
delegator: boolean | null;
}
interface ISignature {
id: string;
profile_id: string;
created_at: string;
updated_at: string;
deleted_at: string | null;
profile?: IProfile;
}
/**
* A reusable template for creating signable instruments. Templates are used to create Envelopes which contain
* Documents to sign.
*/
interface ITemplate {
/**
* The unique ID of the template.
*/
id: string;
/**
* The template's owner/creator.
*/
profile_id: string;
/**
* Organization the template lives in.
*/
organization_id: string;
/**
* Who will "own" envelopes created from this template. Note that while either option is
* technically allowed for all visibility settings, "template_owner" only has an effect if
* visibility is "shared" or "public".
*/
sender: TTemplateSender;
/*
The user-supplied name of the template.
*/
name: string;
/**
* Optional description for the template.
*/
description?: string;
/**
* Number of times the template has been used.
*/
counter: number;
/**
* Number of times the template has been "starred".
*/
star_counter: number;
/** Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable. */
initial_reminder: number | null;
/** Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable. */
followup_reminders: number | null;
/**
* If true, the template is only visible to the creator. If false, the template will also be visible to the user's
* organization, if any.
* @deprecated. See "visibility".
*/
is_personal: boolean;
/**
* If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the
* user's organization. It may be desirable to create documents that are public but that do not appear in the
* organization's shared templates list. To achieve this, set both `is_personal` and `is_public` to TRUE.
* @deprecated. See "visibility".
*/
is_public: boolean;
/**
* If set, the visibility level for the template.
*/
visibility?: TTemplateVisibility;
/**
* If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.)
*/
is_sendable: boolean;
/**
* Creation date/time.
*/
created_at: string;
/**
* Last-update date/time.
*/
updated_at: string;
/**
* Last-used date/time (when the template was used to create a document).
*/
last_used_at: string | null;
search_key: string;
/**
* Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to
* internal systems/applications.
*/
data: Record<string, any> | null;
tags?: string[];
profile?: IProfile;
organization?: IOrganization;
roles?: IRole[];
documents?: ITemplateDocument[];
fields?: ITemplateField[];
// @deprecated. Use documents instead.
template_documents?: ITemplateDocument[];
}
/**
* A file attached to the template for display/signing.
*/
interface ITemplateDocument {
id: string;
name: string;
template_id: string;
order: number;
pages: number;
mime: string;
size: number;
page_sizes: {
width: number;
height: number;
}[];
created_at: string | null;
updated_at: string | null;
// @deprecated. Use pages instead.
page_numbers?: number;
template?: ITemplate;
}
interface ITemplateField {
/** The machine name of the field, e.g. `Buyer-textbox-1` */
name: string;
/** The ID of the role in the recipients list, e.g. `Recipient 2` */
role_name: string;
/** The ID of the template the field is for. */
template_id: string;
/** The ID of the document the field is for. */
document_id: string;
type: TFieldType;
required: boolean;
/** If true, the field will be not be editable by the participant(s). NOTE: Fields may not be both required and readonly. */
readonly: boolean | null;
/** @deprecated. Use top-level fields instead. */
settings: ITemplateFieldSetting | null;
page: number;
validator: string | null;
label: string | null;
/** The X position of the field. */
x: number;
/** The Y position of the field. */
y: number;
/** The width of the field. */
width: number;
/** The height of the field. */
height: number;
/** The default value for the field. */
default: string | null;
/** The placeholder to show in the field. */
placeholder: string | null;
/** For text boxes, allows more than one line of text to be entered. */
multiline: boolean;
/** For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name. */
group: string | null;
/** For dropdowns, the options that are selectable. */
options: IDropdownOption[] | null;
value?: string | null;
is_valid?: boolean;
}
interface ITextFieldSetting {
x: number;
y: number;
width: number;
height: number;
result: string;
leading: number;
alignment: number;
upperCase: boolean;
}
interface ITemplateFieldSetting {
x?: number;
y?: number;
result?: string;
width?: number;
height?: number;
// Text field settings
leading?: number;
alignment?: number;
upperCase?: boolean;
// Dropdowns, checkboxes, radio groups
options?: any[];
[key: string]: any;
}
type TRequestStatus = "OK" | "ERROR";
type TTemplateSender = "envelope_creator" | "template_owner";
type TTemplateAction = "create_personal" | "create_org" | "create_public" | "read" | "write" | "delete" | "change_visibility_personal" | "change_visibility_org" | "change_visibility_public";
type TRecipientAction = "submit" | "decline" | "prepare" | "update";
type TEnvelopeStatus = "complete" | "pending" | "in progress" | "declined" | "canceled";
type TRecipientStatus = "invited" | "opened" | "signed" | "submitted" | "canceled" | "pending" | "declined";
type TRecipientType = "signer" | "cc" | "approver";
/**
* Plans provide access to Verdocs product features.
*/
// export type TPlan = 'env:essential' | 'org:standard';
type TSortTemplateBy = "created_at" | "updated_at" | "name" | "last_used_at" | "counter" | "star_counter";
type TAccessKeyType = "email" | "in_app" | "in_person_link" | "sms";
type TApiKeyPermission = "personal" | "global_read" | "global_write";
/** @deprecated. See envelope.created_at, .updated_at, and .canceled_at. */
type TDeprecatedHistoryEvent = "envelope:created" | "envelope:completed";
type THistoryEvent = "recipient:signed" | "recipient:opened" | "recipient:submitted" | "recipient:prepared" | "recipient:claimed" | "recipient:agreed" | "recipient:invited" | "recipient:reminder" | "recipient:delegated" | "recipient:updated_info" | "recipient:declined" | "recipient:kba_verified" | "recipient:kba_failed" | "recipient:id_verified" | "recipient:id_failed" | "recipient:pin_verified" | "recipient:pin_failed" | "invitation:resent" | "envelope:cc" | "envelope:canceled" | "owner:updated_recipient_info" | "owner:get_in_person_link" | TDeprecatedHistoryEvent;
type TEventDetail = "in_app" | "mail" | "signer" | "sms" | "reminder" | "preparer" | "manual" | "in_person_link" | "guest" | "email" | "" | string; // Modification events have a string description
// Modification events have a string description
type TEnvelopeUpdateResult = Omit<IEnvelope, "histories" | "recipients" | "certificate" | "document" | "fields" | "profile">;
type TFieldType = "signature" | "initial" | "checkbox" | "radio" | "textbox" | "timestamp" | "date" | "dropdown" | "textarea" | "attachment" | "payment";
type TWebhookEvent = "envelope_created" | "envelope_completed" | "envelope_canceled" | "envelope_updated" | "template_created" | "template_updated" | "template_deleted" | "template_used";
type TTemplateVisibility = "private" | "shared" | "public";
type TEntitlement = "envelope" | "kba_auth" | "passcode_auth" | "sms_auth" | "kba_id_auth" | "id_auth" | "custom_disclaimer";
/**
* The authentication method(s) required for a recipient to access an envelope. "Passcode" will require a
* PIN or passcode to be entered, which is intended to be known to the sender and recipient ahead of time
* and communicated by means of their choosing. "SMS" and "Email" will send a one-time-code via the respective
* channel for the recipient to enter. "KBA" will require the recipient to confirm personal information such
* as prior addresses, phone numbers, etc. "ID" will require the recipient to perform full ID-based verification.
*/
type TRecipientAuthMethod = "kba" | "passcode" | "sms" | "email" | "id";
type TRecipientAuthStep = TRecipientAuthMethod | null;
declare const FIELD_TYPES: TFieldType[];
declare const DEFAULT_FIELD_WIDTHS: Record<TFieldType, number>;
declare const DEFAULT_FIELD_HEIGHTS: Record<TFieldType, number>;
declare const WEBHOOK_EVENTS: string[];
declare const ALL_PERMISSIONS: string[];
type TEnvironment = "" | "beta";
type TSessionChangedListener = (endpoint: VerdocsEndpoint, session: TSession, profile: IProfile | null) => void;
interface VerdocsEndpointOptions {
baseURL?: string;
timeout?: number;
environment?: TEnvironment;
sessionType?: TSessionType;
clientID?: string;
/** By default, sessions will be persisted to localStorage. Set `persist` to false to bypass this. */
persist?: boolean;
}
/**
* VerdocsEndpoint is a class wrapper for a specific connection and authorization context for calling the Verdocs APIs.
* Endpoints can be used for isolated session tasks.
*
* For instance, ephemeral signing sessions may be created independently of a caller's status as an authenticated user.
* In that case, an Endpoint can be created and authenticated, used for calls related to signing operations, then
* discarded once signing is complete.
*
* Note that endpoint configuration functions return the instance, so they can be chained, e.g.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
*
* const endpoint = new VerdocsEndpoint();
* endpoint
* .setSessionType('signing')
* .logRequests(true)
* .setClientID('1234)
* .setTimeout(30000);
* ```
*/
declare class VerdocsEndpoint {
private environment;
private sessionType;
private persist;
private baseURL;
private clientID;
private timeout;
private token;
private nextListenerId;
private sessionListeners;
private requestLoggerId;
endpointId: string;
/**
* The current user's userId (NOT profileId), or null if not authenticated.
*/
sub: string | null;
/**
* The current user session, or null if not authenticated. May be either a User or Signing session. If set, the
* presence of the `document_id` field can be used to differentiate the types. Only signing sessions are associated
* with Envelopes.
*/
session: TSession;
/**
* The current user's profile, if known. Note that while sessions are loaded and handled synchronously,
* profiles are loaded asynchronously and may not be available immediately after a session is loaded.
* To ensure both are available, developers should subscribe to the `onSessionChanged` event, which
* will not be fired until the profile is loaded and verified.
*/
profile: IProfile | null;
api: AxiosInstance;
/**
* Create a new VerdocsEndpoint to call Verdocs platform services.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
* const endpoint = new VerdocsEndpoint();
* ```
*/
constructor(options?: VerdocsEndpointOptions);
setDefault(): void;
static getDefault(): VerdocsEndpoint;
/**
* Get the current environment.
*/
getEnvironment(): TEnvironment;
/**
* Get the current session type.
*/
getSessionType(): TSessionType;
/**
* Get the current base URL. This should rarely be anything other than 'https://api.verdocs.com'.
*/
getBaseURL(): string;
/**
* Get the current client ID, if set.
*/
getClientID(): string;
/**
* Get the current timeout.
*/
getTimeout(): number;
/**
* Get the current session, if any.
*/
getSession(): TSession;
/**
* Set the operating environment. This should rarely be anything other than 'verdocs'.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
*
* const endpoint = new VerdocsEndpoint();
* endpoint.setEnvironment('verdocs-stage');
* ```
*/
setEnvironment(environment: TEnvironment): VerdocsEndpoint;
/**
* Set the session type. In general this should be done immediately when the endpoint is created. Changing the
* session type may be done at any time, but may have unintended consequences if the endpoint is shared between
* multiple widgets.
*
* Changing the session type will clear/reload the action session. This may trigger notifications to session state
* observers. Apps that use observers to trigger UI updates such as logging the user out should be prepared to
* handle this event.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
*
* const endpoint = new VerdocsEndpoint();
* endpoint.setEnvironment('verdocs-stage');
* ```
*/
setSessionType(sessionType: TSessionType): VerdocsEndpoint;
/**
* Set the base URL for API calls. Should be called only upon direction from Verdocs Customer Solutions Engineering.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
*
* const endpoint = new VerdocsEndpoint();
* endpoint.setBaseURL('https://api.verdocs.com');
* ```
*/
setBaseURL(url: string): VerdocsEndpoint;
/**
* Set the Client ID for Verdocs API calls.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
*
* const endpoint = new VerdocsEndpoint();
* endpoint.setClientID('1234);
* ```
*/
setClientID(clientID: string): VerdocsEndpoint;
/**
* Set the timeout for API calls in milliseconds. 5000-20000ms is recommended for most purposes. 15000ms is the default.
* Note that some calls may involve rendering operations that require some time to complete, so very short timeouts
* are not recommended.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
*
* const endpoint = new VerdocsEndpoint();
* endpoint.setTimeout(3000);
* ```
*/
setTimeout(timeout: number): VerdocsEndpoint;
/**
* Enable or disable request logging. This may expose sensitive data in the console log, so it should only be used for debugging.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
*
* const endpoint = new VerdocsEndpoint();
* endpoint.logRequests(true);
* ```
*/
logRequests(enable: boolean): VerdocsEndpoint;
/**
* Set the authorization token that will be used for Verdocs API calls. This will also set the session metadata
* and notify any listeners of the new data.
*
* If this Endpoint will be used for non-default purposes (e.g. signing, or in an alternate environment) those
* settings should be made before calling this. Sessions are persisted to localStorage, and the environment and
* type become part of the storage key.
*
* ```typescript
* import {VerdocsEndpoint} from '@verdocs/js-sdk/HTTP';
*
* const endpoint = new VerdocsEndpoint();
* endpoint.setToken(accessToken);
* ```
*/
setToken(token: string | null, sessionType?: TSessionType): VerdocsEndpoint;
/**
* Retrieves the current session token, if any. Tokens should rarely be used for direct actions, but this is
* required by the `<VerdocsView>` and other components to authorize requests to raw PDF files.
*/
getToken(): string | null;
private sessionStorageKey;
/**
* Clear the active session.
*/
clearSession(): this;
/**
* Clear the active signing session.
*/
clearSignerSession(): this;
private notifySessionListeners;
/**
* Subscribe to session state change events.
*/
onSessionChanged(listener: TSessionChangedListener): () => void;
/**
* Load a persisted session from localStorage. Typically called once after the endpoint is configured
* when the app or component starts. Ignored if the endpoint is configured to not persist sessions.
*/
loadSession(): VerdocsEndpoint;
}
interface IEnvelopesSearchResult {
page: number;
total: number;
result: IEnvelope[];
}
interface IDocumentSearchOptions {
rows?: number;
page?: number;
sort_by?: "updated_at" | "created_at";
ascending?: boolean;
is_owner?: boolean;
is_recipient?: boolean;
envelope_status?: TEnvelopeStatus[];
recipient_status?: TEnvelopeStatus[];
}
interface ICreateEnvelopeRecipient {
/** The type of role to create. Most participants in standard flows will be "signer" recipients. */
type: TRecipientType;
/**
* The Role name of the recipient. Please note this is not the person's name. It is the ID of the role, e.g.
* 'Recipient 1', 'Seller', etc. This must match one of the pre-defined roles in the template's Recipients list.
*/
role_name: string;
/** The name of the recipient as it will be displayed in reports and queries, e.g. 'Paige Turner'. */
first_name: string;
last_name: string;
/** The email address of the recipient. One of `email` or `phone` must be provided. */
email?: string;
/**
* The phone number of the recipient. One of `email` or `phone` must be provided. If `phone` is included, the
* recipient will receive an SMS notification for the document.
*/
phone?: string;
/**
* The 1-based sequence number for the recipient. This can be used to override the template's workflow. Recipients
* are processed in parallel for each matching sequence number (e.g. all recipients at level "1" may act in parallel)
* and in series between sequence numbers (e.g. all recipients at level "1" must complete their tasks before
* recipients at level "2" may act).
*/
sequence: number;
/**
* The 1-based order within the sequence for the recipient. Recipients at the same sequence act in parallel, so
* this is only for display purposes.
*/
order: number;
/** Whether the recipient may delegate their tasks to others. Should be false for most standard workflows. */
delegator?: boolean;
/** A custom message to include in the email or SMS invitation. May be left blank for a default message. */
message?: string;
/** To enable authentication for the recipient, set to 'pin' or 'identity'. */
auth_method?: TRecipientAuthMethod;
/** If Passcode-based authentication is used, the passcode to challenge the user to enter. */
passcode?: string;
/**
* If SMS-based authentication is used, the phone number to which one-time codes should be sent.
* NOTE: This may be different from the phone number used for notifications, but leaving it blank
* will trigger an error rather than defaulting to the notifications phone number to avoid mistaken
* assumptions (e.g. if SMS notifications are not enabled for the organization, but SMS authentication
* is).
*/
phone_auth?: string;
/*
* Pre-fill data for the recipient, if known. NOTE: Even when pre-filling these fields for a recipient, if
* KBA is enabled, the recipient must be provided with the option to confirm those details before proceeding,
* provide at least one data point themselves (typically date of birth). Providing every value here will
trigger an error.
*/
address?: string;
city?: string;
state?: string;
zip?: string;
dob?: string;
}
interface ISignerTokenResponse {
/**
* An access token that may be used with a VerdocsEndpoint to perform signing operations.
* When signing, the caller's "authentication" status will be recorded as "in-person".
*/
access_token: string;
/**
* A copy of the envelope related to the signing session. This is almost always needed when
* a signing session is being started, so it is included here for convenience.
*/
envelope: IEnvelope;
/**
* A copy of the recipient record related to the signing session. This is almost always needed when
* a signing session is being started, so it is included here for convenience.
*/
recipient: IRecipient;
}
interface IInPersonLinkResponse {
/** A valid Verdocs Web URL that hosts a signing experience. */
link: string;
/**
* An access token that may be used with a VerdocsEndpoint to perform signing operations.
* When signing, the caller's "authentication" status will be recorded as "in-person".
*/
access_token: string;
/**
* The access key that matches the signing session. May be used for later initiation requests
* if in-person signing was desired, but not necessarily instant (e.g. to hand-off to a
* companion application. **NOTE: Access keys are as sensitive as Bearer Tokens and must be
* protected from theft and unauthorized sharing!**
*/
access_key: TAccessKey;
/**
* A copy of the envelope related to the signing session. This is almost always needed when
* a signing session is being started, so it is included here for convenience.
*/
envelope: IEnvelope;
/**
* A copy of the recipient record related to the signing session. This is almost always needed when
* a signing session is being started, so it is included here for convenience.
*/
recipient: IRecipient;
}
interface IUpdateRecipientSubmitParams {
action: "submit";
}
interface IUpdateRecipientDeclineParams {
action: "decline";
}
interface IUpdateRecipientClaimEnvelope {
action: "owner_update";
first_name: string;
last_name: string;
email: string;
}
interface IUpdateRecipientStatus {
first_name?: string;
last_name?: string;
agreed?: boolean;
action?: "prepare" | "update";
}
interface IUpdateRecipientAgreedParams {
action: "update";
agreed: boolean;
}
interface IUpdateRecipientNameParams {
action: "update";
first_name: string;
last_name: string;
}
interface IUpdateRecipientPrepareParams {
action: "prepare";
recipients: IRecipient[];
}
interface ICreateEnvelopeReminderRequest {
setup_time: number;
interval_time: number;
}
interface ICreateEnvelopeFromTemplateRequest {
template_id: string;
recipients: ICreateEnvelopeRecipient[];
name?: string;
description?: string;
fields?: Pick<IEnvelopeField, "name" | "role_name" | "default">[];
environment?: string;
no_contact?: boolean;
/** Override the sender name of the envelope in email and other notifications. NOTE: To prevent spam