feat: Add Be and tbd skill, also added Roadmap file

Skills/@be/node_modules/jibo-data-utils/lib/docs/time/DateTime.js

@@ -0,0 +1,318 @@
+/**
+ * @interface jibo.utils~ToStringOptions
+ * @description Options to be used when handling the string conversion of dates and times.
+ * @prop {boolean} [suppressVerbalOutput] If the `DateTime` should return
+ *        an empty string for [toString()]{@link jibo.utils.DateTime#toString} and [prefixOnAt()]{@link jibo.utils.DateTime#prefixOnAt}.
+ *        Allows greater control over how MIMs use the `DateTime` without the skill having to handle things
+ *        specially.
+ * @prop {boolean} [dropPeriod] If the period (AM/PM) should be dropped from the time. Has no effect if the time would not
+ *       be output.
+ * @prop {boolean} [display] `true` if the output should be display-compatible. Generally [toString()]{@link jibo.utils.DateTime#toString}
+ *       should output display friendly strings, but some options may change that. To ensure that you get a
+ *       display-compatible string, use this option.
+ * @prop {boolean} [prefixOnAt] Prefixes most days with 'On' and most times with 'at'.
+ *       Examples: "On Tuesday", "At 3:00PM", "Tomorrow", "This morning".
+ *       This replaces the use of [prefixOnAt()]{@link jibo.utils.DateTime#prefixOnAt}.
+ * @prop {boolean} [timeOnly] If only the time should be output, even if the date is not the
+ *       current date.
+ * @prop {boolean} [dateOnly] If only the date/day should be output, even if it is the current day.
+ */
+
+/**
+ * @interface jibo.utils~LocalTime
+ * @prop {number} year YYYY
+ * @prop {string} month Full month name (i.e. `January`, `February`, ...)
+ * @prop {number} monthNum 0-11
+ * @prop {string} dayOfWeek Full weekday name (i.e. `Monday`, `Tuesday`, ...)
+ * @prop {number} date 1-31
+ * @prop {number} hour 0-23
+ * @prop {number} minute 0-59
+ * @prop {number} seconds 0-59
+ * @prop {number} milliseconds 0-999
+ */
+
+/**
+ * Interface describing the serialized form of a [DateTime]{@link jibo.utils.DateTime} instance.
+ * @interface jibo.utils~DateTimeJSON
+ * @prop {'DateTime'} _type Internal type field (for serializing and de-serializing).
+ * @prop {number} utc Milliseconds elapsed since January 1st 1970 UTC, like `Date.now()`.
+ * @prop {jibo.utils~TimezoneJSON} timezone Serialized form of [timezone]{@link jibo.utils.Timezone}.
+ * @prop {number} durationDays Duration of a time period in days, referring to weeks or weekends. Mutually exclusive with other durations.
+ * @prop {number} durationHours Duration of a time period in hours, referring to morning, afternoon, evening, or night.
+ * @prop {number} durationMinutes Duration of a time period in minutes, currently not used.
+ * @prop {string} timePeriod The original time period referenced by the input - a value from the [timePeriods]{@link jibo.utils.DateTime#timePeriods} enum.
+ */
+
+/**
+ * Class for handling locations - taking NLU inputs and turning them into full locations with
+ * a latitude and longitude, and optionally an attached timezone.
+ * @class DateTime
+ * @memberof jibo.utils
+ * @param {string|Date|jibo.utils.Timezone} input Input from the NLU date/time factory.
+ * @param {Function} [input.getTime()] Required if `input` type = `Date`
+ * @param {jibo.utils.Timezone} [input.timezone] Required if `input` type = `DateTime`.
+ * @param {number} [input.durationDays] Required if `input` type = `DateTime`.
+ * @param {number} [input.durationHours] Required if `input` type = `DateTime`.
+ * @param {number} [input.durationMinutes] Required if `input` type = `DateTime`.
+ * @param {number} [input.timePeriod] Required if `input` type = `DateTime`.
+ * @param {String|jibo.utils.Timezone} nluTime Input from the NLU date/time factory
+ * @param {jibo.utils.Timezone} timezone Timezone that this date is in.
+ */
+
+    /**
+     * Duration of a time period in days, referring to weeks or weekends. Mutually exclusive
+     * with other durations.
+     * @name jibo.utils.DateTime#durationDays
+     * @type {Number}
+     * @readOnly
+     */
+
+    /**
+     * Duration of a time period in hours, referring to morning, afternoon, evening, or night.
+     * @name jibo.utils.DateTime#durationHours
+     * @type {Number}
+     * @readOnly
+     */
+
+    /**
+     * Duration of a time period in minutes, currently not used.
+     * @name jibo.utils.DateTime#durationMinutes
+     * @type {Number}
+     * @readOnly
+     */
+
+    /**
+     * The original time period referenced by the input - a value from the [timePeriods]{@link jibo.utils.DateTime#timePeriods} enum.
+     * These values affect how the `DateTime` is converted into a string.
+     * @name jibo.utils.DateTime#timePeriod
+     * @type {String}
+     * @readOnly
+     */
+
+    /**
+     * Private utc value. The public version is a setter that also clears _localTime.
+     * @name jibo.utils.DateTime#_utc
+     * @type {Number}
+     * @private
+     */
+
+    /**
+     * Private timezone value. The public version is a setter that also clears _localTime.
+     * @name jibo.utils.DateTime#_timezone
+     * @type {Timezone}
+     * @private
+     */
+
+    /**
+     * Cached LocalTime to prevent having to recreate that data as often.
+     * @name jibo.utils.DateTime#_localTime
+     * @type {Object}
+     * @private
+     */
+
+    /**
+     * Enum of the time periods.
+     * @name jibo.utils.DateTime#timePeriods
+     * @type {Object}
+     * @static
+     * @prop YEAR
+     * @prop MONTH
+     * @prop WEEK
+     * @prop WEEKEND
+     * @prop DAY
+     * @prop MORNING
+     * @prop AFTERNOON
+     * @prop EVENING
+     * @prop NIGHT
+     * @prop HOUR
+     * @prop MINUTE
+     * @prop NOW
+     */
+
+    /**
+     * @method jibo.utils.DateTime#constructor
+     * @param {String} nluDay Input from the NLU date/time factory.
+     * @param {String} nluTime Input from the NLU date/time factory.
+     * @param {jibo.utils.Timezone} timezone Timezone that this date is in.
+     */
+
+    /**
+     * @method jibo.utils.DateTime#constructor
+     * @param {Object} serializedDateTime An object from [toJSON()]{@link jibo.utils.DateTime#toJSON} to deserialize.
+     */
+
+    /**
+     * @method jibo.utils.DateTime#constructor
+     * @param {Number} epochTime Milliseconds elapsed since January 1st 1970 UTC, like `Date.now()`.
+     * @param {jibo.utils.Timezone} timezone Timezone that this date is in.
+     */
+
+    /**
+     * @method jibo.utils.DateTime#constructor
+     * @param {Date} date A standard Date object.
+     * @param {jibo.utils.Timezone} timezone Timezone that this date is in.
+     */
+
+    /**
+     * Time in UTC. If this `DateTime` represents a period of time, then UTC is the start of it.
+     * @name jibo.utils.DateTime#utc
+     * @type {Number}
+     */
+
+    /**
+     * The Timezone object that is the timezone that this `DateTime` exists in.
+     * @name jibo.utils.DateTime#timezone
+     * @type {jibo.utils.Timezone}
+     */
+
+    /**
+     * Makes a copy of this `DateTime`, including a copy of the Timezone
+     * @method jibo.utils.DateTime#clone
+     * @return {DateTime} The `DateTime` clone.
+     */
+
+    /**
+     * Changes this `DateTime` to the next section of the day - morning, afternoon, evening, night.
+     * @method jibo.utils.DateTime#jumpToNextDayPeriod
+     */
+
+    /**
+     * Adds a set number of years to the `DateTime`.
+     * @method jibo.utils.DateTime#addYear
+     * @param {Number} [years=1] The number of years to add.
+     */
+
+    /**
+     * Adds a set number of days to the `DateTime` and changes it to a `DAY` time period.
+     * @method jibo.utils.DateTime#addDays
+     * @param  {Number} days The number of days to add.
+     * @param {boolean} [zeroHours=false] If `true` will set hours/minutes/seconds to `0`.
+     */
+
+    /**
+     * Adds a set number of hours to the `DateTime` and changes to an `HOUR` time period
+     * @method jibo.utils.DateTime#addHours
+     * @param  {Number} hours The number of hours to add.
+     * @param {boolean} [zeroMinutes=false] If `true` will set minutes/seconds to `0`.
+     */
+
+    /**
+     * Sets the local time, with hours being in 24 hour time (0-23).
+     * Changes to an `HOUR` time period if no minutes were provided,
+     * or `MINUTE` time period if they were.
+     * @method jibo.utils.DateTime#setTime
+     * @param  {number} hours Hour in 24 hour time to set the time to.
+     * @param  {number} [minutes=0] Minutes to set the time to.
+     * @param  {number} [seconds=0] Seconds to set the time to.
+     * @param  {number} [milliseconds=0] milliseconds to set the time to.
+     */
+
+    /**
+     * Irreversibly remove the time from this `DateTime`, turning it into just a full day.
+     * This has no effect on `DateTimes` that are already days, weekends, weeks, months, or years.
+     * @method jibo.utils.DateTime#stripTime
+     */
+
+    /**
+     * If this `DateTime` is in the past. Time periods are only in the past if the end of the period
+     * is in the past.
+     * @method jibo.utils.DateTime#isPast
+     * @return {Boolean} If the time period has ended and is thus fully in the past.
+     */
+
+    /**
+     * If this `DateTime` is in the future (by any amount).
+     * @method jibo.utils.DateTime#isFuture
+     * @return {Boolean} If the time has not come to pass yet.
+     */
+
+    /**
+     * If this `DateTime` is within the specified date range
+     * @method jibo.utils.DateTime#isInRange
+     * @param {string} startDate The start date, in the format 'M/D' or 'M-D'
+     * @param {string} endDate The end date, in the format 'M/D' or 'M-D'
+     * @return {Boolean} If the time has not come to pass yet.
+     */
+
+    /**
+     * Returns an object with separate properties for local time (in this `DateTime`'s timezone)
+     * If this `DateTime` refers to a time period, then the local time will be the start time of that
+     * time period
+     * @method jibo.utils.DateTime#getLocalTime
+     * @return {Object} The local time object.
+     */
+
+    /**
+     * Gets this date in `MMDD` format, useful for some web APIs.
+     * @method jibo.utils.DateTime#getLocalMMDD
+     * @return {String} The date.
+     */
+
+    /**
+     * Gets this date in `YYYYMMDD` format, useful for some web APIs.
+     * @method jibo.utils.DateTime#getLocalYYYYMMDD
+     * @return {String} The date.
+     */
+
+    /**
+     * Returns the number of days between this date and the current date.
+     * @method jibo.utils.DateTime#getRelativeDays
+     * @return {Number} The number of days.
+     */
+
+    /**
+     * Returns the number of hours between this date/time and the current time.
+     * @method jibo.utils.DateTime#getRelativeHours
+     * @return {Number} The number of hours.
+     */
+
+    /**
+     * Gets the local date/time (in this DateTime's timezone) as a human readable or Jibo speakable
+     * string.
+     * It is designed to output stuff like "Today", "3:00PM", "Tomorrow at 3:30PM", "Tuesday".
+     * If [ToStringOptions.suppressVerbalOutput]{@link jibo.utils~ToStringOptions} is `true`, then it returns an empty string.
+     * @method jibo.utils.DateTime#toString
+     * @param {jibo.utils~ToStringOptions} [options] Options to be used when handling the string conversion.
+     * @return {String} The verbal output.
+     */
+
+    /**
+     * @method jibo.utils.DateTime#prefixOnAt
+     * @deprecated
+     * @see jibo.utils~ToStringOptions
+     */
+
+    /**
+     * Gets the relative time in a similar style to MomentJS, but simplified for display on Jibo's
+     * screen.
+     * Currently only supports past times.
+     * @method jibo.utils.DateTime#toMoment
+     * @return {String} The relative time output.
+     */
+
+    /**
+     * Serializes the `DateTime` into a JSON object with markers to assist in deserialization.
+     * @method jibo.utils.DateTime#toJSON
+     * @return {jibo.utils~DateTimeJSON} The serialized `DateTime`.
+     */
+
+    /**
+     * Outputs an ISO formatted string. See
+     * [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
+     * @method jibo.utils.DateTime#toISOString
+     * @return {string}
+     */
+
+    /**
+     * To be called by logging methods to have a more useful output.
+     * MIMs will call this if it is in the MIM prompt data.
+     * @method jibo.utils.DateTime#toLog
+     */
+
+    /**
+     * Parses date and time data output by the NLU parser.
+     * @method jibo.utils.DateTime#_parseInput
+     * @param  {String} nluDate Date output by the NLU date factory.
+     * @param  {String} nluTime Time output by the NLU time factory.
+     * @private
+     */

