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

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

@@ -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.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"geolocation-api-service-method-action-types.d.mts","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.mts","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"}

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

@@ -1 +1 @@
-{"version":3,"file":"geolocation-api-service-method-action-types.mjs","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.mjs","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.cjs

@@ -10,13 +10,16 @@ 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_cachedLocation, _GeolocationApiService_lastFetchedAt, _GeolocationApiService_fetchPromise, _GeolocationApiService_isCacheValid, _GeolocationApiService_performFetch;
+var _GeolocationApiService_instances, _GeolocationApiService_messenger, _GeolocationApiService_fetch, _GeolocationApiService_url, _GeolocationApiService_ttlMs, _GeolocationApiService_policy, _GeolocationApiService_cachedGeolocation, _GeolocationApiService_lastFetchedAt, _GeolocationApiService_fetchPromise, _GeolocationApiService_isCacheValid, _GeolocationApiService_performFetch;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GeolocationApiService = exports.UNKNOWN_LOCATION = exports.serviceName = void 0;
+exports.GeolocationApiService = exports.toLocationCode = exports.getUnknownGeolocationData = exports.UNKNOWN_LOCATION = exports.serviceName = void 0;
 const controller_utils_1 = require("@metamask/controller-utils");
 const types_js_1 = require("../types.cjs");
 const DEFAULT_TTL_MS = 5 * 60 * 1000;
-const ENDPOINT_PATH = '/v1/geolocation';
+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;
 // === GENERAL ===
 /**
  * The name of the {@link GeolocationApiService}, used to namespace the
@@ -28,8 +31,49 @@ exports.serviceName = 'GeolocationApiService';
  * the API returns an empty / invalid response.
  */
 exports.UNKNOWN_LOCATION = 'UNKNOWN';
+/**
+ * Constructs a {@link GeolocationData} with no known fields.
+ *
+ * @returns Geolocation data where every field is `null`.
+ */
+function getUnknownGeolocationData() {
+    return { country: null, region: null, timezone: null };
+}
+exports.getUnknownGeolocationData = getUnknownGeolocationData;
+/**
+ * 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.
+ */
+function toLocationCode(data) {
+    if (data.country === null) {
+        return exports.UNKNOWN_LOCATION;
+    }
+    if (data.region !== null && REGION_APPENDED_COUNTRIES.has(data.country)) {
+        return `${data.country}-${data.region}`;
+    }
+    return data.country;
+}
+exports.toLocationCode = toLocationCode;
 // === MESSENGER ===
-const MESSENGER_EXPOSED_METHODS = ['fetchGeolocation'];
+const MESSENGER_EXPOSED_METHODS = [
+    'fetchGeolocation',
+    'fetchGeolocationData',
+];
 // === SERVICE DEFINITION ===
 /**
  * Returns the base URL for the geolocation API for the given environment.
@@ -47,18 +91,66 @@ function getGeolocationUrl(env) {
     return `https://geolocation.${envPrefix}api.cx.metamask.io${ENDPOINT_PATH}`;
 }
 /**
- * Low-level data service that fetches a location code from the geolocation API.
+ * 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.
  *
  * Responsibilities:
  * - HTTP request to the geolocation endpoint (wrapped in a service policy)
- * - ISO 3166-2 response validation (country code with optional subdivision,
- *   e.g. `US`, `US-NY`, `CA-ON`)
+ * - Response validation of the country, region, and timezone fields
  * - 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} method is automatically registered on the
- * messenger so that controllers and other packages can call it directly.
+ * Its {@link fetchGeolocation} and {@link fetchGeolocationData} methods are
+ * automatically registered on the messenger so that controllers and other
+ * packages can call them directly.
  */
 class GeolocationApiService {
     /**
@@ -86,7 +178,7 @@ class GeolocationApiService {
          * @see {@link createServicePolicy}
          */
         _GeolocationApiService_policy.set(this, void 0);
-        _GeolocationApiService_cachedLocation.set(this, exports.UNKNOWN_LOCATION);
+        _GeolocationApiService_cachedGeolocation.set(this, getUnknownGeolocationData());
         _GeolocationApiService_lastFetchedAt.set(this, null);
         _GeolocationApiService_fetchPromise.set(this, null);
         this.name = exports.serviceName;
@@ -143,11 +235,26 @@ 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_cachedLocation, "f");
+            return __classPrivateFieldGet(this, _GeolocationApiService_cachedGeolocation, "f");
         }
         if (__classPrivateFieldGet(this, _GeolocationApiService_fetchPromise, "f")) {
             return __classPrivateFieldGet(this, _GeolocationApiService_fetchPromise, "f");
@@ -163,7 +270,7 @@ class GeolocationApiService {
     }
 }
 exports.GeolocationApiService = GeolocationApiService;
