@omni-co/embed 0.2.0 → 0.2.2

package/README.md

@@ -1,28 +1,77 @@
-# omni-embed-sdk
+# Omni Embed SSO Typescript SDK
 
-## ⚠️ OmniEmbedSDK uses NPM! ⚠️
+## Basic Example
 
-Publishing to npmjs.org was complicated with Yarn. Until that issue is resolved, please use NPM to manage this package.
+```ts
+  import { embedSsoDashboard } from '@omni-co/embed'
 
-## Installation
+  // This creates a signed embed sso link for a dashboard
+  // in the omni account named Acme.
+  const iframeUrl = embedSsoDashboard({
+    contentId: "miU0hL6z",
+    externalId: "wile.e@coyote.co",
+    name: "Wile E",
+    organizationName: "acme",
+    secret: "abcdefghijklmnopqrstuvwxyz123456",
+  });
+```
 
-1. git clone the repository
-2. `npm install`
-3. `npm run test`
+## Kitchen Sink Example
 
-## Publishing
+```ts
+  import { embedSsoDashboard } from '@omni-co/embed'
 
-1. Create a new branch
-2. Edit the package.json version number appropriately
-3. Open a PR
-4. Merge the PR
-5. Nav to the Releases page in Github: https://github.com/exploreomni/embed-sdk/releases
-6. Click "Draft new Release"
-7. Click "Choose a tag" and type in the new tag name. Convention is to prefix the new version with `v`. Example: `v1.0.0`
-8. Leave target as `main`
-9. Enter a title, usually just the release version eg `v1.0.0`
-10. Add a description
-11. Ensure `Set as latest release` is ticked, if that's appropriate
-12. Click `Publish release`
+  // This creates a signed embed sso link for a dashboard
+  // in the omni account named Acme.
+  const iframeUrl = embedSsoDashboard({
+    contentId: "miU0hL6z",
+    externalId: "wile.e@coyote.co",
+    entity: "cartoon",
+    name: "Wile E",
+    organizationName: "acme",
+    secret: "abcdefghijklmnopqrstuvwxyz123456",
+    prefersDark: "system",
+    theme: "vibes",
+    userAttributes: { tool: "anvil" }
+  });
+```
 
