From f597a5c8e303021dc9debe0a3dd981157de65222 Mon Sep 17 00:00:00 2001 From: Dhaya Benmessaoud Date: Tue, 31 Oct 2017 22:37:14 +0100 Subject: [PATCH] Add types for Google Apps Script's Oauth2 library. --- .../google-apps-script-oauth2-tests.ts | 32 +++ types/google-apps-script-oauth2/index.d.ts | 197 ++++++++++++++++++ types/google-apps-script-oauth2/tsconfig.json | 23 ++ types/google-apps-script-oauth2/tslint.json | 1 + 4 files changed, 253 insertions(+) create mode 100644 types/google-apps-script-oauth2/google-apps-script-oauth2-tests.ts create mode 100644 types/google-apps-script-oauth2/index.d.ts create mode 100644 types/google-apps-script-oauth2/tsconfig.json create mode 100644 types/google-apps-script-oauth2/tslint.json diff --git a/types/google-apps-script-oauth2/google-apps-script-oauth2-tests.ts b/types/google-apps-script-oauth2/google-apps-script-oauth2-tests.ts new file mode 100644 index 0000000000..ca6d874fa4 --- /dev/null +++ b/types/google-apps-script-oauth2/google-apps-script-oauth2-tests.ts @@ -0,0 +1,32 @@ +// Examples from https://github.com/googlesamples/apps-script-oauth2 + +/** + * Create the OAuth2 service. + */ +function getDriveService() { + return OAuth2.createService('drive') + .setAuthorizationBaseUrl('https://accounts.google.com/o/oauth2/auth') + .setTokenUrl('https://accounts.google.com/o/oauth2/token') + .setClientId('xxx') + .setClientSecret('yyy') + .setCallbackFunction('authCallback') + .setPropertyStore(PropertiesService.getUserProperties()) + .setScope('https://www.googleapis.com/auth/drive') + .setParam('login_hint', Session.getActiveUser().getEmail()) + .setParam('access_type', 'offline') + .setParam('approval_prompt', 'force') + ; +} + +/** + * Handle the callback. + */ +function authCallback(request: any) { + const driveService = getDriveService(); + const isAuthorized = driveService.handleCallback(request); + if (isAuthorized) { + Logger.log('success'); + } else { + Logger.log('denied'); + } +} diff --git a/types/google-apps-script-oauth2/index.d.ts b/types/google-apps-script-oauth2/index.d.ts new file mode 100644 index 0000000000..d5d9022849 --- /dev/null +++ b/types/google-apps-script-oauth2/index.d.ts @@ -0,0 +1,197 @@ +// Type definitions for google-apps-script-oauth2 24.0 +// Project: https://github.com/googlesamples/apps-script-oauth2 +// Definitions by: dhayab +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.2 + +/// + +declare namespace GoogleAppsScriptOAuth2 { + interface OAuth2 { + /** + * The supported locations for passing the state parameter. + */ + STATE_PARAMETER_LOCATION: typeof StateParameterLocation; + /** + * The supported formats for the returned OAuth2 token. + */ + TOKEN_FORMAT: typeof TokenFormat; + /** + * Creates a new OAuth2 service with the name specified. + * It's usually best to create and configure your service once at the start of your script, + * and then reference them during the different phases of the authorization flow. + */ + createService(serviceName: string): OAuth2Service; + /** + * Returns the redirect URI that will be used for a given script. + * Often this URI needs to be entered into a configuration screen of your OAuth provider. + */ + getRedirectUri(scriptId: string): string; + } + + interface OAuth2Service { + /** + * Gets an access token for this service. + * This token can be used in HTTP requests to the service's endpoint. + * This method will throw an error if the user's access was not granted or has expired. + */ + getAccessToken(): string; + /** + * Gets the authorization URL. + * The first step in getting an OAuth2 token is to have the user visit this URL + * and approve the authorization request. The user will then be redirected back to your + * application using callback function name specified, so that the flow may continue. + */ + getAuthorizationUrl(): string; + /** + * Gets the last error that occurred this execution when trying to + * automatically refresh or generate an access token. + */ + getLastError(): any; + /** + * Returns the redirect URI that will be used for this service. + * Often this URI needs to be entered into a configuration screen of your OAuth provider. + */ + getRedirectUri(): string; + /** + * Gets the token from the service's property store or cache. + */ + getToken(): object | null; + /** + * Completes the OAuth2 flow using the request data passed in to the callback function. + */ + handleCallback(callbackRequest: object): boolean; + /** + * Determines if the service has access (has been authorized and hasn't expired). + * If offline access was granted and the previous token has expired this method attempts + * to generate a new token. + */ + hasAccess(): boolean; + /** + * Refreshes a token that has expired. + * This is only possible if offline access was requested when the token was authorized. + */ + refresh(): void; + /** + * Resets the service, removing access and requiring the service to be re-authorized. + */ + reset(): void; + /** + * Sets the service's authorization base URL (required). + * For Google services this URL should be `https://accounts.google.com/o/oauth2/auth`. + */ + setAuthorizationBaseUrl(authorizationBaseUrl: string): OAuth2Service; + /** + * Sets the cache to use when persisting credentials (optional). + * Using a cache will reduce the need to read from the property store and may increase + * performance. In most cases this should be a private cache, but a public cache may be + * appropriate if you want to share access across users. + */ + setCache(cache: GoogleAppsScript.Cache.Cache): OAuth2Service; + /** + * Sets the name of the authorization callback function (required). + * This is the function that will be called when the user completes the authorization flow + * on the service provider's website. The callback accepts a request parameter, which + * should be passed to this service's `handleCallback()` method to complete the process. + */ + setCallbackFunction(callbackFunctionName: string): OAuth2Service; + /** + * Sets the client ID to use for the OAuth flow (required). + * You can create client IDs in the "Credentials" section of a Google Developers Console + * project. Although you can use any project with this library, it may be convinient to use + * the project that was created for your script. These projects are not visible if you + * visit the console directly, but you can access it by click on the menu item + * "Resources > Advanced Google services" in the Script Editor, and then click on the link + * "Google Developers Console" in the resulting dialog. + */ + setClientId(clientId: string): OAuth2Service; + /** + * Sets the client secret to use for the OAuth flow (required). + * See the documentation for `setClientId()` for more information on how to create client IDs and secrets. + */ + setClientSecret(clientSecret: string): OAuth2Service; + /** + * Sets number of minutes that a token obtained through Service Account authorization should be valid. Default: 60 minutes. + */ + setExpirationMinutes(expirationMinutes: string): OAuth2Service; + /** + * Sets the issuer (iss) value to use for Service Account authorization. + * If not set the client ID will be used instead. + */ + setIssuer(issuer: string): OAuth2Service; + /** + * Sets an additional parameter to use when constructing the authorization URL (optional). + * See the documentation for your service provider for information on what parameter values they support. + */ + setParam(name: string, value: string): OAuth2Service; + /** + * Sets the private key to use for Service Account authorization. + */ + setPrivateKey(privateKey: string): OAuth2Service; + /** + * Sets the property store to use when persisting credentials (required). + * In most cases this should be user properties, but document or script properties may be appropriate + * if you want to share access across users. + */ + setPropertyStore(propertyStore: GoogleAppsScript.Properties.Properties): OAuth2Service; + /** + * Sets the scope or scopes to request during the authorization flow (optional). + * If the scope value is an array it will be joined using the separator before being sent to the server, + * which is is a space character by default. + */ + setScope(scope: string | string[], separator?: string): OAuth2Service; + /** + * Sets the subject (sub) value to use for Service Account authorization. + */ + setSubject(subject: string): OAuth2Service; + /** + * Sets the format of the returned token. Default: `OAuth2.TOKEN_FORMAT.JSON`. + */ + setTokenFormat(tokenFormat: TokenFormat): OAuth2Service; + /** + * Sets the additional HTTP headers that should be sent when retrieving or refreshing the access token. + */ + setTokenHeaders(tokenHeaders: { [key: string]: string }): OAuth2Service; + /** + * Sets an additional function to invoke on the payload of the access token request. + */ + setTokenPayloadHandler(tokenHandler: (tokenPayload: TokenPayload) => object): OAuth2Service; + /** + * Sets the service's token URL (required). + * For Google services this URL should be `https://accounts.google.com/o/oauth2/token`. + */ + setTokenUrl(tokenUrl: string): OAuth2Service; + } + + enum StateParameterLocation { + /** + * Pass the state parameter in the authorization URL. + */ + AUTHORIZATION_URL, + /** + * Pass the state token in the redirect URL, as a workaround for APIs that don't support the state parameter. + */ + REDIRECT_URL, + } + + enum TokenFormat { + /** + * JSON format, for example `{"access_token": "..."}`. + */ + JSON, + /** + * Form URL-encoded, for example `access_token=...`. + */ + FORM_URL_ENCODED, + } + + interface TokenPayload { + code: string; + client_id: string; + client_secret: string; + redirect_uri: string; + grant_type: string; + } +} + +declare var OAuth2: GoogleAppsScriptOAuth2.OAuth2; diff --git a/types/google-apps-script-oauth2/tsconfig.json b/types/google-apps-script-oauth2/tsconfig.json new file mode 100644 index 0000000000..bc09dd70b9 --- /dev/null +++ b/types/google-apps-script-oauth2/tsconfig.json @@ -0,0 +1,23 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "google-apps-script-oauth2-tests.ts" + ] +} diff --git a/types/google-apps-script-oauth2/tslint.json b/types/google-apps-script-oauth2/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/google-apps-script-oauth2/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" }