@metamask-previews/geolocation-controller 0.0.0-preview-22ff1f0f2

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial release ([#8037](https://github.com/MetaMask/core/pull/8037))
+
+[Unreleased]: https://github.com/MetaMask/core/

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# `@metamask/geolocation-controller`
+
+Centralised geolocation controller with TTL caching and request deduplication.
+
+## Installation
+
+`yarn add @metamask/geolocation-controller`
+
+or
+
+`npm install @metamask/geolocation-controller`
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

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

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=GeolocationController-method-action-types.cjs.map

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

@@ -0,0 +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 by `scripts/generate-method-action-types.ts`.\n * Do not edit manually.\n */\n\nimport type { GeolocationController } from './GeolocationController';\n\n/**\n * Returns the geolocation country 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 country 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 country 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"]}

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

@@ -0,0 +1,30 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+import type { GeolocationController } from "./GeolocationController.cjs";
+/**
+ * Returns the geolocation country code. Delegates to the
+ * {@link GeolocationApiService} for network fetching and caching, then
+ * updates controller state with the result.
+ *
+ * @returns The ISO country code string.
+ */
+export type GeolocationControllerGetGeolocationAction = {
+    type: `GeolocationController:getGeolocation`;
+    handler: GeolocationController['getGeolocation'];
+};
+/**
+ * Forces a fresh geolocation fetch, bypassing the service's cache.
+ *
+ * @returns The ISO country code string.
+ */
+export type GeolocationControllerRefreshGeolocationAction = {
+    type: `GeolocationController:refreshGeolocation`;
+    handler: GeolocationController['refreshGeolocation'];
+};
+/**
+ * Union of all GeolocationController action types.
+ */
+export type GeolocationControllerMethodActions = GeolocationControllerGetGeolocationAction | GeolocationControllerRefreshGeolocationAction;
+//# sourceMappingURL=GeolocationController-method-action-types.d.cts.map

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

@@ -0,0 +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,oCAAgC;AAErE;;;;;;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"}

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

@@ -0,0 +1,30 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+import type { GeolocationController } from "./GeolocationController.mjs";
+/**
+ * Returns the geolocation country code. Delegates to the
+ * {@link GeolocationApiService} for network fetching and caching, then
+ * updates controller state with the result.
+ *
+ * @returns The ISO country code string.
+ */
+export type GeolocationControllerGetGeolocationAction = {
+    type: `GeolocationController:getGeolocation`;
+    handler: GeolocationController['getGeolocation'];
+};
+/**
+ * Forces a fresh geolocation fetch, bypassing the service's cache.
+ *
+ * @returns The ISO country code string.
+ */
+export type GeolocationControllerRefreshGeolocationAction = {
+    type: `GeolocationController:refreshGeolocation`;
+    handler: GeolocationController['refreshGeolocation'];
+};
+/**
+ * Union of all GeolocationController action types.
+ */
+export type GeolocationControllerMethodActions = GeolocationControllerGetGeolocationAction | GeolocationControllerRefreshGeolocationAction;
+//# sourceMappingURL=GeolocationController-method-action-types.d.mts.map

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

@@ -0,0 +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,oCAAgC;AAErE;;;;;;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"}

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

@@ -0,0 +1,6 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+export {};
+//# sourceMappingURL=GeolocationController-method-action-types.mjs.map

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

@@ -0,0 +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 by `scripts/generate-method-action-types.ts`.\n * Do not edit manually.\n */\n\nimport type { GeolocationController } from './GeolocationController';\n\n/**\n * Returns the geolocation country 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 country 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 country 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"]}

package/dist/GeolocationController.cjs

@@ -0,0 +1,154 @@
+"use strict";
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _GeolocationController_instances, _GeolocationController_fetchAndUpdate;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeolocationController = exports.getDefaultGeolocationControllerState = exports.controllerName = void 0;
+const base_controller_1 = require("@metamask/base-controller");
+const geolocation_api_service_1 = require("./geolocation-api-service/geolocation-api-service.cjs");
+/**
+ * The name of the {@link GeolocationController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+exports.controllerName = 'GeolocationController';
+/**
+ * The metadata for each property in {@link GeolocationControllerState}.
+ */
+const geolocationControllerMetadata = {
+    location: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    status: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: true,
+    },
+    lastFetchedAt: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: false,
+    },
+    error: {
+        persist: false,
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        usedInUi: false,
+    },
+};
+/**
+ * Constructs the default {@link GeolocationController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link GeolocationController} state.
+ */
+function getDefaultGeolocationControllerState() {
+    return {
+        location: geolocation_api_service_1.UNKNOWN_LOCATION,
+        status: 'idle',
+        lastFetchedAt: null,
+        error: null,
+    };
+}
+exports.getDefaultGeolocationControllerState = getDefaultGeolocationControllerState;
+const MESSENGER_EXPOSED_METHODS = [
+    'getGeolocation',
+    'refreshGeolocation',
+];
+/**
+ * GeolocationController manages UI-facing geolocation state by delegating
+ * the actual API interaction to {@link GeolocationApiService} via the
+ * messenger.
+ *
+ * The service (registered externally as
+ * `GeolocationApiService:fetchGeolocation`) handles HTTP requests, response
+ * validation, TTL caching, and promise deduplication. This controller focuses
+ * on state lifecycle (`idle` -> `loading` -> `complete` | `error`) and
+ * exposes `getGeolocation` / `refreshGeolocation` as messenger actions.
+ */
+class GeolocationController extends base_controller_1.BaseController {
+    /**
+     * Constructs a new {@link GeolocationController}.
+     *
+     * @param args - The arguments to this controller.
+     * @param args.messenger - The messenger suited for this controller. Must
+     * have a `GeolocationApiService:fetchGeolocation` action handler registered.
+     * @param args.state - Optional partial initial state.
+     */
+    constructor({ messenger, state }) {
+        super({
+            messenger,
+            metadata: geolocationControllerMetadata,
+            name: exports.controllerName,
+            state: { ...getDefaultGeolocationControllerState(), ...state },
+        });
+        _GeolocationController_instances.add(this);
+        this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
+    }
+    /**
+     * Returns the geolocation country code. Delegates to the
+     * {@link GeolocationApiService} for network fetching and caching, then
+     * updates controller state with the result.
+     *
+     * @returns The ISO country code string.
+     */
+    async getGeolocation() {
+        return __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this);
+    }
+    /**
+     * Forces a fresh geolocation fetch, bypassing the service's cache.
+     *
+     * @returns The ISO country code string.
+     */
+    async refreshGeolocation() {
+        this.update((draft) => {
+            draft.lastFetchedAt = null;
+        });
+        return __classPrivateFieldGet(this, _GeolocationController_instances, "m", _GeolocationController_fetchAndUpdate).call(this, { bypassCache: true });
+    }
+}
+exports.GeolocationController = GeolocationController;
+_GeolocationController_instances = new WeakSet(), _GeolocationController_fetchAndUpdate = 
+/**
+ * Calls the geolocation service and updates controller state with the
+ * result.
+ *
+ * @param options - Options forwarded to the service.
+ * @param options.bypassCache - When true, the service skips its TTL cache.
+ * @returns The ISO country code string.
+ */
+async function _GeolocationController_fetchAndUpdate(options) {
+    this.update((draft) => {
+        draft.status = 'loading';
+        draft.error = null;
+    });
+    try {
+        const location = await this.messenger.call('GeolocationApiService:fetchGeolocation', options);
+        this.update((draft) => {
+            draft.location = location;
+            draft.status = 'complete';
+            draft.lastFetchedAt = Date.now();
+            draft.error = null;
+        });
+        return location;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.update((draft) => {
+            draft.status = 'error';
+            draft.error = message;
+        });
+        return this.state.location;
+    }
+};
+//# sourceMappingURL=GeolocationController.cjs.map

