GlobaliD API Client

This is the JavaScript client library communicating with the GlobaliD API.

Setup
Usage
TypeScript
Development

Setup

Before you can utilize this library, you'll need to do the following:

Create a developer app.
(Optional) set up any required verifications.
(Optional) enable PII sharing, if you need user PII.

Usage

Once you've completed the setup, you're ready to start using this library. Here's a usage overview:

Create a GidApiClientFactory.
Use the factory to create a GidApiClient from an authorization code.
Use the client to call GlobaliD API endpoints.

`GidApiClientFactory`

The GidApiClientFactory is responsible for creating instances of GidApiClient. Instantiate a client factory with your developer app's details.

const clientFactory = new GidApiClientFactory({
  clientId,
  clientSecret,
  redirectUri,
  privateKey: {
    key: '-----BEGIN PRIVATE KEY-----\n...',
    passphrase: '$up3R$3cr37'
  }
});

The privateKey option is only necessary if you need users' PII (see PII sharing). The value for privateKey can be either an object—as shown in the example above—or a string. If your private key is encrypted, provide an object with the passphrase; otherwise, provide a string.

`GidApiClient`

The GidApiClient allows you to easily call GlobaliD's API. Use a client factory to create an instance from an authorization code (e.g., received from a redirect after a user signs in with GlobaliD Connect).

const client = clientFactory.create(code);

Note that instances of GidApiClient are short lived since they're created from an authorization code. You should create an instance per authorization code.

Attestations

To retrieve a user's attestations, use attestations.get().

const attestations = await client.attestations.get();

The result is an array of Attestation objects with the following notable properties:

attestor - Name of the agency that verified the attestation
created_at - Date/time at which the attestation was verified
type - Name of the attestation that was made (e.g., phone_number, date_of_birth, email)
verification_type - String indicated whether the attestation was self_declared or verified by an agency.

Consent Command

To retrieve a consent command, use consent.getCommand(consentUuid). This method is useful in the delayed verifications flow.

const consentCommand = await client.consent.getCommand(decoupledId);

The result is a ConsentCommand with these notable properties:

expires_at - Date/time at which the request expires
requested_at - Date/time at which the verification(s) were requested
status - Current status of the missing verification(s); can be one of the following:
- completed
- declined
- expired
- in_progress
- user_action_required

Identity

To retrieve a user's identity, use identity.get().

const identity = await client.identity.get();

The result is an Identity with these properties:

display_name - User's display name
gid_name - User's GlobaliD name (i.e., https://global.id/{gid_name})
gid_uuid - User's GlobaliD UUID

PII

To retrieve a user's PII corresponding to your required verification set, use pii.get(). However, you will need to enable PII sharing in your developer app and provide your private key to your client factory for this to work properly.

const pii = await client.pii.get();

The result is an array of Pii objects with the following properties:

has_attachment - boolean indicating where there's an associated attachment
type - name of the PII attribute (e.g., phone_number, date_of_birth, email)
value - the PII
attachment (optional) - Buffer containing the attachment (e.g., image of the user's photo ID)

Testing

`createGidApiClientMock`

For unit tests, we provide the createGidApiClientMock function for creating mocked GidApiClient instances. The function accepts an optional boolean parameter (default true) indicating whether to include pii.get().

import { createGidApiClientMock } from '@globalid/api-client/testing';

test('GidApiClient usage', async () => {
  const client = createGidApiClientMock();
  client.identity.get.mockResolvedValueOnce({
    gid_uuid: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
    gid_name: 'foo',
    display_name: 'Foo Bar'
  });

  // call your code that uses GidApiClient

  // assertions...
});

`GidApiMockBuilder`

For integration tests, we provide the GidApiMockBuilder class for mocking HTTP calls (via nock) made by the GidApiClient, as well as a clearGidApiMocks function for cleanup.

import { clearGidApiMocks, GidApiMockBuilder } from '@globalid/api-client/testing';

let gidApiMockBuilder;

beforeEach(() => {
  gidApiMockBuilder = new GidApiMockBuilder({ publicKey, privateKey });
});

afterEach(() => {
  clearGidApiMocks();
});

test('GlobaliD API usage', async () => {
  const scope = gidApiMockBuilder
    .mockGetAttestations()
    .mockGetIdentity({
      gid_uuid: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
    })
    .mockGetPii([
      {
        type: 'email',
        value: 'foo@example.com'
      }
    ])
    .build();

  // call your code that uses GidApiClient

  expect(scope.isDone()).toBe(true);
  // other assertions...
});

The constructor of the GidApiMockBuilder accepts an optional public/private key pair, which is required for mocking PII calls. The class provides the following methods:

mockGetAttestations - Mocks the API calls for retrieving attestations
mockGetConsentCommand - Mocks the API calls for retrieving a consent command
mockGetIdentity - Mocks the API calls for retrieving an identity
mockGetPii - Mocks the API calls for retrieving PII
build - Returns a nock.Scope with all the configured API endpoint mocks

Each of the mock* methods accept an optional partial representation of the value returned from the corresponding API call.

TypeScript

This package is written in TypeScript, so type declarations are bundled with it.

Development

The following NPM scripts are available for development:

build – Runs the clean, genver, compile, lint, and format:check scripts to build the project
clean – Removes the output directory for a clean build
compile – Compiles TypeScript files with tsc
format – Formats the files with Prettier
format:check – Checks the formatting of the files with Prettier
genver - Generates a version module with genversion
lint – Lints the code with ESLint
lint:fix – Attempts to fix problems found by the linter
test – Tests the code with Jest
test:watch – Tests the code in watch mode