@salesforce/webapp-template-app-react-sample-b2x-experimental 1.79.2 → 1.80.1

package/dist/.a4drules/features/feature-react-agentforce-conversation-client-embedded-agent-rule.md

@@ -6,27 +6,13 @@ paths:
 
 # Agentforce Conversation Client (standards)
 
-When adding or editing the embedded Agentforce chat client in this project, follow these conventions.
+## DO NOT build a chat UI from scratch
 
-## Component and library
+When the user asks for a chat UI, chat widget, chatbot, agent, or conversational interface — **always use the existing `AgentforceConversationClient` component** from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. Never generate a custom chat implementation, third-party chat library, WebSocket/REST chat, or direct calls to `embedAgentforceClient`.
 
-- Use the shared **AgentforceConversationClient** React component from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. Do not call `embedAgentforceClient` directly in application code.
-- Install with `npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. The underlying SDK (`@salesforce/agentforce-conversation-client`) is included automatically as a dependency.
+## Hard constraints
 
-## Authentication
-
-- The component resolves auth automatically: **localhost** fetches `frontdoorUrl` from `/__lo/frontdoor`; **production** uses `window.location.origin` as `salesforceOrigin`.
-- Do not hard-code `salesforceOrigin` or `frontdoorUrl` unless the consumer explicitly provides them as props.
-
-## Rendering mode
-
-- Pass `agentforceClientConfig.renderingConfig.mode` to select **floating** (default) or **inline**. Do not apply custom positioning CSS to override the built-in layout.
-- For inline mode, set `width` and `height` in `renderingConfig`. Do not override iframe dimensions with external CSS.
-
-## Agent selection
-
-- Use `agentforceClientConfig.agentId` to select a specific agent. Ask the user for the agent ID; if not provided, note that the org's default agent is used.
-
-## Placement
-
-- Render `<AgentforceConversationClient />` inside the existing app layout (e.g. alongside `<Outlet />`). Do not replace the entire page shell with the chat client.
+- **`agentId` is required.** The component will not work without it. Always ask the user for their agent ID before generating code. Do not proceed without one.
+- **Use the React wrapper only.** Import `AgentforceConversationClient` from the package. Never call `embedAgentforceClient` directly.
+- **One instance per window.** Render in the app layout alongside `<Outlet />`, not on individual pages. The component is a singleton.
+- **No auth hard-coding.** The component resolves `salesforceOrigin` and `frontdoorUrl` automatically.

package/dist/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent/SKILL.md

@@ -1,13 +1,45 @@
 ---
 name: feature-react-agentforce-conversation-client-embedded-agent
-description: Embed an Agentforce conversation client (chat UI) into a React web application. Use when the user wants to add an employee agent, a chat client, chatbot, chat widget, chat component, conversation client, or conversational interface to their React app. Also applies when the user asks to embed or integrate any Salesforce agent — including employee agent, travel agent, HR agent, service agent, or any custom-named agent — or mentions Agentforce, Agentforce widget, Agentforce chat, or agent chat.
+description: Embed an Agentforce conversation client (chat UI) into a React web application. Use when the user wants to add an employee agent, a chat client, chatbot, chat widget, chat component, conversation client, or conversational interface to their React app. Also applies when the user asks to embed or integrate any Salesforce agent — including employee agent, travel agent, HR agent, or any custom-named agent — or mentions Agentforce, Agentforce widget, Agentforce chat, or agent chat. ALWAYS use this skill instead of building a chat UI from scratch. Do NOT generate custom chat components, use third-party chat libraries, or create WebSocket/REST chat implementations. Do NOT use for non-React contexts or Lightning Web Components without React.
 ---
 
 # Embedded Agentforce chat (workflow)
 
 When the user wants an embedded Agentforce chat client in a React app, follow this workflow.
 
-## 1. Install the package
+## DO NOT build a chat UI from scratch
+
+When the user asks for a chat UI, chat widget, chatbot, conversational interface, agent embed, or anything related to an embedded agent — **always use the `AgentforceConversationClient` component** from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`.
+
+**Never do any of the following:**
+
+- Build a custom chat component from scratch (no custom message bubbles, input boxes, or chat layouts)
+- Use third-party chat libraries (e.g. `react-chat-widget`, `stream-chat`, `chatscope`, or similar)
+- Create WebSocket, polling, or REST-based chat implementations
+- Generate custom HTML/CSS chat UIs
+- Write a wrapper around `embedAgentforceClient` directly — always use the provided React component
+
+If the user asks for chat functionality that goes beyond what `AgentforceConversationClient` supports (e.g. custom message rendering, message history, typing indicators), explain that the embedded Agentforce client handles all of this internally and cannot be customized beyond the supported `agentforceClientConfig` options (`renderingConfig`, `styleTokens`, `agentId`).
+
+## CRITICAL: Agent ID is required
+
+The Agentforce Conversation Client **will not work** without an `agentId`. There is no default agent — the component renders nothing and silently fails if `agentId` is missing. **Always ask the user for their agent ID before writing any code.**
+
+> **Before proceeding:** Ask the user for their Salesforce agent ID (18-character record ID starting with `0Xx`). If they do not have one, direct them to **Setup → Agents** in their Salesforce org to find or create one. Do not generate code without an `agentId`.
+
+## 1. Collect the agent ID
+
+Ask the user:
+
+- "What is your Salesforce agent ID? (You can find it in Setup → Agents → select an agent → copy the ID from the URL. It's an 18-character ID starting with `0Xx`.)"
+
+If the user does not provide one:
+
+- Explain that the conversation client **requires** an agent ID and will not function without it.
+- Direct them to **Setup → Agents** in their org.
+- Do **not** proceed to generate the embed code until an agent ID is provided.
+
+## 2. Install the package
 
 ```bash
 npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
@@ -15,16 +47,16 @@ npm install @salesforce/webapp-template-feature-react-agentforce-conversation-cl
 
 This single install also brings in `@salesforce/agentforce-conversation-client` (the underlying SDK) automatically.
 
-## 2. Use the shared wrapper
+## 3. Use the shared wrapper
 
 Use the `AgentforceConversationClient` React component. It resolves auth automatically:
 
 - **Dev (localhost)**: fetches `frontdoorUrl` from `/__lo/frontdoor`
 - **Prod (hosted in org)**: uses `salesforceOrigin` from `window.location.origin`
 
-## 3. Embed in the layout
+## 4. Embed in the layout
 
-Render `<AgentforceConversationClient />` in the app layout so the chat client loads globally. Keep it alongside the existing layout (do not replace the page shell).
+Render `<AgentforceConversationClient />` in the app layout so the chat client loads globally. Keep it alongside the existing layout (do not replace the page shell). **Always pass `agentId`.**
 
 ```tsx
 import { Outlet } from "react-router";
