@relayerfi/widget-kit-core 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @relayerfi/widget-kit-core
+
+[![npm version](https://img.shields.io/npm/v/@relayerfi/widget-kit-core.svg)](https://www.npmjs.com/package/@relayerfi/widget-kit-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Framework-agnostic runtime for Relayer widgets. Handles widget directory management, metadata fetching, URL security classification, and proxy communication.
+
+This package is used internally by `@relayerfi/widget-kit-react`. Most integrators should install that package instead.
+
+## Install
+
+```bash
+pnpm add @relayerfi/widget-kit-core
+```
+
+## What It Does
+
+- **WidgetDirectory** - Classifies widget URLs as trusted, malicious, or unknown
+- **Metadata fetching** - Resolves action metadata from widget URLs via the Relayer proxy
+- **Error types** - Structured `WidgetError` with factory methods
+- **Utilities** - URL formatting, client-key management, proxy endpoint builders
+
+## Key Exports
+
+```typescript
+import { WidgetDirectory, WidgetError, PROXY_URL } from '@relayerfi/widget-kit-core';
+
+const directory = WidgetDirectory.getInstance();
+await directory.init();
+const state = directory.lookup('https://app.relayer.fi');
+```
+
+## Related Packages
+
+| Package | Purpose |
+|---------|---------|
+| [`@relayerfi/action-kit`](https://www.npmjs.com/package/@relayerfi/action-kit) | Action type definitions, validators, executors |
+| [`@relayerfi/widget-kit-react`](https://www.npmjs.com/package/@relayerfi/widget-kit-react) | React components for rendering widgets |
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,625 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  API_REPOSITORY_URL: () => API_REPOSITORY_URL,
+  BlockchainError: () => BlockchainError,
+  ErrorUtils: () => ErrorUtils,
+  InvalidOperationError: () => InvalidOperationError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  PROXY_TO_DEV_HEADERS: () => import_action_kit.PROXY_TO_DEV_HEADERS,
+  PROXY_URL: () => PROXY_URL,
+  RELAYER_VALUES: () => import_action_kit.RELAYER_VALUES,
+  RelayerError: () => RelayerError,
+  SDK_TO_PROXY_HEADERS: () => import_action_kit.SDK_TO_PROXY_HEADERS,
+  SecurityError: () => SecurityError,
+  VALID_OPERATIONS: () => import_action_kit.VALID_OPERATIONS,
+  VERSION: () => VERSION,
+  ValidationError: () => ValidationError,
+  WidgetDirectory: () => WidgetDirectory,
+  WidgetError: () => WidgetError,
+  addHexPrefix: () => addHexPrefix,
+  clearClientKey: () => clearClientKey,
+  execute: () => execute,
+  formatNumber: () => formatNumber,
+  getClientKey: () => getClientKey,
+  getMetadata: () => getMetadata,
+  proxify: () => proxify,
+  removeHexPrefix: () => removeHexPrefix,
+  setClientKey: () => setClientKey,
+  truncateAddress: () => truncateAddress,
+  truncateString: () => truncateString
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils/client-key.ts
+var globalClientKey = "";
+var EXTENSION_STORAGE_KEY = "relayer_client_key";
+function getStorageAPI() {
+  if (typeof chrome !== "undefined" && chrome.storage) {
+    return chrome.storage;
+  }
+  if (typeof browser !== "undefined" && browser.storage) {
+    return browser.storage;
+  }
+  return null;
+}
+async function setClientKey(key) {
+  if (!key || key.trim() === "") {
+    throw new Error("Client key is required and cannot be empty");
+  }
+  globalClientKey = key;
+  const storage = getStorageAPI();
+  if (storage) {
+    try {
+      await storage.local.set({ [EXTENSION_STORAGE_KEY]: key });
+    } catch (error) {
+      throw new Error("Failed to store client key in storage", { cause: error });
+    }
+  }
+}
+async function getClientKey() {
+  if (globalClientKey && globalClientKey.trim() !== "") {
+    return globalClientKey;
+  }
+  const storage = getStorageAPI();
+  if (storage) {
+    try {
+      const result = await storage.local.get(EXTENSION_STORAGE_KEY);
+      const storedKey = result[EXTENSION_STORAGE_KEY];
+      if (storedKey) {
+        globalClientKey = storedKey;
+        return globalClientKey;
+      }
+    } catch (error) {
+      throw new Error("Failed to get client key from storage", { cause: error });
+    }
+  }
+  throw new Error("Client key not found");
+}
+function clearClientKey() {
+  globalClientKey = "";
+  return globalClientKey;
+}
+
+// src/utils/format.ts
+function removeHexPrefix(address) {
+  return address.startsWith("0x") ? address.slice(2) : address;
+}
+function addHexPrefix(address) {
+  return address.startsWith("0x") ? address : `0x${address}`;
+}
+function formatNumber(value, decimals = 2) {
+  const num = typeof value === "string" ? parseFloat(value) : value;
+  return num.toLocaleString(void 0, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  });
+}
+function truncateString(str, length = 4) {
+  if (str.length <= length * 2 + 3) return str;
+  return `${str.substring(0, length)}...${str.substring(str.length - length)}`;
+}
+function truncateAddress(address) {
+  return truncateString(removeHexPrefix(address), 4);
+}
+
+// src/utils/constants.ts
+var import_action_kit = require("@relayerfi/action-kit");
+var PROXY_URL = "https://proxy.relayer.fi";
+var API_REPOSITORY_URL = "https://api.relayer.fi/v1/directory/v1";
+
+// src/utils/proxify.ts
+var import_action_kit2 = require("@relayerfi/action-kit");
+async function proxify(url, isExtension = false) {
+  const clientKey = await getClientKey();
+  if (!clientKey) {
+    throw new Error("Client key not found", { cause: new Error("Client key not found") });
+  }
+  const proxyEndpoint = `${PROXY_URL}/proxy`;
+  const queryParams = new URLSearchParams();
+  queryParams.set("url", url);
+  const proxifiedUrl = `${proxyEndpoint}?${queryParams.toString()}`;
+  const headers = {
+    Accept: "application/json",
+    [import_action_kit.SDK_TO_PROXY_HEADERS.USER_AGENT]: import_action_kit.RELAYER_VALUES.USER_AGENT,
+    [import_action_kit.SDK_TO_PROXY_HEADERS.CONTENT_TYPE]: import_action_kit.RELAYER_VALUES.CONTENT_TYPE_JSON,
+    [import_action_kit.SDK_TO_PROXY_HEADERS.CLIENT_KEY]: clientKey
+  };
+  return { url: proxifiedUrl, headers };
+}
+async function getDynamicExecutor(key) {
+  if (!key) {
+    return await (0, import_action_kit2.createDynamicExecutor)();
+  } else {
+    return (0, import_action_kit2.createDynamicExecutor)(key);
+  }
+}
+async function execute(action, inputs, context, options) {
+  const clientKey = await getClientKey();
+  if (!clientKey) {
+    const executor = await getDynamicExecutor();
+    return await executor.execute(action, inputs, context, options);
+  } else {
+    const executor = await getDynamicExecutor(clientKey);
+    return await executor.execute(action, inputs, context, options);
+  }
+}
+async function getMetadata(url) {
+  const clientKey = await getClientKey();
+  const executor = clientKey ? new import_action_kit2.WidgetExecutor(clientKey) : new import_action_kit2.WidgetExecutor();
+  return await executor.getMetadata(url);
+}
+
+// src/errors/Errors.ts
+var RelayerError = class extends Error {
+  code;
+  httpStatus;
+  originalError;
+  context;
+  constructor({
+    message,
+    code = "UNKNOWN_ERROR",
+    httpStatus,
+    originalError,
+    context
+  }) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.originalError = originalError;
+    this.context = context;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Convert error to a plain object for logging or serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      httpStatus: this.httpStatus,
+      stack: this.stack,
+      context: this.context,
+      originalError: this.originalError ? {
+        message: this.originalError.message,
+        name: this.originalError.name,
+        stack: this.originalError.stack
+      } : void 0
+    };
+  }
+};
+var NetworkError = class _NetworkError extends RelayerError {
+  constructor({
+    message,
+    code = "NETWORK_ERROR",
+    httpStatus,
+    originalError,
+    context
+  }) {
+    super({ message, code, httpStatus, originalError, context });
+  }
+  static fromFetchError(url, error, httpStatus) {
+    return new _NetworkError({
+      message: `Network request failed for ${url}`,
+      code: "FETCH_ERROR",
+      httpStatus,
+      originalError: error,
+      context: { url }
+    });
+  }
+};
+var ValidationError = class _ValidationError extends RelayerError {
+  invalidFields;
+  constructor({
+    message,
+    code = "VALIDATION_ERROR",
+    invalidFields,
+    context
+  }) {
+    super({ message, code, context });
+    this.invalidFields = invalidFields;
+  }
+  static missingField(fieldName) {
+    return new _ValidationError({
+      message: `Missing required field: ${fieldName}`,
+      code: "MISSING_FIELD",
+      invalidFields: { [fieldName]: "Field is required" }
+    });
+  }
+  static invalidFormat(fieldName, reason) {
+    return new _ValidationError({
+      message: `Invalid format for ${fieldName}: ${reason}`,
+      code: "INVALID_FORMAT",
+      invalidFields: { [fieldName]: reason }
+    });
+  }
+};
+var SecurityError = class extends RelayerError {
+  constructor({
+    message,
+    code = "SECURITY_ERROR",
+    context
+  }) {
+    super({ message, code, context });
+  }
+};
+var BlockchainError = class _BlockchainError extends RelayerError {
+  constructor({
+    message,
+    code = "BLOCKCHAIN_ERROR",
+    originalError,
+    context
+  }) {
+    super({ message, code, originalError, context });
+  }
+  static transactionFailed(reason, context) {
+    return new _BlockchainError({
+      message: `Transaction failed: ${reason}`,
+      code: "TRANSACTION_FAILED",
+      context
+    });
+  }
+  static walletConnectionFailed(reason) {
+    return new _BlockchainError({
+      message: `Failed to connect to wallet: ${reason}`,
+      code: "WALLET_CONNECTION_ERROR"
+    });
+  }
+};
+var NotFoundError = class _NotFoundError extends RelayerError {
+  constructor({
+    message,
+    code = "NOT_FOUND",
+    httpStatus = 404,
+    context
+  }) {
+    super({ message, code, httpStatus, context });
+  }
+  static resourceNotFound(resourceType, identifier) {
+    return new _NotFoundError({
+      message: `${resourceType} not found: ${identifier}`,
+      context: { resourceType, identifier }
+    });
+  }
+};
+var InvalidOperationError = class _InvalidOperationError extends RelayerError {
+  constructor({
+    message,
+    code = "INVALID_OPERATION",
+    context
+  }) {
+    super({ message, code, context });
+  }
+  static actionNotPermitted(action, reason) {
+    return new _InvalidOperationError({
+      message: `Operation not permitted: ${action}. Reason: ${reason}`,
+      context: { action, reason }
+    });
+  }
+};
+var WidgetError = class _WidgetError extends RelayerError {
+  constructor({
+    message,
+    code = "WIDGET_ERROR",
+    httpStatus,
+    originalError,
+    context
+  }) {
+    super({ message, code, httpStatus, originalError, context });
+  }
+  static metadataFetchFailed(url, httpStatus) {
+    return new _WidgetError({
+      message: `Failed to fetch widget metadata from ${url}`,
+      code: "METADATA_FETCH_FAILED",
+      httpStatus,
+      context: { url }
+    });
+  }
+  static invalidUrl(url, reason) {
+    return new _WidgetError({
+      message: `Invalid widget URL: ${url}. Reason: ${reason}`,
+      code: "INVALID_URL",
+      context: { url, reason }
+    });
+  }
+  static invalidMetadata(reason, originalError) {
+    return new _WidgetError({
+      message: `Invalid widget metadata: ${reason}`,
+      code: "INVALID_METADATA",
+      originalError,
+      context: { reason }
+    });
+  }
+  static actionError(actionIndex, reason) {
+    return new _WidgetError({
+      message: `Failed to execute widget action at index ${actionIndex}: ${reason}`,
+      code: "ACTION_EXECUTION_ERROR",
+      context: { actionIndex, reason }
+    });
+  }
+  /**
+   * Error when fetching the widget directory fails.
+   * @param url The URL that was fetched.
+   * @param httpStatus The HTTP status code received.
+   * @param statusText Optional status text from the response.
+   */
+  static directoryFetchFailed(url, httpStatus, statusText) {
+    return new _WidgetError({
+      message: `Failed to fetch widget directory from ${url}. Status: ${httpStatus}${statusText ? ` (${statusText})` : ""}`,
+      code: "REGISTRY_FETCH_FAILED",
+      httpStatus,
+      context: { url }
+    });
+  }
+  /**
+   * Error when the fetched directory data has an invalid format.
+   * @param reason Description of why the format is invalid.
+   */
+  static invalidDirectoryFormat(reason) {
+    return new _WidgetError({
+      message: `Invalid widget directory format: ${reason}`,
+      code: "INVALID_REGISTRY_FORMAT",
+      context: { reason }
+    });
+  }
+  /**
+   * Generic error during the directory refresh process.
+   * @param reason Description of the error.
+   * @param originalError The original error caught, if any.
+   */
+  static directoryRefreshError(reason, originalError) {
+    return new _WidgetError({
+      message: `Error during widget directory refresh: ${reason}`,
+      code: "REGISTRY_REFRESH_ERROR",
+      originalError,
+      context: { reason }
+    });
+  }
+};
+var ErrorUtils = {
+  /**
+   * Safely wrap async operations with consistent error handling
+   */
+  async safeAsync(promise, errorMapper) {
+    try {
+      return await promise;
+    } catch (error) {
+      if (errorMapper) {
+        throw errorMapper(error);
+      }
+      if (error instanceof RelayerError) {
+        throw error;
+      }
+      throw new RelayerError({
+        message: error instanceof Error ? error.message : String(error),
+        originalError: error instanceof Error ? error : void 0
+      });
+    }
+  }
+};
+
+// src/directory/WidgetDirectory.ts
+var WidgetDirectory = class _WidgetDirectory {
+  static instance = null;
+  widgetsByHostAndPath = /* @__PURE__ */ new Map();
+  widgetsByHost = /* @__PURE__ */ new Map();
+  lastUpdated = /* @__PURE__ */ new Date(0);
+  isRefreshing = false;
+  isExtension = false;
+  defaultDirectoryUrl;
+  initializationPromise = null;
+  isInitialized = false;
+  refreshIntervalId = null;
+  // Para almacenar el ID del intervalo
+  constructor(config = {}) {
+    this.isExtension = typeof chrome !== "undefined" && chrome.runtime && !!chrome.runtime.id;
+    this.defaultDirectoryUrl = API_REPOSITORY_URL;
+  }
+  static getInstance(config = {}) {
+    if (!this.instance) {
+      this.instance = new _WidgetDirectory(config);
+    }
+    return this.instance;
+  }
+  async init(config = {}) {
+    if (this.isInitialized && !config.forceRefresh) {
+      return;
+    }
+    if (this.initializationPromise && !config.forceRefresh) {
+      return this.initializationPromise;
+    }
+    if (config.forceRefresh) {
+      this.isInitialized = false;
+    }
+    this.initializationPromise = (async () => {
+      try {
+        const urlToRefresh = this.defaultDirectoryUrl;
+        await this.refresh(urlToRefresh);
+        if (this.isExtension && config?.refreshInterval) {
+          if (this.refreshIntervalId) {
+            clearInterval(this.refreshIntervalId);
+          }
+          this.refreshIntervalId = setInterval(() => {
+            this.refresh(urlToRefresh).catch((error) => {
+            });
+          }, config.refreshInterval);
+        }
+        this.isInitialized = true;
+      } catch (error) {
+        this.isInitialized = false;
+        throw error;
+      } finally {
+        this.initializationPromise = null;
+      }
+    })();
+    return this.initializationPromise;
+  }
+  createKey(host, pathname) {
+    return `${host}${pathname}`;
+  }
+  normalizeHost(hostInput) {
+    let host = hostInput;
+    if (host.startsWith("http://") || host.startsWith("https://")) {
+      try {
+        const url = new URL(hostInput);
+        host = url.host;
+      } catch (e) {
+        const match = hostInput.match(/^https?:\/\/([^/?#]+)/i);
+        if (match && match[1]) {
+          host = match[1];
+        } else {
+          host = hostInput.split("/")[0] || hostInput;
+        }
+      }
+    }
+    if (host.startsWith("www.")) {
+      host = host.substring(4);
+    }
+    return host;
+  }
+  lookup(url) {
+    if (!this.isInitialized) {
+      return { state: "unknown" };
+    }
+    try {
+      const urlObj = typeof url === "string" ? new URL(url) : url;
+      const host = this.normalizeHost(urlObj.host);
+      const pathname = urlObj.pathname;
+      const exactKey = this.createKey(host, pathname);
+      const exactMatch = this.widgetsByHostAndPath.get(exactKey);
+      if (exactMatch) {
+        return { state: exactMatch.state, id: exactMatch.id };
+      }
+      const hostApps = this.widgetsByHost.get(host);
+      if (hostApps && hostApps.length > 0) {
+        for (const app of hostApps) {
+          const appPath = app.path || "/";
+          if (pathname.startsWith(appPath)) {
+            return { state: app.state, id: app.id };
+          }
+        }
+        const maliciousApp = hostApps.find((app) => app.state === "malicious");
+        if (maliciousApp) {
+          return { state: "malicious", id: maliciousApp.id };
+        }
+        const rootPathApp = hostApps.find((app) => (app.path || "/") === "/");
+        if (rootPathApp) {
+          return { state: rootPathApp.state, id: rootPathApp.id };
+        }
+        return { state: "unknown" };
+      }
+      return { state: "unknown" };
+    } catch (error) {
+      return { state: "unknown" };
+    }
+  }
+  async refresh(directoryUrl) {
+    if (this.isRefreshing) {
+      return;
+    }
+    const urlToFetch = directoryUrl || this.defaultDirectoryUrl;
+    this.isRefreshing = true;
+    try {
+      const response = await fetch(urlToFetch, {
+        headers: { "Cache-Control": "no-cache, no-store", Pragma: "no-cache" }
+      });
+      if (!response.ok) {
+        throw WidgetError.directoryFetchFailed(
+          urlToFetch,
+          response.status,
+          response.statusText
+        );
+      }
+      const data = await response.json();
+      if (!data || typeof data !== "object" || !Array.isArray(data.mini_apps)) {
+        throw WidgetError.invalidDirectoryFormat("Missing expected fields (mini_apps)");
+      }
+      const newWidgetsByHostAndPath = /* @__PURE__ */ new Map();
+      const newWidgetsByHost = /* @__PURE__ */ new Map();
+      for (const app of data.mini_apps) {
+        if (app && typeof app === "object" && app.host && app.state) {
+          const originalAppHost = app.host;
+          const normalizedHost = this.normalizeHost(app.host);
+          const path = app.path || "/";
+          const normalizedApp = { ...app, host: normalizedHost, path };
+          const key = this.createKey(normalizedHost, path);
+          newWidgetsByHostAndPath.set(key, normalizedApp);
+          if (!newWidgetsByHost.has(normalizedHost)) {
+            newWidgetsByHost.set(normalizedHost, []);
+          }
+          newWidgetsByHost.get(normalizedHost).push(normalizedApp);
+        } else {
+          console.warn(
+            "[widget-kit] Skipping invalid WidgetEntry during refresh:",
+            app
+          );
+        }
+      }
+      for (const [host, apps] of newWidgetsByHost) {
+        apps.sort((a, b) => b.path.length - a.path.length);
+        newWidgetsByHost.set(host, apps);
+      }
+      this.widgetsByHostAndPath = newWidgetsByHostAndPath;
+      this.widgetsByHost = newWidgetsByHost;
+      this.lastUpdated = new Date(data.lastUpdated);
+    } catch (error) {
+      if (error instanceof WidgetError) throw error;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw WidgetError.directoryRefreshError(
+        errorMessage,
+        error instanceof Error ? error : void 0
+      );
+    } finally {
+      this.isRefreshing = false;
+    }
+  }
+  getLastUpdated() {
+    return this.lastUpdated;
+  }
+  getCurrentDirectory() {
+    return this.widgetsByHostAndPath;
+  }
+  debug() {
+    console.log("=== Directory Debug ===");
+    console.log(`Is Initialized: ${this.isInitialized}`);
+    console.log(`Last Updated: ${this.lastUpdated.toISOString()}`);
+    console.log("By Host + Path:");
+    for (const [key, app] of this.widgetsByHostAndPath) {
+      console.log(`  ${key} -> State: ${app.state}, Path in App: ${app.path}`);
+    }
+    console.log("By Host (Sorted by path specificity):");
+    for (const [host, apps] of this.widgetsByHost) {
+      console.log(`  ${host}:`);
+      apps.forEach((app) => console.log(`    Path: ${app.path} -> State: ${app.state}`));
+    }
+    console.log("=======================");
+  }
+};
+
+// src/index.ts
+var VERSION = "0.1.2";
+//# sourceMappingURL=index.cjs.map