-_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() {
+_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() {
     return (__classPrivateFieldGet(this, _GeolocationApiService_lastFetchedAt, "f") !== null &&
         Date.now() - __classPrivateFieldGet(this, _GeolocationApiService_lastFetchedAt, "f") < __classPrivateFieldGet(this, _GeolocationApiService_ttlMs, "f"));
 }, _GeolocationApiService_performFetch = 
@@ -171,7 +278,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 ISO 3166-2 location code string.
+ * @returns The validated geolocation data.
  */
 async function _GeolocationApiService_performFetch() {
     const response = await __classPrivateFieldGet(this, _GeolocationApiService_policy, "f").execute(async () => {
@@ -181,14 +288,11 @@ async function _GeolocationApiService_performFetch() {
         }
         return localResponse;
     });
-    const raw = (await response.text()).trim();
-    const location = /^[A-Z]{2}(-[A-Z0-9]{1,3})?$/u.test(raw)
-        ? raw
-        : exports.UNKNOWN_LOCATION;
-    if (location !== exports.UNKNOWN_LOCATION) {
-        __classPrivateFieldSet(this, _GeolocationApiService_cachedLocation, location, "f");
+    const geolocation = parseGeolocationResponse((await response.text()).trim());
+    if (geolocation.country !== null) {
+        __classPrivateFieldSet(this, _GeolocationApiService_cachedGeolocation, geolocation, "f");
         __classPrivateFieldSet(this, _GeolocationApiService_lastFetchedAt, Date.now(), "f");
     }
-    return location;
+    return geolocation;
 };
 //# sourceMappingURL=geolocation-api-service.cjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"geolocation-api-service.cjs","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"]}
+{"version":3,"file":"geolocation-api-service.cjs","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    if (geolocation.country !== null) {\n      this.#cachedGeolocation = geolocation;\n      this.#lastFetchedAt = Date.now();\n    }\n\n    return geolocation;\n  }\n}\n"]}

package/dist/geolocation-api-service/geolocation-api-service.d.cts

@@ -13,6 +13,39 @@ export declare const serviceName = "GeolocationApiService";
  * the API returns an empty / invalid response.
  */
 export declare const UNKNOWN_LOCATION = "UNKNOWN";
+/**
+ * Geolocation details returned by the geolocation API.
+ *
+ * Each field is `null` when the API omits it or returns a value that fails
+ * validation.
+ */
+export type GeolocationData = {
+    /** ISO 3166-1 alpha-2 country code (e.g. `US`, `FR`). */
+    country: string | null;
+    /** ISO 3166-2 subdivision code without the country prefix (e.g. `WA`). */
+    region: string | null;
+    /** IANA time zone name (e.g. `America/Los_Angeles`). */
+    timezone: string | null;
+};
+/**
+ * Constructs a {@link GeolocationData} with no known fields.
+ *
+ * @returns Geolocation data where every field is `null`.
+ */
+export declare function getUnknownGeolocationData(): GeolocationData;
+/**
+ * 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 declare function toLocationCode(data: GeolocationData): string;
 /**
  * Actions that {@link GeolocationApiService} exposes to other consumers.
  */
@@ -44,18 +77,19 @@ export type FetchGeolocationOptions = {
     bypassCache?: boolean;
 };
 /**
- * Low-level data service that fetches a location code from the geolocation API.
+ * Low-level data service that fetches geolocation details from the geolocation
+ * API.
  *
  * Responsibilities:
  * - HTTP request to the geolocation endpoint (wrapped in a service policy)
- * - ISO 3166-2 response validation (country code with optional subdivision,
- *   e.g. `US`, `US-NY`, `CA-ON`)
+ * - Response validation of the country, region, and timezone fields
  * - 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} method is automatically registered on the
- * messenger so that controllers and other packages can call it directly.
+ * Its {@link fetchGeolocation} and {@link fetchGeolocationData} methods are
+ * automatically registered on the messenger so that controllers and other
+ * packages can call them directly.
  */
 export declare class GeolocationApiService {
     #private;
@@ -123,6 +157,19 @@ export declare class GeolocationApiService {
      * {@link UNKNOWN_LOCATION} when the API returns an empty or invalid body.
      */
     fetchGeolocation(options?: FetchGeolocationOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    fetchGeolocationData(options?: FetchGeolocationOptions): Promise<GeolocationData>;
 }
 export {};
 //# sourceMappingURL=geolocation-api-service.d.cts.map

package/dist/geolocation-api-service/geolocation-api-service.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"geolocation-api-service.d.cts","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EACd,mCAAmC;AAEpC,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB;AAE7C,OAAO,EAAE,GAAG,EAAE,qBAAoB;AAClC,OAAO,KAAK,EAAE,kCAAkC,EAAE,0DAAyD;AAQ3G;;;GAGG;AACH,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAM1C;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,kCAAkC,CAAC;AAE9E;;;GAGG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEhD;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CACpD,OAAO,WAAW,EAClB,4BAA4B,GAAG,cAAc,EAC7C,2BAA2B,GAAG,aAAa,CAC5C,CAAC;AAoBF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAqB;;IAChC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,WAAW,CAAC;IAuBlC;;;;;;;;;;;;OAYG;gBACS,EACV,SAAS,EACT,GAAa,EACb,KAAK,EAAE,aAAgC,EACvC,KAAK,EACL,aAAkB,GACnB,EAAE;QACD,SAAS,EAAE,8BAA8B,CAAC;QAC1C,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,0BAA0B,CAAC;KAC5C;IAcD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAIvE;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAIvE;;;;;;;OAOG;IACH,UAAU,CACR,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GACnD,WAAW;IAId;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;CAiE3E"}
+{"version":3,"file":"geolocation-api-service.d.cts","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EACd,mCAAmC;AAEpC,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB;AAE7C,OAAO,EAAE,GAAG,EAAE,qBAAoB;AAClC,OAAO,KAAK,EAAE,kCAAkC,EAAE,0DAAyD;AAc3G;;;GAGG;AACH,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,yDAAyD;IACzD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,eAAe,CAE3D;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAU5D;AASD;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,kCAAkC,CAAC;AAE9E;;;GAGG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEhD;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CACpD,OAAO,WAAW,EAClB,4BAA4B,GAAG,cAAc,EAC7C,2BAA2B,GAAG,aAAa,CAC5C,CAAC;AA+EF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,qBAAqB;;IAChC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,WAAW,CAAC;IAuBlC;;;;;;;;;;;;OAYG;gBACS,EACV,SAAS,EACT,GAAa,EACb,KAAK,EAAE,aAAgC,EACvC,KAAK,EACL,aAAkB,GACnB,EAAE;QACD,SAAS,EAAE,8BAA8B,CAAC;QAC1C,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,0BAA0B,CAAC;KAC5C;IAcD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAIvE;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAIvE;;;;;;;OAOG;IACH,UAAU,CACR,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GACnD,WAAW;IAId;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1E;;;;;;;;;;;OAWG;IACG,oBAAoB,CACxB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,eAAe,CAAC;CAgE5B"}

package/dist/geolocation-api-service/geolocation-api-service.d.mts

@@ -13,6 +13,39 @@ export declare const serviceName = "GeolocationApiService";
  * the API returns an empty / invalid response.
  */
 export declare const UNKNOWN_LOCATION = "UNKNOWN";
+/**
+ * Geolocation details returned by the geolocation API.
+ *
+ * Each field is `null` when the API omits it or returns a value that fails
+ * validation.
+ */
+export type GeolocationData = {
+    /** ISO 3166-1 alpha-2 country code (e.g. `US`, `FR`). */
+    country: string | null;
+    /** ISO 3166-2 subdivision code without the country prefix (e.g. `WA`). */
+    region: string | null;
+    /** IANA time zone name (e.g. `America/Los_Angeles`). */
+    timezone: string | null;
+};
+/**
+ * Constructs a {@link GeolocationData} with no known fields.
+ *
+ * @returns Geolocation data where every field is `null`.
+ */
+export declare function getUnknownGeolocationData(): GeolocationData;
+/**
+ * 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 declare function toLocationCode(data: GeolocationData): string;
 /**
  * Actions that {@link GeolocationApiService} exposes to other consumers.
  */
@@ -44,18 +77,19 @@ export type FetchGeolocationOptions = {
     bypassCache?: boolean;
 };
 /**
- * Low-level data service that fetches a location code from the geolocation API.
+ * Low-level data service that fetches geolocation details from the geolocation
+ * API.
  *
  * Responsibilities:
  * - HTTP request to the geolocation endpoint (wrapped in a service policy)
- * - ISO 3166-2 response validation (country code with optional subdivision,
- *   e.g. `US`, `US-NY`, `CA-ON`)
+ * - Response validation of the country, region, and timezone fields
  * - 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} method is automatically registered on the
- * messenger so that controllers and other packages can call it directly.
+ * Its {@link fetchGeolocation} and {@link fetchGeolocationData} methods are
+ * automatically registered on the messenger so that controllers and other
+ * packages can call them directly.
  */
 export declare class GeolocationApiService {
     #private;
@@ -123,6 +157,19 @@ export declare class GeolocationApiService {
      * {@link UNKNOWN_LOCATION} when the API returns an empty or invalid body.
      */
     fetchGeolocation(options?: FetchGeolocationOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    fetchGeolocationData(options?: FetchGeolocationOptions): Promise<GeolocationData>;
 }
 export {};
 //# sourceMappingURL=geolocation-api-service.d.mts.map

package/dist/geolocation-api-service/geolocation-api-service.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"geolocation-api-service.d.mts","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EACd,mCAAmC;AAEpC,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB;AAE7C,OAAO,EAAE,GAAG,EAAE,qBAAoB;AAClC,OAAO,KAAK,EAAE,kCAAkC,EAAE,0DAAyD;AAQ3G;;;GAGG;AACH,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAM1C;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,kCAAkC,CAAC;AAE9E;;;GAGG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEhD;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CACpD,OAAO,WAAW,EAClB,4BAA4B,GAAG,cAAc,EAC7C,2BAA2B,GAAG,aAAa,CAC5C,CAAC;AAoBF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAqB;;IAChC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,WAAW,CAAC;IAuBlC;;;;;;;;;;;;OAYG;gBACS,EACV,SAAS,EACT,GAAa,EACb,KAAK,EAAE,aAAgC,EACvC,KAAK,EACL,aAAkB,GACnB,EAAE;QACD,SAAS,EAAE,8BAA8B,CAAC;QAC1C,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,0BAA0B,CAAC;KAC5C;IAcD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAIvE;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAIvE;;;;;;;OAOG;IACH,UAAU,CACR,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GACnD,WAAW;IAId;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;CAiE3E"}
+{"version":3,"file":"geolocation-api-service.d.mts","sourceRoot":"","sources":["../../src/geolocation-api-service/geolocation-api-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EACd,mCAAmC;AAEpC,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB;AAE7C,OAAO,EAAE,GAAG,EAAE,qBAAoB;AAClC,OAAO,KAAK,EAAE,kCAAkC,EAAE,0DAAyD;AAc3G;;;GAGG;AACH,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,yDAAyD;IACzD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,eAAe,CAE3D;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAU5D;AASD;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,kCAAkC,CAAC;AAE9E;;;GAGG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEhD;;;GAGG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,CACpD,OAAO,WAAW,EAClB,4BAA4B,GAAG,cAAc,EAC7C,2BAA2B,GAAG,aAAa,CAC5C,CAAC;AA+EF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,qBAAqB;;IAChC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,WAAW,CAAC;IAuBlC;;;;;;;;;;;;OAYG;gBACS,EACV,SAAS,EACT,GAAa,EACb,KAAK,EAAE,aAAgC,EACvC,KAAK,EACL,aAAkB,GACnB,EAAE;QACD,SAAS,EAAE,8BAA8B,CAAC;QAC1C,GAAG,CAAC,EAAE,GAAG,CAAC;QACV,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,0BAA0B,CAAC;KAC5C;IAcD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAIvE;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAIvE;;;;;;;OAOG;IACH,UAAU,CACR,QAAQ,EAAE,UAAU,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,GACnD,WAAW;IAId;;;;;;;;;;;OAWG;IACG,gBAAgB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1E;;;;;;;;;;;OAWG;IACG,oBAAoB,CACxB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,eAAe,CAAC;CAgE5B"}