@assembly-js/app-bridge

Helper functions for postMessage communications between custom apps (embedded in iframes) and the Copilot parent application.

Installation

npm/yarn

npm install @assembly-js/app-bridge
# or
yarn add @assembly-js/app-bridge

Usage

npm Usage

import { AssemblyBridge } from "@assembly-js/app-bridge";

// Set breadcrumbs
AssemblyBridge.header.setBreadcrumbs([
  { label: "Dashboard" },
  { label: "Users", onClick: () => console.log("navigated") },
]);

// Set actions menu
AssemblyBridge.header.setActionsMenu([
  { label: "Download", icon: "Download", onClick: () => downloadFile() },
  {
    label: "Delete",
    icon: "Trash",
    color: "red",
    onClick: () => confirmDelete(),
  },
]);

API Reference

AssemblyBridge.header

setBreadcrumbs(items)

Set the breadcrumb navigation items in the header.

AssemblyBridge.header.setBreadcrumbs([
  { label: "Home" },
  { label: "Projects", onClick: () => navigateToProjects() },
  { label: "Current Project" },
]);

Parameters:

• items: Array of { label: string, onClick?: () => void }

setPrimaryCta(config)

Set or clear the primary CTA button.

// Set a CTA
AssemblyBridge.header.setPrimaryCta({
  label: "Save Changes",
  icon: "Check",
  onClick: () => save(),
});

// Clear the CTA
AssemblyBridge.header.setPrimaryCta(null);

Parameters:

• config: { label: string, icon?: Icon, onClick: () => void } or null

setSecondaryCta(config)

Set or clear the secondary CTA button. Same API as setPrimaryCta.

setActionsMenu(items)

Set the actions dropdown menu items.

AssemblyBridge.header.setActionsMenu([
  { label: "Archive", icon: "Archive", onClick: () => archive() },
  { label: "Delete", icon: "Trash", color: "red", onClick: () => remove() },
]);

Parameters:

• items: Array of { label: string, icon?: Icon, color?: 'red', onClick: () => void }

AssemblyBridge.configure(config)

Configure the bridge with additional settings.

AssemblyBridge.configure({
  additionalOrigins: ["portal.yourcompany.com", "https://custom-domain.com"],
  debug: true, // Enable debug logging
});

Parameters:

• config.additionalOrigins: Array of origins to allow for postMessage communication. Origins without a protocol default to HTTPS. Can be called multiple times - origins are cumulative.
• config.debug: Enable debug mode to log warnings to the console when messages cannot be sent (e.g., parent origin not in allowlist, not running in an iframe). Useful for troubleshooting.

Note: The bridge includes built-in support for *.copilot.app, *.myassembly.com, dashboard.assembly.com, localhost, and their staging equivalents. You only need to use configure() for custom portal domains. The parent origin is learned from the first source-verified parent message — document.referrer is not used.

AssemblyBridge.navigate(route, options?)

Navigate to a different route in the parent application.

// Navigate to settings
AssemblyBridge.navigate("settings");

// Navigate to a specific app
AssemblyBridge.navigate("apps", { id: "app-123" });

// Navigate to a specific form
AssemblyBridge.navigate("forms", { id: "form-456" });

Parameters:

• route: One of the supported routes (see below)
• options: Optional { id?: string }

AssemblyBridge.navigateTo(destination, options?)

Navigate to a typed destination and await the host's acknowledgement. Returns a promise that resolves with { ok: true } on success, { ok: false, reason } when the host rejects the navigation, or rejects after the timeout if the host never responds.

TypeScript enforces the required params for each destination at compile time.

// Navigate to a specific invoice
const result = await AssemblyBridge.navigateTo({ to: "invoice", invoiceId: "inv_abc" });
if (!result.ok) {
  console.warn("Navigation rejected:", result.reason);
}

// Navigate to a client detail page
await AssemblyBridge.navigateTo({ to: "client", clientId: "cli_xyz", tab: "notes" });

// Navigate to home
await AssemblyBridge.navigateTo({ to: "home" });

Supported destinations:

Options:

• replace: Replace the current history entry instead of pushing (default: false)
• newTab: Open in a new tab (default: false)
• timeout: Milliseconds to wait for host acknowledgement before rejecting (default: 10000)

AssemblyBridge.location.report(path, search, replace?)

Report the app's current location to the host. Call this on every client-side route change. The path must have any surface prefix stripped — report /orders/42, not /c/orders/42.

AssemblyBridge.location.report("/orders/42", "?tab=details");
AssemblyBridge.location.report("/dashboard", "");
// Signal a replace (no new history entry on the host):
AssemblyBridge.location.report("/settings", "", true);

Parameters:

• path: App-local path, surface prefix stripped (e.g. /orders/42).
• search: Query string including the leading ?, or '' when absent.
• replace: When true, the host should replace its history entry instead of pushing.

AssemblyBridge.location.onNavigate(handler)

Register a handler invoked whenever the host sends a location.navigate command. The handler receives a { path, search, replace? } payload with no surface prefix — the app must re-add its own prefix before navigating.

AssemblyBridge.location.onNavigate(({ path, search, replace }) => {
  const destination = `/c${path}${search}`;
  if (replace) {
    router.replace(destination);
  } else {
    router.push(destination);
  }
});

Parameters:

• handler: Called with { path: string; search: string; replace?: boolean }.

Supported Values

Icons

Available for CTAs: Archive, Plus, Templates, Trash, Check

Available for action menu items: Archive, Plus, Templates, Trash, Download, Check, Disconnect

Routes

• apps - Applications page (supports id for specific app)
• billing - Billing page
• contracts - Contracts page
• files - Files page (supports id for channel)
• forms - Forms page (supports id for specific form)
• helpdesk - Help desk page (supports id for specific article)
• invoices - Invoices page
• messages - Messages page (supports id for channel)
• notifications - Notifications page (supports id for channel)
• settings - Settings page
• settings.billing - Billing settings
• settings.profile - Profile settings
• products.create - Create product page
• products.edit - Edit product page (supports id for product)

TypeScript Support

The package includes TypeScript declarations. Import types as needed:

import type {
  BreadcrumbItem,
  CtaConfig,
  ActionMenuItem,
  Route,
  Icon,
  NavigateDestination,
  NavigateToOptions,
  NavigateResult,
} from "@assembly-js/app-bridge";

Development

# Install dependencies
yarn install

# Build
yarn build

# Type check
yarn type-check

# Run tests
yarn test

# Generate content-hashed files
yarn generate-manifest

License

MIT