@@ -34,37 +66,51 @@ export default function AppLayout() {
   return (
     <>
       <Outlet />
-      <AgentforceConversationClient />
+      <AgentforceConversationClient
+        agentforceClientConfig={{
+          agentId: "0Xx000000000000AAA",
+        }}
+      />
     </>
   );
 }
 ```
 
-## 4. Configure the agent
+Replace `"0Xx000000000000AAA"` with the agent ID provided by the user.
 
-Pass options via the `agentforceClientConfig` prop:
+## 5. Configure rendering and theming (optional)
 
-| Option                             | Purpose                                           |
-| ---------------------------------- | ------------------------------------------------- |
-| `renderingConfig.mode`             | `"floating"` (default) or `"inline"`              |
-| `renderingConfig.width` / `height` | Inline dimensions (number for px, string for CSS) |
-| `agentId`                          | Select a specific agent from the org              |
-| `styleTokens`                      | Theme colors and style overrides                  |
+Pass additional options via the `agentforceClientConfig` prop:
+
+| Option                             | Purpose                                                    | Required |
+| ---------------------------------- | ---------------------------------------------------------- | -------- |
+| `agentId`                          | The agent to load — **required, will not work without it** | **Yes**  |
+| `renderingConfig.mode`             | `"floating"` (default) or `"inline"`                       | No       |
+| `renderingConfig.width` / `height` | Inline dimensions (number for px, string for CSS)          | No       |
+| `styleTokens`                      | Theme colors and style overrides                           | No       |
 
 See [embed-examples.md](docs/embed-examples.md) for complete examples of each mode.
 
-## 5. Validate prerequisites
+## 6. Validate prerequisites
+
+Before the conversation client will work, the user must verify all of the following in their Salesforce org:
 
-- The org must allow `localhost:<PORT>` in **Trusted Domains for Inline Frames** (session settings).
+1. **Agent is active:** The org must have the agent referenced by `agentId` in an **Active** state and deployed to the correct channel (**Setup → Agents**).
+2. **Trusted domains:** The org must allow `localhost:<PORT>` in **Trusted Domains for Inline Frames** (**Setup → Session Settings → Trusted Domains for Inline Frames**). Required for local development.
+3. **First-party cookies disabled:** **"Require first party use of Salesforce cookies"** must be **unchecked/disabled** in **Setup → My Domain**. If this setting is enabled, the embedded conversation client will fail to authenticate and will not load.
 
 ## Quick reference: rendering modes
 
-### Floating (default)
+### Floating (default rendering mode)
 
-A persistent chat widget overlay pinned to the bottom-right corner. No extra config needed — floating is the default.
+A persistent chat widget overlay pinned to the bottom-right corner. Floating is the default rendering mode — but `agentId` is still required.
 
 ```tsx
