{"_id":"@caspingus/ssml-check-core","name":"@caspingus/ssml-check-core","dist-tags":{"latest":"0.3.9"},"versions":{"0.3.9":{"name":"@caspingus/ssml-check-core","version":"0.3.9","description":"Core library to check for valid SSML","main":"index.js","dependencies":{"@caspingus/xml-js":"^1.6.11","buffer":"^6.0.3","stream-browserify":"^3.0.0","string_decoder":"^1.3.0"},"devDependencies":{"webpack":"^5.88.2","webpack-cli":"^5.1.4"},"scripts":{"dev":"npm install && webpack watch --mode development --devtool eval-source-map","prod":"npm install && webpack --mode production"},"repository":{"type":"git","url":"git+https://github.com/michaelsharman/ssml-check-core.git"},"keywords":["ssml","alexa","google","voice","speech","amazon alexa","google assistant","vui"],"license":"MIT","bugs":{"url":"https://github.com/michaelsharman/ssml-check-core/issues"},"_id":"@caspingus/ssml-check-core@0.3.9","gitHead":"6d932a350dad819c50acb819ba284ad896a13d2a","types":"./index.d.ts","homepage":"https://github.com/michaelsharman/ssml-check-core#readme","_nodeVersion":"22.1.0","_npmVersion":"10.8.3","dist":{"integrity":"sha512-AdIWmI4cAd3OGmDFCcMlfU8BmL5Cgj1C7DM7mAh02HZmN8hMGN+4A+VBvFy3xuMd8a8jerL0na+Wx1oQWqhZsA==","shasum":"d6ba08c50338efd2cfcc920015332d7a91394248","tarball":"https://registry.npmjs.org/@caspingus/ssml-check-core/-/ssml-check-core-0.3.9.tgz","fileCount":19,"unpackedSize":101591,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQC0rhXs8ob4g8jLdGEa0FU3VuaAmwf4glEOgnW3xkfB4QIgCwyzhdCyrSrNWe3cnscuoqzn8WVqyS0KjQJ8j/VPIvg="}]},"_npmUser":{"name":"caspingus","email":"michael@learnosity.com"},"directories":{},"maintainers":[{"name":"caspingus","email":"michael@learnosity.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ssml-check-core_0.3.9_1726726340040_0.7254800328946269"},"_hasShrinkwrap":false}},"time":{"created":"2024-09-19T06:12:19.922Z","0.3.9":"2024-09-19T06:12:20.184Z","modified":"2024-09-19T06:12:20.491Z"},"maintainers":[{"name":"caspingus","email":"michael@learnosity.com"}],"description":"Core library to check for valid SSML","homepage":"https://github.com/michaelsharman/ssml-check-core#readme","keywords":["ssml","alexa","google","voice","speech","amazon alexa","google assistant","vui"],"repository":{"type":"git","url":"git+https://github.com/michaelsharman/ssml-check-core.git"},"bugs":{"url":"https://github.com/michaelsharman/ssml-check-core/issues"},"license":"MIT","readme":"# SSML-Check-Core\n\nSSML-Check-Core will verify that a given input is valid SSML\n\n# Usage\n\nThis library exposes two functions which allow you to check and optionally correct a given SSML string\n\n## Check\nThe first is `check` which verifies whether the given input is a valid SSML string on either the Amazon Alexa or Google Assistant platform (or both). This function returns a Promise with an array of errors indicating how the input fails validation, or a Promise of undefined if there are no errors.\n\n```\ncheck(ssml, options)\n```\n\nThe arguments to this function are:\n\n * ssml - The SSML to check\n * options - Options for evaluating the SSML as noted below\n \nThe options structure is composed of the following fields with the following default values:\n\n```\n{\n  platform: 'all',           // The voice platform to evaluate this SSML against.\n                             // Valid values are \"all\", \"amazon\", or \"google\".\n  locale:undefined,          // The locale you want to check against, used for certain\n                             // locale-specific attributes like amazon:emotion\n  unsupportedTags:undefined, // An array of tags that will be flagged as invalid\n                             // For example, ['prosody']\n  getPositions:false,        // If set, the index of the tag will be returned as the position\n                             // field within the error object\n}\n```\n\nThe return value is a Promise resolving to an array of errors that were encountered in processing the SSML, or `undefined` if no errors were encountered.  The format of each error object is as follows:\n\n```\n{\n  type,       // The type of error encountered (\"tag\" or a specific error)\n  tag,        // The tag that had an error (set if type is \"tag\")\n  attribute,  // The attribute that had an error (set if type is \"tag\")\n  value,      // The attribute value that was in error (set if type is \"tag\" or \"audio\")\n  position,   // The position of the start of the tag within the input string (set if getPositions is true)\n  message,    // A fully formed human readable string with details of the error. (set if error includes a message) \n}\n```\n\nThe current version of ssml-check-core will check for the following:\n\n * Valid XML format\n * All tags are valid tags for their platform with valid attributes and values\n * No more than five `audio` tags in the response\n * Note invalid & character\n\n### Example\n\n```\nconst ssmlCheck = require('ssml-check-core');\nssmlCheck.check('<speak><prosody rate=\"5%\">Hello world</prosody></speak>')\n.then((errors) => {\n  if (errors) {\n    console.log(JSON.stringify(errors));\n  } else {\n    console.log('SSML is clean');\n  }\n});\n```\nwill output `[{\"type\":\"tag\",\"tag\":\"prosody\",\"attribute\":\"rate\",\"value\":\"5%\"}]`\n\n## verifyAndFix \nThe second function is `verifyAndFix` which returns a Promise of an object containing an array of caught SSML errors (similar to check) and, if possible, corrected SSML as noted below.\n\n```\nverifyAndFix(ssml, options)\n```\n\nThe arguments to this function, including the options structure, are the same as for check.\n\nThe return value is a Promise resolving to an object with the following fields:\n\n```\n{\n  fixedSSML,  // A fixed SSML string if errors are found that can be corrected for\n              // This field will be undefined if the SSML cannot be corrected\n  errors,     // An array of errors. The format of each object in this array is as\n              // defined above for the check function. This field is undefined\n              // if there are no errors.    \n}\n```\n\nIf there are no errors, then the Promise will contain an empty object.\n\nThe current version of ssml-check-core will correct the following errors:\n\n * If more than five `audio` tags are in the response, elements after the first five are removed\n * If an invalid tag is found, the tag will be removed but the contents of the element will remain \n * If an invalid attribute is found, it will be removed (in the case of the src attribute for audio, if this is missing or invalid the element will be removed)\n * If an invalid value is found for an attribute within a valid tag, the value will be corrected as best possible. For example, adding a leading + to values that require it like prosody's pitch attribute, adjusting the value to be within an acceptable range, or substituting a default value if necessary \n\n### Examples\n\n```\nconst ssmlCheck = require('ssml-check-core');\nssmlCheck.verifyAndFix('<speak><tag>What is this?</tag><break time=\"20000ms\"/>This & that</speak>')\n.then((result) => {\n  if (result.fixedSSML) {\n    console.log(result.fixedSSML);\n  } else if (result.errors) {\n    console.log(JSON.stringify(result.errors));\n  } else {\n    console.log('SSML is clean');\n  }\n});\n```\nwill output `<speak>What is this?<break time=\"10s\"/>This &amp; that</speak>`\n\n```\nconst ssmlCheck = require('ssml-check-core');\nssmlCheck.verifyAndFix('<speak><prosody rate=\"60\">Hello world</prosody></speak>')\n.then((result) => {\n  if (result.fixedSSML) {\n    console.log(result.fixedSSML);\n  } else if (result.errors) {\n    console.log(JSON.stringify(result.errors));\n  } else {\n    console.log('SSML is clean');\n  }\n});\n```\nwill output `<speak><prosody rate=\"60%\">Hello world</prosody></speak>`\n\n# Contributions\n\nWe love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:\n\n- Reporting a bug\n- Discussing the current state of the code\n- Submitting a fix\n- Proposing new features\n\nWhen contributing to this repository, please first discuss the change you wish to make by raising an issue or sending an e-mail with to the owners of this repository.\n","readmeFilename":"README.md"}