@salesforce/agentforce-conversation-client 0.5.2

package/LICENSE.txt

@@ -0,0 +1,82 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this
+software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were
+last updated on April 15, 2025, and constitute a legally binding
+agreement between you and Salesforce. If you do not agree to these Terms of
+Use, do not install or use the Software.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free
+copyright license to reproduce, prepare derivative works of, publicly
+display, publicly perform, sublicense, and distribute the Software and
+derivative works subject to these Terms. These Terms shall be included in
+all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce
+reserves all rights, title, and interest in and to all intellectual
+property subsisting in the Software. No rights are granted to you hereunder
+other than as expressly set forth herein. Users residing in countries on
+the United States Office of Foreign Assets Control sanction list, or which
+are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you
+are responsible. The Software may contain bugs, errors and
+incompatibilities and is made available on an AS IS basis without support,
+updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or
+discontinue, the Software (or any part thereof) with or without notice. You
+agree that Salesforce shall not be liable to you or to any third party for
+any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or
+proceeding made or brought against Salesforce by a third party arising out
+of or accruing from (a) your use of the Software, and (b) any application
+you develop with the Software that infringes any copyright, trademark,
+trade secret, trade dress, patent, or other intellectual property right of
+any person or defames any person or violates their rights of publicity or
+privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce
+from any damages, attorney fees, and costs finally awarded against
+Salesforce as a result of, or for any amounts paid by Salesforce under a
+settlement approved by you in writing of, a Claim Against Salesforce,
+provided Salesforce (x) promptly gives you written notice of the Claim
+Against Salesforce, (y) gives you sole control of the defense and
+settlement of the Claim Against Salesforce (except that you may not settle
+any Claim Against Salesforce unless it unconditionally releases Salesforce
+of all liability), and (z) gives you all reasonable assistance, at your
+expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT
+SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES,
+INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA,
+OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN
+CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU
+HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of
+the State of California, without regard to its conflicts of laws
+rules. Each party hereby consents to the exclusive jurisdiction of the
+state and federal courts located in San Francisco County, California to
+adjudicate any dispute arising out of or relating to these Terms of Use and
+the download, installation, and/or use of the Software. Except as expressly
+stated herein, these Terms of Use constitute the entire agreement between
+the parties, and supersede all prior and contemporaneous agreements,
+proposals, or representations, written or oral, concerning their subject
+matter. No modification, amendment, or waiver of any provision of these
+Terms of Use shall be effective unless it is by an update to these Terms of
+Use that Salesforce makes available, or is in writing and signed by the
+party against whom the modification, amendment, or waiver is to be
+asserted.
+
+Data Privacy: Salesforce may collect, process, and store device,
+system, and other information related to your use of the Software. This
+information includes, but is not limited to, IP address, user metrics, and
+other data ("Usage Data"). Salesforce may use Usage Data for analytics,
+product development, and marketing purposes. You acknowledge that files
+generated in conjunction with the Software may contain sensitive or
+confidential data, and you are solely responsible for anonymizing and
+protecting such data.

package/README.md