package/dist/GeolocationController.cjs.map

@@ -0,0 +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 { UNKNOWN_LOCATION } from './geolocation-api-service/geolocation-api-service';\nimport type { GeolocationApiServiceFetchGeolocationAction } from './geolocation-api-service/geolocation-api-service-method-action-types';\nimport type { GeolocationControllerMethodActions } from './GeolocationController-method-action-types';\nimport type { GeolocationRequestStatus } from './types';\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-1 alpha-2 country code, 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 country 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 country 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 country 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 country 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"]}

package/dist/GeolocationController.d.cts

@@ -0,0 +1,112 @@
+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 { GeolocationControllerMethodActions } from "./GeolocationController-method-action-types.cjs";
+import type { GeolocationRequestStatus } from "./types.cjs";
+/**
+ * The name of the {@link GeolocationController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+export declare const controllerName = "GeolocationController";
+/**
+ * State for the {@link GeolocationController}.
+ */
+export type GeolocationControllerState = {
+    /** ISO 3166-1 alpha-2 country code, or "UNKNOWN" if not yet determined. */
+    location: string;
+    /** Current status of the geolocation fetch lifecycle. */
+    status: GeolocationRequestStatus;
+    /** Epoch milliseconds of the last successful fetch, or null if never fetched. */
+    lastFetchedAt: number | null;
+    /** Last error message, or null if no error has occurred. */
+    error: string | null;
+};
+/**
+ * Constructs the default {@link GeolocationController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link GeolocationController} state.
+ */
+export declare function getDefaultGeolocationControllerState(): GeolocationControllerState;
+/**
+ * Retrieves the state of the {@link GeolocationController}.
+ */
+export type GeolocationControllerGetStateAction = ControllerGetStateAction<typeof controllerName, GeolocationControllerState>;
+/**
+ * Actions that {@link GeolocationControllerMessenger} exposes to other consumers.
+ */
+export type GeolocationControllerActions = GeolocationControllerGetStateAction | GeolocationControllerMethodActions;
+/**
+ * Actions from other messengers that {@link GeolocationControllerMessenger} calls.
+ */
+type AllowedActions = GeolocationApiServiceFetchGeolocationAction;
+/**
+ * Published when the state of {@link GeolocationController} changes.
+ */
+export type GeolocationControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, GeolocationControllerState>;
+/**
+ * Events that {@link GeolocationControllerMessenger} exposes to other consumers.
+ */
+export type GeolocationControllerEvents = GeolocationControllerStateChangeEvent;
+/**
+ * Events from other messengers that {@link GeolocationControllerMessenger}
+ * subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger restricted to actions and events accessed by
+ * {@link GeolocationController}.
+ */
+export type GeolocationControllerMessenger = Messenger<typeof controllerName, GeolocationControllerActions | AllowedActions, GeolocationControllerEvents | AllowedEvents>;
+/**
+ * Options for constructing the {@link GeolocationController}.
+ */
+export type GeolocationControllerOptions = {
+    /** The messenger for inter-controller communication. */
+    messenger: GeolocationControllerMessenger;
+    /** Optional partial initial state. */
+    state?: Partial<GeolocationControllerState>;
+};
+/**
+ * GeolocationController manages UI-facing geolocation state by delegating
+ * the actual API interaction to {@link GeolocationApiService} via the
+ * messenger.
+ *
+ * The service (registered externally as
+ * `GeolocationApiService:fetchGeolocation`) handles HTTP requests, response
+ * validation, TTL caching, and promise deduplication. This controller focuses
+ * on state lifecycle (`idle` -> `loading` -> `complete` | `error`) and
+ * exposes `getGeolocation` / `refreshGeolocation` as messenger actions.
+ */
+export declare class GeolocationController extends BaseController<typeof controllerName, GeolocationControllerState, GeolocationControllerMessenger> {
+    #private;
+    /**
+     * Constructs a new {@link GeolocationController}.
+     *
+     * @param args - The arguments to this controller.
+     * @param args.messenger - The messenger suited for this controller. Must
+     * have a `GeolocationApiService:fetchGeolocation` action handler registered.
+     * @param args.state - Optional partial initial state.
+     */
+    constructor({ messenger, state }: GeolocationControllerOptions);
+    /**
+     * Returns the geolocation country code. Delegates to the
+     * {@link GeolocationApiService} for network fetching and caching, then
+     * updates controller state with the result.
+     *
+     * @returns The ISO country code string.
+     */
+    getGeolocation(): Promise<string>;
+    /**
+     * Forces a fresh geolocation fetch, bypassing the service's cache.
+     *
+     * @returns The ISO country code string.
+     */
+    refreshGeolocation(): Promise<string>;
+}
+export {};
+//# sourceMappingURL=GeolocationController.d.cts.map

