LEAP Host SDK

LEAP Host SDK is a TypeScript library that helps your LEAP apps communicate easily with LEAP client applications.

How to install

This library should be installed as an npm package. We use semantic versioning so the best way to stay up-to-date without backward compatibility concern is to accept minor releases:

npm i @leapdev/leap-host

Breaking changes in 4.0.0

Version 4.0.0 is a major release. Review the items below before upgrading from 3.x.

document.selectPrecedent() response is now camelCase on LEAP Desktop

On LEAP Desktop, document.selectPrecedent() previously returned the raw host response with PascalCase property names (for example RecordId, ParentId, DocumentType). The SDK now normalises the response to camelCase (for example recordId, parentId, documentType) to match the SelectPrecedentResponse TypeScript interface and LEAP Web behaviour.

If your app reads properties directly from the selectPrecedent response, update property access to camelCase:

// Before (3.x on LEAP Desktop)
const response = await sdk.document.selectPrecedent(request);
const id = response.RecordId;

// After (4.0)
const response = await sdk.document.selectPrecedent(request);
const id = response.recordId;

New in 4.0.0

• sdk.leapContext.hostInfo.accessibility — accessibility settings from the host (font scale, theme, high contrast, reduced motion, and more), available after init() and on context updates.
• document.createDocumentBasedOnURL() — create a document in LEAP from a remote URL.
• subscribeContextUpdate() / unsubscribeContextUpdate() — listen for host context changes with automatic sdk.leapContext updates.

How to use

In order to have all the features supported, please develop with the latest LEAP desktop 2.3 or above

The first thing you have to do is to initialise the SDK

import { LeapHostSdkFactory } from '@leapdev/leap-host';

const sdk = LeapHostSdkFactory.getInstance();
if (!!sdk) {
  await sdk.init('LEAP auth clientId');
  // IMPORTANT: please make sure you are using the correct clientId we provide for your app
}

This init function returns a Promise. We recommend that you do this initialisation once and cache the promise result in memory.

By awaiting the promise, you then have access to methods that perform actions in the LEAP client applications. Please refer to the API reference for all supported methods.

Subscribing to context updates

The SDK keeps sdk.leapContext up to date automatically. Register a callback if your app needs to react when the host context changes:

sdk.subscribeContextUpdate(
  (leapContext) => console.log(leapContext),
  (error) => console.error(error)
);

TL;DR

Abstracting LEAP context retrieval

A LEAP app needs to know the context of where its being loaded, e.g. the matterId where it is loaded, which record is being selected (if the current page in LEAP is a list), etc. The LEAP app is expected to retrieve the context object from the hosting LEAP client application. A connection between the LEAP client application and LEAP app is assigned a unique guid. The LEAP app can access this value via "appSessionId" property received.

The LEAP Host SDK abstracts the context retrieval process by presenting a unified API to the LEAP app. By calling the init function, the LEAP app will have access to the context object as follow.

import { LeapHostSdkFactory } from '@leapdev/leap-host';

const sdk = LeapHostSdkFactory.getInstance();
if (!!sdk) {
  await sdk.init('LEAP auth clientId');
  console.log(sdk.leapContext);
}

Obtaining LEAP Auth token

A LEAP app often needs to call the LEAP API Gateway services. To do so, you will need to init the sdk first then call the method below

// for best practise, just call this method whenever you need to use the access token, caching it is not recommeded
const accessToken = await sdk.getRefreshedAccessToken();

// or if you want to get the claims in the token you can go
const decodedAccessToken = await sdk.getDecodedRefreshedAccessToken();

Sending a command to the LEAP client application

A LEAP client applications (LEAP Desktop / Web / Mobile) accepts certain messages from LEAP apps and act upon them. For example, they can open a document or show a message box.

The LEAP Host SDK facilitates this process by exposing a set of semantic functions through which the LEAP app can invoke.

await sdk.init();

// open a message box in LEAP
sdk.system.alert({ message: 'Hello, world' });

// open a matter
sdk.matter.openMatter(openMatterRequest);

// close the app
sdk.system.close();

API reference

Accounting

Create a time entry

createTimeEntryV2(request: CreateTimeEntryRequest): Promise<CreateTimeEntryResponse>;

Create a fee entry

createFeeEntryV2(request: CreateFeeEntryRequest): Promise<CreateFeeEntryResponse>;

Create a cost recovery

createCostRecoveryV2(request: CreateCostRecoveryEntryRequest): Promise<CreateCostRecoveryResponse>;

//Request example:
const request = {
  "matterId":"c2b1cbde-77ec-2642-91d9-09191e5258c6",
  "appSessionId":"1fa55cbb-7b02-a546-94a2-8986be7fce5b"
};

const response = await sdk.accounting.createCostRecoveryV2(request);

Create an invoice

createInvoiceV2(request: CreateInvoiceRequest): Promise<CreateInvoiceResponse>;

