@fullstory/browser 2.1.0 → 2.1.1

package/README.md

@@ -73,8 +73,8 @@ The only required option is `orgId`, all others are optional.
 
 *  `orgId` -  Sets your Fullstory Org Id. Find out how to get your Org Id [here](https://help.fullstory.com/hc/en-us/articles/360047075853).
 *  `debug` - When set to `true`, enables Fullstory debug messages; defaults to `false`.
-*  `host` - The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`.
-*  `script` - Fullstory script host domain. Fullstory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com`.
+*  `host` - The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`, or to the region-specific equivalent (e.g. `eu1.fullstory.com`) when your `orgId` carries a region suffix.
+*  `script` - Fullstory script host domain. Fullstory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com/s/fs.js`, or to the region-specific equivalent (e.g. `edge.eu1.fullstory.com/s/fs.js`) when your `orgId` carries a region suffix.
 * `namespace` - Sets the global identifier for Fullstory when conflicts with `FS` arise; see [help](https://help.fullstory.com/hc/en-us/articles/360020624694-What-if-the-identifier-FS-is-used-by-another-script-on-my-site-).
 * `cookieDomain` - Overrides the cookie domain. By default, cookies will be valid for all subdomains of your site; if you want to limit the cookies to a specific subdomain, you can set the domain value explicitly. More information can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622874-Can-the-Fullstory-cookie-be-associated-with-a-specific-subdomain-).
 * `recordCrossDomainIFrames` - Defaults to `false`. Fullstory can record cross-domain iFrames if: 1. The Fullstory Browser SDK is running in the cross-domain iFrame and 2. `recordCrossDomainIFrames` is set to `true` in the cross-domain iFrame and 3. The Fullstory Browser SDK is running in the parent page of the cross-domain iFrame. Click [here](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) for a detailed explanation of what "cross-domain" means. Before using, you should understand the security implications, and configure your [Content Security Policy](https://www.html5rocks.com/en/tutorials/security/content-security-policy/) (CSP) HTTP headers accordingly - specifically the frame-ancestors directive. Failure to configure your CSP headers while using this setting can bypass IFrames security protections that are included in modern browsers. More information about cross-domain iFrame recording can be found on our [Knowledge Base](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-Fullstory-capture-content-that-is-presented-in-iframes-#2-the-outer-page-is-running-fullstory-and-you-have-iframes-runni). Note: the `recordCrossDomainIFrames` parameter is the same as the `window['_fs_run_in_iframe']` referenced in the KB article.
@@ -84,6 +84,17 @@ The only required option is `orgId`, all others are optional.
 * `assetMapId` - Use this to set the current asset map id. See [Asset Uploading for Web](https://help.fullstory.com/hc/en-us/articles/4404129191575-Asset-Uploading-for-Web) for more information.
 * `appHost` - Use this to set the app host for displaying session urls. If using a version of [Fullstory Relay](https://help.fullstory.com/hc/en-us/articles/360046112593-How-to-send-captured-traffic-to-your-First-Party-Domain-using-Fullstory-Relay), you may need to set `appHost` "app.fullstory.com" or "app.eu1.fullstory.com" depending on your region.
 
+### Data center regions
+
+Your `orgId` encodes the data center your org lives in — for example the `eu1` in `o-ABC123-eu1`. The SDK reads that suffix and points `host`, `script` and `appHost` at the matching region, so an org outside the default (`na1`) data center does not need to configure anything beyond `orgId`:
+
+```javascript
+FullStory.init({ orgId: 'o-ABC123-eu1' });
+// loads https://edge.eu1.fullstory.com/s/fs.js and records to eu1.fullstory.com
+```
+
+The region is applied to any of those three options that resolve to a Fullstory-owned domain, **including values you pass explicitly** — so `host: "fullstory.com"` on an `eu1` org becomes `eu1.fullstory.com` rather than silently recording to the wrong data center. Hosts Fullstory does not own, such as a proxy or Fullstory Relay domain of your own, are always used exactly as you provide them.
+
 ### Ready Callback
 
 The `init` function also accepts an optional `readyCallback` argument. If you provide a function, it will be invoked when the Fullstory session has started. Your callback will be called with one parameter: an object containing information about the session. Currently the only property is `sessionUrl`, which is a string containing the URL to the session.

package/dist/hosts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Region resolution for the Fullstory host/script options.
+ *
+ * `fs.js` derives an org's region by parsing the locale suffix off its orgId (see
+ * `orgLocale()` / `fullstoryHost()` in the monorepo's `packages/recording/src/fsglobals.ts`),
+ * but that only runs once `fs.js` has already loaded — far too late to fix the URL that
+ * fetched it. So the same resolution has to happen here, before the snippet injects its
+ * `<script>` tag, or an EU org that sets nothing but `orgId` fetches `fs.js` and its
+ * settings from the na1 edge, which does not serve that org (VAL-10545).
+ */
+/**
+ * The `host` / `script` defaults applied by `@fullstory/snippet`. Duplicated here because
+ * the package does not export them, and we need the default value in hand to regionalize
+ * it. Keep in sync with the defaults in that package's `initFS` / `executeSnippet` when
+ * upgrading the dependency.
+ */
+export declare const DEFAULT_HOST = "fullstory.com";
+export declare const DEFAULT_SCRIPT = "edge.fullstory.com/s/fs.js";
+/**
+ * Parses the region/locale suffix out of an orgId, e.g. "o-7Y9H-eu1" -> "eu1". Returns
+ * `undefined` for na1 and for orgIds that carry no region, meaning "apply no region".
+ * Mirrors `orgLocale()` in the monorepo's `packages/recording/src/fsglobals.ts`.
+ */
+export declare const orgLocale: (orgId?: string) => string | undefined;
+/**
+ * Applies an org's region to a Fullstory-owned host, inserting the locale as the label
+ * immediately before the registrable domain and preserving any path:
+ *
+ *   ("fullstory.com", "eu1")               -> "eu1.fullstory.com"
+ *   ("edge.fullstory.com/s/fs.js", "eu1")  -> "edge.eu1.fullstory.com/s/fs.js"
+ *
+ * Hosts Fullstory does not own — self-hosted proxies, Relay, localhost — are returned
+ * untouched, as are hosts already carrying the right region (so this is idempotent and
+ * safe to stack with the same resolution in `fs.js`).
+ */
+export declare const regionalize: (value: string, locale?: string) => string;

package/dist/index.d.ts

@@ -5,13 +5,17 @@ import { FSApi } from '@fullstory/snippet';
  * - orgId: Reference for your [Org Id](https://help.fullstory.com/hc/en-us/articles/360047075853) listed in FullStory.
  * - namespace: Global object name that contains the FullStory browser API methods and properties. Defaults to `FS`.
  * - debug: Debug mode with extra browser console logging.
- * - host: The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`.
- * - script: FullStory script host domain. FullStory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com`.
+ * - host: The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`, or the region-specific equivalent (e.g. `eu1.fullstory.com`) when `orgId` carries a region suffix.
+ * - script: FullStory script host domain. FullStory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com/s/fs.js`, or the region-specific equivalent (e.g. `edge.eu1.fullstory.com/s/fs.js`) when `orgId` carries a region suffix.
  * - cookieDomain: Overrides the cookie domain. By default, cookies will be valid for all subdomains of your site; if you want to limit the cookies to a specific subdomain, you can set the domain value explicitly. More information can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622874-Can-the-FullStory-cookie-be-associated-with-a-specific-subdomain-).
  * - recordCrossDomainIFrames: FullStory can record cross-domain iFrames. Defaults to `false`. Certain limitations apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G333PYKPGZ4B42WDBV3YKV).
  * - recordOnlyThisIFrame: FullStory can record the iFrame as its own unique session. Defaults to `false`. Additional conditions apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G33B40Q2TPQA8MA7SF8Y5P).
  * - devMode: In dev mode FullStory won't record sessions. Any calls to SDK methods will `console.warn` that FullStory is in `devMode`. Defaults to `false`.
  * - sessionUid (beta): Sets the session UID passed to the `FS('init', ...)` v2 operation.
+ *
+ * The region encoded in `orgId` (e.g. the `eu1` in `o-ABC123-eu1`) is applied to `host`, `script` and `appHost`
+ * whenever those resolve to a FullStory-owned domain, including values you set explicitly. Hosts FullStory does
+ * not own — a proxy or Relay domain of your own — are always used exactly as given.
  */
 export interface SnippetOptions {
     orgId: string;

package/dist/index.esm.js

@@ -33,6 +33,89 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * Region resolution for the Fullstory host/script options.
+ *
+ * `fs.js` derives an org's region by parsing the locale suffix off its orgId (see
+ * `orgLocale()` / `fullstoryHost()` in the monorepo's `packages/recording/src/fsglobals.ts`),
+ * but that only runs once `fs.js` has already loaded — far too late to fix the URL that
+ * fetched it. So the same resolution has to happen here, before the snippet injects its
+ * `<script>` tag, or an EU org that sets nothing but `orgId` fetches `fs.js` and its
+ * settings from the na1 edge, which does not serve that org (VAL-10545).
+ */
+/**
+ * The `host` / `script` defaults applied by `@fullstory/snippet`. Duplicated here because
+ * the package does not export them, and we need the default value in hand to regionalize
+ * it. Keep in sync with the defaults in that package's `initFS` / `executeSnippet` when
+ * upgrading the dependency.
+ */
+var DEFAULT_HOST = 'fullstory.com';
+var DEFAULT_SCRIPT = 'edge.fullstory.com/s/fs.js';
+/**
+ * Matches any subdomain of "fullstory.com", e.g. "www.fullstory.com", "edge.fullstory.com".
+ * Anchored at the start, so a customer proxy such as "cdn.acme.com/fullstory.com/x" does
+ * not match.
+ */
+var FS_DOMAIN = /^([^.]+\.)*fullstory\.com(\/|$)/;
+/** Region labels look like "eu1", "ap1", "na1". */
+var REGION_LABEL = /^[a-z]{2,3}[0-9]+$/;
+/**
+ * Parses the region/locale suffix out of an orgId, e.g. "o-7Y9H-eu1" -> "eu1". Returns
+ * `undefined` for na1 and for orgIds that carry no region, meaning "apply no region".
+ * Mirrors `orgLocale()` in the monorepo's `packages/recording/src/fsglobals.ts`.
+ */
+var orgLocale = function (orgId) {
+    var sections = orgId ? orgId.split('-') : [];
+    if (sections.length < 3) {
+        return undefined;
+    }
+    var prefix = sections[0];
+    var realm = sections[sections.length - 1];
+    // A standard type prefix has only one character in it (o, u, p, etc.). If there is more
+    // than one character then we most likely have a legacy org ID that happens to contain
+    // hyphens, not a region suffix.
+    if (realm === 'na1' || prefix.length > 1) {
+        return undefined;
+    }
+    return realm;
+};
+/**
+ * Applies an org's region to a Fullstory-owned host, inserting the locale as the label
+ * immediately before the registrable domain and preserving any path:
+ *
+ *   ("fullstory.com", "eu1")               -> "eu1.fullstory.com"
+ *   ("edge.fullstory.com/s/fs.js", "eu1")  -> "edge.eu1.fullstory.com/s/fs.js"
+ *
+ * Hosts Fullstory does not own — self-hosted proxies, Relay, localhost — are returned
+ * untouched, as are hosts already carrying the right region (so this is idempotent and
+ * safe to stack with the same resolution in `fs.js`).
+ */
+var regionalize = function (value, locale) {
+    if (!locale || !FS_DOMAIN.test(value)) {
+        return value;
+    }
+    // Only the host is rewritten; anything from the first "/" on is left alone.
+    var pathIndex = value.indexOf('/');
+    var host = pathIndex === -1 ? value : value.slice(0, pathIndex);
+    var path = pathIndex === -1 ? '' : value.slice(pathIndex);
+    var labels = host.split('.');
+    // FS_DOMAIN guarantees at least "fullstory.com", so this is never negative.
+    var insertAt = labels.length - 2;
+    var existing = insertAt > 0 ? labels[insertAt - 1] : undefined;
+    if (existing === locale) {
+        return value;
+    }
+    if (existing !== undefined && REGION_LABEL.test(existing)) {
+        // A different region is already present (e.g. "edge.na1.fullstory.com" on an eu1 org).
+        // Replace it rather than insert, which would yield "edge.eu1.na1.fullstory.com".
+        labels[insertAt - 1] = locale;
+    }
+    else {
+        labels.splice(insertAt, 0, locale);
+    }
+    return labels.join('.') + path;
+};
+
 // Module-level state set during `_init` (replaces former window `_fs_*` globals).
 var _namespace;
 var _initialized = false;
@@ -87,6 +170,17 @@ var _init = function (inputOptions, readyCallback) {
             console.warn('Ignoring `debug = true` because `script` is set');
         }
     }
+    // `fs.js` resolves the org's region itself, but not until after it has loaded — the URL
+    // that fetches it has to be regionalized here instead (VAL-10545). Fullstory-owned hosts
+    // pick up the region label; customer proxies and Relay hosts are left alone.
+    var locale = orgLocale(options.orgId);
+    if (locale) {
+        options.host = regionalize(options.host || DEFAULT_HOST, locale);
+        options.script = regionalize(options.script || DEFAULT_SCRIPT, locale);
+        if (fsInitEnv.appHost) {
+            fsInitEnv.appHost = regionalize(fsInitEnv.appHost, locale);
+        }
+    }
     initFS(options);
     var fs = getFullStory(_namespace);
     if (!fs) {

package/dist/index.js

@@ -35,6 +35,89 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+/**
+ * Region resolution for the Fullstory host/script options.
+ *
+ * `fs.js` derives an org's region by parsing the locale suffix off its orgId (see
+ * `orgLocale()` / `fullstoryHost()` in the monorepo's `packages/recording/src/fsglobals.ts`),
+ * but that only runs once `fs.js` has already loaded — far too late to fix the URL that
+ * fetched it. So the same resolution has to happen here, before the snippet injects its
+ * `<script>` tag, or an EU org that sets nothing but `orgId` fetches `fs.js` and its
+ * settings from the na1 edge, which does not serve that org (VAL-10545).
+ */
+/**
+ * The `host` / `script` defaults applied by `@fullstory/snippet`. Duplicated here because
+ * the package does not export them, and we need the default value in hand to regionalize
+ * it. Keep in sync with the defaults in that package's `initFS` / `executeSnippet` when
+ * upgrading the dependency.
+ */
+var DEFAULT_HOST = 'fullstory.com';
+var DEFAULT_SCRIPT = 'edge.fullstory.com/s/fs.js';
+/**
+ * Matches any subdomain of "fullstory.com", e.g. "www.fullstory.com", "edge.fullstory.com".
+ * Anchored at the start, so a customer proxy such as "cdn.acme.com/fullstory.com/x" does
+ * not match.
+ */
+var FS_DOMAIN = /^([^.]+\.)*fullstory\.com(\/|$)/;
+/** Region labels look like "eu1", "ap1", "na1". */
+var REGION_LABEL = /^[a-z]{2,3}[0-9]+$/;
+/**
+ * Parses the region/locale suffix out of an orgId, e.g. "o-7Y9H-eu1" -> "eu1". Returns
+ * `undefined` for na1 and for orgIds that carry no region, meaning "apply no region".
+ * Mirrors `orgLocale()` in the monorepo's `packages/recording/src/fsglobals.ts`.
+ */
+var orgLocale = function (orgId) {
+    var sections = orgId ? orgId.split('-') : [];
+    if (sections.length < 3) {
+        return undefined;
+    }
+    var prefix = sections[0];
+    var realm = sections[sections.length - 1];
+    // A standard type prefix has only one character in it (o, u, p, etc.). If there is more
+    // than one character then we most likely have a legacy org ID that happens to contain
+    // hyphens, not a region suffix.
+    if (realm === 'na1' || prefix.length > 1) {
+        return undefined;
+    }
+    return realm;
+};
+/**
+ * Applies an org's region to a Fullstory-owned host, inserting the locale as the label
+ * immediately before the registrable domain and preserving any path:
+ *
+ *   ("fullstory.com", "eu1")               -> "eu1.fullstory.com"
+ *   ("edge.fullstory.com/s/fs.js", "eu1")  -> "edge.eu1.fullstory.com/s/fs.js"
+ *
+ * Hosts Fullstory does not own — self-hosted proxies, Relay, localhost — are returned
+ * untouched, as are hosts already carrying the right region (so this is idempotent and
+ * safe to stack with the same resolution in `fs.js`).
+ */
+var regionalize = function (value, locale) {
+    if (!locale || !FS_DOMAIN.test(value)) {
+        return value;
+    }
+    // Only the host is rewritten; anything from the first "/" on is left alone.
+    var pathIndex = value.indexOf('/');
+    var host = pathIndex === -1 ? value : value.slice(0, pathIndex);
+    var path = pathIndex === -1 ? '' : value.slice(pathIndex);
+    var labels = host.split('.');
+    // FS_DOMAIN guarantees at least "fullstory.com", so this is never negative.
+    var insertAt = labels.length - 2;
+    var existing = insertAt > 0 ? labels[insertAt - 1] : undefined;
+    if (existing === locale) {
+        return value;
+    }
+    if (existing !== undefined && REGION_LABEL.test(existing)) {
+        // A different region is already present (e.g. "edge.na1.fullstory.com" on an eu1 org).
+        // Replace it rather than insert, which would yield "edge.eu1.na1.fullstory.com".
+        labels[insertAt - 1] = locale;
+    }
+    else {
+        labels.splice(insertAt, 0, locale);
+    }
+    return labels.join('.') + path;
+};
+
 // Module-level state set during `_init` (replaces former window `_fs_*` globals).
 var _namespace;
 var _initialized = false;
@@ -89,6 +172,17 @@ var _init = function (inputOptions, readyCallback) {
             console.warn('Ignoring `debug = true` because `script` is set');
         }
     }
+    // `fs.js` resolves the org's region itself, but not until after it has loaded — the URL
+    // that fetches it has to be regionalized here instead (VAL-10545). Fullstory-owned hosts
+    // pick up the region label; customer proxies and Relay hosts are left alone.
+    var locale = orgLocale(options.orgId);
+    if (locale) {
+        options.host = regionalize(options.host || DEFAULT_HOST, locale);
+        options.script = regionalize(options.script || DEFAULT_SCRIPT, locale);
+        if (fsInitEnv.appHost) {
+            fsInitEnv.appHost = regionalize(fsInitEnv.appHost, locale);
+        }
+    }
     snippet.initFS(options);
     var fs = getFullStory(_namespace);
     if (!fs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstory/browser",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "The official Fullstory browser SDK",
   "repository": "git://github.com/fullstorydev/fullstory-browser-sdk.git",
   "homepage": "https://github.com/fullstorydev/fullstory-browser-sdk",

package/src/hosts.test.ts

@@ -0,0 +1,65 @@
+import { DEFAULT_HOST, DEFAULT_SCRIPT, orgLocale, regionalize } from './hosts';
+
+describe('orgLocale', () => {
+  it('should return the region suffix of a regional orgId', () => {
+    expect(orgLocale('o-7Y9H-eu1')).toBe('eu1');
+    expect(orgLocale('o-1A2B3C-ap1')).toBe('ap1');
+  });
+
+  it('should return undefined for na1, which needs no region label', () => {
+    expect(orgLocale('o-7Y9H-na1')).toBeUndefined();
+  });
+
+  it('should return undefined for orgIds with no region', () => {
+    expect(orgLocale('123')).toBeUndefined();
+    expect(orgLocale('o-7Y9H')).toBeUndefined();
+    expect(orgLocale('')).toBeUndefined();
+    expect(orgLocale(undefined)).toBeUndefined();
+  });
+
+  it('should ignore legacy orgIds that merely contain hyphens', () => {
+    // A real type prefix is a single character (o, u, p); anything longer is a legacy id.
+    expect(orgLocale('ACME-Widgets-Inc')).toBeUndefined();
+  });
+});
+
+describe('regionalize', () => {
+  it('should insert the region before the registrable domain', () => {
+    expect(regionalize(DEFAULT_HOST, 'eu1')).toBe('eu1.fullstory.com');
+    expect(regionalize(DEFAULT_SCRIPT, 'eu1')).toBe('edge.eu1.fullstory.com/s/fs.js');
+  });
+
+  it('should preserve the path of a script URL', () => {
+    expect(regionalize('edge.fullstory.com/s/fs-debug.js', 'eu1'))
+      .toBe('edge.eu1.fullstory.com/s/fs-debug.js');
+  });
+
+  it('should regionalize the www and app subdomains', () => {
+    expect(regionalize('www.fullstory.com', 'eu1')).toBe('www.eu1.fullstory.com');
+    expect(regionalize('app.fullstory.com', 'eu1')).toBe('app.eu1.fullstory.com');
+  });
+
+  it('should be idempotent for hosts already carrying the region', () => {
+    expect(regionalize('eu1.fullstory.com', 'eu1')).toBe('eu1.fullstory.com');
+    expect(regionalize('edge.eu1.fullstory.com/s/fs.js', 'eu1'))
+      .toBe('edge.eu1.fullstory.com/s/fs.js');
+  });
+
+  it('should replace a mismatched region rather than stacking another one on top', () => {
+    expect(regionalize('edge.na1.fullstory.com/s/fs.js', 'eu1'))
+      .toBe('edge.eu1.fullstory.com/s/fs.js');
+  });
+
+  it('should leave hosts Fullstory does not own untouched', () => {
+    expect(regionalize('fs.acme.com', 'eu1')).toBe('fs.acme.com');
+    expect(regionalize('localhost:8080', 'eu1')).toBe('localhost:8080');
+    // Anchored, so a proxy path that happens to mention fullstory.com is not a match.
+    expect(regionalize('cdn.acme.com/fullstory.com/fs.js', 'eu1'))
+      .toBe('cdn.acme.com/fullstory.com/fs.js');
+  });
+
+  it('should return the value unchanged when there is no region', () => {
+    expect(regionalize(DEFAULT_SCRIPT, undefined)).toBe(DEFAULT_SCRIPT);
+    expect(regionalize(DEFAULT_SCRIPT, '')).toBe(DEFAULT_SCRIPT);
+  });
+});

package/src/hosts.ts

@@ -0,0 +1,94 @@
+/**
+ * Region resolution for the Fullstory host/script options.
+ *
+ * `fs.js` derives an org's region by parsing the locale suffix off its orgId (see
+ * `orgLocale()` / `fullstoryHost()` in the monorepo's `packages/recording/src/fsglobals.ts`),
+ * but that only runs once `fs.js` has already loaded — far too late to fix the URL that
+ * fetched it. So the same resolution has to happen here, before the snippet injects its
+ * `<script>` tag, or an EU org that sets nothing but `orgId` fetches `fs.js` and its
+ * settings from the na1 edge, which does not serve that org (VAL-10545).
+ */
+
+/**
+ * The `host` / `script` defaults applied by `@fullstory/snippet`. Duplicated here because
+ * the package does not export them, and we need the default value in hand to regionalize
+ * it. Keep in sync with the defaults in that package's `initFS` / `executeSnippet` when
+ * upgrading the dependency.
+ */
+export const DEFAULT_HOST = 'fullstory.com';
+export const DEFAULT_SCRIPT = 'edge.fullstory.com/s/fs.js';
+
+/**
+ * Matches any subdomain of "fullstory.com", e.g. "www.fullstory.com", "edge.fullstory.com".
+ * Anchored at the start, so a customer proxy such as "cdn.acme.com/fullstory.com/x" does
+ * not match.
+ */
+const FS_DOMAIN = /^([^.]+\.)*fullstory\.com(\/|$)/;
+
+/** Region labels look like "eu1", "ap1", "na1". */
+const REGION_LABEL = /^[a-z]{2,3}[0-9]+$/;
+
+/**
+ * Parses the region/locale suffix out of an orgId, e.g. "o-7Y9H-eu1" -> "eu1". Returns
+ * `undefined` for na1 and for orgIds that carry no region, meaning "apply no region".
+ * Mirrors `orgLocale()` in the monorepo's `packages/recording/src/fsglobals.ts`.
+ */
+export const orgLocale = (orgId?: string): string | undefined => {
+  const sections = orgId ? orgId.split('-') : [];
+  if (sections.length < 3) {
+    return undefined;
+  }
+
+  const prefix = sections[0];
+  const realm = sections[sections.length - 1];
+
+  // A standard type prefix has only one character in it (o, u, p, etc.). If there is more
+  // than one character then we most likely have a legacy org ID that happens to contain
+  // hyphens, not a region suffix.
+  if (realm === 'na1' || prefix.length > 1) {
+    return undefined;
+  }
+
+  return realm;
+};
+
+/**
+ * Applies an org's region to a Fullstory-owned host, inserting the locale as the label
+ * immediately before the registrable domain and preserving any path:
+ *
+ *   ("fullstory.com", "eu1")               -> "eu1.fullstory.com"
+ *   ("edge.fullstory.com/s/fs.js", "eu1")  -> "edge.eu1.fullstory.com/s/fs.js"
+ *
+ * Hosts Fullstory does not own — self-hosted proxies, Relay, localhost — are returned
+ * untouched, as are hosts already carrying the right region (so this is idempotent and
+ * safe to stack with the same resolution in `fs.js`).
+ */
+export const regionalize = (value: string, locale?: string): string => {
+  if (!locale || !FS_DOMAIN.test(value)) {
+    return value;
+  }
+
+  // Only the host is rewritten; anything from the first "/" on is left alone.
+  const pathIndex = value.indexOf('/');
+  const host = pathIndex === -1 ? value : value.slice(0, pathIndex);
+  const path = pathIndex === -1 ? '' : value.slice(pathIndex);
+
+  const labels = host.split('.');
+  // FS_DOMAIN guarantees at least "fullstory.com", so this is never negative.
+  const insertAt = labels.length - 2;
+  const existing = insertAt > 0 ? labels[insertAt - 1] : undefined;
+
+  if (existing === locale) {
+    return value;
+  }
+
+  if (existing !== undefined && REGION_LABEL.test(existing)) {
+    // A different region is already present (e.g. "edge.na1.fullstory.com" on an eu1 org).
+    // Replace it rather than insert, which would yield "edge.eu1.na1.fullstory.com".
+    labels[insertAt - 1] = locale;
+  } else {
+    labels.splice(insertAt, 0, locale);
+  }
+
+  return labels.join('.') + path;
+};

package/src/index.test.ts

@@ -18,6 +18,20 @@ const findBrowserInitEnv = (ns = 'FS'): Record<string, unknown> | undefined => {
   return initOptions?.env;
 };
 
+/** Snippet's own init call (the first one), which carries the resolved orgId/host/script. */
+const findSnippetInitEnv = (ns = 'FS'): Record<string, unknown> | undefined => {
+  const initCalls = getFsQueue(ns)?.filter((call) => call[0] === 'init') ?? [];
+  const initOptions = initCalls[0]?.[1] as { env?: Record<string, unknown> } | undefined;
+  return initOptions?.env;
+};
+
+/** The `src` of the <script> tag the snippet injects to load fs.js. */
+const injectedScriptSrc = (): string | undefined => {
+  const scripts = document.querySelectorAll('script[data-fs-namespace]');
+  expect(scripts).toHaveLength(1);
+  return (scripts[0] as HTMLScriptElement).src;
+};
+
 beforeEach(() => {
   // Module-level init state lives in the SDK; re-import for a clean slate per test.
   jest.resetModules();
@@ -28,6 +42,9 @@ beforeEach(() => {
     }
   });
   delete (window as { FS?: unknown }).FS;
+  // The snippet appends to the shared jsdom document; drop prior tests' script tags so
+  // `injectedScriptSrc()` can only ever see the one injected by the test at hand.
+  document.querySelectorAll('script[data-fs-namespace]').forEach((el) => { el.remove(); });
 });
 
 const loadSdk = async () => {
@@ -155,6 +172,63 @@ describe('init', () => {
   });
 });
 
+describe('region resolution', () => {
+  // fs.js only learns the org's region after it loads, so the SDK has to resolve it up
+  // front or a regional org fetches fs.js and its settings from the na1 edge (VAL-10545).
+  const euOrg = 'o-7Y9H-eu1';
+
+  it('should fetch fs.js from the org region edge', async () => {
+    const { init } = await loadSdk();
+    init({ orgId: euOrg });
+
+    expect(injectedScriptSrc()).toContain('edge.eu1.fullstory.com/s/fs.js');
+  });
+
+  it('should pass the regional host and script to the snippet init', async () => {
+    const { init } = await loadSdk();
+    init({ orgId: euOrg });
+
+    const env = findSnippetInitEnv();
+    expect(env?.host).toBe('eu1.fullstory.com');
+    expect(env?.script).toBe('edge.eu1.fullstory.com/s/fs.js');
+  });
+
+  it('should regionalize the debug script', async () => {
+    const { init } = await loadSdk();
+    init({ orgId: euOrg, debug: true });
+
+    expect(injectedScriptSrc()).toContain('edge.eu1.fullstory.com/s/fs-debug.js');
+  });
+
+  it('should regionalize an explicitly set Fullstory host', async () => {
+    const { init } = await loadSdk();
+    init({ orgId: euOrg, host: 'fullstory.com', appHost: 'app.fullstory.com' });
+
+    expect(findSnippetInitEnv()?.host).toBe('eu1.fullstory.com');
+    expect(findBrowserInitEnv()?.appHost).toBe('app.eu1.fullstory.com');
+  });
+
+  it('should leave a self-hosted proxy untouched', async () => {
+    const { init } = await loadSdk();
+    init({ orgId: euOrg, host: 'fs.example.com', script: 'fs.example.com/fs.js' });
+
+    const env = findSnippetInitEnv();
+    expect(env?.host).toBe('fs.example.com');
+    expect(env?.script).toBe('fs.example.com/fs.js');
+    expect(injectedScriptSrc()).toContain('fs.example.com/fs.js');
+  });
+
+  it('should not change the defaults for an org with no region', async () => {
+    const { init } = await loadSdk();
+    init({ orgId: testOrg });
+
+    const env = findSnippetInitEnv();
+    expect(env?.host).toBe('fullstory.com');
+    expect(env?.script).toBe('edge.fullstory.com/s/fs.js');
+    expect(injectedScriptSrc()).toContain('edge.fullstory.com/s/fs.js');
+  });
+});
+
 describe('devMode', () => {
   let consoleWarnedMessage;
   const oldConsoleWarn = console.warn;

package/src/index.ts

@@ -1,4 +1,5 @@
 import { initFS, FSApi } from '@fullstory/snippet';
+import { DEFAULT_HOST, DEFAULT_SCRIPT, orgLocale, regionalize } from './hosts';
 
 /**
  * FullStory Client SDK snippet options.
@@ -6,13 +7,17 @@ import { initFS, FSApi } from '@fullstory/snippet';
  * - orgId: Reference for your [Org Id](https://help.fullstory.com/hc/en-us/articles/360047075853) listed in FullStory.
  * - namespace: Global object name that contains the FullStory browser API methods and properties. Defaults to `FS`.
  * - debug: Debug mode with extra browser console logging.
- * - host: The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`.
- * - script: FullStory script host domain. FullStory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com`.
+ * - host: The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`, or the region-specific equivalent (e.g. `eu1.fullstory.com`) when `orgId` carries a region suffix.
+ * - script: FullStory script host domain. FullStory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com/s/fs.js`, or the region-specific equivalent (e.g. `edge.eu1.fullstory.com/s/fs.js`) when `orgId` carries a region suffix.
  * - cookieDomain: Overrides the cookie domain. By default, cookies will be valid for all subdomains of your site; if you want to limit the cookies to a specific subdomain, you can set the domain value explicitly. More information can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622874-Can-the-FullStory-cookie-be-associated-with-a-specific-subdomain-).
  * - recordCrossDomainIFrames: FullStory can record cross-domain iFrames. Defaults to `false`. Certain limitations apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G333PYKPGZ4B42WDBV3YKV).
  * - recordOnlyThisIFrame: FullStory can record the iFrame as its own unique session. Defaults to `false`. Additional conditions apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G33B40Q2TPQA8MA7SF8Y5P).
  * - devMode: In dev mode FullStory won't record sessions. Any calls to SDK methods will `console.warn` that FullStory is in `devMode`. Defaults to `false`.
  * - sessionUid (beta): Sets the session UID passed to the `FS('init', ...)` v2 operation.
+ *
+ * The region encoded in `orgId` (e.g. the `eu1` in `o-ABC123-eu1`) is applied to `host`, `script` and `appHost`
+ * whenever those resolve to a FullStory-owned domain, including values you set explicitly. Hosts FullStory does
+ * not own — a proxy or Relay domain of your own — are always used exactly as given.
  */
 export interface SnippetOptions {
   orgId: string;
@@ -121,6 +126,18 @@ const _init = (inputOptions: SnippetOptions, readyCallback?: ReadyCallback) => {
     }
   }
 
+  // `fs.js` resolves the org's region itself, but not until after it has loaded — the URL
+  // that fetches it has to be regionalized here instead (VAL-10545). Fullstory-owned hosts
+  // pick up the region label; customer proxies and Relay hosts are left alone.
+  const locale = orgLocale(options.orgId);
+  if (locale) {
+    options.host = regionalize(options.host || DEFAULT_HOST, locale);
+    options.script = regionalize(options.script || DEFAULT_SCRIPT, locale);
+    if (fsInitEnv.appHost) {
+      fsInitEnv.appHost = regionalize(fsInitEnv.appHost, locale);
+    }
+  }
+
   initFS(options);
 
   const fs = getFullStory(_namespace);