[google.script.client-side] Add types (#31792)

* [google.script.client-side] Add types

* [google.script.client-side] Put version and enable header lint rule

types/google.script.client-side/google.script.client-side-tests.ts

@@ -0,0 +1,39 @@
+google.script.url.getLocation(location => {
+    location.hash; // $ExpectedType string
+    location.parameter; // $ExpectedType { [key: string]: string }
+    location.parameters; // $ExpectedType { [key: string]: ReadonlyArray<string> }
+});
+
+google.script.history.push(null);
+google.script.history.push({ timestamp: Date.now() }, { foo: 'bar', fiz: 'baz' });
+google.script.history.push({ timestamp: Date.now() }, { foo: ['bar', 'cat'], fiz: 'baz' }, 'anchor1');
+
+google.script.history.replace(null);
+google.script.history.replace({ timestamp: Date.now() }, { foo: 'bar', fiz: 'baz' });
+google.script.history.replace({ timestamp: Date.now() }, { foo: ['bar', 'cat'], fiz: 'baz' }, 'anchor1');
+
+google.script.history.setChangeHandler(e => {
+    e.state; // $ExpectedType google.script.history.State
+    e.location.hash; // $ExpectedType string
+    e.location.parameter; // $ExpectedType { [key: string]: string }
+    e.location.parameters; // $ExpectedType { [key: string]: ReadonlyArray<string> }
+});
+
+google.script.host.origin; // $ExpectType string
+google.script.host.close();
+google.script.host.editor.focus();
+google.script.host.setHeight(450);
+google.script.host.setWidth(300);
+
+google.script.run.withSuccessHandler(() => {}).executeScript({ message: 'test for google.script.run' });
+
+google.script.run
+    .withSuccessHandler(value => {})
+    .withFailureHandler(error => {})
+    .getEmail();
+
+google.script.run
+    .withSuccessHandler((value, userObject) => {})
+    .withFailureHandler((error, userObject) => {})
+    .withUserObject({})
+    .getSomeData(Date.now(), { options: 'none' }, 'anchor1', true, null);

types/google.script.client-side/index.d.ts

@@ -0,0 +1,151 @@
+// Type definitions for Google Apps Script Client-side API 0.0
+// Project: https://developers.google.com/apps-script/guides/html/reference/host
+// Definitions by: clomie <https://github.com/clomie>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.2
+
+declare namespace google.script {
+    interface UrlLocation {
+        /**
+         * The string value of URL fragment after the # character, or an emptry string if no URL fragment is present
+         */
+        hash: string;
+
+        /**
+         * An object of key/value pairs that correspond to the URL request parameters.
+         * Only the first value will be returned for parameters that have multiple values.
+         * If no parameters are present, this will be an empty object.
+         */
+        parameter: { [key: string]: string };
+
+        /**
+         * An object similar to location.parameter, but with an array of values for each key.
+         * If no parameters are present, this will be an empty object.
+         */
+        parameters: { [key: string]: ReadonlyArray<string> };
+    }
+
+    namespace url {
+        /**
+         * Gets a URL location object and passes it to the specified callback function (as the only argument).
+         * @param callback a client-side callback function to run, using the location object as the only argument.
+         */
+        function getLocation(callback: (location: UrlLocation) => void): void;
+    }
+
+    namespace history {
+        type State = object | null;
+        interface Query {
+            [key: string]: string | ReadonlyArray<string>;
+        }
+
+        /**
+         * Pushes the provided state object, URL parameters and URL fragment onto the browser history stack.
+         * @param stateObject An developer-defined object to be associated with a browser history event, and which resurfaces when the state is popped.
+         * Typically used to store application state information (such as page data) for future retrieval.
+         * @param params An object containing URL parameters to associate with this state.
+         * For example, {foo: “bar”, fiz: “baz”} equates to "?foo=bar&fiz=baz".
+         * Alternatively, arrays can be used: {foo: [“bar”, “cat”], fiz: “baz”} equates to "?foo=bar&foo=cat&fiz=baz".
+         * If null or undefined, the current URL parameters are not changed. If empty, the URL parameters are cleared.
+         * @param hash The string URL fragment appearing after the '#' character.
+         * If null or undefined, the current URL fragment is not changed. If empty, the URL fragment is cleared.
+         */
+        function push(stateObject: State, params?: Query, hash?: string): void;
+
+        /**
+         * Replaces the top event on the browser history stack with the provided (developer-defined) state object, URL parameters and URL fragment.
+         * @param stateObject An developer-defined object to be associated with a browser history event, and which resurfaces when the state is popped.
+         * Typically used to store application state information (such as page data) for future retrieval.
+         * @param params An object containing URL parameters to associate with this state.
+         * For example, {foo: “bar”, fiz: “baz”} equates to "?foo=bar&fiz=baz".
+         * Alternatively, arrays can be used: {foo: [“bar”, “cat”], fiz: “baz”} equates to "?foo=bar&foo=cat&fiz=baz".
+         * If null or undefined, the current URL parameters are not changed. If empty, the URL parameters are cleared.
+         * @param hash The string URL fragment appearing after the '#' character.
+         * If null or undefined, the current URL fragment is not changed. If empty, the URL fragment is cleared.
+         */
+        function replace(stateObject: State, params?: Query, hash?: string): void;
+
+        interface HistoryChangeEvent {
+            /**
+             * The state object associated with the popped event.
+             * This object is identical to the state object that used in the corresponding push() or replace() method that added the popped state to the history stack.
+             */
+            state: State;
+
+            /**
+             * A location object associated with the popped event
+             */
+            location: UrlLocation;
+        }
+
+        /**
+         * Sets a callback function to respond to changes in the browser history.
+         * @param callback a client-side callback function to run upon a history change event, using the event object as the only argument.
+         */
+        function setChangeHandler(handler: (event: HistoryChangeEvent) => void): void;
+    }
+
+    namespace host {
+        /**
+         * Provides the host domain, so scripts can set their origin correctly.
+         */
+        const origin: string;
+
+        /**
+         * Closes the current dialog or sidebar.
+         */
+        function close(): void;
+
+        namespace editor {
+            /**
+             * Switches browser focus from the dialog or sidebar to the Google Docs, Sheets, or Forms editor.
+             */
+            function focus(): void;
+        }
+
+        /**
+         * Sets the height of the current dialog.
+         * @param height the new height, in pixels
+         */
+        function setHeight(height: number): void;
+
+        /**
+         * Sets the width of the current dialog.
+         * @param width the new width, in pixels
+         */
+        function setWidth(width: number): void;
+    }
+
+    const run: Runner;
+
+    interface Runner {
+        /**
+         * Executes the server-side Apps Script function with the corresponding name.
+         */
+        [functionName: string]: (...args: any[]) => void;
+
+        /**
+         * Sets a callback function to run if the server-side function throws an exception.
+         * Without a failure handler, failures are logged to the JavaScript console.
+         * To override this, call withFailureHandler(null) or supply a failure handler that does nothing.
+         * @param handler a client-side callback function to run if the server-side function throws an exception;
+         * the Error object is passed to the function as the first argument, and the user object (if any) is passed as a second argument
+         */
+        withFailureHandler(handler: (error: Error, object?: any) => void): Runner;
+
+        /**
+         * Sets a callback function to run if the server-side function returns successfully.
+         * @param handler a client-side callback function to run if the server-side function returns successfully;
+         * the server's return value is passed to the function as the first argument, and the user object (if any) is passed as a second argument
+         */
+        withSuccessHandler(handler: (value?: any, object?: any) => void): Runner;
+
+        /**
+         * Sets an object to pass as a second parameter to the success and failure handlers.
+         * @param object an object to pass as a second parameter to the success and failure handlers;
+         * because user objects are not sent to the server, they are not subject to the restrictions on parameters and return values for server calls.
+         * User objects cannot, however, be objects constructed with the new operator
+         */
+        withUserObject(object: any): Runner;
+    }
+}

types/google.script.client-side/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.script.client-side-tests.ts"
+    ]
+}

types/google.script.client-side/tslint.json

@@ -0,0 +1,3 @@
+{
+    "extends": "dtslint/dt.json"
+}