Create an office receipt

createOfficeReceiptV2(request: CreateOfficeReceiptRequest): Promise<CreateOfficeReceiptResponse>;

Create an office payment

createOfficePaymentV2(request: CreateOfficePaymentRequest): Promise<CreateOfficePaymentResponse>;

//Request example:
const request = {
  "matterId":"c2b1cbde-77ec-2642-91d9-09191e5258c6",
  "appSessionId":"1fa55cbb-7b02-a546-94a2-8986be7fce5b"
};

const response = await sdk.accounting.createOfficePaymentV2(request);

Create an office payment request

createOfficePaymentRequestV2(request: CreateNewOfficePaymentRequestRequest): Promise<CreateNewOfficePaymentRequestResponse>;

Create an trust payment request

createTrustPaymentRequestV2(request: CreateNewTrustPaymentRequestRequest): Promise<CreateNewTrustPaymentRequestResponse>;

Create an office journal

createOfficeJournalV2(request: CreateOfficeJournalRequest): Promise<CreateOfficeJournalResponse>;

Create a trust receipt

createTrustReceiptV2(request: CreateTrustReceiptRequest): Promise<CreateTrustReceiptResponse>;

Create a trust payment

createTrustPaymentV2(request: CreateTrustPaymentRequest): Promise<CreateTrustPaymentResponse>;

Create a trust journal

createOfficeJournalV2(request: CreateOfficeJournalRequest): Promise<CreateOfficeJournalResponse>;

Create trust to office

createTrustToOfficeV2(request: CreateTrustToOfficeRequest): Promise<CreateTrustToOfficeResponse>;

Reload the financial summary

reloadFinancialSummary(request: ReloadFinancialSummaryRequest): void;

Reload the time fee list

reloadTimeFeeList(request: ReloadTimeFeeListRequest): void;

Reload the office ledger

reloadOfficeLedger(request: ReloadOfficeLedgerRequest): void;

Reload the anticipated payment list

reloadAnticipatedPaymentList(request: ReloadAnticipatedPaymentListRequest): void;

Reload the cost recovery list

reloadCostRecoveryList(request: ReloadCostRecoveryListRequest): void;

//Request example:
const request = {
  "matterId":"c2b1cbde-77ec-2642-91d9-09191e5258c6",
  "appSessionId":"1fa55cbb-7b02-a546-94a2-8986be7fce5b"
};

sdk.accounting.reloadCostRecoveryList(request);

Reload the trust ledger

reloadTrustLedger(request: ReloadTrustLedgerRequest): void;

Reload the controlled money list

reloadControlledMoneyList(request: ReloadControlledMoneyListRequest): void;

Reload the power money list

reloadPowerMoneyList(request: ReloadPowerMoneyListRequest): void;

Reload the transit money list

reloadTransitMoneyList(request: ReloadTransitMoneyListRequest): void;

Open a fee

openFee(request: OpenFeeRequest): void;

App

Open the legal guide

Opens the ByLawyers "Legal Guides" tab and routes to the guide for the given matter type and state.

openLegalGuide(request: OpenLegalGuideRequest): void;

//Request example:
const request = {
  "matterTypeId":"c2b1cbde-77ec-2642-91d9-09191e5258c6",
  "state":"NSW"
};

sdk.app.openLegalGuide(request);

Calc

Evaluate paths

evaluatePaths(request: EvaluatePathsRequest): Promise<PathResult[]>;

//Request example:
const request = {
  "executionContext": {
    "matterGUID": "a4a9a42d-2dd8-48c4-bf06-b213369a5c84"
  },
  "paths": ["matter.clientList.{__id,__className,__fileOrder,__description,personList}", "matter.fileNumber"]
};

sdk.calc.evaluatePaths(request)
.then(response =>{
  //handle the response here
});

Card

Select card(s) from the list

selectCard(request?: SelectCardRequest): Promise<Card[]>;

Create a card

createCard(): Promise<CreatedCard[]>;

Open a card

openCard(request: OpenCardRequest): void;

Communication

Compose an email

composeEmail(request: CreateEmailRequest): void;

Create an appointment

createAppointment(request: CreateAppointmentRequest): void;

//Request example:
const request = {
  "matterId":"c2b1cbde-77ec-2642-91d9-09191e5258c6",
  "startDate": "2020-10-21T05:12:46.472Z",
  "endDate": "2020-10-22T05:13:46.472Z",
  "attachments":[],
  "requiredAttendees":[],
  "optionalAttendees":[]
};

sdk.communication.createAppointment(request);

Create a task

createTask(request: CreateTaskRequest): void;

//Request example:
const request = {
  "matterId":"c2b1cbde-77ec-2642-91d9-09191e5258c6",
  "startDate":"2020-10-21T00:00:00.000Z",
  "dueDate":"2020-10-22T00:00:00.000Z"
};

sdk.communication.createTask(request);

Document

Preview a document

