@metamask-previews/geolocation-controller 0.1.3-preview-d67bfdbad → 0.1.3-preview-937b1a1

package/dist/geolocation-api-service/geolocation-api-service.mjs

@@ -9,14 +9,11 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     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 _GeolocationApiService_instances, _GeolocationApiService_messenger, _GeolocationApiService_fetch, _GeolocationApiService_url, _GeolocationApiService_ttlMs, _GeolocationApiService_policy, _GeolocationApiService_cachedGeolocation, _GeolocationApiService_lastFetchedAt, _GeolocationApiService_fetchPromise, _GeolocationApiService_isCacheValid, _GeolocationApiService_performFetch;
+var _GeolocationApiService_instances, _GeolocationApiService_messenger, _GeolocationApiService_fetch, _GeolocationApiService_url, _GeolocationApiService_ttlMs, _GeolocationApiService_policy, _GeolocationApiService_cachedLocation, _GeolocationApiService_lastFetchedAt, _GeolocationApiService_fetchPromise, _GeolocationApiService_isCacheValid, _GeolocationApiService_performFetch;
 import { createServicePolicy, HttpError } from "@metamask/controller-utils";
 import { Env } from "../types.mjs";
 const DEFAULT_TTL_MS = 5 * 60 * 1000;
-const ENDPOINT_PATH = '/v2/geolocation';
-const COUNTRY_PATTERN = /^[A-Z]{2}$/u;
-const REGION_PATTERN = /^[A-Z0-9]{1,3}$/u;
-const TIMEZONE_PATTERN = /^[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)*$/u;
+const ENDPOINT_PATH = '/v1/geolocation';
 // === GENERAL ===
 /**
  * The name of the {@link GeolocationApiService}, used to namespace the
@@ -28,47 +25,8 @@ export const serviceName = 'GeolocationApiService';
  * the API returns an empty / invalid response.
  */
 export const UNKNOWN_LOCATION = 'UNKNOWN';
-/**
- * Constructs a {@link GeolocationData} with no known fields.
- *
- * @returns Geolocation data where every field is `null`.
- */
-export function getUnknownGeolocationData() {
-    return { country: null, region: null, timezone: null };
-}
-/**
- * Country codes for which the location code includes the region. This mirrors
- * the legacy `v1` geolocation endpoint, which only appended the subdivision for
- * the United States and Canada (e.g. `US-NY`, `CA-ON`) and returned the country
- * alone for everywhere else.
- */
-const REGION_APPENDED_COUNTRIES = new Set(['US', 'CA']);
-/**
- * Converts geolocation data to a location code.
- *
- * To preserve backwards compatibility with the legacy `v1` endpoint, the region
- * is appended only for {@link REGION_APPENDED_COUNTRIES} (e.g. `US-NY`,
- * `CA-ON`); all other countries return the country code alone (e.g. `FR`), even
- * when a region is known.
- *
- * @param data - The geolocation data to convert.
- * @returns The location code (e.g. `US-NY`, `FR`), or
- * {@link UNKNOWN_LOCATION} when the country is unknown.
- */
-export function toLocationCode(data) {
-    if (data.country === null) {
-        return UNKNOWN_LOCATION;
-    }
-    if (data.region !== null && REGION_APPENDED_COUNTRIES.has(data.country)) {
-        return `${data.country}-${data.region}`;
-    }
-    return data.country;
-}
 // === MESSENGER ===
