@omni-co/embed 0.3.20 → 0.4.0

package/README.md

@@ -40,7 +40,7 @@ const iframeUrl = await embedSsoDashboard({
 });
 
 // Alternatively you can create a signed embed sso link for a workbook
-onst iframeUrl = await embedSsoWorkbook({
+const iframeUrl = await embedSsoWorkbook({
   contentId: "miU0hL6z",
   externalId: "wile.e@coyote.co",
   name: "Wile E",
@@ -49,6 +49,20 @@ onst iframeUrl = await embedSsoWorkbook({
 });
 ```
 
+## Using Vanity Domains
+
+```ts
+// Use `host` to create a link to a vanity domain.
+// Note: `organizationName` and `domain` are incompatible with `host`
+const iframeUrl = await embedSsoDashboard({
+  contentId: "miU0hL6z",
+  externalId: "wile.e@coyote.co",
+  host: "omni.example.com",
+  name: "Wile E",
+  secret: "abcdefghijklmnopqrstuvwxyz123456",
+});
+```
+
 ## Kitchen Sink Example
 
 ```ts
@@ -78,47 +92,76 @@ type EmbedSsoProps = {
   // Short GUID of the dashboard. Can be obtained via the dashboard's url.
   contentId: string;
 
+  // Optional custom theme property that styles the embedded dashboard.
+  customTheme?: CustomThemeProperties;
+
+  // Optional identifier to associate the user with an external
+  // organization or system.
+  entity?: string;
+
   // Required identifier to associate the external user with an
   // automatically generated internal Omni user.
   externalId: string;
 
+  // Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
+  // Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"Aberdeen"%2C"Alabama"%5D%2C"is_negative"%3Afalse%7D&f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"UK"%5D%2C"is_negative"%3Afalse%7D
+  filterSearchParam?: string;
+
+  /**
+   * Used to set the host of signed embed URL, required when using vanity domains.
+   * Protocol is not required, as https is assumed.
+   * Port is not accepted. If required, use the `port` prop.
+   *
+   * @throws Error if `domain` or `organizationName` are provided.
+   * @example "omni.example.com"
+   * @example "omni.another-example.app"
+   */
+  host?: string;
+
+  // Optional link access setting to control which Omni dashboard links are shown. Note that regardless of the linkAccess value,
+  // all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
+  // "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
+  // "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
+  // undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
+  linkAccess?: string;
+
   // Required name of the external user.
   name: string;
 
-  // Required Omni organization which contains the dashboard.
-  organizationName: string;
+  /**
+   * Name of the organization the content belongs to. If provided, generates a default embed host
+   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
+   *
+   * @throws Error if `host` is provided.
+   */
+  organizationName?: string;
+
+  // Port of host
+  port?: number;
+
+  // Optional dark mode setting. Can be one of "true", "false", or "system".
+  prefersDark?: string;
 
   // Signing secret available to Omni admins.
   secret: string;
 
-  // Optional identifier to associate the user with an external
-  // organization or system.
-  entity?: string;
-
   // Optional user attributes to be passed to user associated with the
   // externalId. User attributes must be created in Omni before being
   // defined and given a value here.
   userAttributes?: Record<string, string | string[] | number | number[]>;
 
-  // Optional dark mode setting. Can be one of "true", "false", or "system".
-  prefersDark?: string;
-
   // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
   theme?: string;
 
-  // Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
-  // Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"Aberdeen"%2C"Alabama"%5D%2C"is_negative"%3Afalse%7D&f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"UK"%5D%2C"is_negative"%3Afalse%7D
-  filterSearchParam?: string;
-
-  // Optional link access setting to control which Omni dashboard links are shown. Note that regardless of the linkAccess value,
-  // all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
-  // "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
-  // "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
-  // undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
-  linkAccess?: string;
+  // DEPRECATED
 
-  // Optional custom theme property that styles the embedded dashboard.
-  customTheme?: CustomThemeProperties;
+  /**
+   * @deprecated Introduced for internal testing only. For vanity domains, use the `host`
+   * prop instead. Will be dropped in a v1.0.0 release.
+   *
+   * @throws Error if `host` is provided.
+   */
+  domain?: string;
 };
 ```
 
@@ -131,32 +174,61 @@ type EmbedSsoProps = {
   // Short GUID of the workbook. Can be obtained via the workbook's share -> embed -> iframe url or via the dashboard url (will embed the workbook associated with the dashboard id)
   contentId: string;
 
+  // Optional identifier to associate the user with an external
+  // organization or system.
+  entity?: string;
+
   // Required identifier to associate the external user with an
   // automatically generated internal Omni user.
   externalId: string;
 
+  /**
+   * Used to set the host of signed embed URL, required when using vanity domains.
+   * Protocol is not required, as https is assumed.
+   * Port is not accepted. If required, use the `port` prop.
+   *
+   * @throws Error if `domain` or `organizationName` are provided.
+   * @example "omni.example.com"
+   * @example "omni.another-example.app"
+   */
+  host?: string;
+
   // Required name of the external user.
   name: string;
 
-  // Required Omni organization which contains the workbook.
-  organizationName: string;
+  /**
+   * Name of the organization the content belongs to. If provided, generates a default embed host
+   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
+   *
+   * @throws Error if `host` is provided.
+   */
+  organizationName?: string;
+
+  // Port of host
+  port?: number;
+
+  // Optional dark mode setting. Can be one of "true", "false", or "system".
+  prefersDark?: string;
 
   // Signing secret available to Omni admins.
   secret: string;
 
-  // Optional identifier to associate the user with an external
-  // organization or system.
-  entity?: string;
-
   // Optional user attributes to be passed to user associated with the
   // externalId. User attributes must be created in Omni before being
   // defined and given a value here.
   userAttributes?: Record<string, string | string[] | number | number[]>;
 
-  // Optional dark mode setting. Can be one of "true", "false", or "system".
-  prefersDark?: string;
-
   // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
   theme?: string;
+
+  // DEPRECATED
+
+  /**
+   * @deprecated Introduced for internal testing only. For vanity domains, use the `host`
+   * prop instead. Will be dropped in a v1.0.0 release.
+   *
+   * @throws Error if `host` is provided.
+   */
+  domain?: string;
 };
 ```

package/lib/cjs/embed.js

@@ -7,39 +7,50 @@ const types_1 = require("./types");
 const defaultEmbedDomain = "embed-omniapp.co";
 const embedLoginPath = "/embed/login";
 const validateProps = (props) => {
-    const { externalId, name, nonce, organizationName, secret, userAttributes } = props;
-    if (!externalId) {
+    const { externalId, name, nonce, secret, userAttributes } = props;
+    let host, domain, organizationName;
+    if ("host" in props)
+        host = props.host;
+    if ("organizationName" in props)
+        organizationName = props.organizationName;
+    if ("domain" in props)
+        domain = props.domain;
+    if (!externalId)
         throw new Error("externalId is required");
-    }
-    if (!name) {
+    if (!name)
         throw new Error("name is required");
-    }
-    if (!organizationName) {
-        throw new Error("organizationName is required");
-    }
-    if (!secret) {
+    if (!secret)
         throw new Error("secret is required");
-    }
-    if (nonce && nonce.length !== 32) {
+    if (!host && !organizationName)
+        throw new Error("Must specify either `host` or `organizationName`");
+    if (host && (organizationName || domain))
+        throw new Error("`host` must be used exclusively and cannot be combined with `organizationName` or `domain` (domain is deprecated)");
+    if (domain)
+        console.warn("`domain` is deprecated and will be removed in a future v1.0.0 release. Use `host` to specify your vanity domain instead (eg `host: 'omni.my-company.com'`).");
+    if (nonce && nonce.length !== 32)
         throw new Error("nonce must be 32 characters");
-    }
-    if (typeof userAttributes !== "object") {
-        if (userAttributes) {
-            throw new Error("userAttributes must be an object");
-        }
-    }
+    if (typeof userAttributes !== "object" && userAttributes)
+        throw new Error("userAttributes must be an object");
 };
 const embedSsoContent = async (props) => {
     validateProps(props);
-    let { accessBoost, connectionRoles: rawConnectionRoles, contentPath, customTheme: rawCustomTheme, domain, externalId, filterSearchParam, linkAccess, mode, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, } = props;
+    let { accessBoost, connectionRoles: rawConnectionRoles, contentPath, customTheme: rawCustomTheme, externalId, filterSearchParam, linkAccess, mode, name, nonce, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, } = props;
+    let host, domain, organizationName;
+    if ("host" in props)
+        host = props.host;
+    if ("organizationName" in props) {
+        domain = props.domain;
+        organizationName = props.organizationName;
+    }
     // Handle defaults
     nonce = nonce !== null && nonce !== void 0 ? nonce : (await (0, random_str_1.random32ByteString)());
-    domain = domain !== null && domain !== void 0 ? domain : defaultEmbedDomain;
     const userAttributes = rawUserAttributes && JSON.stringify(rawUserAttributes);
     const customTheme = rawCustomTheme && JSON.stringify(rawCustomTheme);
     const connectionRoles = rawConnectionRoles && JSON.stringify(rawConnectionRoles);
     // Generate the url for the embed login route
-    const url = new URL(embedLoginPath, `https://${organizationName.toLocaleLowerCase()}.${domain}${port ? `:${port}` : ""}`);
+    if (!host)
+        host = `${organizationName}.${domain !== null && domain !== void 0 ? domain : defaultEmbedDomain}`;
+    const url = new URL(embedLoginPath, `https://${host}${port ? `:${port}` : ""}`);
     // Get a signature for the request
     const signature = (0, signature_1.getSignature)({
         loginUrl: url.toString(),

package/lib/cjs/types.d.ts

@@ -6,7 +6,6 @@ export declare enum EmbedSessionMode {
 type EmbedSsoBaseProps = {
     externalId: string;
     name: string;
-    organizationName: string;
     secret: string;
     entity?: string;
     userAttributes?: Record<string, UserAttributeValue>;
@@ -23,10 +22,37 @@ type EmbedSsoBaseProps = {
      * only the content specified in the contentId will be embedded.
      */
     mode?: EmbedSessionMode;
-    domain?: string;
     nonce?: string;
     port?: number;
-};
+} & ({
+    host?: never;
+    /**
+     * @deprecated Introduced for internal testing only. For vanity domains, use the `host` prop instead.
+     *
+     * @throws Error if `host` is provided.
+     */
+    domain?: string;
+    /**
+     * Name of the organization the content belongs to. If provided, generates a default embed host
+     * URL in the form of `https://<organizationName>.embed-omniapp.co`.
+     *
+     * @throws Error if `host` is provided.
+     */
+    organizationName: string;
+} | {
+    domain?: never;
+    organizationName?: never;
+    /**
+     * Used to set the host of signed embed URL, required when using vanity domains.
+     * Protocol is not required, as https is assumed.
+     * Port is not accepted. If required, use the `port` prop.
+     *
+     * @throws Error if `domain` or `organizationName` are provided.
+     * @example "omni.example.com"
+     * @example "omni.another-example.app"
+     */
+    host: string;
+});
 type EmbedSsoDashboardOnlyProps = {
     accessBoost?: boolean;
     filterSearchParam?: string;

package/lib/esm/embed.js

@@ -4,39 +4,50 @@ import { EmbeddedContent, } from "./types";
 const defaultEmbedDomain = "embed-omniapp.co";
 const embedLoginPath = "/embed/login";
 const validateProps = (props) => {
-    const { externalId, name, nonce, organizationName, secret, userAttributes } = props;
-    if (!externalId) {
+    const { externalId, name, nonce, secret, userAttributes } = props;
+    let host, domain, organizationName;
+    if ("host" in props)
+        host = props.host;
+    if ("organizationName" in props)
+        organizationName = props.organizationName;
+    if ("domain" in props)
+        domain = props.domain;
+    if (!externalId)
         throw new Error("externalId is required");
-    }
-    if (!name) {
+    if (!name)
         throw new Error("name is required");
-    }
-    if (!organizationName) {
-        throw new Error("organizationName is required");
-    }
-    if (!secret) {
+    if (!secret)
         throw new Error("secret is required");
-    }
-    if (nonce && nonce.length !== 32) {
+    if (!host && !organizationName)
+        throw new Error("Must specify either `host` or `organizationName`");
+    if (host && (organizationName || domain))
+        throw new Error("`host` must be used exclusively and cannot be combined with `organizationName` or `domain` (domain is deprecated)");
+    if (domain)
+        console.warn("`domain` is deprecated and will be removed in a future v1.0.0 release. Use `host` to specify your vanity domain instead (eg `host: 'omni.my-company.com'`).");
+    if (nonce && nonce.length !== 32)
         throw new Error("nonce must be 32 characters");
-    }
-    if (typeof userAttributes !== "object") {
-        if (userAttributes) {
-            throw new Error("userAttributes must be an object");
-        }
-    }
+    if (typeof userAttributes !== "object" && userAttributes)
+        throw new Error("userAttributes must be an object");
 };
 const embedSsoContent = async (props) => {
     validateProps(props);
-    let { accessBoost, connectionRoles: rawConnectionRoles, contentPath, customTheme: rawCustomTheme, domain, externalId, filterSearchParam, linkAccess, mode, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, } = props;
+    let { accessBoost, connectionRoles: rawConnectionRoles, contentPath, customTheme: rawCustomTheme, externalId, filterSearchParam, linkAccess, mode, name, nonce, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, } = props;
+    let host, domain, organizationName;
+    if ("host" in props)
+        host = props.host;
+    if ("organizationName" in props) {
+        domain = props.domain;
+        organizationName = props.organizationName;
+    }
     // Handle defaults
     nonce = nonce !== null && nonce !== void 0 ? nonce : (await random32ByteString());
-    domain = domain !== null && domain !== void 0 ? domain : defaultEmbedDomain;
     const userAttributes = rawUserAttributes && JSON.stringify(rawUserAttributes);
     const customTheme = rawCustomTheme && JSON.stringify(rawCustomTheme);
     const connectionRoles = rawConnectionRoles && JSON.stringify(rawConnectionRoles);
     // Generate the url for the embed login route
-    const url = new URL(embedLoginPath, `https://${organizationName.toLocaleLowerCase()}.${domain}${port ? `:${port}` : ""}`);
+    if (!host)
+        host = `${organizationName}.${domain !== null && domain !== void 0 ? domain : defaultEmbedDomain}`;
+    const url = new URL(embedLoginPath, `https://${host}${port ? `:${port}` : ""}`);
     // Get a signature for the request
     const signature = getSignature({
         loginUrl: url.toString(),

package/lib/esm/types.d.ts

@@ -6,7 +6,6 @@ export declare enum EmbedSessionMode {
 type EmbedSsoBaseProps = {
     externalId: string;
     name: string;
-    organizationName: string;
     secret: string;
     entity?: string;
     userAttributes?: Record<string, UserAttributeValue>;
@@ -23,10 +22,37 @@ type EmbedSsoBaseProps = {
      * only the content specified in the contentId will be embedded.
      */
     mode?: EmbedSessionMode;
-    domain?: string;
     nonce?: string;
     port?: number;
-};
+} & ({
+    host?: never;
+    /**
+     * @deprecated Introduced for internal testing only. For vanity domains, use the `host` prop instead.
+     *
+     * @throws Error if `host` is provided.
+     */
+    domain?: string;
+    /**
+     * Name of the organization the content belongs to. If provided, generates a default embed host
+     * URL in the form of `https://<organizationName>.embed-omniapp.co`.
+     *
+     * @throws Error if `host` is provided.
+     */
+    organizationName: string;
+} | {
+    domain?: never;
+    organizationName?: never;
+    /**
+     * Used to set the host of signed embed URL, required when using vanity domains.
+     * Protocol is not required, as https is assumed.
+     * Port is not accepted. If required, use the `port` prop.
+     *
+     * @throws Error if `domain` or `organizationName` are provided.
+     * @example "omni.example.com"
+     * @example "omni.another-example.app"
+     */
+    host: string;
+});
 type EmbedSsoDashboardOnlyProps = {
     accessBoost?: boolean;
     filterSearchParam?: string;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.20",
+  "version": "0.4.0",
   "license": "MIT",
   "name": "@omni-co/embed",
   "author": "Nate Agrin <nate@exploreomni.com>",