Legalesign Typescript / Javascript SDK

The Typescript SDK is provided as an ease-of-use extension to the Legalesign GraphQL library. Both the SDK and the test library are provided with the minimum framework installations, as we want you to be able to be able to use this or a version of the SDK as easily as possible on any platform.

If you need help integrating this SDK with your platform please get in touch with our support team [email protected] or post your question in the issues log of this repository.

Types

The SDK contains a tested type library of the Legalesign platform (document, template, etc.) for you to use in your integrations. Sometimes these can be helpful even if you don't use the SDK api call framework.

import { Document } from "legalesign-sdk-js";

or alias it in case you are using other packages that contain Document exports with

import { Document as LegalesignDocument } from "legalesign-sdk-js";

Installation

In the root of your project use the following to install the SDK;

npm install legalesign-sdk-js

then use the following in the header of your code

import Legalesign from 'legalesign-sdk-js'

Testing / Examples

If you need help using the SDK, you can find examples for most calls in the test library legalesign-sdk-js-test. This is also a useful way to test some of the basic setup of your account. Let run through a basic send to give you an idea how it works (remember you can find many more in the test project). Most e-signature developers will need to use (and possibly reuse) a template, document or group for one of their automations. The code that follows is aimed at getting you started with simple implementations to perform common tasks.

The Typescript SDK is provided as an ease-of-use extension to the Legalesign GraphQL library. Both the SDK and the test library are provided with the minimum framework installations, as we want you to be able to be able to use this or a version of the SDK as easily as possible on any platform.

If you need help integrating this SDK with your platform please get in touch with our support team [email protected] or post to the issues log of this repository.

IMPORTANT SECURITY NOTE : This SDK is intended to be used with server-side technologies, i.e. so that no credentials are exposed to the outside world. As such it is ideal for an AWS lambda function, node process or Next SSR element but NOT in a client side web page. If you're at all in doubt, get in touch with us.

Installation

In the root of your project use the following to install the SDK;

npm install legalesign-sdk-js

then use the following in the header of your code

import Legalesign from 'legalesign-sdk-js'

The Basics

All actions performed through the SDK utilise the Legalesign class which handles acquiring security credentials. The type of action want will determine which of the object extensions you should use selector, downloader, factory, sender or uploader.

selector

Provides the ability to retrieve data and supplies some shortcut methods to frequently used task, such as providing a list of groups. Also allows freeform GraphQL queries and mutations.

sender

Validates and packages various send methods including single document, multiple document and bulk send.

uploader

Allows the programmer to add new templates and other file formats to their group.

downloader

Does what it says on the tin. You pass in objects that contain the file link and it downloads the file to the location you specify.

factory

Allows you to archive or restore an object.

Types

The SDK contains a tested layout of the core types on the Legalesign platform (document, template, etc.) for you to use in your integrations. Sometimes these can be helpful even if you don't use the SDK api call framework.

import { Document } from "@legalesign-sdk-js";

or alias it in case you are using other packages that contain Document exports with

import { Document as LegalesignDocument } from "@legalesign-sdk-js";

Testing / Examples

If you need help using the SDK, you can find examples for most calls in the test library @legalesign/sdk-test. This is also a useful way to test some of the basic setup of your account.

git clone legalesign-sdk-tests https://github.com/legalesign/legalesign-sdk-test.git

Send an Existing Template

In a node project with the @legalesign-sdk-js installed include the following code

import { Legalesign, SendOptions, Recipient } from "legalesign-sdk-js";

const lesign = new Legalesign({
  organisationId: "b3XXXXX",
  options: {
    apiUser: "[email protected]",
    apiPassword: "yourapipassword",
  },
});

const recipient: Recipient = {
  email: "[email protected]",
  firstName: "Sidney",
  lastName: "Lawrence",
};

  const sendOptions: SendOptions = {
    title: "SDK Test Simple Send",
    groupId: "Z3GROUPID",
    templateId: "dHBTEMPLATEID",
    recipients: [recipient],
  };

const response = await lesign.sender.send(sendOptions);

You can find a version of this in the @legalesign/sdk-test project.

Note that in this version we assume that the groupId and the templateId that you're using are static so you can simply look up the ids through (console.legalesign.com). If this isn't the case then you might need to use the SDK to get the lists of templates or groups available to your API user. The example also assumes that you've locked the template - otherwise there is the chance that alterations may have made it invalid to send.

In order to find out if the sending process succeeded you'll need to monitor the status of the document and the events sent back to you. Depending on your integration the example code may be enough for you, but the next example will show you how to check on a document.

Retrieve Document Details

Another common task is to check on the status of an existing document. The SDK simplifies calls for core API objects so that you don't need to create your own graphQL queries.

This example fetches all the details for the document with the given ID (remember to test you can get API ids of templates and documents from the Console):

  const result = await lesign.selector.getDocument(
    "ZG9jYWU1MjFiMDItYTAxYy0xMWVmLTg4OWItMDXNm"
  );

  console.log(result?.status);

And this listing helper in selector helps you to get the latest documents:

  const result = await lesign.selector.listTopDocuments("Z3JwZG1234=", 20);

Receive Events

Reuse a Draft

Often you'll already know a lot of the details that you want to apply to your send task. The easiest way to store this so that they can be altered /without changing your code later/ is to create a draft object inside the Legalesign platform. This is a JSON version of all the parameters required to send one or more documents with all the recipients and prefilled fields which it might require.

To see how this is done go into console.legalesign.com and start the preparations to send your target template. Before sending click in the top left corner and choose Save As Draft. This will take all the information that you've applied and stash it away. The console will take you to the Drafts listing and your new draft will appear once it has been generated by the system.

Grab the ID of the draft so that we can use it in this integration.