@basedash/embed 0.1.0

package/dist/server.d.cts

@@ -0,0 +1,59 @@
+import { EmbedUser, BasedashRole } from './index.cjs';
+
+type EmbedSecret = string | Uint8Array;
+/**
+ * A duration understood by `jose` (for example, `"10m"` or `"1h"`) or a
+ * duration in seconds.
+ */
+type TokenExpiration = string | number;
+type DashboardFilterValue = string | string[] | number | boolean;
+interface CreateEmbedTokenOptions {
+    secret: EmbedSecret;
+    orgId: string;
+    user: EmbedUser;
+    /**
+     * @default "10m"
+     */
+    expiresIn?: TokenExpiration;
+}
+interface CreateDashboardFilterTokenOptions {
+    secret: EmbedSecret;
+    dashboardLinkId: string;
+    params: Record<string, DashboardFilterValue>;
+    /**
+     * @default "1h"
+     */
+    expiresIn?: TokenExpiration;
+}
+interface EmbedTokenClaims {
+    email: string;
+    orgId: string;
+    firstName?: string;
+    lastName?: string;
+    role?: BasedashRole;
+    groups?: string[];
+    iat: number;
+    exp: number;
+}
+interface DashboardFilterTokenClaims {
+    dashboardLinkId: string;
+    params: Record<string, DashboardFilterValue>;
+    iat: number;
+    exp: number;
+}
+/**
+ * Creates the short-lived JWT used by full-app Basedash embeds.
+ *
+ * This function must only run on a trusted server. Never send the embed secret
+ * to a browser.
+ */
+declare function createEmbedToken({ secret, orgId, user, expiresIn, }: CreateEmbedTokenOptions): Promise<string>;
+/**
+ * Creates a JWT that locks filter values on a shared dashboard.
+ *
+ * This function must only run on a trusted server. Never send the embed secret
+ * to a browser.
+ */
+declare function createDashboardFilterToken({ secret, dashboardLinkId, params, expiresIn, }: CreateDashboardFilterTokenOptions): Promise<string>;
+
+export { type CreateDashboardFilterTokenOptions, type CreateEmbedTokenOptions, type DashboardFilterTokenClaims, type DashboardFilterValue, type EmbedSecret, type EmbedTokenClaims, type TokenExpiration, createDashboardFilterToken, createEmbedToken };

package/dist/server.d.ts

@@ -0,0 +1,59 @@
+import { EmbedUser, BasedashRole } from './index.js';
+
+type EmbedSecret = string | Uint8Array;
+/**
+ * A duration understood by `jose` (for example, `"10m"` or `"1h"`) or a
+ * duration in seconds.
+ */
+type TokenExpiration = string | number;
+type DashboardFilterValue = string | string[] | number | boolean;
+interface CreateEmbedTokenOptions {
+    secret: EmbedSecret;
+    orgId: string;
+    user: EmbedUser;
+    /**
+     * @default "10m"
+     */
+    expiresIn?: TokenExpiration;
+}
+interface CreateDashboardFilterTokenOptions {
+    secret: EmbedSecret;
+    dashboardLinkId: string;
+    params: Record<string, DashboardFilterValue>;
+    /**
+     * @default "1h"
+     */
+    expiresIn?: TokenExpiration;
+}
+interface EmbedTokenClaims {
+    email: string;
+    orgId: string;
+    firstName?: string;
+    lastName?: string;
+    role?: BasedashRole;
+    groups?: string[];
+    iat: number;
+    exp: number;
+}
+interface DashboardFilterTokenClaims {
+    dashboardLinkId: string;
+    params: Record<string, DashboardFilterValue>;
+    iat: number;
+    exp: number;
+}
+/**
+ * Creates the short-lived JWT used by full-app Basedash embeds.
+ *
+ * This function must only run on a trusted server. Never send the embed secret
+ * to a browser.
+ */
+declare function createEmbedToken({ secret, orgId, user, expiresIn, }: CreateEmbedTokenOptions): Promise<string>;
+/**
+ * Creates a JWT that locks filter values on a shared dashboard.
+ *
+ * This function must only run on a trusted server. Never send the embed secret
+ * to a browser.
+ */
+declare function createDashboardFilterToken({ secret, dashboardLinkId, params, expiresIn, }: CreateDashboardFilterTokenOptions): Promise<string>;
+
+export { type CreateDashboardFilterTokenOptions, type CreateEmbedTokenOptions, type DashboardFilterTokenClaims, type DashboardFilterValue, type EmbedSecret, type EmbedTokenClaims, type TokenExpiration, createDashboardFilterToken, createEmbedToken };

package/dist/server.js

