@metamask-previews/geolocation-controller 0.1.3-preview-0b2e3c9b4 → 0.1.3-preview-2296abeaf

package/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **BREAKING:** Resolve the user's country, region, and timezone via the `v2` geolocation endpoint through new `GeolocationController:getGeolocationData` and `GeolocationApiService:fetchGeolocationData` actions that return a `GeolocationData` object, along with matching `GeolocationControllerState` fields ([#9691](https://github.com/MetaMask/core/pull/9691))
+  - `GeolocationController` now delegates to `GeolocationApiService:fetchGeolocationData`; the location code returned by `getGeolocation`/`fetchGeolocation` preserves the legacy `v1` behavior of appending the region only for the US and Canada (e.g. `US-NY`, `CA-ON`) and returning the country alone elsewhere
 - Point `GeolocationApiService` at API Platform's `geolocation-api` service instead of the legacy Ramps-owned `on-ramp` geolocation endpoint, which is slated for deprecation ([#9417](https://github.com/MetaMask/core/pull/9417))
   - UAT temporarily resolves to the production URL since API Platform has not yet provisioned a dedicated UAT deployment for this service
 - Bump `@metamask/controller-utils` from `^12.0.0` to `^12.3.0` ([#8774](https://github.com/MetaMask/core/pull/8774), [#9058](https://github.com/MetaMask/core/pull/9058), [#9083](https://github.com/MetaMask/core/pull/9083), [#9218](https://github.com/MetaMask/core/pull/9218))

package/dist/GeolocationController-method-action-types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"GeolocationController-method-action-types.cjs","sourceRoot":"","sources":["../src/GeolocationController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { GeolocationController } from './GeolocationController.js';\n\n/**\n * Returns the geolocation code. Delegates to the\n * {@link GeolocationApiService} for network fetching and caching, then\n * updates controller state with the result.\n *\n * @returns The ISO 3166-2 location code string.\n */\nexport type GeolocationControllerGetGeolocationAction = {\n  type: `GeolocationController:getGeolocation`;\n  handler: GeolocationController['getGeolocation'];\n};\n\n/**\n * Forces a fresh geolocation fetch, bypassing the service's cache.\n *\n * @returns The ISO 3166-2 location code string.\n */\nexport type GeolocationControllerRefreshGeolocationAction = {\n  type: `GeolocationController:refreshGeolocation`;\n  handler: GeolocationController['refreshGeolocation'];\n};\n\n/**\n * Union of all GeolocationController action types.\n */\nexport type GeolocationControllerMethodActions =\n  | GeolocationControllerGetGeolocationAction\n  | GeolocationControllerRefreshGeolocationAction;\n"]}
+{"version":3,"file":"GeolocationController-method-action-types.cjs","sourceRoot":"","sources":["../src/GeolocationController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { GeolocationController } from './GeolocationController.js';\n\n/**\n * Returns the geolocation code. Delegates to the\n * {@link GeolocationApiService} for network fetching and caching, then\n * updates controller state with the result.\n *\n * @returns The ISO 3166-2 location code string.\n */\nexport type GeolocationControllerGetGeolocationAction = {\n  type: `GeolocationController:getGeolocation`;\n  handler: GeolocationController['getGeolocation'];\n};\n\n/**\n * Returns the country, region, and timezone for the current client.\n * Delegates to the {@link GeolocationApiService} for network fetching and\n * caching, then updates controller state with the result.\n *\n * @returns The geolocation data, where each field is `null` when it could\n * not be determined.\n */\nexport type GeolocationControllerGetGeolocationDataAction = {\n  type: `GeolocationController:getGeolocationData`;\n  handler: GeolocationController['getGeolocationData'];\n};\n\n/**\n * Forces a fresh geolocation fetch, bypassing the service's cache.\n *\n * @returns The ISO 3166-2 location code string.\n */\nexport type GeolocationControllerRefreshGeolocationAction = {\n  type: `GeolocationController:refreshGeolocation`;\n  handler: GeolocationController['refreshGeolocation'];\n};\n\n/**\n * Union of all GeolocationController action types.\n */\nexport type GeolocationControllerMethodActions =\n  | GeolocationControllerGetGeolocationAction\n  | GeolocationControllerGetGeolocationDataAction\n  | GeolocationControllerRefreshGeolocationAction;\n"]}

package/dist/GeolocationController-method-action-types.d.cts

@@ -14,6 +14,18 @@ export type GeolocationControllerGetGeolocationAction = {
     type: `GeolocationController:getGeolocation`;
     handler: GeolocationController['getGeolocation'];
 };
+/**
+ * Returns the country, region, and timezone for the current client.
+ * Delegates to the {@link GeolocationApiService} for network fetching and
+ * caching, then updates controller state with the result.
+ *
+ * @returns The geolocation data, where each field is `null` when it could
+ * not be determined.
+ */
+export type GeolocationControllerGetGeolocationDataAction = {
+    type: `GeolocationController:getGeolocationData`;
+    handler: GeolocationController['getGeolocationData'];
+};
 /**
  * Forces a fresh geolocation fetch, bypassing the service's cache.
  *
@@ -26,5 +38,5 @@ export type GeolocationControllerRefreshGeolocationAction = {
 /**
  * Union of all GeolocationController action types.
  */
-export type GeolocationControllerMethodActions = GeolocationControllerGetGeolocationAction | GeolocationControllerRefreshGeolocationAction;
+export type GeolocationControllerMethodActions = GeolocationControllerGetGeolocationAction | GeolocationControllerGetGeolocationDataAction | GeolocationControllerRefreshGeolocationAction;
 //# sourceMappingURL=GeolocationController-method-action-types.d.cts.map

package/dist/GeolocationController-method-action-types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"GeolocationController-method-action-types.d.cts","sourceRoot":"","sources":["../src/GeolocationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oCAAmC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,yCAAyC,GAAG;IACtD,IAAI,EAAE,sCAAsC,CAAC;IAC7C,OAAO,EAAE,qBAAqB,CAAC,gBAAgB,CAAC,CAAC;CAClD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAC1C,yCAAyC,GACzC,6CAA6C,CAAC"}
+{"version":3,"file":"GeolocationController-method-action-types.d.cts","sourceRoot":"","sources":["../src/GeolocationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oCAAmC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,yCAAyC,GAAG;IACtD,IAAI,EAAE,sCAAsC,CAAC;IAC7C,OAAO,EAAE,qBAAqB,CAAC,gBAAgB,CAAC,CAAC;CAClD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;CACtD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAC1C,yCAAyC,GACzC,6CAA6C,GAC7C,6CAA6C,CAAC"}

package/dist/GeolocationController-method-action-types.d.mts

@@ -14,6 +14,18 @@ export type GeolocationControllerGetGeolocationAction = {
     type: `GeolocationController:getGeolocation`;
     handler: GeolocationController['getGeolocation'];
 };
+/**
+ * Returns the country, region, and timezone for the current client.
+ * Delegates to the {@link GeolocationApiService} for network fetching and
+ * caching, then updates controller state with the result.
+ *
+ * @returns The geolocation data, where each field is `null` when it could
+ * not be determined.
+ */
+export type GeolocationControllerGetGeolocationDataAction = {
+    type: `GeolocationController:getGeolocationData`;
+    handler: GeolocationController['getGeolocationData'];
+};
 /**
  * Forces a fresh geolocation fetch, bypassing the service's cache.
  *
@@ -26,5 +38,5 @@ export type GeolocationControllerRefreshGeolocationAction = {
 /**
  * Union of all GeolocationController action types.
  */
-export type GeolocationControllerMethodActions = GeolocationControllerGetGeolocationAction | GeolocationControllerRefreshGeolocationAction;
+export type GeolocationControllerMethodActions = GeolocationControllerGetGeolocationAction | GeolocationControllerGetGeolocationDataAction | GeolocationControllerRefreshGeolocationAction;
 //# sourceMappingURL=GeolocationController-method-action-types.d.mts.map

package/dist/GeolocationController-method-action-types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"GeolocationController-method-action-types.d.mts","sourceRoot":"","sources":["../src/GeolocationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oCAAmC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,yCAAyC,GAAG;IACtD,IAAI,EAAE,sCAAsC,CAAC;IAC7C,OAAO,EAAE,qBAAqB,CAAC,gBAAgB,CAAC,CAAC;CAClD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAC1C,yCAAyC,GACzC,6CAA6C,CAAC"}
+{"version":3,"file":"GeolocationController-method-action-types.d.mts","sourceRoot":"","sources":["../src/GeolocationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oCAAmC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,yCAAyC,GAAG;IACtD,IAAI,EAAE,sCAAsC,CAAC;IAC7C,OAAO,EAAE,qBAAqB,CAAC,gBAAgB,CAAC,CAAC;CAClD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;CACtD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,6CAA6C,GAAG;IAC1D,IAAI,EAAE,0CAA0C,CAAC;IACjD,OAAO,EAAE,qBAAqB,CAAC,oBAAoB,CAAC,CAAC;CACtD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAC1C,yCAAyC,GACzC,6CAA6C,GAC7C,6CAA6C,CAAC"}

package/dist/GeolocationController-method-action-types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"GeolocationController-method-action-types.mjs","sourceRoot":"","sources":["../src/GeolocationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { GeolocationController } from './GeolocationController.js';\n\n/**\n * Returns the geolocation code. Delegates to the\n * {@link GeolocationApiService} for network fetching and caching, then\n * updates controller state with the result.\n *\n * @returns The ISO 3166-2 location code string.\n */\nexport type GeolocationControllerGetGeolocationAction = {\n  type: `GeolocationController:getGeolocation`;\n  handler: GeolocationController['getGeolocation'];\n};\n\n/**\n * Forces a fresh geolocation fetch, bypassing the service's cache.\n *\n * @returns The ISO 3166-2 location code string.\n */\nexport type GeolocationControllerRefreshGeolocationAction = {\n  type: `GeolocationController:refreshGeolocation`;\n  handler: GeolocationController['refreshGeolocation'];\n};\n\n/**\n * Union of all GeolocationController action types.\n */\nexport type GeolocationControllerMethodActions =\n  | GeolocationControllerGetGeolocationAction\n  | GeolocationControllerRefreshGeolocationAction;\n"]}
+{"version":3,"file":"GeolocationController-method-action-types.mjs","sourceRoot":"","sources":["../src/GeolocationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { GeolocationController } from './GeolocationController.js';\n\n/**\n * Returns the geolocation code. Delegates to the\n * {@link GeolocationApiService} for network fetching and caching, then\n * updates controller state with the result.\n *\n * @returns The ISO 3166-2 location code string.\n */\nexport type GeolocationControllerGetGeolocationAction = {\n  type: `GeolocationController:getGeolocation`;\n  handler: GeolocationController['getGeolocation'];\n};\n\n/**\n * Returns the country, region, and timezone for the current client.\n * Delegates to the {@link GeolocationApiService} for network fetching and\n * caching, then updates controller state with the result.\n *\n * @returns The geolocation data, where each field is `null` when it could\n * not be determined.\n */\nexport type GeolocationControllerGetGeolocationDataAction = {\n  type: `GeolocationController:getGeolocationData`;\n  handler: GeolocationController['getGeolocationData'];\n};\n\n/**\n * Forces a fresh geolocation fetch, bypassing the service's cache.\n *\n * @returns The ISO 3166-2 location code string.\n */\nexport type GeolocationControllerRefreshGeolocationAction = {\n  type: `GeolocationController:refreshGeolocation`;\n  handler: GeolocationController['refreshGeolocation'];\n};\n\n/**\n * Union of all GeolocationController action types.\n */\nexport type GeolocationControllerMethodActions =\n  | GeolocationControllerGetGeolocationAction\n  | GeolocationControllerGetGeolocationDataAction\n  | GeolocationControllerRefreshGeolocationAction;\n"]}

package/dist/GeolocationController.cjs

@@ -25,6 +25,24 @@ const geolocationControllerMetadata = {
         includeInStateLogs: true,
         usedInUi: true,
     },
+    country: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    region: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    timezone: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
     status: {
         persist: false,
         includeInDebugSnapshot: true,
@@ -55,6 +73,7 @@ const geolocationControllerMetadata = {
 function getDefaultGeolocationControllerState() {
     return {
         location: geolocation_api_service_js_1.UNKNOWN_LOCATION,
+        ...(0, geolocation_api_service_js_1.getUnknownGeolocationData)(),
         status: 'idle',
         lastFetchedAt: null,
         error: null,
@@ -63,6 +82,7 @@ function getDefaultGeolocationControllerState() {
 exports.getDefaultGeolocationControllerState = getDefaultGeolocationControllerState;
 const MESSENGER_EXPOSED_METHODS = [
     'getGeolocation',
+    'getGeolocationData',
     'refreshGeolocation',
 ];
 /**
@@ -103,6 +123,18 @@ class GeolocationController extends base_controller_1.BaseController {
      * @returns The ISO 3166-2 location code string.
      */
     async getGeolocation() {
+        await __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this);
+        return this.state.location;
+    }
+    /**
+     * Returns the country, region, and timezone for the current client.
+     * Delegates to the {@link GeolocationApiService} for network fetching and
+     * caching, then updates controller state with the result.
+     *
+     * @returns The geolocation data, where each field is `null` when it could
+     * not be determined.
+     */
+    async getGeolocationData() {
         return __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this);
     }
     /**
@@ -114,7 +146,8 @@ class GeolocationController extends base_controller_1.BaseController {
         this.update((draft) => {
             draft.lastFetchedAt = null;
         });
-        return __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this, { bypassCache: true });
+        await __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this, { bypassCache: true });
+        return this.state.location;
     }
 }
 exports.GeolocationController = GeolocationController;
@@ -125,7 +158,8 @@ _GeolocationController_instances = new WeakSet(), _GeolocationController_fetchAn
  *
  * @param options - Options forwarded to the service.
  * @param options.bypassCache - When true, the service skips its TTL cache.
- * @returns The ISO 3166-2 location code string.
+ * @returns The geolocation data. When the service throws, the last known
+ * geolocation is returned instead.
  */
 async function _GeolocationController_fetchAndUpdate(options) {
     this.update((draft) => {
@@ -133,14 +167,17 @@ async function _GeolocationController_fetchAndUpdate(options) {
         draft.error = null;
     });
     try {
-        const location = await this.messenger.call('GeolocationApiService:fetchGeolocation', options);
+        const geolocation = await this.messenger.call('GeolocationApiService:fetchGeolocationData', options);
         this.update((draft) => {
-            draft.location = location;
+            draft.location = (0, geolocation_api_service_js_1.toLocationCode)(geolocation);
+            draft.country = geolocation.country;
+            draft.region = geolocation.region;
+            draft.timezone = geolocation.timezone;
             draft.status = 'complete';
             draft.lastFetchedAt = Date.now();
             draft.error = null;
         });
-        return location;
+        return geolocation;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -148,7 +185,8 @@ async function _GeolocationController_fetchAndUpdate(options) {
             draft.status = 'error';
             draft.error = message;
         });
-        return this.state.location;
+        const { country, region, timezone } = this.state;
+        return { country, region, timezone };
     }
 };
 //# sourceMappingURL=GeolocationController.cjs.map

package/dist/GeolocationController.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"GeolocationController.cjs","sourceRoot":"","sources":["../src/GeolocationController.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Messenger } from '@metamask/messenger';\n\nimport type { GeolocationApiServiceFetchGeolocationAction } from './geolocation-api-service/geolocation-api-service-method-action-types.js';\nimport { UNKNOWN_LOCATION } from './geolocation-api-service/geolocation-api-service.js';\nimport type { GeolocationControllerMethodActions } from './GeolocationController-method-action-types.js';\nimport type { GeolocationRequestStatus } from './types.js';\n\n/**\n * The name of the {@link GeolocationController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'GeolocationController';\n\n/**\n * State for the {@link GeolocationController}.\n */\nexport type GeolocationControllerState = {\n  /** ISO 3166-2 location code (e.g. \"US\", \"US-NY\", \"CA-ON\"), or \"UNKNOWN\" if not yet determined. */\n  location: string;\n  /** Current status of the geolocation fetch lifecycle. */\n  status: GeolocationRequestStatus;\n  /** Epoch milliseconds of the last successful fetch, or null if never fetched. */\n  lastFetchedAt: number | null;\n  /** Last error message, or null if no error has occurred. */\n  error: string | null;\n};\n\n/**\n * The metadata for each property in {@link GeolocationControllerState}.\n */\nconst geolocationControllerMetadata = {\n  location: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  status: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  lastFetchedAt: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: false,\n  },\n  error: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: false,\n  },\n} satisfies StateMetadata<GeolocationControllerState>;\n\n/**\n * Constructs the default {@link GeolocationController} state. This allows\n * consumers to provide a partial state object when initializing the controller\n * and also helps in constructing complete state objects for this controller in\n * tests.\n *\n * @returns The default {@link GeolocationController} state.\n */\nexport function getDefaultGeolocationControllerState(): GeolocationControllerState {\n  return {\n    location: UNKNOWN_LOCATION,\n    status: 'idle',\n    lastFetchedAt: null,\n    error: null,\n  };\n}\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'getGeolocation',\n  'refreshGeolocation',\n] as const;\n\n/**\n * Retrieves the state of the {@link GeolocationController}.\n */\nexport type GeolocationControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  GeolocationControllerState\n>;\n\n/**\n * Actions that {@link GeolocationControllerMessenger} exposes to other consumers.\n */\nexport type GeolocationControllerActions =\n  | GeolocationControllerGetStateAction\n  | GeolocationControllerMethodActions;\n\n/**\n * Actions from other messengers that {@link GeolocationControllerMessenger} calls.\n */\ntype AllowedActions = GeolocationApiServiceFetchGeolocationAction;\n\n/**\n * Published when the state of {@link GeolocationController} changes.\n */\nexport type GeolocationControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  GeolocationControllerState\n>;\n\n/**\n * Events that {@link GeolocationControllerMessenger} exposes to other consumers.\n */\nexport type GeolocationControllerEvents = GeolocationControllerStateChangeEvent;\n\n/**\n * Events from other messengers that {@link GeolocationControllerMessenger}\n * subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link GeolocationController}.\n */\nexport type GeolocationControllerMessenger = Messenger<\n  typeof controllerName,\n  GeolocationControllerActions | AllowedActions,\n  GeolocationControllerEvents | AllowedEvents\n>;\n\n/**\n * Options for constructing the {@link GeolocationController}.\n */\nexport type GeolocationControllerOptions = {\n  /** The messenger for inter-controller communication. */\n  messenger: GeolocationControllerMessenger;\n  /** Optional partial initial state. */\n  state?: Partial<GeolocationControllerState>;\n};\n\n/**\n * GeolocationController manages UI-facing geolocation state by delegating\n * the actual API interaction to {@link GeolocationApiService} via the\n * messenger.\n *\n * The service (registered externally as\n * `GeolocationApiService:fetchGeolocation`) handles HTTP requests, response\n * validation, TTL caching, and promise deduplication. This controller focuses\n * on state lifecycle (`idle` -> `loading` -> `complete` | `error`) and\n * exposes `getGeolocation` / `refreshGeolocation` as messenger actions.\n */\nexport class GeolocationController extends BaseController<\n  typeof controllerName,\n  GeolocationControllerState,\n  GeolocationControllerMessenger\n> {\n  /**\n   * Constructs a new {@link GeolocationController}.\n   *\n   * @param args - The arguments to this controller.\n   * @param args.messenger - The messenger suited for this controller. Must\n   * have a `GeolocationApiService:fetchGeolocation` action handler registered.\n   * @param args.state - Optional partial initial state.\n   */\n  constructor({ messenger, state }: GeolocationControllerOptions) {\n    super({\n      messenger,\n      metadata: geolocationControllerMetadata,\n      name: controllerName,\n      state: { ...getDefaultGeolocationControllerState(), ...state },\n    });\n\n    this.messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Returns the geolocation code. Delegates to the\n   * {@link GeolocationApiService} for network fetching and caching, then\n   * updates controller state with the result.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async getGeolocation(): Promise<string> {\n    return this.#fetchAndUpdate();\n  }\n\n  /**\n   * Forces a fresh geolocation fetch, bypassing the service's cache.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async refreshGeolocation(): Promise<string> {\n    this.update((draft) => {\n      draft.lastFetchedAt = null;\n    });\n    return this.#fetchAndUpdate({ bypassCache: true });\n  }\n\n  /**\n   * Calls the geolocation service and updates controller state with the\n   * result.\n   *\n   * @param options - Options forwarded to the service.\n   * @param options.bypassCache - When true, the service skips its TTL cache.\n   * @returns The ISO 3166-2 location code string.\n   */\n  async #fetchAndUpdate(options?: { bypassCache?: boolean }): Promise<string> {\n    this.update((draft) => {\n      draft.status = 'loading';\n      draft.error = null;\n    });\n\n    try {\n      const location = await this.messenger.call(\n        'GeolocationApiService:fetchGeolocation',\n        options,\n      );\n\n      this.update((draft) => {\n        draft.location = location;\n        draft.status = 'complete';\n        draft.lastFetchedAt = Date.now();\n        draft.error = null;\n      });\n\n      return location;\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n\n      this.update((draft) => {\n        draft.status = 'error';\n        draft.error = message;\n      });\n\n      return this.state.location;\n    }\n  }\n}\n"]}
+{"version":3,"file":"GeolocationController.cjs","sourceRoot":"","sources":["../src/GeolocationController.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Messenger } from '@metamask/messenger';\n\nimport type { GeolocationApiServiceFetchGeolocationDataAction } from './geolocation-api-service/geolocation-api-service-method-action-types.js';\nimport type { GeolocationData } from './geolocation-api-service/geolocation-api-service.js';\nimport {\n  getUnknownGeolocationData,\n  toLocationCode,\n  UNKNOWN_LOCATION,\n} from './geolocation-api-service/geolocation-api-service.js';\nimport type { GeolocationControllerMethodActions } from './GeolocationController-method-action-types.js';\nimport type { GeolocationRequestStatus } from './types.js';\n\n/**\n * The name of the {@link GeolocationController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'GeolocationController';\n\n/**\n * State for the {@link GeolocationController}.\n */\nexport type GeolocationControllerState = {\n  /** ISO 3166-2 location code (e.g. \"US\", \"US-NY\", \"CA-ON\"), or \"UNKNOWN\" if not yet determined. */\n  location: string;\n  /** ISO 3166-1 alpha-2 country code (e.g. \"US\"), or null if not yet determined. */\n  country: string | null;\n  /** ISO 3166-2 subdivision code without the country prefix (e.g. \"NY\"), or null if not yet determined. */\n  region: string | null;\n  /** IANA time zone name (e.g. \"America/Los_Angeles\"), or null if not yet determined. */\n  timezone: string | null;\n  /** Current status of the geolocation fetch lifecycle. */\n  status: GeolocationRequestStatus;\n  /** Epoch milliseconds of the last successful fetch, or null if never fetched. */\n  lastFetchedAt: number | null;\n  /** Last error message, or null if no error has occurred. */\n  error: string | null;\n};\n\n/**\n * The metadata for each property in {@link GeolocationControllerState}.\n */\nconst geolocationControllerMetadata = {\n  location: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  country: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  region: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  timezone: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  status: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  lastFetchedAt: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: false,\n  },\n  error: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: false,\n  },\n} satisfies StateMetadata<GeolocationControllerState>;\n\n/**\n * Constructs the default {@link GeolocationController} state. This allows\n * consumers to provide a partial state object when initializing the controller\n * and also helps in constructing complete state objects for this controller in\n * tests.\n *\n * @returns The default {@link GeolocationController} state.\n */\nexport function getDefaultGeolocationControllerState(): GeolocationControllerState {\n  return {\n    location: UNKNOWN_LOCATION,\n    ...getUnknownGeolocationData(),\n    status: 'idle',\n    lastFetchedAt: null,\n    error: null,\n  };\n}\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'getGeolocation',\n  'getGeolocationData',\n  'refreshGeolocation',\n] as const;\n\n/**\n * Retrieves the state of the {@link GeolocationController}.\n */\nexport type GeolocationControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  GeolocationControllerState\n>;\n\n/**\n * Actions that {@link GeolocationControllerMessenger} exposes to other consumers.\n */\nexport type GeolocationControllerActions =\n  | GeolocationControllerGetStateAction\n  | GeolocationControllerMethodActions;\n\n/**\n * Actions from other messengers that {@link GeolocationControllerMessenger} calls.\n */\ntype AllowedActions = GeolocationApiServiceFetchGeolocationDataAction;\n\n/**\n * Published when the state of {@link GeolocationController} changes.\n */\nexport type GeolocationControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  GeolocationControllerState\n>;\n\n/**\n * Events that {@link GeolocationControllerMessenger} exposes to other consumers.\n */\nexport type GeolocationControllerEvents = GeolocationControllerStateChangeEvent;\n\n/**\n * Events from other messengers that {@link GeolocationControllerMessenger}\n * subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link GeolocationController}.\n */\nexport type GeolocationControllerMessenger = Messenger<\n  typeof controllerName,\n  GeolocationControllerActions | AllowedActions,\n  GeolocationControllerEvents | AllowedEvents\n>;\n\n/**\n * Options for constructing the {@link GeolocationController}.\n */\nexport type GeolocationControllerOptions = {\n  /** The messenger for inter-controller communication. */\n  messenger: GeolocationControllerMessenger;\n  /** Optional partial initial state. */\n  state?: Partial<GeolocationControllerState>;\n};\n\n/**\n * GeolocationController manages UI-facing geolocation state by delegating\n * the actual API interaction to {@link GeolocationApiService} via the\n * messenger.\n *\n * The service (registered externally as\n * `GeolocationApiService:fetchGeolocation`) handles HTTP requests, response\n * validation, TTL caching, and promise deduplication. This controller focuses\n * on state lifecycle (`idle` -> `loading` -> `complete` | `error`) and\n * exposes `getGeolocation` / `refreshGeolocation` as messenger actions.\n */\nexport class GeolocationController extends BaseController<\n  typeof controllerName,\n  GeolocationControllerState,\n  GeolocationControllerMessenger\n> {\n  /**\n   * Constructs a new {@link GeolocationController}.\n   *\n   * @param args - The arguments to this controller.\n   * @param args.messenger - The messenger suited for this controller. Must\n   * have a `GeolocationApiService:fetchGeolocation` action handler registered.\n   * @param args.state - Optional partial initial state.\n   */\n  constructor({ messenger, state }: GeolocationControllerOptions) {\n    super({\n      messenger,\n      metadata: geolocationControllerMetadata,\n      name: controllerName,\n      state: { ...getDefaultGeolocationControllerState(), ...state },\n    });\n\n    this.messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Returns the geolocation code. Delegates to the\n   * {@link GeolocationApiService} for network fetching and caching, then\n   * updates controller state with the result.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async getGeolocation(): Promise<string> {\n    await this.#fetchAndUpdate();\n    return this.state.location;\n  }\n\n  /**\n   * Returns the country, region, and timezone for the current client.\n   * Delegates to the {@link GeolocationApiService} for network fetching and\n   * caching, then updates controller state with the result.\n   *\n   * @returns The geolocation data, where each field is `null` when it could\n   * not be determined.\n   */\n  async getGeolocationData(): Promise<GeolocationData> {\n    return this.#fetchAndUpdate();\n  }\n\n  /**\n   * Forces a fresh geolocation fetch, bypassing the service's cache.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async refreshGeolocation(): Promise<string> {\n    this.update((draft) => {\n      draft.lastFetchedAt = null;\n    });\n    await this.#fetchAndUpdate({ bypassCache: true });\n    return this.state.location;\n  }\n\n  /**\n   * Calls the geolocation service and updates controller state with the\n   * result.\n   *\n   * @param options - Options forwarded to the service.\n   * @param options.bypassCache - When true, the service skips its TTL cache.\n   * @returns The geolocation data. When the service throws, the last known\n   * geolocation is returned instead.\n   */\n  async #fetchAndUpdate(options?: {\n    bypassCache?: boolean;\n  }): Promise<GeolocationData> {\n    this.update((draft) => {\n      draft.status = 'loading';\n      draft.error = null;\n    });\n\n    try {\n      const geolocation = await this.messenger.call(\n        'GeolocationApiService:fetchGeolocationData',\n        options,\n      );\n\n      this.update((draft) => {\n        draft.location = toLocationCode(geolocation);\n        draft.country = geolocation.country;\n        draft.region = geolocation.region;\n        draft.timezone = geolocation.timezone;\n        draft.status = 'complete';\n        draft.lastFetchedAt = Date.now();\n        draft.error = null;\n      });\n\n      return geolocation;\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n\n      this.update((draft) => {\n        draft.status = 'error';\n        draft.error = message;\n      });\n\n      const { country, region, timezone } = this.state;\n      return { country, region, timezone };\n    }\n  }\n}\n"]}

package/dist/GeolocationController.d.cts

@@ -1,7 +1,8 @@
 import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
 import { BaseController } from "@metamask/base-controller";
 import type { Messenger } from "@metamask/messenger";
-import type { GeolocationApiServiceFetchGeolocationAction } from "./geolocation-api-service/geolocation-api-service-method-action-types.cjs";
+import type { GeolocationApiServiceFetchGeolocationDataAction } from "./geolocation-api-service/geolocation-api-service-method-action-types.cjs";
+import type { GeolocationData } from "./geolocation-api-service/geolocation-api-service.cjs";
 import type { GeolocationControllerMethodActions } from "./GeolocationController-method-action-types.cjs";
 import type { GeolocationRequestStatus } from "./types.cjs";
 /**
@@ -16,6 +17,12 @@ export declare const controllerName = "GeolocationController";
 export type GeolocationControllerState = {
     /** ISO 3166-2 location code (e.g. "US", "US-NY", "CA-ON"), or "UNKNOWN" if not yet determined. */
     location: string;
+    /** ISO 3166-1 alpha-2 country code (e.g. "US"), or null if not yet determined. */
+    country: string | null;
+    /** ISO 3166-2 subdivision code without the country prefix (e.g. "NY"), or null if not yet determined. */
+    region: string | null;
+    /** IANA time zone name (e.g. "America/Los_Angeles"), or null if not yet determined. */
+    timezone: string | null;
     /** Current status of the geolocation fetch lifecycle. */
     status: GeolocationRequestStatus;
     /** Epoch milliseconds of the last successful fetch, or null if never fetched. */
@@ -43,7 +50,7 @@ export type GeolocationControllerActions = GeolocationControllerGetStateAction |
 /**
  * Actions from other messengers that {@link GeolocationControllerMessenger} calls.
  */
-type AllowedActions = GeolocationApiServiceFetchGeolocationAction;
+type AllowedActions = GeolocationApiServiceFetchGeolocationDataAction;
 /**
  * Published when the state of {@link GeolocationController} changes.
  */
@@ -101,6 +108,15 @@ export declare class GeolocationController extends BaseController<typeof control
      * @returns The ISO 3166-2 location code string.
      */
     getGeolocation(): Promise<string>;
+    /**
+     * Returns the country, region, and timezone for the current client.
+     * Delegates to the {@link GeolocationApiService} for network fetching and
+     * caching, then updates controller state with the result.
+     *
+     * @returns The geolocation data, where each field is `null` when it could
+     * not be determined.
+     */
+    getGeolocationData(): Promise<GeolocationData>;
     /**
      * Forces a fresh geolocation fetch, bypassing the service's cache.
      *

package/dist/GeolocationController.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"GeolocationController.d.cts","sourceRoot":"","sources":["../src/GeolocationController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,2CAA2C,EAAE,kFAAiF;AAE5I,OAAO,KAAK,EAAE,kCAAkC,EAAE,wDAAuD;AACzG,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAmB;AAE3D;;;;GAIG;AACH,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,MAAM,EAAE,wBAAwB,CAAC;IACjC,iFAAiF;IACjF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAgCF;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,IAAI,0BAA0B,CAOjF;AAOD;;GAEG;AACH,MAAM,MAAM,mCAAmC,GAAG,wBAAwB,CACxE,OAAO,cAAc,EACrB,0BAA0B,CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GACpC,mCAAmC,GACnC,kCAAkC,CAAC;AAEvC;;GAEG;AACH,KAAK,cAAc,GAAG,2CAA2C,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,qCAAqC,GAAG,0BAA0B,CAC5E,OAAO,cAAc,EACrB,0BAA0B,CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,qCAAqC,CAAC;AAEhF;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CACpD,OAAO,cAAc,EACrB,4BAA4B,GAAG,cAAc,EAC7C,2BAA2B,GAAG,aAAa,CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,wDAAwD;IACxD,SAAS,EAAE,8BAA8B,CAAC;IAC1C,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,cAAc,CACvD,OAAO,cAAc,EACrB,0BAA0B,EAC1B,8BAA8B,CAC/B;;IACC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,4BAA4B;IAc9D;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;CA8C5C"}
+{"version":3,"file":"GeolocationController.d.cts","sourceRoot":"","sources":["../src/GeolocationController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,+CAA+C,EAAE,kFAAiF;AAChJ,OAAO,KAAK,EAAE,eAAe,EAAE,8DAA6D;AAM5F,OAAO,KAAK,EAAE,kCAAkC,EAAE,wDAAuD;AACzG,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAmB;AAE3D;;;;GAIG;AACH,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yGAAyG;IACzG,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uFAAuF;IACvF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,wBAAwB,CAAC;IACjC,iFAAiF;IACjF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAkDF;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,IAAI,0BAA0B,CAQjF;AAQD;;GAEG;AACH,MAAM,MAAM,mCAAmC,GAAG,wBAAwB,CACxE,OAAO,cAAc,EACrB,0BAA0B,CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GACpC,mCAAmC,GACnC,kCAAkC,CAAC;AAEvC;;GAEG;AACH,KAAK,cAAc,GAAG,+CAA+C,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,qCAAqC,GAAG,0BAA0B,CAC5E,OAAO,cAAc,EACrB,0BAA0B,CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,qCAAqC,CAAC;AAEhF;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CACpD,OAAO,cAAc,EACrB,4BAA4B,GAAG,cAAc,EAC7C,2BAA2B,GAAG,aAAa,CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,wDAAwD;IACxD,SAAS,EAAE,8BAA8B,CAAC;IAC1C,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,cAAc,CACvD,OAAO,cAAc,EACrB,0BAA0B,EAC1B,8BAA8B,CAC/B;;IACC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,4BAA4B;IAc9D;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAKvC;;;;;;;OAOG;IACG,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAIpD;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;CAsD5C"}

package/dist/GeolocationController.d.mts

@@ -1,7 +1,8 @@
 import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
 import { BaseController } from "@metamask/base-controller";
 import type { Messenger } from "@metamask/messenger";
-import type { GeolocationApiServiceFetchGeolocationAction } from "./geolocation-api-service/geolocation-api-service-method-action-types.mjs";
+import type { GeolocationApiServiceFetchGeolocationDataAction } from "./geolocation-api-service/geolocation-api-service-method-action-types.mjs";
+import type { GeolocationData } from "./geolocation-api-service/geolocation-api-service.mjs";
 import type { GeolocationControllerMethodActions } from "./GeolocationController-method-action-types.mjs";
 import type { GeolocationRequestStatus } from "./types.mjs";
 /**
@@ -16,6 +17,12 @@ export declare const controllerName = "GeolocationController";
 export type GeolocationControllerState = {
     /** ISO 3166-2 location code (e.g. "US", "US-NY", "CA-ON"), or "UNKNOWN" if not yet determined. */
     location: string;
+    /** ISO 3166-1 alpha-2 country code (e.g. "US"), or null if not yet determined. */
+    country: string | null;
+    /** ISO 3166-2 subdivision code without the country prefix (e.g. "NY"), or null if not yet determined. */
+    region: string | null;
+    /** IANA time zone name (e.g. "America/Los_Angeles"), or null if not yet determined. */
+    timezone: string | null;
     /** Current status of the geolocation fetch lifecycle. */
     status: GeolocationRequestStatus;
     /** Epoch milliseconds of the last successful fetch, or null if never fetched. */
@@ -43,7 +50,7 @@ export type GeolocationControllerActions = GeolocationControllerGetStateAction |
 /**
  * Actions from other messengers that {@link GeolocationControllerMessenger} calls.
  */
-type AllowedActions = GeolocationApiServiceFetchGeolocationAction;
+type AllowedActions = GeolocationApiServiceFetchGeolocationDataAction;
 /**
  * Published when the state of {@link GeolocationController} changes.
  */
@@ -101,6 +108,15 @@ export declare class GeolocationController extends BaseController<typeof control
      * @returns The ISO 3166-2 location code string.
      */
     getGeolocation(): Promise<string>;
+    /**
+     * Returns the country, region, and timezone for the current client.
+     * Delegates to the {@link GeolocationApiService} for network fetching and
+     * caching, then updates controller state with the result.
+     *
+     * @returns The geolocation data, where each field is `null` when it could
+     * not be determined.
+     */
+    getGeolocationData(): Promise<GeolocationData>;
     /**
      * Forces a fresh geolocation fetch, bypassing the service's cache.
      *

package/dist/GeolocationController.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"GeolocationController.d.mts","sourceRoot":"","sources":["../src/GeolocationController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,2CAA2C,EAAE,kFAAiF;AAE5I,OAAO,KAAK,EAAE,kCAAkC,EAAE,wDAAuD;AACzG,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAmB;AAE3D;;;;GAIG;AACH,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,MAAM,EAAE,wBAAwB,CAAC;IACjC,iFAAiF;IACjF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAgCF;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,IAAI,0BAA0B,CAOjF;AAOD;;GAEG;AACH,MAAM,MAAM,mCAAmC,GAAG,wBAAwB,CACxE,OAAO,cAAc,EACrB,0BAA0B,CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GACpC,mCAAmC,GACnC,kCAAkC,CAAC;AAEvC;;GAEG;AACH,KAAK,cAAc,GAAG,2CAA2C,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,qCAAqC,GAAG,0BAA0B,CAC5E,OAAO,cAAc,EACrB,0BAA0B,CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,qCAAqC,CAAC;AAEhF;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CACpD,OAAO,cAAc,EACrB,4BAA4B,GAAG,cAAc,EAC7C,2BAA2B,GAAG,aAAa,CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,wDAAwD;IACxD,SAAS,EAAE,8BAA8B,CAAC;IAC1C,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,cAAc,CACvD,OAAO,cAAc,EACrB,0BAA0B,EAC1B,8BAA8B,CAC/B;;IACC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,4BAA4B;IAc9D;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;CA8C5C"}
+{"version":3,"file":"GeolocationController.d.mts","sourceRoot":"","sources":["../src/GeolocationController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,+CAA+C,EAAE,kFAAiF;AAChJ,OAAO,KAAK,EAAE,eAAe,EAAE,8DAA6D;AAM5F,OAAO,KAAK,EAAE,kCAAkC,EAAE,wDAAuD;AACzG,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAmB;AAE3D;;;;GAIG;AACH,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yGAAyG;IACzG,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uFAAuF;IACvF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yDAAyD;IACzD,MAAM,EAAE,wBAAwB,CAAC;IACjC,iFAAiF;IACjF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAkDF;;;;;;;GAOG;AACH,wBAAgB,oCAAoC,IAAI,0BAA0B,CAQjF;AAQD;;GAEG;AACH,MAAM,MAAM,mCAAmC,GAAG,wBAAwB,CACxE,OAAO,cAAc,EACrB,0BAA0B,CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GACpC,mCAAmC,GACnC,kCAAkC,CAAC;AAEvC;;GAEG;AACH,KAAK,cAAc,GAAG,+CAA+C,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,qCAAqC,GAAG,0BAA0B,CAC5E,OAAO,cAAc,EACrB,0BAA0B,CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,qCAAqC,CAAC;AAEhF;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CACpD,OAAO,cAAc,EACrB,4BAA4B,GAAG,cAAc,EAC7C,2BAA2B,GAAG,aAAa,CAC5C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,wDAAwD;IACxD,SAAS,EAAE,8BAA8B,CAAC;IAC1C,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,cAAc,CACvD,OAAO,cAAc,EACrB,0BAA0B,EAC1B,8BAA8B,CAC/B;;IACC;;;;;;;OAOG;gBACS,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,4BAA4B;IAc9D;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAKvC;;;;;;;OAOG;IACG,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAIpD;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;CAsD5C"}

package/dist/GeolocationController.mjs

@@ -5,7 +5,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _GeolocationController_instances, _GeolocationController_fetchAndUpdate;
 import { BaseController } from "@metamask/base-controller";
-import { UNKNOWN_LOCATION } from "./geolocation-api-service/geolocation-api-service.mjs";
+import { getUnknownGeolocationData, toLocationCode, UNKNOWN_LOCATION } from "./geolocation-api-service/geolocation-api-service.mjs";
 /**
  * The name of the {@link GeolocationController}, used to namespace the
  * controller's actions and events and to namespace the controller's state data
@@ -22,6 +22,24 @@ const geolocationControllerMetadata = {
         includeInStateLogs: true,
         usedInUi: true,
     },
+    country: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    region: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    timezone: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
     status: {
         persist: false,
         includeInDebugSnapshot: true,
@@ -52,6 +70,7 @@ const geolocationControllerMetadata = {
 export function getDefaultGeolocationControllerState() {
     return {
         location: UNKNOWN_LOCATION,
+        ...getUnknownGeolocationData(),
         status: 'idle',
         lastFetchedAt: null,
         error: null,
@@ -59,6 +78,7 @@ export function getDefaultGeolocationControllerState() {
 }
 const MESSENGER_EXPOSED_METHODS = [
     'getGeolocation',
+    'getGeolocationData',
     'refreshGeolocation',
 ];
 /**
@@ -99,6 +119,18 @@ export class GeolocationController extends BaseController {
      * @returns The ISO 3166-2 location code string.
      */
     async getGeolocation() {
+        await __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this);
+        return this.state.location;
+    }
+    /**
+     * Returns the country, region, and timezone for the current client.
+     * Delegates to the {@link GeolocationApiService} for network fetching and
+     * caching, then updates controller state with the result.
+     *
+     * @returns The geolocation data, where each field is `null` when it could
+     * not be determined.
+     */
+    async getGeolocationData() {
         return __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this);
     }
     /**
@@ -110,7 +142,8 @@ export class GeolocationController extends BaseController {
         this.update((draft) => {
             draft.lastFetchedAt = null;
         });
-        return __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this, { bypassCache: true });
+        await __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this, { bypassCache: true });
+        return this.state.location;
     }
 }
 _GeolocationController_instances = new WeakSet(), _GeolocationController_fetchAndUpdate = 
@@ -120,7 +153,8 @@ _GeolocationController_instances = new WeakSet(), _GeolocationController_fetchAn
  *
  * @param options - Options forwarded to the service.
  * @param options.bypassCache - When true, the service skips its TTL cache.
- * @returns The ISO 3166-2 location code string.
+ * @returns The geolocation data. When the service throws, the last known
+ * geolocation is returned instead.
  */
 async function _GeolocationController_fetchAndUpdate(options) {
     this.update((draft) => {
@@ -128,14 +162,17 @@ async function _GeolocationController_fetchAndUpdate(options) {
         draft.error = null;
     });
     try {
-        const location = await this.messenger.call('GeolocationApiService:fetchGeolocation', options);
+        const geolocation = await this.messenger.call('GeolocationApiService:fetchGeolocationData', options);
         this.update((draft) => {
-            draft.location = location;
+            draft.location = toLocationCode(geolocation);
+            draft.country = geolocation.country;
+            draft.region = geolocation.region;
+            draft.timezone = geolocation.timezone;
             draft.status = 'complete';
             draft.lastFetchedAt = Date.now();
             draft.error = null;
         });
-        return location;
+        return geolocation;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -143,7 +180,8 @@ async function _GeolocationController_fetchAndUpdate(options) {
             draft.status = 'error';
             draft.error = message;
         });
-        return this.state.location;
+        const { country, region, timezone } = this.state;
+        return { country, region, timezone };
     }
 };
 //# sourceMappingURL=GeolocationController.mjs.map

package/dist/GeolocationController.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"GeolocationController.mjs","sourceRoot":"","sources":["../src/GeolocationController.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Messenger } from '@metamask/messenger';\n\nimport type { GeolocationApiServiceFetchGeolocationAction } from './geolocation-api-service/geolocation-api-service-method-action-types.js';\nimport { UNKNOWN_LOCATION } from './geolocation-api-service/geolocation-api-service.js';\nimport type { GeolocationControllerMethodActions } from './GeolocationController-method-action-types.js';\nimport type { GeolocationRequestStatus } from './types.js';\n\n/**\n * The name of the {@link GeolocationController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'GeolocationController';\n\n/**\n * State for the {@link GeolocationController}.\n */\nexport type GeolocationControllerState = {\n  /** ISO 3166-2 location code (e.g. \"US\", \"US-NY\", \"CA-ON\"), or \"UNKNOWN\" if not yet determined. */\n  location: string;\n  /** Current status of the geolocation fetch lifecycle. */\n  status: GeolocationRequestStatus;\n  /** Epoch milliseconds of the last successful fetch, or null if never fetched. */\n  lastFetchedAt: number | null;\n  /** Last error message, or null if no error has occurred. */\n  error: string | null;\n};\n\n/**\n * The metadata for each property in {@link GeolocationControllerState}.\n */\nconst geolocationControllerMetadata = {\n  location: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  status: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  lastFetchedAt: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: false,\n  },\n  error: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: false,\n  },\n} satisfies StateMetadata<GeolocationControllerState>;\n\n/**\n * Constructs the default {@link GeolocationController} state. This allows\n * consumers to provide a partial state object when initializing the controller\n * and also helps in constructing complete state objects for this controller in\n * tests.\n *\n * @returns The default {@link GeolocationController} state.\n */\nexport function getDefaultGeolocationControllerState(): GeolocationControllerState {\n  return {\n    location: UNKNOWN_LOCATION,\n    status: 'idle',\n    lastFetchedAt: null,\n    error: null,\n  };\n}\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'getGeolocation',\n  'refreshGeolocation',\n] as const;\n\n/**\n * Retrieves the state of the {@link GeolocationController}.\n */\nexport type GeolocationControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  GeolocationControllerState\n>;\n\n/**\n * Actions that {@link GeolocationControllerMessenger} exposes to other consumers.\n */\nexport type GeolocationControllerActions =\n  | GeolocationControllerGetStateAction\n  | GeolocationControllerMethodActions;\n\n/**\n * Actions from other messengers that {@link GeolocationControllerMessenger} calls.\n */\ntype AllowedActions = GeolocationApiServiceFetchGeolocationAction;\n\n/**\n * Published when the state of {@link GeolocationController} changes.\n */\nexport type GeolocationControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  GeolocationControllerState\n>;\n\n/**\n * Events that {@link GeolocationControllerMessenger} exposes to other consumers.\n */\nexport type GeolocationControllerEvents = GeolocationControllerStateChangeEvent;\n\n/**\n * Events from other messengers that {@link GeolocationControllerMessenger}\n * subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link GeolocationController}.\n */\nexport type GeolocationControllerMessenger = Messenger<\n  typeof controllerName,\n  GeolocationControllerActions | AllowedActions,\n  GeolocationControllerEvents | AllowedEvents\n>;\n\n/**\n * Options for constructing the {@link GeolocationController}.\n */\nexport type GeolocationControllerOptions = {\n  /** The messenger for inter-controller communication. */\n  messenger: GeolocationControllerMessenger;\n  /** Optional partial initial state. */\n  state?: Partial<GeolocationControllerState>;\n};\n\n/**\n * GeolocationController manages UI-facing geolocation state by delegating\n * the actual API interaction to {@link GeolocationApiService} via the\n * messenger.\n *\n * The service (registered externally as\n * `GeolocationApiService:fetchGeolocation`) handles HTTP requests, response\n * validation, TTL caching, and promise deduplication. This controller focuses\n * on state lifecycle (`idle` -> `loading` -> `complete` | `error`) and\n * exposes `getGeolocation` / `refreshGeolocation` as messenger actions.\n */\nexport class GeolocationController extends BaseController<\n  typeof controllerName,\n  GeolocationControllerState,\n  GeolocationControllerMessenger\n> {\n  /**\n   * Constructs a new {@link GeolocationController}.\n   *\n   * @param args - The arguments to this controller.\n   * @param args.messenger - The messenger suited for this controller. Must\n   * have a `GeolocationApiService:fetchGeolocation` action handler registered.\n   * @param args.state - Optional partial initial state.\n   */\n  constructor({ messenger, state }: GeolocationControllerOptions) {\n    super({\n      messenger,\n      metadata: geolocationControllerMetadata,\n      name: controllerName,\n      state: { ...getDefaultGeolocationControllerState(), ...state },\n    });\n\n    this.messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Returns the geolocation code. Delegates to the\n   * {@link GeolocationApiService} for network fetching and caching, then\n   * updates controller state with the result.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async getGeolocation(): Promise<string> {\n    return this.#fetchAndUpdate();\n  }\n\n  /**\n   * Forces a fresh geolocation fetch, bypassing the service's cache.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async refreshGeolocation(): Promise<string> {\n    this.update((draft) => {\n      draft.lastFetchedAt = null;\n    });\n    return this.#fetchAndUpdate({ bypassCache: true });\n  }\n\n  /**\n   * Calls the geolocation service and updates controller state with the\n   * result.\n   *\n   * @param options - Options forwarded to the service.\n   * @param options.bypassCache - When true, the service skips its TTL cache.\n   * @returns The ISO 3166-2 location code string.\n   */\n  async #fetchAndUpdate(options?: { bypassCache?: boolean }): Promise<string> {\n    this.update((draft) => {\n      draft.status = 'loading';\n      draft.error = null;\n    });\n\n    try {\n      const location = await this.messenger.call(\n        'GeolocationApiService:fetchGeolocation',\n        options,\n      );\n\n      this.update((draft) => {\n        draft.location = location;\n        draft.status = 'complete';\n        draft.lastFetchedAt = Date.now();\n        draft.error = null;\n      });\n\n      return location;\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n\n      this.update((draft) => {\n        draft.status = 'error';\n        draft.error = message;\n      });\n\n      return this.state.location;\n    }\n  }\n}\n"]}
+{"version":3,"file":"GeolocationController.mjs","sourceRoot":"","sources":["../src/GeolocationController.ts"],"names":[],"mappings":";;;;;;AAKA,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAK3D,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EACjB,8DAA6D;AAI9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAsBtD;;GAEG;AACH,MAAM,6BAA6B,GAAG;IACpC,QAAQ,EAAE;QACR,OAAO,EAAE,KAAK;QACd,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,QAAQ,EAAE,IAAI;KACf;IACD,OAAO,EAAE;QACP,OAAO,EAAE,KAAK;QACd,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,QAAQ,EAAE,IAAI;KACf;IACD,MAAM,EAAE;QACN,OAAO,EAAE,KAAK;QACd,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,QAAQ,EAAE,IAAI;KACf;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,KAAK;QACd,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,QAAQ,EAAE,IAAI;KACf;IACD,MAAM,EAAE;QACN,OAAO,EAAE,KAAK;QACd,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,QAAQ,EAAE,IAAI;KACf;IACD,aAAa,EAAE;QACb,OAAO,EAAE,KAAK;QACd,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,QAAQ,EAAE,KAAK;KAChB;IACD,KAAK,EAAE;QACL,OAAO,EAAE,KAAK;QACd,sBAAsB,EAAE,IAAI;QAC5B,kBAAkB,EAAE,IAAI;QACxB,QAAQ,EAAE,KAAK;KAChB;CACkD,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,UAAU,oCAAoC;IAClD,OAAO;QACL,QAAQ,EAAE,gBAAgB;QAC1B,GAAG,yBAAyB,EAAE;QAC9B,MAAM,EAAE,MAAM;QACd,aAAa,EAAE,IAAI;QACnB,KAAK,EAAE,IAAI;KACZ,CAAC;AACJ,CAAC;AAED,MAAM,yBAAyB,GAAG;IAChC,gBAAgB;IAChB,oBAAoB;IACpB,oBAAoB;CACZ,CAAC;AA6DX;;;;;;;;;;GAUG;AACH,MAAM,OAAO,qBAAsB,SAAQ,cAI1C;IACC;;;;;;;OAOG;IACH,YAAY,EAAE,SAAS,EAAE,KAAK,EAAgC;QAC5D,KAAK,CAAC;YACJ,SAAS;YACT,QAAQ,EAAE,6BAA6B;YACvC,IAAI,EAAE,cAAc;YACpB,KAAK,EAAE,EAAE,GAAG,oCAAoC,EAAE,EAAE,GAAG,KAAK,EAAE;SAC/D,CAAC,CAAC;;QAEH,IAAI,CAAC,SAAS,CAAC,4BAA4B,CACzC,IAAI,EACJ,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,cAAc;QAClB,MAAM,uBAAA,IAAI,+EAAgB,MAApB,IAAI,CAAkB,CAAC;QAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,kBAAkB;QACtB,OAAO,uBAAA,IAAI,+EAAgB,MAApB,IAAI,CAAkB,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,kBAAkB;QACtB,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YACpB,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC;QAC7B,CAAC,CAAC,CAAC;QACH,MAAM,uBAAA,IAAI,+EAAgB,MAApB,IAAI,EAAiB,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;IAC7B,CAAC;CAgDF;;AA9CC;;;;;;;;GAQG;AACH,KAAK,gDAAiB,OAErB;IACC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QACpB,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;QACzB,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAC3C,4CAA4C,EAC5C,OAAO,CACR,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YACpB,KAAK,CAAC,QAAQ,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;YAC7C,KAAK,CAAC,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;YACpC,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;YAClC,KAAK,CAAC,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC;YACtC,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC;YAC1B,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACjC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,CAAC,CAAC,CAAC;QAEH,OAAO,WAAW,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAEvE,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YACpB,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC;YACvB,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;QACxB,CAAC,CAAC,CAAC;QAEH,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACjD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACvC,CAAC;AACH,CAAC","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Messenger } from '@metamask/messenger';\n\nimport type { GeolocationApiServiceFetchGeolocationDataAction } from './geolocation-api-service/geolocation-api-service-method-action-types.js';\nimport type { GeolocationData } from './geolocation-api-service/geolocation-api-service.js';\nimport {\n  getUnknownGeolocationData,\n  toLocationCode,\n  UNKNOWN_LOCATION,\n} from './geolocation-api-service/geolocation-api-service.js';\nimport type { GeolocationControllerMethodActions } from './GeolocationController-method-action-types.js';\nimport type { GeolocationRequestStatus } from './types.js';\n\n/**\n * The name of the {@link GeolocationController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'GeolocationController';\n\n/**\n * State for the {@link GeolocationController}.\n */\nexport type GeolocationControllerState = {\n  /** ISO 3166-2 location code (e.g. \"US\", \"US-NY\", \"CA-ON\"), or \"UNKNOWN\" if not yet determined. */\n  location: string;\n  /** ISO 3166-1 alpha-2 country code (e.g. \"US\"), or null if not yet determined. */\n  country: string | null;\n  /** ISO 3166-2 subdivision code without the country prefix (e.g. \"NY\"), or null if not yet determined. */\n  region: string | null;\n  /** IANA time zone name (e.g. \"America/Los_Angeles\"), or null if not yet determined. */\n  timezone: string | null;\n  /** Current status of the geolocation fetch lifecycle. */\n  status: GeolocationRequestStatus;\n  /** Epoch milliseconds of the last successful fetch, or null if never fetched. */\n  lastFetchedAt: number | null;\n  /** Last error message, or null if no error has occurred. */\n  error: string | null;\n};\n\n/**\n * The metadata for each property in {@link GeolocationControllerState}.\n */\nconst geolocationControllerMetadata = {\n  location: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  country: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  region: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  timezone: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  status: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: true,\n  },\n  lastFetchedAt: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: false,\n  },\n  error: {\n    persist: false,\n    includeInDebugSnapshot: true,\n    includeInStateLogs: true,\n    usedInUi: false,\n  },\n} satisfies StateMetadata<GeolocationControllerState>;\n\n/**\n * Constructs the default {@link GeolocationController} state. This allows\n * consumers to provide a partial state object when initializing the controller\n * and also helps in constructing complete state objects for this controller in\n * tests.\n *\n * @returns The default {@link GeolocationController} state.\n */\nexport function getDefaultGeolocationControllerState(): GeolocationControllerState {\n  return {\n    location: UNKNOWN_LOCATION,\n    ...getUnknownGeolocationData(),\n    status: 'idle',\n    lastFetchedAt: null,\n    error: null,\n  };\n}\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'getGeolocation',\n  'getGeolocationData',\n  'refreshGeolocation',\n] as const;\n\n/**\n * Retrieves the state of the {@link GeolocationController}.\n */\nexport type GeolocationControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  GeolocationControllerState\n>;\n\n/**\n * Actions that {@link GeolocationControllerMessenger} exposes to other consumers.\n */\nexport type GeolocationControllerActions =\n  | GeolocationControllerGetStateAction\n  | GeolocationControllerMethodActions;\n\n/**\n * Actions from other messengers that {@link GeolocationControllerMessenger} calls.\n */\ntype AllowedActions = GeolocationApiServiceFetchGeolocationDataAction;\n\n/**\n * Published when the state of {@link GeolocationController} changes.\n */\nexport type GeolocationControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  GeolocationControllerState\n>;\n\n/**\n * Events that {@link GeolocationControllerMessenger} exposes to other consumers.\n */\nexport type GeolocationControllerEvents = GeolocationControllerStateChangeEvent;\n\n/**\n * Events from other messengers that {@link GeolocationControllerMessenger}\n * subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link GeolocationController}.\n */\nexport type GeolocationControllerMessenger = Messenger<\n  typeof controllerName,\n  GeolocationControllerActions | AllowedActions,\n  GeolocationControllerEvents | AllowedEvents\n>;\n\n/**\n * Options for constructing the {@link GeolocationController}.\n */\nexport type GeolocationControllerOptions = {\n  /** The messenger for inter-controller communication. */\n  messenger: GeolocationControllerMessenger;\n  /** Optional partial initial state. */\n  state?: Partial<GeolocationControllerState>;\n};\n\n/**\n * GeolocationController manages UI-facing geolocation state by delegating\n * the actual API interaction to {@link GeolocationApiService} via the\n * messenger.\n *\n * The service (registered externally as\n * `GeolocationApiService:fetchGeolocation`) handles HTTP requests, response\n * validation, TTL caching, and promise deduplication. This controller focuses\n * on state lifecycle (`idle` -> `loading` -> `complete` | `error`) and\n * exposes `getGeolocation` / `refreshGeolocation` as messenger actions.\n */\nexport class GeolocationController extends BaseController<\n  typeof controllerName,\n  GeolocationControllerState,\n  GeolocationControllerMessenger\n> {\n  /**\n   * Constructs a new {@link GeolocationController}.\n   *\n   * @param args - The arguments to this controller.\n   * @param args.messenger - The messenger suited for this controller. Must\n   * have a `GeolocationApiService:fetchGeolocation` action handler registered.\n   * @param args.state - Optional partial initial state.\n   */\n  constructor({ messenger, state }: GeolocationControllerOptions) {\n    super({\n      messenger,\n      metadata: geolocationControllerMetadata,\n      name: controllerName,\n      state: { ...getDefaultGeolocationControllerState(), ...state },\n    });\n\n    this.messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Returns the geolocation code. Delegates to the\n   * {@link GeolocationApiService} for network fetching and caching, then\n   * updates controller state with the result.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async getGeolocation(): Promise<string> {\n    await this.#fetchAndUpdate();\n    return this.state.location;\n  }\n\n  /**\n   * Returns the country, region, and timezone for the current client.\n   * Delegates to the {@link GeolocationApiService} for network fetching and\n   * caching, then updates controller state with the result.\n   *\n   * @returns The geolocation data, where each field is `null` when it could\n   * not be determined.\n   */\n  async getGeolocationData(): Promise<GeolocationData> {\n    return this.#fetchAndUpdate();\n  }\n\n  /**\n   * Forces a fresh geolocation fetch, bypassing the service's cache.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async refreshGeolocation(): Promise<string> {\n    this.update((draft) => {\n      draft.lastFetchedAt = null;\n    });\n    await this.#fetchAndUpdate({ bypassCache: true });\n    return this.state.location;\n  }\n\n  /**\n   * Calls the geolocation service and updates controller state with the\n   * result.\n   *\n   * @param options - Options forwarded to the service.\n   * @param options.bypassCache - When true, the service skips its TTL cache.\n   * @returns The geolocation data. When the service throws, the last known\n   * geolocation is returned instead.\n   */\n  async #fetchAndUpdate(options?: {\n    bypassCache?: boolean;\n  }): Promise<GeolocationData> {\n    this.update((draft) => {\n      draft.status = 'loading';\n      draft.error = null;\n    });\n\n    try {\n      const geolocation = await this.messenger.call(\n        'GeolocationApiService:fetchGeolocationData',\n        options,\n      );\n\n      this.update((draft) => {\n        draft.location = toLocationCode(geolocation);\n        draft.country = geolocation.country;\n        draft.region = geolocation.region;\n        draft.timezone = geolocation.timezone;\n        draft.status = 'complete';\n        draft.lastFetchedAt = Date.now();\n        draft.error = null;\n      });\n\n      return geolocation;\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n\n      this.update((draft) => {\n        draft.status = 'error';\n        draft.error = message;\n      });\n\n      const { country, region, timezone } = this.state;\n      return { country, region, timezone };\n    }\n  }\n}\n"]}