-const MESSENGER_EXPOSED_METHODS = [
-    'fetchGeolocation',
-    'fetchGeolocationData',
-];
+const MESSENGER_EXPOSED_METHODS = ['fetchGeolocation'];
 // === SERVICE DEFINITION ===
 /**
  * Returns the base URL for the geolocation API for the given environment.
@@ -86,66 +44,18 @@ function getGeolocationUrl(env) {
     return `https://geolocation.${envPrefix}api.cx.metamask.io${ENDPOINT_PATH}`;
 }
 /**
- * Reads a string field from a parsed response body, keeping it only when it
- * matches the expected format.
- *
- * @param body - The parsed response body.
- * @param field - The name of the field to read.
- * @param pattern - The pattern the field value must match.
- * @returns The trimmed field value, or `null` when it is missing or invalid.
- */
-function readValidatedField(body, field, pattern) {
-    const value = body[field];
-    if (typeof value !== 'string') {
-        return null;
-    }
-    const trimmed = value.trim();
-    return pattern.test(trimmed) ? trimmed : null;
-}
-/**
- * Parses and validates the geolocation API response body.
- *
- * The endpoint is expected to return JSON such as
- * `{"country":"US","region":"WA","timezone":"America/Los_Angeles"}`. Anything
- * that cannot be parsed, or any individual field that fails validation, is
- * reported as unknown rather than throwing, so that consumers can keep working
- * with partial or missing data.
- *
- * @param raw - The raw response body.
- * @returns The validated geolocation data.
- */
-function parseGeolocationResponse(raw) {
-    let body;
-    try {
-        body = JSON.parse(raw);
-    }
-    catch {
-        return getUnknownGeolocationData();
-    }
-    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
-        return getUnknownGeolocationData();
-    }
-    const record = body;
-    return {
-        country: readValidatedField(record, 'country', COUNTRY_PATTERN),
-        region: readValidatedField(record, 'region', REGION_PATTERN),
-        timezone: readValidatedField(record, 'timezone', TIMEZONE_PATTERN),
-    };
-}
-/**
- * Low-level data service that fetches geolocation details from the geolocation
- * API.
+ * Low-level data service that fetches a location code from the geolocation API.
  *
  * Responsibilities:
  * - HTTP request to the geolocation endpoint (wrapped in a service policy)
- * - Response validation of the country, region, and timezone fields
+ * - ISO 3166-2 response validation (country code with optional subdivision,
+ *   e.g. `US`, `US-NY`, `CA-ON`)
  * - TTL-based in-memory cache
  * - Promise deduplication (concurrent callers share a single in-flight request)
  *
  * This class is intentionally not a controller: it does not manage UI state.
- * Its {@link fetchGeolocation} and {@link fetchGeolocationData} methods are
- * automatically registered on the messenger so that controllers and other
- * packages can call them directly.
+ * Its {@link fetchGeolocation} method is automatically registered on the
+ * messenger so that controllers and other packages can call it directly.
  */
 export class GeolocationApiService {
     /**
@@ -173,7 +83,7 @@ export class GeolocationApiService {
          * @see {@link createServicePolicy}
          */
         _GeolocationApiService_policy.set(this, void 0);
-        _GeolocationApiService_cachedGeolocation.set(this, getUnknownGeolocationData());
+        _GeolocationApiService_cachedLocation.set(this, UNKNOWN_LOCATION);
         _GeolocationApiService_lastFetchedAt.set(this, null);
         _GeolocationApiService_fetchPromise.set(this, null);
         this.name = serviceName;
@@ -230,26 +140,11 @@ export class GeolocationApiService {
      * {@link UNKNOWN_LOCATION} when the API returns an empty or invalid body.
      */
     async fetchGeolocation(options) {
-        return toLocationCode(await this.fetchGeolocationData(options));
-    }
-    /**
-     * 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.
-     */
-    async fetchGeolocationData(options) {
         if (options?.bypassCache) {
             __classPrivateFieldSet(this, _GeolocationApiService_lastFetchedAt, null, "f");
         }
         if (__classPrivateFieldGet(this, _GeolocationApiService_instances, "m", _GeolocationApiService_isCacheValid).call(this)) {
-            return __classPrivateFieldGet(this, _GeolocationApiService_cachedGeolocation, "f");
+            return __classPrivateFieldGet(this, _GeolocationApiService_cachedLocation, "f");
         }
         if (__classPrivateFieldGet(this, _GeolocationApiService_fetchPromise, "f")) {
             return __classPrivateFieldGet(this, _GeolocationApiService_fetchPromise, "f");
@@ -264,7 +159,7 @@ export class GeolocationApiService {
         }
     }
 }
-_GeolocationApiService_messenger = new WeakMap(), _GeolocationApiService_fetch = new WeakMap(), _GeolocationApiService_url = new WeakMap(), _GeolocationApiService_ttlMs = new WeakMap(), _GeolocationApiService_policy = new WeakMap(), _GeolocationApiService_cachedGeolocation = new WeakMap(), _GeolocationApiService_lastFetchedAt = new WeakMap(), _GeolocationApiService_fetchPromise = new WeakMap(), _GeolocationApiService_instances = new WeakSet(), _GeolocationApiService_isCacheValid = function _GeolocationApiService_isCacheValid() {
+_GeolocationApiService_messenger = new WeakMap(), _GeolocationApiService_fetch = new WeakMap(), _GeolocationApiService_url = new WeakMap(), _GeolocationApiService_ttlMs = new WeakMap(), _GeolocationApiService_policy = new WeakMap(), _GeolocationApiService_cachedLocation = new WeakMap(), _GeolocationApiService_lastFetchedAt = new WeakMap(), _GeolocationApiService_fetchPromise = new WeakMap(), _GeolocationApiService_instances = new WeakSet(), _GeolocationApiService_isCacheValid = function _GeolocationApiService_isCacheValid() {
     return (__classPrivateFieldGet(this, _GeolocationApiService_lastFetchedAt, "f") !== null &&
         Date.now() - __classPrivateFieldGet(this, _GeolocationApiService_lastFetchedAt, "f") < __classPrivateFieldGet(this, _GeolocationApiService_ttlMs, "f"));
 }, _GeolocationApiService_performFetch = 
@@ -272,7 +167,7 @@ _GeolocationApiService_messenger = new WeakMap(), _GeolocationApiService_fetch =
  * Performs the actual HTTP fetch, wrapped in the service policy for automatic
  * retry and circuit-breaking, and validates the response.
  *
- * @returns The validated geolocation data.
+ * @returns The ISO 3166-2 location code string.
  */
 async function _GeolocationApiService_performFetch() {
     const response = await __classPrivateFieldGet(this, _GeolocationApiService_policy, "f").execute(async () => {
@@ -282,18 +177,14 @@ async function _GeolocationApiService_performFetch() {
         }
         return localResponse;
     });
-    const geolocation = parseGeolocationResponse((await response.text()).trim());
-    // Cache whenever at least one field resolved. A partially-known result
-    // (e.g. timezone without a valid country) is still worth caching so we do
-    // not re-fetch it within the TTL window; only a fully-unknown response is
-    // left uncached so it can be retried.
-    const hasKnownField = geolocation.country !== null ||
-        geolocation.region !== null ||
-        geolocation.timezone !== null;
-    if (hasKnownField) {
-        __classPrivateFieldSet(this, _GeolocationApiService_cachedGeolocation, geolocation, "f");
+    const raw = (await response.text()).trim();
+    const location = /^[A-Z]{2}(-[A-Z0-9]{1,3})?$/u.test(raw)
+        ? raw
+        : UNKNOWN_LOCATION;
+    if (location !== UNKNOWN_LOCATION) {
+        __classPrivateFieldSet(this, _GeolocationApiService_cachedLocation, location, "f");
         __classPrivateFieldSet(this, _GeolocationApiService_lastFetchedAt, Date.now(), "f");
     }
-    return geolocation;
+    return location;
 };
 //# sourceMappingURL=geolocation-api-service.mjs.map

package/dist/geolocation-api-service/geolocation-api-service.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"geolocation-api-service.mjs","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CreateServicePolicyOptions,\n  ServicePolicy,\n} from '@metamask/controller-utils';\nimport { createServicePolicy, HttpError } from '@metamask/controller-utils';\nimport type { Messenger } from '@metamask/messenger';\nimport type { IDisposable } from 'cockatiel';\n\nimport { Env } from '../types.js';\nimport type { GeolocationApiServiceMethodActions } from './geolocation-api-service-method-action-types.js';\n\nconst DEFAULT_TTL_MS = 5 * 60 * 1000;\n\nconst ENDPOINT_PATH = '/v2/geolocation';\n\nconst COUNTRY_PATTERN = /^[A-Z]{2}$/u;\n\nconst REGION_PATTERN = /^[A-Z0-9]{1,3}$/u;\n\nconst TIMEZONE_PATTERN = /^[A-Za-z][A-Za-z0-9_+-]*(?:\\/[A-Za-z0-9_+-]+)*$/u;\n\n// === GENERAL ===\n\n/**\n * The name of the {@link GeolocationApiService}, used to namespace the\n * service's actions and events.\n */\nexport const serviceName = 'GeolocationApiService';\n\n/**\n * Sentinel value used when the geolocation has not been determined yet or when\n * the API returns an empty / invalid response.\n */\nexport const UNKNOWN_LOCATION = 'UNKNOWN';\n\n/**\n * Geolocation details returned by the geolocation API.\n *\n * Each field is `null` when the API omits it or returns a value that fails\n * validation.\n */\nexport type GeolocationData = {\n  /** ISO 3166-1 alpha-2 country code (e.g. `US`, `FR`). */\n  country: string | null;\n  /** ISO 3166-2 subdivision code without the country prefix (e.g. `WA`). */\n  region: string | null;\n  /** IANA time zone name (e.g. `America/Los_Angeles`). */\n  timezone: string | null;\n};\n\n/**\n * Constructs a {@link GeolocationData} with no known fields.\n *\n * @returns Geolocation data where every field is `null`.\n */\nexport function getUnknownGeolocationData(): GeolocationData {\n  return { country: null, region: null, timezone: null };\n}\n\n/**\n * Country codes for which the location code includes the region. This mirrors\n * the legacy `v1` geolocation endpoint, which only appended the subdivision for\n * the United States and Canada (e.g. `US-NY`, `CA-ON`) and returned the country\n * alone for everywhere else.\n */\nconst REGION_APPENDED_COUNTRIES = new Set(['US', 'CA']);\n\n/**\n * Converts geolocation data to a location code.\n *\n * To preserve backwards compatibility with the legacy `v1` endpoint, the region\n * is appended only for {@link REGION_APPENDED_COUNTRIES} (e.g. `US-NY`,\n * `CA-ON`); all other countries return the country code alone (e.g. `FR`), even\n * when a region is known.\n *\n * @param data - The geolocation data to convert.\n * @returns The location code (e.g. `US-NY`, `FR`), or\n * {@link UNKNOWN_LOCATION} when the country is unknown.\n */\nexport function toLocationCode(data: GeolocationData): string {\n  if (data.country === null) {\n    return UNKNOWN_LOCATION;\n  }\n\n  if (data.region !== null && REGION_APPENDED_COUNTRIES.has(data.country)) {\n    return `${data.country}-${data.region}`;\n  }\n\n  return data.country;\n}\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'fetchGeolocation',\n  'fetchGeolocationData',\n] as const;\n\n/**\n * Actions that {@link GeolocationApiService} exposes to other consumers.\n */\nexport type GeolocationApiServiceActions = GeolocationApiServiceMethodActions;\n\n/**\n * Actions from other messengers that {@link GeolocationApiServiceMessenger}\n * calls.\n */\ntype AllowedActions = never;\n\n/**\n * Events that {@link GeolocationApiService} exposes to other consumers.\n */\nexport type GeolocationApiServiceEvents = never;\n\n/**\n * Events from other messengers that {@link GeolocationApiService} subscribes\n * to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link GeolocationApiService}.\n */\nexport type GeolocationApiServiceMessenger = Messenger<\n  typeof serviceName,\n  GeolocationApiServiceActions | AllowedActions,\n  GeolocationApiServiceEvents | AllowedEvents\n>;\n\n// === SERVICE DEFINITION ===\n\n/**\n * Returns the base URL for the geolocation API for the given environment.\n *\n * Served by API Platform's `geolocation-api` service, not the legacy\n * Ramps-owned `on-ramp` endpoint this previously pointed to. API Platform has\n * not yet provisioned a dedicated UAT deployment for this service, so UAT\n * temporarily resolves to the production URL until one exists.\n *\n * @param env - The environment to get the URL for.\n * @returns The full URL for the geolocation endpoint.\n */\nfunction getGeolocationUrl(env: Env): string {\n  const envPrefix = env === Env.DEV ? 'dev-' : '';\n  return `https://geolocation.${envPrefix}api.cx.metamask.io${ENDPOINT_PATH}`;\n}\n\n/**\n * Reads a string field from a parsed response body, keeping it only when it\n * matches the expected format.\n *\n * @param body - The parsed response body.\n * @param field - The name of the field to read.\n * @param pattern - The pattern the field value must match.\n * @returns The trimmed field value, or `null` when it is missing or invalid.\n */\nfunction readValidatedField(\n  body: Record<string, unknown>,\n  field: string,\n  pattern: RegExp,\n): string | null {\n  const value = body[field];\n\n  if (typeof value !== 'string') {\n    return null;\n  }\n\n  const trimmed = value.trim();\n\n  return pattern.test(trimmed) ? trimmed : null;\n}\n\n/**\n * Parses and validates the geolocation API response body.\n *\n * The endpoint is expected to return JSON such as\n * `{\"country\":\"US\",\"region\":\"WA\",\"timezone\":\"America/Los_Angeles\"}`. Anything\n * that cannot be parsed, or any individual field that fails validation, is\n * reported as unknown rather than throwing, so that consumers can keep working\n * with partial or missing data.\n *\n * @param raw - The raw response body.\n * @returns The validated geolocation data.\n */\nfunction parseGeolocationResponse(raw: string): GeolocationData {\n  let body: unknown;\n\n  try {\n    body = JSON.parse(raw);\n  } catch {\n    return getUnknownGeolocationData();\n  }\n\n  if (typeof body !== 'object' || body === null || Array.isArray(body)) {\n    return getUnknownGeolocationData();\n  }\n\n  const record = body as Record<string, unknown>;\n\n  return {\n    country: readValidatedField(record, 'country', COUNTRY_PATTERN),\n    region: readValidatedField(record, 'region', REGION_PATTERN),\n    timezone: readValidatedField(record, 'timezone', TIMEZONE_PATTERN),\n  };\n}\n\n/**\n * Options accepted by {@link GeolocationApiService.fetchGeolocation}.\n */\nexport type FetchGeolocationOptions = {\n  /** When true, the TTL cache is invalidated so the next request fetches fresh data. */\n  bypassCache?: boolean;\n};\n\n/**\n * Low-level data service that fetches geolocation details from the geolocation\n * API.\n *\n * Responsibilities:\n * - HTTP request to the geolocation endpoint (wrapped in a service policy)\n * - Response validation of the country, region, and timezone fields\n * - TTL-based in-memory cache\n * - Promise deduplication (concurrent callers share a single in-flight request)\n *\n * This class is intentionally not a controller: it does not manage UI state.\n * Its {@link fetchGeolocation} and {@link fetchGeolocationData} methods are\n * automatically registered on the messenger so that controllers and other\n * packages can call them directly.\n */\nexport class GeolocationApiService {\n  /**\n   * The name of the service.\n   */\n  readonly name: typeof serviceName;\n\n  readonly #messenger: GeolocationApiServiceMessenger;\n\n  readonly #fetch: typeof globalThis.fetch;\n\n  readonly #url: string;\n\n  readonly #ttlMs: number;\n\n  /**\n   * The policy that wraps each HTTP request.\n   *\n   * @see {@link createServicePolicy}\n   */\n  readonly #policy: ServicePolicy;\n\n  #cachedGeolocation: GeolocationData = getUnknownGeolocationData();\n\n  #lastFetchedAt: number | null = null;\n\n  #fetchPromise: Promise<GeolocationData> | null = null;\n\n  /**\n   * Constructs a new {@link GeolocationApiService}.\n   *\n   * @param args - The constructor arguments.\n   * @param args.messenger - The messenger suited for this service.\n   * @param args.env - The environment to determine the correct API endpoint.\n   * Defaults to PRD.\n   * @param args.fetch - A function that can be used to make an HTTP request.\n   * Defaults to the global fetch.\n   * @param args.ttlMs - Cache TTL in milliseconds. Defaults to 5 minutes.\n   * @param args.policyOptions - Options to pass to `createServicePolicy`, which\n   * is used to wrap each request. See {@link CreateServicePolicyOptions}.\n   */\n  constructor({\n    messenger,\n    env = Env.PRD,\n    fetch: fetchFunction = globalThis.fetch,\n    ttlMs,\n    policyOptions = {},\n  }: {\n    messenger: GeolocationApiServiceMessenger;\n    env?: Env;\n    fetch?: typeof fetch;\n    ttlMs?: number;\n    policyOptions?: CreateServicePolicyOptions;\n  }) {\n    this.name = serviceName;\n    this.#messenger = messenger;\n    this.#url = getGeolocationUrl(env);\n    this.#fetch = fetchFunction;\n    this.#ttlMs = ttlMs ?? DEFAULT_TTL_MS;\n    this.#policy = createServicePolicy(policyOptions);\n\n    this.#messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Registers a handler that will be called after a request returns a 5xx\n   * response, causing a retry.\n   *\n   * @param listener - The handler to be called.\n   * @returns An object that can be used to unregister the handler.\n   * @see {@link createServicePolicy}\n   */\n  onRetry(listener: Parameters<ServicePolicy['onRetry']>[0]): IDisposable {\n    return this.#policy.onRetry(listener);\n  }\n\n  /**\n   * Registers a handler that will be called after a set number of retry rounds\n   * prove that requests to the API endpoint consistently return a 5xx response.\n   *\n   * @param listener - The handler to be called.\n   * @returns An object that can be used to unregister the handler.\n   * @see {@link createServicePolicy}\n   */\n  onBreak(listener: Parameters<ServicePolicy['onBreak']>[0]): IDisposable {\n    return this.#policy.onBreak(listener);\n  }\n\n  /**\n   * Registers a handler that will be called when requests are consistently\n   * failing or when a successful request takes longer than the degraded\n   * threshold.\n   *\n   * @param listener - The handler to be called.\n   * @returns An object that can be used to unregister the handler.\n   */\n  onDegraded(\n    listener: Parameters<ServicePolicy['onDegraded']>[0],\n  ): IDisposable {\n    return this.#policy.onDegraded(listener);\n  }\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   */\n  async fetchGeolocation(options?: FetchGeolocationOptions): Promise<string> {\n    return toLocationCode(await this.fetchGeolocationData(options));\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   */\n  async fetchGeolocationData(\n    options?: FetchGeolocationOptions,\n  ): Promise<GeolocationData> {\n    if (options?.bypassCache) {\n      this.#lastFetchedAt = null;\n    }\n\n    if (this.#isCacheValid()) {\n      return this.#cachedGeolocation;\n    }\n\n    if (this.#fetchPromise) {\n      return this.#fetchPromise;\n    }\n\n    const promise = this.#performFetch();\n    this.#fetchPromise = promise;\n\n    try {\n      return await promise;\n    } finally {\n      this.#fetchPromise = null;\n    }\n  }\n\n  /**\n   * Checks whether the cached geolocation is still within the TTL window.\n   *\n   * @returns True if the cache is valid.\n   */\n  #isCacheValid(): boolean {\n    return (\n      this.#lastFetchedAt !== null &&\n      Date.now() - this.#lastFetchedAt < this.#ttlMs\n    );\n  }\n\n  /**\n   * Performs the actual HTTP fetch, wrapped in the service policy for automatic\n   * retry and circuit-breaking, and validates the response.\n   *\n   * @returns The validated geolocation data.\n   */\n  async #performFetch(): Promise<GeolocationData> {\n    const response = await this.#policy.execute(async () => {\n      const localResponse = await this.#fetch(this.#url);\n      if (!localResponse.ok) {\n        throw new HttpError(\n          localResponse.status,\n          `Geolocation fetch failed: ${localResponse.status}`,\n        );\n      }\n      return localResponse;\n    });\n\n    const geolocation = parseGeolocationResponse(\n      (await response.text()).trim(),\n    );\n\n    // Cache whenever at least one field resolved. A partially-known result\n    // (e.g. timezone without a valid country) is still worth caching so we do\n    // not re-fetch it within the TTL window; only a fully-unknown response is\n    // left uncached so it can be retried.\n    const hasKnownField =\n      geolocation.country !== null ||\n      geolocation.region !== null ||\n      geolocation.timezone !== null;\n\n    if (hasKnownField) {\n      this.#cachedGeolocation = geolocation;\n      this.#lastFetchedAt = Date.now();\n    }\n\n    return geolocation;\n  }\n}\n"]}
+{"version":3,"file":"geolocation-api-service.mjs","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CreateServicePolicyOptions,\n  ServicePolicy,\n} from '@metamask/controller-utils';\nimport { createServicePolicy, HttpError } from '@metamask/controller-utils';\nimport type { Messenger } from '@metamask/messenger';\nimport type { IDisposable } from 'cockatiel';\n\nimport { Env } from '../types.js';\nimport type { GeolocationApiServiceMethodActions } from './geolocation-api-service-method-action-types.js';\n\nconst DEFAULT_TTL_MS = 5 * 60 * 1000;\n\nconst ENDPOINT_PATH = '/v1/geolocation';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link GeolocationApiService}, used to namespace the\n * service's actions and events.\n */\nexport const serviceName = 'GeolocationApiService';\n\n/**\n * Sentinel value used when the geolocation has not been determined yet or when\n * the API returns an empty / invalid response.\n */\nexport const UNKNOWN_LOCATION = 'UNKNOWN';\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = ['fetchGeolocation'] as const;\n\n/**\n * Actions that {@link GeolocationApiService} exposes to other consumers.\n */\nexport type GeolocationApiServiceActions = GeolocationApiServiceMethodActions;\n\n/**\n * Actions from other messengers that {@link GeolocationApiServiceMessenger}\n * calls.\n */\ntype AllowedActions = never;\n\n/**\n * Events that {@link GeolocationApiService} exposes to other consumers.\n */\nexport type GeolocationApiServiceEvents = never;\n\n/**\n * Events from other messengers that {@link GeolocationApiService} subscribes\n * to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link GeolocationApiService}.\n */\nexport type GeolocationApiServiceMessenger = Messenger<\n  typeof serviceName,\n  GeolocationApiServiceActions | AllowedActions,\n  GeolocationApiServiceEvents | AllowedEvents\n>;\n\n// === SERVICE DEFINITION ===\n\n/**\n * Returns the base URL for the geolocation API for the given environment.\n *\n * Served by API Platform's `geolocation-api` service, not the legacy\n * Ramps-owned `on-ramp` endpoint this previously pointed to. API Platform has\n * not yet provisioned a dedicated UAT deployment for this service, so UAT\n * temporarily resolves to the production URL until one exists.\n *\n * @param env - The environment to get the URL for.\n * @returns The full URL for the geolocation endpoint.\n */\nfunction getGeolocationUrl(env: Env): string {\n  const envPrefix = env === Env.DEV ? 'dev-' : '';\n  return `https://geolocation.${envPrefix}api.cx.metamask.io${ENDPOINT_PATH}`;\n}\n\n/**\n * Options accepted by {@link GeolocationApiService.fetchGeolocation}.\n */\nexport type FetchGeolocationOptions = {\n  /** When true, the TTL cache is invalidated so the next request fetches fresh data. */\n  bypassCache?: boolean;\n};\n\n/**\n * Low-level data service that fetches a location code from the geolocation API.\n *\n * Responsibilities:\n * - HTTP request to the geolocation endpoint (wrapped in a service policy)\n * - ISO 3166-2 response validation (country code with optional subdivision,\n *   e.g. `US`, `US-NY`, `CA-ON`)\n * - TTL-based in-memory cache\n * - Promise deduplication (concurrent callers share a single in-flight request)\n *\n * This class is intentionally not a controller: it does not manage UI state.\n * Its {@link fetchGeolocation} method is automatically registered on the\n * messenger so that controllers and other packages can call it directly.\n */\nexport class GeolocationApiService {\n  /**\n   * The name of the service.\n   */\n  readonly name: typeof serviceName;\n\n  readonly #messenger: GeolocationApiServiceMessenger;\n\n  readonly #fetch: typeof globalThis.fetch;\n\n  readonly #url: string;\n\n  readonly #ttlMs: number;\n\n  /**\n   * The policy that wraps each HTTP request.\n   *\n   * @see {@link createServicePolicy}\n   */\n  readonly #policy: ServicePolicy;\n\n  #cachedLocation: string = UNKNOWN_LOCATION;\n\n  #lastFetchedAt: number | null = null;\n\n  #fetchPromise: Promise<string> | null = null;\n\n  /**\n   * Constructs a new {@link GeolocationApiService}.\n   *\n   * @param args - The constructor arguments.\n   * @param args.messenger - The messenger suited for this service.\n   * @param args.env - The environment to determine the correct API endpoint.\n   * Defaults to PRD.\n   * @param args.fetch - A function that can be used to make an HTTP request.\n   * Defaults to the global fetch.\n   * @param args.ttlMs - Cache TTL in milliseconds. Defaults to 5 minutes.\n   * @param args.policyOptions - Options to pass to `createServicePolicy`, which\n   * is used to wrap each request. See {@link CreateServicePolicyOptions}.\n   */\n  constructor({\n    messenger,\n    env = Env.PRD,\n    fetch: fetchFunction = globalThis.fetch,\n    ttlMs,\n    policyOptions = {},\n  }: {\n    messenger: GeolocationApiServiceMessenger;\n    env?: Env;\n    fetch?: typeof fetch;\n    ttlMs?: number;\n    policyOptions?: CreateServicePolicyOptions;\n  }) {\n    this.name = serviceName;\n    this.#messenger = messenger;\n    this.#url = getGeolocationUrl(env);\n    this.#fetch = fetchFunction;\n    this.#ttlMs = ttlMs ?? DEFAULT_TTL_MS;\n    this.#policy = createServicePolicy(policyOptions);\n\n    this.#messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Registers a handler that will be called after a request returns a 5xx\n   * response, causing a retry.\n   *\n   * @param listener - The handler to be called.\n   * @returns An object that can be used to unregister the handler.\n   * @see {@link createServicePolicy}\n   */\n  onRetry(listener: Parameters<ServicePolicy['onRetry']>[0]): IDisposable {\n    return this.#policy.onRetry(listener);\n  }\n\n  /**\n   * Registers a handler that will be called after a set number of retry rounds\n   * prove that requests to the API endpoint consistently return a 5xx response.\n   *\n   * @param listener - The handler to be called.\n   * @returns An object that can be used to unregister the handler.\n   * @see {@link createServicePolicy}\n   */\n  onBreak(listener: Parameters<ServicePolicy['onBreak']>[0]): IDisposable {\n    return this.#policy.onBreak(listener);\n  }\n\n  /**\n   * Registers a handler that will be called when requests are consistently\n   * failing or when a successful request takes longer than the degraded\n   * threshold.\n   *\n   * @param listener - The handler to be called.\n   * @returns An object that can be used to unregister the handler.\n   */\n  onDegraded(\n    listener: Parameters<ServicePolicy['onDegraded']>[0],\n  ): IDisposable {\n    return this.#policy.onDegraded(listener);\n  }\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   */\n  async fetchGeolocation(options?: FetchGeolocationOptions): Promise<string> {\n    if (options?.bypassCache) {\n      this.#lastFetchedAt = null;\n    }\n\n    if (this.#isCacheValid()) {\n      return this.#cachedLocation;\n    }\n\n    if (this.#fetchPromise) {\n      return this.#fetchPromise;\n    }\n\n    const promise = this.#performFetch();\n    this.#fetchPromise = promise;\n\n    try {\n      return await promise;\n    } finally {\n      this.#fetchPromise = null;\n    }\n  }\n\n  /**\n   * Checks whether the cached geolocation is still within the TTL window.\n   *\n   * @returns True if the cache is valid.\n   */\n  #isCacheValid(): boolean {\n    return (\n      this.#lastFetchedAt !== null &&\n      Date.now() - this.#lastFetchedAt < this.#ttlMs\n    );\n  }\n\n  /**\n   * Performs the actual HTTP fetch, wrapped in the service policy for automatic\n   * retry and circuit-breaking, and validates the response.\n   *\n   * @returns The ISO 3166-2 location code string.\n   */\n  async #performFetch(): Promise<string> {\n    const response = await this.#policy.execute(async () => {\n      const localResponse = await this.#fetch(this.#url);\n      if (!localResponse.ok) {\n        throw new HttpError(\n          localResponse.status,\n          `Geolocation fetch failed: ${localResponse.status}`,\n        );\n      }\n      return localResponse;\n    });\n\n    const raw = (await response.text()).trim();\n    const location = /^[A-Z]{2}(-[A-Z0-9]{1,3})?$/u.test(raw)\n      ? raw\n      : UNKNOWN_LOCATION;\n\n    if (location !== UNKNOWN_LOCATION) {\n      this.#cachedLocation = location;\n      this.#lastFetchedAt = Date.now();\n    }\n\n    return location;\n  }\n}\n"]}

package/dist/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UNKNOWN_LOCATION = exports.toLocationCode = exports.getUnknownGeolocationData = exports.GeolocationApiService = exports.getDefaultGeolocationControllerState = exports.GeolocationController = exports.Env = void 0;
+exports.UNKNOWN_LOCATION = exports.GeolocationApiService = exports.getDefaultGeolocationControllerState = exports.GeolocationController = exports.Env = void 0;
 var types_js_1 = require("./types.cjs");
 Object.defineProperty(exports, "Env", { enumerable: true, get: function () { return types_js_1.Env; } });
 var GeolocationController_js_1 = require("./GeolocationController.cjs");
@@ -8,7 +8,5 @@ Object.defineProperty(exports, "GeolocationController", { enumerable: true, get:
 Object.defineProperty(exports, "getDefaultGeolocationControllerState", { enumerable: true, get: function () { return GeolocationController_js_1.getDefaultGeolocationControllerState; } });
 var geolocation_api_service_js_1 = require("./geolocation-api-service/geolocation-api-service.cjs");
 Object.defineProperty(exports, "GeolocationApiService", { enumerable: true, get: function () { return geolocation_api_service_js_1.GeolocationApiService; } });
-Object.defineProperty(exports, "getUnknownGeolocationData", { enumerable: true, get: function () { return geolocation_api_service_js_1.getUnknownGeolocationData; } });
-Object.defineProperty(exports, "toLocationCode", { enumerable: true, get: function () { return geolocation_api_service_js_1.toLocationCode; } });
 Object.defineProperty(exports, "UNKNOWN_LOCATION", { enumerable: true, get: function () { return geolocation_api_service_js_1.UNKNOWN_LOCATION; } });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAeA,wCAAiC;AAAxB,+FAAA,GAAG,OAAA;AACZ,wEAGoC;AAFlC,iIAAA,qBAAqB,OAAA;AACrB,gJAAA,oCAAoC,OAAA;AAEtC,oGAK8D;AAJ5D,mIAAA,qBAAqB,OAAA;AACrB,uIAAA,yBAAyB,OAAA;AACzB,4HAAA,cAAc,OAAA;AACd,8HAAA,gBAAgB,OAAA","sourcesContent":["export type {\n  GeolocationControllerState,\n  GeolocationControllerGetStateAction,\n  GeolocationControllerActions,\n  GeolocationControllerStateChangeEvent,\n  GeolocationControllerEvents,\n  GeolocationControllerMessenger,\n  GeolocationControllerOptions,\n} from './GeolocationController.js';\nexport type {\n  GeolocationControllerGetGeolocationAction,\n  GeolocationControllerGetGeolocationDataAction,\n  GeolocationControllerRefreshGeolocationAction,\n} from './GeolocationController-method-action-types.js';\nexport type { GeolocationRequestStatus } from './types.js';\nexport { Env } from './types.js';\nexport {\n  GeolocationController,\n  getDefaultGeolocationControllerState,\n} from './GeolocationController.js';\nexport {\n  GeolocationApiService,\n  getUnknownGeolocationData,\n  toLocationCode,\n  UNKNOWN_LOCATION,\n} from './geolocation-api-service/geolocation-api-service.js';\nexport type {\n  GeolocationApiServiceMessenger,\n  GeolocationApiServiceActions,\n  GeolocationApiServiceEvents,\n  FetchGeolocationOptions,\n  GeolocationData,\n} from './geolocation-api-service/geolocation-api-service.js';\nexport type {\n  GeolocationApiServiceFetchGeolocationAction,\n  GeolocationApiServiceFetchGeolocationDataAction,\n} from './geolocation-api-service/geolocation-api-service-method-action-types.js';\n"]}
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAcA,wCAAiC;AAAxB,+FAAA,GAAG,OAAA;AACZ,wEAGoC;AAFlC,iIAAA,qBAAqB,OAAA;AACrB,gJAAA,oCAAoC,OAAA;AAEtC,oGAG8D;AAF5D,mIAAA,qBAAqB,OAAA;AACrB,8HAAA,gBAAgB,OAAA","sourcesContent":["export type {\n  GeolocationControllerState,\n  GeolocationControllerGetStateAction,\n  GeolocationControllerActions,\n  GeolocationControllerStateChangeEvent,\n  GeolocationControllerEvents,\n  GeolocationControllerMessenger,\n  GeolocationControllerOptions,\n} from './GeolocationController.js';\nexport type {\n  GeolocationControllerGetGeolocationAction,\n  GeolocationControllerRefreshGeolocationAction,\n} from './GeolocationController-method-action-types.js';\nexport type { GeolocationRequestStatus } from './types.js';\nexport { Env } from './types.js';\nexport {\n  GeolocationController,\n  getDefaultGeolocationControllerState,\n} from './GeolocationController.js';\nexport {\n  GeolocationApiService,\n  UNKNOWN_LOCATION,\n} from './geolocation-api-service/geolocation-api-service.js';\nexport type {\n  GeolocationApiServiceMessenger,\n  GeolocationApiServiceActions,\n  GeolocationApiServiceEvents,\n  FetchGeolocationOptions,\n} from './geolocation-api-service/geolocation-api-service.js';\nexport type { GeolocationApiServiceFetchGeolocationAction } from './geolocation-api-service/geolocation-api-service-method-action-types.js';\n"]}

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 export type { GeolocationControllerState, GeolocationControllerGetStateAction, GeolocationControllerActions, GeolocationControllerStateChangeEvent, GeolocationControllerEvents, GeolocationControllerMessenger, GeolocationControllerOptions, } from "./GeolocationController.cjs";
-export type { GeolocationControllerGetGeolocationAction, GeolocationControllerGetGeolocationDataAction, GeolocationControllerRefreshGeolocationAction, } from "./GeolocationController-method-action-types.cjs";
+export type { GeolocationControllerGetGeolocationAction, GeolocationControllerRefreshGeolocationAction, } from "./GeolocationController-method-action-types.cjs";
 export type { GeolocationRequestStatus } from "./types.cjs";
 export { Env } from "./types.cjs";
 export { GeolocationController, getDefaultGeolocationControllerState, } from "./GeolocationController.cjs";
-export { GeolocationApiService, getUnknownGeolocationData, toLocationCode, UNKNOWN_LOCATION, } from "./geolocation-api-service/geolocation-api-service.cjs";
-export type { GeolocationApiServiceMessenger, GeolocationApiServiceActions, GeolocationApiServiceEvents, FetchGeolocationOptions, GeolocationData, } from "./geolocation-api-service/geolocation-api-service.cjs";
-export type { GeolocationApiServiceFetchGeolocationAction, GeolocationApiServiceFetchGeolocationDataAction, } from "./geolocation-api-service/geolocation-api-service-method-action-types.cjs";
+export { GeolocationApiService, UNKNOWN_LOCATION, } from "./geolocation-api-service/geolocation-api-service.cjs";
+export type { GeolocationApiServiceMessenger, GeolocationApiServiceActions, GeolocationApiServiceEvents, FetchGeolocationOptions, } from "./geolocation-api-service/geolocation-api-service.cjs";
+export type { GeolocationApiServiceFetchGeolocationAction } from "./geolocation-api-service/geolocation-api-service-method-action-types.cjs";
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,0BAA0B,EAC1B,mCAAmC,EACnC,4BAA4B,EAC5B,qCAAqC,EACrC,2BAA2B,EAC3B,8BAA8B,EAC9B,4BAA4B,GAC7B,oCAAmC;AACpC,YAAY,EACV,yCAAyC,EACzC,6CAA6C,EAC7C,6CAA6C,GAC9C,wDAAuD;AACxD,YAAY,EAAE,wBAAwB,EAAE,oBAAmB;AAC3D,OAAO,EAAE,GAAG,EAAE,oBAAmB;AACjC,OAAO,EACL,qBAAqB,EACrB,oCAAoC,GACrC,oCAAmC;AACpC,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,GACjB,8DAA6D;AAC9D,YAAY,EACV,8BAA8B,EAC9B,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,EACvB,eAAe,GAChB,8DAA6D;AAC9D,YAAY,EACV,2CAA2C,EAC3C,+CAA+C,GAChD,kFAAiF"}
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,0BAA0B,EAC1B,mCAAmC,EACnC,4BAA4B,EAC5B,qCAAqC,EACrC,2BAA2B,EAC3B,8BAA8B,EAC9B,4BAA4B,GAC7B,oCAAmC;AACpC,YAAY,EACV,yCAAyC,EACzC,6CAA6C,GAC9C,wDAAuD;AACxD,YAAY,EAAE,wBAAwB,EAAE,oBAAmB;AAC3D,OAAO,EAAE,GAAG,EAAE,oBAAmB;AACjC,OAAO,EACL,qBAAqB,EACrB,oCAAoC,GACrC,oCAAmC;AACpC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GACjB,8DAA6D;AAC9D,YAAY,EACV,8BAA8B,EAC9B,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,GACxB,8DAA6D;AAC9D,YAAY,EAAE,2CAA2C,EAAE,kFAAiF"}

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 export type { GeolocationControllerState, GeolocationControllerGetStateAction, GeolocationControllerActions, GeolocationControllerStateChangeEvent, GeolocationControllerEvents, GeolocationControllerMessenger, GeolocationControllerOptions, } from "./GeolocationController.mjs";
-export type { GeolocationControllerGetGeolocationAction, GeolocationControllerGetGeolocationDataAction, GeolocationControllerRefreshGeolocationAction, } from "./GeolocationController-method-action-types.mjs";
+export type { GeolocationControllerGetGeolocationAction, GeolocationControllerRefreshGeolocationAction, } from "./GeolocationController-method-action-types.mjs";
 export type { GeolocationRequestStatus } from "./types.mjs";
 export { Env } from "./types.mjs";
 export { GeolocationController, getDefaultGeolocationControllerState, } from "./GeolocationController.mjs";
-export { GeolocationApiService, getUnknownGeolocationData, toLocationCode, UNKNOWN_LOCATION, } from "./geolocation-api-service/geolocation-api-service.mjs";
-export type { GeolocationApiServiceMessenger, GeolocationApiServiceActions, GeolocationApiServiceEvents, FetchGeolocationOptions, GeolocationData, } from "./geolocation-api-service/geolocation-api-service.mjs";
-export type { GeolocationApiServiceFetchGeolocationAction, GeolocationApiServiceFetchGeolocationDataAction, } from "./geolocation-api-service/geolocation-api-service-method-action-types.mjs";
+export { GeolocationApiService, UNKNOWN_LOCATION, } from "./geolocation-api-service/geolocation-api-service.mjs";
+export type { GeolocationApiServiceMessenger, GeolocationApiServiceActions, GeolocationApiServiceEvents, FetchGeolocationOptions, } from "./geolocation-api-service/geolocation-api-service.mjs";
+export type { GeolocationApiServiceFetchGeolocationAction } from "./geolocation-api-service/geolocation-api-service-method-action-types.mjs";
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,0BAA0B,EAC1B,mCAAmC,EACnC,4BAA4B,EAC5B,qCAAqC,EACrC,2BAA2B,EAC3B,8BAA8B,EAC9B,4BAA4B,GAC7B,oCAAmC;AACpC,YAAY,EACV,yCAAyC,EACzC,6CAA6C,EAC7C,6CAA6C,GAC9C,wDAAuD;AACxD,YAAY,EAAE,wBAAwB,EAAE,oBAAmB;AAC3D,OAAO,EAAE,GAAG,EAAE,oBAAmB;AACjC,OAAO,EACL,qBAAqB,EACrB,oCAAoC,GACrC,oCAAmC;AACpC,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,GACjB,8DAA6D;AAC9D,YAAY,EACV,8BAA8B,EAC9B,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,EACvB,eAAe,GAChB,8DAA6D;AAC9D,YAAY,EACV,2CAA2C,EAC3C,+CAA+C,GAChD,kFAAiF"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,0BAA0B,EAC1B,mCAAmC,EACnC,4BAA4B,EAC5B,qCAAqC,EACrC,2BAA2B,EAC3B,8BAA8B,EAC9B,4BAA4B,GAC7B,oCAAmC;AACpC,YAAY,EACV,yCAAyC,EACzC,6CAA6C,GAC9C,wDAAuD;AACxD,YAAY,EAAE,wBAAwB,EAAE,oBAAmB;AAC3D,OAAO,EAAE,GAAG,EAAE,oBAAmB;AACjC,OAAO,EACL,qBAAqB,EACrB,oCAAoC,GACrC,oCAAmC;AACpC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GACjB,8DAA6D;AAC9D,YAAY,EACV,8BAA8B,EAC9B,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,GACxB,8DAA6D;AAC9D,YAAY,EAAE,2CAA2C,EAAE,kFAAiF"}

package/dist/index.mjs

@@ -1,4 +1,4 @@
 export { Env } from "./types.mjs";
 export { GeolocationController, getDefaultGeolocationControllerState } from "./GeolocationController.mjs";
-export { GeolocationApiService, getUnknownGeolocationData, toLocationCode, UNKNOWN_LOCATION } from "./geolocation-api-service/geolocation-api-service.mjs";
+export { GeolocationApiService, UNKNOWN_LOCATION } from "./geolocation-api-service/geolocation-api-service.mjs";
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,GAAG,EAAE,oBAAmB;AACjC,OAAO,EACL,qBAAqB,EACrB,oCAAoC,EACrC,oCAAmC;AACpC,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EACjB,8DAA6D","sourcesContent":["export type {\n  GeolocationControllerState,\n  GeolocationControllerGetStateAction,\n  GeolocationControllerActions,\n  GeolocationControllerStateChangeEvent,\n  GeolocationControllerEvents,\n  GeolocationControllerMessenger,\n  GeolocationControllerOptions,\n} from './GeolocationController.js';\nexport type {\n  GeolocationControllerGetGeolocationAction,\n  GeolocationControllerGetGeolocationDataAction,\n  GeolocationControllerRefreshGeolocationAction,\n} from './GeolocationController-method-action-types.js';\nexport type { GeolocationRequestStatus } from './types.js';\nexport { Env } from './types.js';\nexport {\n  GeolocationController,\n  getDefaultGeolocationControllerState,\n} from './GeolocationController.js';\nexport {\n  GeolocationApiService,\n  getUnknownGeolocationData,\n  toLocationCode,\n  UNKNOWN_LOCATION,\n} from './geolocation-api-service/geolocation-api-service.js';\nexport type {\n  GeolocationApiServiceMessenger,\n  GeolocationApiServiceActions,\n  GeolocationApiServiceEvents,\n  FetchGeolocationOptions,\n  GeolocationData,\n} from './geolocation-api-service/geolocation-api-service.js';\nexport type {\n  GeolocationApiServiceFetchGeolocationAction,\n  GeolocationApiServiceFetchGeolocationDataAction,\n} from './geolocation-api-service/geolocation-api-service-method-action-types.js';\n"]}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,GAAG,EAAE,oBAAmB;AACjC,OAAO,EACL,qBAAqB,EACrB,oCAAoC,EACrC,oCAAmC;AACpC,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EACjB,8DAA6D","sourcesContent":["export type {\n  GeolocationControllerState,\n  GeolocationControllerGetStateAction,\n  GeolocationControllerActions,\n  GeolocationControllerStateChangeEvent,\n  GeolocationControllerEvents,\n  GeolocationControllerMessenger,\n  GeolocationControllerOptions,\n} from './GeolocationController.js';\nexport type {\n  GeolocationControllerGetGeolocationAction,\n  GeolocationControllerRefreshGeolocationAction,\n} from './GeolocationController-method-action-types.js';\nexport type { GeolocationRequestStatus } from './types.js';\nexport { Env } from './types.js';\nexport {\n  GeolocationController,\n  getDefaultGeolocationControllerState,\n} from './GeolocationController.js';\nexport {\n  GeolocationApiService,\n  UNKNOWN_LOCATION,\n} from './geolocation-api-service/geolocation-api-service.js';\nexport type {\n  GeolocationApiServiceMessenger,\n  GeolocationApiServiceActions,\n  GeolocationApiServiceEvents,\n  FetchGeolocationOptions,\n} from './geolocation-api-service/geolocation-api-service.js';\nexport type { GeolocationApiServiceFetchGeolocationAction } from './geolocation-api-service/geolocation-api-service-method-action-types.js';\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamask-previews/geolocation-controller",
-  "version": "0.1.3-preview-d67bfdbad",
+  "version": "0.1.3-preview-937b1a1",
   "description": "Centralised geolocation controller with TTL caching and request deduplication",
   "keywords": [
     "Ethereum",