@verdocs/js-sdk 3.3.2 → 3.6.0

package/Envelopes/Envelopes.d.ts

@@ -1,4 +1,4 @@
-import { IEnvelope, IEnvelopesSummary, IRecipient, IDocumentFieldSettings, IEnvelopeDocument } from './Types';
+import { IEnvelope, IEnvelopesSummary, IRecipient, IEnvelopeDocument, IEnvelopeFieldSettings } from './Types';
 import { ICreateEnvelopeRole, IEnvelopesSearchResult, ISigningSessionRequest } from './Types';
 import { TEnvelopeUpdateResult, TEnvelopeStatus, TRecipientStatus } from './Types';
 import { VerdocsEndpoint } from '../VerdocsEndpoint';
@@ -167,17 +167,17 @@ export declare const getEnvelopeFile: (endpoint: VerdocsEndpoint, envelopeId: st
 /**
  * Update a Document field. Typically called during the signing process as a Recipient fills in fields.
  */
-export declare const updateEnvelopeField: (endpoint: VerdocsEndpoint, envelopeId: string, fieldName: string, value: any) => Promise<IDocumentFieldSettings>;
+export declare const updateEnvelopeField: (endpoint: VerdocsEndpoint, envelopeId: string, fieldName: string, value: any) => Promise<IEnvelopeFieldSettings>;
 /**
  * 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.
  */
-export declare const updateEnvelopeFieldSignature: (endpoint: VerdocsEndpoint, envelopeId: string, fieldName: string, signatureId: string) => Promise<IDocumentFieldSettings>;
+export declare const updateEnvelopeFieldSignature: (endpoint: VerdocsEndpoint, envelopeId: string, fieldName: string, signatureId: string) => Promise<IEnvelopeFieldSettings>;
 /**
  * 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.
  */
-export declare const updateEnvelopeFieldInitials: (endpoint: VerdocsEndpoint, envelopeId: string, fieldName: string, initialId: string) => Promise<IDocumentFieldSettings>;
+export declare const updateEnvelopeFieldInitials: (endpoint: VerdocsEndpoint, envelopeId: string, fieldName: string, initialId: string) => Promise<IEnvelopeFieldSettings>;
 /**
  * Get the attached file for an attachment field (if any)
  */

package/Envelopes/Types.d.ts

@@ -134,7 +134,7 @@ export interface IRecipient {
     status: TRecipientStatus;
     type: TRecipientType;
     updated_at: string;
-    fields?: IDocumentField[];
+    fields?: IEnvelopeField[];
 }
 export interface IEnvelopeDocument {
     id: string;
@@ -148,7 +148,7 @@ export interface IEnvelopeDocument {
     created_at: string;
     updated_at: string;
 }
-export interface IDocumentFieldOptions {
+export 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. */
@@ -162,7 +162,7 @@ export interface IDocumentFieldOptions {
     /** The visible label for the field e.g. 'Not Applicable' */
     value: string;
 }
-export interface IDocumentFieldSettings {
+export interface IEnvelopeFieldSettings {
     type?: string;
     x: number;
     y: number;
@@ -176,7 +176,7 @@ export interface IDocumentFieldSettings {
     alignment?: number;
     upperCase?: boolean;
     /** Dropdowns, checkboxes, radio groups */
-    options?: IDocumentFieldOptions[];
+    options?: IEnvelopeFieldOptions[];
     /** Signatures and Initials, result will be "signed" */
     base64?: string;
     hash?: string;
@@ -202,9 +202,9 @@ export declare enum DocumentFieldTypes {
     PAYMENT = "payment"
 }
 export type TDocumentFieldType = `${DocumentFieldTypes}`;
-export interface IDocumentField {
+export interface IEnvelopeField {
     /**
-     * The ID of the document the field is for. For historical reasons, this is called `envelope_id` because documents
+     * The ID of the envelope the field is for. For historical reasons, this is called `envelope_id` because documents
      * were previously called envelopes.
      */
     envelope_id: string;
@@ -220,10 +220,26 @@ export interface IDocumentField {
     type: TDocumentFieldType;
     /** If true, the field will be required */
     required: boolean;
-    settings?: IDocumentFieldSettings;
+    settings?: IEnvelopeFieldSettings;
     validator: string | null;
     /** Not sent by the server. Used in the UI to identify prepared fields. */
     prepared?: boolean;
+    /** If set, the tab index for the field. */
+    tabindex: 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;
+    /** The placeholder to show in the field. */
+    placeholder?: string;
+    /** For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name. */
+    group?: string;
 }
 /**
  * An Envelope is a workflow wrapper that shepherds one or more Documents through the various recipients in a signing
@@ -255,7 +271,7 @@ export interface IEnvelope {
     document?: IEnvelopeDocument | null;
     /** Documents attached to this envelope */
     documents?: IEnvelopeDocument[] | null;
-    fields?: IDocumentField[];
+    fields?: IEnvelopeField[];
 }
 export type TEnvelopeUpdateResult = Omit<IEnvelope, 'histories' | 'recipients' | 'certificate' | 'document' | 'fields' | 'profile'>;
 export interface IActivityEntry {

package/Templates/TemplateDocuments.js

@@ -81,7 +81,7 @@ export var createTemplateDocument = function (endpoint, templateId, file, onUplo
     formData.append('document', file, file.name);
     return endpoint.api //
         .post("/templates/".concat(templateId, "/documents"), formData, {
-        timeout: 60000,
+        timeout: 120000,
         onUploadProgress: function (event) {
             var total = event.total || 1;
             var loaded = event.loaded || 0;

package/Templates/Templates.d.ts

@@ -4,7 +4,7 @@
  *
  * @module
  */
-import { ITemplate, ITemplateOwnerInfo, ITemplatesSearchResult, ITemplatesSummary, TTemplateSender } from './Types';
+import { IRole, ITemplate, ITemplateField, ITemplateOwnerInfo, ITemplatesSearchResult, ITemplatesSummary, TTemplateSender } from './Types';
 import { VerdocsEndpoint } from '../VerdocsEndpoint';
 export interface IGetTemplatesParams {
     is_starred?: boolean;
@@ -44,12 +44,58 @@ export declare const getTemplate: (endpoint: VerdocsEndpoint, templateId: string
  * ```
  */
 export declare const getTemplateOwnerInfo: (endpoint: VerdocsEndpoint, templateId: string) => Promise<ITemplateOwnerInfo>;
+/**
+ * Represents a document to be attached to a template via an externally-accessible URI. A copy of the document will be
+ * downloaded from the specified URI. Note that the URI will be accessed without headers or other authorization methods
+ * set, so the URI itself must encode any security tokens or keys required to access the file.
+ */
+export interface IDocumentFromUri {
+    /** The URI to retrieve the file from. */
+    uri: string;
+    /** A name for the attachment. */
+    name: string;
+}
+/**
+ * Represents a document to be attached to a template via a Base64-encoded string attachment. This is the best option
+ * for maximum security but there is a 10MB size limit for the entire creation request. Requests attaching larger files
+ * should use `IDocumentFromUri` or add attachments via `createTemplateDocument` after creating the template.
+ */
+export interface IDocumentFromData {
+    /** Base64-encoded file data. */
+    data: string;
+    /** A name for the attachment. */
+    name: string;
+}
 export interface ITemplateCreateParams {
+    /** Name for the template to create. */
     name: string;
+    /**
+     * Optional (defaults to true). Personal templates are only visible to the owner. Non-personal templates are shared
+     * within the user's organization.
+     */
     is_personal?: boolean;
+    /**
+     * Optional (defaults to false). Public templates may be found (via search) and viewed by anyone.
+     */
     is_public?: boolean;
+    /** Optional (defaults to EVERYONE_AS_CREATOR). Who may create and send envelopes using this template. */
     sender?: TTemplateSender;
+    /** Optional description for the template to help identify it. */
     description?: string;
+    /**
+     * Optional list of roles to create. Documents are required if roles or fields will also be specified. Files may
+     * be attached via a number of methods (browser File object, remote URI reference, or Base64-encoded string) but
+     * all entries must of of the same type.
+     */
+    documents?: File[] | IDocumentFromUri[] | IDocumentFromData[];
+    /**
+     * Optional list of roles to create. Note that if roles are not included in the request, fields will be ignored.
+     */
+    roles?: IRole[];
+    /**
+     * Optional list of fields to create.
+     */
+    fields?: ITemplateField[];
 }
 /**
  * Create a template.
@@ -60,7 +106,7 @@ export interface ITemplateCreateParams {
  * const newTemplate = await Templates.createTemplate((VerdocsEndpoint.getDefault(), {...});
  * ```
  */
-export declare const createTemplate: (endpoint: VerdocsEndpoint, params: ITemplateCreateParams) => Promise<ITemplate>;
+export declare const createTemplate: (endpoint: VerdocsEndpoint, params: ITemplateCreateParams, onUploadProgress?: ((percent: number, loadedBytes: number, totalBytes: number) => void) | undefined) => Promise<ITemplate>;
 /**
  * Update a template.
  *

package/Templates/Templates.js

@@ -85,6 +85,15 @@ export var getTemplateOwnerInfo = function (endpoint, templateId) {
         .get("/templates/".concat(templateId))
         .then(function (r) { return r.data; });
 };
+var ALLOWED_CREATE_FIELDS = [
+    'name',
+    'is_personal',
+    'is_public',
+    'sender',
+    'description',
+    'roles',
+    'fields',
+];
 /**
  * Create a template.
  *
@@ -94,10 +103,33 @@ export var getTemplateOwnerInfo = function (endpoint, templateId) {
  * const newTemplate = await Templates.createTemplate((VerdocsEndpoint.getDefault(), {...});
  * ```
  */
-export var createTemplate = function (endpoint, params) {
-    return endpoint.api //
-        .post('/templates/', params)
-        .then(function (r) { return r.data; });
+export var createTemplate = function (endpoint, params, onUploadProgress) {
+    var options = {
+        timeout: 120000,
+        onUploadProgress: function (event) {
+            var total = event.total || 1;
+            var loaded = event.loaded || 0;
+            onUploadProgress === null || onUploadProgress === void 0 ? void 0 : onUploadProgress(Math.floor((loaded * 100) / (total || 1)), loaded, total || 1);
+        },
+    };
+    if (params.documents && params.documents[0] instanceof File) {
+        if (params.documents.length > 10) {
+            throw new Error('createTemplate() has a maximum of 10 documents that can be attached.');
+        }
+        var formData_1 = new FormData();
+        ALLOWED_CREATE_FIELDS.forEach(function (allowedKey) {
+            if (params[allowedKey] !== undefined) {
+                formData_1.append(allowedKey, params[allowedKey]);
+            }
+        });
+        params.documents.forEach(function (file) {
+            formData_1.append('documents', file, file.name);
+        });
+        return endpoint.api.post('/templates', formData_1, options).then(function (r) { return r.data; });
+    }
+    else {
+        return endpoint.api.post('/templates', params, options).then(function (r) { return r.data; });
+    }
 };
 /**
  * Update a template.

package/Templates/Types.d.ts

@@ -88,6 +88,7 @@ export interface ITemplate {
     roles?: IRole[];
     /**
      * Pages attached to the template. Note that this is all of the pages for all document attachments in sequential order.
+     * @deprecated. Use document page counts instead, and accessor functions that take page numbers rather than Page objects.
      */
     pages?: IPage[];
     /**
@@ -253,8 +254,14 @@ export interface ITemplateDocument {
     pages?: IPage[];
 }
 export interface ITemplateField {
+    /** The machine name of the field, e.g. `checkbox_groupP1-18` */
     name: string;
+    /** The ID of the role in the recipients list, e.g. `Recipient 2` */
     role_name: string;
+    /**
+     * The ID of the document the field is for. For historical reasons, this is called `envelope_id` because documents
+     * were previously called envelopes.
+     */
     template_id: string;
     type: TDocumentFieldType;
     required: boolean;
@@ -262,6 +269,22 @@ export interface ITemplateField {
     page_sequence: number;
     validator?: string;
     label?: string;
+    /** If set, the tab index for the field. */
+    tabindex: 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;
+    /** The placeholder to show in the field. */
+    placeholder?: string;
+    /** For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name. */
+    group?: string;
 }
 export interface ITextFieldSetting {
     x: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verdocs/js-sdk",
-  "version": "3.3.2",
+  "version": "3.6.0",
   "private": false,
   "homepage": "https://github.com/Verdocs/js-sdk",
   "description": "Verdocs JS SDK",
@@ -35,7 +35,6 @@
     "lint": "tslint -p tsconfig.json",
     "docs-md": "typedoc --tsconfig ./tsconfig-typedoc.json",
     "docs-html": "typedoc --tsconfig ./tsconfig-typedoc.json --plugin none --out docs-html",
-    "Xdocs-html": "typedoc --tsconfig ./tsconfig-typedoc.json --plugin ./typedoc-theme.tsx --out docs-html",
     "docs": "npm run docs-md && npm run docs-html",
     "clear-docs": "aws --profile=verdocs cloudfront create-invalidation --distribution-id E29UFGU4KEH1GQ --paths \"/*\"",
     "deploy-docs": "npm run docs && aws --profile=verdocs s3 sync --acl public-read --delete docs-html s3://verdocs-developers-js-sdk/ && yarn clear-docs",