@fullstory/browser 2.1.0-beta.0 → 2.1.1

package/README.md

@@ -4,6 +4,8 @@
 
 Fullstory's browser SDK lets you manage Fullstory data capture on your site as well as retrieve deep links to session replays and send your own custom events. More information about the Fullstory API can be found at https://developer.fullstory.com.
 
+Version 2.1.0 updates the sdk to use v2.1 of the Fullstory snippet. No external updates are required. Please reference our developer docs for a list of [what's new in Snippet 2.1](https://developer.fullstory.com/browser/getting-started/#whats-new-in-version-21).
+
 > **NOTE:** this is the documentation for version 2. For version 1 documentation, please see [@fullstory/browser@1.7.1](https://www.npmjs.com/package/@fullstory/browser/v/1.7.1).
 
 ## Install the SDK
@@ -71,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.
@@ -82,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-beta.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",
@@ -25,7 +25,7 @@
     "sdk"
   ],
   "dependencies": {
-    "@fullstory/snippet": "2.1.0-beta.0"
+    "@fullstory/snippet": "2.1.0"
   },
   "overrides": {
     "brace-expansion": "^5.0.8"

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);