diff --git a/types/actions-on-google/actions-sdk-app.d.ts b/types/actions-on-google/actions-sdk-app.d.ts index 28281a6c6b..99c8bd900b 100644 --- a/types/actions-on-google/actions-sdk-app.d.ts +++ b/types/actions-on-google/actions-sdk-app.d.ts @@ -1,20 +1,38 @@ -/** - * @typedef {object} ActionsSdkAppOptions JSON configuration. - * @property {TODO} request - Express HTTP request object. - * @property {TODO} response - Express HTTP response object. - * @property {TODO=} sessionStarted - Function callback when session starts. - */ +import * as express from 'express'; + +import { AssistantApp } from './assistant-app'; +import { Carousel, List, RichResponse, SimpleResponse } from './response-builder'; + +// --------------------------------------------------------------------------- +// Actions SDK support +// --------------------------------------------------------------------------- + declare type ActionsSdkAppOptions = { - request: any; - response: any; - sessionStarted: any; + /** Express HTTP request object. */ + request: express.Request; + /** Express HTTP response object. */ + response: express.Response; + /** Function callback when session starts. */ + sessionStarted?: () => any; }; /** * This is the class that handles the conversation API directly from Assistant, * providing implementation for all the methods available in the API. */ -declare class ActionsSdkApp { +declare class ActionsSdkApp extends AssistantApp { + /** + * Constructor for ActionsSdkApp object. + * To be used in the Actions SDK HTTP endpoint logic. + * + * @example + * const ActionsSdkApp = require('actions-on-google').ActionsSdkApp; + * const app = new ActionsSdkApp({request: request, response: response, + * sessionStarted:sessionStarted}); + * + * @param {ActionsSdkAppOptions} options + * @actionssdk + */ constructor(options: ActionsSdkAppOptions); /** @@ -22,6 +40,7 @@ declare class ActionsSdkApp { * Uses Google-Auth-Library to verify authorization token against given * Google Cloud Project ID. Auth token is given in request header with key, * "Authorization". + * * @example * const app = new ActionsSdkApp({request, response}); * app.isRequestFromAssistant('nodejs-cloud-test-project-1234') @@ -31,19 +50,22 @@ declare class ActionsSdkApp { * .catch(err => { * response.status(400).send(); * }); + * * @param {string} projectId Google Cloud Project ID for the Assistant app. - * @return {TODO} Promise resolving with google-auth-library LoginTicket + * @return {Promise} Promise resolving with google-auth-library LoginTicket * if request is from a valid source, otherwise rejects with the error reason * for an invalid token. * @actionssdk */ - isRequestFromAssistant(projectId: string): any; + isRequestFromAssistant(projectId: string): Promise; /** * Gets the request Conversation API version. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); * const apiVersion = app.getApiVersion(); + * * @return {string} Version value or null if no value. * @actionssdk */ @@ -51,9 +73,11 @@ declare class ActionsSdkApp { /** * Gets the user's raw input query. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); * app.tell('You said ' + app.getRawInput()); + * * @return {string} User's raw query or null if no value. * @actionssdk */ @@ -62,9 +86,11 @@ declare class ActionsSdkApp { /** * Gets previous JSON dialog state that the app sent to Assistant. * Alternatively, use the app.data field to store JSON values between requests. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); * const dialogState = app.getDialogState(); + * * @return {any} JSON object provided to the Assistant in the previous * user turn or {} if no value. * @actionssdk @@ -74,9 +100,11 @@ declare class ActionsSdkApp { /** * Gets the "versionLabel" specified inside the Action Package. * Used by app to do version control. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); * const actionVersionLabel = app.getActionVersionLabel(); + * * @return {string} The specified version label or null if unspecified. * @actionssdk */ @@ -85,9 +113,11 @@ declare class ActionsSdkApp { /** * Gets the unique conversation ID. It's a new ID for the initial query, * and stays the same until the end of the conversation. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); * const conversationId = app.getConversationId(); + * * @return {string} Conversation ID or null if no value. * @actionssdk */ @@ -97,8 +127,10 @@ declare class ActionsSdkApp { * Get the current intent. Alternatively, using a handler Map with * {@link AssistantApp#handleRequest|handleRequest}, the client library will * automatically handle the incoming intents. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); + * * function responseHandler (app) { * const intent = app.getIntent(); * switch (intent) { @@ -106,12 +138,15 @@ declare class ActionsSdkApp { * const inputPrompt = app.buildInputPrompt(false, 'Welcome to action snippets! Say anything.'); * app.ask(inputPrompt); * break; + * * case app.StandardIntents.TEXT: * app.tell('You said ' + app.getRawInput()); * break; * } * } + * * app.handleRequest(responseHandler); + * * @return {string} Intent id or null if no value. * @actionssdk */ @@ -120,8 +155,10 @@ declare class ActionsSdkApp { /** * Get the argument value by name from the current intent. If the argument * is not a text argument, the entire argument object is returned. + * * Note: If incoming request is using an API version under 2 (e.g. 'v1'), * the argument object will be in Proto2 format (snake_case, etc). + * * @param {string} argName Name of the argument. * @return {string} Argument value matching argName * or null if no matching argument. @@ -131,8 +168,10 @@ declare class ActionsSdkApp { /** * Returns the option key user chose from options response. + * * @example * const app = new App({request: req, response: res}); + * * function pickOption (app) { * if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) { * app.askWithCarousel('Which of these looks good?', @@ -143,13 +182,17 @@ declare class ActionsSdkApp { * app.ask('What would you like?'); * } * } + * * function optionPicked (app) { * app.ask('You picked ' + app.getSelectedOption()); * } + * * const actionMap = new Map(); * actionMap.set(app.StandardIntents.TEXT, pickOption); * actionMap.set(app.StandardIntents.OPTION, optionPicked); + * * app.handleRequest(actionMap); + * * @return {string} Option key of selected item. Null if no option selected or * if current intent is not OPTION intent. * @actionssdk @@ -160,8 +203,10 @@ declare class ActionsSdkApp { * Asks to collect user's input; all user's queries need to be sent to * the app. * {@link https://developers.google.com/actions/policies/general-policies#user_experience|The guidelines when prompting the user for a response must be followed at all times}. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); + * * function mainIntent (app) { * const inputPrompt = app.buildInputPrompt(true, 'Hi! ' + * 'I can read out an ordinal like ' + @@ -169,6 +214,7 @@ declare class ActionsSdkApp { * ['I didn\'t hear a number', 'If you\'re still there, what\'s the number?', 'What is the number?']); * app.ask(inputPrompt); * } + * * function rawInput (app) { * if (app.getRawInput() === 'bye') { * app.tell('Goodbye!'); @@ -179,23 +225,28 @@ declare class ActionsSdkApp { * app.ask(inputPrompt); * } * } + * * const actionMap = new Map(); * actionMap.set(app.StandardIntents.MAIN, mainIntent); * actionMap.set(app.StandardIntents.TEXT, rawInput); + * * app.handleRequest(actionMap); - * @param {InputPrompt|SimpleResponse|RichResponse} inputPrompt Holding initial and + * + * @param {Object|SimpleResponse|RichResponse} inputPrompt Holding initial and * no-input prompts. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by App. - * @return {AskTellResponse} The response that is sent to Assistant to ask user to provide input. + * @return {express.Response|null} The response that is sent to Assistant to ask user to provide input. * @actionssdk */ - ask(inputPrompt: InputPrompt | SimpleResponse | RichResponse, dialogState?: DialogState): AskTellResponse; + ask(inputPrompt: object | SimpleResponse | RichResponse, dialogState?: object): express.Response | null; /** * Asks to collect user's input with a list. + * * @example * const app = new ActionsSdkApp({request, response}); + * * function welcomeIntent (app) { * app.askWithlist('Which of these looks good?', * app.buildList('List title') @@ -208,6 +259,7 @@ declare class ActionsSdkApp { * .setTitle('Number two'), * ])); * } + * * function optionIntent (app) { * if (app.getSelectedOption() === SELECTION_KEY_ONE) { * app.tell('Number one is a great choice!'); @@ -215,24 +267,28 @@ declare class ActionsSdkApp { * app.tell('Number two is a great choice!'); * } * } + * * const actionMap = new Map(); * actionMap.set(app.StandardIntents.TEXT, welcomeIntent); * actionMap.set(app.StandardIntents.OPTION, optionIntent); * app.handleRequest(actionMap); - * @param {InputPrompt|SimpleResponse|RichResponse} inputPrompt Holding initial and + * + * @param {Object|SimpleResponse|RichResponse} inputPrompt Holding initial and * no-input prompts. Cannot contain basic card. * @param {List} list List built with {@link AssistantApp#buildList|buildList}. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. - * @return {AskTellResponse} The response that is sent to Assistant to ask user to provide input. + * @return {express.Response|null} The response that is sent to Assistant to ask user to provide input. * @actionssdk */ - askWithList(inputPrompt: InputPrompt | SimpleResponse | RichResponse, list: List, dialogState?: DialogState): AskTellResponse; + askWithList(inputPrompt: object | SimpleResponse | RichResponse, list: List, dialogState?: object): express.Response | null; /** * Asks to collect user's input with a carousel. + * * @example * const app = new ActionsSdkApp({request, response}); + * * function welcomeIntent (app) { * app.askWithCarousel('Which of these looks good?', * app.buildCarousel() @@ -245,6 +301,7 @@ declare class ActionsSdkApp { * .setTitle('Number two'), * ])); * } + * * function optionIntent (app) { * if (app.getSelectedOption() === SELECTION_KEY_ONE) { * app.tell('Number one is a great choice!'); @@ -252,25 +309,29 @@ declare class ActionsSdkApp { * app.tell('Number two is a great choice!'); * } * } + * * const actionMap = new Map(); * actionMap.set(app.StandardIntents.TEXT, welcomeIntent); * actionMap.set(app.StandardIntents.OPTION, optionIntent); * app.handleRequest(actionMap); - * @param {InputPrompt|SimpleResponse|RichResponse} inputPrompt Holding initial and + * + * @param {Object|SimpleResponse|RichResponse} inputPrompt Holding initial and * no-input prompts. Cannot contain basic card. * @param {Carousel} carousel Carousel built with * {@link AssistantApp#buildCarousel|buildCarousel}. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. - * @return {AskTellResponse} The response that is sent to Assistant to ask user to provide input. + * @return {express.Response|null} The response that is sent to Assistant to ask user to provide input. * @actionssdk */ - askWithCarousel(inputPrompt: InputPrompt | SimpleResponse | RichResponse, carousel: Carousel, dialogState?: DialogState): AskTellResponse; + askWithCarousel(inputPrompt: object | SimpleResponse | RichResponse, carousel: Carousel, dialogState?: object): express.Response | null; /** * Tells Assistant to render the speech response and close the mic. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); + * * function mainIntent (app) { * const inputPrompt = app.buildInputPrompt(true, 'Hi! ' + * 'I can read out an ordinal like ' + @@ -278,6 +339,7 @@ declare class ActionsSdkApp { * ['I didn\'t hear a number', 'If you\'re still there, what\'s the number?', 'What is the number?']); * app.ask(inputPrompt); * } + * * function rawInput (app) { * if (app.getRawInput() === 'bye') { * app.tell('Goodbye!'); @@ -288,258 +350,43 @@ declare class ActionsSdkApp { * app.ask(inputPrompt); * } * } + * * const actionMap = new Map(); * actionMap.set(app.StandardIntents.MAIN, mainIntent); * actionMap.set(app.StandardIntents.TEXT, rawInput); + * * app.handleRequest(actionMap); + * * @param {string|SimpleResponse|RichResponse} textToSpeech Final response. * Spoken response can be SSML. - * @return {AskTellResponse} The HTTP response that is sent back to Assistant. + * @return {express.Response|null} The HTTP response that is sent back to Assistant. * @actionssdk */ - tell(textToSpeech: string | SimpleResponse | RichResponse): AskTellResponse; + tell(textToSpeech: string | SimpleResponse | RichResponse): express.Response | null; /** * Builds the {@link https://developers.google.com/actions/reference/conversation#InputPrompt|InputPrompt object} * from initial prompt and no-input prompts. + * * The App needs one initial prompt to start the conversation. If there is no user response, * the App re-opens the mic and renders the no-input prompts three times * (one for each no-input prompt that was configured) to help the user * provide the right response. + * * Note: we highly recommend app to provide all the prompts required here in order to ensure a * good user experience. + * * @example * const inputPrompt = app.buildInputPrompt(false, 'Welcome to action snippets! Say a number.', * ['Say any number', 'Pick a number', 'What is the number?']); * app.ask(inputPrompt); + * * @param {boolean} isSsml Indicates whether the text to speech is SSML or not. * @param {string} initialPrompt The initial prompt the App asks the user. * @param {Array=} noInputs Array of re-prompts when the user does not respond (max 3). - * @return {InputPrompt} An {@link https://developers.google.com/actions/reference/conversation#InputPrompt|InputPrompt object}. + * @return {Object} An {@link https://developers.google.com/actions/reference/conversation#InputPrompt|InputPrompt object}. * @actionssdk */ - buildInputPrompt(isSsml: boolean, initialPrompt: string, noInputs?: string[]): InputPrompt; + buildInputPrompt(isSsml: boolean, initialPrompt: string, noInputs?: string[]): object; } - -/** - * List of standard intents that the app provides. - * @readonly - * @enum {string} - * @actionssdk - * @dialogflow - */ -declare const enum StandardIntents { - /** - * App fires MAIN intent for queries like [talk to $app]. - */ - MAIN, - /** - * App fires TEXT intent when action issues ask intent. - */ - TEXT, - /** - * App fires PERMISSION intent when action invokes askForPermission. - */ - PERMISSION, - /** - * App fires OPTION intent when user chooses from options provided. - */ - OPTION, - /** - * App fires TRANSACTION_REQUIREMENTS_CHECK intent when action sets up transaction. - */ - TRANSACTION_REQUIREMENTS_CHECK, - /** - * App fires DELIVERY_ADDRESS intent when action asks for delivery address. - */ - DELIVERY_ADDRESS, - /** - * App fires TRANSACTION_DECISION intent when action asks for transaction decision. - */ - TRANSACTION_DECISION, - /** - * App fires CONFIRMATION intent when requesting affirmation from user. - */ - CONFIRMATION, - /** - * App fires DATETIME intent when requesting date/time from user. - */ - DATETIME, - /** - * App fires SIGN_IN intent when requesting sign-in from user. - */ - SIGN_IN, - /** - * App fires NO_INPUT intent when user doesn't provide input. - */ - NO_INPUT, - /** - * App fires CANCEL intent when user exits app mid-dialog. - */ - CANCEL, - /** - * App fires NEW_SURFACE intent when requesting handoff to a new surface from user. - */ - NEW_SURFACE, -} - -/** - * List of supported permissions the app supports. - * @readonly - * @enum {string} - * @actionssdk - * @dialogflow - */ -declare const enum SupportedPermissions { - /** - * The user's name as defined in the - * {@link https://developers.google.com/actions/reference/conversation#UserProfile|UserProfile object} - */ - NAME, - /** - * The location of the user's current device, as defined in the - * {@link https://developers.google.com/actions/reference/conversation#Location|Location object}. - */ - DEVICE_PRECISE_LOCATION, - /** - * City and zipcode corresponding to the location of the user's current device, as defined in the - * {@link https://developers.google.com/actions/reference/conversation#Location|Location object}. - */ - DEVICE_COARSE_LOCATION, -} - -/** - * List of built-in argument names. - * @readonly - * @enum {string} - * @actionssdk - * @dialogflow - */ -declare const enum BuiltInArgNames { - /** - * Permission granted argument. - */ - PERMISSION_GRANTED, - /** - * Option selected argument. - */ - OPTION, - /** - * Transaction requirements check result argument. - */ - TRANSACTION_REQ_CHECK_RESULT, - /** - * Delivery address value argument. - */ - DELIVERY_ADDRESS_VALUE, - /** - * Transactions decision argument. - */ - TRANSACTION_DECISION_VALUE, - /** - * Confirmation argument. - */ - CONFIRMATION, - /** - * DateTime argument. - */ - DATETIME, - /** - * Sign in status argument. - */ - SIGN_IN, - /** - * Reprompt count for consecutive NO_INPUT intents. - */ - REPROMPT_COUNT, - /** - * Flag representing finality of NO_INPUT intent. - */ - IS_FINAL_REPROMPT, - /** - * New surface value argument. - */ - NEW_SURFACE, -} - -/** - * List of possible conversation stages, as defined in the - * {@link https://developers.google.com/actions/reference/conversation#Conversation|Conversation object}. - * @readonly - * @enum {number} - * @actionssdk - * @dialogflow - */ -declare const enum ConversationStages { - /** - * Unspecified conversation state. - */ - UNSPECIFIED, - /** - * A new conversation. - */ - NEW, - /** - * An active (ongoing) conversation. - */ - ACTIVE, -} - -/** - * List of surface capabilities supported by the app. - * @readonly - * @enum {string} - * @actionssdk - * @dialogflow - */ -declare const enum SurfaceCapabilities { - /** - * The ability to output audio. - */ - AUDIO_OUTPUT, - /** - * The ability to output on a screen - */ - SCREEN_OUTPUT, -} - -/** - * List of possible user input types. - * @readonly - * @enum {number} - * @actionssdk - * @dialogflow - */ -declare const enum InputTypes { - /** - * Unspecified. - */ - UNSPECIFIED, - /** - * Input given by touch. - */ - TOUCH, - /** - * Input given by voice (spoken). - */ - VOICE, - /** - * Input given by keyboard (typed). - */ - KEYBOARD, -} - -/** - * List of possible sign in result status values. - * @readonly - * @enum {string} - * @actionssdk - * @dialogflow - */ -declare const enum SignInStatus { - UNSPECIFIED, - OK, - CANCELLED, - ERROR, -} diff --git a/types/actions-on-google/assistant-app.d.ts b/types/actions-on-google/assistant-app.d.ts index b83a77a1c7..28125bc4bf 100644 --- a/types/actions-on-google/assistant-app.d.ts +++ b/types/actions-on-google/assistant-app.d.ts @@ -1,125 +1,400 @@ +import * as express from 'express'; + +import { BasicCard, Carousel, List, OptionItem, RichResponse } from './response-builder'; +import { ActionPaymentTransactionConfig, Cart, GooglePaymentTransactionConfig, LineItem, + Order, OrderUpdate, TransactionDecision, TransactionValues } from './transactions'; /** - * @typedef {object} AssistantAppOptions JSON configuration. - * @property {TODO} request - Express HTTP request object. - * @property {TODO} response - Express HTTP response object. - * @property {TODO=} sessionStarted - Function callback when session starts. + * List of standard intents that the app provides. + * @enum {string} + * @actionssdk + * @dialogflow */ -declare type AssistantAppOptions = { - request: any; - response: any; - sessionStarted: any; +declare enum StandardIntents { + /** + * App fires MAIN intent for queries like [talk to $app]. + */ + MAIN, + /** + * App fires TEXT intent when action issues ask intent. + */ + TEXT, + /** + * App fires PERMISSION intent when action invokes askForPermission. + */ + PERMISSION, + /** + * App fires OPTION intent when user chooses from options provided. + */ + OPTION, + /** + * App fires TRANSACTION_REQUIREMENTS_CHECK intent when action sets up transaction. + */ + TRANSACTION_REQUIREMENTS_CHECK, + /** + * App fires DELIVERY_ADDRESS intent when action asks for delivery address. + */ + DELIVERY_ADDRESS, + /** + * App fires TRANSACTION_DECISION intent when action asks for transaction decision. + */ + TRANSACTION_DECISION, + /** + * App fires CONFIRMATION intent when requesting affirmation from user. + */ + CONFIRMATION, + /** + * App fires DATETIME intent when requesting date/time from user. + */ + DATETIME, + /** + * App fires SIGN_IN intent when requesting sign-in from user. + */ + SIGN_IN, + /** + * App fires NO_INPUT intent when user doesn't provide input. + */ + NO_INPUT, + /** + * App fires CANCEL intent when user exits app mid-dialog. + */ + CANCEL, + /** + * App fires NEW_SURFACE intent when requesting handoff to a new surface from user. + */ + NEW_SURFACE, +} + +/** + * List of supported permissions the app supports. + * @enum {string} + * @actionssdk + * @dialogflow + */ +declare enum SupportedPermissions { + /** + * The user's name as defined in the + * {@link https://developers.google.com/actions/reference/conversation#UserProfile|UserProfile object} + */ + NAME, + /** + * The location of the user's current device, as defined in the + * {@link https://developers.google.com/actions/reference/conversation#Location|Location object}. + */ + DEVICE_PRECISE_LOCATION, + /** + * City and zipcode corresponding to the location of the user's current device, as defined in the + * {@link https://developers.google.com/actions/reference/conversation#Location|Location object}. + */ + DEVICE_COARSE_LOCATION, +} + +/** + * List of built-in argument names. + * @enum {string} + * @actionssdk + * @dialogflow + */ +declare enum BuiltInArgNames { + /** + * Permission granted argument. + */ + PERMISSION_GRANTED, + /** + * Option selected argument. + */ + OPTION, + /** + * Transaction requirements check result argument. + */ + TRANSACTION_REQ_CHECK_RESULT, + /** + * Delivery address value argument. + */ + DELIVERY_ADDRESS_VALUE, + /** + * Transactions decision argument. + */ + TRANSACTION_DECISION_VALUE, + /** + * Confirmation argument. + */ + CONFIRMATION, + /** + * DateTime argument. + */ + DATETIME, + /** + * Sign in status argument. + */ + SIGN_IN, + /** + * Reprompt count for consecutive NO_INPUT intents. + */ + REPROMPT_COUNT, + /** + * Flag representing finality of NO_INPUT intent. + */ + IS_FINAL_REPROMPT, + /** + * New surface value argument. + */ + NEW_SURFACE, +} + +/** + * List of possible conversation stages, as defined in the + * {@link https://developers.google.com/actions/reference/conversation#Conversation|Conversation object}. + * @enum {number|string} + * @actionssdk + * @dialogflow + */ +declare enum ConversationStages { + /** + * Unspecified conversation state. + */ + UNSPECIFIED, + /** + * A new conversation. + */ + NEW, + /** + * An active (ongoing) conversation. + */ + ACTIVE, +} + +/** + * List of surface capabilities supported by the app. + * @enum {string} + * @actionssdk + * @dialogflow + */ +declare enum SurfaceCapabilities { + /** + * The ability to output audio. + */ + AUDIO_OUTPUT, + /** + * The ability to output on a screen + */ + SCREEN_OUTPUT, +} + +/** + * List of possible user input types. + * @enum {number|string} + * @actionssdk + * @dialogflow + */ +declare enum InputTypes { + /** + * Unspecified. + */ + UNSPECIFIED, + /** + * Input given by touch. + */ + TOUCH, + /** + * Input given by voice (spoken). + */ + VOICE, + /** + * Input given by keyboard (typed). + */ + KEYBOARD +} + +/** + * List of possible sign in result status values. + * @enum {string} + * @actionssdk + * @dialogflow + */ +declare enum SignInStatus { + /** + * Unknown status. + */ + UNSPECIFIED, + /** + * User successfully completed the account linking. + */ + OK, + /** + * Cancelled or dismissed account linking. + */ + CANCELLED, + /** + * System or network error. + */ + ERROR +} + +/** + * User provided date/time info. + */ +declare type DateTime = { + date: { + year: number; + month: number; + day: number; + }; + time: { + hours: number; + minutes: number; + seconds: number; + nanos: number; + }; +}; + +/** + * User's permissioned name info. + */ +declare type UserName = { + /** User's display name. */ + displayName: string; + /** User's given name. */ + givenName: string; + /** User's family name. */ + familyName: string; +}; + +/** + * User's permissioned device location. + */ +declare type DeviceLocation = { + /** {latitude, longitude}. Requested with SupportedPermissions.DEVICE_PRECISE_LOCATION. */ + coordinates: object; + /** Full, formatted street address. Requested with SupportedPermissions.DEVICE_PRECISE_LOCATION. */ + address: string; + /** Zip code. Requested with SupportedPermissions.DEVICE_COARSE_LOCATION. */ + zipCode: string; + /** Device city. Requested with SupportedPermissions.DEVICE_COARSE_LOCATION. */ + city: string; +}; + +/** + * User object. + */ +declare type User = { + /** Random string ID for Google user. */ + userId: string; + /** User name information. Null if not requested with {@link AssistantApp#askForPermission|askForPermission(SupportedPermissions.NAME)}. */ + userName: UserName; + /** Unique Oauth2 token. Only available with account linking. */ + accessToken: string; +}; + +/** + * Actions on Google Surface. + */ +declare type Surface = { + /** Capabilities of the surface. */ + capabilities: Capability[]; +}; + +/** + * Surface capability. + */ +declare type Capability = { + /** Name of the capability. */ + name: string; }; /** * The Actions on Google client library AssistantApp base class. + * * This class contains the methods that are shared between platforms to support the conversation API * protocol from Assistant. It also exports the 'State' class as a helper to represent states by * name. */ declare class AssistantApp { - constructor(options: AssistantAppOptions, requestData: any); - /** * The session state. - * @public - * @type {string} */ state: string; /** * The session data in JSON format. - * @public - * @type {Object} */ - data: any; + data: object; /** * List of standard intents that the app provides. * @readonly - * @type {TODO} * @actionssdk * @dialogflow */ - readonly StandardIntents: any; + readonly StandardIntents: typeof StandardIntents; /** * List of supported permissions the app supports. * @readonly - * @type {TODO} * @actionssdk * @dialogflow */ - readonly SupportedPermissions: any; + readonly SupportedPermissions: typeof SupportedPermissions; /** * List of built-in argument names. * @readonly - * @type {TODO} * @actionssdk * @dialogflow */ - readonly BuiltInArgNames: any; - - /** - * The property name used when specifying an input value data spec. - * @readonly - * @type {string} - * @actionssdk - * @dialogflow - */ - readonly ANY_TYPE_PROPERTY_: string; + readonly BuiltInArgNames: typeof BuiltInArgNames; /** * List of possible conversation stages, as defined in the * {@link https://developers.google.com/actions/reference/conversation#Conversation|Conversation object}. * @readonly - * @type {TODO} * @actionssdk * @dialogflow */ - readonly ConversationStages: any; + readonly ConversationStages: typeof ConversationStages; /** * List of surface capabilities supported by the app. * @readonly - * @type {TODO} * @actionssdk * @dialogflow */ - readonly SurfaceCapabilities: any; + readonly SurfaceCapabilities: typeof SurfaceCapabilities; /** * List of possible user input types. * @readonly - * @type {TODO} * @actionssdk * @dialogflow */ - readonly InputTypes: any; + readonly InputTypes: typeof InputTypes; /** * List of possible sign in result status values. * @readonly - * @type {TODO} * @actionssdk * @dialogflow */ - readonly SignInStatus: any; + readonly SignInStatus: typeof SignInStatus; /** * Values related to supporting {@link Transactions}. * @readonly - * @type {TODO} */ - readonly Transactions: any; + readonly Transactions: typeof TransactionValues; + + // --------------------------------------------------------------------------- + // Public APIs + // --------------------------------------------------------------------------- /** * Handles the incoming Assistant request using a handler or Map of handlers. * Each handler can be a function callback or Promise. + * * @example * // Actions SDK * const app = new ActionsSdkApp({request: request, response: response}); + * * function mainIntent (app) { * const inputPrompt = app.buildInputPrompt(true, 'Hi! ' + * 'I can read out an ordinal like ' + @@ -127,6 +402,7 @@ declare class AssistantApp { * ['I didn\'t hear a number', 'If you\'re still there, what\'s the number?', 'What is the number?']); * app.ask(inputPrompt); * } + * * function rawInput (app) { * if (app.getRawInput() === 'bye') { * app.tell('Goodbye!'); @@ -137,15 +413,19 @@ declare class AssistantApp { * app.ask(inputPrompt); * } * } + * * const actionMap = new Map(); * actionMap.set(app.StandardIntents.MAIN, mainIntent); * actionMap.set(app.StandardIntents.TEXT, rawInput); + * * app.handleRequest(actionMap); + * * // Dialogflow * const app = new DialogflowApp({request: req, response: res}); * const NAME_ACTION = 'make_name'; * const COLOR_ARGUMENT = 'color'; * const NUMBER_ARGUMENT = 'number'; + * * function makeName (app) { * const number = app.getArgument(NUMBER_ARGUMENT); * const color = app.getArgument(COLOR_ARGUMENT); @@ -153,19 +433,24 @@ declare class AssistantApp { * color + ' ' + number + * '! I hope you like it. See you next time.'); * } + * * const actionMap = new Map(); * actionMap.set(NAME_ACTION, makeName); * app.handleRequest(actionMap); + * * @param {(Function|Map)} handler The handler (or Map of handlers) for the request. + * @return {undefined} * @actionssdk * @dialogflow */ - handleRequest(handler: any | any): void; + handleRequest(handler: ((app: AssistantApp) => any) | (Map any>)): void; /** * Equivalent to {@link AssistantApp#askForPermission|askForPermission}, * but allows you to prompt the user for more than one permission at once. + * * Notes: + * * * The order in which you specify the permission prompts does not matter - * it is controlled by the Assistant to provide a consistent user experience. * * The user will be able to either accept all permissions at once, or none. @@ -173,10 +458,12 @@ declare class AssistantApp { * dialog turns asking for each permission independently with askForPermission. * * Asking for DEVICE_COARSE_LOCATION and DEVICE_PRECISE_LOCATION at once is * equivalent to just asking for DEVICE_PRECISE_LOCATION + * * @example * const app = new DialogflowApp({request: req, response: res}); * const REQUEST_PERMISSION_ACTION = 'request_permission'; * const GET_RIDE_ACTION = 'get_ride'; + * * function requestPermission (app) { * const permission = [ * app.SupportedPermissions.NAME, @@ -184,6 +471,7 @@ declare class AssistantApp { * ]; * app.askForPermissions('To pick you up', permissions); * } + * * function sendRide (app) { * if (app.isPermissionGranted()) { * const displayName = app.getUserName().displayName; @@ -199,25 +487,28 @@ declare class AssistantApp { * actionMap.set(REQUEST_PERMISSION_ACTION, requestPermission); * actionMap.set(GET_RIDE_ACTION, sendRide); * app.handleRequest(actionMap); + * * @param {string} context Context why the permission is being asked; it's the TTS * prompt prefix (action phrase) we ask the user. * @param {Array} permissions Array of permissions App supports, each of * which comes from AssistantApp.SupportedPermissions. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. Used in {@link ActionsSdkAssistant}. - * @return {AskTellResponse} A response is sent to Assistant to ask for the user's permission; for any + * @return {express.Response|null} A response is sent to Assistant to ask for the user's permission; for any * invalid input, we return null. * @actionssdk * @dialogflow */ - askForPermissions(context: string, permissions: string[], dialogState?: DialogState): AskTellResponse; + askForPermissions(context: string, permissions: string[], dialogState?: object): express.Response | null; /** * Checks whether user is in transactable state. + * * @example * const app = new DialogflowApp({request: request, response: response}); * const WELCOME_INTENT = 'input.welcome'; * const TXN_REQ_COMPLETE = 'txn.req.complete'; + * * let transactionConfig = { * deliveryAddressRequired: false, * type: app.Transactions.PaymentType.BANK, @@ -226,6 +517,7 @@ declare class AssistantApp { * function welcomeIntent (app) { * app.askForTransactionRequirements(transactionConfig); * } + * * function txnReqCheck (app) { * if (app.getTransactionRequirementsResult() === app.Transactions.ResultType.OK) { * // continue cart building flow @@ -233,55 +525,64 @@ declare class AssistantApp { * // don't continue cart building * } * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(TXN_REQ_COMPLETE, txnReqCheck); * app.handleRequest(actionMap); + * * @param {ActionPaymentTransactionConfig|GooglePaymentTransactionConfig=} * transactionConfig Configuration for the transaction. Includes payment * options and order options. Optional if order has no payment or * delivery. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. Used in {@link ActionsSdkAssistant}. - * @return {AskTellResponse} HTTP response. + * @return {express.Response|null} HTTP response. * @actionssdk * @dialogflow */ - askForTransactionRequirements(transactionConfig: ActionPaymentTransactionConfig | GooglePaymentTransactionConfig, dialogState?: DialogState): AskTellResponse; + askForTransactionRequirements(transactionConfig?: ActionPaymentTransactionConfig | GooglePaymentTransactionConfig, dialogState?: object): express.Response | null; /** * Asks user to confirm transaction information. + * * @example * const app = new DialogflowApp({request: request, response: response}); * const WELCOME_INTENT = 'input.welcome'; * const TXN_COMPLETE = 'txn.complete'; + * * let transactionConfig = { * deliveryAddressRequired: false, * type: app.Transactions.PaymentType.BANK, * displayName: 'Checking-1234' * }; + * * let order = app.buildOrder(); * // fill order cart + * * function welcomeIntent (app) { * app.askForTransaction(order, transactionConfig); * } + * * function txnComplete (app) { * // respond with order update * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(TXN_COMPLETE, txnComplete); * app.handleRequest(actionMap); + * * @param {Order} order Order built with buildOrder(). * @param {ActionPaymentTransactionConfig|GooglePaymentTransactionConfig} * transactionConfig Configuration for the transaction. Includes payment * options and order options. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. Used in {@link ActionsSdkAssistant}. - * @return {AskTellResponse} HTTP response + * @return {express.Response|null} HTTP response * @dialogflow */ - askForTransactionDecision(order: Order, transactionConfig: ActionPaymentTransactionConfig | GooglePaymentTransactionConfig, dialogState?: DialogState): AskTellResponse; + askForTransactionDecision(order: Order, transactionConfig: ActionPaymentTransactionConfig | GooglePaymentTransactionConfig, dialogState?: object): express.Response | null; /** * Asks the Assistant to guide the user to grant a permission. For example, @@ -290,22 +591,28 @@ declare class AssistantApp { * and the AssistantApp.SupportedPermissions.NAME permission. With this, the Assistant will ask * the user, in your agent's voice, the following: '[Context with reason for the request], * I'll just need to get your name from Google, is that OK?'. + * * Once the user accepts or denies the request, the Assistant will fire another intent: * assistant.intent.action.PERMISSION with a boolean argument: AssistantApp.BuiltInArgNames.PERMISSION_GRANTED * and, if granted, the information that you requested. + * * Read more: + * * * {@link https://developers.google.com/actions/reference/conversation#ExpectedIntent|Supported Permissions} * * Check if the permission has been granted with {@link AssistantApp#isPermissionGranted|isPermissionsGranted} * * {@link AssistantApp#getDeviceLocation|getDeviceLocation} * * {@link AssistantApp#getUserName|getUserName} + * * @example * const app = new DialogflowApp({request: req, response: res}); * const REQUEST_PERMISSION_ACTION = 'request_permission'; * const GET_RIDE_ACTION = 'get_ride'; + * * function requestPermission (app) { * const permission = app.SupportedPermissions.NAME; * app.askForPermission('To pick you up', permission); * } + * * function sendRide (app) { * if (app.isPermissionGranted()) { * const displayName = app.getUserName().displayName; @@ -319,23 +626,25 @@ declare class AssistantApp { * actionMap.set(REQUEST_PERMISSION_ACTION, requestPermission); * actionMap.set(GET_RIDE_ACTION, sendRide); * app.handleRequest(actionMap); + * * @param {string} context Context why permission is asked; it's the TTS * prompt prefix (action phrase) we ask the user. * @param {string} permission One of the permissions Assistant supports, each of * which comes from AssistantApp.SupportedPermissions. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. - * @return {AskTellResponse} A response is sent to the Assistant to ask for the user's permission; + * @return {express.Response|null} A response is sent to the Assistant to ask for the user's permission; * for any invalid input, we return null. * @actionssdk * @dialogflow */ - askForPermission(context: string, permission: string, dialogState?: DialogState): AskTellResponse; + askForPermission(context: string, permission: string, dialogState?: object): express.Response | null; /** * Returns true if the request follows a previous request asking for * permission from the user and the user granted the permission(s). Otherwise, * false. Use with {@link AssistantApp#askForPermissions|askForPermissions}. + * * @example * const app = new ActionsSdkApp({request: request, response: response}); * // or @@ -349,6 +658,7 @@ declare class AssistantApp { * if (app.isPermissionGranted()) { * // Use the requested permission(s) to get the user a ride * } + * * @return {boolean} true if permissions granted. * @dialogflow * @actionssdk @@ -357,14 +667,17 @@ declare class AssistantApp { /** * Asks user for delivery address. + * * @example * // For DialogflowApp: * const app = new DialogflowApp({request, response}); * const WELCOME_INTENT = 'input.welcome'; * const DELIVERY_INTENT = 'delivery.address'; + * * function welcomeIntent (app) { * app.askForDeliveryAddress('To make sure I can deliver to you'); * } + * * function addressIntent (app) { * const postalCode = app.getDeliveryAddress().postalAddress.postalCode; * if (isInDeliveryZone(postalCode)) { @@ -373,17 +686,21 @@ declare class AssistantApp { * app.tell('I\'m sorry it looks like we can\'t deliver to you.'); * } * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(DELIVERY_INTENT, addressIntent); * app.handleRequest(actionMap); + * * // For ActionsSdkApp: * const app = new ActionsSdkApp({request, response}); * const WELCOME_INTENT = app.StandardIntents.MAIN; * const DELIVERY_INTENT = app.StandardIntents.DELIVERY_ADDRESS; + * * function welcomeIntent (app) { * app.askForDeliveryAddress('To make sure I can deliver to you'); * } + * * function addressIntent (app) { * const postalCode = app.getDeliveryAddress().postalAddress.postalCode; * if (isInDeliveryZone(postalCode)) { @@ -392,28 +709,33 @@ declare class AssistantApp { * app.tell('I\'m sorry it looks like we can\'t deliver to you.'); * } * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(DELIVERY_INTENT, addressIntent); * app.handleRequest(actionMap); + * * @param {string} reason Reason given to user for asking delivery address. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. - * @return {AskTellResponse} HTTP response. + * @return {express.Response|null} HTTP response. * @actionssdk * @dialogflow */ - askForDeliveryAddress(reason: string, dialogState?: DialogState): AskTellResponse; + askForDeliveryAddress(reason: string, dialogState?: object): express.Response | null; /** * Asks user for a confirmation. + * * @example * const app = new DialogflowApp({ request, response }); * const WELCOME_INTENT = 'input.welcome'; * const CONFIRMATION = 'confirmation'; + * * function welcomeIntent (app) { * app.askForConfirmation('Are you sure you want to do that?'); * } + * * function confirmation (app) { * if (app.getUserConfirmation()) { * app.tell('Great! I\'m glad you want to do it!'); @@ -421,32 +743,37 @@ declare class AssistantApp { * app.tell('That\'s okay. Let\'s not do it now.'); * } * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(CONFIRMATION, confirmation); * app.handleRequest(actionMap); + * * @param {string=} prompt The confirmation prompt presented to the user to * query for an affirmative or negative response. If undefined or null, * Google will use a generic yes/no prompt. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. Used in {@link ActionsSdkAssistant}. - * @return {AskTellResponse} HTTP response. + * @return {express.Response|null} HTTP response. * @actionssdk * @dialogflow */ - askForConfirmation(prompt?: string, dialogState?: DialogState): AskTellResponse; + askForConfirmation(prompt?: string, dialogState?: object): express.Response | null; /** * Asks user for a timezone-agnostic date and time. + * * @example * const app = new DialogflowApp({ request, response }); * const WELCOME_INTENT = 'input.welcome'; * const DATETIME = 'datetime'; + * * function welcomeIntent (app) { * app.askForDateTime('When do you want to come in?', * 'Which date works best for you?', * 'What time of day works best for you?'); * } + * * function datetime (app) { * app.tell({speech: 'Great see you at your appointment!', * displayText: 'Great, we will see you on ' @@ -455,10 +782,12 @@ declare class AssistantApp { * + ' at ' + app.getDateTime().time.hours * + (app.getDateTime().time.minutes || '')}); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(DATETIME, datetime); * app.handleRequest(actionMap); + * * @param {string=} initialPrompt The initial prompt used to ask for a * date and time. If undefined or null, Google will use a generic * prompt. @@ -468,30 +797,34 @@ declare class AssistantApp { * @param {string=} timePrompt The prompt used to specifically ask for the * time if not provided by user. If undefined or null, Google will use a * generic prompt. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. Used in {@link ActionsSdkAssistant}. - * @return {AskTellResponse} HTTP response. + * @return {express.Response | null} HTTP response. * @actionssdk * @dialogflow */ - askForDateTime(initialPrompt?: string, datePrompt?: string, timePrompt?: string, dialogState?: DialogState): AskTellResponse; + askForDateTime(initialPrompt?: string, datePrompt?: string, timePrompt?: string, dialogState?: object): express.Response | null; /** * Hands the user off to a web sign in flow. App sign in and OAuth credentials * are set in the {@link https://console.actions.google.com|Actions Console}. * Retrieve the access token in subsequent intents using * app.getUser().accessToken. + * * Note: Currently this API requires enabling the app for Transactions APIs. * To do this, fill out the App Info section of the Actions Console project * and check the box indicating the use of Transactions under "Privacy and * consent". + * * @example * const app = new DialogflowApp({ request, response }); * const WELCOME_INTENT = 'input.welcome'; * const SIGN_IN = 'sign.in'; + * * function welcomeIntent (app) { * app.askForSignIn(); * } + * * function signIn (app) { * if (app.getSignInStatus() === app.SignInstatus.OK) { * let accessToken = app.getUser().accessToken; @@ -500,24 +833,28 @@ declare class AssistantApp { * app.ask('I won\'t be able to save your data, but let\'s continue!'); * } * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(SIGN_IN, signIn); * app.handleRequest(actionMap); - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. Used in {@link ActionsSdkAssistant}. - * @return {AskTellResponse} HTTP response. + * @return {express.Response|null} HTTP response. * @actionssdk * @dialogflow */ - askForSignIn(dialogState?: DialogState): AskTellResponse; + askForSignIn(dialogState?: object): express.Response | null; /** * Requests the user to switch to another surface during the conversation. + * * @example * const app = new DialogflowApp({ request, response }); * const WELCOME_INTENT = 'input.welcome'; * const SHOW_IMAGE = 'show.image'; + * * function welcomeIntent (app) { * if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) { * showPicture(app); @@ -530,6 +867,7 @@ declare class AssistantApp { * app.tell('This part of the app only works on screen devices. Sorry about that'); * } * } + * * function showImage (app) { * if (!app.isNewSurface()) { * app.tell('Ok, I understand. You don't want to see pictures. Bye'); @@ -537,34 +875,38 @@ declare class AssistantApp { * showPicture(app, pictureType); * } * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(SHOW_IMAGE, showImage); * app.handleRequest(actionMap); + * * @param {string} context Context why new surface is requested; it's the TTS * prompt prefix (action phrase) we ask the user. * @param {string} notificationTitle Title of the notification appearing on * new surface device. - * @param {Array} capabilities The list of capabilities required in + * @param {Array} capabilities The list of capabilities required in * the surface. - * @param {DialogState=} dialogState JSON object the app uses to hold dialog state that + * @param {Object=} dialogState JSON object the app uses to hold dialog state that * will be circulated back by Assistant. Used in {@link ActionsSdkAssistant}. - * @return {AskTellResponse} HTTP response. + * @return {express.Response|null} HTTP response. * @dialogflow * @actionssdk */ - askForNewSurface(context: string, notificationTitle: string, capabilities: string[], dialogState?: DialogState): AskTellResponse; + askForNewSurface(context: string, notificationTitle: string, capabilities: SurfaceCapabilities[], dialogState?: object): express.Response | null; /** * Gets the {@link User} object. * The user object contains information about the user, including * a string identifier and personal information (requires requesting permissions, * see {@link AssistantApp#askForPermissions|askForPermissions}). + * * @example * const app = new DialogflowApp({request: request, response: response}); * // or * const app = new ActionsSdkApp({request: request, response: response}); * const userId = app.getUser().userId; + * * @return {User} Null if no value. * @actionssdk * @dialogflow @@ -575,14 +917,17 @@ declare class AssistantApp { * If granted permission to user's name in previous intent, returns user's * display name, family name, and given name. If name info is unavailable, * returns null. + * * @example * const app = new DialogflowApp({request: req, response: res}); * const REQUEST_PERMISSION_ACTION = 'request_permission'; * const SAY_NAME_ACTION = 'get_name'; + * * function requestPermission (app) { * const permission = app.SupportedPermissions.NAME; * app.askForPermission('To know who you are', permission); * } + * * function sayName (app) { * if (app.isPermissionGranted()) { * app.tell('Your name is ' + app.getUserName().displayName)); @@ -605,9 +950,11 @@ declare class AssistantApp { * Gets the user locale. Returned string represents the regional language * information of the user set in their Assistant settings. * For example, 'en-US' represents US English. + * * @example * const app = new DialogflowApp({request, response}); * const locale = app.getUserLocale(); + * * @return {string} User's locale, e.g. 'en-US'. Null if no locale given. * @actionssdk * @dialogflow @@ -618,6 +965,7 @@ declare class AssistantApp { * If granted permission to device's location in previous intent, returns device's * location (see {@link AssistantApp#askForPermissions|askForPermissions}). * If device info is unavailable, returns null. + * * @example * const app = new DialogflowApp({request: req, response: res}); * // or @@ -629,6 +977,7 @@ declare class AssistantApp { * if (app.isPermissionGranted()) { * sendCarTo(app.getDeviceLocation().coordinates); * } + * * @return {DeviceLocation} Null if location permission is not granted. * @actionssdk * @dialogflow @@ -648,34 +997,41 @@ declare class AssistantApp { * Get the argument value by name from the current intent. * If the argument is included in originalRequest, and is not a text argument, * the entire argument object is returned. + * * Note: If incoming request is using an API version under 2 (e.g. 'v1'), * the argument object will be in Proto2 format (snake_case, etc). + * * @example * const app = new DialogflowApp({request: request, response: response}); * const WELCOME_INTENT = 'input.welcome'; * const NUMBER_INTENT = 'input.number'; + * * function welcomeIntent (app) { * app.ask('Welcome to action snippets! Say a number.'); * } + * * function numberIntent (app) { * const number = app.getArgument(NUMBER_ARGUMENT); * app.tell('You said ' + number); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(NUMBER_INTENT, numberIntent); * app.handleRequest(actionMap); + * * @param {string} argName Name of the argument. * @return {Object} Argument value matching argName * or null if no matching argument. * @dialogflow * @actionssdk */ - getArgumentCommon(argName: string): any; + getArgumentCommon(argName: string): object; /** * Gets transactability of user. Only use after calling * askForTransactionRequirements. Null if no result given. + * * @return {string} One of Transactions.ResultType. * @dialogflow * @actionssdk @@ -684,16 +1040,18 @@ declare class AssistantApp { /** * Gets order delivery address. Only use after calling askForDeliveryAddress. - * @return {DeliveryAddress} Delivery address information. Null if user + * + * @return {Location} Delivery address information. Null if user * denies permission, or no address given. * @dialogflow * @actionssdk */ - getDeliveryAddress(): any; + getDeliveryAddress(): Location; /** * Gets transaction decision information. Only use after calling * askForTransactionDecision. + * * @return {TransactionDecision} Transaction decision data. Returns object with * userDecision only if user declines. userDecision will be one of * Transactions.ConfirmationDecision. Null if no decision given. @@ -704,15 +1062,17 @@ declare class AssistantApp { /** * Gets confirmation decision. Use after askForConfirmation. + * * @return {(boolean|null)} False if user replied with negative response. Null if no user * confirmation decision given. * @dialogflow * @actionssdk */ - getUserConfirmation(): boolean | any; + getUserConfirmation(): boolean | null; /** * Gets user provided date and time. Use after askForDateTime. + * * @return {DateTime} Date and time given by the user. Null if no user * date and time given. * @dialogflow @@ -722,6 +1082,7 @@ declare class AssistantApp { /** * Gets status of user sign in request. + * * @return {string} Result of user sign in request. One of * DialogflowApp.SignInStatus or ActionsSdkApp.SignInStatus * Null if no sign in status. @@ -732,11 +1093,14 @@ declare class AssistantApp { /** * Returns true if user device has a given surface capability. + * * @param {string} requestedCapability Must be one of {@link SurfaceCapabilities}. * @return {boolean} True if user device has the given capability. + * * @example * const app = new DialogflowApp({request: req, response: res}); * const DESCRIBE_SOMETHING = 'DESCRIBE_SOMETHING'; + * * function describe (app) { * if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) { * app.tell(richResponseWithBasicCard); @@ -747,13 +1111,15 @@ declare class AssistantApp { * const actionMap = new Map(); * actionMap.set(DESCRIBE_SOMETHING, describe); * app.handleRequest(actionMap); + * * @dialogflow * @actionssdk */ - hasSurfaceCapability(requestedCapability: string): boolean; + hasSurfaceCapability(requestedCapability: SurfaceCapabilities): boolean; /** * Gets surface capabilities of user device. + * * @return {Array} Supported surface capabilities, as defined in * AssistantApp.SurfaceCapabilities. * @dialogflow @@ -763,26 +1129,30 @@ declare class AssistantApp { /** * Returns the set of other available surfaces for the user. + * * @return {Array} Empty if no available surfaces. * @actionssdk * @dialogflow */ - getAvailableSurfaces(): (Surface)[]; + getAvailableSurfaces(): Surface[]; /** * Returns true if user has an available surface which includes all given * capabilities. Available surfaces capabilities may exist on surfaces other * than that used for an ongoing conversation. + * * @param {string|Array} capabilities Must be one of * {@link SurfaceCapabilities}. * @return {boolean} True if user has a capability available on some surface. + * * @dialogflow * @actionssdk */ - hasAvailableSurfaceCapabilities(capabilities: string | string[]): boolean; + hasAvailableSurfaceCapabilities(capabilities: SurfaceCapabilities | SurfaceCapabilities[]): boolean; /** * Returns the result of the AskForNewSurface helper. + * * @return {boolean} True if user has triggered conversation on a new device * following the NEW_SURFACE intent. * @actionssdk @@ -794,6 +1164,7 @@ declare class AssistantApp { * Returns true if the app is being tested in sandbox mode. Enable sandbox * mode in the (Actions console)[console.actions.google.com] to test * transactions. + * * @return {boolean} True if app is being used in Sandbox mode. * @dialogflow * @actionssdk @@ -805,11 +1176,14 @@ declare class AssistantApp { * user. This should be used along with the NO_INPUT intent to reprompt the * user for input in cases where the Google Assistant could not pick up any * speech. + * * @example * const app = new ActionsSdkApp({request, response}); + * * function welcome (app) { * app.ask('Welcome to your app!'); * } + * * function noInput (app) { * if (app.getRepromptCount() === 0) { * app.ask(`What was that?`); @@ -819,10 +1193,12 @@ declare class AssistantApp { * app.tell(`Okay let's try this again later.`); * } * } + * * const actionMap = new Map(); * actionMap.set(app.StandardIntents.MAIN, welcome); * actionMap.set(app.StandardIntents.NO_INPUT, noInput); * app.handleRequest(actionMap); + * * @return {number} The current reprompt count. Null if no reprompt count * available (e.g. not in the NO_INPUT intent). * @dialogflow @@ -835,11 +1211,14 @@ declare class AssistantApp { * user. This should be used along with the NO_INPUT intent to give the final * response to the user after multiple silences and should be an app.tell * which ends the conversation. + * * @example * const app = new ActionsSdkApp({request, response}); + * * function welcome (app) { * app.ask('Welcome to your app!'); * } + * * function noInput (app) { * if (app.getRepromptCount() === 0) { * app.ask(`What was that?`); @@ -849,10 +1228,12 @@ declare class AssistantApp { * app.tell(`Okay let's try this again later.`); * } * } + * * const actionMap = new Map(); * actionMap.set(app.StandardIntents.MAIN, welcome); * actionMap.set(app.StandardIntents.NO_INPUT, noInput); * app.handleRequest(actionMap); + * * @return {boolean} True if in a NO_INPUT intent and this is the final turn * of dialog. * @dialogflow @@ -860,8 +1241,13 @@ declare class AssistantApp { */ isFinalReprompt(): boolean; + // --------------------------------------------------------------------------- + // Response Builders + // --------------------------------------------------------------------------- + /** * Constructs RichResponse with chainable property setters. + * * @param {RichResponse=} richResponse RichResponse to clone. * @return {RichResponse} Constructed RichResponse. */ @@ -869,6 +1255,7 @@ declare class AssistantApp { /** * Constructs BasicCard with chainable property setters. + * * @param {string=} bodyText Body text of the card. Can be set using setTitle * instead. * @return {BasicCard} Constructed BasicCard. @@ -877,6 +1264,7 @@ declare class AssistantApp { /** * Constructs List with chainable property setters. + * * @param {string=} title A title to set for a new List. * @return {List} Constructed List. */ @@ -884,12 +1272,14 @@ declare class AssistantApp { /** * Constructs Carousel with chainable property setters. + * * @return {Carousel} Constructed Carousel. */ buildCarousel(): Carousel; /** * Constructs OptionItem with chainable property setters. + * * @param {string=} key A unique key to identify this option. This key will * be returned as an argument in the resulting actions.intent.OPTION * intent. @@ -897,10 +1287,15 @@ declare class AssistantApp { * use to identify this option instead of the option key. * @return {OptionItem} Constructed OptionItem. */ - buildOptionItem(key?: string, synonyms: string | any): OptionItem; + buildOptionItem(key?: string, synonyms?: string | string[]): OptionItem; + + // --------------------------------------------------------------------------- + // Transaction Builders + // --------------------------------------------------------------------------- /** * Constructs Order with chainable property setters. + * * @param {string} orderId Unique identifier for the order. * @return {Order} Constructed Order. */ @@ -908,6 +1303,7 @@ declare class AssistantApp { /** * Constructs Cart with chainable property setters. + * * @param {string=} cartId Unique identifier for the cart. * @return {Cart} Constructed Cart. */ @@ -917,6 +1313,7 @@ declare class AssistantApp { * Constructs LineItem with chainable property setters. * Because of a previous bug, the parameters are swapped compared to * the LineItem constructor to prevent a breaking change. + * * @param {string} name Name of the line item. * @param {string} id Unique identifier for the item. * @return {LineItem} Constructed LineItem. @@ -925,6 +1322,7 @@ declare class AssistantApp { /** * Constructs OrderUpdate with chainable property setters. + * * @param {string} orderId Unique identifier of the order. * @param {boolean} isGoogleOrderId True if the order ID is provided by * Google. False if the order ID is app provided. @@ -932,101 +1330,4 @@ declare class AssistantApp { */ buildOrderUpdate(orderId: string, isGoogleOrderId: boolean): OrderUpdate; - /** - * Find argument with requirements - * @param {Array} targets Argument to find - * @return {*} The argument - */ - findArgument_(...targets: string[]): any; - } - -/** - * User provided date/time info. - * @typedef {object} DateTime - * @property {Object} date - * @property {number} date.year - * @property {number} date.month - * @property {number} date.day - * @property {Object} time - * @property {number} time.hours - * @property {number} time.minutes - * @property {number} time.seconds - * @property {number} time.nanos - */ -declare type DateTime = { - date: any; - "date.year": number; - "date.month": number; - "date.day": number; - time: any; - "time.hours": number; - "time.minutes": number; - "time.seconds": number; - "time.nanos": number; -}; - -/** - * User's permissioned name info. - * @typedef {object} UserName - * @property {string} displayName - User's display name. - * @property {string} givenName - User's given name. - * @property {string} familyName - User's family name. - */ -declare type UserName = { - displayName: string; - givenName: string; - familyName: string; -}; - -/** - * User's permissioned device location. - * @typedef {object} DeviceLocation - * @property {Object} coordinates - {latitude, longitude}. Requested with - * SupportedPermissions.DEVICE_PRECISE_LOCATION. - * @property {string} address - Full, formatted street address. Requested with - * SupportedPermissions.DEVICE_PRECISE_LOCATION. - * @property {string} zipCode - Zip code. Requested with - * SupportedPermissions.DEVICE_COARSE_LOCATION. - * @property {string} city - Device city. Requested with - * SupportedPermissions.DEVICE_COARSE_LOCATION. - */ -declare type DeviceLocation = { - coordinates: any; - address: string; - zipCode: string; - city: string; -}; - -/** - * User object. - * @typedef {object} User - * @property {string} userId - Random string ID for Google user. - * @property {UserName} userName - User name information. Null if not - * requested with {@link AssistantApp#askForPermission|askForPermission(SupportedPermissions.NAME)}. - * @property {string} accessToken - Unique Oauth2 token. Only available with - * account linking. - */ -declare type User = { - userId: string; - userName: UserName; - accessToken: string; -}; - -/** - * Actions on Google Surface. - * @typedef {object} Surface - * @property {Array} capabilities - Capabilities of the surface. - */ -declare type Surface = { - capabilities: (Capability)[]; -}; - -/** - * Surface capability. - * @typedef {object} Capability - * @property {string} name - Name of the capability. - */ -declare type Capability = { - name: string; -}; diff --git a/types/actions-on-google/dialogflow-app.d.ts b/types/actions-on-google/dialogflow-app.d.ts index cf5eefb7c2..ac4f9e3959 100644 --- a/types/actions-on-google/dialogflow-app.d.ts +++ b/types/actions-on-google/dialogflow-app.d.ts @@ -1,27 +1,62 @@ +import * as express from 'express'; + +import { AssistantApp } from './assistant-app'; +import { Carousel, List, RichResponse, SimpleResponse } from './response-builder'; + +// --------------------------------------------------------------------------- +// Dialogflow support +// --------------------------------------------------------------------------- /** - * @typedef {object} DialogflowAppOptions JSON configuration. - * @property {TODO} request - Express HTTP request object. - * @property {TODO} response - Express HTTP response object. - * @property {TODO=} sessionStarted - Function callback when session starts. - * Only called if webhook is enabled for welcome/triggering intents, and - * called from Web Simulator or Google Home device (i.e., not Dialogflow simulator). + * Dialogflow {@link https://dialogflow.com/docs/concept-contexts|Context}. */ +declare type Context = { + /** Full name of the context. */ + name: string; + /** + * Parameters carried within this context. + * See {@link https://dialogflow.com/docs/concept-actions#section-extracting-values-from-contexts|here}. + */ + parameters: object; + /** Remaining number of intents */ + lifespan: number; +}; + declare type DialogflowAppOptions = { - request: any; - response: any; - sessionStarted: any; + /** Express HTTP request object. */ + request: express.Request; + /** Express HTTP response object. */ + response: express.Response; + /** + * Function callback when session starts. + * Only called if webhook is enabled for welcome/triggering intents, and + * called from Web Simulator or Google Home device (i.e., not Dialogflow simulator). + */ + sessionStarted?: () => any; }; /** * This is the class that handles the communication with Dialogflow's fulfillment API. */ -declare class DialogflowApp { +declare class DialogflowApp extends AssistantApp { + /** + * Constructor for DialogflowApp object. + * To be used in the Dialogflow fulfillment webhook logic. + * + * @example + * const DialogflowApp = require('actions-on-google').DialogflowApp; + * const app = new DialogflowApp({request: request, response: response, + * sessionStarted:sessionStarted}); + * + * @param {DialogflowAppOptions} options + * @dialogflow + */ constructor(options: DialogflowAppOptions); /** * @deprecated * Verifies whether the request comes from Dialogflow. + * * @param {string} key The header key specified by the developer in the * Dialogflow Fulfillment settings of the app. * @param {string} value The private value specified by the developer inside the @@ -33,6 +68,7 @@ declare class DialogflowApp { /** * Verifies whether the request comes from Dialogflow. + * * @param {string} key The header key specified by the developer in the * Dialogflow Fulfillment settings of the app. * @param {string} value The private value specified by the developer inside the @@ -47,21 +83,26 @@ declare class DialogflowApp { * {@link AssistantApp#handleRequest|handleRequest}, * the client library will automatically handle the incoming intents. * 'Intent' in the Dialogflow context translates into the current action. + * * @example * const app = new DialogflowApp({request: request, response: response}); + * * function responseHandler (app) { * const intent = app.getIntent(); * switch (intent) { * case WELCOME_INTENT: * app.ask('Welcome to action snippets! Say a number.'); * break; + * * case NUMBER_INTENT: * const number = app.getArgument(NUMBER_ARGUMENT); * app.tell('You said ' + number); * break; * } * } + * * app.handleRequest(responseHandler); + * * @return {string} Intent id or null if no value (action name). * @dialogflow */ @@ -71,29 +112,35 @@ declare class DialogflowApp { * Get the argument value by name from the current intent. If the argument * is included in originalRequest, and is not a text argument, the entire * argument object is returned. + * * Note: If incoming request is using an API version under 2 (e.g. 'v1'), * the argument object will be in Proto2 format (snake_case, etc). + * * @example * const app = new DialogflowApp({request: request, response: response}); * const WELCOME_INTENT = 'input.welcome'; * const NUMBER_INTENT = 'input.number'; + * * function welcomeIntent (app) { * app.ask('Welcome to action snippets! Say a number.'); * } + * * function numberIntent (app) { * const number = app.getArgument(NUMBER_ARGUMENT); * app.tell('You said ' + number); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(NUMBER_INTENT, numberIntent); * app.handleRequest(actionMap); + * * @param {string} argName Name of the argument. * @return {Object} Argument value matching argName * or null if no matching argument. * @dialogflow */ - getArgument(argName: string): any; + getArgument(argName: string): object; /** * Get the context argument value by name from the current intent. Context @@ -101,41 +148,49 @@ declare class DialogflowApp { * lifespan of the given context. If the context argument has an original * value, usually representing the underlying entity value, that will be given * as part of the return object. + * * @example * const app = new DialogflowApp({request: request, response: response}); * const WELCOME_INTENT = 'input.welcome'; * const NUMBER_INTENT = 'input.number'; * const OUT_CONTEXT = 'output_context'; * const NUMBER_ARG = 'myNumberArg'; + * * function welcomeIntent (app) { * const parameters = {}; * parameters[NUMBER_ARG] = '42'; * app.setContext(OUT_CONTEXT, 1, parameters); * app.ask('Welcome to action snippets! Ask me for your number.'); * } + * * function numberIntent (app) { * const number = app.getContextArgument(OUT_CONTEXT, NUMBER_ARG); * // number === { value: 42 } * app.tell('Your number is ' + number.value); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(NUMBER_INTENT, numberIntent); * app.handleRequest(actionMap); + * * @param {string} contextName Name of the context. * @param {string} argName Name of the argument. * @return {Object} Object containing value property and optional original * property matching context argument. Null if no matching argument. * @dialogflow */ - getContextArgument(contextName: string, argName: string): any; + getContextArgument(contextName: string, argName: string): object; /** * Returns the RichResponse constructed in Dialogflow response builder. + * * @example * const app = new App({request: req, response: res}); + * * function tellFact (app) { * let fact = 'Google was founded in 1998'; + * * if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) { * app.ask(app.getIncomingRichResponse().addSimpleResponse('Here\'s a ' + * 'fact for you. ' + fact + ' Which one do you want to hear about ' + @@ -145,9 +200,12 @@ declare class DialogflowApp { * 'do you want to hear about next, Google\'s history or headquarters?'); * } * } + * * const actionMap = new Map(); * actionMap.set('tell.fact', tellFact); + * * app.handleRequest(actionMap); + * * @return {RichResponse} RichResponse created in Dialogflow. If no RichResponse was * created, an empty RichResponse is returned. * @dialogflow @@ -156,8 +214,10 @@ declare class DialogflowApp { /** * Returns the List constructed in Dialogflow response builder. + * * @example * const app = new App({request: req, response: res}); + * * function pickOption (app) { * if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) { * app.askWithList('Which of these looks good?', @@ -168,9 +228,12 @@ declare class DialogflowApp { * app.ask('What would you like?'); * } * } + * * const actionMap = new Map(); * actionMap.set('pick.option', pickOption); + * * app.handleRequest(actionMap); + * * @return {List} List created in Dialogflow. If no List was created, an empty * List is returned. * @dialogflow @@ -179,8 +242,10 @@ declare class DialogflowApp { /** * Returns the Carousel constructed in Dialogflow response builder. + * * @example * const app = new App({request: req, response: res}); + * * function pickOption (app) { * if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) { * app.askWithCarousel('Which of these looks good?', @@ -191,9 +256,12 @@ declare class DialogflowApp { * app.ask('What would you like?'); * } * } + * * const actionMap = new Map(); * actionMap.set('pick.option', pickOption); + * * app.handleRequest(actionMap); + * * @return {Carousel} Carousel created in Dialogflow. If no Carousel was created, * an empty Carousel is returned. * @dialogflow @@ -202,8 +270,10 @@ declare class DialogflowApp { /** * Returns the option key user chose from options response. + * * @example * const app = new App({request: req, response: res}); + * * function pickOption (app) { * if (app.hasSurfaceCapability(app.SurfaceCapabilities.SCREEN_OUTPUT)) { * app.askWithCarousel('Which of these looks good?', @@ -214,13 +284,17 @@ declare class DialogflowApp { * app.ask('What would you like?'); * } * } + * * function optionPicked (app) { * app.ask('You picked ' + app.getSelectedOption()); * } + * * const actionMap = new Map(); * actionMap.set('pick.option', pickOption); * actionMap.set('option.picked', optionPicked); + * * app.handleRequest(actionMap); + * * @return {string} Option key of selected item. Null if no option selected or * if current intent is not OPTION intent. * @dialogflow @@ -230,39 +304,47 @@ declare class DialogflowApp { /** * Asks to collect the user's input. * {@link https://developers.google.com/actions/policies/general-policies#user_experience|The guidelines when prompting the user for a response must be followed at all times}. + * * NOTE: Due to a bug, if you specify the no-input prompts, * the mic is closed after the 3rd prompt, so you should use the 3rd prompt * for a bye message until the bug is fixed. + * * @example * const app = new DialogflowApp({request: request, response: response}); * const WELCOME_INTENT = 'input.welcome'; * const NUMBER_INTENT = 'input.number'; + * * function welcomeIntent (app) { * app.ask('Welcome to action snippets! Say a number.', * ['Say any number', 'Pick a number', 'We can stop here. See you soon.']); * } + * * function numberIntent (app) { * const number = app.getArgument(NUMBER_ARGUMENT); * app.tell('You said ' + number); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(NUMBER_INTENT, numberIntent); * app.handleRequest(actionMap); + * * @param {string|SimpleResponse|RichResponse} inputPrompt The input prompt * response. * @param {Array=} noInputs Array of re-prompts when the user does not respond (max 3). - * @return {AskTellResponse} HTTP response. + * @return {express.Response|null} HTTP response. * @dialogflow */ - ask(inputPrompt: string | SimpleResponse | RichResponse, noInputs?: string[]): AskTellResponse; + ask(inputPrompt: string | SimpleResponse | RichResponse, noInputs?: string[]): express.Response | null; /** * Asks to collect the user's input with a list. + * * @example * const app = new DialogflowApp({request, response}); * const WELCOME_INTENT = 'input.welcome'; * const OPTION_INTENT = 'option.select'; + * * function welcomeIntent (app) { * app.askWithList('Which of these looks good?', * app.buildList('List title') @@ -275,6 +357,7 @@ declare class DialogflowApp { * .setTitle('Title of Second List Item'), * ])); * } + * * function optionIntent (app) { * if (app.getSelectedOption() === SELECTION_KEY_ONE) { * app.tell('Number one is a great choice!'); @@ -282,24 +365,28 @@ declare class DialogflowApp { * app.tell('Number two is a great choice!'); * } * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(OPTION_INTENT, optionIntent); * app.handleRequest(actionMap); + * * @param {string|RichResponse|SimpleResponse} inputPrompt The input prompt * response. * @param {List} list List built with {@link AssistantApp#buildList|buildList}. - * @return {AskTellResponse} HTTP response. + * @return {express.Response|null} HTTP response. * @dialogflow */ - askWithList(inputPrompt: string | RichResponse | SimpleResponse, list: List): AskTellResponse; + askWithList(inputPrompt: string | RichResponse | SimpleResponse, list: List): express.Response | null; /** * Asks to collect the user's input with a carousel. + * * @example * const app = new DialogflowApp({request, response}); * const WELCOME_INTENT = 'input.welcome'; * const OPTION_INTENT = 'option.select'; + * * function welcomeIntent (app) { * app.askWithCarousel('Which of these looks good?', * app.buildCarousel() @@ -312,6 +399,7 @@ declare class DialogflowApp { * .setTitle('Number two'), * ])); * } + * * function optionIntent (app) { * if (app.getSelectedOption() === SELECTION_KEY_ONE) { * app.tell('Number one is a great choice!'); @@ -319,79 +407,94 @@ declare class DialogflowApp { * app.tell('Number two is a great choice!'); * } * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(OPTION_INTENT, optionIntent); * app.handleRequest(actionMap); + * * @param {string|RichResponse|SimpleResponse} inputPrompt The input prompt * response. * @param {Carousel} carousel Carousel built with * {@link AssistantApp#buildCarousel|buildCarousel}. - * @return {AskTellResponse} HTTP response. + * @return {express.Response|null} HTTP response. * @dialogflow */ - askWithCarousel(inputPrompt: string | RichResponse | SimpleResponse, carousel: Carousel): AskTellResponse; + askWithCarousel(inputPrompt: string | RichResponse | SimpleResponse, carousel: Carousel): express.Response | null; /** * Tells the Assistant to render the speech response and close the mic. + * * @example * const app = new DialogflowApp({request: request, response: response}); * const WELCOME_INTENT = 'input.welcome'; * const NUMBER_INTENT = 'input.number'; + * * function welcomeIntent (app) { * app.ask('Welcome to action snippets! Say a number.'); * } + * * function numberIntent (app) { * const number = app.getArgument(NUMBER_ARGUMENT); * app.tell('You said ' + number); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(NUMBER_INTENT, numberIntent); * app.handleRequest(actionMap); + * * @param {string|SimpleResponse|RichResponse} speechResponse Final response. * Spoken response can be SSML. - * @return {AskTellResponse} The response that is sent back to Assistant. + * @return {express.Response|null} The response that is sent back to Assistant. * @dialogflow */ - tell(speechResponse: string | SimpleResponse | RichResponse): AskTellResponse; + tell(speechResponse: string | SimpleResponse | RichResponse): express.Response | null; /** * Set a new context for the current intent. + * * @example * const app = new DialogflowApp({request: request, response: response}); * const CONTEXT_NUMBER = 'number'; * const NUMBER_ARGUMENT = 'myNumber'; + * * function welcomeIntent (app) { * app.setContext(CONTEXT_NUMBER); * app.ask('Welcome to action snippets! Say a number.'); * } + * * function numberIntent (app) { * const number = app.getArgument(NUMBER_ARGUMENT); * app.tell('You said ' + number); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(NUMBER_INTENT, numberIntent); * app.handleRequest(actionMap); + * * @param {string} name Name of the context. Dialogflow converts to lowercase. * @param {number} [lifespan=1] Context lifespan. * @param {Object=} parameters Context JSON parameters. * @return {null|undefined} Null if the context name is not defined. * @dialogflow */ - setContext(name: string, lifespan?: number, parameters?: any): any | any; + setContext(name: string, lifespan?: number, parameters?: any): null | undefined; /** * Returns the incoming contexts for this intent. + * * @example * const app = new DialogflowApp({request: request, response: response}); * const CONTEXT_NUMBER = 'number'; * const NUMBER_ARGUMENT = 'myNumber'; + * * function welcomeIntent (app) { * app.setContext(CONTEXT_NUMBER); * app.ask('Welcome to action snippets! Say a number.'); * } + * * function numberIntent (app) { * let contexts = app.getContexts(); * // contexts === [{ @@ -405,25 +508,30 @@ declare class DialogflowApp { * const number = app.getArgument(NUMBER_ARGUMENT); * app.tell('You said ' + number); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(NUMBER_INTENT, numberIntent); * app.handleRequest(actionMap); + * * @return {Context[]} Empty if no active contexts. * @dialogflow */ - getContexts(): (Context)[]; + getContexts(): Context[]; /** * Returns the incoming context by name for this intent. + * * @example * const app = new DialogflowApp({request: request, response: response}); * const CONTEXT_NUMBER = 'number'; * const NUMBER_ARGUMENT = 'myNumber'; + * * function welcomeIntent (app) { * app.setContext(CONTEXT_NUMBER); * app.ask('Welcome to action snippets! Say a number.'); * } + * * function numberIntent (app) { * let context = app.getContext(CONTEXT_NUMBER); * // context === { @@ -437,39 +545,29 @@ declare class DialogflowApp { * const number = app.getArgument(NUMBER_ARGUMENT); * app.tell('You said ' + number); * } + * * const actionMap = new Map(); * actionMap.set(WELCOME_INTENT, welcomeIntent); * actionMap.set(NUMBER_INTENT, numberIntent); * app.handleRequest(actionMap); + * * @param {string} name The name of the Context to retrieve. * @return {Object} Context value matching name * or null if no matching context. * @dialogflow */ - getContext(name: string): any; + getContext(name: string): object; /** * Gets the user's raw input query. + * * @example * const app = new DialogflowApp({request: request, response: response}); * app.tell('You said ' + app.getRawInput()); + * * @return {string} User's raw query or null if no value. * @dialogflow */ getRawInput(): string; } - -/** - * Dialogflow {@link https://dialogflow.com/docs/concept-contexts|Context}. - * @typedef {object} Context - * @property {string} name - Full name of the context. - * @property {Object} parameters - Parameters carried within this context. - * See {@link https://dialogflow.com/docs/concept-actions#section-extracting-values-from-contexts|here}. - * @property {number} lifespan - Remaining number of intents - */ -declare type Context = { - name: string; - parameters: any; - lifespan: number; -}; diff --git a/types/actions-on-google/index.d.ts b/types/actions-on-google/index.d.ts index 0e8fd831e5..971e78cc0e 100644 --- a/types/actions-on-google/index.d.ts +++ b/types/actions-on-google/index.d.ts @@ -1,6 +1,6 @@ -// Type definitions for actions-on-google 1.5 +// Type definitions for actions-on-google 1.5.1 // Project: https://github.com/actions-on-google/actions-on-google-nodejs -// Definitions by: Joel Hegg , Pilwon Huh +// Definitions by: Joel Hegg // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.4 @@ -12,7 +12,7 @@ import * as Transactions from './transactions'; import * as Responses from './response-builder'; -export { AssistantApp, AssistantAppOptions, RequestHandler, SessionStartedFunction, State } from './assistant-app'; +export { AssistantApp } from './assistant-app'; export { ActionsSdkApp, ActionsSdkAppOptions } from './actions-sdk-app'; export { DialogflowApp, DialogflowAppOptions } from './dialogflow-app'; export { Transactions }; diff --git a/types/actions-on-google/response-builder.d.ts b/types/actions-on-google/response-builder.d.ts index 772d567644..c87ff8f7ce 100644 --- a/types/actions-on-google/response-builder.d.ts +++ b/types/actions-on-google/response-builder.d.ts @@ -1,74 +1,72 @@ +/** + * A collection of response builders. + */ + +import { OrderUpdate } from './transactions'; /** * Simple Response type. - * @typedef {object} SimpleResponse - * @property {string} speech - Speech to be spoken to user. SSML allowed. - * @property {string} [displayText] - Optional text to be shown to user */ declare type SimpleResponse = { + /** Speech to be spoken to user. SSML allowed. */ speech: string; - displayText: string; + /** Optional text to be shown to user */ + displayText?: string; }; /** * Suggestions to show with response. - * @typedef {object} Suggestion - * @property {string} title - Text of the suggestion. */ declare type Suggestion = { + /** Text of the suggestion. */ title: string; }; /** * Link Out Suggestion. Used in rich response as a suggestion chip which, when * selected, links out to external URL. - * @typedef {object} LinkOutSuggestion - * @property {string} title - Text shown on the suggestion chip. - * @property {string} url - String URL to open. */ declare type LinkOutSuggestion = { + /** Text shown on the suggestion chip. */ title: string; + /** String URL to open. */ url: string; }; /** * Image type shown on visual elements. - * @typedef {object} Image - * @property {string} url - Image source URL. - * @property {string} accessibilityText - Text to replace for image for - * accessibility. - * @property {number} width - Width of the image. - * @property {number} height - Height of the image. */ declare type Image = { + /** Image source URL. */ url: string; + /** Text to replace for image for accessibility. */ accessibilityText: string; + /** Width of the image. */ width: number; + /** Height of the image. */ height: number; }; /** * Basic Card Button. Shown below basic cards. Open a URL when selected. - * @typedef {object} Button - * @property {string} title - Text shown on the button. - * @property {Object} openUrlAction - Action to take when selected. - * @property {string} openUrlAction.url - String URL to open. */ declare type Button = { + /** Text shown on the button. */ title: string; - openUrlAction: any; - "openUrlAction.url": string; + /** Action to take when selected. */ + openUrlAction: { + /** String URL to open. */ + url: string; + }; }; /** * Option info. Provides unique identifier for a given OptionItem. - * @typedef {object} OptionInfo - * @property {string} key - Unique string ID for this option. - * @property {Array} synonyms - Synonyms that can be used by the user - * to indicate this option if they do not use the key. */ declare type OptionInfo = { + /** Unique string ID for this option. */ key: string; + /** Synonyms that can be used by the user to indicate this option if they do not use the key. */ synonyms: string[]; }; @@ -76,29 +74,32 @@ declare type OptionInfo = { * Class for initializing and constructing Rich Responses with chainable interface. */ declare class RichResponse { + /** + * Constructor for RichResponse. Accepts optional RichResponse to clone. + * + * @param {RichResponse=} richResponse Optional RichResponse to clone. + */ constructor(richResponse?: RichResponse); /** * Ordered list of either SimpleResponse objects or BasicCard objects. * First item must be SimpleResponse. There can be at most one card. - * @type {Array} */ items: (SimpleResponse | BasicCard)[]; /** * Ordered list of text suggestions to display. Optional. - * @type {Array} */ - suggestions: (Suggestion)[]; + suggestions: Suggestion[]; /** * Link Out Suggestion chip for this rich response. Optional. - * @type {LinkOutSuggestion} */ - linkOutSuggestion: LinkOutSuggestion; + linkOutSuggestion?: LinkOutSuggestion; /** * Adds a SimpleResponse to list of items. + * * @param {string|SimpleResponse} simpleResponse Simple response to present to * user. If just a string, display text will not be set. * @return {RichResponse} Returns current constructed RichResponse. @@ -107,6 +108,7 @@ declare class RichResponse { /** * Adds a BasicCard to list of items. + * * @param {BasicCard} basicCard Basic card to include in response. * @return {RichResponse} Returns current constructed RichResponse. */ @@ -114,6 +116,7 @@ declare class RichResponse { /** * Adds a single suggestion or list of suggestions to list of items. + * * @param {string|Array} suggestions Either a single string suggestion * or list of suggestions to add. * @return {RichResponse} Returns current constructed RichResponse. @@ -130,6 +133,7 @@ declare class RichResponse { /** * Sets the suggestion link for this rich response. + * * @param {string} destinationName Name of the link out destination. * @param {string} suggestionUrl - String URL to open when suggestion is used. * @return {RichResponse} Returns current constructed RichResponse. @@ -139,6 +143,7 @@ declare class RichResponse { /** * Adds an order update to this response. Use after a successful transaction * decision to confirm the order. + * * @param {OrderUpdate} orderUpdate OrderUpdate object to add. * @return {RichResponse} Returns current constructed RichResponse. */ @@ -150,40 +155,41 @@ declare class RichResponse { * Class for initializing and constructing Basic Cards with chainable interface. */ declare class BasicCard { + /** + * Constructor for BasicCard. Accepts optional BasicCard to clone. + * + * @param {BasicCard=} basicCard Optional BasicCard to clone. + */ constructor(basicCard?: BasicCard); /** * Title of the card. Optional. - * @type {string} */ - title: string; + title?: string; /** * Body text to show on the card. Required, unless image is present. - * @type {string} */ formattedText: string; /** * Subtitle of the card. Optional. - * @type {string} */ - subtitle: string; + subtitle?: string; /** * Image to show on the card. Optional. - * @type {Image} */ - image: Image; + image?: Image; /** * Ordered list of buttons to show below card. Optional. - * @type {Array