@omni-co/embed 0.4.8 → 0.4.10

package/README.md

@@ -24,10 +24,14 @@ yarn:
 yarn add @omni-co/embed
 ```
 
-## Basic Example
+## Basic Examples
 
 ```ts
-import { embedSsoDashboard, embedSsoWorkbook } from "@omni-co/embed";
+import {
+  embedSsoDashboard,
+  embedSsoWorkbook,
+  embedSsoContentDiscovery,
+} from "@omni-co/embed";
 
 // This creates a signed embed sso link for a dashboard
 // in the omni account named Acme.
@@ -39,7 +43,7 @@ const iframeUrl = await embedSsoDashboard({
   secret: "abcdefghijklmnopqrstuvwxyz123456",
 });
 
-// Alternatively you can create a signed embed sso link for a workbook
+// Alternatively, you can create a signed embed sso link for a workbook.
 const iframeUrl = await embedSsoWorkbook({
   contentId: "miU0hL6z",
   externalId: "wile.e@coyote.co",
@@ -47,39 +51,28 @@ const iframeUrl = await embedSsoWorkbook({
   organizationName: "acme",
   secret: "abcdefghijklmnopqrstuvwxyz123456",
 });
-```
-
-## 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",
+// You can also create a signed embed sso link for a content discovery page.
+const iframeUrl = await embedSsoContentDiscovery({
   externalId: "wile.e@coyote.co",
-  host: "omni.example.com",
   name: "Wile E",
+  path: "root",
+  organizationName: "acme",
   secret: "abcdefghijklmnopqrstuvwxyz123456",
 });
 ```
 
-## Kitchen Sink Example
+## Using Vanity Domains
 
 ```ts
-import { embedSsoDashboard, embedSsoWorkbook } from "@omni-co/embed";
-
-// This creates a signed embed sso link for a dashboard
-// in the omni account named Acme.
+// 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",
-  entity: "cartoon",
+  host: "omni.example.com",
   name: "Wile E",
-  organizationName: "acme",
   secret: "abcdefghijklmnopqrstuvwxyz123456",
-  prefersDark: "system",
-  theme: "vibes",
-  userAttributes: { tool: "anvil" },
 });
 ```
 
@@ -88,25 +81,59 @@ const iframeUrl = await embedSsoDashboard({
 This is the type signature for the `embedSsoDashboard` function:
 
 ```ts
-type EmbedSsoProps = {
+type EmbedSsoDashboardProps = {
+  // Optional boolean property that toggles the dashboard's Access Boost setting.
+  accessBoost?: boolean;
+
+  // Optional object that determines the connection permissions for the embed user.
+  connectionRoles?: Record<string, EmbedConnectionRoles>;
+
   // Short GUID of the dashboard. Can be obtained via the dashboard's url.
   contentId: string;
 
-  // Optional custom theme property that styles the embedded dashboard.
+  // Optional custom theme object that styles the embedded dashboard.
   customTheme?: CustomThemeProperties;
 
-  // Optional identifier to associate the user with an external
-  // organization or system.
+  /**
+   * Optional custom theme ID setting that styles the embedded dashboard.
+   * This ID should be from a theme created within the Omni application.
+   */
+  customThemeId?: string;
+
+  // Optional email parameter that sets the default scheduling email for the embed user.
+  email?: string;
+
+  /**
+   * Optional identifier to associate the user with an external organization or system.
+   * Note that each distinct entity will generate its own folder and group. These can be used by
+   * an embed user to share content with other members in the same entity.
+   */
   entity?: string;
 
-  // Required identifier to associate the external user with an
-  // automatically generated internal Omni user.
+  /**
+   * Optional content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
+   *
+   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
+   * EDITOR: the user will have the ability to manage content in the entity folder.
+   * VIEWER: the user will only be able to view content in the entity folder.
+   */
+  entityFolderContentRole?: EmbedEntityFolderContentRoles;
+
+  // 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
+  /**
+   * 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 groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
+   */
+  groups?: string[];
+
   /**
    * Used to set the host of signed embed URL, required when using vanity domains.
    * Protocol is not required, as https is assumed.
@@ -118,13 +145,24 @@ type EmbedSsoProps = {
    */
   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.
+  /**
+   * 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;
 
+  /**
+   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
+   *
+   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
+   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
+   */
+  mode?: EmbedSessionMode;
+
   // Required name of the external user.
   name: string;
 
@@ -136,7 +174,7 @@ type EmbedSsoProps = {
    */
   organizationName?: string;
 
-  // Port of host
+  // Port of host.
   port?: number;
 
   // Optional dark mode setting. Can be one of "true", "false", or "system".
@@ -145,14 +183,16 @@ type EmbedSsoProps = {
   // Signing secret available to Omni admins.
   secret: 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 theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
   theme?: 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[]>;
+
   // DEPRECATED
 
   /**
@@ -170,18 +210,58 @@ type EmbedSsoProps = {
 This is the type signature for the `embedSsoWorkbook` function:
 
 ```ts
-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)
+type EmbedSsoWorkbookProps = {
+  // Optional object that determines the connection permissions for the embed user.
+  connectionRoles?: Record<string, EmbedConnectionRoles>;
+
+  /**
+   * Short GUID of the workbook.
+   *
+   * Can be obtained via the workbook's share -> embed -> iframe url or via the dashboard url.
+   * This will embed the workbook associated with the dashboard id.
+   */
   contentId: string;
 
-  // Optional identifier to associate the user with an external
-  // organization or system.
+  /**
+   * Optional custom theme object. Note that this theme will only apply to dashboards viewed
+   * during the generated embed session.
+   */
+  customTheme?: CustomThemeProperties;
+
+  /**
+   * Optional custom theme ID setting. Note that this theme will only apply to dashboards viewed
+   * during the generated embed session.
+   */
+  customThemeId?: string;
+
+  // Optional email parameter that sets the default scheduling email for the embed user.
+  email?: string;
+
+  /**
+   * Optional identifier to associate the user with an external organization or system.
+   * Note that each distinct entity will generate its own folder and group. These can be used by
+   * an embed user to share content with other members in the same entity.
+   */
   entity?: string;
 
+  /**
+   * Optional content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
+   *
+   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
+   * EDITOR: the user will have the ability to manage content in the entity folder.
+   * VIEWER: the user will only be able to view content in the entity folder.
+   */
+  entityFolderContentRole?: EmbedEntityFolderContentRoles;
+
   // Required identifier to associate the external user with an
   // automatically generated internal Omni user.
   externalId: string;
 
+  /*
+   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
+   */
+  groups?: string[];
+
   /**
    * Used to set the host of signed embed URL, required when using vanity domains.
    * Protocol is not required, as https is assumed.
@@ -193,6 +273,14 @@ type EmbedSsoProps = {
    */
   host?: string;
 
+  /**
+   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
+   *
+   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
+   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
+   */
+  mode?: EmbedSessionMode;
+
   // Required name of the external user.
   name: string;
 
@@ -204,7 +292,7 @@ type EmbedSsoProps = {
    */
   organizationName?: string;
 
-  // Port of host
+  // Port of host.
   port?: number;
 
   // Optional dark mode setting. Can be one of "true", "false", or "system".
@@ -213,14 +301,136 @@ type EmbedSsoProps = {
   // Signing secret available to Omni admins.
   secret: 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.
+  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
+  theme?: 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[]>;
 
+  // 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;
+};
+```
+
+## embedSsoContentDiscovery
+
+This is the type signature for the `embedSsoContentDiscovery` function:
+
+```ts
+type EmbedSsoContentDiscoveryProps = {
+  // Optional object that determines the connection permissions for the embed user.
+  connectionRoles?: Record<string, EmbedConnectionRoles>;
+
+  /**
+   * Optional custom theme object. Note that this theme will only apply to dashboards viewed
+   * during the generated embed session.
+   */
+  customTheme?: CustomThemeProperties;
+
+  /**
+   * Optional custom theme ID setting. Note that this theme will only apply to dashboards viewed
+   * during the generated embed session.
+   */
+  customThemeId?: string;
+
+  // Optional email parameter that sets the default scheduling email for the embed user.
+  email?: string;
+
+  /**
+   * Optional identifier to associate the user with an external organization or system.
+   * Note that each distinct entity will generate its own folder and group. These can be used by
+   * an embed user to share content with other members in the same entity.
+   */
+  entity?: string;
+
+  /**
+   * Optional content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
+   *
+   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
+   * EDITOR: the user will have the ability to manage content in the entity folder.
+   * VIEWER: the user will only be able to view content in the entity folder.
+   */
+  entityFolderContentRole?: EmbedEntityFolderContentRoles;
+
+  // Required identifier to associate the external user with an
+  // automatically generated internal Omni user.
+  externalId: string;
+
+  /*
+   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
+   */
+  groups?: 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 mode setting that determines whether the entire application should be embedded or a single piece of content.
+   *
+   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
+   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
+   */
+  mode?: EmbedSessionMode;
+
+  // Required name of the external user.
+  name: 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;
+
+  /**
+   * Required path property. The path value determines the starting content discovery page
+   * for the generated embed session. Can be one of "my", "entity-folder", or "root".
+   *
+   * my: "My Content" page
+   * entity-folder: embed entity folder
+   * root: "Hub" page
+   */
+  path: EmbedSsoContentDiscoveryPath;
+
+  // 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 theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
   theme?: 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[]>;
+
   // DEPRECATED
 
   /**

package/lib/cjs/signature.js

@@ -21,7 +21,7 @@ accessBoost, connectionRoles, customTheme, customThemeId, email, entity, entityF
     // We create a map of optional params and convert it to an array
     // to ensure that the order of the optional params is alphabetical and consistent.
     const optionalParamsMap = {
-        ...(accessBoost && { accessBoost: accessBoost === null || accessBoost === void 0 ? void 0 : accessBoost.toString() }),
+        ...(accessBoost !== undefined && { accessBoost: accessBoost.toString() }),
         ...(connectionRoles && { connectionRoles }),
         ...(customTheme && { customTheme }),
         ...(customThemeId && { customThemeId }),

package/lib/cjs/types.d.ts

@@ -15,19 +15,22 @@ type EmbedSsoBaseProps = {
     customThemeId?: string;
     /**
      * Optional connection roles setting. Object keys should be connection IDs from the embedded Omni instance.
-     * Object values should be connection roles. At the moment, the only valid role string is "RESTRICTED_QUERIER".
+     * Object values should be connection roles.
      */
     connectionRoles?: Record<string, EmbedConnectionRoles>;
     /**
      * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
-     * If EmbedSessionMode.Application is selected, the entire application will be embedded. If EmbedSessionMode.SingleContent is selected,
-     * only the content specified in the contentId will be embedded.
+     *
+     * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
+     * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
      */
     mode?: EmbedSessionMode;
     /**
-     * Optional content role setting. Can be one of "EDITOR" or "VIEWER". If set to "EDITOR", the user will have the ability to manage
-     * content in their associated embed entity folder. If set to "VIEWER", the user will only be able to view content in
-     * their associated embed entity folder.
+     * Optional content role setting. Can be one of "MANAGER", "EDITOR", or "VIEWER".
+     *
+     * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
+     * EDITOR: the user will have the ability to manage content in the entity folder.
+     * VIEWER: the user will only be able to view content in the entity folder.
      */
     entityFolderContentRole?: EmbedEntityFolderContentRoles;
     /**
@@ -209,7 +212,7 @@ export type EmbedSsoWorkbookProps = EmbedSsoBaseProps & EmbedContentIdProp;
 export type EmbedSsoContentDiscoveryProps = EmbedSsoBaseProps & {
     /**
      * Required connection roles object. Object keys should be connection IDs from the embedded Omni instance.
-     * Object values should be connection roles. At the moment, the only valid role string is "RESTRICTED_QUERIER".
+     * Object values should be connection roles.
      */
     connectionRoles: Record<string, EmbedConnectionRoles>;
     /**

package/lib/esm/signature.js

@@ -14,7 +14,7 @@ accessBoost, connectionRoles, customTheme, customThemeId, email, entity, entityF
     // We create a map of optional params and convert it to an array
     // to ensure that the order of the optional params is alphabetical and consistent.
     const optionalParamsMap = {
-        ...(accessBoost && { accessBoost: accessBoost === null || accessBoost === void 0 ? void 0 : accessBoost.toString() }),
+        ...(accessBoost !== undefined && { accessBoost: accessBoost.toString() }),
         ...(connectionRoles && { connectionRoles }),
         ...(customTheme && { customTheme }),
         ...(customThemeId && { customThemeId }),

package/lib/esm/types.d.ts

@@ -15,19 +15,22 @@ type EmbedSsoBaseProps = {
     customThemeId?: string;
     /**
      * Optional connection roles setting. Object keys should be connection IDs from the embedded Omni instance.
-     * Object values should be connection roles. At the moment, the only valid role string is "RESTRICTED_QUERIER".
+     * Object values should be connection roles.
      */
     connectionRoles?: Record<string, EmbedConnectionRoles>;
     /**
      * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
-     * If EmbedSessionMode.Application is selected, the entire application will be embedded. If EmbedSessionMode.SingleContent is selected,
-     * only the content specified in the contentId will be embedded.
+     *
+     * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
+     * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
      */
     mode?: EmbedSessionMode;
     /**
-     * Optional content role setting. Can be one of "EDITOR" or "VIEWER". If set to "EDITOR", the user will have the ability to manage
-     * content in their associated embed entity folder. If set to "VIEWER", the user will only be able to view content in
-     * their associated embed entity folder.
+     * Optional content role setting. Can be one of "MANAGER", "EDITOR", or "VIEWER".
+     *
+     * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
+     * EDITOR: the user will have the ability to manage content in the entity folder.
+     * VIEWER: the user will only be able to view content in the entity folder.
      */
     entityFolderContentRole?: EmbedEntityFolderContentRoles;
     /**
@@ -209,7 +212,7 @@ export type EmbedSsoWorkbookProps = EmbedSsoBaseProps & EmbedContentIdProp;
 export type EmbedSsoContentDiscoveryProps = EmbedSsoBaseProps & {
     /**
      * Required connection roles object. Object keys should be connection IDs from the embedded Omni instance.
-     * Object values should be connection roles. At the moment, the only valid role string is "RESTRICTED_QUERIER".
+     * Object values should be connection roles.
      */
     connectionRoles: Record<string, EmbedConnectionRoles>;
     /**

package/package.json

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