@@ -0,0 +1,139 @@
+# @salesforce/agentforce-conversation-client
+
+Agentforce Conversation Client SDK for embedding the Agentforce chat experience into external applications. By default, Lightning Out 2.0 is embedded within the target container.
+
+## Overview
+
+This library embeds the Agentforce Conversation Client using Lightning Out 2.0. The `salesforceOrigin` option is passed to the Lightning Out application as the `org-url` attribute.
+
+## Prerequisites
+
+- The hosting application must already have a valid Salesforce session established (for example, via SSO or an existing authenticated Salesforce context).
+- Lightning Out uses the existing session to initialize; without it, the embed will fail to start.
+
+## Installation
+
+```bash
+npm install @salesforce/agentforce-conversation-client
+```
+
+## Usage
+
+### Basic Embedding
+
+```typescript
+import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
+
+const { loApp, chatClientComponent } = embedAgentforceClient({
+  container: "#agentforce-container",
+  salesforceOrigin: "https://myorg.my.salesforce.com",
+});
+```
+
+### With Configuration
+
+```typescript
+import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
+
+const { loApp, chatClientComponent } = embedAgentforceClient({
+  container: "#agentforce-container",
+  salesforceOrigin: "https://myorg.my.salesforce.com",
+  agentforceClientConfig: {
+    styleProperties: {
+      MessageBlockInboundColor: "#0176d3",
+    },
+    mode: "Inline", // or "Floating"
+  },
+});
+```
+
+### Listening for Events
+
+```typescript
+const { loApp } = embedAgentforceClient({
+  container: "#agentforce-container",
+  salesforceOrigin: "https://myorg.my.salesforce.com",
+});
+
+loApp.addEventListener("lo.application.ready", () => {
+  console.log("Lightning Out is ready");
+});
+
+loApp.addEventListener("lo.component.ready", (event) => {
+  console.log("Component ready:", event.detail.componentName);
+});
+
+loApp.addEventListener("lo.application.error", (event) => {
+  console.error("Error:", event.detail);
+});
+```
+
+## API
+
+### `embedAgentforceClient(options)`
+
+Embeds the Agentforce Conversation Client into a specified DOM container. By default, Lightning Out is embedded within the target container.
+
+#### Parameters
+
+| Parameter                        | Type                     | Required | Description                               |
+| -------------------------------- | ------------------------ | -------- | ----------------------------------------- |
+| `options.container`              | `string \| HTMLElement`  | Yes      | CSS selector or HTMLElement to embed into |
+| `options.salesforceOrigin`       | `string`                 | Yes      | Salesforce org origin URL                 |
+| `options.frontdoorUrl`           | `string`                 | No       | Frontdoor URL for authentication          |
+| `options.agentforceClientConfig` | `AgentforceClientConfig` | No       | Configuration for the Agentforce client   |
+
+#### Returns
+
+| Property              | Type                      | Description                       |
+| --------------------- | ------------------------- | --------------------------------- |
+| `loApp`               | `LightningOutApplication` | The Lightning Out application     |
+| `chatClientComponent` | `HTMLElement`             | The chat client component element |
+
+### Component Constants
+
+These constants define the Lightning Out component tag and namespace.
+
+```typescript
+export const AGENTFORCE_CLIENT_ELEMENT_TAG = "runtime_copilot-acc-sdk-wrapper";
+export const AGENTFORCE_CLIENT_NAMESPACE = "runtime_copilot";
+export const AGENTFORCE_CLIENT_COMPONENT_NAME = "accSdkWrapper";
+```
+
+## Types
+
+```typescript
+// Accepts any style property key-value pairs
+type StyleProperties = Record<string, string>;
+
+interface AgentforceClientConfig {
+  styleProperties?: StyleProperties;
+  mode?: "Inline" | "Floating";
+}
+
+interface EmbedAgentforceClientOptions {
+  container: string | HTMLElement;
+  salesforceOrigin: string;
+  frontdoorUrl?: string;
+  agentforceClientConfig?: AgentforceClientConfig;
+}
+
+interface EmbedAgentforceClientResult {
+  loApp: LightningOutApplication;
+  chatClientComponent: HTMLElement;
+}
+```
+
+## Development
+
+```bash
+# Build the package
+npm run build
+
+# Watch mode for development
+npm run dev
+```
+
+## License
+
+See LICENSE file in the repository root.

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { LightningOutApplication } from "@lightning-out/application";
+/**
+ * The ACC wrapper component name used by Lightning Out
+ */
+export declare const AGENTFORCE_CLIENT_ELEMENT_TAG = "runtime_copilot-acc-sdk-wrapper";
+/**
+ * The namespace used by Lightning Out
+ */
+export declare const AGENTFORCE_CLIENT_NAMESPACE = "runtime_copilot";
+/**
+ * The component name used by Lightning Out
+ */
+export declare const AGENTFORCE_CLIENT_COMPONENT_NAME = "accSdkWrapper";
+/**
+ * Styling options for the Agentforce client
+ * Accepts any style property key-value pairs
+ */
+export type StyleTokens = Record<string, string>;
+/**
+ * Agentforce client configuration options
+ */
+export interface AgentforceClientConfig {
+    /** Styling options */
+    styleTokens?: StyleTokens;
+    /** Display mode - Inline or Floating */
+    mode?: "Inline" | "Floating";
+}
+/**
+ * Options for embedding the Agentforce client
+ */
+export interface EmbedAgentforceClientOptions {
+    /** CSS selector or HTMLElement */
+    container: string | HTMLElement;
+    /** Salesforce org origin URL (used as endpoint for component resolution) */
+    salesforceOrigin: string;
+    /** Frontdoor URL for authentication */
+    frontdoorUrl?: string;
+    /** Agentforce client configuration */
+    agentforceClientConfig?: AgentforceClientConfig;
+}
+/**
+ * Result of embedding the Agentforce client
+ */
+export interface EmbedAgentforceClientResult {
+    /** The Lightning Out application element */
+    loApp: LightningOutApplication;
+    /** The chat client component element */
+    chatClientComponent: HTMLElement;
+}
+/**
+ * Embeds the Agentforce Conversation Client into a specified DOM container.
+ *
+ * @param options - Configuration options
+ * @returns The created elements
+ * @throws Error if required options are missing
+ *
+ * @example
+ * ```ts
+ * embedAgentforceClient({
+ *   container: '#agentforce-conversation-client-container',
+ *   salesforceOrigin: 'https://myorg.my.salesforce.com',
+ *   agentforceClientConfig: { styleTokens: { MessageBlockInboundColor: '#0176d3' } }
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Listen for Lightning Out events after embedding
+ * const { loApp } = embedAgentforceClient({ ... });
+ *
+ * loApp.addEventListener('lo.application.ready', () => {
+ *   console.log('Lightning Out is ready');
+ * });
+ *
+ * loApp.addEventListener('lo.component.ready', (event) => {
+ *   console.log('Component ready:', event.detail.componentName);
+ * });
+ * ```
+ */
+export declare function embedAgentforceClient(options?: EmbedAgentforceClientOptions | null): EmbedAgentforceClientResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,6BAA6B,oCAAoC,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,2BAA2B,oBAAoB,CAAC;AAE7D;;GAEG;AACH,eAAO,MAAM,gCAAgC,kBAAkB,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,sBAAsB;IACtB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wCAAwC;IACxC,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C,kCAAkC;IAClC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,4CAA4C;IAC5C,KAAK,EAAE,uBAAuB,CAAC;IAC/B,wCAAwC;IACxC,mBAAmB,EAAE,WAAW,CAAC;CACjC;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,CAAC,EAAE,4BAA4B,GAAG,IAAI,GAC3C,2BAA2B,CAkB7B"}

