@codatum/embed 0.1.0

package/dist/index.js

@@ -0,0 +1,618 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+
+// src/types.ts
+var SDK_VERSION = "0.1.0";
+var SqlDisplayValues = ["SHOW", "RESULT_ONLY", "HIDE"];
+var ThemeValues = ["LIGHT", "DARK", "SYSTEM"];
+var TokenProviderTriggers = {
+  INIT: "INIT",
+  RELOAD: "RELOAD",
+  REFRESH: "REFRESH"
+};
+var EmbedErrorCodes = {
+  INVALID_OPTIONS: "INVALID_OPTIONS",
+  CONTAINER_NOT_FOUND: "CONTAINER_NOT_FOUND",
+  INIT_TIMEOUT: "INIT_TIMEOUT",
+  TOKEN_PROVIDER_FAILED: "TOKEN_PROVIDER_FAILED",
+  MISSING_REQUIRED_PARAM: "MISSING_REQUIRED_PARAM",
+  INVALID_PARAM_VALUE: "INVALID_PARAM_VALUE",
+  UNEXPECTED_ERROR: "UNEXPECTED_ERROR"
+};
+var EmbedError = class extends Error {
+  constructor(code, message, options) {
+    super(message);
+    this.name = "EmbedError";
+    this.code = code;
+    if ((options == null ? void 0 : options.cause) !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+var RESET_TO_DEFAULT = "_RESET_TO_DEFAULT_";
+var EmbedStatuses = {
+  CREATED: "CREATED",
+  INITIALIZING: "INITIALIZING",
+  READY: "READY",
+  DESTROYED: "DESTROYED"
+};
+
+// src/utils.ts
+var deepClone = (source) => {
+  if (source === null || source === void 0 || typeof source !== "object") return source;
+  if (source instanceof Date) return new Date(source.getTime());
+  if (typeof Node !== "undefined" && source instanceof Node) return source;
+  if (Array.isArray(source)) return source.map(deepClone);
+  const result = {};
+  for (const key of Object.keys(source)) {
+    result[key] = deepClone(source[key]);
+  }
+  return result;
+};
+var EMBED_URL_REGEX = /^https:\/\/app\.codatum\.com\/protected\/workspace\/[a-fA-F0-9]{24}\/notebook\/[a-fA-F0-9]{24}(\?.*)?$/;
+var isValidEmbedUrl = (url) => {
+  return EMBED_URL_REGEX.test(url);
+};
+var buildIframeSrc = (embedUrl, iframeOptions) => {
+  const url = new URL(embedUrl);
+  if (iframeOptions == null ? void 0 : iframeOptions.theme) {
+    url.searchParams.set("theme", iframeOptions.theme);
+  }
+  if (iframeOptions == null ? void 0 : iframeOptions.locale) {
+    url.searchParams.set("locale", iframeOptions.locale);
+  }
+  return url.toString();
+};
+var BASE_IFRAME_CLASS = "codatum-embed-iframe";
+var getIframeClassName = (iframeOptions) => {
+  return BASE_IFRAME_CLASS + ((iframeOptions == null ? void 0 : iframeOptions.className) ? ` ${iframeOptions.className}` : "");
+};
+var getTokenTtlMs = (token) => {
+  try {
+    const base64 = token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/");
+    const payload = JSON.parse(atob(base64));
+    return payload.exp * 1e3 - Date.now();
+  } catch (error) {
+    console.error(`Failed to parse token. Auto-refresh is disabled.`, error);
+    return null;
+  }
+};
+var validateEmbedOptions = (options) => {
+  const throwError = (message) => {
+    throw new EmbedError(EmbedErrorCodes.INVALID_OPTIONS, message);
+  };
+  if (!options.container || typeof options.container !== "string" && !(options.container instanceof HTMLElement)) {
+    throwError("container must be an HTMLElement or a string selector");
+  }
+  if (!options.embedUrl || !isValidEmbedUrl(options.embedUrl)) {
+    throwError(
+      "embedUrl must match https://app.codatum.com/protected/workspace/{workspaceId}/notebook/{notebookId}"
+    );
+  }
+  if (!options.tokenProvider || typeof options.tokenProvider !== "function") {
+    throwError("tokenProvider must be a function");
+  }
+  if (options.iframeOptions) {
+    if (typeof options.iframeOptions !== "object") {
+      throwError("iframeOptions must be an object");
+    }
+    const theme = options.iframeOptions.theme;
+    if (theme !== void 0 && !ThemeValues.includes(theme)) {
+      throwError(`iframeOptions.theme must be one of ${ThemeValues.join(", ")}`);
+    }
+    const locale = options.iframeOptions.locale;
+    if (locale !== void 0 && typeof locale !== "string") {
+      throwError("iframeOptions.locale must be a string");
+    }
+    const className = options.iframeOptions.className;
+    if (className !== void 0 && typeof className !== "string") {
+      throwError("iframeOptions.className must be a string");
+    }
+    const style = options.iframeOptions.style;
+    if (style !== void 0 && typeof style !== "object") {
+      throwError("iframeOptions.style must be a CSSStyleDeclaration");
+    }
+  }
+  if (options.tokenOptions) {
+    if (typeof options.tokenOptions !== "object") {
+      throwError("tokenOptions must be an object");
+    }
+    const refreshBuffer = options.tokenOptions.refreshBuffer;
+    if (refreshBuffer !== void 0 && (typeof refreshBuffer !== "number" || refreshBuffer < 0)) {
+      throwError("tokenOptions.refreshBuffer must be a non-negative number");
+    }
+    const retryCount = options.tokenOptions.retryCount;
+    if (retryCount !== void 0 && (typeof retryCount !== "number" || retryCount < 0)) {
+      throwError("tokenOptions.retryCount must be a non-negative number");
+    }
+    const initTimeout = options.tokenOptions.initTimeout;
+    if (initTimeout !== void 0 && (typeof initTimeout !== "number" || initTimeout < 0)) {
+      throwError("tokenOptions.initTimeout must be a non-negative number");
+    }
+    const onRefreshError = options.tokenOptions.onRefreshError;
+    if (onRefreshError !== void 0 && typeof onRefreshError !== "function") {
+      throwError("tokenOptions.onRefreshError must be a function");
+    }
+  }
+  if (options.displayOptions) {
+    if (typeof options.displayOptions !== "object") {
+      throwError("displayOptions must be an object");
+    }
+    const sqlDisplay = options.displayOptions.sqlDisplay;
+    if (sqlDisplay !== void 0 && !SqlDisplayValues.includes(sqlDisplay)) {
+      throwError(`displayOptions.sqlDisplay must be one of ${SqlDisplayValues.join(", ")}`);
+    }
+    const hideParamsForm = options.displayOptions.hideParamsForm;
+    if (hideParamsForm !== void 0 && typeof hideParamsForm !== "boolean") {
+      throwError("displayOptions.hideParamsForm must be a boolean");
+    }
+    const expandParamsFormByDefault = options.displayOptions.expandParamsFormByDefault;
+    if (expandParamsFormByDefault !== void 0 && typeof expandParamsFormByDefault !== "boolean") {
+      throwError("displayOptions.expandParamsFormByDefault must be a boolean");
+    }
+  }
+};
+
+// src/Embed.ts
+var DEFAULT_REFRESH_BUFFER = 60;
+var DEFAULT_RETRY_COUNT = 2;
+var DEFAULT_INIT_TIMEOUT = 30;
+var SHORT_TTL_THRESHOLD = 10 * 1e3;
+var SHORT_TTL_MAX_CONSECUTIVE = 3;
+var EmbedInstance = class {
+  constructor(options) {
+    this.iframeEl = null;
+    this.shortTtlCount = 0;
+    this._status = EmbedStatuses.CREATED;
+    this.initTimeoutId = null;
+    this.refreshTimerId = null;
+    this.reloadInProgress = false;
+    this.readyForTokenHandled = false;
+    this.eventHandlers = {
+      paramChanged: [],
+      executeSqlsTriggered: []
+    };
+    this.boundHandleMessage = (event) => this.handleMessage(event);
+    var _a, _b, _c;
+    validateEmbedOptions(options);
+    this.options = deepClone(options);
+    this.expectedOrigin = new URL(this.options.embedUrl).origin;
+    const tokenOptions = (_a = this.options.tokenOptions) != null ? _a : {};
+    this.refreshBuffer = ((_b = tokenOptions.refreshBuffer) != null ? _b : DEFAULT_REFRESH_BUFFER) * 1e3;
+    this.retryCount = (_c = tokenOptions.retryCount) != null ? _c : DEFAULT_RETRY_COUNT;
+    this.onRefreshError = tokenOptions.onRefreshError;
+    this.initPromise = new Promise((resolve, reject) => {
+      this.resolveInit = resolve;
+      this.rejectInit = reject;
+    });
+    window.addEventListener("message", this.boundHandleMessage);
+  }
+  /**
+   * Creates the iframe, appends it to the container, and starts the token/connection flow.
+   * Call this after createEmbed() to complete initialization.
+   */
+  init() {
+    var _a, _b;
+    if (this.isDestroyed) {
+      return Promise.resolve();
+    }
+    if (this._status !== EmbedStatuses.CREATED) {
+      return this.initPromise;
+    }
+    this._status = EmbedStatuses.INITIALIZING;
+    const container = typeof this.options.container === "string" ? document.querySelector(this.options.container) : this.options.container;
+    if (!container) {
+      this.rejectInit(
+        new EmbedError(EmbedErrorCodes.CONTAINER_NOT_FOUND, "Container element not found")
+      );
+      return this.initPromise;
+    }
+    const iframeOptions = this.options.iframeOptions;
+    const iframe = document.createElement("iframe");
+    iframe.src = buildIframeSrc(this.options.embedUrl, iframeOptions);
+    iframe.className = getIframeClassName(iframeOptions);
+    iframe.setAttribute("allow", "fullscreen; clipboard-write");
+    Object.assign(iframe.style, __spreadValues({
+      width: "100%",
+      height: "100%",
+      border: "none"
+    }, iframeOptions == null ? void 0 : iframeOptions.style));
+    this.iframeEl = iframe;
+    container.appendChild(iframe);
+    const initTimeoutMs = ((_b = (_a = this.options.tokenOptions) == null ? void 0 : _a.initTimeout) != null ? _b : DEFAULT_INIT_TIMEOUT) * 1e3;
+    if (initTimeoutMs > 0) {
+      this.initTimeoutId = setTimeout(() => {
+        this.initTimeoutId = null;
+        if (this._status === EmbedStatuses.INITIALIZING) {
+          this.destroy();
+          this.rejectInit(
+            new EmbedError(
+              EmbedErrorCodes.INIT_TIMEOUT,
+              `Initialization did not complete within ${initTimeoutMs}ms`
+            )
+          );
+        }
+      }, initTimeoutMs);
+    }
+    return this.initPromise;
+  }
+  get iframe() {
+    return this.isDestroyed ? null : this.iframeEl;
+  }
+  get status() {
+    return this._status;
+  }
+  get isDestroyed() {
+    return this._status === EmbedStatuses.DESTROYED;
+  }
+  clearInitTimeout() {
+    if (this.initTimeoutId !== null) {
+      clearTimeout(this.initTimeoutId);
+      this.initTimeoutId = null;
+    }
+  }
+  clearRefreshTimer() {
+    if (this.refreshTimerId !== null) {
+      clearTimeout(this.refreshTimerId);
+      this.refreshTimerId = null;
+    }
+  }
+  sendSetToken(result) {
+    if (!this.iframeEl) return;
+    const win = this.iframeEl.contentWindow;
+    if (!win || this.isDestroyed) return;
+    const payload = __spreadValues({
+      displayOptions: this.options.displayOptions
+    }, result.params != null && result.params.length > 0 ? { params: result.params } : {});
+    try {
+      const serialized = Object.keys(payload).length ? JSON.parse(JSON.stringify(payload)) : void 0;
+      win.postMessage(
+        __spreadValues({
+          type: "SET_TOKEN",
+          token: result.token,
+          sdkVersion: SDK_VERSION
+        }, serialized),
+        this.expectedOrigin
+      );
+    } catch (err) {
+      throw new EmbedError(
+        EmbedErrorCodes.UNEXPECTED_ERROR,
+        err instanceof Error ? err.message : String(err),
+        { cause: err }
+      );
+    }
+  }
+  /**
+   * Calls tokenProvider with context and retries with exponential backoff up to retryCount on failure,
+   * unless context.markNonRetryable() was called. On success, schedules the next token refresh.
+   */
+  fetchSessionWithRetry(trigger, attempt = 0, delayMs = 1e3) {
+    let nonRetryable = false;
+    const context = {
+      trigger,
+      markNonRetryable: () => {
+        nonRetryable = true;
+      }
+    };
+    return this.options.tokenProvider(context).then((session) => {
+      const ttlMs = getTokenTtlMs(session.token);
+      if (ttlMs !== null) {
+        this.scheduleRefresh(ttlMs);
+      }
+      return session;
+    }).catch((err) => {
+      if (this.isDestroyed) return Promise.reject(err);
+      if (nonRetryable || attempt >= this.retryCount) {
+        return Promise.reject(err);
+      }
+      return new Promise((resolve, reject) => {
+        setTimeout(() => {
+          this.fetchSessionWithRetry(trigger, attempt + 1, delayMs * 2).then(resolve, reject);
+        }, delayMs);
+      });
+    });
+  }
+  scheduleRefresh(ttlMs) {
+    if (this.isDestroyed) return;
+    this.clearRefreshTimer();
+    const delayMs = Math.max(0, ttlMs - this.refreshBuffer);
+    if (delayMs < SHORT_TTL_THRESHOLD) {
+      this.shortTtlCount++;
+      if (this.shortTtlCount > SHORT_TTL_MAX_CONSECUTIVE) {
+        console.warn(
+          `Auto-refresh disabled: token refresh interval has been too short (< ${SHORT_TTL_THRESHOLD}ms) for ${SHORT_TTL_MAX_CONSECUTIVE} consecutive attempts.`
+        );
+        return;
+      }
+    } else {
+      this.shortTtlCount = 0;
+    }
+    this.refreshTimerId = setTimeout(() => {
+      this.refreshTimerId = null;
+      this.runRefreshWithRetry();
+    }, delayMs);
+  }
+  runRefreshWithRetry() {
+    if (this.isDestroyed) return;
+    this.fetchSessionWithRetry(TokenProviderTriggers.REFRESH).then((result) => {
+      if (this.isDestroyed) return;
+      this.sendSetToken(result);
+    }).catch((err) => {
+      var _a;
+      if (this.isDestroyed) return;
+      (_a = this.onRefreshError) == null ? void 0 : _a.call(
+        this,
+        new EmbedError(
+          EmbedErrorCodes.TOKEN_PROVIDER_FAILED,
+          err instanceof Error ? err.message : String(err),
+          { cause: err }
+        )
+      );
+    });
+  }
+  handleMessage(event) {
+    if (!this.iframeEl || event.source !== this.iframeEl.contentWindow || event.origin !== this.expectedOrigin) {
+      return;
+    }
+    const data = event.data;
+    if (!data || typeof data !== "object" || typeof data.type !== "string") {
+      return;
+    }
+    if (data.type === "READY_FOR_TOKEN") {
+      this.onReadyForToken();
+    } else if (data.type === "PARAM_CHANGED") {
+      for (const h of this.eventHandlers.paramChanged) {
+        h(deepClone(data));
+      }
+    } else if (data.type === "EXECUTE_SQLS_TRIGGERED") {
+      for (const h of this.eventHandlers.executeSqlsTriggered) {
+        h(deepClone(data));
+      }
+    }
+  }
+  onReadyForToken() {
+    if (this.readyForTokenHandled || this._status !== EmbedStatuses.INITIALIZING) return;
+    this.readyForTokenHandled = true;
+    this.fetchSessionWithRetry(TokenProviderTriggers.INIT).then((result) => {
+      if (this.isDestroyed) return;
+      this._status = EmbedStatuses.READY;
+      this.clearInitTimeout();
+      this.sendSetToken(result);
+      this.resolveInit();
+    }).catch((err) => {
+      if (this.isDestroyed) return;
+      this.clearInitTimeout();
+      this.rejectInit(
+        new EmbedError(
+          EmbedErrorCodes.TOKEN_PROVIDER_FAILED,
+          err instanceof Error ? err.message : String(err),
+          { cause: err }
+        )
+      );
+    });
+  }
+  reload() {
+    if (this.isDestroyed) return Promise.resolve();
+    if (this._status !== EmbedStatuses.READY) return Promise.resolve();
+    if (this.reloadInProgress) return Promise.resolve();
+    this.reloadInProgress = true;
+    return this.fetchSessionWithRetry(TokenProviderTriggers.RELOAD).then(
+      (result) => {
+        this.reloadInProgress = false;
+        if (this.isDestroyed) return;
+        this.sendSetToken(result);
+      },
+      (err) => {
+        this.reloadInProgress = false;
+        if (this.isDestroyed) return;
+        throw new EmbedError(
+          EmbedErrorCodes.TOKEN_PROVIDER_FAILED,
+          err instanceof Error ? err.message : String(err),
+          { cause: err }
+        );
+      }
+    );
+  }
+  on(event, handler) {
+    if (this.isDestroyed) return;
+    this.eventHandlers[event].push(handler);
+  }
+  off(event, handler) {
+    const list = this.eventHandlers[event];
+    const i = list.indexOf(handler);
+    if (i !== -1) list.splice(i, 1);
+  }
+  destroy() {
+    var _a;
+    if (this.isDestroyed) return;
+    this._status = EmbedStatuses.DESTROYED;
+    this.clearInitTimeout();
+    this.clearRefreshTimer();
+    window.removeEventListener("message", this.boundHandleMessage);
+    (_a = this.iframeEl) == null ? void 0 : _a.remove();
+    this.iframeEl = null;
+  }
+};
+function createEmbed(options) {
+  return new EmbedInstance(options);
+}
+
+// src/ParamMapper.ts
+var DATE_FORMAT_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+var isValidDateFormat = (s) => {
+  return DATE_FORMAT_REGEX.test(s);
+};
+var validateDatatype = (value, datatype, key) => {
+  if (value === RESET_TO_DEFAULT) return;
+  switch (datatype) {
+    case "STRING":
+      if (typeof value !== "string") {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Parameter ${key} must be a string, got ${typeof value}`
+        );
+      }
+      return;
+    case "NUMBER":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Parameter ${key} must be a number, got ${typeof value}`
+        );
+      }
+      return;
+    case "BOOLEAN":
+      if (typeof value !== "boolean") {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Parameter ${key} must be a boolean, got ${typeof value}`
+        );
+      }
+      return;
+    case "DATE":
+      if (typeof value !== "string") {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Parameter ${key} must be a date string, got ${typeof value}`
+        );
+      }
+      if (!isValidDateFormat(value)) {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Parameter ${key} must be a date in YYYY-MM-DD format, got: ${value}`
+        );
+      }
+      return;
+    case "STRING[]":
+      if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Parameter ${key} must be a string array`
+        );
+      }
+      return;
+    case "[DATE, DATE]":
+      if (!Array.isArray(value) || value.length !== 2 || typeof value[0] !== "string" || typeof value[1] !== "string") {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Parameter ${key} must be a [string, string] tuple (date range)`
+        );
+      }
+      if (!isValidDateFormat(value[0]) || !isValidDateFormat(value[1])) {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Parameter ${key} must be a date range in YYYY-MM-DD format, got: [${value[0]}, ${value[1]}]`
+        );
+      }
+      return;
+    default: {
+      const _ = datatype;
+      return;
+    }
+  }
+};
+var ParamMapper = class {
+  constructor(mapping, meta) {
+    this.defs = {};
+    for (const key of Object.keys(mapping)) {
+      const paramId = mapping[key];
+      const m = meta == null ? void 0 : meta[key];
+      this.defs[key] = __spreadValues({ paramId }, m);
+    }
+    this.aliasByParamId = /* @__PURE__ */ new Map();
+    for (const [alias, paramId] of Object.entries(mapping)) {
+      this.aliasByParamId.set(paramId, alias);
+    }
+  }
+  encode(values, options) {
+    var _a;
+    const result = [];
+    const keys = (_a = options == null ? void 0 : options.only) != null ? _a : Object.keys(this.defs);
+    const valuesByKey = values;
+    const skipValidation = (options == null ? void 0 : options.noValidate) === true;
+    for (const key of keys) {
+      const def = this.defs[key];
+      if (def == null) continue;
+      const raw = valuesByKey[key];
+      if (raw == null) {
+        if (!skipValidation && def.required) {
+          throw new EmbedError(
+            EmbedErrorCodes.MISSING_REQUIRED_PARAM,
+            `Missing required parameter: ${key}`
+          );
+        }
+        continue;
+      }
+      if (!skipValidation && def.datatype) {
+        validateDatatype(raw, def.datatype, key);
+      }
+      result.push({
+        param_id: def.paramId,
+        param_value: raw === RESET_TO_DEFAULT ? RESET_TO_DEFAULT : JSON.stringify(raw),
+        is_hidden: def.hidden ? true : void 0
+      });
+    }
+    return result;
+  }
+  decode(params, options) {
+    var _a;
+    const result = {};
+    const keys = (_a = options == null ? void 0 : options.only) != null ? _a : Object.keys(this.defs);
+    const skipValidation = (options == null ? void 0 : options.noValidate) === true;
+    for (const key of keys) {
+      const def = this.defs[key];
+      if (def == null) continue;
+      const encodedParam = params.find((p) => p.param_id === def.paramId);
+      if (encodedParam == null) {
+        if (!skipValidation && def.required) {
+          throw new EmbedError(
+            EmbedErrorCodes.MISSING_REQUIRED_PARAM,
+            `Missing required parameter: ${key}`
+          );
+        }
+        continue;
+      }
+      let decoded;
+      try {
+        decoded = JSON.parse(encodedParam.param_value);
+      } catch (e) {
+        throw new EmbedError(
+          EmbedErrorCodes.INVALID_PARAM_VALUE,
+          `Invalid parameter value: ${encodedParam.param_value}`
+        );
+      }
+      if (!skipValidation && def.datatype) {
+        validateDatatype(decoded, def.datatype, key);
+      }
+      result[key] = decoded;
+    }
+    return result;
+  }
+};
+function createParamMapper(mapping, meta) {
+  return new ParamMapper(mapping, meta);
+}
+export {
+  EmbedError,
+  EmbedErrorCodes,
+  EmbedStatuses,
+  RESET_TO_DEFAULT,
+  SDK_VERSION,
+  createEmbed,
+  createParamMapper
+};
+//# sourceMappingURL=index.js.map