Merge pull request #4 from identity-com/feature/IDCOM-138__updated_cl…

…ient_apis

Add selfDeclarationTextAgreedTo to createGatewayToken & add findGatewayTokens

.gitignore

@@ -59,4 +59,4 @@ swapProgramId
 *.history
 
 # tests
-*test-results.xml
+*test-results.xml

README.md

@@ -6,7 +6,7 @@ This library provides a client and uility methods for helping Decentralized Apps
     - [Installation](#installation)
     - [Import](#import)
   - [Functions/Classes](#functionsclasses)
-    - [findGatewayToken](#findgatewaytoken)
+    - [findGatewayTokens](#findgatewaytokens)
     - [GatekeeperClient](#gatekeeperclient)
       - [initialisation](#initialisation)
       - [createGatewayToken](#creategatewaytoken)
@@ -24,17 +24,19 @@ import { GatekeeperClient, GatekeeperClientConfig, GatekeeperRecord, findGateway
 ```
 
 ## Functions/Classes
-### findGatewayToken
-Utility method for finding a gateway token for a given public key. This method does the lookup against the Solana blockchain. Returns null if a gateway token doesn't exist for the given public key.
+### findGatewayTokens
+Utility method for finding gateway token created for a given public key. This method does the lookup against the Solana blockchain. Returns an empty array if gateway tokens doesn't exist for the given public key.
 ```
-const gatewayToken: PublicKey = await findGatewayToken(connection, owner, mintAuthorityPublicKey);
+const gatewayToken: PublicKey = await findGatewayToken(connection, owner, gatekeeperKey);
 ```
+Optionally, a 'revoked' flag can be passed to allow retrieval of all, even revoked, tokens.
 
 ### GatekeeperClient
 The GatekeeperClient is a class with helper methods to enable communication with a Gatekeeper server.
 
 #### initialisation
-The baseUrl of the gatekeeper server must be provided when creating a client instance:
+The baseUrl of the gatekeeper server must be provided when creating a client instance. Additional headers can be passed in config
+that will be added to HTTP requests to the gatekeeper-api:
 ```
 const baseUrl: string = 'http://<gateway url>';
 const clientInst = new GatekeeperClient({ baseUrl });
@@ -45,9 +47,15 @@ Requests that a gateway token be created for the given Solana public key. Return
 ```
 const gatewayToken = await gatekeeperClientInst.createGatewayToken(walletPublicKey);
 ```
-Alternatively, a gateway token can be requested by providing the Solana public key and a Civic verifiablePresentationId. The gatekeeper server validates that the verifiablePresentation is completed successfully before creating the gateway token.
+An optional parameter 'selfDeclarationTextAgreedTo' can be provided indicating that the requester has read and agreed to the passed text.
 ```
-const gatewayToken = await gatekeeperClientInst.createGatewayToken(walletPublicKey, presentationRequestId);
+const selfDeclarationTextAgreedTo = 'I declare I am not resident in <not-allowed-territory>'
+...<UI for user to agree to text>
+const gatewayToken = await gatekeeperClientInst.createGatewayToken({ walletPublicKey, selfDeclarationTextAgreedTo });
+```
+A gateway token can be requested by providing a Civic presentationRequestId. The gatekeeper server validates that the presentation provided by the user is successful and a token is generated. The presentationRequest created by the DAPP should contain the publicKey address to create the gateway token for.
+```
+const gatewayToken = await gatekeeperClientInst.createGatewayToken({ presentationRequestId });
 ```
 
 #### auditGatewayToken

dist/index.d.ts

@@ -1,11 +1,13 @@
 import { Connection, PublicKey } from '@solana/web3.js';
+export declare const TOKEN_PROGRAM_ID: PublicKey;
 export declare type GatekeeperRecord = {
     timestamp: string;
     token: string;
     name: string;
     ipAddress: string;
     country: string;
     approved: boolean;
+    selfDeclarationTextAgreedTo: string;
     document?: {
         nationality: string;
         name: {
@@ -21,41 +23,52 @@ export declare type GatekeeperRecord = {
 };
 export declare type GatekeeperClientConfig = {
     baseUrl: string;
+    headers?: Record<string, string>;
 };
-export interface GatekeeperClientInterface {
-    createGatewayToken(walletPublicKey: PublicKey, presentationRequestId?: string): Promise<GatekeeperRecord>;
-    auditGatewayToken(token: string): Promise<GatekeeperRecord | null>;
-}
-export declare type CreateTokenRequest = {
+export declare type TokenCreationRequest = {
+    walletPublicKey?: PublicKey;
+    selfDeclarationTextAgreedTo?: string;
+    presentationRequestId?: string;
+};
+declare type ServerTokenRequest = {
     scopeRequest?: string;
     address?: string;
+    selfDeclarationTextAgreedTo?: string;
 };
+export interface GatekeeperClientInterface {
+    createGatewayToken(tokenCreationRequest: ServerTokenRequest): Promise<GatekeeperRecord>;
+    auditGatewayToken(token: string): Promise<GatekeeperRecord | null>;
+    requestAirdrop(walletPublicKey: PublicKey): Promise<void>;
+}
 export declare type AirdropRequest = {
-    publicKey: string;
+    address: string;
 };
-export declare type GatekeeperRequest = CreateTokenRequest | AirdropRequest;
+export declare type GatekeeperRequest = ServerTokenRequest | AirdropRequest;
 export declare type GatekeeperResponse = GatekeeperRecord | null | Record<string, unknown>;
 export declare class GatekeeperClient implements GatekeeperClientInterface {
     config: GatekeeperClientConfig;
     constructor(config: GatekeeperClientConfig);
     get baseUrl(): string;
+    get headers(): Record<string, string>;
+    postGatekeeperServer<T extends GatekeeperRequest, U extends GatekeeperResponse>(body: T, path?: string): Promise<U>;
     /**
      * This function creates gateway tokens for current connected wallet
      * If called and a gateway token already exists for this wallet, it will throw an exception
      *
      * @param {PublicKey} walletPublicKey
+     * @param {string} [selfDeclarationTextAgreedTo] - the text that a user had to agree to in order to call createGatewayToken
      * @param {string} [presentationRequestId] If a Civic scope request was used to verify the identity of the trader, pass it here.
      */
-    createGatewayToken(walletPublicKey: PublicKey, presentationRequestId?: string): Promise<GatekeeperRecord>;
+    createGatewayToken({ walletPublicKey, selfDeclarationTextAgreedTo, presentationRequestId }: TokenCreationRequest): Promise<GatekeeperRecord>;
     auditGatewayToken(token: string): Promise<GatekeeperRecord | null>;
     requestAirdrop(walletPublicKey: PublicKey): Promise<void>;
 }
-/**
- * attempts to fetch a gateway token from the Solana blockchain. Will return null if the token account doesn't exist
- * or has been frozen
- * @param {Connection} connection
- * @param {PublicKey} owner
- * @param {PublicKey} gatekeeperKey
- * @returns Promise<PublicKey | null>
- */
-export declare const findGatewayToken: (connection: Connection, owner: PublicKey, gatekeeperKey: PublicKey) => Promise<PublicKey | null>;
+export declare type GatewayToken = {
+    gatekeeperKey: PublicKey;
+    owner: PublicKey;
+    isValid: boolean;
+    publicKey: PublicKey;
+    programId: PublicKey;
+};
+export declare const findGatewayTokens: (connection: Connection, owner: PublicKey, gatekeeperKey: PublicKey, showRevoked?: boolean) => Promise<GatewayToken[]>;
+export {};