package/dist/GeolocationController.d.cts.map

@@ -0,0 +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;AAGrD,OAAO,KAAK,EAAE,2CAA2C,EAAE,kFAA8E;AACzI,OAAO,KAAK,EAAE,kCAAkC,EAAE,wDAAoD;AACtG,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAgB;AAExD;;;;GAIG;AACH,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,2EAA2E;IAC3E,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"}

package/dist/GeolocationController.d.mts

@@ -0,0 +1,112 @@
+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 { GeolocationControllerMethodActions } from "./GeolocationController-method-action-types.mjs";
+import type { GeolocationRequestStatus } from "./types.mjs";
+/**
+ * The name of the {@link GeolocationController}, used to namespace the
+ * controller's actions and events and to namespace the controller's state data
+ * when composed with other controllers.
+ */
+export declare const controllerName = "GeolocationController";
+/**
+ * State for the {@link GeolocationController}.
+ */
+export type GeolocationControllerState = {
+    /** ISO 3166-1 alpha-2 country code, or "UNKNOWN" if not yet determined. */
+    location: string;
+    /** Current status of the geolocation fetch lifecycle. */
+    status: GeolocationRequestStatus;
+    /** Epoch milliseconds of the last successful fetch, or null if never fetched. */
+    lastFetchedAt: number | null;
+    /** Last error message, or null if no error has occurred. */
+    error: string | null;
+};
+/**
+ * Constructs the default {@link GeolocationController} state. This allows
+ * consumers to provide a partial state object when initializing the controller
+ * and also helps in constructing complete state objects for this controller in
+ * tests.
+ *
+ * @returns The default {@link GeolocationController} state.
+ */
+export declare function getDefaultGeolocationControllerState(): GeolocationControllerState;
+/**
+ * Retrieves the state of the {@link GeolocationController}.
+ */
+export type GeolocationControllerGetStateAction = ControllerGetStateAction<typeof controllerName, GeolocationControllerState>;
+/**
+ * Actions that {@link GeolocationControllerMessenger} exposes to other consumers.
+ */
+export type GeolocationControllerActions = GeolocationControllerGetStateAction | GeolocationControllerMethodActions;
+/**
+ * Actions from other messengers that {@link GeolocationControllerMessenger} calls.
+ */
+type AllowedActions = GeolocationApiServiceFetchGeolocationAction;
+/**
+ * Published when the state of {@link GeolocationController} changes.
+ */
+export type GeolocationControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, GeolocationControllerState>;
+/**
+ * Events that {@link GeolocationControllerMessenger} exposes to other consumers.
+ */
+export type GeolocationControllerEvents = GeolocationControllerStateChangeEvent;
+/**
+ * Events from other messengers that {@link GeolocationControllerMessenger}
+ * subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger restricted to actions and events accessed by
+ * {@link GeolocationController}.
+ */
+export type GeolocationControllerMessenger = Messenger<typeof controllerName, GeolocationControllerActions | AllowedActions, GeolocationControllerEvents | AllowedEvents>;
+/**
+ * Options for constructing the {@link GeolocationController}.
+ */
+export type GeolocationControllerOptions = {
+    /** The messenger for inter-controller communication. */
+    messenger: GeolocationControllerMessenger;
+    /** Optional partial initial state. */
+    state?: Partial<GeolocationControllerState>;
+};
+/**
+ * GeolocationController manages UI-facing geolocation state by delegating
+ * the actual API interaction to {@link GeolocationApiService} via the
+ * messenger.
+ *
+ * The service (registered externally as
+ * `GeolocationApiService:fetchGeolocation`) handles HTTP requests, response
+ * validation, TTL caching, and promise deduplication. This controller focuses
+ * on state lifecycle (`idle` -> `loading` -> `complete` | `error`) and
+ * exposes `getGeolocation` / `refreshGeolocation` as messenger actions.
+ */
+export declare class GeolocationController extends BaseController<typeof controllerName, GeolocationControllerState, GeolocationControllerMessenger> {
+    #private;
+    /**
+     * Constructs a new {@link GeolocationController}.
+     *
+     * @param args - The arguments to this controller.
+     * @param args.messenger - The messenger suited for this controller. Must
+     * have a `GeolocationApiService:fetchGeolocation` action handler registered.
+     * @param args.state - Optional partial initial state.
+     */
+    constructor({ messenger, state }: GeolocationControllerOptions);
+    /**
+     * Returns the geolocation country code. Delegates to the
+     * {@link GeolocationApiService} for network fetching and caching, then
+     * updates controller state with the result.
+     *
+     * @returns The ISO country code string.
+     */
+    getGeolocation(): Promise<string>;
+    /**
+     * Forces a fresh geolocation fetch, bypassing the service's cache.
+     *
+     * @returns The ISO country code string.
+     */
+    refreshGeolocation(): Promise<string>;
+}
+export {};
+//# sourceMappingURL=GeolocationController.d.mts.map

package/dist/GeolocationController.d.mts.map

@@ -0,0 +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;AAGrD,OAAO,KAAK,EAAE,2CAA2C,EAAE,kFAA8E;AACzI,OAAO,KAAK,EAAE,kCAAkC,EAAE,wDAAoD;AACtG,OAAO,KAAK,EAAE,wBAAwB,EAAE,oBAAgB;AAExD;;;;GAIG;AACH,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,2EAA2E;IAC3E,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"}