@fastnear/wallet-adapter 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# @fastnear/wallet-adapter
+
+A lightweight, dependency-free client interface for integrating NEAR wallets into your dApp.
+
+## Features
+
+- 🚀 Zero dependencies
+- 📱 Works with all major NEAR wallets
+- 💪 Full TypeScript support
+- 🔒 Secure iframe-based design
+- 📦 ESM and CommonJS support
+- 🎯 Simple, promise-based API
+
+## Installation
+
+```bash
+npm install @fastnear/wallet-adapter
+```
+
+## Basic Usage
+
+```javascript
+import { WalletAdapter } from '@fastnear/wallet-adapter';
+
+// Create adapter instance
+const adapter = new WalletAdapter();
+
+// Sign in
+const result = await adapter.signIn({
+  networkId: 'mainnet',
+  contractId: 'example.near',
+  wallet: 'near' // optional, defaults to user choice
+});
+
+if (result.url) {
+  // Redirect to wallet
+  window.location.href = result.url;
+} else if (result.accountId) {
+  console.log('Signed in as:', result.accountId);
+} else if (result.error) {
+  console.error('Failed to sign in:', result.error);
+}
+
+// Send transaction
+const txResult = await adapter.sendTransaction({
+  receiverId: 'example.near',
+  actions: [{
+    type: 'FunctionCall',
+    params: {
+      methodName: 'example_method',
+      args: { /* ... */ },
+      gas: '30000000000000',
+      deposit: '0'
+    }
+  }]
+});
+
+if (txResult.url) {
+  window.location.href = txResult.url;
+} else if (txResult.hash) {
+  console.log('Transaction hash:', txResult.hash);
+}
+
+// Clean up when done
+adapter.destroy();
+```
+
+## Advanced Configuration
+
+```javascript
+const adapter = new WalletAdapter({
+  // Custom widget URL (defaults to official hosted version)
+  widgetUrl: 'https://your-domain.com/wallet-widget/',
+  
+  // Restrict message origin for security (defaults to '*')
+  targetOrigin: 'https://your-domain.com',
+  
+  // Handle wallet state updates
+  onStateUpdate: (state) => {
+    localStorage.setItem('wallet-state', JSON.stringify(state));
+  }
+});
+```
+
+## API Reference
+
+### `new WalletAdapter(config?)`
+
+Creates a new wallet adapter instance.
+
+#### Config Options
+- `widgetUrl?: string` - URL of the wallet widget (defaults to official hosted version)
+- `targetOrigin?: string` - Target origin for postMessage (defaults to '*')
+- `onStateUpdate?: (state: WalletState) => void` - Called when wallet state changes
+
+### `signIn(config)`
+
+Signs in with a NEAR wallet.
+
+#### Config
+```typescript
+{
+  networkId: 'mainnet' | 'testnet',
+  contractId: string,
+  wallet?: 'near' | 'here' | 'meteor'
+}
+```
+
+#### Returns
+```typescript
+Promise<{
+  url?: string,        // URL to redirect to if needed
+  accountId?: string,  // Account ID if immediately available
+  error?: string       // Error message if sign in failed
+}>
+```
+
+### `sendTransaction(config)`
+
+Sends a transaction using the connected wallet.
+
+#### Config
+```typescript
+{
+  receiverId: string,
+  actions: Array<{
+    type: string,
+    params: {
+      methodName?: string,
+      args?: Object,
+      gas?: string,
+      deposit?: string
+    }
+  }>,
+  wallet?: 'near' | 'here' | 'meteor'
+}
+```
+
+#### Returns
+```typescript
+Promise<{
+  url?: string,    // URL to redirect to if needed
+  hash?: string,   // Transaction hash if immediately available
+  error?: string   // Error message if transaction failed
+}>
+```
+
+### `getState()`
+
+Gets current wallet state.
+
+#### Returns
+```typescript
+{
+  accountId?: string,    // NEAR account ID if signed in
+  publicKey?: string,    // Public key if available
+  privateKey?: string,   // Private key if available
+  lastWalletId?: string  // ID of last used wallet
+}
+```
+
+### `destroy()`
+
+Cleans up adapter resources. Should be called when adapter is no longer needed.
+
+## Supported Wallets
+
+- NEAR Wallet (MyNearWallet)
+- HERE Wallet
+- Meteor Wallet
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,167 @@
+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.js
+var src_exports = {};
+__export(src_exports, {
+  WalletAdapter: () => WalletAdapter
+});
+module.exports = __toCommonJS(src_exports);
+var WalletAdapter = class _WalletAdapter {
+  /** @type {HTMLIFrameElement} */
+  #iframe = null;
+  /** @type {string} */
+  #targetOrigin;
+  /** @type {string} */
+  #widgetUrl;
+  /** @type {Map<string, Function>} */
+  #pending = /* @__PURE__ */ new Map();
+  /** @type {WalletState} */
+  #state = {};
+  /** @type {Function} */
+  #onStateUpdate;
+  /** @type {string} */
+  #callbackUrl;
+  /** @type {string} */
+  static defaultWidgetUrl = "https://wallet-adapter.fastnear.com";
+  /**
+   * @param {WalletAdapterConfig} [config]
+   */
+  constructor({
+    widgetUrl = _WalletAdapter.defaultWidgetUrl,
+    targetOrigin = "*",
+    onStateUpdate,
+    callbackUrl = window.location.href
+  } = {}) {
+    this.#targetOrigin = targetOrigin;
+    this.#widgetUrl = widgetUrl;
+    this.#onStateUpdate = onStateUpdate;
+    this.#callbackUrl = callbackUrl;
+    window.addEventListener("message", this.#handleMessage.bind(this));
+  }
+  /**
+   * Creates an iframe for wallet interaction
+   * @param {string} path - Path to load in iframe
+   * @returns {HTMLIFrameElement}
+   */
+  #createIframe(path) {
+    if (this.#iframe) {
+      this.#iframe.remove();
+    }
+    const url = new URL(path, this.#widgetUrl);
+    const iframe = document.createElement("iframe");
+    iframe.src = url.toString();
+    iframe.allow = "usb";
+    iframe.style.border = "none";
+    iframe.style.zIndex = "10000";
+    iframe.style.position = "fixed";
+    iframe.style.display = "block";
+    iframe.style.top = "0";
+    iframe.style.left = "0";
+    iframe.style.width = "100%";
+    iframe.style.height = "100%";
+    document.body.appendChild(iframe);
+    this.#iframe = iframe;
+    return iframe;
+  }
+  /**
+   * Handles messages from the wallet widget
+   * @param {MessageEvent} event
+   */
+  #handleMessage(event) {
+    if (this.#targetOrigin !== "*" && event.origin !== this.#targetOrigin) {
+      return;
+    }
+    const { id, type, action, payload } = event.data;
+    if (type !== "wallet-adapter")
+      return;
+    if (action === "close") {
+      this.#iframe?.remove();
+      this.#iframe = null;
+      return;
+    }
+    if (payload?.state) {
+      this.#state = { ...this.#state, ...payload.state };
+      this.#onStateUpdate?.(this.#state);
+    }
+    const resolve = this.#pending.get(id);
+    if (resolve) {
+      this.#pending.delete(id);
+      this.#iframe?.remove();
+      this.#iframe = null;
+      resolve(payload);
+    }
+  }
+  /**
+   * Sends a message to the wallet widget
+   * @param {string} path - Path to load in iframe
+   * @param {string} method - Method to call
+   * @param {Object} params - Parameters to pass
+   * @returns {Promise<any>}
+   */
+  async #sendMessage(path, method, params) {
+    return new Promise((resolve) => {
+      const id = Math.random().toString(36).slice(2);
+      this.#pending.set(id, resolve);
+      const iframe = this.#createIframe(path);
+      iframe.onload = () => {
+        iframe.contentWindow?.postMessage({
+          type: "wallet-adapter",
+          method,
+          params: {
+            id,
+            ...params,
+            state: this.#state,
+            callbackUrl: params.callbackUrl || this.#callbackUrl
+          }
+        }, this.#targetOrigin);
+      };
+    });
+  }
+  /**
+   * Get current wallet state
+   * @returns {WalletState}
+   */
+  getState() {
+    return { ...this.#state };
+  }
+  /**
+   * Sign in with a NEAR wallet
+   * @param {SignInConfig} config
+   * @returns {Promise<SignInResult>}
+   */
+  async signIn(config) {
+    return this.#sendMessage("/login.html", "signIn", config);
+  }
+  /**
+   * Send a transaction using connected wallet
+   * @param {TransactionConfig} config
+   * @returns {Promise<TransactionResult>}
+   */
+  async sendTransaction(config) {
+    return this.#sendMessage("/sign.html", "sendTransaction", config);
+  }
+  /**
+   * Clean up adapter resources
+   */
+  destroy() {
+    window.removeEventListener("message", this.#handleMessage);
+    this.#iframe?.remove();
+    this.#iframe = null;
+  }
+};

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @typedef {Object} WalletState
+ * @property {string} [accountId] - NEAR account ID if signed in
+ * @property {string} [publicKey] - Public key if available
+ * @property {string} [privateKey] - Private key if available
+ * @property {string} [lastWalletId] - ID of last used wallet
+ */
+/**
+ * @typedef {Object} WalletAction
+ * @property {string} type - Action type
+ * @property {Object} [args] - Action arguments
+ * @property {string|number} [gas] - Gas to attach
+ * @property {string|number} [deposit] - Deposit to attach
+ */
+/**
+ * @typedef {Object} SignInConfig
+ * @property {string} networkId - NEAR network ID ('mainnet' or 'testnet')
+ * @property {string} contractId - Contract ID to request access for
+ * @property {'near'|'here'|'meteor'} [wallet] - Preferred wallet to use
+ * @property {string} [callbackUrl] - URL to redirect back to after wallet interaction
+ */
+/**
+ * @typedef {Object} SignInResult
+ * @property {string} [url] - URL to redirect to if needed
+ * @property {string} [accountId] - Account ID if immediately available
+ * @property {string} [error] - Error message if sign in failed
+ */
+/**
+ * @typedef {Object} TransactionConfig
+ * @property {string} receiverId - Transaction receiver account ID
+ * @property {WalletAction[]} actions - Transaction actions to perform
+ * @property {'near'|'here'|'meteor'} [wallet] - Preferred wallet to use
+ * @property {string} [callbackUrl] - URL to redirect back to after wallet interaction
+ */
+/**
+ * @typedef {Object} TransactionResult
+ * @property {string} [url] - URL to redirect to if needed
+ * @property {string} [hash] - Transaction hash if immediately available
+ * @property {string} [error] - Error message if transaction failed
+ */
+/**
+ * @typedef {Object} WalletAdapterConfig
+ * @property {string} [widgetUrl] - URL of the wallet widget (defaults to official hosted version)
+ * @property {string} [targetOrigin] - Target origin for postMessage (defaults to '*')
+ * @property {(state: WalletState) => void} [onStateUpdate] - Called when wallet state changes
+ * @property {string} [callbackUrl] - Default callback URL for wallet interactions (defaults to current page URL)
+ */
+/**
+ * Interface for interacting with NEAR wallets
+ */
+export class WalletAdapter {
+    /** @type {string} */
+    static defaultWidgetUrl: string;
+    /**
+     * @param {WalletAdapterConfig} [config]
+     */
+    constructor({ widgetUrl, targetOrigin, onStateUpdate, callbackUrl }?: WalletAdapterConfig);
+    /**
+     * Get current wallet state
+     * @returns {WalletState}
+     */
+    getState(): WalletState;
+    /**
+     * Sign in with a NEAR wallet
+     * @param {SignInConfig} config
+     * @returns {Promise<SignInResult>}
+     */
+    signIn(config: SignInConfig): Promise<SignInResult>;
+    /**
+     * Send a transaction using connected wallet
+     * @param {TransactionConfig} config
+     * @returns {Promise<TransactionResult>}
+     */
+    sendTransaction(config: TransactionConfig): Promise<TransactionResult>;
+    /**
+     * Clean up adapter resources
+     */
+    destroy(): void;
+    #private;
+}
+export type WalletState = {
+    /**
+     * - NEAR account ID if signed in
+     */
+    accountId?: string;
+    /**
+     * - Public key if available
+     */
+    publicKey?: string;
+    /**
+     * - Private key if available
+     */
+    privateKey?: string;
+    /**
+     * - ID of last used wallet
+     */
+    lastWalletId?: string;
+};
+export type WalletAction = {
+    /**
+     * - Action type
+     */
+    type: string;
+    /**
+     * - Action arguments
+     */
+    args?: any;
+    /**
+     * - Gas to attach
+     */
+    gas?: string | number;
+    /**
+     * - Deposit to attach
+     */
+    deposit?: string | number;
+};
+export type SignInConfig = {
+    /**
+     * - NEAR network ID ('mainnet' or 'testnet')
+     */
+    networkId: string;
+    /**
+     * - Contract ID to request access for
+     */
+    contractId: string;
+    /**
+     * - Preferred wallet to use
+     */
+    wallet?: "near" | "here" | "meteor";
+    /**
+     * - URL to redirect back to after wallet interaction
+     */
+    callbackUrl?: string;
+};
+export type SignInResult = {
+    /**
+     * - URL to redirect to if needed
+     */
+    url?: string;
+    /**
+     * - Account ID if immediately available
+     */
+    accountId?: string;
+    /**
+     * - Error message if sign in failed
+     */
+    error?: string;
+};
+export type TransactionConfig = {
+    /**
+     * - Transaction receiver account ID
+     */
+    receiverId: string;
+    /**
+     * - Transaction actions to perform
+     */
+    actions: WalletAction[];
+    /**
+     * - Preferred wallet to use
+     */
+    wallet?: "near" | "here" | "meteor";
+    /**
+     * - URL to redirect back to after wallet interaction
+     */
+    callbackUrl?: string;
+};
+export type TransactionResult = {
+    /**
+     * - URL to redirect to if needed
+     */
+    url?: string;
+    /**
+     * - Transaction hash if immediately available
+     */
+    hash?: string;
+    /**
+     * - Error message if transaction failed
+     */
+    error?: string;
+};
+export type WalletAdapterConfig = {
+    /**
+     * - URL of the wallet widget (defaults to official hosted version)
+     */
+    widgetUrl?: string;
+    /**
+     * - Target origin for postMessage (defaults to '*')
+     */
+    targetOrigin?: string;
+    /**
+     * - Called when wallet state changes
+     */
+    onStateUpdate?: (state: WalletState) => void;
+    /**
+     * - Default callback URL for wallet interactions (defaults to current page URL)
+     */
+    callbackUrl?: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AAEH;;;;;;GAMG;AAEH;;;;;GAKG;AAEH;;;;;;GAMG;AAEH;;;;;GAKG;AAEH;;;;;;GAMG;AAEH;;GAEG;AACH;IAsBI,qBAAqB;IACrB,yBADW,MAAM,CAC+C;IAEhE;;OAEG;IACH,sEAFW,mBAAmB,EAa7B;IAmGD;;;OAGG;IACH,YAFa,WAAW,CAIvB;IAED;;;;OAIG;IACH,eAHW,YAAY,GACV,OAAO,CAAC,YAAY,CAAC,CAIjC;IAED;;;;OAIG;IACH,wBAHW,iBAAiB,GACf,OAAO,CAAC,iBAAiB,CAAC,CAItC;IAED;;OAEG;IACH,gBAIC;;CACF;;;;;gBAnOW,MAAM;;;;gBACN,MAAM;;;;iBACN,MAAM;;;;mBACN,MAAM;;;;;;UAKN,MAAM;;;;;;;;UAEN,MAAM,GAAC,MAAM;;;;cACb,MAAM,GAAC,MAAM;;;;;;eAKb,MAAM;;;;gBACN,MAAM;;;;aACN,MAAM,GAAC,MAAM,GAAC,QAAQ;;;;kBACtB,MAAM;;;;;;UAKN,MAAM;;;;gBACN,MAAM;;;;YACN,MAAM;;;;;;gBAKN,MAAM;;;;aACN,YAAY,EAAE;;;;aACd,MAAM,GAAC,MAAM,GAAC,QAAQ;;;;kBACtB,MAAM;;;;;;UAKN,MAAM;;;;WACN,MAAM;;;;YACN,MAAM;;;;;;gBAKN,MAAM;;;;mBACN,MAAM;;;;oBACN,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI;;;;kBAC5B,MAAM"}

package/dist/index.js

@@ -0,0 +1,147 @@
+// src/index.js
+var WalletAdapter = class _WalletAdapter {
+  /** @type {HTMLIFrameElement} */
+  #iframe = null;
+  /** @type {string} */
+  #targetOrigin;
+  /** @type {string} */
+  #widgetUrl;
+  /** @type {Map<string, Function>} */
+  #pending = /* @__PURE__ */ new Map();
+  /** @type {WalletState} */
+  #state = {};
+  /** @type {Function} */
+  #onStateUpdate;
+  /** @type {string} */
+  #callbackUrl;
+  /** @type {string} */
+  static defaultWidgetUrl = "https://wallet-adapter.fastnear.com";
+  /**
+   * @param {WalletAdapterConfig} [config]
+   */
+  constructor({
+    widgetUrl = _WalletAdapter.defaultWidgetUrl,
+    targetOrigin = "*",
+    onStateUpdate,
+    callbackUrl = window.location.href
+  } = {}) {
+    this.#targetOrigin = targetOrigin;
+    this.#widgetUrl = widgetUrl;
+    this.#onStateUpdate = onStateUpdate;
+    this.#callbackUrl = callbackUrl;
+    window.addEventListener("message", this.#handleMessage.bind(this));
+  }
+  /**
+   * Creates an iframe for wallet interaction
+   * @param {string} path - Path to load in iframe
+   * @returns {HTMLIFrameElement}
+   */
+  #createIframe(path) {
+    if (this.#iframe) {
+      this.#iframe.remove();
+    }
+    const url = new URL(path, this.#widgetUrl);
+    const iframe = document.createElement("iframe");
+    iframe.src = url.toString();
+    iframe.allow = "usb";
+    iframe.style.border = "none";
+    iframe.style.zIndex = "10000";
+    iframe.style.position = "fixed";
+    iframe.style.display = "block";
+    iframe.style.top = "0";
+    iframe.style.left = "0";
+    iframe.style.width = "100%";
+    iframe.style.height = "100%";
+    document.body.appendChild(iframe);
+    this.#iframe = iframe;
+    return iframe;
+  }
+  /**
+   * Handles messages from the wallet widget
+   * @param {MessageEvent} event
+   */
+  #handleMessage(event) {
+    if (this.#targetOrigin !== "*" && event.origin !== this.#targetOrigin) {
+      return;
+    }
+    const { id, type, action, payload } = event.data;
+    if (type !== "wallet-adapter")
+      return;
+    if (action === "close") {
+      this.#iframe?.remove();
+      this.#iframe = null;
+      return;
+    }
+    if (payload?.state) {
+      this.#state = { ...this.#state, ...payload.state };
+      this.#onStateUpdate?.(this.#state);
+    }
+    const resolve = this.#pending.get(id);
+    if (resolve) {
+      this.#pending.delete(id);
+      this.#iframe?.remove();
+      this.#iframe = null;
+      resolve(payload);
+    }
+  }
+  /**
+   * Sends a message to the wallet widget
+   * @param {string} path - Path to load in iframe
+   * @param {string} method - Method to call
+   * @param {Object} params - Parameters to pass
+   * @returns {Promise<any>}
+   */
+  async #sendMessage(path, method, params) {
+    return new Promise((resolve) => {
+      const id = Math.random().toString(36).slice(2);
+      this.#pending.set(id, resolve);
+      const iframe = this.#createIframe(path);
+      iframe.onload = () => {
+        iframe.contentWindow?.postMessage({
+          type: "wallet-adapter",
+          method,
+          params: {
+            id,
+            ...params,
+            state: this.#state,
+            callbackUrl: params.callbackUrl || this.#callbackUrl
+          }
+        }, this.#targetOrigin);
+      };
+    });
+  }
+  /**
+   * Get current wallet state
+   * @returns {WalletState}
+   */
+  getState() {
+    return { ...this.#state };
+  }
+  /**
+   * Sign in with a NEAR wallet
+   * @param {SignInConfig} config
+   * @returns {Promise<SignInResult>}
+   */
+  async signIn(config) {
+    return this.#sendMessage("/login.html", "signIn", config);
+  }
+  /**
+   * Send a transaction using connected wallet
+   * @param {TransactionConfig} config
+   * @returns {Promise<TransactionResult>}
+   */
+  async sendTransaction(config) {
+    return this.#sendMessage("/sign.html", "sendTransaction", config);
+  }
+  /**
+   * Clean up adapter resources
+   */
+  destroy() {
+    window.removeEventListener("message", this.#handleMessage);
+    this.#iframe?.remove();
+    this.#iframe = null;
+  }
+};
+export {
+  WalletAdapter
+};

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@fastnear/wallet-adapter",
+  "version": "0.1.0",
+  "description": "Client interface for NEAR wallet adapter",
+  "repository": "https://github.com/fastnear/wallet-adapter.git",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "node build.js && npm run types",
+    "types": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "esbuild": "^0.19.0",
+    "typescript": "^5.0.0"
+  }
+}