node-alexa-smapi


A node.js client library for using the Alexa Skill Management API.

Table Of Contents

* Obtaining Essential Credentials
* Documentation
* Constructor
* Constants
* Access Tokens
* Skill Operations
* Interaction Model Operations
* Account Linking Operations
* Vendor Operations
* Skill Enablement Operations
* Skill Certification Operations
* Skill Testing Operations
* Intent Request History Operations
* Miscellaneous Functions
* Custom API calls
* Examples
* Using Promises
* Using Async/Await

Obtaining Essential Credentials

In order to obtain the refreshToken, clientId, and clientSecret, you'll need to follow the instructions below:
1. Follow these instructions to retrieve clientId and clientSecret.
2. Run ask util generate-lwa-tokens to generate a refreshToken (copy the value from refresh_token and use it to initialize refreshToken in the next step).
3. Create a file called secrets.json which should look something like:

``json
{
"refreshToken": "generated by ask util generate-lwa-tokens",
"clientId": "amzn1.application-oa2-client.myClientId",
"clientSecret": "myClientSecret"
}
`

And here is some example code to test that the credentials are valid:
`js
const mySmapiClient = require('node-alexa-smapi')();
const mySecrets = require('./secrets.json');

mySmapiClient.tokens.refresh({
refreshToken: mySecrets.refreshToken,
clientId: mySecrets.clientId,
clientSecret: mySecrets.clientSecret,
}).then(() => {
mySmapiClient.vendors.list().then(result => {
console.log(My vendor list: ${JSON.stringify(result, null, ' ')});
})
});
`

See the examples part for more examples.

Documentation

Official Documentation: https://developer.amazon.com/docs/smapi/ask-cli-intro.html#smapi-intro

All methods return a promise, which either resolves to the SMAPI data received, or rejects with an error.

$3

`javascript
// Constructor for building the SMAPI REST client.
// params should be in the form: {version: "v0, or v1 (default)", region: "NA (default), EU, or FE"}.
Object alexaSmapi(optional Object params)
`

$3

`javascript
// All possible base URLs. By default, the NA url is used.
const BASE_URLS = {
NA: 'https://api.amazonalexa.com',
EU: 'https://api.eu.amazonalexa.com',
FE: 'https://api.fe.amazonalexa.com'
};
`

$3

This module includes operation to retrieve a SMAPI compliant (Login with Amazon) access token. Immediately after instantiation invoke alexaSmapi.tokens.refresh(params) to seed the (Authorization header) access token for all future operations.
`javascript
// Constructor for building the SMAPI REST client.
// params should be in the form: {version: "v0, or v1 (default)", region: "NA (default), EU, or FE"}.
const alexaSmapi = require('node-alexa-smapi');
var smapiClient = alexaSmapi(optional Object params);
smapiClient.tokens.refresh({
refreshToken: "MY_REFRESH_TOKEN",
clientId: "MY_CLIENT_ID",
clientSecret: "MY_CLIENT_SECRET"
});
`

$3

Official Documentation: https://developer.amazon.com/docs/smapi/skill-operations.html

`javascript
// Fetches the skill manifest associated with the skill ID.
Object alexaSmapi.skills.getManifest(String skillId, String stage)

// Creates a new skill associated with the vendor ID.
Object alexaSmapi.skills.create(String vendorId, Object skillManifest)

// Updates a skill's manifest with the specified skill ID.
alexaSmapi.skills.update(String skillId, String stage, Object skillManifest)

// Retrieves the current statuc of the skill
Object alexaSmapi.skills.status(String skillId)

// List the skills for a specified vendorId, which is a mandatory parameter.
// The optional maxResults and nextToken values provide paging for the results.
Object alexaSmapi.skills.list(String vendorId, optional Integer maxResults, optional String nextToken)

// Deletes a skill by its skill ID.
alexaSmapi.skills.delete(String skillId)
`

$3

Official Documentation: https://developer.amazon.com/docs/smapi/interaction-model-operations.html

`javascript
// Retrieves the interaction model for a specified skill.
Object alexaSmapi.interactionModel.get(String skillId, String stage, String locale)

// Retrieves the Etag for a specified skill.
String alexaSmapi.interactionModel.getEtag(String skillId, String stage, String locale)

