@omni-co/embed 0.6.0 → 0.7.0

package/lib/cjs/embed.d.ts

@@ -1,4 +1,4 @@
-import { EmbedSsoContentDiscoveryProps, EmbedSsoDashboardProps, EmbedSsoWorkbookProps } from "./types";
+import { EmbedSsoContentDiscoveryProps, EmbedSsoDashboardProps, EmbedSsoWorkbookProps, GenerateEmbedSsoSessionProps, RedeemEmbedSsoSessionProps } from "./types";
 export declare const embedSsoDashboard: (props: EmbedSsoDashboardProps) => Promise<string>;
 export declare const embedSsoWorkbook: (props: EmbedSsoWorkbookProps) => Promise<string>;
 /**
@@ -7,3 +7,26 @@ export declare const embedSsoWorkbook: (props: EmbedSsoWorkbookProps) => Promise
  * @returns Promise wrapped around a generated embed login url.
  */
 export declare const embedSsoContentDiscovery: (props: EmbedSsoContentDiscoveryProps) => Promise<string>;
+/**
+ * First step of the 2-step SSO embed login flow. If successful, outputs an object that
+ * includes an SSO embed session token. If unsuccessful, outputs an object that includes
+ * an error message.
+ *
+ * To elaborate, this function upserts an SSO embed user and session to the specified Omni
+ * organization / host. The returned session token corresponds to the generated session.
+ */
+export declare const createSessionToken: ({ apiKey, domain, host, organizationName, port, ...restProps }: GenerateEmbedSsoSessionProps) => Promise<{
+    success: true;
+    sessionToken: string;
+    error?: never;
+} | {
+    success: false;
+    sessionToken?: never;
+    error: string;
+}>;
+/**
+ * Second step of the 2-step SSO embed login flow. Uses a generated session token
+ * to output an session redemption URL that can be used to display embedded content.
+ * The returned URL should be passed into an `iframe`'s src attribute.
+ */
+export declare const redeemSessionToken: ({ domain, host, organizationName, port, nonce: propsNonce, secret, prefersDark, sessionToken: sessionId, theme, }: RedeemEmbedSsoSessionProps) => Promise<string>;

package/lib/cjs/embed.js

@@ -1,11 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.embedSsoContentDiscovery = exports.embedSsoWorkbook = exports.embedSsoDashboard = void 0;
+exports.redeemSessionToken = exports.createSessionToken = exports.embedSsoContentDiscovery = exports.embedSsoWorkbook = exports.embedSsoDashboard = void 0;
 const random_str_1 = require("./random-str");
 const signature_1 = require("./signature");
 const types_1 = require("./types");
 const defaultEmbedDomain = "embed-omniapp.co";
 const embedLoginPath = "/embed/login";
