fix: Adds address parsing features to utils (#2571)

* done

* done

* by logger

* logger

.circleci/config.yml

@@ -36,7 +36,7 @@ jobs:
             - .npmrc
             - .nyc_output/*
             - .nycrc
-            - .yarn/releases/yarn-4.5.3.cjs
+            - .yarn/releases/*
             - .yarn/plugins/*
             - .yarnclean
             - .yarnrc.yml

packages/stentor-models/src/Request/AddressIntentRequest.ts

@@ -0,0 +1,50 @@
+/*! Copyright (c) 2025, XAPP AI */
+import { IntentRequest, RequestSlotMap, RequestSlot } from "./IntentRequest";
+
+export interface AddressIntentRequestSlotMap extends RequestSlotMap {
+  /**
+   * Fully formed address with street number, street name, quadrant, city, state, and zip code.
+   *
+   * On chat, this can sometimes be derived from the NLU's entity extraction.
+   */
+  address?: RequestSlot<string>;
+  /**
+   * City name.
+   */
+  city?: RequestSlot<string>;
+  /**
+   * State or Province.  Can be a two letter abbreviation or full name.
+   */
+  state?: RequestSlot<string>;
+  /**
+   * Zip code.
+   */
+  zip?: RequestSlot<string>;
+  /**
+   * Street name and number.
+   */
+  street?: RequestSlot<string>;
+  /**
+   * Street name.
+   */
+  street_name?: RequestSlot<string>;
+  /**
+   * Street number, only
+   */
+  street_number?: RequestSlot<string>;
+  /**
+   * Quadrant, if applicable.
+   */
+  quadrant?: RequestSlot<string>;
+}
+
+export interface AddressIntentRequest extends IntentRequest {
+  /**
+   * An intent that can parse an address query
+   */
+  intentId: string;
+  /**
+   * The slots
+   */
+  slots: AddressIntentRequestSlotMap;
+}

packages/stentor-models/src/Request/IntentRequest.ts

@@ -6,74 +6,81 @@ import { IntentRequestType } from "./Types";
 import { KnowledgeAnswer, KnowledgeBaseResult } from "./KnowledgeBase";
 import { ActiveContext } from "../Response";
 
-export type RequestSlotValues = string | number | object | DateTimeRange | DateTime | Duration | (string)[];
+export type RequestSlotValues =
+  | string
+  | number
+  | object
+  | DateTimeRange
+  | DateTime
+  | Duration
+  | string[];
 
 export interface RequestAttachment {
-    /**
-     * Url to the uploaded file
-     */
-    url: string;
-    /**
-     * Optional type if available (media type, like "image")
-     */
-    type?: string;
+  /**
+   * Url to the uploaded file
+   */
+  url: string;
+  /**
+   * Optional type if available (media type, like "image")
+   */
+  type?: string;
 }
 
 /**
  * Information for a slot coming in on the request.
  */
 export interface RequestSlot<T = RequestSlotValues> {
-    /**
-     * The name of the slot, also used as the key in the RequestSlotMap.
-     *
-     * For example, "FIRST_TEAM" or "Podcast", this is typically user defined.
-     */
-    name: string;
-    /**
-     * The slot normalized value.
-     *
-     * When leveraging synonyms, this will be the canonical value.  If not then it is
-     * the same as the rawValue.
-     *
-     * For example, "University of Virginia" or "Red Wine".
-     */
-    value?: T;
-    /**
-     * The original value provided by the NLU before normalization.
-     */
-    original?: any;
-    /**
-     * The raw spoken value.
-     *
-     * For example, "cavaliers" or "red"
-     */
-    rawValue?: string;
-    /**
-     * ID of the slot, if applicable.
-     *
-     * For example, "UVA"
-     */
-    id?: string;
-    /**
-     * Confidence on the slot match.  Range is between 0 - 1 where 1 is the highest confidence.
-     */
-    matchConfidence?: number;
-    /**
-     * If the entity resolution was successful or not.
-     *
-     * See {@link https://developer.amazon.com/docs/custom-skills/define-synonyms-and-ids-for-slot-type-values-entity-resolution.html#er-built-in-types}
-     */
-    successfulMatch?: boolean;
+  /**
+   * The name of the slot, also used as the key in the RequestSlotMap.
+   *
+   * For example, "FIRST_TEAM" or "Podcast", this is typically user defined.
+   */
+  name: string;
+  /**
+   * The slot normalized value.
+   *
+   * When leveraging synonyms, this will be the canonical value.  If not then it is
+   * the same as the rawValue.
+   *
+   * For example, "University of Virginia" or "Red Wine".
+   */
+  value?: T;
+  /**
+   * The original value provided by the NLU before normalization.
+   */
+  original?: any;
+  /**
+   * The raw spoken value.
+   *
+   * For example, "cavaliers" or "red"
+   */
+  rawValue?: string;
+  /**
+   * ID of the slot, if applicable.
+   *
+   * For example, "UVA"
+   */
+  id?: string;
+  /**
+   * Confidence on the slot match.  Range is between 0 - 1 where 1 is the highest confidence.
+   */
+  matchConfidence?: number;
+  /**
+   * If the entity resolution was successful or not.
+   *
+   * See {@link https://developer.amazon.com/docs/custom-skills/define-synonyms-and-ids-for-slot-type-values-entity-resolution.html#er-built-in-types}
+   */
+  successfulMatch?: boolean;
 }
 
 /**
  * Map of slots where the key is the name of the slot.
  */
 export interface RequestSlotMap {
-    /**
-     * Each key is the slot name and the corresponding value is the slot.
-     */
-    [slotName: string]: RequestSlot;
+  /**
+   * Each key is the slot name and the corresponding value is the slot.
+   */
+  [slotName: string]: RequestSlot | undefined;
 }
 
 /**
@@ -82,68 +89,68 @@ export interface RequestSlotMap {
  * For Alexa see {@link https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/handling-requests-sent-by-alexa#intentrequest}
  */
 export interface IntentRequest extends BaseRequest, SentimentedRequest {
-    /**
-     * The type of an intent request is always "INTENT_REQUEST"
-     */
-    type: IntentRequestType;
-    /**
-     * The ID of the matched intent.
-     * 
-     * A value of NLU_RESULT_PLACEHOLDER will send the IntentRequest through an NLU service if one is provided.
-     */
-    intentId: string;
-    /**
-     * The ID of the user's current session.
-     *
-     * A session is typically defined by the channel is on but it is typically a set
-     * of requests and responses that are linked together.
-     */
-    sessionId: string;
-    /**
-     * Slots for the intent.
-     */
-    slots?: RequestSlotMap;
-    /**
-     * Confidence level of the intent match.  On a scale from 0-1 where 1 is the highest confidence of a match.
-     * 
-     * {@link https://docs.aws.amazon.com/lex/latest/dg/confidence-scores.html}
-     * {@link https://docs.microsoft.com/en-us/azure/cognitive-services/luis/luis-concept-prediction-score}
-     * {@link https://cloud.google.com/dialogflow/es/docs/intents-matching#confidence}
-     */
-    matchConfidence?: number;
-    /**
-     * Current active contexts.
-     */
-    activeContexts?: ActiveContext[];
-    /**
-     * Is the request a barge-in, did the user interupt the assistants response.
-     */
-    isBargeIn?: boolean;
-    /**
-     * A meta, preliminary request that is more for understanding if the assistant can provide an answer or not.
-     */
-    canFulfill?: boolean;
-    /**
-     * Optional data that can be added to the request
-     */
-    data?: Data;
-    /**
-     * A unique request provided by a question answering system.
-     * 
-     * @beta
-     * @deprecated - Will be removed in next major version. Use the newer knowledgeBaseResult which has more information.
-     */
-    knowledgeAnswer?: KnowledgeAnswer;
-    /**
-     * Results returned from a knowledge base such as AWS Kendra.
-     * 
-     * @beta
-     */
-    knowledgeBaseResult?: KnowledgeBaseResult;
-    /**
-     * Uploads from the request
-     * 
-     * @beta 
-     */
-    attachments?: RequestAttachment[];
+  /**
+   * The type of an intent request is always "INTENT_REQUEST"
+   */
+  type: IntentRequestType;
+  /**
+   * The ID of the matched intent.
+   *
+   * A value of NLU_RESULT_PLACEHOLDER will send the IntentRequest through an NLU service if one is provided.
+   */
+  intentId: string;
+  /**
+   * The ID of the user's current session.
+   *
+   * A session is typically defined by the channel is on but it is typically a set
+   * of requests and responses that are linked together.
+   */
+  sessionId: string;
+  /**
+   * Slots for the intent.
+   */
+  slots?: RequestSlotMap;
+  /**
+   * Confidence level of the intent match.  On a scale from 0-1 where 1 is the highest confidence of a match.
+   *
+   * {@link https://docs.aws.amazon.com/lex/latest/dg/confidence-scores.html}
+   * {@link https://docs.microsoft.com/en-us/azure/cognitive-services/luis/luis-concept-prediction-score}
+   * {@link https://cloud.google.com/dialogflow/es/docs/intents-matching#confidence}
+   */
+  matchConfidence?: number;
+  /**
+   * Current active contexts.
+   */
+  activeContexts?: ActiveContext[];
+  /**
+   * Is the request a barge-in, did the user interupt the assistants response.
+   */
+  isBargeIn?: boolean;
+  /**
+   * A meta, preliminary request that is more for understanding if the assistant can provide an answer or not.
+   */
+  canFulfill?: boolean;
+  /**
+   * Optional data that can be added to the request
+   */
+  data?: Data;
+  /**
+   * A unique request provided by a question answering system.
+   *
+   * @beta
+   * @deprecated - Will be removed in next major version. Use the newer knowledgeBaseResult which has more information.
+   */
+  knowledgeAnswer?: KnowledgeAnswer;
+  /**
+   * Results returned from a knowledge base such as AWS Kendra.
+   *
+   * @beta
+   */
+  knowledgeBaseResult?: KnowledgeBaseResult;
+  /**
+   * Uploads from the request
+   *
+   * @beta
+   */
+  attachments?: RequestAttachment[];
 }

packages/stentor-models/src/Request/index.ts

@@ -1,4 +1,5 @@
 /*! Copyright (c) 2019, XAPPmedia */
+export * from "./AddressIntentRequest";
 export * from "./AudioPlayerRequest";
 export * from "./ChannelActionRequest";
 export * from "./InputUnknownRequest";

packages/stentor-utils/package.json

@@ -40,6 +40,7 @@
   },
   "dependencies": {
     "@types/xmldoc": "1.1.9",
+    "addresser": "1.1.20",
     "blueimp-md5": "2.19.0",
     "chrono-node": "2.7.7",
     "date-fns": "4.1.0",