// Updates the interaction model for a specified skill.
Object alexaSmapi.interactionModel.update(String skillId, String stage, String locale, Object interactionModel)

// Retrieves the building status of the interaction model.
Object alexaSmapi.interactionModel.getStatus(String skillId, String stage, String locale)
`

$3

Official Documentation: https://developer.amazon.com/docs/smapi/account-linking-operations.html

`javascript
// Updates the account linking details
alexaSmapi.accountLinking.update(String skillId, String stage, Object accountLinkingRequest)

// Retrieves the account linking details
Object alexaSmapi.accountLinking.readInfo(String skillId, String stage)

// Deletes the account linking details
alexaSmapi.accountLinking.delete(String skillId, String stage)
`

$3

Official Documentation: https://developer.amazon.com/docs/smapi/vendor-operations.html

`javascript
// List all of the vendors associated with a user (access token).
Array alexaSmapi.vendors.list()
`

$3

Official Documentation: https://developer.amazon.com/docs/smapi/skill-enablement.html

`javascript
// Enables a skill stage for the requestor. The requestor should be either a developer or the owner of the skill.
// Please note that only one skill stage can be enabled for a given user at one time.
alexaSmapi.skillEnablement.enable(String skillId, String stage)

// Checks whether a skill stage is enabled or not for the requestor.
alexaSmapi.skillEnablement.status(String skillId, String stage)

// Disables a skill by deleting the skill enablement.
alexaSmapi.skillEnablement.disable(String skillId, String stage)
`

$3

Official Documentation: https://developer.amazon.com/docs/smapi/skill-certification-operations.html

`javascript
// Submit a skill for certification for potential publication.
alexaSmapi.skillCertification.submit(String skillId)

// Check status of a skill certification.
// Working for v1 only as it was implemented mainly trough trial & error as operation is not documented under https://developer.amazon.com/docs/smapi/skill-certification-operations.html
alexaSmapi.skillCertification.status(String vendorId, String skillId)

// Withdraw a skill from the certification process.
// Possible enumeration values for 'reason'
// * TEST_SKILL
// * MORE_FEATURES
// * DISCOVERED_ISSUE
// * NOT_RECEIVED_CERTIFICATION_FEEDBACK
// * NOT_INTEND_TO_PUBLISH
// * OTHER
alexaSmapi.skillCertification.withdraw(String skillId, String reason, String message)
`

$3

Official Documentation: https://developer.amazon.com/docs/smapi/skill-testing-operations.html

`javascript
// Used for directly testing a skill by passing the skill request object directly.
Object alexaSmapi.skillTesting.validate(String skillId, String stage, [String] locales)

// Used for directly testing a skill by passing the skill request object directly.
Object alexaSmapi.skillTesting.validationStatus(String skillId, String stage, String validationId)

// Used for directly testing a skill by passing the skill request object directly.
Object alexaSmapi.skillTesting.invoke(String skillId, String endpointRegion, Object skillRequest)

// Simulates a skill execution.
Object alexaSmapi.skillTesting.simulate(String skillId, String content, String locale)

