@avaya/infinity-elements-sdk

CLI tool for scaffolding InfinityElement projects.

Table of Contents

• Installation
• Usage
  • Initialize a new project
  • Custom Element Naming Rules
  • Start development server
  • Build for production
• What it creates
• Element Properties (Variables)
  • How It Works
  • Example
  • Implementing Element Properties
  • Important Notes
• Authentication
  • ElementAPI: getAvayaJwt()
• License

Installation

npm install -g @avaya/infinity-elements-sdk

Usage

Initialize a new project

infinity init my-element
cd my-element

Custom Element Naming Rules

Your element name must follow the W3C Custom Elements specification:

| Rule | Valid | Invalid | | -------------------------------- | ---------------------------- | ----------------------------- | | Must contain a hyphen | my-element, user-profile | myelement, profile | | Must start with lowercase letter | my-element | 1-element, -element | | All lowercase | my-element | My-Element, myElement | | No reserved names | my-annotation | annotation-xml, font-face |

Reserved names (cannot be used): annotation-xml, color-profile, font-face, font-face-src, font-face-uri, font-face-format, font-face-name, missing-glyph

Start development server

infinity dev

Build for production

infinity build

What it creates

The CLI scaffolds a complete React project that compiles to a web component using r2wc:

• React component with TypeScript
• CSS Modules for styling
• Vite for building and dev server
• Ready-to-use web component

Element Properties (Variables)

InfinityElements support configurable properties that administrators set in the Infinity Configuration UI. These properties are passed to your web component as HTML attributes, which r2wc automatically converts to React props.

How It Works

1. Admin Configuration: In the Configuration UI, administrators add name/value pairs to the element's "Properties" section
2. Attribute Injection: When your element loads, these properties become HTML attributes
3. React Props: The r2wc library automatically maps these attributes to your element's props

Example

Admin sets properties: | Name | Value | |------|-------| | theme | dark | | customer-name | John Doe |

Your element receives:

<my-element theme="dark" customer-name="John Doe"></my-element>

Implementing Element Properties

1. Define props in your React component:

// src/Element.tsx
interface ElementProps {
  theme?: string;
  customerName?: string;
  maxItems?: string; // Note: all values are strings
}

const Element: React.FC<ElementProps> = ({
  theme = "light",
  customerName,
  maxItems = "10",
}) => {
  const max = parseInt(maxItems, 10); // Convert to number if needed

  return (
    <div className={theme === "dark" ? styles.dark : styles.light}>
      {customerName && <h2>Welcome, {customerName}</h2>}
      {/* Your element content */}
    </div>
  );
};

2. Register props in the web component wrapper:

// src/index.ts
import r2wc from "@r2wc/react-to-web-component";
import Element from "./Element";

const WebElement = r2wc(Element, React, ReactDOM, {
  props: {
    theme: "string",
    customerName: "string",
    maxItems: "string",
  },
});

customElements.define("my-element", WebElement);

Important Notes

• ⚠️ All values are strings: HTML attributes are always strings; parse numbers/booleans in your element
• ⚠️ Props must be declared: Only props listed in the r2wc props object will be passed to React
• ✅ Provide defaults: Always set sensible defaults since properties are optional
• ✅ Use kebab-case for HTML attributes: r2wc automatically converts between kebab-case HTML attributes (e.g., customer-name) and camelCase React props (e.g., customerName)

Authentication

Web components can authenticate using Keycloak's OAuth 2.0 PKCE flow via popup window, enabling secure access to protected resources with session persistence in browser storage.

ElementAPI: getAvayaJwt()

The simplest way to authenticate is using the getAvayaJwt() method from @avaya/infinity-elements-api:

import { ElementAPI } from "@avaya/infinity-elements-api";

const api = new ElementAPI({ elementId: "my-element" });

// Get JWT (cached, auto-refreshed, deduplicated across iframes)
const jwt = await api.getAvayaJwt({
  redirectUri: "https://myapp.com/callback",
});

// Use JWT for API calls
const response = await fetch("https://api.example.com/data", {
  headers: { Authorization: `Bearer ${jwt}` },
});

Features:

• ✅ Returns cached token from localStorage if available and not expired
• ✅ Automatically refreshes expired tokens using refresh token
• ✅ Prevents duplicate OAuth popups across multiple iframes/elements
• ✅ Initiates Keycloak OAuth PKCE flow if no token exists

See the @avaya/infinity-elements-api API.md in (/@avaya/infinity-elements-sdk/project/docs/)for full API reference and oauth-coordination-analysis.md for details on how duplicate popups are prevented.

License

MIT