-🥳 - The [github action defined here](https://github.com/exploreomni/embed-sdk/blob/main/.github/workflows/publish.yml) should publish the new release to npmjs.org.
+## embedSsoDashboard
+
+This is the type signature for the embedSsoDashboard function:
+
+```ts
+type EmbedSsoDashboardProps = {
+  // Short GUID of the dashboard. Can be obtained via the dashboard's url.
+  contentId: string;
+
+  // Required identifier to associate the external user with an 
+  // automatically generated internal Omni user.
+  externalId: string;
+
+  // Required name of the external user.
+  name: string;
+
+  // Required Omni organization which contains the dashboard.
+  organizationName: 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>;
+
+  // 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;
+};
+
+```

package/lib/cjs/embed.d.ts

@@ -1,14 +1,16 @@
 type EmbedSsoProps = {
     contentId: string;
-    domain?: string;
     externalId: string;
     name: string;
-    nonce?: string;
     organizationName: string;
-    port?: number;
     secret: string;
-    userAttributes?: Record<string, string>;
     entity?: string;
+    userAttributes?: Record<string, string>;
+    prefersDark?: string;
+    theme?: string;
+    domain?: string;
+    nonce?: string;
+    port?: number;
 };
 export declare const embedSsoDashboard: (props: EmbedSsoProps) => string;
 export {};

package/lib/cjs/embed.js

@@ -34,7 +34,7 @@ const validateProps = (props) => {
 };
 const embedSsoDashboard = (props) => {
     validateProps(props);
-    let { contentId, domain, externalId, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, } = props;
+    let { contentId, domain, externalId, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, } = props;
     // Handle defaults
     nonce = nonce ?? (0, random_str_1.random32ByteString)();
     domain = domain ?? defaultEmbedDomain;
@@ -53,6 +53,8 @@ const embedSsoDashboard = (props) => {
         secret,
         userAttributes,
         entity,
+        prefersDark,
+        theme,
     });
     // Build and return the signed url
     url.searchParams.append("contentPath", contentPath);
@@ -62,6 +64,8 @@ const embedSsoDashboard = (props) => {
     url.searchParams.append("signature", signature);
     userAttributes && url.searchParams.append("userAttributes", userAttributes);
     entity && url.searchParams.append("entity", entity);
+    prefersDark && url.searchParams.append("prefersDark", prefersDark);
+    theme && url.searchParams.append("theme", theme);
     return url.toString();
 };
 exports.embedSsoDashboard = embedSsoDashboard;

package/lib/cjs/signature.d.ts

@@ -39,9 +39,17 @@ type SignatureProps = {
      * user will this value assigned to its omni_user_embed_entity user attribute.
      */
     entity?: string;
+    /**
+     * Whether the user prefers light, dark, or system theme.
+     */
+    prefersDark?: string;
+    /**
+     * The theme of the embed.
+     */
+    theme?: string;
 };
 export declare const getSignature: ({ secret, ...props }: SignatureProps) => string;
 export declare const TEST_ONLY: {
-    generateStringForSignature: ({ loginUrl, contentPath, externalId, name, nonce, userAttributes, entity, }: Omit<SignatureProps, "secret">) => string;
+    generateStringForSignature: ({ loginUrl, contentPath, externalId, name, nonce, userAttributes, entity, prefersDark, theme, }: Omit<SignatureProps, "secret">) => string;
 };
 export {};

package/lib/cjs/signature.js

@@ -11,9 +11,11 @@ const hmacSign = (data, secret) => {
     return hmac.digest("base64url");
 };
 exports.hmacSign = hmacSign;
-const generateStringForSignature = ({ loginUrl, contentPath, externalId, name, nonce, userAttributes, entity, }) => {
+const generateStringForSignature = ({ loginUrl, contentPath, externalId, name, nonce, userAttributes, entity, prefersDark, theme, }) => {
     const optionalParams = [];
     entity && optionalParams.push(entity);
+    prefersDark && optionalParams.push(prefersDark);
+    theme && optionalParams.push(theme);
     userAttributes && optionalParams.push(userAttributes);
     return `
   ${loginUrl}

package/lib/esm/embed.d.ts

@@ -1,14 +1,16 @@
 type EmbedSsoProps = {
     contentId: string;
-    domain?: string;
     externalId: string;
     name: string;
-    nonce?: string;
     organizationName: string;
-    port?: number;
     secret: string;
-    userAttributes?: Record<string, string>;
     entity?: string;
+    userAttributes?: Record<string, string>;
+    prefersDark?: string;
+    theme?: string;
+    domain?: string;
+    nonce?: string;
+    port?: number;
 };
 export declare const embedSsoDashboard: (props: EmbedSsoProps) => string;
 export {};

package/lib/esm/embed.js

@@ -31,7 +31,7 @@ const validateProps = (props) => {
 };
 export const embedSsoDashboard = (props) => {
     validateProps(props);
-    let { contentId, domain, externalId, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, } = props;
+    let { contentId, domain, externalId, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, } = props;
     // Handle defaults
     nonce = nonce ?? random32ByteString();
     domain = domain ?? defaultEmbedDomain;
@@ -50,6 +50,8 @@ export const embedSsoDashboard = (props) => {
         secret,
         userAttributes,
         entity,
+        prefersDark,
+        theme,
     });
     // Build and return the signed url
     url.searchParams.append("contentPath", contentPath);
@@ -59,5 +61,7 @@ export const embedSsoDashboard = (props) => {
     url.searchParams.append("signature", signature);
     userAttributes && url.searchParams.append("userAttributes", userAttributes);
     entity && url.searchParams.append("entity", entity);
+    prefersDark && url.searchParams.append("prefersDark", prefersDark);
+    theme && url.searchParams.append("theme", theme);
     return url.toString();
 };

package/lib/esm/signature.d.ts

@@ -39,9 +39,17 @@ type SignatureProps = {
      * user will this value assigned to its omni_user_embed_entity user attribute.
      */
     entity?: string;
+    /**
+     * Whether the user prefers light, dark, or system theme.
+     */
+    prefersDark?: string;
+    /**
+     * The theme of the embed.
+     */
+    theme?: string;
 };
 export declare const getSignature: ({ secret, ...props }: SignatureProps) => string;
 export declare const TEST_ONLY: {
-    generateStringForSignature: ({ loginUrl, contentPath, externalId, name, nonce, userAttributes, entity, }: Omit<SignatureProps, "secret">) => string;
+    generateStringForSignature: ({ loginUrl, contentPath, externalId, name, nonce, userAttributes, entity, prefersDark, theme, }: Omit<SignatureProps, "secret">) => string;
 };
 export {};

package/lib/esm/signature.js

@@ -4,9 +4,11 @@ export const hmacSign = (data, secret) => {
     hmac.update(data);
     return hmac.digest("base64url");
 };
-const generateStringForSignature = ({ loginUrl, contentPath, externalId, name, nonce, userAttributes, entity, }) => {
+const generateStringForSignature = ({ loginUrl, contentPath, externalId, name, nonce, userAttributes, entity, prefersDark, theme, }) => {
     const optionalParams = [];
     entity && optionalParams.push(entity);
+    prefersDark && optionalParams.push(prefersDark);
+    theme && optionalParams.push(theme);
     userAttributes && optionalParams.push(userAttributes);
     return `
   ${loginUrl}

package/package.json

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