package/dist/geolocation-api-service/geolocation-api-service-method-action-types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"geolocation-api-service-method-action-types.cjs","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { GeolocationApiService } from './geolocation-api-service.js';\n\n/**\n * Returns the geolocation code. Serves from cache when the TTL has not\n * expired, otherwise performs a network fetch. Concurrent callers are\n * deduplicated to a single in-flight request.\n *\n * @param options - Optional fetch options.\n * @param options.bypassCache - When true, invalidates the TTL cache. If a\n * request is already in-flight it will be reused (deduplication always\n * applies).\n * @returns An ISO 3166-2 location code (e.g. `US`, `US-NY`, `CA-ON`), or\n * {@link UNKNOWN_LOCATION} when the API returns an empty or invalid body.\n */\nexport type GeolocationApiServiceFetchGeolocationAction = {\n  type: `GeolocationApiService:fetchGeolocation`;\n  handler: GeolocationApiService['fetchGeolocation'];\n};\n\n/**\n * Union of all GeolocationApiService action types.\n */\nexport type GeolocationApiServiceMethodActions =\n  GeolocationApiServiceFetchGeolocationAction;\n"]}
+{"version":3,"file":"geolocation-api-service-method-action-types.cjs","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { GeolocationApiService } from './geolocation-api-service.js';\n\n/**\n * Returns the geolocation code. Serves from cache when the TTL has not\n * expired, otherwise performs a network fetch. Concurrent callers are\n * deduplicated to a single in-flight request.\n *\n * @param options - Optional fetch options.\n * @param options.bypassCache - When true, invalidates the TTL cache. If a\n * request is already in-flight it will be reused (deduplication always\n * applies).\n * @returns An ISO 3166-2 location code (e.g. `US`, `US-NY`, `CA-ON`), or\n * {@link UNKNOWN_LOCATION} when the API returns an empty or invalid body.\n */\nexport type GeolocationApiServiceFetchGeolocationAction = {\n  type: `GeolocationApiService:fetchGeolocation`;\n  handler: GeolocationApiService['fetchGeolocation'];\n};\n\n/**\n * Returns the country, region, and timezone for the current client. Serves\n * from cache when the TTL has not expired, otherwise performs a network\n * fetch. Concurrent callers are deduplicated to a single in-flight request.\n *\n * @param options - Optional fetch options.\n * @param options.bypassCache - When true, invalidates the TTL cache. If a\n * request is already in-flight it will be reused (deduplication always\n * applies).\n * @returns The geolocation data, where each field is `null` when the API\n * omits it or returns a value that fails validation.\n */\nexport type GeolocationApiServiceFetchGeolocationDataAction = {\n  type: `GeolocationApiService:fetchGeolocationData`;\n  handler: GeolocationApiService['fetchGeolocationData'];\n};\n\n/**\n * Union of all GeolocationApiService action types.\n */\nexport type GeolocationApiServiceMethodActions =\n  | GeolocationApiServiceFetchGeolocationAction\n  | GeolocationApiServiceFetchGeolocationDataAction;\n"]}