+const generateSsoEmbedSessionPath = "/api/unstable/embed/sso/generate-session";
+const redeemSsoEmbedSessionPath = "/embed/sso/redeem-session";
+const createEmbedRequestUrl = (props) => {
+    let host, domain, organizationName;
+    if ("host" in props)
+        host = props.host;
+    if ("organizationName" in props) {
+        domain = props.domain;
+        organizationName = props.organizationName;
+    }
+    // Generate the url for the embed login route
+    if (!host)
+        host = `${organizationName}.${domain !== null && domain !== void 0 ? domain : defaultEmbedDomain}`;
+    const url = new URL(props.requestPath, `https://${host}${props.port ? `:${props.port}` : ""}`);
+    return url;
+};
 const validateProps = (props) => {
     const { externalId, name, nonce, secret, userAttributes, customTheme, customThemeId, } = props;
     let host, domain, organizationName;
@@ -36,24 +52,20 @@ const validateProps = (props) => {
 };
 const embedSsoContent = async (props) => {
     validateProps(props);
-    let { accessBoost, connectionRoles: rawConnectionRoles, contentPath, customTheme: rawCustomTheme, customThemeId, email, externalId, filterSearchParam, linkAccess, mode, name, nonce, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, entityFolderContentRole, groups: rawGroups, } = props;
-    let host, domain, organizationName;
-    if ("host" in props)
-        host = props.host;
-    if ("organizationName" in props) {
-        domain = props.domain;
-        organizationName = props.organizationName;
-    }
+    let { accessBoost, connectionRoles: rawConnectionRoles, contentPath, customTheme: rawCustomTheme, customThemeId, domain, email, externalId, filterSearchParam, host, linkAccess, mode, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, entityFolderContentRole, groups: rawGroups, } = props;
     // Handle defaults
     nonce = nonce !== null && nonce !== void 0 ? nonce : (await (0, random_str_1.random32ByteString)());
     const userAttributes = rawUserAttributes && JSON.stringify(rawUserAttributes);
     const customTheme = rawCustomTheme && JSON.stringify(rawCustomTheme);
     const connectionRoles = rawConnectionRoles && JSON.stringify(rawConnectionRoles);
     const groups = rawGroups && JSON.stringify(rawGroups);
-    // Generate the url for the embed login route
-    if (!host)
-        host = `${organizationName}.${domain !== null && domain !== void 0 ? domain : defaultEmbedDomain}`;
-    const url = new URL(embedLoginPath, `https://${host}${port ? `:${port}` : ""}`);
+    const url = createEmbedRequestUrl({
+        domain,
+        host,
+        organizationName,
+        port,
+        requestPath: embedLoginPath,
+    });
     // Get a signature for the request
     const signature = (0, signature_1.getSignature)({
         // Required parameters
@@ -124,10 +136,82 @@ exports.embedSsoWorkbook = embedSsoWorkbook;
 const embedSsoContentDiscovery = async (props) => {
     // Entity paths for the Content Discovery embed no longer require stripping the leading `/`.
     // This check maintains backwards compatibility with the old behavior.
-    const contentPath = props.path.startsWith('/') ? props.path : `/${props.path}`;
+    const contentPath = props.path.startsWith("/")
+        ? props.path
+        : `/${props.path}`;
     return embedSsoContent({
         ...props,
         contentPath,
     });
 };
 exports.embedSsoContentDiscovery = embedSsoContentDiscovery;
+/**
+ * First step of the 2-step SSO embed login flow. If successful, outputs an object that
+ * includes an SSO embed session token. If unsuccessful, outputs an object that includes
+ * an error message.
+ *
+ * To elaborate, this function upserts an SSO embed user and session to the specified Omni
+ * organization / host. The returned session token corresponds to the generated session.
+ */
+const createSessionToken = async ({ apiKey, domain, host, organizationName, port, ...restProps }) => {
+    const generateRequestUrl = createEmbedRequestUrl({
+        domain,
+        host,
+        organizationName,
+        port,
+        requestPath: generateSsoEmbedSessionPath,
+    });
+    // Hit the endpoint with the endpoint params + signature
+    const fetchResponse = await fetch(generateRequestUrl, {
+        method: "POST",
+        body: JSON.stringify({
+            ...restProps,
+        }),
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-type": "application/json",
+        },
+    });
+    if (!fetchResponse.ok)
+        return {
+            error: `Failed to generate embed session: ${fetchResponse.statusText}`,
+            success: false,
+        };
+    const fetchData = await fetchResponse.json();
+    if (!fetchData.sessionId)
+        return { error: "No session ID returned from endpoint.", success: false };
+    return { sessionToken: fetchData.sessionId, success: true };
+};
+exports.createSessionToken = createSessionToken;
+/**
+ * Second step of the 2-step SSO embed login flow. Uses a generated session token
+ * to output an session redemption URL that can be used to display embedded content.
+ * The returned URL should be passed into an `iframe`'s src attribute.
+ */
+const redeemSessionToken = async ({ domain, host, organizationName, port, nonce: propsNonce, secret, prefersDark, sessionToken: sessionId, // sessionToken is just a facade for the sessionId
+theme, }) => {
+    const redeemRequestUrl = createEmbedRequestUrl({
+        domain,
+        host,
+        organizationName,
+        port,
+        requestPath: redeemSsoEmbedSessionPath,
+    });
+    const nonce = propsNonce !== null && propsNonce !== void 0 ? propsNonce : (await (0, random_str_1.random32ByteString)());
+    const signature = (0, signature_1.signSessionRedemption)({
+        requestUrl: redeemRequestUrl.toString(),
+        nonce,
+        prefersDark,
+        sessionId,
+        secret,
+        theme,
+    });
+    prefersDark !== undefined &&
+        redeemRequestUrl.searchParams.append("prefersDark", prefersDark);
+    theme !== undefined && redeemRequestUrl.searchParams.append("theme", theme);
+    redeemRequestUrl.searchParams.append("nonce", nonce);
+    redeemRequestUrl.searchParams.append("sessionId", sessionId);
+    redeemRequestUrl.searchParams.append("signature", signature);
+    return redeemRequestUrl.toString();
+};
+exports.redeemSessionToken = redeemSessionToken;

package/lib/cjs/types.d.ts

@@ -3,6 +3,35 @@ export declare enum EmbedSessionMode {
     Application = "APPLICATION",
     SingleContent = "SINGLE_CONTENT"
 }
+type HostProps = {
+    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 EmbedSsoBaseProps = {
     externalId: string;
     name: string;
@@ -45,35 +74,7 @@ type EmbedSsoBaseProps = {
     linkAccess?: 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;
-});
+} & HostProps;
 type EmbedSsoDashboardOnlyProps = {
     accessBoost?: boolean;
 };
@@ -218,4 +219,10 @@ export type EmbedSsoContentDiscoveryProps = EmbedSsoBaseProps & {
      */
     path: string;
 };
+export type GenerateEmbedSsoSessionProps = Omit<EmbedSsoContentProps, "prefersDark" | "theme" | "secret" | "nonce"> & {
+    apiKey: string;
+} & HostProps;
+export type RedeemEmbedSsoSessionProps = Pick<EmbedSsoContentProps, "nonce" | "prefersDark" | "secret" | "theme" | "port"> & {
+    sessionToken: string;
+} & HostProps;
 export {};

package/lib/esm/embed.d.ts

@@ -1,4 +1,4 @@
-import { EmbedSsoContentDiscoveryProps, EmbedSsoDashboardProps, EmbedSsoWorkbookProps } from "./types";
+import { EmbedSsoContentDiscoveryProps, EmbedSsoDashboardProps, EmbedSsoWorkbookProps, GenerateEmbedSsoSessionProps, RedeemEmbedSsoSessionProps } from "./types";
 export declare const embedSsoDashboard: (props: EmbedSsoDashboardProps) => Promise<string>;
 export declare const embedSsoWorkbook: (props: EmbedSsoWorkbookProps) => Promise<string>;
 /**
@@ -7,3 +7,26 @@ export declare const embedSsoWorkbook: (props: EmbedSsoWorkbookProps) => Promise
  * @returns Promise wrapped around a generated embed login url.
  */
 export declare const embedSsoContentDiscovery: (props: EmbedSsoContentDiscoveryProps) => Promise<string>;
+/**
+ * First step of the 2-step SSO embed login flow. If successful, outputs an object that
+ * includes an SSO embed session token. If unsuccessful, outputs an object that includes
+ * an error message.
+ *
+ * To elaborate, this function upserts an SSO embed user and session to the specified Omni
+ * organization / host. The returned session token corresponds to the generated session.
+ */
+export declare const createSessionToken: ({ apiKey, domain, host, organizationName, port, ...restProps }: GenerateEmbedSsoSessionProps) => Promise<{
+    success: true;
+    sessionToken: string;
+    error?: never;
+} | {
+    success: false;
+    sessionToken?: never;
+    error: string;
+}>;
+/**
+ * Second step of the 2-step SSO embed login flow. Uses a generated session token
+ * to output an session redemption URL that can be used to display embedded content.
+ * The returned URL should be passed into an `iframe`'s src attribute.
+ */
+export declare const redeemSessionToken: ({ domain, host, organizationName, port, nonce: propsNonce, secret, prefersDark, sessionToken: sessionId, theme, }: RedeemEmbedSsoSessionProps) => Promise<string>;

package/lib/esm/embed.js

@@ -1,8 +1,24 @@
 import { random32ByteString } from "./random-str";
-import { getSignature } from "./signature";
+import { getSignature, signSessionRedemption } from "./signature";
 import { EmbeddedContent, } from "./types";
 const defaultEmbedDomain = "embed-omniapp.co";
 const embedLoginPath = "/embed/login";
+const generateSsoEmbedSessionPath = "/api/unstable/embed/sso/generate-session";
+const redeemSsoEmbedSessionPath = "/embed/sso/redeem-session";
+const createEmbedRequestUrl = (props) => {
+    let host, domain, organizationName;
+    if ("host" in props)
+        host = props.host;
+    if ("organizationName" in props) {
+        domain = props.domain;
+        organizationName = props.organizationName;
+    }
+    // Generate the url for the embed login route
+    if (!host)
+        host = `${organizationName}.${domain !== null && domain !== void 0 ? domain : defaultEmbedDomain}`;
+    const url = new URL(props.requestPath, `https://${host}${props.port ? `:${props.port}` : ""}`);
+    return url;
+};
 const validateProps = (props) => {
     const { externalId, name, nonce, secret, userAttributes, customTheme, customThemeId, } = props;
     let host, domain, organizationName;
@@ -33,24 +49,20 @@ const validateProps = (props) => {
 };
 const embedSsoContent = async (props) => {
     validateProps(props);
-    let { accessBoost, connectionRoles: rawConnectionRoles, contentPath, customTheme: rawCustomTheme, customThemeId, email, externalId, filterSearchParam, linkAccess, mode, name, nonce, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, entityFolderContentRole, groups: rawGroups, } = props;
-    let host, domain, organizationName;
-    if ("host" in props)
-        host = props.host;
-    if ("organizationName" in props) {
-        domain = props.domain;
-        organizationName = props.organizationName;
-    }
+    let { accessBoost, connectionRoles: rawConnectionRoles, contentPath, customTheme: rawCustomTheme, customThemeId, domain, email, externalId, filterSearchParam, host, linkAccess, mode, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, entityFolderContentRole, groups: rawGroups, } = props;
     // Handle defaults
     nonce = nonce !== null && nonce !== void 0 ? nonce : (await random32ByteString());
     const userAttributes = rawUserAttributes && JSON.stringify(rawUserAttributes);
     const customTheme = rawCustomTheme && JSON.stringify(rawCustomTheme);
     const connectionRoles = rawConnectionRoles && JSON.stringify(rawConnectionRoles);
     const groups = rawGroups && JSON.stringify(rawGroups);
-    // Generate the url for the embed login route
-    if (!host)
-        host = `${organizationName}.${domain !== null && domain !== void 0 ? domain : defaultEmbedDomain}`;
-    const url = new URL(embedLoginPath, `https://${host}${port ? `:${port}` : ""}`);
+    const url = createEmbedRequestUrl({
+        domain,
+        host,
+        organizationName,
+        port,
+        requestPath: embedLoginPath,
+    });
     // Get a signature for the request
     const signature = getSignature({
         // Required parameters
@@ -119,9 +131,79 @@ export const embedSsoWorkbook = async (props) => {
 export const embedSsoContentDiscovery = async (props) => {
     // Entity paths for the Content Discovery embed no longer require stripping the leading `/`.
     // This check maintains backwards compatibility with the old behavior.
-    const contentPath = props.path.startsWith('/') ? props.path : `/${props.path}`;
+    const contentPath = props.path.startsWith("/")
+        ? props.path
+        : `/${props.path}`;
     return embedSsoContent({
         ...props,
         contentPath,
     });
 };
+/**
+ * First step of the 2-step SSO embed login flow. If successful, outputs an object that
+ * includes an SSO embed session token. If unsuccessful, outputs an object that includes
+ * an error message.
+ *
+ * To elaborate, this function upserts an SSO embed user and session to the specified Omni
+ * organization / host. The returned session token corresponds to the generated session.
+ */
+export const createSessionToken = async ({ apiKey, domain, host, organizationName, port, ...restProps }) => {
+    const generateRequestUrl = createEmbedRequestUrl({
+        domain,
+        host,
+        organizationName,
+        port,
+        requestPath: generateSsoEmbedSessionPath,
+    });
+    // Hit the endpoint with the endpoint params + signature
+    const fetchResponse = await fetch(generateRequestUrl, {
+        method: "POST",
+        body: JSON.stringify({
+            ...restProps,
+        }),
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-type": "application/json",
+        },
+    });
+    if (!fetchResponse.ok)
+        return {
+            error: `Failed to generate embed session: ${fetchResponse.statusText}`,
+            success: false,
+        };
+    const fetchData = await fetchResponse.json();
+    if (!fetchData.sessionId)
+        return { error: "No session ID returned from endpoint.", success: false };
+    return { sessionToken: fetchData.sessionId, success: true };
+};
+/**
+ * Second step of the 2-step SSO embed login flow. Uses a generated session token
+ * to output an session redemption URL that can be used to display embedded content.
+ * The returned URL should be passed into an `iframe`'s src attribute.
+ */
+export const redeemSessionToken = async ({ domain, host, organizationName, port, nonce: propsNonce, secret, prefersDark, sessionToken: sessionId, // sessionToken is just a facade for the sessionId
+theme, }) => {
+    const redeemRequestUrl = createEmbedRequestUrl({
+        domain,
+        host,
+        organizationName,
+        port,
+        requestPath: redeemSsoEmbedSessionPath,
+    });
+    const nonce = propsNonce !== null && propsNonce !== void 0 ? propsNonce : (await random32ByteString());
+    const signature = signSessionRedemption({
+        requestUrl: redeemRequestUrl.toString(),
+        nonce,
+        prefersDark,
+        sessionId,
+        secret,
+        theme,
+    });
+    prefersDark !== undefined &&
+        redeemRequestUrl.searchParams.append("prefersDark", prefersDark);
+    theme !== undefined && redeemRequestUrl.searchParams.append("theme", theme);
+    redeemRequestUrl.searchParams.append("nonce", nonce);
+    redeemRequestUrl.searchParams.append("sessionId", sessionId);
+    redeemRequestUrl.searchParams.append("signature", signature);
+    return redeemRequestUrl.toString();
+};

package/lib/esm/types.d.ts

@@ -3,6 +3,35 @@ export declare enum EmbedSessionMode {
     Application = "APPLICATION",
     SingleContent = "SINGLE_CONTENT"
 }
+type HostProps = {
+    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 EmbedSsoBaseProps = {
     externalId: string;
     name: string;
@@ -45,35 +74,7 @@ type EmbedSsoBaseProps = {
     linkAccess?: 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;
-});
+} & HostProps;
 type EmbedSsoDashboardOnlyProps = {
     accessBoost?: boolean;
 };
@@ -218,4 +219,10 @@ export type EmbedSsoContentDiscoveryProps = EmbedSsoBaseProps & {
      */
     path: string;
 };
+export type GenerateEmbedSsoSessionProps = Omit<EmbedSsoContentProps, "prefersDark" | "theme" | "secret" | "nonce"> & {
+    apiKey: string;
+} & HostProps;
+export type RedeemEmbedSsoSessionProps = Pick<EmbedSsoContentProps, "nonce" | "prefersDark" | "secret" | "theme" | "port"> & {
+    sessionToken: string;
+} & HostProps;
 export {};

package/package.json

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