@@ -0,0 +1,83 @@
+import { SignJWT } from 'jose';
+
+// src/server/index.ts
+var ALGORITHM = "HS256";
+var DEFAULT_EMBED_TOKEN_EXPIRATION = "10m";
+var DEFAULT_DASHBOARD_TOKEN_EXPIRATION = "1h";
+async function createEmbedToken({
+  secret,
+  orgId,
+  user,
+  expiresIn = DEFAULT_EMBED_TOKEN_EXPIRATION
+}) {
+  assertSecret(secret);
+  assertNonEmpty(orgId, "orgId");
+  assertNonEmpty(user.email, "user.email");
+  assertExpiration(expiresIn);
+  const payload = {
+    email: user.email,
+    orgId,
+    ...user.firstName === void 0 ? {} : { firstName: user.firstName },
+    ...user.lastName === void 0 ? {} : { lastName: user.lastName },
+    ...user.role === void 0 ? {} : { role: user.role },
+    ...user.groups === void 0 ? {} : { groups: user.groups }
+  };
+  return signToken(payload, secret, expiresIn);
+}
+async function createDashboardFilterToken({
+  secret,
+  dashboardLinkId,
+  params,
+  expiresIn = DEFAULT_DASHBOARD_TOKEN_EXPIRATION
+}) {
+  assertSecret(secret);
+  assertNonEmpty(dashboardLinkId, "dashboardLinkId");
+  assertExpiration(expiresIn);
+  assertDashboardParams(params);
+  return signToken(
+    {
+      dashboardLinkId,
+      params
+    },
+    secret,
+    expiresIn
+  );
+}
+async function signToken(payload, secret, expiresIn) {
+  const issuedAt = Math.floor(Date.now() / 1e3);
+  const expiration = typeof expiresIn === "number" ? issuedAt + expiresIn : expiresIn;
+  return new SignJWT(payload).setProtectedHeader({ alg: ALGORITHM, typ: "JWT" }).setIssuedAt(issuedAt).setExpirationTime(expiration).sign(toSecretKey(secret));
+}
+function toSecretKey(secret) {
+  return typeof secret === "string" ? new TextEncoder().encode(secret) : secret;
+}
+function assertSecret(secret) {
+  if (typeof secret === "string" && secret.length === 0 || secret instanceof Uint8Array && secret.byteLength === 0) {
+    throw new TypeError("secret must not be empty");
+  }
+}
+function assertExpiration(expiresIn) {
+  if (typeof expiresIn === "string" && expiresIn.trim().length === 0 || typeof expiresIn === "number" && (!Number.isFinite(expiresIn) || expiresIn <= 0)) {
+    throw new TypeError("expiresIn must be a positive duration");
+  }
+}
+function assertDashboardParams(params) {
+  for (const [key, value] of Object.entries(params)) {
+    assertNonEmpty(key, "params key");
+    const validValue = typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) || Array.isArray(value) && value.every((item) => typeof item === "string");
+    if (!validValue) {
+      throw new TypeError(
+        `params.${key} must be a string, string array, finite number, or boolean`
+      );
+    }
+  }
+}
+function assertNonEmpty(value, name) {
+  if (value.trim().length === 0) {
+    throw new TypeError(`${name} must not be empty`);
+  }
+}
+
+export { createDashboardFilterToken, createEmbedToken };
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/index.ts"],"names":[],"mappings":"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","file":"server.js","sourcesContent":["import { SignJWT } from \"jose\";\n\nimport type { BasedashRole, EmbedUser } from \"../embed\";\n\nconst ALGORITHM = \"HS256\";\nconst DEFAULT_EMBED_TOKEN_EXPIRATION = \"10m\";\nconst DEFAULT_DASHBOARD_TOKEN_EXPIRATION = \"1h\";\n\nexport type EmbedSecret = string | Uint8Array;\n\n/**\n * A duration understood by `jose` (for example, `\"10m\"` or `\"1h\"`) or a\n * duration in seconds.\n */\nexport type TokenExpiration = string | number;\n\nexport type DashboardFilterValue = string | string[] | number | boolean;\n\nexport interface CreateEmbedTokenOptions {\n  secret: EmbedSecret;\n  orgId: string;\n  user: EmbedUser;\n  /**\n   * @default \"10m\"\n   */\n  expiresIn?: TokenExpiration;\n}\n\nexport interface CreateDashboardFilterTokenOptions {\n  secret: EmbedSecret;\n  dashboardLinkId: string;\n  params: Record<string, DashboardFilterValue>;\n  /**\n   * @default \"1h\"\n   */\n  expiresIn?: TokenExpiration;\n}\n\nexport interface EmbedTokenClaims {\n  email: string;\n  orgId: string;\n  firstName?: string;\n  lastName?: string;\n  role?: BasedashRole;\n  groups?: string[];\n  iat: number;\n  exp: number;\n}\n\nexport interface DashboardFilterTokenClaims {\n  dashboardLinkId: string;\n  params: Record<string, DashboardFilterValue>;\n  iat: number;\n  exp: number;\n}\n\n/**\n * Creates the short-lived JWT used by full-app Basedash embeds.\n *\n * This function must only run on a trusted server. Never send the embed secret\n * to a browser.\n */\nexport async function createEmbedToken({\n  secret,\n  orgId,\n  user,\n  expiresIn = DEFAULT_EMBED_TOKEN_EXPIRATION,\n}: CreateEmbedTokenOptions): Promise<string> {\n  assertSecret(secret);\n  assertNonEmpty(orgId, \"orgId\");\n  assertNonEmpty(user.email, \"user.email\");\n  assertExpiration(expiresIn);\n\n  const payload = {\n    email: user.email,\n    orgId,\n    ...(user.firstName === undefined ? {} : { firstName: user.firstName }),\n    ...(user.lastName === undefined ? {} : { lastName: user.lastName }),\n    ...(user.role === undefined ? {} : { role: user.role }),\n    ...(user.groups === undefined ? {} : { groups: user.groups }),\n  };\n\n  return signToken(payload, secret, expiresIn);\n}\n\n/**\n * Creates a JWT that locks filter values on a shared dashboard.\n *\n * This function must only run on a trusted server. Never send the embed secret\n * to a browser.\n */\nexport async function createDashboardFilterToken({\n  secret,\n  dashboardLinkId,\n  params,\n  expiresIn = DEFAULT_DASHBOARD_TOKEN_EXPIRATION,\n}: CreateDashboardFilterTokenOptions): Promise<string> {\n  assertSecret(secret);\n  assertNonEmpty(dashboardLinkId, \"dashboardLinkId\");\n  assertExpiration(expiresIn);\n  assertDashboardParams(params);\n\n  return signToken(\n    {\n      dashboardLinkId,\n      params,\n    },\n    secret,\n    expiresIn,\n  );\n}\n\nasync function signToken(\n  payload: Record<string, unknown>,\n  secret: EmbedSecret,\n  expiresIn: TokenExpiration,\n): Promise<string> {\n  const issuedAt = Math.floor(Date.now() / 1000);\n  const expiration =\n    typeof expiresIn === \"number\" ? issuedAt + expiresIn : expiresIn;\n\n  return new SignJWT(payload)\n    .setProtectedHeader({ alg: ALGORITHM, typ: \"JWT\" })\n    .setIssuedAt(issuedAt)\n    .setExpirationTime(expiration)\n    .sign(toSecretKey(secret));\n}\n\nfunction toSecretKey(secret: EmbedSecret): Uint8Array {\n  return typeof secret === \"string\" ? new TextEncoder().encode(secret) : secret;\n}\n\nfunction assertSecret(secret: EmbedSecret): void {\n  if (\n    (typeof secret === \"string\" && secret.length === 0) ||\n    (secret instanceof Uint8Array && secret.byteLength === 0)\n  ) {\n    throw new TypeError(\"secret must not be empty\");\n  }\n}\n\nfunction assertExpiration(expiresIn: TokenExpiration): void {\n  if (\n    (typeof expiresIn === \"string\" && expiresIn.trim().length === 0) ||\n    (typeof expiresIn === \"number\" &&\n      (!Number.isFinite(expiresIn) || expiresIn <= 0))\n  ) {\n    throw new TypeError(\"expiresIn must be a positive duration\");\n  }\n}\n\nfunction assertDashboardParams(\n  params: Record<string, DashboardFilterValue>,\n): void {\n  for (const [key, value] of Object.entries(params)) {\n    assertNonEmpty(key, \"params key\");\n\n    const validValue =\n      typeof value === \"string\" ||\n      typeof value === \"boolean\" ||\n      (typeof value === \"number\" && Number.isFinite(value)) ||\n      (Array.isArray(value) &&\n        value.every((item): item is string => typeof item === \"string\"));\n\n    if (!validValue) {\n      throw new TypeError(\n        `params.${key} must be a string, string array, finite number, or boolean`,\n      );\n    }\n  }\n}\n\nfunction assertNonEmpty(value: string, name: string): void {\n  if (value.trim().length === 0) {\n    throw new TypeError(`${name} must not be empty`);\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@basedash/embed",
+  "version": "0.1.0",
+  "description": "Typed helpers and React components for embedding Basedash",
+  "license": "MIT",
+  "author": "Basedash",
+  "homepage": "https://www.basedash.com/docs/features/embedding",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Basedash/embed.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Basedash/embed/issues"
+  },
+  "keywords": [
+    "basedash",
+    "analytics",
+    "embedding",
+    "iframe",
+    "react"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "scripts": {
+    "build": "tsup",
+    "check": "pnpm typecheck && pnpm test && pnpm build && publint && attw --pack . --profile node16",
+    "changeset": "changeset",
+    "dev": "tsup --watch",
+    "lint": "pnpm typecheck",
+    "prepublishOnly": "pnpm check",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "jose": "^6.2.10"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0 <20"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@changesets/cli": "^3.0.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "jsdom": "^30.0.1",
+    "publint": "^0.3.24",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}