[amazon-cognito-auth-js] Creating package (#25622)

* Creating initial type definitions for 'amazon-cognito-auth-js', which include all JSDoc from the ES source code. I'm attempting to follow the same interface naming conventions found in aws/amazon-cognito-identity-js. I've deviated from the standard package template by creating a /test subfolder that contains the conventionally named test file along with a second file that references types from a global namespace.

* Removing tslint interface-name rule override and removing "I" prefix
from interface names.

* Improving tests by ensuring all interface types are explicitly
referenced.

* Removing unnecessary .editorconfig in package directory.
This commit is contained in:
Scott Escue
2018-05-09 12:39:54 -07:00
committed by Sheetal Nandi
parent 20c0779394
commit c7331be0bf
5 changed files with 787 additions and 0 deletions
+577
View File
@@ -0,0 +1,577 @@
// Type definitions for amazon-cognito-auth-js 1.2
// Project: https://github.com/aws/amazon-cognito-auth-js
// Definitions by: Scott Escue <https://github.com/scottescue>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 2.2
/*
* Create global variable to provide access to types when used without module
* loading.
*/
export as namespace AmazonCognitoIdentity;
// Stubs the XDomainRequest built-in from older IE browsers, does not follow the project's interface naming convention
export interface XDomainRequest {
readonly responseText: string;
timeout: number;
onprogress: () => void;
ontimeout: () => void;
onerror: () => void;
onload: () => void;
open(method: string, url: string): void;
send(data: string): void;
abort(): void;
}
export interface CognitoSessionData {
/**
* The session's Id token.
*/
IdToken?: CognitoIdToken;
/**
* The session's refresh token.
*/
RefreshToken?: CognitoRefreshToken;
/**
* The session's access token.
*/
AccessToken?: CognitoAccessToken;
/**
* The session's token scopes.
*/
TokenScopes?: CognitoTokenScopes;
/**
* The session's state.
*/
State?: string;
}
export interface CognitoAuthOptions {
/**
* Required: User pool application client id.
*/
ClientId: string;
/**
* Required: The application/user-pools Cognito web hostname,this is set at the Cognito console.
*/
AppWebDomain: string;
/**
* Optional: The token scopes
*/
TokenScopesArray?: ReadonlyArray<string>;
/**
* Required: Required: The redirect Uri, which will be launched after authentication as signed in.
*/
RedirectUriSignIn: string;
/**
* Required: The redirect Uri, which will be launched when signed out.
*/
RedirectUriSignOut: string;
/**
* Optional: Pre-selected identity provider (this allows to automatically trigger social provider authentication flow).
*/
IdentityProvider?: string;
/**
* Optional: UserPoolId for the configured cognito userPool.
*/
UserPoolId?: string;
/**
* Optional: boolean flag indicating if the data collection is enabled to support cognito advanced security features. By default, this flag is set to true.
*/
AdvancedSecurityDataCollectionFlag?: boolean;
}
export interface CognitoAuthUserHandler {
onSuccess: (authSession: CognitoAuthSession) => void;
onFailure: (err: any) => void;
}
export interface CognitoConstants {
DOMAIN_SCHEME: string;
DOMAIN_PATH_SIGNIN: string;
DOMAIN_PATH_TOKEN: string;
DOMAIN_PATH_SIGNOUT: string;
DOMAIN_QUERY_PARAM_REDIRECT_URI: string;
DOMAIN_QUERY_PARAM_SIGNOUT_URI: string;
DOMAIN_QUERY_PARAM_RESPONSE_TYPE: string;
DOMAIN_QUERY_PARAM_IDENTITY_PROVIDER: string;
DOMAIN_QUERY_PARAM_USERCONTEXTDATA: string;
CLIENT_ID: string;
STATE: string;
SCOPE: string;
TOKEN: string;
CODE: string;
POST: string;
PARAMETERERROR: string;
SCOPETYPEERROR: string;
QUESTIONMARK: string;
POUNDSIGN: string;
COLONDOUBLESLASH: string;
SLASH: string;
AMPERSAND: string;
EQUALSIGN: string;
SPACE: string;
CONTENTTYPE: string;
CONTENTTYPEVALUE: string;
AUTHORIZATIONCODE: string;
IDTOKEN: string;
ACCESSTOKEN: string;
REFRESHTOKEN: string;
ERROR: string;
ERROR_DESCRIPTION: string;
STRINGTYPE: string;
STATELENGTH: number;
STATEORIGINSTRING: string;
WITHCREDENTIALS: string;
UNDEFINED: string;
SELF: string;
HOSTNAMEREGEX: RegExp;
QUERYPARAMETERREGEX1: RegExp;
QUERYPARAMETERREGEX2: RegExp;
HEADER: { 'Content-Type': string };
}
export class CognitoIdToken {
/**
* Constructs a new CognitoIdToken object
* @param IdToken The JWT Id token
*/
constructor(IdToken: string);
/**
* @returns the record's token.
*/
getJwtToken(): string;
/**
* Sets new value for id token.
* @param idToken The JWT Id token
*/
setJwtToken(idToken: string): void;
/**
* @returns the token's expiration (exp member).
*/
getExpiration(): number;
/**
* @returns the token's payload.
*/
decodePayload(): object;
}
export class CognitoRefreshToken {
/**
* Constructs a new CognitoRefreshToken object
* @param RefreshToken The JWT refresh token.
*/
constructor(RefreshToken: string);
/**
* @returns the record's token.
*/
getToken(): string;
/**
* Sets new value for refresh token.
* @param refreshToken The JWT refresh token.
*/
setToken(refreshToken: string): void;
}
export class CognitoAccessToken {
/**
* Constructs a new CognitoAccessToken object
* @param AccessToken The JWT access token.
*/
constructor(AccessToken: string);
/**
* @returns the record's token.
*/
getJwtToken(): string;
/**
* Sets new value for access token.
* @param accessToken The JWT access token.
*/
setJwtToken(accessToken: string): void;
/**
* @returns the token's expiration (exp member).
*/
getExpiration(): number;
/**
* @returns the username from payload.
*/
getUsername(): string;
/**
* @returns the token's payload.
*/
decodePayload(): object;
}
export class CognitoTokenScopes {
/**
* Constructs a new CognitoTokenScopes object
* @param TokenScopesArray The token scopes
*/
constructor(TokenScopesArray: ReadonlyArray<string>);
/**
* @returns the token scopes.
*/
getScopes(): string[];
/**
* Sets new value for token scopes.
* @param tokenScopes The token scopes
*/
setTokenScopes(tokenScopes: ReadonlyArray<string>): void;
}
export class CognitoAuthSession {
/**
* Constructs a new CognitoUserSession object
* @param sessionData The session's tokens, scopes, and state.
*/
constructor(sessionData: CognitoSessionData);
/**
* @returns the session's Id token
*/
getIdToken(): CognitoIdToken;
/**
* Set a new Id token
* @param IdToken The session's Id token.
*/
setIdToken(IdToken: CognitoIdToken): void;
/**
* @returns the session's refresh token
*/
getRefreshToken(): CognitoRefreshToken;
/**
* Set a new Refresh token
* @param RefreshToken The session's refresh token.
*/
setRefreshToken(RefreshToken: CognitoRefreshToken): void;
/**
* @returns the session's access token
*/
getAccessToken(): CognitoAccessToken;
/**
* Set a new Access token
* @param AccessToken The session's access token.
*/
setAccessToken(AccessToken: CognitoAccessToken): void;
/**
* @returns the session's token scopes
*/
getTokenScopes(): CognitoTokenScopes;
/**
* Set new token scopes
* @param tokenScopes The session's token scopes.
*/
setTokenScopes(tokenScopes: CognitoTokenScopes): void;
/**
* @returns the session's state
*/
getState(): string;
/**
* Set new state
* @param state The session's state.
*/
setState(State: string): void;
/**
* Checks to see if the session is still valid based on session expiry information found
* in Access and Id Tokens and the current time
* @returns if the session is still valid
*/
isValid(): boolean;
}
export class CognitoAuth {
/**
* Called on success or error.
*/
userhandler: CognitoAuthUserHandler;
/**
* Constructs a new CognitoAuth object
* @param options Creation options
*/
constructor(options: CognitoAuthOptions);
/**
* @returns the constants
*/
getCognitoConstants(): CognitoConstants;
/**
* @returns the client id
*/
getClientId(): string;
/**
* @returns the app web domain
*/
getAppWebDomain(): string;
/**
* method for getting the current user of the application from the local storage
*
* @returns the user retrieved from storage
*/
getCurrentUser(): string;
/**
* method for setting the current user's name
* @param Username the user's name
*/
setUser(Username: string): void;
/**
* sets response type to 'code'
*/
useCodeGrantFlow(): void;
/**
* sets response type to 'token'
*/
useImplicitFlow(): void;
/**
* @returns the current session for this user
*/
getSignInUserSession(): CognitoAuthSession;
/**
* @returns the user's username
*/
getUsername(): string;
/**
* @param Username the user's username
*/
setUsername(Username: string): void;
/**
* @returns the user's state
*/
getState(): string;
/**
* @param State the user's state
*/
setState(State: string): void;
/**
* This is used to get a session, either from the session object or from the local storage, or by using a refresh token
* @param RedirectUriSignIn Required: The redirect Uri, which will be launched after authentication.
* @param TokenScopesArray Required: The token scopes, it is an array of strings specifying all scopes for the tokens.
*/
getSession(): void;
/**
* Parse the http request response and proceed according to different response types.
* @param httpRequestResponse the http request response
*/
parseCognitoWebResponse(httpRequestResponse: string): void;
/**
* Get the query parameter map and proceed according to code response type.
* @param Query parameter map
*/
getCodeQueryParameter(map: ReadonlyMap<string, string>): void;
/**
* Get the query parameter map and proceed according to token response type.
* @param Query parameter map
*/
getTokenQueryParameter(map: ReadonlyMap<string, string>): void;
/**
* Get cached tokens and scopes and return a new session using all the cached data.
* @returns the auth session
*/
getCachedSession(): CognitoAuthSession;
/**
* This is used to get last signed in user from local storage
* @returns the last user name
*/
getLastUser(): string;
/**
* This is used to save the session tokens and scopes to local storage.
*/
cacheTokensScopes(): void;
/**
* Compare two sets if they are identical.
* @param set1 one set
* @param set2 the other set
* @returns boolean value is true if two sets are identical
*/
compareSets(set1: ReadonlySet<any>, set2: ReadonlySet<any>): boolean;
/**
* Get the hostname from url.
* @param url the url string
* @returns hostname string
*/
getHostName(url: string): string;
/**
* Get http query parameters and return them as a map.
* @param url the url string
* @param splitMark query parameters split mark (prefix)
* @returns map
*/
getQueryParameters(url: string, splitMark: string): Map<string, string>;
/**
* helper function to generate a random string
* @param length the length of string
* @param chars a original string
* @returns a random value.
*/
generateRandomString(length: number, chars: string): string;
/**
* This is used to clear the session tokens and scopes from local storage
*/
clearCachedTokensScopes(): void;
/**
* This is used to build a user session from tokens retrieved in the authentication result
* @param refreshToken Successful auth response from server.
*/
refreshSession(refreshToken: string): void;
/**
* Make the http POST request.
* @param header header JSON object
* @param body body JSON object
* @param url string
* @param onSuccess callback
* @param onFailure callback
*/
makePOSTRequest(header: object, body: object, url: string,
onSuccess: (responseText: string) => void,
onFailure: (responseText: string) => void): void;
/**
* Create the XHR object
* @param method which method to call
* @param url the url string
* @returns xhr
*/
createCORSRequest(method: string, url: string): XMLHttpRequest | XDomainRequest;
/**
* The http POST request onFailure callback.
* @param err the error object
*/
onFailure(err: any): void;
/**
* The http POST request onSuccess callback when refreshing tokens.
* @param jsonData tokens
*/
onSuccessRefreshToken(jsonData: string): void;
/**
* The http POST request onSuccess callback when exchanging code for tokens.
* @param jsonData tokens
*/
onSuccessExchangeForToken(jsonData: string): void;
/**
* Launch Cognito Auth UI page.
* @param URL the url to launch
*/
launchUri(URL: string): void;
/**
* @returns scopes string
*/
getSpaceSeperatedScopeString(): string;
/**
* Create the FQDN(fully qualified domain name) for authorization endpoint.
* @returns url
*/
getFQDNSignIn(): string;
/**
* Sign out the user.
*/
signOut(): void;
/**
* Create the FQDN(fully qualified domain name) for signout endpoint.
* @returns url
*/
getFQDNSignOut(): string;
/**
* This method returns the encoded data string used for cognito advanced security feature.
* This would be generated only when developer has included the JS used for collecting the
* data on their client. Please refer to documentation to know more about using AdvancedSecurity
* features
*/
getUserContextData(): string;
/**
* Helper method to let the user know if he has either a valid cached session
* or a valid authenticated session from the app integration callback.
* @returns userSignedIn
*/
isUserSignedIn(): boolean;
}
export class DateHelper {
/**
* @returns The current time in "ddd MMM D HH:mm:ss UTC YYYY" format.
*/
getNowString(): string;
}
export class StorageHelper {
/**
* This is used to get a storage object
* @returns the storage
*/
constructor();
/**
* This is used to return the storage
* @returns the storage
*/
getStorage(): Storage;
}
@@ -0,0 +1,162 @@
import * as lib from 'amazon-cognito-auth-js';
const idToken: lib.CognitoIdToken = new lib.CognitoIdToken('fak3T0ken1==');
idToken.decodePayload(); // $ExpectType object
idToken.setJwtToken('fak3T0ken2=='); // $ExpectType void
idToken.getJwtToken(); // $ExpectType string
idToken.getExpiration(); // $ExpectType number
const refreshToken: lib.CognitoRefreshToken = new lib.CognitoRefreshToken('refreshplease==');
refreshToken.setToken('refreshagainplease=='); // $ExpectType void
refreshToken.getToken(); // $ExpectType string
const accessToken: lib.CognitoAccessToken = new lib.CognitoAccessToken('fak3T0ken3==');
accessToken.decodePayload(); // $ExpectType object
accessToken.setJwtToken('fak3T0ken4=='); // $ExpectType void
accessToken.getJwtToken(); // $ExpectType string
accessToken.getExpiration(); // $ExpectType number
accessToken.getUsername(); // $ExpectType string
const tokenScopes: lib.CognitoTokenScopes = new lib.CognitoTokenScopes(['email', 'custom1']);
tokenScopes.setTokenScopes(['openid']); // $ExpectType void
tokenScopes.getScopes(); // $ExpectType string[]
let sessionData: lib.CognitoSessionData = {};
let authSession: lib.CognitoAuthSession = new lib.CognitoAuthSession(sessionData);
sessionData = {
IdToken: idToken,
RefreshToken: refreshToken,
AccessToken: accessToken,
TokenScopes: tokenScopes,
State: '/myapp/home'
};
authSession = new lib.CognitoAuthSession(sessionData);
authSession.setIdToken(new lib.CognitoIdToken('fak3T0ken5==')); // $ExpectType void
authSession.setRefreshToken(new lib.CognitoRefreshToken('refreshmeyetagain==')); // $ExpectType void
authSession.setAccessToken(new lib.CognitoAccessToken('fak3T0ken6==')); // $ExpectType void
authSession.setTokenScopes(new lib.CognitoTokenScopes(['email'])); // $ExpectType void
authSession.setState('/myapp/login'); // $ExpectType void
authSession.getIdToken(); // $ExpectType CognitoIdToken
authSession.getRefreshToken(); // $ExpectType CognitoRefreshToken
authSession.getAccessToken(); // $ExpectType CognitoAccessToken
authSession.getTokenScopes(); // $ExpectType CognitoTokenScopes
authSession.getState(); // $ExpectType string
let authOptions: lib.CognitoAuthOptions = {
ClientId: '1a2b3c4d5e6f7g',
AppWebDomain: 'myapp.auth.us-east-1.amazoncognito.com',
RedirectUriSignIn: 'https://myapp.com/login',
RedirectUriSignOut: 'https://myapp.com/logout'
};
let auth: lib.CognitoAuth = new lib.CognitoAuth(authOptions);
authOptions = {
ClientId: '1a2b3c4d5e6f7g',
AppWebDomain: 'myapp.auth.us-east-1.amazoncognito.com',
TokenScopesArray: ['email', 'openid'],
RedirectUriSignIn: 'https://myapp.com/login',
RedirectUriSignOut: 'https://myapp.com/logout',
IdentityProvider: 'Facebook',
UserPoolId: 'us-east-1_faKE4ReAl',
AdvancedSecurityDataCollectionFlag: true
};
auth = new lib.CognitoAuth(authOptions);
auth.getClientId(); // $ExpectType string
auth.getAppWebDomain(); // $ExpectType string
auth.getCurrentUser(); // $ExpectType string
auth.setUser('jane.doe'); // $ExpectType void
auth.useCodeGrantFlow(); // $ExpectType void
auth.useImplicitFlow(); // $ExpectType void
auth.getSignInUserSession(); // $ExpectType CognitoAuthSession
auth.getUsername(); // $ExpectType string
auth.setUsername('john.doe'); // $ExpectType void
auth.getState(); // $ExpectType string
auth.setState('/myhost/default.htm'); // $ExpectType void
auth.getSession(); // $ExpectType void
auth.parseCognitoWebResponse('url&stuff=true'); // $ExpectType void
auth.getCodeQueryParameter(new Map()); // $ExpectType void
auth.getTokenQueryParameter(new Map()); // $ExpectType void
auth.getCachedSession(); // $ExpectType CognitoAuthSession
auth.getLastUser(); // $ExpectType string
auth.cacheTokensScopes(); // $ExpectType void
auth.compareSets(new Set(['1']), new Set(['1'])); // $ExpectType boolean
auth.getHostName('https://site.com/page?size=10'); // $ExpectType string
auth.getQueryParameters('http://site.com?1=1&2=2', '?'); // $ExpectType Map<string, string>
auth.generateRandomString(5, '159erf'); // $ExpectType string
auth.clearCachedTokensScopes(); // $ExpectType void
auth.refreshSession('refreshToken=='); // $ExpectType void
// $ExpectType void
auth.makePOSTRequest({ 'Content-Type': 'application/json' }, { pool: '2' },
'https://auth.com/signin',
(data) => console.log(data),
(error) => console.log(error));
auth.createCORSRequest('POST', '/myapp/login'); // $ExpectType XMLHttpRequest | XDomainRequest
auth.onFailure('request failed'); // $ExpectType void
auth.onSuccessRefreshToken('{"name":"John", "age":31}'); // $ExpectType void
auth.onSuccessExchangeForToken('{"name":"Jane", "age":30}'); // $ExpectType void
auth.launchUri('https://auth.com/login'); // $ExpectType void
auth.getSpaceSeperatedScopeString(); // $ExpectType string
auth.getFQDNSignIn(); // $ExpectType string
auth.signOut(); // $ExpectType void
auth.getFQDNSignOut(); // $ExpectType string
auth.getUserContextData(); // $ExpectType string
auth.isUserSignedIn(); // $ExpectType boolean
const userHandler: lib.CognitoAuthUserHandler = {
onSuccess: (authSession: lib.CognitoAuthSession) => console.log(authSession),
onFailure: (error: any) => console.log(error)
};
auth.userhandler = userHandler;
const constants: lib.CognitoConstants = auth.getCognitoConstants();
constants.DOMAIN_SCHEME; // $ExpectType string
constants.DOMAIN_PATH_SIGNIN; // $ExpectType string
constants.DOMAIN_PATH_TOKEN; // $ExpectType string
constants.DOMAIN_PATH_SIGNOUT; // $ExpectType string
constants.DOMAIN_QUERY_PARAM_REDIRECT_URI; // $ExpectType string
constants.DOMAIN_QUERY_PARAM_SIGNOUT_URI; // $ExpectType string
constants.DOMAIN_QUERY_PARAM_RESPONSE_TYPE; // $ExpectType string
constants.DOMAIN_QUERY_PARAM_IDENTITY_PROVIDER; // $ExpectType string
constants.DOMAIN_QUERY_PARAM_USERCONTEXTDATA; // $ExpectType string
constants.CLIENT_ID; // $ExpectType string
constants.STATE; // $ExpectType string
constants.SCOPE; // $ExpectType string
constants.TOKEN; // $ExpectType string
constants.CODE; // $ExpectType string
constants.POST; // $ExpectType string
constants.PARAMETERERROR; // $ExpectType string
constants.SCOPETYPEERROR; // $ExpectType string
constants.QUESTIONMARK; // $ExpectType string
constants.POUNDSIGN; // $ExpectType string
constants.COLONDOUBLESLASH; // $ExpectType string
constants.SLASH; // $ExpectType string
constants.AMPERSAND; // $ExpectType string
constants.EQUALSIGN; // $ExpectType string
constants.SPACE; // $ExpectType string
constants.CONTENTTYPE; // $ExpectType string
constants.CONTENTTYPEVALUE; // $ExpectType string
constants.AUTHORIZATIONCODE; // $ExpectType string
constants.IDTOKEN; // $ExpectType string
constants.ACCESSTOKEN; // $ExpectType string
constants.REFRESHTOKEN; // $ExpectType string
constants.ERROR; // $ExpectType string
constants.ERROR_DESCRIPTION; // $ExpectType string
constants.STRINGTYPE; // $ExpectType string
constants.STATELENGTH; // $ExpectType number
constants.STATEORIGINSTRING; // $ExpectType string
constants.WITHCREDENTIALS; // $ExpectType string
constants.UNDEFINED; // $ExpectType string
constants.SELF; // $ExpectType string
constants.HOSTNAMEREGEX; // $ExpectType RegExp
constants.QUERYPARAMETERREGEX1; // $ExpectType RegExp
constants.QUERYPARAMETERREGEX2; // $ExpectType RegExp
constants.HEADER['Content-Type']; // $ExpectType string
const dateHelper: lib.DateHelper = new lib.DateHelper();
dateHelper.getNowString(); // $ExpectType string
const storageHelper: lib.StorageHelper = new lib.StorageHelper();
storageHelper.getStorage(); // $ExpectType Storage
@@ -0,0 +1,22 @@
AmazonCognitoIdentity.CognitoIdToken; // $ExpectType typeof CognitoIdToken
AmazonCognitoIdentity.CognitoRefreshToken; // $ExpectType typeof CognitoRefreshToken
AmazonCognitoIdentity.CognitoAccessToken; // $ExpectType typeof CognitoAccessToken
AmazonCognitoIdentity.CognitoTokenScopes; // $ExpectType typeof CognitoTokenScopes
AmazonCognitoIdentity.CognitoAuthSession; // $ExpectType typeof CognitoAuthSession
AmazonCognitoIdentity.CognitoAuth; // $ExpectType typeof CognitoAuth
AmazonCognitoIdentity.DateHelper; // $ExpectType typeof DateHelper
AmazonCognitoIdentity.StorageHelper; // $ExpectType typeof StorageHelper
const sessionData: AmazonCognitoIdentity.CognitoSessionData = {};
new AmazonCognitoIdentity.CognitoAuthSession(sessionData);
const authOptions: AmazonCognitoIdentity.CognitoAuthOptions = {
ClientId: '1a2b3c4d5e6f7g',
AppWebDomain: 'myapp.auth.us-east-1.amazoncognito.com',
RedirectUriSignIn: 'https://myapp.com/login',
RedirectUriSignOut: 'https://myapp.com/logout'
};
const auth = new AmazonCognitoIdentity.CognitoAuth(authOptions);
auth.userhandler; // $ExpectType CognitoAuthUserHandler
auth.getCognitoConstants(); // $ExpectType CognitoConstants
auth.createCORSRequest('', ''); // $ExpectType XMLHttpRequest | XDomainRequest
@@ -0,0 +1,25 @@
{
"compilerOptions": {
"module": "commonjs",
"lib": [
"dom",
"es6"
],
"noImplicitAny": true,
"noImplicitThis": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"baseUrl": "../",
"typeRoots": [
"../"
],
"types": [],
"noEmit": true,
"forceConsistentCasingInFileNames": true
},
"files": [
"index.d.ts",
"test/amazon-cognito-auth-js-tests.ts",
"test/amazon-cognito-auth-js-umd-tests.ts"
]
}
+1
View File
@@ -0,0 +1 @@
{ "extends": "dtslint/dt.json" }