@omni-co/embed 0.2.1 → 0.3.0-pre.1

package/README.md

@@ -1,28 +1,89 @@
-# omni-embed-sdk
+# Omni Embed SSO Typescript SDK
 
-## ⚠️ OmniEmbedSDK uses NPM! ⚠️
+## Install
 
-Publishing to npmjs.org was complicated with Yarn. Until that issue is resolved, please use NPM to manage this package.
+npm:
+```
+npm install @omni-co/embed
+```
 
-## Installation
+yarn:
+```
+yarn add @omni-co/embed
+```
 
-1. git clone the repository
-2. `npm install`
-3. `npm run test`
+## Basic 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",
+    name: "Wile E",
+    organizationName: "acme",
+    secret: "abcdefghijklmnopqrstuvwxyz123456",
+  });
+```
 
-🥳 - 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.
+## Kitchen Sink Example
+
+```ts
+  import { embedSsoDashboard } from '@omni-co/embed'
+
+  // 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" }
+  });
+```
+
+## 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/{esm/embed.js → embed.js}

@@ -1,5 +1,5 @@
-import { random32ByteString } from "./random-str";
-import { getSignature } from "./signature";
+import { random32ByteString } from "./random-str.js";
+import { getSignature } from "./signature.js";
 const defaultEmbedDomain = "embed-omniapp.co";
 const embedLoginRoute = "/embed/login";
 const embedDashboardPath = "/embed/dashboards";
@@ -33,8 +33,8 @@ export const embedSsoDashboard = (props) => {
     validateProps(props);
     let { contentId, domain, externalId, name, nonce, organizationName, port, secret, userAttributes: rawUserAttributes, entity, prefersDark, theme, } = props;
     // Handle defaults
-    nonce = nonce ?? random32ByteString();
-    domain = domain ?? defaultEmbedDomain;
+    nonce = nonce !== null && nonce !== void 0 ? nonce : random32ByteString();
+    domain = domain !== null && domain !== void 0 ? domain : defaultEmbedDomain;
     const userAttributes = rawUserAttributes && JSON.stringify(rawUserAttributes);
     // Generate the url for the embed login route
     const url = new URL(embedLoginRoute, `https://${organizationName.toLocaleLowerCase()}.${domain}${port ? `:${port}` : ""}`);

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./embed.js";
+export * from "./signature.js";

package/lib/index.js

@@ -0,0 +1,2 @@
+export * from "./embed.js";
+export * from "./signature.js";

package/lib/{esm/signature.js → signature.js}

