Client library for the Draftable document comparison API
npm install @draftable/compare-apiDraftable Compare API - Node.js Client Library
==============================================






A thin JavaScript client for the Draftable API which wraps all available endpoints and handles authentication and signing.
See the full API documentation for an introduction to the API, usage notes, and other reference material.
- Requirements
- Getting started
- API reference
- Initializing the client
- Retrieving comparisons
- Deleting comparisons
- Creating comparisons
- Displaying comparisons
- Exporting comparisons
- Utility functions
- Other information
- Browser support
- Self-signed certificates
- License
Requirements
------------
- Operating system: Any maintained Linux, macOS, or Windows release
- Node.js runtime: Any maintained version
Getting started
---------------
- Create a free API account
- Retrieve your credentials
- Install the library
``sh
`
npm install @draftable/compare-api
`
- Instantiate a client
js
`
var client = require('@draftable/compare-api').client('
var comparisons = client.comparisons;
`
- Start creating comparisons
js
`
comparisons.create({
left: {
source: 'https://api.draftable.com/static/test-documents/code-of-conduct/left.rtf',
fileType: 'rtf',
},
right: {
source: 'https://api.draftable.com/static/test-documents/code-of-conduct/right.pdf',
fileType: 'pdf',
},
}).then(function(comparison) {
console.log("Comparison created: %s", comparison);
// Generate a signed viewer URL to access the private comparison. The expiry
// time defaults to 30 minutes if the valid_until parameter is not provided.
const viewerURL = comparisons.signedViewerURL(comparison.identifier);
console.log("Viewer URL (expires in 30 mins): %s", viewerURL);
});
Comparison
API reference
-------------
- All API requests return _Promises_:
- Successful calls that return data resolve to objects
null
- Successful calls that return no data resolve to (e.g. a DELETE request)
Promise
- Calls which fail for any reason will reject the with an Error object
Client
$3
The package exports a function to create a for your API account.
Client
provides a comparisons property which yields a ComparisonsClient to manage the comparisons for your API account.
Client
Creating a differs slightly based on the API endpoint being used:
`
js
`
// Draftable API (default endpoint)
var comparisons = require('@draftable/compare-api').client(
'
'
).comparisons;
// Draftable API regional endpoint or Self-hosted
var comparisons = require('@draftable/compare-api').client(
'
'
'https://draftable.example.com/api/v1' // Replace with the endpoint URL
).comparisons;
getAll()
For API Self-hosted you may need to suppress TLS certificate validation if the server is using a self-signed certificate (the default).
$3
-
Promise
Returns a which resolves to a list of all your comparisons, ordered from newest to oldest. This is potentially an expensive operation.
get(identifier: string)
-
Promise
Returns a which resolves to the specified Comparison or rejects if the specified comparison identifier does not exist.
Comparison
objects have the following properties:
identifier: string
-
left: object
The unique identifier of the comparison
- / right: object
fileType: string
Information about each side of the comparison
-
sourceURL: string
The file extension
- _(optional)_
displayName: string
The URL for the file if the original request was specified by URL
- _(optional)_
publiclyAccessible: boolean
The display name for the file if given in the original request
-
creationTime: Date
Indicates if the comparison is public
-
expiryTime: Date
Time in UTC when the comparison was created
- _(optional)_
ready: boolean
The expiry time if the comparison is set to expire
-
Comparison
Indicates if the comparison is ready to display
If a is _ready_ (i.e. it has been processed) it has the following additional properties:
failed: boolean
-
errorMessage: string
Indicates if comparison processing failed
- _(only present if failed)_
`
Reason processing of the comparison failed
#### Example usage
js
`
var identifier = '
comparisons.get(identifier).then(function(comparison) {
const visibility = comparison.publiclyAccessible ? 'private' : 'public';
const status = comparison.ready ? 'ready' : 'not ready';
console.log("Comparison '%s' (%s) is %s.", comparison.identifier, visibility, status);
if (comparison.ready && comparison.failed) {
console.log("The comparison failed with error: %s", comparison.errorMessage);
}
});
destroy(identifier: string)
$3
-
Promise
Returns a which resolves on successfully deleting the specified comparison or rejects if no such comparison exists.
`
#### Example usage
js
`
comparisons.getAll().then(function(oldest_comparisons) {
console.log("Deleting oldest 10 comparisons ...");
const deleteStartIndex = Math.max(0, oldest_comparisons.length - 10);
for (let i = deleteStartIndex; i < oldest_comparisons.length; ++i) {
const identifier = oldest_comparisons[i].identifier;
comparisons.destroy(identifier).then(function() {
console.log("Comparison '%s' deleted.", identifier);
});
}
});
create(options)
$3
-
Promise
Returns a which resolves to a new Comparison object.
options
consists of the following parameters:
left: object
- / right: object
identifier: string
Describes the left and right files (see below)
- _(optional)_
publiclyAccessible: boolean
Identifier to use for the comparison:
- If specified, the identifier must be unique (i.e. not already be in use)
- If unspecified, the API will automatically generate a unique identifier
- _(optional)_
false
Specifies the comparison visibility:
- If or unspecified authentication is required to view the comparison
true
- If the comparison can be accessed by anyone with knowledge of the URL
expires: Date | string
- _(optional)_
Date
Time at which the comparison will be deleted:
- Must be specified as a object or a string which can be parsed by Date.parse
options.left
- If specified, the provided expiry time must be UTC and in the future
- If unspecified, the comparison will never expire (but may be explicitly deleted)
and options.right consist of the following parameters:
source: buffer | string
-
buffer
Specifies the source for this side of the comparison:
- If provided as a , contains the file data (e.g. {source: fs.readFileSync('path/to/file')})
string
- If provided as a , the URL from which the server will download the file (e.g. {source: 'https://example.com/path/to/file'})
fileType: string
-
pdf
The type of file being submitted:
- PDF:
docx
- Word: , docm, doc, rtf
pptx
- PowerPoint: , pptm, ppt
txt
- Text:
displayName: string
- _(optional)_
`
The name of the file shown in the comparison viewer
#### Example usage
js
`
var identifier = comparisons.generateIdentifier();
comparisons.create({
identifier: identifier,
left: {
source: 'https://domain.com/left.pdf',
fileType: 'pdf',
displayName: 'Document.pdf',
},
right: {
source: fs.readFileSync('path/to/right/file.docx'),
fileType: 'docx',
displayName: 'Document (revised).docx',
},
// Expire this comparison in 2 hours (default is no expiry)
expires: new Date(Date.now() + 1000 60 120),
}).then(function(comparison) {
console.log("Created comparison: %s", comparison);
});
publicViewerURL(identifier: string, wait?: boolean)
$3
-
signedViewerURL(identifier: string, valid_until?: Date | string, wait?: boolean)
Generates a public viewer URL for the specified comparison
-
identifier
Generates a signed viewer URL for the specified comparison
Both functions use the following common parameters:
-
wait
Identifier of the comparison for which to generate a _viewer URL_
- _(optional)_
false
Specifies the behaviour of the viewer if the provided comparison does not exist
- If or unspecified, the viewer will show an error if the identifier does not exist
true
- If , the viewer will wait for a comparison with the provided identifier to exist
identifier
Note this will result in a perpetual loading animation if the is never created
signedViewerURL
The function also supports the following parameters:
valid_until
- _(optional)_
Date
Time at which the URL will expire (no longer load)
- Must be specified as a object or a string which can be parsed by Date.parse
`
- If specified, the provided expiry time must be UTC and in the future
- If unspecified, the URL will be generated with the default 30 minute expiry
See the displaying comparisons section in the API documentation for additional details.
#### Example usage
js
`
var identifier = '
// Retrieve a signed viewer URL which is valid for 1 hour. The viewer will wait
// for the comparison to exist in the event processing has not yet completed.
var valid_until = new Date(Date.now() + 1000 60 60)
var viewerURL = comparisons.signedViewerURL(identifier, valid_until, true);
console.log("Viewer URL (expires in 1 hour): %s", viewerURL);
Export
$3
Export the comparison to PDF by sending the comparison identifier along with the requested export kind.
- Four export kinds are supported.
- single_page: Displays the right side document only with highlights and deletion markers showing the diff
- combined: Displays both right and left sides
- left: Displays left side only
- right: Displays right side only
After creating the export, you must poll using the export identifier to obtain the URL of the exported document.
objects have the following properties:
identifier: string
-
comparison: string
The unique identifier of the export
-
url: string
The unique identifier of the comparison
-
kind: string
The URL for the file if the original request was specified by URL
-
single_page
The export kind, one of the following , combined, left or right
ready: boolean
-
failed: boolean
Indicates if the export is ready to get
-
`
Indicates if the export failed
#### Export example usage
Post request of the export
js
`
client.exports
.requestExport({
comparison: "
kind: "combined",
include_cover_page: false,
})
.then((result: ExportResult) => {
console.log(result);
}
`
Get requested export
js
`
client.exports.get(requestResponse.identifier).then((result: ExportResult) => {
console.log(result);
});
generateIdentifier()
$3
-
NODE_TLS_REJECT_UNAUTHORIZED
Generates a random unique comparison identifier
Other information
-----------------
$3
This library is designed primarily for server-side usage. Usage in web browsers (client-side) is not currently supported.
Calling the Draftable API via client-side JavaScript is generally discouraged as this implies sharing API credentials with end-users.
$3
If connecting to an API Self-hosted endpoint which is using a self-signed certificate (the default) you will need to suppress certificate validation. This can be done by setting the environment variable to 0.
`
See the below examples for different operating systems and shell environments. Note that all examples only set the variable for the running shell and it will not persist. To persist the setting consult the documentation for your shell environment. This should be done with caution as this setting suppresses certificate validation for all connections made by the Node.js runtime!
(ba)sh (Linux, macOS, WSL)
sh
`
export NODE_TLS_REJECT_UNAUTHORIZED=0
`
PowerShell:
posh
`
$env:NODE_TLS_REJECT_UNAUTHORIZED=0
`
Command Prompt (Windows):
cmd
``
SET NODE_TLS_REJECT_UNAUTHORIZED=0
Setting this environment variable in production environments is strongly discouraged as it significantly lowers security. We only recommend setting this environment variable in development environments if configuring a CA signed certificate for API Self-hosted is not possible.
License
-------
All content is licensed under the terms of The MIT License.