@salesforce/ui-bundle-template-feature-react-customer-web-client-chat 11.52.0

package/dist/scripts/sf-project-setup.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Run from SFDX project root: install dependencies, build, and launch the dev server
+ * for the UI bundle in force-app/main/default/uiBundles/.
+ *
+ * Usage: npm run sf-project-setup
+ * (from the directory that contains force-app/ and sfdx-project.json)
+ */
+
+import { spawnSync } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+/**
+ * npm strips .gitignore from published packages — generate them on first run.
+ * Templates are stored in scripts/gitignore-templates.json (generated at build
+ * time from the actual .gitignore files). The JSON may not exist in git-cloned
+ * distributions where .gitignore is already present, so loading is best-effort.
+ */
+function loadGitignoreTemplates() {
+  const templatesPath = resolve(__dirname, 'gitignore-templates.json');
+  if (!existsSync(templatesPath)) return null;
+  try {
+    return JSON.parse(readFileSync(templatesPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function ensureGitignore(dir, content) {
+  if (!content) return;
+  const gitignorePath = resolve(dir, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, content, 'utf8');
+    console.log(`Created .gitignore in ${dir}`);
+  }
+}
+
+function resolveUIBundlesDir() {
+  const sfdxPath = resolve(ROOT, 'sfdx-project.json');
+  if (!existsSync(sfdxPath)) {
+    console.error('Error: sfdx-project.json not found at project root.');
+    process.exit(1);
+  }
+  const sfdxProject = JSON.parse(readFileSync(sfdxPath, 'utf8'));
+  const pkgDir = sfdxProject?.packageDirectories?.[0]?.path;
+  if (!pkgDir) {
+    console.error('Error: No packageDirectories[].path found in sfdx-project.json.');
+    process.exit(1);
+  }
+  return resolve(ROOT, pkgDir, 'main', 'default', 'uiBundles');
+}
+
+function discoverUIBundleDir() {
+  const uiBundlesDir = resolveUIBundlesDir();
+  if (!existsSync(uiBundlesDir)) {
+    console.error(`Error: uiBundles directory not found: ${uiBundlesDir}`);
+    process.exit(1);
+  }
+  const entries = readdirSync(uiBundlesDir, { withFileTypes: true });
+  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
+  if (dirs.length === 0) {
+    console.error(`Error: No UI bundle folder found under ${uiBundlesDir}`);
+    process.exit(1);
+  }
+  if (dirs.length > 1) {
+    console.log(`Multiple UI bundles found; using first: ${dirs[0].name}`);
+  }
+  return resolve(uiBundlesDir, dirs[0].name);
+}
+
+function run(label, cmd, args, opts) {
+  console.log(`\n--- ${label} ---\n`);
+  const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+// Ensure .gitignore files exist (npm strips them from published packages).
+const gitignoreTemplates = loadGitignoreTemplates();
+if (gitignoreTemplates) {
+  ensureGitignore(ROOT, gitignoreTemplates.sfdx);
+  const bundlesDir = resolveUIBundlesDir();
+  if (existsSync(bundlesDir)) {
+    for (const entry of readdirSync(bundlesDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        ensureGitignore(resolve(bundlesDir, entry.name), gitignoreTemplates.webapp);
+      }
+    }
+  }
+}
+
+const uiBundleDir = discoverUIBundleDir();
+console.log('SFDX project root:', ROOT);
+console.log('UI bundle directory:', uiBundleDir);
+
+run('npm install', 'npm', ['install', '--registry', 'https://registry.npmjs.org/'], { cwd: uiBundleDir });
+run('npm run build', 'npm', ['run', 'build'], { cwd: uiBundleDir });

package/dist/scripts/soql/account.soql

@@ -0,0 +1,6 @@
+// Use .soql files to store SOQL queries.
+// You can execute queries in VS Code by selecting the
+//     query text and running the command:
+//     SFDX: Execute SOQL Query with Currently Selected Text
+
+SELECT Id, Name FROM Account

package/dist/scripts/validate-org-setup-config.mjs

@@ -0,0 +1,38 @@
+/**
+ * Build / CI gate: validate this package's org-setup.config.json against the
+ * shared schema (W-23043729, spec §5.2).
+ *
+ * Ships inside the SFDX project template, so a generated app can self-check its
+ * org-setup.config.json in its own CI:
+ *   npm run validate:org-setup-config
+ *
+ * Uses the SAME validateConfig + schema as org-setup.mjs runtime, so build-time
+ * and runtime checks can never drift. A missing config file is OK (not every
+ * project ships one); a present-but-invalid config fails the gate.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { validateConfig } from './org-setup-config-schema.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const configPath = resolve(__dirname, 'org-setup.config.json');
+
+if (!existsSync(configPath)) {
+  console.log('✓ org-setup.config.json: not present (nothing to validate)');
+  process.exit(0);
+}
+
+const result = validateConfig(readFileSync(configPath, 'utf8'), configPath);
+if (result.ok) {
+  console.log('✓ org-setup.config.json');
+  process.exit(0);
+}
+
+console.error('❌ org-setup.config.json is invalid:');
+for (const err of result.errors) {
+  console.error(`   - ${err}`);
+}
+process.exit(1);

package/dist/sfdx-project.json

@@ -0,0 +1,12 @@
+{
+  "packageDirectories": [
+    {
+      "path": "force-app",
+      "default": true
+    }
+  ],
+  "name": "MyProject",
+  "namespace": "",
+  "sfdcLoginUrl": "https://login.salesforce.com",
+  "sourceApiVersion": "67.0"
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@salesforce/ui-bundle-template-feature-react-customer-web-client-chat",
+  "version": "11.52.0",
+  "description": "Embedded Customer Web Client (Embedded Messaging) chat feature for UI Bundles",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "author": "",
+  "type": "module",
+  "main": "src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/index.ts",
+  "types": "src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/index.ts",
+      "import": "./src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/index.ts",
+      "default": "./src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "rules"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "react-router": "^8.0.0"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "executor": "@salesforce/ui-bundle-template-cli:apply-patches"
+      },
+      "watch": {
+        "executor": "@salesforce/ui-bundle-template-cli:watch-patches"
+      },
+      "build:dist-app": {
+        "executor": "@salesforce/ui-bundle-template-cli:build-dist-app"
+      },
+      "dev": {
+        "executor": "@salesforce/ui-bundle-template-cli:dev-server"
+      }
+    }
+  }
+}

package/src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/components/CustomerWebClientChat.tsx

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { useEffect } from "react";
+import type { CustomerWebClientChatProps, WindowWithCwcProperties } from "../types/chat";
+
+/**
+ * React wrapper that embeds the Customer Web Client (Embedded Messaging) chat
+ * widget into an external site. It dynamically loads the site's
+ * `embeddedservice_bootstrap` script and calls `init` with the org, deployment,
+ * site, and SCRT2 configuration. Renders nothing itself — the chat UI is a
+ * floating widget injected by the bootstrap script.
+ */
+export function CustomerWebClientChat({
+	orgId,
+	deploymentName,
+	siteURL,
+	scrt2URL,
+	language = "en",
+	devMode = false,
+}: CustomerWebClientChatProps) {
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		if (
+			!orgId ||
+			!deploymentName ||
+			!siteURL ||
+			!scrt2URL ||
+			!(orgId.length === 15 || orgId.length === 18)
+		) {
+			console.warn("[CustomerWebClientChat] missing required config; skipping init");
+			return;
+		}
+
+		const win = window as WindowWithCwcProperties;
+		const bootstrapSrc = `${siteURL}/assets/js/bootstrap.js`;
+		const existing = document.querySelector<HTMLScriptElement>(`script[src="${bootstrapSrc}"]`);
+		const script: HTMLScriptElement = existing ?? document.createElement("script");
+
+		const init = () => {
+			try {
+				if (!win.embeddedservice_bootstrap) return;
+				win.embeddedservice_bootstrap.settings.language = language;
+				if (devMode) win.embeddedservice_bootstrap.settings.devMode = true;
+				win.embeddedservice_bootstrap.init(orgId, deploymentName, siteURL, {
+					scrt2URL,
+				});
+			} catch (err) {
+				console.error("Error loading Embedded Messaging: ", err);
+			}
+		};
+
+		if (existing) {
+			if (win.embeddedservice_bootstrap) init();
+			else existing.addEventListener("load", init, { once: true });
+		} else {
+			script.type = "text/javascript";
+			script.src = bootstrapSrc;
+			script.addEventListener("load", init, { once: true });
+			document.body.appendChild(script);
+		}
+
+		return () => {
+			script.removeEventListener("load", init);
+		};
+	}, [orgId, deploymentName, siteURL, scrt2URL, language, devMode]);
+
+	return null;
+}
+
+export default CustomerWebClientChat;

package/src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * feature-react-customer-web-client-chat – Customer Web Client (Embedded Messaging) chat
+ */
+
+export { CustomerWebClientChat } from "./components/CustomerWebClientChat";
+export type { CustomerWebClientChatProps } from "./types/chat";

package/src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/pages/TestChatPage.tsx

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import CustomerWebClientChat from "../components/CustomerWebClientChat";
+
+export default function TestChatPage() {
+	return (
+		<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
+			<div className="text-center">
+				<h1 className="text-4xl font-bold text-gray-900 mb-4">Chat</h1>
+				<p className="text-lg text-gray-600 mb-8">
+					Welcome to your Customer Web Client chat application.
+				</p>
+			</div>
+			<CustomerWebClientChat
+				orgId="<ORG_ID_15_OR_18_CHAR_00D...>"
+				deploymentName="<EMBEDDED_SERVICE_DEPLOYMENT_NAME>"
+				siteURL="<SITE_URL>"
+				scrt2URL="<SCRT2_URL>"
+			/>
+		</div>
+	);
+}

package/src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/routes.tsx

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import type { RouteObject } from "react-router";
+import AppLayout from "./__inherit__appLayout";
+import TestChatPage from "./pages/TestChatPage";
+
+export const routes: RouteObject[] = [
+	{
+		path: "/",
+		element: <AppLayout />,
+		children: [
+			{
+				path: "test-chat",
+				element: <TestChatPage />,
+				handle: { showInNavigation: true, label: "Test Chat" },
+			},
+		],
+	},
+];

package/src/force-app/main/default/uiBundles/feature-react-customer-web-client-chat/src/types/chat.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/** Shape of the Embedded Messaging bootstrap global injected by the site's bootstrap.js. */
+export interface WindowWithCwcProperties extends Window {
+	embeddedservice_bootstrap?: {
+		settings: {
+			language: string;
+			devMode?: boolean;
+		};
+		init: (
+			orgId: string,
+			deploymentName: string,
+			siteURL: string,
+			options: { scrt2URL: string },
+		) => void;
+	};
+}
+
+export interface CustomerWebClientChatProps {
+	/** The organization id (15- or 18-char Salesforce id starting with `00D`). */
+	orgId: string;
+	/** The Embedded Service deployment / channel name the agent is connected to. */
+	deploymentName: string;
+	/** The ESW site URL. Usually contains `ESW` and the deployment name. */
+	siteURL: string;
+	/** The SCRT2 (Service Cloud Real-Time) chat service URL. Usually contains `scrt`. */
+	scrt2URL: string;
+	/** Optional chat language. Defaults to `"en"`. */
+	language?: string;
+	/** Optional. Enables Embedded Messaging dev mode. Defaults to `false`. */
+	devMode?: boolean;
+}