-<AgentforceConversationClient />
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
+  }}
+/>
 ```
 
 ### Inline
@@ -74,6 +120,7 @@ The chat renders within the page layout at a specific size.
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "inline", width: 420, height: 600 },
   }}
 />
@@ -86,6 +133,7 @@ Use `styleTokens` to customize the chat appearance.
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#0176d3",
       headerBlockTextColor: "#ffffff",
@@ -95,14 +143,6 @@ Use `styleTokens` to customize the chat appearance.
 />
 ```
 
-### Agent selection
-
-Pass `agentId` to load a specific agent (e.g. travel agent, HR agent).
+## Troubleshooting
 
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000",
-  }}
-/>
-```
+If the chat widget does not appear, fails to authenticate, or behaves unexpectedly, see [troubleshooting.md](docs/troubleshooting.md).

package/dist/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent/docs/embed-examples.md

@@ -2,16 +2,22 @@
 
 Detailed examples for configuring the Agentforce Conversation Client. All examples use the `AgentforceConversationClient` React component; the underlying `embedAgentforceClient` API accepts the same `agentforceClientConfig` shape.
 
+> **Important:** Every example requires an `agentId`. The component will not render without one. There is no default agent. Replace `"0Xx000000000000AAA"` in every example with the user's actual agent ID.
+
 ---
 
-## Floating mode (default)
+## Floating mode (default rendering mode)
 
-A floating chat widget appears in the bottom-right corner. It starts minimized and expands when the user clicks it. This is the default — no `renderingConfig` is required.
+A floating chat widget appears in the bottom-right corner. It starts minimized and expands when the user clicks it. Floating is the default rendering mode — no `renderingConfig` is needed — but `agentId` is always required.
 
-### Minimal (no config)
+### Minimal
 
 ```tsx
-<AgentforceConversationClient />
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
+  }}
+/>
 ```
 
 ### Explicit floating
@@ -19,18 +25,19 @@ A floating chat widget appears in the bottom-right corner. It starts minimized a
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
   }}
 />
 ```
 
-### Floating with a specific agent and theme
+### Floating with theming
 
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
-    agentId: "0Xx000000000000",
     styleTokens: {
       headerBlockBackground: "#032D60",
       headerBlockTextColor: "#ffffff",
@@ -50,6 +57,7 @@ The chat renders inside the parent container at a specific size. Use this when t
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "inline", width: 420, height: 600 },
   }}
 />
@@ -60,6 +68,7 @@ The chat renders inside the parent container at a specific size. Use this when t
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "inline", width: "100%", height: "80vh" },
   }}
 />
@@ -73,6 +82,7 @@ The chat renders inside the parent container at a specific size. Use this when t
   <aside style={{ width: 400 }}>
     <AgentforceConversationClient
       agentforceClientConfig={{
+        agentId: "0Xx000000000000AAA",
         renderingConfig: { mode: "inline", width: "100%", height: "100%" },
       }}
     />
@@ -91,6 +101,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#0176d3",
       headerBlockTextColor: "#ffffff",
@@ -104,6 +115,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#0176d3",
       headerBlockTextColor: "#ffffff",
@@ -118,6 +130,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#1a1a2e",
       headerBlockTextColor: "#e0e0e0",
@@ -129,40 +142,37 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 
 ---
 
-## Agent selection
-
-Use `agentId` to load a specific agent from the org. If omitted, the org's default employee agent is used.
-
-### Specific agent by ID
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000",
-  }}
-/>
-```
+## Full layout example
 
-### Agent with inline mode and theming
+Shows the recommended pattern: agent ID passed directly, single render in the app layout.
 
 ```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000",
