Options
All
  • Public
  • Public/Protected
  • All
Menu

@octosign/client

Index

Type aliases

Functions

Type aliases

ApiClientConfiguration

ApiClientConfiguration: { customProtocol?: string; disableSecurity?: boolean; requestsOrigin?: string; secretInitialNonce?: number; secretKey?: string; serverHost?: string; serverPort?: number; serverProtocol?: "http" | "https" }

Client configuration options.

Type declaration

  • Optional Readonly customProtocol?: string

    Custom protocol used with the application, e.g., to launch it - signer://listen.

    Defaults to 'signer'.

  • Optional Readonly disableSecurity?: boolean

    Disables using of HMAC in messages and sets requestsOrigin to *

    Make sure you understand the implications on the security!

    Defaults to false.

  • Optional Readonly requestsOrigin?: string

    Origin the server will be asked to trust

    Influences generated launch URL that sets trusted origin

    Defaults to the current location origin, e.g. 'https://example.com' if available, '*' otherwise.

  • Optional Readonly secretInitialNonce?: number

    Secret initial nonce used for the communication.

    Should be cryptographically secure random 32-bit integer generated separately for each session. You can generate this number on the server side and set it on the session so its reused across navigation. There is no need to configure this unless you know what you are doing.

    Defaults to random integer generated on instantiation.

  • Optional Readonly secretKey?: string

    Secret key used for the communication.

    Should be cryptographically secure random hex string generated separately for each session. You can generate this key on the server side and set it on the session so its reused across navigation. There is no need to configure this unless you know what you are doing.

    Defaults to random 64-char (256-bit) hex string generated on instantiation.

  • Optional Readonly serverHost?: string

    Host of the server - Octosign White Label

    Defaults to '127.0.0.1'

  • Optional Readonly serverPort?: number

    Port of the server - Octosign White Label

    Influences also the URL generated to launch the application.

    Defaults to 37200

  • Optional Readonly serverProtocol?: "http" | "https"

    Protocol of the server - Octosign White Label

    Defaults to 'http'

Document

Document: { content: string; id?: string; legalEffect?: string; title?: string }

Document exchanged during the signing.

Type declaration

  • Readonly content: string

    Document content for signing.

    Can be plaintext in the case of XML base64-encoded binary in the case of any format.

  • Optional Readonly id?: string

    Optional ID you can use to identify your document.

  • Optional Readonly legalEffect?: string

    Optional legal effect shown to user next to the signing button.

  • Optional Readonly title?: string

    Optional title shown during signing.

ServerInfo

ServerInfo: { status: "LOADING" | "READY"; version: string }

Info about the server and its current state.

Type declaration

  • Readonly status: "LOADING" | "READY"

    Current server status.

  • Readonly version: string

    Version of the Octosign White Label.

    Should follow semantic versioning.

SignatureParameters

SignatureParameters: { format: "PADES" | "XADES" }

Parameters used to create a signature.

Type declaration

  • Readonly format: "PADES" | "XADES"

    Signature format PAdES is usable only with documents of type application/pdf. Format XAdES is usable with XML or with any file type if using an ASiC container.

Functions

apiClient

  • apiClient(options?: ApiClientConfiguration): { getLaunchURL: any; info: any; sign: any; waitForStatus: any }

  • Octosign White Label API client for the app running in the server mode.

    Example (es module and async/await)

     
    import { apiClient } from '@octosign/client';
const client = apiClient();

// Launch URL that should be used by user to launch the signer application
console.log(client.getLaunchURL());

await client.waitForStatus('READY');

const content = '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title></Document>';
console.log(await client.sign({ content }));
// => { content: '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title>...</Document>' }

    All further examples use es module and async/await, but the library can be also used as commonjs module and using promises.

    Example (commonjs and promises)

     
    var apiClient = require('@octosign/client').apiClient;
var client = apiClient();

console.log(client.getLaunchURL());

client.waitForStatus('READY')
  .then(function() {
    var content = '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title></Document>';
    return client.sign({ content: content });
  })
  .then(function(signedDocument) {
    console.log(signedDocument);
    // => { content: '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title>...signature...</Document>' }
  });

    Parameters

    Returns { getLaunchURL: any; info: any; sign: any; waitForStatus: any }

    An instance of API client.

    • getLaunchURL: function
      • getLaunchURL(command?: "listen"): string

      • Construct custom protocol launch URI that can be opened by user to launch the application.

        Example

         
        import { apiClient } from '@octosign/client';
const client = apiClient();
console.log(client.createLaunchURI());
// => signer://listen/37200/https%3A%2F%2Fexample.com/3a2bca8d73c62e75177fa877de283cc0c96cdf3ba08f8eb878a96da93de3d798/260372071

        Parameters

        • command: "listen" = 'listen'

        Returns string

        URL that can be opened by the user.

    • info: function

      • Retrieve server info with its current state.

        Example

         
        import { apiClient } from '@octosign/client';
const client = apiClient();
console.log(await client.info());
// => { version: '1.2.3', status: 'READY' }

        Returns Promise<ServerInfo>

        Info about the server and its current state.

    • sign: function

      • Sign a document.

        Example

         
        import { apiClient } from '@octosign/client';
const client = apiClient();

console.log(await client.sign({ content: '<?xml version="1.0"?><Document><Title>Lorem Ipsum</Title></Document>' }));
// => { content: '...signed document...' }

        Parameters

        • document: Document
        • signatureParameters: SignatureParameters = ...

          Optional signature parameters.

        • payloadMimeType: string = 'application/xml'

          Optional payload mime type, defaults to 'application/xml' - plaintext XML. Must reflect document content type so should be changed if content is not a plaintext XML.

        Returns Promise<Document>

        Signed document.

    • waitForStatus: function
      • waitForStatus(status: "LOADING" | "READY", timeout?: number, delay?: number): Promise<ServerInfo>

      • Wait for server to be in the requested state.

        Repeatedly tries to get server info retrying

        Example

         
        import { apiClient } from '@octosign/client';
const client = apiClient();
await client.waitForStatus('READY');
// => { version: '1.2.3', status: 'READY' }

        Parameters

        • status: "LOADING" | "READY"

          Wanted status of the server.

        • timeout: number = 60

          Timeout in seconds before giving up and rejecting with error.

        • delay: number = 4

          Delay before making next attempt after failure.

        Returns Promise<ServerInfo>

        Info about the server and its current state.

Generated using TypeDoc