package/dist/index.js

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import { LightningOutApplication } from "@lightning-out/application";
+/**
+ * The ACC wrapper component name used by Lightning Out
+ */
+export const AGENTFORCE_CLIENT_ELEMENT_TAG = "runtime_copilot-acc-sdk-wrapper";
+/**
+ * The namespace used by Lightning Out
+ */
+export const AGENTFORCE_CLIENT_NAMESPACE = "runtime_copilot";
+/**
+ * The component name used by Lightning Out
+ */
+export const AGENTFORCE_CLIENT_COMPONENT_NAME = "accSdkWrapper";
+/**
+ * Resolves a container parameter to an HTMLElement
+ * @param container - CSS selector or HTMLElement
+ * @returns The resolved HTMLElement or null if not found
+ * @internal
+ */
+function resolveContainer(container) {
+    if (container instanceof HTMLElement)
+        return container;
+    if (typeof container === "string")
+        return document.querySelector(container);
+    return null;
+}
+/**
+ * Create and configure the Lightning Out application and chat client component
+ * @param container - The container element
+ * @param salesforceOrigin - The Salesforce origin URL
+ * @param agentforceClientConfig - Configuration for the Agentforce client
+ * @returns The created Lightning Out app and chat client component
+ * @internal
+ */
+function createLightningOutApp(container, salesforceOrigin, frontdoorUrl, agentforceClientConfig) {
+    const loApp = new LightningOutApplication();
+    loApp.setAttribute("org-url", salesforceOrigin);
+    loApp.setAttribute("components", `${AGENTFORCE_CLIENT_NAMESPACE}/${AGENTFORCE_CLIENT_COMPONENT_NAME}`);
+    if (frontdoorUrl) {
+        loApp.setAttribute("frontdoor-url", frontdoorUrl);
+    }
+    container.appendChild(loApp);
+    const chatClientComponent = document.createElement(AGENTFORCE_CLIENT_ELEMENT_TAG);
+    chatClientComponent.configuration =
+        agentforceClientConfig;
+    container.appendChild(chatClientComponent);
+    loApp.addEventListener("lo.application.error", (event) => {
+        console.error("Agentforce Conversation Client: Lightning Out error:", event.detail);
+    });
+    return { loApp, chatClientComponent };
+}
+/**
+ * Embeds the Agentforce Conversation Client into a specified DOM container.
+ *
+ * @param options - Configuration options
+ * @returns The created elements
+ * @throws Error if required options are missing
+ *
+ * @example
+ * ```ts
+ * embedAgentforceClient({
+ *   container: '#agentforce-conversation-client-container',
+ *   salesforceOrigin: 'https://myorg.my.salesforce.com',
+ *   agentforceClientConfig: { styleTokens: { MessageBlockInboundColor: '#0176d3' } }
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Listen for Lightning Out events after embedding
+ * const { loApp } = embedAgentforceClient({ ... });
+ *
+ * loApp.addEventListener('lo.application.ready', () => {
+ *   console.log('Lightning Out is ready');
+ * });
+ *
+ * loApp.addEventListener('lo.component.ready', (event) => {
+ *   console.log('Component ready:', event.detail.componentName);
+ * });
+ * ```
+ */
+export function embedAgentforceClient(options) {
+    const { container, salesforceOrigin, frontdoorUrl, agentforceClientConfig = {} } = options ?? {};
+    if (!container)
+        throw new Error("Agentforce Conversation Client: container is required");
+    if (!salesforceOrigin)
+        throw new Error("Agentforce Conversation Client: salesforceOrigin is required");
+    const containerElement = resolveContainer(container);
+    if (!containerElement) {
+        throw new Error(`Agentforce Conversation Client: container not found: ${container}`);
+    }
+    return createLightningOutApp(containerElement, salesforceOrigin, frontdoorUrl, agentforceClientConfig);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@salesforce/agentforce-conversation-client",
+  "description": "Agentforce Conversation Client SDK for embedding via Lightning Out 2.0",
+  "version": "0.5.2",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "dev": "tsc --build --watch"
+  },
+  "dependencies": {
+    "@lightning-out/application": "2.1.1-rc.2"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "gitHead": "c85ca502ecb32ebdee7563a3477060f7ed529c9d"
+}