GlobaliD API Client

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

• Setup
• Usage
  • GidApiClientFactory
  • GidApiClient
    • Attestations
    • Consent Command
    • Identity
    • PII
  • Testing
    • createGidApiClientMock
    • GidApiMockBuilder
• TypeScript
• Development

Setup

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

1. Create a developer app.
2. (Optional) set up any required verifications.
3. (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:

1. Create a GidApiClientFactory.
2. Use the factory to create a GidApiClient from an authorization code.
3. 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: '[email protected]'
      }
    ])
    .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