// Retrieves the status of the simulated skill execution.
Object alexaSmapi.skillTesting.simulationStatus(String skillId, String requestId)
`

$3

Official Documentation: https://developer.amazon.com/docs/smapi/intent-request-history.html

`javascript
// Provides aggregated and anonymized transcriptions of user speech data and intent request details for their skills, on a per-skill basis.
// A skill must have at least 10 unique users per locale in a day, in order for data to be available for that locale for that day.
// Here is the format for params (only the skillId is required all others are optional):
// * skillId - The skillId for which utterance data is returned.
// * nextToken (default: null) - Use nextToken along with the maxResults parameter to specify how many results should be loaded in the page.
// * maxResults (default: 10) - Maximum number of result items (at-most and not at-least) that will be returned in the response.
// * sortDirection (dafault: desc) - Valid values: asc (for ascending) or desc (for descending).
// * sortField - Valid values: dialogAct.name, locale, intent.confidence.bin, stage, publicationStatus, intent.name, interactionType, or utteranceText.
// * dialogAct.name (default: null) - Valid values: Dialog.ElicitSlot, Dialog.ConfirmSlot, or Dialog.ConfirmIntent.
// * locale (default: null) - Valid values: All currently supported locales. Example: en-US. This filter can have multiple values and is not case-sensitive.
// * intent.confidence.bin (default: null) - Valid values: HIGH, MEDIUM, OR LOW. This filter can have multiple values and is not case-sensitive.
// * stage (default: null) - Valid values: live or development. This filter can have multiple values and is not case-sensitive.
// * publicationStatus (default: null) - Valid values: certification or development. This filter can have multiple values and is not case-sensitive.
// * utteranceText (default: null) - Valid values: Any string. This filter can have multiple values and is not case-sensitive.
// * intent.name (default: null) - Valid values: Any string without white spaces. This filter can have multiple values and is not case-sensitive.
// * intent.slot.name (default: null) - Valid values: Any string without white spaces. This filter can have multiple values and is not case-sensitive.
// * interactionType (default: null) - This filter can have multiple values. Valid values:
// * ONE_SHOT: The user invokes the skill and states their intent in a single phrase.
// * MODAL: The user first invokes the skill and then states their intent.
alexaSmapi.intentRequests.list(Object params)
`
Sample params:
`javascript
const params = {
skillId: 'MY_SKILL_ID',
maxResults: 10,
sortDirection: 'desc',
sortField: 'intent.confidence.bin',
locale: 'en-US',
locale: 'en-CA',
locale: 'en-GB',
locale: 'en-AU',
locale: 'en-IN',
'intent.confidence.bin': 'high',
'intent.confidence.bin': 'medium',
'intent.confidence.bin': 'low',
stage: 'live',
stage: 'development',
publicationStatus: 'certification',
publicationStatus: 'development',
utteranceText: 'api',
utteranceText: 'a pie',
utteranceText: 'ape',
'intent.name': 'testIntent',
'intent.name': 'AMAZON.HelpIntent',
interactionType: 'ONE_SHOT',
interactionType: 'MODAL'
};
`

$3


`javascript
// Refeshes the authorization token with the access token provided.
alexaSmapi.refreshToken(String accessToken)

// Sets the new base URL for future API calls.
alexaSmapi.setBaseUrl(String url)
`

$3

Due to its recent release to the public, some API methods may not be covered by this module. In that case, a bunch of custom functions are available to use. They will return the response received from making the call.

`javascript
// Perform a custom HEAD request
alexaSmapi.custom.head(String url)

// Perform a custom GET request
alexaSmapi.custom.get(String url, Object parameters)

// Perform a custom POST request
alexaSmapi.custom.post(String url, Object parameters)

// Perform a custom PUT request
alexaSmapi.custom.put(String url, Object parameters)

// Perform a custom DELETE request
alexaSmapi.custom.delete(String url)
`

Examples

Note that you'll always need to have a valid refreshToken, in which you can obtain that code below:
`js
const mySmapiClient = require('node-alexa-smapi')();
const mySecrets = require('./secrets.json');

mySmapiClient.tokens.refresh({
refreshToken: mySecrets.refreshToken,
clientId: mySecrets.clientId,
clientSecret: mySecrets.clientSecret,
}).then(() => {
// do something with the SMAPI client...
});
`

$3


`javascript
const mySmapiClient = require('node-alexa-smapi')();
const mySecrets = require('./secrets.json');

mySmapiClient.tokens.refresh({
refreshToken: mySecrets.refreshToken,
clientId: mySecrets.clientId,
clientSecret: mySecrets.clientSecret,
})
.then(() => smapiClient.skills.getManifest(skillId, 'development'))
.then(data => console.log(data))
.catch(error => console.log(error));
`

$3


`javascript
const mySmapiClient = require('node-alexa-smapi')();
const mySecrets = require('./secrets.json');

(async function() {
try {
await mySmapiClient.tokens.refresh({
refreshToken: mySecrets.refreshToken,
clientId: mySecrets.clientId,
clientSecret: mySecrets.clientSecret,
});

let manifest = await smapiClient.skills.getManifest(skillId, 'development');
console.log(manifest);
} catch (error) {
console.log(error);
}
})();
``