package/dist/geolocation-api-service/geolocation-api-service-method-action-types.d.cts

@@ -19,8 +19,24 @@ export type GeolocationApiServiceFetchGeolocationAction = {
     type: `GeolocationApiService:fetchGeolocation`;
     handler: GeolocationApiService['fetchGeolocation'];
 };
+/**
+ * Returns the country, region, and timezone for the current client. Serves
+ * from cache when the TTL has not expired, otherwise performs a network
+ * fetch. Concurrent callers are deduplicated to a single in-flight request.
+ *
+ * @param options - Optional fetch options.
+ * @param options.bypassCache - When true, invalidates the TTL cache. If a
+ * request is already in-flight it will be reused (deduplication always
+ * applies).
+ * @returns The geolocation data, where each field is `null` when the API
+ * omits it or returns a value that fails validation.
+ */
+export type GeolocationApiServiceFetchGeolocationDataAction = {
+    type: `GeolocationApiService:fetchGeolocationData`;
+    handler: GeolocationApiService['fetchGeolocationData'];
+};
 /**
  * Union of all GeolocationApiService action types.
  */
-export type GeolocationApiServiceMethodActions = GeolocationApiServiceFetchGeolocationAction;
+export type GeolocationApiServiceMethodActions = GeolocationApiServiceFetchGeolocationAction | GeolocationApiServiceFetchGeolocationDataAction;
 //# sourceMappingURL=geolocation-api-service-method-action-types.d.cts.map

package/dist/geolocation-api-service/geolocation-api-service-method-action-types.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"geolocation-api-service-method-action-types.d.cts","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,sCAAqC;AAE1E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,2CAA2C,GAAG;IACxD,IAAI,EAAE,wCAAwC,CAAC;IAC/C,OAAO,EAAE,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;CACpD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAC5C,2CAA2C,CAAC"}
+{"version":3,"file":"geolocation-api-service-method-action-types.d.cts","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,sCAAqC;AAE1E;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,2CAA2C,GAAG;IACxD,IAAI,EAAE,wCAAwC,CAAC;IAC/C,OAAO,EAAE,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;CACpD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,+CAA+C,GAAG;IAC5D,IAAI,EAAE,4CAA4C,CAAC;IACnD,OAAO,EAAE,qBAAqB,CAAC,sBAAsB,CAAC,CAAC;CACxD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kCAAkC,GAC1C,2CAA2C,GAC3C,+CAA+C,CAAC"}