@contentful/experiences-web 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+## 0.0.2 (2026-09-29)
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.5.2
+- Updated core to 0.9.2
+
+## 0.0.1 (2026-09-29)
+
+### 🚀 Features
+
+- add Web SDK runtime ([#208](https://github.com/contentful/experiences/pull/208))
+
+### 🧱 Updated Dependencies
+
+- Updated client to 0.5.1
+- Updated core to 0.9.1

package/README.md

@@ -0,0 +1,97 @@
+# @contentful/experiences-web
+
+The browser SDK for fetching and resolving [Contentful Experiences](https://www.contentful.com/developers/docs/concepts/experiences/) in a Web application. It produces runtime-neutral `PortableRenderPlan` values; render a plan with the framework adapter used by your application.
+
+> **Alpha.** This package is a lean browser runtime. Its API is still evolving.
+
+## Install
+
+```sh
+npm install @contentful/experiences-web
+```
+
+## Browser transport and preview
+
+This package inherits Client's by-ID Experience transport capabilities: it can use the Content Delivery API (CDA) and, when configured, the Content Preview API (CPA). Destination operations remain delivery-only.
+
+Browser configuration is trusted application configuration. A bearer token is sent to the endpoint selected by that configuration, so validate the endpoint's origin, CORS/preflight policy, and token scope before constructing the SDK. Do not place tokens in query strings. Browser-visible delivery and preview tokens must be appropriate for the audience and origin that can load them; use a server boundary when that is not acceptable.
+
+`environmentId` identifies the Contentful environment used by an Experience request. It is distinct from the generated delivery client's optional `environment` endpoint configuration. For endpoint selection, the Experiences SDK's `host` maps to the generated client's `baseUrl`; a raw `ContentfulViewDeliveryClient` can instead be constructed with `baseUrl` directly. Endpoint precedence is explicit `host`/raw-client `baseUrl`, then generated-client `environment`, then the delivery or preview default. These options support trusted custom endpoints such as a proxy, staging service, or regional endpoint.
+
+```ts
+import { ContentfulExperiences } from '@contentful/experiences-web';
+
+const experiences = new ContentfulExperiences({
+  spaceId,
+  environmentId: 'master',
+  resolverConfig,
+  delivery: {
+    accessToken: publicDeliveryToken,
+    host: 'https://experiences-proxy.example.com', // optional trusted endpoint
+  },
+  preview: { accessToken: publicPreviewToken }, // optional direct CPA client
+  locale: 'en-US',
+  app: { name: 'storefront', version: '1.0.0' },
+});
+
+const plan = await experiences.fetchExperience({ experienceId });
+const draft = await experiences.fetchExperience({ experienceId, preview: true });
+
+experiences.setLocale('de-DE');
+```
+
+The generated delivery client must be able to reach the selected endpoint from the browser using its Authorization and feature headers. Validate CORS/preflight behavior in the browsers you support before deployment. If direct browser access is not appropriate, use a trusted same-origin client or an application BFF.
+
+Preview here means a direct, by-ID CPA fetch through the shared runtime. It is not a Preview Session: `@contentful/experiences-live-preview` owns Preview Session HTTP loading, WebSocket subscription, and update state. The Web SDK neither integrates nor owns that transport.
+
+## Browser-safe configuration
+
+Resolver configuration runs in the browser. Keep `resolveData`, `resolveToken`, and component configuration free of server-only imports, secrets, and privileged calls. Treat resolver `metadata` as browser-visible too: pass only values that are safe to expose to the current user. Debug logging and source maps remain opt-in and can expose raw CMS data.
+
+Locale is mutable browser state. Update it with `setLocale()` rather than sharing a request-scoped Node facade; browser navigation, language selection, and concurrent renders then observe the current client-side locale without leaking server request state. An explicit per-call locale still wins for that fetch.
+
+## Context providers and redaction
+
+The default event context is read lazily and includes the current URL, path, query parameters, search, hash, referrer, title, viewport dimensions, and User-Agent. SPA navigation is therefore reflected without reconstructing the SDK. These values can contain sensitive data.
+
+Use `browserContext.getPageProperties` and `browserContext.getUserAgent` to redact or replace the defaults before a value is retained, logged, or sent onward. Do not expose authentication material, raw identifiers, or personal data merely because it is available in the browser.
+
+```ts
+const experiences = new ContentfulExperiences({
+  // delivery and resolver configuration...
+  browserContext: {
+    getPageProperties: () => ({
+      path: window.location.pathname,
+      query: {},
+      referrer: '',
+      search: '',
+      title: document.title,
+      url: `${window.location.origin}${window.location.pathname}`,
+    }),
+    getUserAgent: () => undefined,
+  },
+});
+```
+
+## SSR import safety
+
+The package can be imported by server-rendered applications, but importing it must not read browser globals or start browser work. Import safety does not make the live Web runtime a server runtime: create and use browser-owned SDK state only in client-side lifecycle code, and use the Node SDK plus a serializable `PortableRenderPlan` for server rendering. The separate SSR test configuration protects the public-entry import and pure browser-context fallbacks without promising that future stateful Web construction will run on the server.
+
+## Errors and destinations
+
+Missing Experiences surface the delivery client's `NotFoundError`; other delivery and resolution errors propagate so the application can apply its normal error policy. Destination operations use the delivery service and return either a resolved plan or a redirect result; route redirects at the application boundary.
+
+For a by-ID fetch, `preview: true` selects the configured CPA client and throws if no preview client was configured. The delivery client's errors, including `NotFoundError`, otherwise propagate. Destination fetches remain delivery-only.
+
+## Current limitations
+
+- No event methods, persistence, or offline queues yet.
+- No server request facade; use `@contentful/experiences-node` for request-scoped server work.
+
+## Architecture boundary
+
+`@contentful/experiences-web` is a public Web-specific sibling of `@contentful/experiences-node`. Both build on the internal `@contentful/experiences-client` and `@contentful/experiences-sdk-core` packages. The Web package owns browser state; the Node package owns request-local state. Neither package inherits the other's lifecycle semantics.
+
+## License
+
+MIT. See the repository [LICENSE](../../LICENSE) and [NOTICE](../../NOTICE) for full attribution.

package/dist/browser-event-context.d.ts

@@ -0,0 +1,12 @@
+import { EventBuilderConfig } from '@contentful/experiences-client';
+
+type Page = ReturnType<NonNullable<EventBuilderConfig['getPageProperties']>>;
+/**
+ * Reads the current browser page at event-build time. Keeping this lazy makes
+ * navigation updates visible to an existing SDK instance and keeps SSR safe.
+ */
+declare function getPageProperties(): Page;
+/** Returns the current browser user agent, or no value outside a browser. */
+declare function getUserAgent(): string | undefined;
+
+export { getPageProperties, getUserAgent };

package/dist/browser-event-context.js

@@ -0,0 +1,32 @@
+import { DEFAULT_PAGE_PROPERTIES } from "@contentful/experiences-client";
+function getPageProperties() {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return { ...DEFAULT_PAGE_PROPERTIES };
+  }
+  try {
+    const { location } = window;
+    const query = Object.fromEntries(new URL(location.href).searchParams.entries());
+    return {
+      ...DEFAULT_PAGE_PROPERTIES,
+      url: location.href,
+      path: location.pathname,
+      query,
+      search: location.search,
+      hash: location.hash,
+      referrer: document.referrer,
+      title: document.title,
+      width: window.innerWidth,
+      height: window.innerHeight
+    };
+  } catch {
+    return { ...DEFAULT_PAGE_PROPERTIES };
+  }
+}
+function getUserAgent() {
+  return typeof window === "undefined" || typeof window.navigator === "undefined" ? void 0 : window.navigator.userAgent;
+}
+export {
+  getPageProperties,
+  getUserAgent
+};
+//# sourceMappingURL=browser-event-context.js.map

package/dist/browser-event-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser-event-context.ts"],"sourcesContent":["import { DEFAULT_PAGE_PROPERTIES, type EventBuilderConfig } from '@contentful/experiences-client';\n\ntype Page = ReturnType<NonNullable<EventBuilderConfig['getPageProperties']>>;\n\n/**\n * Reads the current browser page at event-build time. Keeping this lazy makes\n * navigation updates visible to an existing SDK instance and keeps SSR safe.\n */\nexport function getPageProperties(): Page {\n  if (typeof window === 'undefined' || typeof document === 'undefined') {\n    return { ...DEFAULT_PAGE_PROPERTIES };\n  }\n\n  try {\n    const { location } = window;\n    const query = Object.fromEntries(new URL(location.href).searchParams.entries());\n\n    return {\n      ...DEFAULT_PAGE_PROPERTIES,\n      url: location.href,\n      path: location.pathname,\n      query,\n      search: location.search,\n      hash: location.hash,\n      referrer: document.referrer,\n      title: document.title,\n      width: window.innerWidth,\n      height: window.innerHeight,\n    };\n  } catch {\n    return { ...DEFAULT_PAGE_PROPERTIES };\n  }\n}\n\n/** Returns the current browser user agent, or no value outside a browser. */\nexport function getUserAgent(): string | undefined {\n  return typeof window === 'undefined' || typeof window.navigator === 'undefined'\n    ? undefined\n    : window.navigator.userAgent;\n}\n"],"mappings":"AAAA,SAAS,+BAAwD;AAQ1D,SAAS,oBAA0B;AACxC,MAAI,OAAO,WAAW,eAAe,OAAO,aAAa,aAAa;AACpE,WAAO,EAAE,GAAG,wBAAwB;AAAA,EACtC;AAEA,MAAI;AACF,UAAM,EAAE,SAAS,IAAI;AACrB,UAAM,QAAQ,OAAO,YAAY,IAAI,IAAI,SAAS,IAAI,EAAE,aAAa,QAAQ,CAAC;AAE9E,WAAO;AAAA,MACL,GAAG;AAAA,MACH,KAAK,SAAS;AAAA,MACd,MAAM,SAAS;AAAA,MACf;AAAA,MACA,QAAQ,SAAS;AAAA,MACjB,MAAM,SAAS;AAAA,MACf,UAAU,SAAS;AAAA,MACnB,OAAO,SAAS;AAAA,MAChB,OAAO,OAAO;AAAA,MACd,QAAQ,OAAO;AAAA,IACjB;AAAA,EACF,QAAQ;AACN,WAAO,EAAE,GAAG,wBAAwB;AAAA,EACtC;AACF;AAGO,SAAS,eAAmC;AACjD,SAAO,OAAO,WAAW,eAAe,OAAO,OAAO,cAAc,cAChE,SACA,OAAO,UAAU;AACvB;","names":[]}

package/dist/contentful-experiences.d.ts

@@ -0,0 +1,22 @@
+import { EventBuilderConfig, ContentfulExperiences as ContentfulExperiences$1, ContentfulExperiencesConfig } from '@contentful/experiences-client';
+
+/** Optional browser context providers, useful for application-specific redaction. */
+type BrowserEventContextProviders = Pick<EventBuilderConfig, 'getPageProperties' | 'getUserAgent'>;
+/**
+ * Long-lived, browser-oriented SDK configuration.
+ */
+type ExperiencesWebConfig = Omit<ContentfulExperiencesConfig, 'eventBuilder' | 'locale'> & {
+    locale?: string;
+    app?: EventBuilderConfig['app'];
+    browserContext?: BrowserEventContextProviders;
+};
+/** Browser runtime with mutable application locale and live event context. */
+declare class ContentfulExperiences extends ContentfulExperiences$1 {
+    #private;
+    constructor(config: ExperiencesWebConfig);
+    get locale(): string | undefined;
+    /** Changes the default locale used by subsequent events and fetches. */
+    setLocale(locale: string | undefined): void;
+}
+
+export { type BrowserEventContextProviders, ContentfulExperiences, type ExperiencesWebConfig };

package/dist/contentful-experiences.js

@@ -0,0 +1,33 @@
+import {
+  ContentfulExperiences as ClientContentfulExperiences
+} from "@contentful/experiences-client";
+import { getPageProperties, getUserAgent } from "./browser-event-context.js";
+import { DEFAULT_EVENT_CONTEXT_LIBRARY } from "./sdk-info.js";
+class ContentfulExperiences extends ClientContentfulExperiences {
+  #locale;
+  constructor(config) {
+    const { app, browserContext, ...clientConfig } = config;
+    super({
+      ...clientConfig,
+      eventBuilder: {
+        app,
+        channel: "web",
+        library: DEFAULT_EVENT_CONTEXT_LIBRARY,
+        getPageProperties: browserContext?.getPageProperties ?? getPageProperties,
+        getUserAgent: browserContext?.getUserAgent ?? getUserAgent
+      }
+    });
+    this.#locale = config.locale;
+  }
+  get locale() {
+    return this.#locale;
+  }
+  /** Changes the default locale used by subsequent events and fetches. */
+  setLocale(locale) {
+    this.#locale = locale;
+  }
+}
+export {
+  ContentfulExperiences
+};
+//# sourceMappingURL=contentful-experiences.js.map

package/dist/contentful-experiences.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contentful-experiences.ts"],"sourcesContent":["import {\n  ContentfulExperiences as ClientContentfulExperiences,\n  type ContentfulExperiencesConfig,\n  type EventBuilderConfig,\n} from '@contentful/experiences-client';\n\nimport { getPageProperties, getUserAgent } from './browser-event-context.js';\nimport { DEFAULT_EVENT_CONTEXT_LIBRARY } from './sdk-info.js';\n\n/** Optional browser context providers, useful for application-specific redaction. */\nexport type BrowserEventContextProviders = Pick<\n  EventBuilderConfig,\n  'getPageProperties' | 'getUserAgent'\n>;\n\n/**\n * Long-lived, browser-oriented SDK configuration.\n */\nexport type ExperiencesWebConfig = Omit<ContentfulExperiencesConfig, 'eventBuilder' | 'locale'> & {\n  locale?: string;\n  app?: EventBuilderConfig['app'];\n  browserContext?: BrowserEventContextProviders;\n};\n\n/** Browser runtime with mutable application locale and live event context. */\nexport class ContentfulExperiences extends ClientContentfulExperiences {\n  #locale: string | undefined;\n\n  constructor(config: ExperiencesWebConfig) {\n    const { app, browserContext, ...clientConfig } = config;\n    super({\n      ...clientConfig,\n      eventBuilder: {\n        app,\n        channel: 'web',\n        library: DEFAULT_EVENT_CONTEXT_LIBRARY,\n        getPageProperties: browserContext?.getPageProperties ?? getPageProperties,\n        getUserAgent: browserContext?.getUserAgent ?? getUserAgent,\n      },\n    });\n    this.#locale = config.locale;\n  }\n\n  override get locale(): string | undefined {\n    return this.#locale;\n  }\n\n  /** Changes the default locale used by subsequent events and fetches. */\n  setLocale(locale: string | undefined): void {\n    this.#locale = locale;\n  }\n}\n"],"mappings":"AAAA;AAAA,EACE,yBAAyB;AAAA,OAGpB;AAEP,SAAS,mBAAmB,oBAAoB;AAChD,SAAS,qCAAqC;AAkBvC,MAAM,8BAA8B,4BAA4B;AAAA,EACrE;AAAA,EAEA,YAAY,QAA8B;AACxC,UAAM,EAAE,KAAK,gBAAgB,GAAG,aAAa,IAAI;AACjD,UAAM;AAAA,MACJ,GAAG;AAAA,MACH,cAAc;AAAA,QACZ;AAAA,QACA,SAAS;AAAA,QACT,SAAS;AAAA,QACT,mBAAmB,gBAAgB,qBAAqB;AAAA,QACxD,cAAc,gBAAgB,gBAAgB;AAAA,MAChD;AAAA,IACF,CAAC;AACD,SAAK,UAAU,OAAO;AAAA,EACxB;AAAA,EAEA,IAAa,SAA6B;AACxC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,UAAU,QAAkC;AAC1C,SAAK,UAAU;AAAA,EACjB;AACF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { getPageProperties, getUserAgent } from './browser-event-context.js';
+export { BrowserEventContextProviders, ContentfulExperiences, ExperiencesWebConfig } from './contentful-experiences.js';
+export { EXPERIENCES_WEB_SDK_NAME, EXPERIENCES_WEB_SDK_VERSION } from './sdk-info.js';
+export { ContentfulViewDelivery, ContentfulViewDeliveryClient, CreateClientOptions, DELIVERY_HOST, DestinationRedirectResult, ExperienceFetchError, NotFoundError, PREVIEW_HOST, RuntimeClientSource, RuntimeFetchByDestinationNodeOptions, RuntimeFetchByDestinationPathOptions, RuntimeFetchExperienceOptions, RuntimeResolveOptions, createClient } from '@contentful/experiences-client';
+export { ExperiencePayload, PortableRenderPlan, ResolverConfig } from '@contentful/experiences-sdk-core';

package/dist/index.js

@@ -0,0 +1,27 @@
+import { getPageProperties, getUserAgent } from "./browser-event-context.js";
+import { ContentfulExperiences } from "./contentful-experiences.js";
+import { EXPERIENCES_WEB_SDK_NAME, EXPERIENCES_WEB_SDK_VERSION } from "./sdk-info.js";
+import {
+  ContentfulViewDelivery,
+  ContentfulViewDeliveryClient,
+  DELIVERY_HOST,
+  ExperienceFetchError,
+  NotFoundError,
+  PREVIEW_HOST,
+  createClient
+} from "@contentful/experiences-client";
+export {
+  ContentfulExperiences,
+  ContentfulViewDelivery,
+  ContentfulViewDeliveryClient,
+  DELIVERY_HOST,
+  EXPERIENCES_WEB_SDK_NAME,
+  EXPERIENCES_WEB_SDK_VERSION,
+  ExperienceFetchError,
+  NotFoundError,
+  PREVIEW_HOST,
+  createClient,
+  getPageProperties,
+  getUserAgent
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export { getPageProperties, getUserAgent } from './browser-event-context.js';\nexport { ContentfulExperiences } from './contentful-experiences.js';\nexport type {\n  BrowserEventContextProviders,\n  ExperiencesWebConfig,\n} from './contentful-experiences.js';\nexport { EXPERIENCES_WEB_SDK_NAME, EXPERIENCES_WEB_SDK_VERSION } from './sdk-info.js';\n\nexport {\n  ContentfulViewDelivery,\n  ContentfulViewDeliveryClient,\n  DELIVERY_HOST,\n  ExperienceFetchError,\n  NotFoundError,\n  PREVIEW_HOST,\n  createClient,\n} from '@contentful/experiences-client';\nexport type {\n  CreateClientOptions,\n  DestinationRedirectResult,\n  RuntimeClientSource,\n  RuntimeFetchByDestinationNodeOptions,\n  RuntimeFetchByDestinationPathOptions,\n  RuntimeFetchExperienceOptions,\n  RuntimeResolveOptions,\n} from '@contentful/experiences-client';\nexport type {\n  ExperiencePayload,\n  PortableRenderPlan,\n  ResolverConfig,\n} from '@contentful/experiences-sdk-core';\n"],"mappings":"AAAA,SAAS,mBAAmB,oBAAoB;AAChD,SAAS,6BAA6B;AAKtC,SAAS,0BAA0B,mCAAmC;AAEtE;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}

package/dist/sdk-info.d.ts

@@ -0,0 +1,11 @@
+/** Package identity attached to events built by the Web SDK. */
+declare const EXPERIENCES_WEB_SDK_NAME: string;
+/** Package version attached to events built by the Web SDK. */
+declare const EXPERIENCES_WEB_SDK_VERSION: string;
+/** @internal Stable library metadata supplied to the shared EventBuilder. */
+declare const DEFAULT_EVENT_CONTEXT_LIBRARY: {
+    name: string;
+    version: string;
+};
+
+export { DEFAULT_EVENT_CONTEXT_LIBRARY, EXPERIENCES_WEB_SDK_NAME, EXPERIENCES_WEB_SDK_VERSION };

package/dist/sdk-info.js

@@ -0,0 +1,12 @@
+const EXPERIENCES_WEB_SDK_NAME = true ? "@contentful/experiences-web" : "@contentful/experiences-web";
+const EXPERIENCES_WEB_SDK_VERSION = true ? "0.0.1" : "0.0.0";
+const DEFAULT_EVENT_CONTEXT_LIBRARY = {
+  name: EXPERIENCES_WEB_SDK_NAME,
+  version: EXPERIENCES_WEB_SDK_VERSION
+};
+export {
+  DEFAULT_EVENT_CONTEXT_LIBRARY,
+  EXPERIENCES_WEB_SDK_NAME,
+  EXPERIENCES_WEB_SDK_VERSION
+};
+//# sourceMappingURL=sdk-info.js.map

package/dist/sdk-info.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sdk-info.ts"],"sourcesContent":["declare const __DEFAULT_EVENT_CONTEXT_LIBRARY_NAME__: string | undefined;\ndeclare const __DEFAULT_EVENT_CONTEXT_LIBRARY_VERSION__: string | undefined;\n\n/** Package identity attached to events built by the Web SDK. */\nexport const EXPERIENCES_WEB_SDK_NAME =\n  typeof __DEFAULT_EVENT_CONTEXT_LIBRARY_NAME__ === 'string'\n    ? __DEFAULT_EVENT_CONTEXT_LIBRARY_NAME__\n    : '@contentful/experiences-web';\n\n/** Package version attached to events built by the Web SDK. */\nexport const EXPERIENCES_WEB_SDK_VERSION =\n  typeof __DEFAULT_EVENT_CONTEXT_LIBRARY_VERSION__ === 'string'\n    ? __DEFAULT_EVENT_CONTEXT_LIBRARY_VERSION__\n    : '0.0.0';\n\n/** @internal Stable library metadata supplied to the shared EventBuilder. */\nexport const DEFAULT_EVENT_CONTEXT_LIBRARY = {\n  name: EXPERIENCES_WEB_SDK_NAME,\n  version: EXPERIENCES_WEB_SDK_VERSION,\n};\n"],"mappings":"AAIO,MAAM,2BACX,OACI,gCACA;AAGC,MAAM,8BACX,OACI,UACA;AAGC,MAAM,gCAAgC;AAAA,EAC3C,MAAM;AAAA,EACN,SAAS;AACX;","names":[]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@contentful/experiences-web",
+  "version": "0.0.2",
+  "description": "Browser SDK for Contentful Experiences",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contentful/experiences.git",
+    "directory": "packages/web"
+  },
+  "dependencies": {
+    "@contentful/experiences-client": "0.5.2",
+    "@contentful/experiences-sdk-core": "0.9.2"
+  },
+  "devDependencies": {
+    "jsdom": "^30.0.1"
+  }
+}