@@ -1,3 +1,14 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 import crypto from "crypto";
 export const hmacSign = (data, secret) => {
     const hmac = crypto.createHmac("sha256", secret);
@@ -21,7 +32,8 @@ const generateStringForSignature = ({ loginUrl, contentPath, externalId, name, n
         .trim()
         .replace(/\n\s+/g, "\n");
 };
-export const getSignature = ({ secret, ...props }) => {
+export const getSignature = (_a) => {
+    var { secret } = _a, props = __rest(_a, ["secret"]);
     return hmacSign(generateStringForSignature(props), secret);
 };
 export const TEST_ONLY = {

package/package.json

@@ -1,10 +1,8 @@
 {
-  "version": "0.2.1",
+  "version": "0.3.0-pre.1",
   "license": "MIT",
   "name": "@omni-co/embed",
   "author": "Nate Agrin <nate@exploreomni.com>",
-  "main": "lib/cjs/index.js",
-  "module": "lib/esm/index.js",
   "files": [
     "lib/**/*"
   ],
@@ -14,7 +12,7 @@
     "vitest": "^0.34.6"
   },
   "scripts": {
-    "build": "npm run clean && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json",
+    "build": "npm run clean && tsc -p tsconfig.json",
     "clean": "rm -rf lib",
     "prepublishOnly": "npm run build",
     "test": "vitest",
@@ -22,5 +20,8 @@
   },
   "dependencies": {
     "nanoid": "^5.0.2"
-  }
+  },
+  "exports": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "type": "module"
 }

package/lib/cjs/embed.js

@@ -1,71 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.embedSsoDashboard = void 0;
-const random_str_1 = require("./random-str");
-const signature_1 = require("./signature");
-const defaultEmbedDomain = "embed-omniapp.co";
-const embedLoginRoute = "/embed/login";
-const embedDashboardPath = "/embed/dashboards";
-const validateProps = (props) => {
-    const { contentId, externalId, name, nonce, organizationName, secret, userAttributes, } = props;
-    if (!contentId) {
-        throw new Error("contentId is required");
-    }
-    if (!externalId) {
-        throw new Error("externalId is required");
-    }
-    if (!name) {
-        throw new Error("name is required");
-    }
-    if (!organizationName) {
-        throw new Error("organizationName is required");
-    }
-    if (!secret) {
-        throw new Error("secret is required");
-    }
-    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");
-        }
-    }
-};
-const embedSsoDashboard = (props) => {
-    validateProps(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;
-    const userAttributes = rawUserAttributes && JSON.stringify(rawUserAttributes);
-    // Generate the url for the embed login route
-    const url = new URL(embedLoginRoute, `https://${organizationName.toLocaleLowerCase()}.${domain}${port ? `:${port}` : ""}`);
-    // Generate the content path
-    const contentPath = `${embedDashboardPath}/${contentId}`;
-    // Get a signature for the request
-    const signature = (0, signature_1.getSignature)({
-        loginUrl: url.toString(),
-        contentPath,
-        externalId,
-        name,
-        nonce,
-        secret,
-        userAttributes,
-        entity,
-        prefersDark,
-        theme,
-    });
-    // Build and return the signed url
-    url.searchParams.append("contentPath", contentPath);
-    url.searchParams.append("externalId", externalId);
-    url.searchParams.append("name", name);
-    url.searchParams.append("nonce", nonce);
-    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/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./embed";
-export * from "./signature";

package/lib/cjs/index.js

@@ -1,18 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./embed"), exports);
-__exportStar(require("./signature"), exports);

package/lib/cjs/random-str.js

@@ -1,11 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.random32ByteString = void 0;
-const nanoid_1 = require("nanoid");
-const humanReadableByteSpace = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-// Generates a random 32 byte, human readable string.
-// Based on math at https://zelark.github.io/nano-id-cc/
-// at 1000 Ids/s it would take more than 1 quadrillion years or
-// 8,730,800,738,924,245T IDs, in order to have a 1% probability
-// of at least one collision.
-exports.random32ByteString = (0, nanoid_1.customAlphabet)(humanReadableByteSpace, 32);

package/lib/cjs/signature.js

@@ -1,37 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TEST_ONLY = exports.getSignature = exports.hmacSign = void 0;
-const crypto_1 = __importDefault(require("crypto"));
-const hmacSign = (data, secret) => {
-    const hmac = crypto_1.default.createHmac("sha256", secret);
-    hmac.update(data);
-    return hmac.digest("base64url");
-};
-exports.hmacSign = hmacSign;
-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}
-  ${contentPath}
-  ${externalId}
-  ${name}
-  ${nonce}
-  ${optionalParams.join("\n")}
-  `
-        .trim()
-        .replace(/\n\s+/g, "\n");
-};
-const getSignature = ({ secret, ...props }) => {
-    return (0, exports.hmacSign)(generateStringForSignature(props), secret);
-};
-exports.getSignature = getSignature;
-exports.TEST_ONLY = {
-    generateStringForSignature,
-};

package/lib/esm/embed.d.ts

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

package/lib/esm/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./embed";
-export * from "./signature";

package/lib/esm/index.js

@@ -1,2 +0,0 @@
-export * from "./embed";
-export * from "./signature";

package/lib/esm/random-str.d.ts

@@ -1 +0,0 @@
-export declare const random32ByteString: (size?: number | undefined) => string;

package/lib/esm/signature.d.ts

@@ -1,55 +0,0 @@
-export declare const hmacSign: (data: string, secret: string) => string;
-type SignatureProps = {
-    /**
-     * The protocol, domain, optional port and /embed/login route of the request.
-     *
-     * Example: `https://example.embed-omniapp.com/embed/login`
-     */
-    loginUrl: string;
-    /**
-     * The path to the content being embedded.
-     *
-     * Example: /embed/dashboards/123abc
-     */
-    contentPath: string;
-    /**
-     * The external id of the user.
-     */
-    externalId: string;
-    /**
-     * The name of the user.
-     */
-    name: string;
-    /**
-     * The nonce of the request.
-     */
-    nonce: string;
-    /**
-     * The secret used to sign the request
-     */
-    secret: string;
-    /**
-     * The user attributes to be sent with the request. Expected to be a stringified JSON object.
-     *
-     * Example: '{ "team": "Lakers" }'
-     */
-    userAttributes?: string;
-    /**
-     * The entity that the created embed user will belong to. Practically speaking, the embed
-     * 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, prefersDark, theme, }: Omit<SignatureProps, "secret">) => string;
-};
-export {};

package/lib/{cjs/embed.d.ts → embed.d.ts}

@@ -1,16 +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 {};