previewDocument(request: PreviewDocumentRequest): void;

Preview a Precedent

previewPrecedent(request: PreviewPrecedentRequest): void;

Edit a Precedent

editPrecedent(request: EditPrecedentRequest): void;

Get the details of a selected precedent

selectPrecedent(request: SelectPrecedentRequest): Promise<SelectPrecedentResponse>;

Create a document from a URL

createDocumentBasedOnURL(request: CreateDocumentBasedOnURLRequest): void;

Create a document from a container

createDocumentFromContainer(request: CreateDocumentFromContainerRequest): void;

Create a document from a precedent

createDocumentFromPrecedent(request: CreateDocumentFromPrecedentRequest): void;

Open a document

openDocument(request: OpenDocumentRequest): void;

const request = {
  "matterId":"c2b1cbde-77ec-2642-91d9-09191e5258c6",
  "documentId":"ba5e2173-e6bc-47b4-9280-787f78454e2b",
  "appSessionId":"b90402b8-c7cb-435b-b1fc-8bbcb1d49934"
};

sdk.document.openDocument(request);

Reload the document list

reloadDocumentList(request: ReloadDocumentListRequest): void;

LawConnect

Share documents

shareDocuments(request: ShareDocumentsRequest): void;

Share a folder

shareFolder(request: ShareFolderRequest): void;

Share an office statement

shareOfficeStatement(request: ShareOfficeStatementRequest): void;

Share a trust statement

shareTrustStatement(request: ShareTrustStatementRequest): void;

Matter

Open a table

openTable(request: OpenTableRequest): void;

Open a matter

openMatter(request: OpenMatterRequest): void;

//Request example:
const request = {
  "matterId":"c2b1cbde-77ec-2642-91d9-09191e5258c6",
  "appSessionId":"1fa55cbb-7b02-a546-94a2-8986be7fce5b"
};

sdk.matter.openMatter(request);

Select matter(s)

selectMatter(request?: SelectMatterRequest): Promise<Matter[]>;

Person

Select staff

selectStaff(request?: SelectStaffRequest): Promise<Staff[]>;

MS Teams

Share a document

shareDocument(request: ShareDocumentRequest): void;

Share a matter

shareMatter(request: ShareMatterRequest): void;

Request a callback

shareMatter(request: RequestCallbackRequest): void;

Person

Select person(s) from the list

selectPerson(request: SelectPersonRequest): Promise<Person[]>;

Open a person

openPerson(request: OpenPerson): void;

Register

Reload document register list

reloadDocumentRegisterList(request: ReloadDocumentRegisterListRequest): void;

Reload power estate list

reloadPowerEstateList(request: ReloadPowerEstateListRequest): void;

Schema

Get schema list

getLists(request: GetListsRequest): Promise<SchemaResponse<SchemaList[]>>;

Customise list

customiseList(request: CustomiseListRequest): Promise<CustomiseListResponse>;

System

Get a refreshed access token

getRefreshedAccessToken(): Promise<string>;

Get a decoded access token

getDecodedRefreshedAccessToken(): Promise<any>;

Subscribe to context updates

subscribeContextUpdate(onSuccess?: (leapContext: LeapContext) => void, onError?: (error: any) => void): void;

Unsubscribe from context updates

unsubscribeContextUpdate(): void;

Open Twitter window

openTwitter(request: BaseRequest): void;

Close the current LEAP app

close(): void;

Hide the current LEAP app

hide(): void;

Show loading icon in LEAP

wait(request?: MessageRequest): void;

Hide loading icon in LEAP

resume(): void;

Show a message box in LEAP (Deprecated, replaced with openDialog)

alert(): void;

Show an error message in LEAP (Deprecated, replaced with openDialog)

error(): void;

Display a message on the dialog box in LEAP

openDialogV2(request: DialogRequest): Promise<system.DialogButtonType>;

Open an URL in browser

openUrl(config: BrowserConfig): void;

//Request example:
const config = {
  "url": "https://app.test.bylawyers.com.au/",
  "openExternal": false,
  "useNativeLoading": false
  "width": 900,
  "height": 500,
  "minWidth": 800,
  "minHeight": 400,
  "maxWidth": 1000,
  "maxHeight": 600,
  "closeHandler": "jsFunction(parameter)",
  "fixedWindowSize": false,
  "independentWindow": false,
  "windowTitle": "Good day"
};

sdk.system.openUrl(config);

Get host system info

getSystemInfo(): void;

Set window title

setWindowTitle(request: SetWindowTitleRequest): void;

Register a handler to trigger before closing a window

registerHostMessageHandler('onBeforeClose', () => {
  //sdk.system.cancelClose();
  //your logic goes here
  //sdk.system.close();
});

Send a custom request object to the host

send(request: object, hasResponse?: boolean): Promise<any>;

Notify the host system when your app has finished loading (to avoid having different loaders from LEAP and your app)

finishLoading(): void;