-    renderingConfig: { mode: "inline", width: 400, height: 700 },
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-    },
-  }}
-/>
+import { Outlet } from "react-router";
+import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+
+export default function AppLayout() {
+  return (
+    <>
+      <Outlet />
+      <AgentforceConversationClient
+        agentforceClientConfig={{
+          agentId: "0Xx000000000000AAA",
+          styleTokens: {
+            headerBlockBackground: "#0176d3",
+            headerBlockTextColor: "#ffffff",
+          },
+        }}
+      />
+    </>
+  );
+}
 ```
 
 ---
 
 ## Using the low-level `embedAgentforceClient` API
 
-The React component wraps `embedAgentforceClient`. If you need the raw API (e.g. in a non-React context), the config shape is the same:
+The React component wraps `embedAgentforceClient`. If you need the raw API (e.g. in a non-React context), the config shape is the same — `agentId` is still required:
 
 ```ts
 import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
@@ -171,7 +181,7 @@ const { loApp, chatClientComponent } = embedAgentforceClient({
   container: "#agentforce-container",
   salesforceOrigin: "https://myorg.my.salesforce.com",
   agentforceClientConfig: {
-    agentId: "0Xx000000000000",
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
     styleTokens: {
       headerBlockBackground: "#0176d3",

package/dist/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent/docs/troubleshooting.md

@@ -0,0 +1,51 @@
+# Troubleshooting
+
+Common issues when using the Agentforce Conversation Client.
+
+---
+
+### Chat widget does not appear
+
+**Cause:** Missing or invalid `agentId`. The component will not render anything without a valid agent ID.
+
+**Solution:**
+
+1. Verify `agentId` is passed in `agentforceClientConfig` — it is required
+2. Confirm the ID is correct (18-character Salesforce record ID, starts with `0Xx`)
+3. Check that the agent exists and is **Active** in **Setup → Agents**
+
+### Chat loads but shows "agent not available"
+
+**Cause:** The agent exists but is not deployed or is inactive.
+
+**Solution:**
+
+1. In **Setup → Agents**, ensure the agent status is **Active**
+2. Verify the agent is deployed to the correct channel
+
+### Authentication error on localhost
+
+**Cause:** `localhost:<PORT>` is not in the org's trusted domains for inline frames.
+
+**Solution:**
+
+1. Go to **Setup → Session Settings → Trusted Domains for Inline Frames**
+2. Add `localhost:<PORT>` (e.g. `localhost:3000`)
+3. Restart the dev server
+
+### Chat fails to authenticate / blank iframe
+
+**Cause:** "Require first party use of Salesforce cookies" is enabled in the org's session settings. This blocks the embedded client from establishing a session.
+
+**Solution:**
+
+1. Go to **Setup → Session Settings**
+2. Find **"Require first party use of Salesforce cookies"**
+3. **Uncheck / disable** this setting
+4. Save and reload the app
+
+### Multiple chat widgets appear
+
+**Cause:** `AgentforceConversationClient` is rendered in multiple places.
+
+**Solution:** Render it once in the app layout, not on individual pages. The component uses a singleton pattern — only one instance should exist per window.

package/dist/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.80.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.80.0...v1.80.1) (2026-03-09)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+# [1.80.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.79.2...v1.80.0) (2026-03-07)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 ## [1.79.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.79.1...v1.79.2) (2026-03-06)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/classes/WebAppAuthUtils.cls

@@ -0,0 +1,68 @@
+/**
+ * Utility class for Web Application authentication REST endpoints.
+ */
+public without sharing class WebAppAuthUtils {
+
+    /**
+     * Exception for authentication errors with HTTP status code support.
+     */
+    public class AuthException extends Exception {
+        public Integer statusCode { get; private set; } // HTTP status code (e.g. 400, 500)
+        public List<String> messages { get; private set; } // List of error messages
+
+        public AuthException(Integer statusCode, String message) {
+            this.statusCode = statusCode;
+            this.messages = new List<String>{ message };
+        }
+
+        public AuthException(Integer statusCode, List<String> messages) {
+            this.statusCode = statusCode;
+            this.messages = new List<String>(messages);
+        }
+    }
+
+    /**
+     * Validates and sanitizes redirect URL to prevent open redirect vulnerabilities.
+     * @param url The URL to validate.
+     * @param defaultUrl Fallback URL if validation fails.
+     * @return Sanitized URL or defaultUrl if invalid.
+     */
+    public static String getSanitizedStartUrl(String url, String defaultUrl) {
+        if (String.isBlank(url) || url.equals('/')) { return defaultUrl; }
+        
+        String decoded; // Decode URL to catch encoded bypasses (%2f%2f -> //)
+        try {
+            decoded = EncodingUtil.urlDecode(url, 'UTF-8');
+        } catch (Exception e) {
+            return defaultUrl;
+        }
+        
+        // Must start with / but not // (protocol-relative)
+        if (!decoded.startsWith('/') || decoded.startsWith('//')) { return defaultUrl; }
+        // Reject backslashes (some browsers treat \ as /)
+        if (decoded.contains('\\')) { return defaultUrl; }
+        // Reject @ which can indicate user info in URL (//user@evil.com)
+        if (decoded.contains('@')) { return defaultUrl; }
+        // Reject : which could indicate protocol or port manipulation
+        if (decoded.contains(':')) { return defaultUrl; }
+        // Reject control characters (ASCII < 32) and DEL (127)
+        for (Integer i = 0; i < decoded.length(); i++) {
+            Integer charCode = decoded.charAt(i);
+            if (charCode < 32 || charCode == 127) { return defaultUrl; }
+        }
+        
+        return defaultUrl + url;
+    }
+
+    /**
+     * Logs an error message and stack trace to the system debug log.
+     * It is only captured if a Trace Flag is active for the user.
+     * 
+     * @param ex The exception to log.
+     * @param level The logging level to use.
+     */
+    public static void debugLog(Exception ex, LoggingLevel level) {
+        System.debug(level, 'Message: ' + ex.getMessage());
+        System.debug(level, 'Stack Trace: ' + ex.getStackTraceString());
+    }
+}

package/dist/force-app/main/default/classes/WebAppAuthUtils.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

package/dist/force-app/main/default/classes/WebAppChangePassword.cls

@@ -0,0 +1,77 @@
+/**
+ * Web Applications REST endpoint for authenticated user password changes.
+ * 
+ * Endpoint: POST /services/apexrest/auth/change-password
+ * 
+ * Allows authenticated users to change their password by providing their current password
+ * and a new password. The new password is validated against org password policies.
+ * 
+ * Security: Uses 'with sharing' to enforce user-level security. Only authenticated users
+ * can change their own password.
+ */
+@RestResource(urlMapping='/auth/change-password')
+global with sharing class WebAppChangePassword {
+
+    /**
+     * Changes the password for the currently authenticated user.
+     * 
+     * @param newPassword The new password to set.
+     * @param currentPassword The user's current password for verification.
+     * @return SuccessPasswordChangeResponse on success, ErrorPasswordChangeResponse on failure.
+     */
+    @HttpPost
+    global static PasswordChangeResponse changePassword(String newPassword, String currentPassword) {
+        Savepoint sp = Database.setSavepoint();
+        try {
+            // newPassword and confirmPassword should be validated to be the same value on the client
+            Site.changePassword(newPassword, newPassword, currentPassword);
+            return new SuccessPasswordChangeResponse();
+        } catch (Exception ex) {
+            Database.rollback(sp);
+
+            // System.SecurityException is a user error but treat others as system errors
+            if (ex instanceof System.SecurityException) {
+                RestContext.response.statusCode = 400;
+                return new ErrorPasswordChangeResponse(ex.getMessage());
+            }
+
+            // Logs are only captured if a Trace Flag is active for the user
+            WebAppAuthUtils.debugLog(ex, LoggingLevel.ERROR);
+
+            RestContext.response.statusCode = 500;
+            return new ErrorPasswordChangeResponse('Password change failed');
+        }
+    }
+
+    /** Base response class for password change operations. */
+    global abstract class PasswordChangeResponse {
+        
+        /** Success or failure of the password change operation */
+        protected final Boolean success;
+    }
+
+    /** Success response for password change. */
+    global class SuccessPasswordChangeResponse extends PasswordChangeResponse {
+
+        /** Constructs a success response. */
+        private SuccessPasswordChangeResponse() {
+            this.success = true;
+        }
+    }
+
+    /** Error response for password change. */
+    global class ErrorPasswordChangeResponse extends PasswordChangeResponse {
+
+        /** Error message describing the failure reason */
+        private final String error;
+        
+        /**
+         * Constructs an error response with the specified error message.
+         * @param error The error message to return to the client.
+         */
+        private ErrorPasswordChangeResponse(String error) {
+            this.success = false;
+            this.error = error;
+        }
+    }
+}

package/dist/force-app/main/default/classes/WebAppChangePassword.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>66.0</apiVersion>
+    <status>Active</status>
+</ApexClass>