Changelog
All notable changes (from [1.4.0] onwards) will be documented here.
Last updated
All notable changes (from [1.4.0] onwards) will be documented here.
Last updated
All notable changes (from [1.4.0] onwards) will be documented here.
Please note that this project adheres to Semantic Versioning. As carter-js is built around an API which is still in beta, breaking changes may be introduced indirectly in minor releases. Major releases will be reserved for breaking changes to the way in carter-js is used. IE. function names, parameter depreciations etc. Where a breaking change is made on the API side, carter-js will be updated to reflect this change. However, as carter-js exposes the API response to the user, it is possible that this response may change and will not be reflected in a major release if the only difference is in the response from the API.
I will continue to build carter-js with the intention of maintaining backwards compatibility, but this is not guaranteed. Previous versions of carter-js are always likely to be outdated as the API progresses.
carter-js now uses Carter's unstable API endpoints.
playerId parameter has been renamed to userId in all functions. This is to reflect the change in the API.
carter.personalise now takes a userId as its second argument. personalise(text: string, userId: string, speak?: boolean | undefined).
Other changes related to the api can be found in the carter docs, this changelog covers only the changes related to carter-js usage.
carter.history now consists of only interactions, ordered by default with the newst first in the array. This simplified the type and still enables easy sorting and filtering where necessary, as the timestamp is now included in the interaction object.
Wherever possible, properties have moved to being null when not present. This is both more semantically correct and allows for less errors when trying to access undefined properties.
All carter interactions now contain an error message property interaction.errorMessage, which will be populated where appropriate and possible for better debugging.
carter.registerSkill now takes a skill object as its only parameter. This object contains the skill name, action and options. See docs for details.
Interactions
Now contain:
type property, which is a string of the interaction type ie. "say", "opener" or "personalise"
isoTimestamp property, which is an ISO string of the timestamp of the interaction
characterName property, which is a string of the character name
url property, which is a string of the url the request was sent to
forcedBehaviours property, which is an array of triggered forced behaviours from carter. Not to be confused with triggeredSkills and executedSkills, which are carter-js skills created as a result of forced behaviours.
All interactions are now of the same type and structure, legacy properties have been left in the object while they are still present in the api response, but will be removed in a future release.
Default speak parameter is now false. This is to move carter-js inline with the API. If you want to use the audio url, you must now pass speak: true to the carter constructor, or when calling carter functions.
Optional speak parameter when creating a carter object. This will determine whether or not carter returns an audio URL, which is currently slowing down response times
Optional speak parameter to all interaction functions. This allows you to override the default class speak property. opener and personalise can also receive this parameter, but the audio url is not currently supported by the API for these functions, so related properties in the interaction will remain undefined.
All interactions now have a response_text property, which extracts the response text from the API response. This is to streamline getting your output, but also allows me to adapt carter-js to the API changes in the future. Using this property to extract your output is strongly recommended as it will always work, regardless of API changes.
say now has a response_audio parameter which extracts the audio URL from the API response. See response_text. opener and personalise also have this property, but it will always be undefined as the API does not currently support audio for these functions. Another minor update will be released with this functionality when available. Using this property to extract your audio is strongly recommended as it will always work, regardless of API changes.
Small type changes to accommodate the above additions.
None
None
Items marked as [Beta] are currently untested and may not work as expected.
Vastly improved error handling. Errors are handled where appropriate and useful error messages are thrown where possible.
Logging. By providing a logging object to the Carter constructor, you can now log all interactions with the API. This is useful for debugging and for monitoring. Logging will be improved in future releases.
Support for the new /opener endpoint with carter.opener(playerId).
Support for the new /personalise endpoint with carter.personalise(text).
Added new types for opener and personalise interactions. These are identical to the CarterInteraction type, but don't include forced behaviours.
[Beta] The Carter object now takes an extra property userLogger which can be used to activate debug logging. More details in the documentation.
carter.say no longer accepts a CarterPayloadOptions object as its second argument. Instead, it accepts a playerId string. carter-js will still generate a uuid if this is not provided.
Changed query property in carter to `text
Time taken property of interactions is now calculated by carter-js rather than the API. This is measured from function call to just before the interaction is returned.
interactions now contain an id property which is a uuid generated by carter-js, this is used to identify interactions when logging and in the history array.
Skill actions no longer accept metadata or entity parameters.
The carter.history array can now contain CarterInteraction objects OR CarterOpenerInteraction objects. Personalise interactions are not included as they are not considered part of the conversation.
carter.downvote() has been removed. This is because the API no longer supports downvoting.
carter.audioLink has been removed. This is because the API no longer supports audio links.
Fixes issue where skill actions which did not alter the response did not work if no value was returned.
Skill actions which alter the response must now return a CarterSkillOutput object. See documentation for details.
Skill actions which alter the response can now return a CarterSkillOutput object. See documentation for details.
Skill actions must now return a CarterSkillOutput object. See documentation for details.
Bug fixes related to carter update 0.0.18
Skills
Skills allow a carter-js object to detect CarterAPI triggers. A carter-js skill allows you to then define an action which will take in CarterAPI's response and allow you to modify it. This action can be triggered automatically or manually and allows easy replacement of text in your CarterAPI responses.
Carter.registerSkill(name, action, options) - registers a new skill and its action with your carter object
Carter.skills - An array of skills registered with your carter object
Timing functions
You can now extract response time data from your conversation history. As well as being able to pull the response time data from an individual CarterInteraction you are now able to use:
Carter.lastResponseTime() - extracts the response time from your most recent interaction.
Carter.averageResponseTime() - Calculates the average response time of interactions with your agent, can accept an optional minutes parameter
carter.say() now returns a CarterResponse object with an undefined data property if the response from Carter is not successful - if the response.ok property is not true.
Following on from the above change, it might now be possible to pass an interaction to Carter.downvote() which doesn't have any data as it was unsuccessful. Therefore, Carter.downvote() will now return false both if the request is unsuccessful and if carter-js is unable to retrieve a TID from the object provided.
Fixed spelling error in CarterData object. Was "time_takem" now "time_taken"
Breaking Changes: please note there is a small breaking change in this release related to the CarterConversationEntry type. This is the object used in the Carter.history array. As I don't believe this feature is being used yet I have elected to make this a minor release. There is also a deprecation I have chosen to include in a minor release for the same reason.
Carter.downvote() can now accept 3 types of argument. It will accept a CarterInteraction, a CarterConversationEntry (the object stored in Carter.history array), or you can simply pass it a TID.
Carter.latest() is now a utility function which will return the most recent interaction. The Carter.latest property has been deprecated.
Types
carter-js types have had a semantic overhaul, they now make more sense and their context is more clear. The heart of CarterAPI is in increasing our ability to interact with technology, hence carter-js has taken on more interaction-focussed semantics.
CarterJSResponse -> CarterInteraction: Still contains request and response data for every message you send to Carter.
CarterQueryOptions -> CarterPayloadOptions: More in line with the terminology used in CarterInteraction and more intuitive.
Breaking CarterConversationEntry: This object has been reworked to be more semantically intuitive and to avoid repeating data. Previously, it contained a CarterData object and what used to be called the CarterJSResponse object, now renamed CarterInteraction. These objects contain similar data, and since the CarterInteraction object contains all the information about an object you might need, the CarterConversationEntry now contains only the timestamp and the interaction.
CarterConversationEntry {
isoTimestamp: string
interaction: CarterInteraction
}Updated docs
Carter.latest attribute has been removed and replaced by Carter.latest(). (See above)