Skills/@be/node_modules/jibo-data-utils/lib/docs/time/DateTimeUtils.js

@@ -0,0 +1,107 @@
+/**
+ * Utilities for date and time.
+ * @class DateTimeUtils
+ * @memberof jibo.utils
+ */
+
+    /**
+     * Zero-based array of (lower-case) month names, starting with `january`.
+     * @name jibo.utils.DateTimeUtils.MONTHS
+     * @type {String[]}
+     */
+
+    /**
+     * Zero-based array of three-letter month abbreviations, starting with `Jan`.
+     * @name jibo.utils.DateTimeUtils.MONTH_ABBREVIATIONS
+     * @type {String[]}
+     */
+
+    /**
+     * Zero-based array of (lower-case) day names, starting with `sunday`.
+     * @name jibo.utils.DateTimeUtils.DAYS_OF_WEEK
+     * @type {String[]}
+     */
+
+    /**
+     * Milliseconds per day.
+     * @name jibo.utils.DateTimeUtils.MS_PER_DAY
+     * @type {Number}
+     * @private
+     */
+
+    /**
+     * Unit of time for getting the difference between two DateTimes
+     * @typedef jibo.utils.DateTimeUtils.DiffUnit
+     * @prop Milliseconds 0
+     * @prop Seconds 1
+     * @prop Minutes 2
+     * @prop Hours 3
+     * @prop Days 4
+     * @prop Weeks 5
+     */
+
+    /**
+     * Gets a verbal/written string of an integer value. Currently this function can only handle values
+     * between `-99` and `99`.
+     * @method jibo.utils.DateTimeUtils.getVerbalNumber
+     * @param {Number} input Integer to convert.
+     * @returns {String} Spoken version of the number.
+     */
+
+    /**
+     * Gets the [ordinal form]{@link https://en.wiktionary.org/wiki/ordinal_number} of a positive integer.
+     * @method jibo.utils.DateTimeUtils.getOrdinal
+     * @param  {Number} num Integer to get the ordinal form of.
+     * @return {String} Ordinal number.
+     */
+
+    /**
+     * Gets a verbal string for Jibo to read from a time in 24-hour values.
+     * @method jibo.utils.DateTimeUtils.getVerbalTime
+     * @param {Number} hour Hour in 24-hour time.
+     * @param {Number} [minute=0] Minutes in the time.
+     * @param {Boolean} [dropPeriod=false] `true` if the period (AM/PM) should be dropped from the time.
+     * @returns {String} Verbal time, ie `three PM`.
+     */
+
+    /**
+     * Gets a string suitable for visual display of a time.
+     * @method jibo.utils.DateTimeUtils.getVisualTime
+     * @param {Number} hour The hour in 24-hour time.
+     * @param {Number|null} [minute=0] Minutes in the time. Pass null to drop minutes entirely (`3 PM`).
+     * @param {Boolean} [dropPeriod=false] `true` if the period (AM/PM) should be dropped from the time.
+     * @returns {String} Visual time, ie `3:00 PM`.
+     */
+
+    /**
+     * Converts a 24-hour HHMM time string to a verbal 12-hour time for Jibo to read.
+     * @method jibo.utils.DateTimeUtils.getVerbalTimeFrom24Hour
+     * @param {String} time 24-hour time as a string, ie `1500`.
+     * @returns {String} Verbal time, ie `three PM`.
+     */
+
+    /**
+     * Converts a 24-hour HHMM time string to 12-hour time for display.
+     * @method jibo.utils.DateTimeUtils.getVisualTimeFrom24Hour
+     * @param {String} time 24 hour time as a string, ie `1500`.
+     * @returns {String} Visual time, ie `3:00 PM`.
+     */
+
+    /**
+     * Gets the number of days between two dates, ignoring hours and minutes.
+     * @method jibo.utils.DateTimeUtils.getDaysBetweenDates
+     * @param {Date} a Earlier date.
+     * @param {Date} b Later date.
+     * @returns {Number} The number of days between the two dates.
+     */
+
+    /**
+     * Gets the amount of time between two DateTimes. Differences are not rounded. When getting
+     * the difference in days, this is not the difference in dates, but the difference in 24 hour
+     * segments.
+     * @method jibo.utils.DateTimeUtils.diffDateTimes
+     * @param {jibo.utils.DateTime} a Earlier date.
+     * @param {jibo.utils.DateTime} b Later date.
+     * @param {jibo.utils.DateTimeUtils.DiffUnit} [unit=DiffUnit.Milliseconds] Unit to get the difference in.
+     * @returns {Number} The difference between the two dates.
+     */