Feature #58: Promisified API

.gitignore

@@ -1,3 +1,4 @@
 /node_modules
 /dist
-.DS_Store
+.DS_Store
+.idea

README.md

@@ -28,57 +28,41 @@ npm build
 
 ## Documentation
 
-Apps built with this Sdk are meant to be run in an iframe inside the Safe Web UI.
-This library exposes a single method called `initSdk` that receives a single optional parameter, an array of regular expressions. By default it's configured to accept messages from this URLs:
+Apps built with the Safe Apps SDK are meant to be run in an iframe inside the Safe Web UI.
+This library exposes a class as a default export. It accepts an optional options object:  
+`whitelistedDomains` - Array of regular expressions for origins you want to accept messages from. If not passed, accepts
+messages from any origin (default).
 
-- mainnet: https://gnosis-safe.io,
-- mainnet-staging: https://safe-team.staging.gnosisdev.com,
-- rinkeby: https://rinkeby.gnosis-safe.io,
-- rinkeby-staging: https://safe-team-rinkeby.staging.gnosisdev.com,
-- rinkeby-dev: https://safe-team.dev.gnosisdev.com
-- localhost (for the desktop app)
-
-By passing the argument to `initSdk` you can add more URLs to the list. It's useful when you are running your own instance of Safe Multisig.
 
 ```js
-import initSdk from '@gnosis.pm/safe-apps-sdk';
+import SafeAppsSDK from '@gnosis.pm/safe-apps-sdk';
 
-const appsSdk = initSdk();
-```
+const opts = {
+  whitelistedDomains: [/gnosis-safe\\.io/]
+}
 
-It returns a SDK instance that allows you to interact with the Safe Multisig application.
+const appsSdk = new SafeAppsSDK(opts);
+```
 
-### Subscribing to events
+The instance allows you to interact with the Safe Multisig application.
 
-Once you get the SDK instance, you will be able to subscribe to events from the Safe Multisig.
 
-The SDK instance exposes a method called `addListeners` that receives an object with known keys, over these keys you will be able to subscribe to different events.
+### Getting Safe information
 
-- `onSafeInfo`: It will provide you first level information like the safeAddress, network, etc.
-- `onTransactionConfirmation`: Fired when the user confirms the transaction inside his wallet. The response will include `requestId` and `safeTxHash` of the transaction.
+Safe information can be obtained by calling `.getSafeInfo()`
 
 ```js
-import { SafeInfo } from '@gnosis.pm/safe-apps-sdk';
-
-const onSafeInfo = (safeInfo: SafeInfo): void => {
-  console.log(safeInfo);
-};
-
-const onTransactionConfirmation = ({ requestId, safeTxHash }) => {
-  console.log(requestId, safeTxHash);
-};
-
-appsSdk.addListeners({
-  onSafeInfo,
-  onTransactionConfirmation,
-});
+const safe = await appsSdk.getSafeInfo()
+// {
+//   "safeAddress": "0x2fC97b3c7324EFc0BeC094bf75d5dCdFEb082C53",
+//   "ethBalance": "0",
+//   "network": "RINKEBY"
+// }
 ```
 
-You can remove listeners by calling `appsSdk.removeListeners()`.
-
 ### Sending TXs
 
-Sending a TX through the Safe Multisig is as simple as invoking `sendTransactionsWithParams` method with an array of TXs.
+Sending a TX through the Safe Multisig is as simple as invoking `.txs.send()`
 
 ```js
 // Create a web3 instance
@@ -102,24 +86,33 @@ const params = {
   safeTxGas: 500000,
 };
 
-// Send to Safe-multisig
-const message = appsSdk.sendTransactionsWithParams(txs, params);
-console.log(message.requestId);
+try {
+  const txs = await appsSdk.txs.send({ txs, params });
+  // { safeTxHash: '0x...' }
+} catch (err) {
+  console.error(err.message)
+}
 ```
 
-`sendTransactionsWithParams` returns a message containing the requestId. You can use it to map transaction calls with `onTransactionConfirmation` events.
-
 > Note: `value` accepts a number or a string as a decimal or hex number.
 
 ### Retrieving transaction's status
 
-Once you received safe transaction hash from `onTransactionConfirmation` event listener, you might want to get the status of the transaction (was it executed? how many confirmations does it have?):
+Once you received safe transaction hash, you might want to get the status of the transaction (was it executed? how many confirmations does it have?):
 
 ```js
-const tx = sdk.txs.getBySafeTxHash(safeTxHash);
+const tx = await sdk.txs.getBySafeTxHash(safeTxHash);
 ```
 
-It will return the following structure https://github.com/gnosis/safe-apps-sdk/blob/development/src/types.ts#L157 or throw an error if the backend hasn't synced the transaction yet
+It will return the following structure https://github.com/gnosis/safe-apps-sdk/blob/development/src/types.ts#L182 or throw an error if the backend hasn't synced the transaction yet
+
+## RPC Calls
+
+### getBalance
+
+```
+const balance = await safe.eth.getBalance({ params: ['0x...'] })
+```
 
 ## Testing in the Safe Multisig application
 
@@ -165,7 +158,7 @@ For this we recommend to use [react-app-rewired](https://www.npmjs.com/package/r
 },
 ```
 
-Additionally you need to create the `config-overrides.js` file in the root of the project to confirgure the **CORS** headers. The content of the file should be:
+Additionally, you need to create the `config-overrides.js` file in the root of the project to confirgure the **CORS** headers. The content of the file should be:
 
 ```js
 /* config-overrides.js */

package.json

@@ -1,9 +1,9 @@
 {
   "name": "@gnosis.pm/safe-apps-sdk",
-  "version": "0.4.2",
+  "version": "1.0.0",
   "description": "SDK developed to integrate third-party apps with Safe-Multisig app.",
-  "main": "dist/index.js",
-  "typings": "dist/index.d.ts",
+  "main": "dist/src/index.js",
+  "typings": "dist/src/index.d.ts",
   "files": [
     "dist/**/*",
     "README.md"
@@ -23,22 +23,24 @@
   "author": "Gnosis (https://gnosis.pm)",
   "license": "MIT",
   "dependencies": {
+    "semver": "^7.3.2",
     "web3-core": "^1.3.0"
   },
   "devDependencies": {
     "@types/jest": "^26.0.15",
-    "@types/node": "^14.14.6",
-    "@typescript-eslint/eslint-plugin": "^4.6.0",
-    "@typescript-eslint/parser": "^4.6.0",
-    "eslint": "^7.12.1",
+    "@types/node": "^14.14.8",
+    "@types/semver": "^7.3.4",
+    "@typescript-eslint/eslint-plugin": "^4.8.1",
+    "@typescript-eslint/parser": "^4.8.1",
+    "eslint": "^7.13.0",
     "eslint-config-prettier": "^6.15.0",
     "eslint-plugin-prettier": "^3.1.4",
     "husky": "^4.3.0",
-    "jest": "^26.6.1",
-    "lint-staged": "^10.5.0",
+    "jest": "^26.6.3",
+    "lint-staged": "^10.5.1",
     "prettier": "^2.1.2",
     "rimraf": "^3.0.2",
-    "ts-jest": "^26.4.3",
+    "ts-jest": "^26.4.4",
     "tslint": "^6.1.3",
     "tslint-config-prettier": "^1.18.0",
     "typescript": "^4.0.5"

src/communication/index.ts

@@ -1,108 +1,69 @@
-import {
-  InterfaceMessageIds,
-  InterfaceMessageEvent,
-  SentSDKMessage,
-  SDKMessageIds,
-  SDKMessageToPayload,
-  RequestId,
-  InterfaceMessageToPayload,
-  Communicator,
-} from '../types';
-import { INTERFACE_MESSAGES } from './messageIds';
+import semver from 'semver';
+import { InterfaceMessageEvent, Communicator, Methods, Response } from '../types';
+import { MessageFormatter } from './messageFormatter';
 
-class InterfaceCommunicator implements Communicator {
-  private allowedOrigins: RegExp[] = [];
+// eslint-disable-next-line
+type Callback = (response: any) => void;
 
-  constructor(allowedOrigins: RegExp[]) {
+class PostMessageCommunicator implements Communicator {
+  private readonly allowedOrigins: RegExp[] | null = null;
+  private callbacks = new Map<string, Callback>();
+
+  constructor(allowedOrigins: RegExp[] | null = null) {
     this.allowedOrigins = allowedOrigins;
 
     window.addEventListener('message', this.onParentMessage);
   }
 
-  private isValidMessage({ origin, data }: InterfaceMessageEvent): boolean {
-    const emptyOrMalformed = !data || !data.messageId;
-    const unknownOrigin = this.allowedOrigins?.find((regExp) => regExp.test(origin)) === undefined;
-    const sameOrigin = origin === window.origin;
+  private isValidMessage = ({ origin, data, source }: InterfaceMessageEvent): boolean => {
+    const emptyOrMalformed = !data;
+    const sentFromParentEl = source === window.parent;
+    const allowedSDKVersion = typeof data.version !== 'undefined' ? semver.gte(data.version, '1.0.0') : false;
+    let validOrigin = true;
+    if (Array.isArray(this.allowedOrigins)) {
+      validOrigin = this.allowedOrigins.find((regExp) => regExp.test(origin)) === undefined;
+    }
 
-    return !emptyOrMalformed && !unknownOrigin && !sameOrigin;
-  }
+    return !emptyOrMalformed && sentFromParentEl && allowedSDKVersion && validOrigin;
+  };
 
-  private logIncomingMessage(origin: string, payload: InterfaceMessageToPayload[InterfaceMessageIds]): void {
-    console.info(`SafeConnector: A message was received from origin ${origin}. `, payload);
-  }
-
-  private onParentMessage(msg: InterfaceMessageEvent): void {
-    this.logIncomingMessage(msg.origin, msg.data);
+  private logIncomingMessage = (msg: InterfaceMessageEvent): void => {
+    console.info(`Safe Apps SDK v1: A message was received from origin ${msg.origin}. `, msg.data);
+  };
 
+  private onParentMessage = (msg: InterfaceMessageEvent): void => {
     if (this.isValidMessage(msg)) {
-      this.handleIncomingMessage(msg.data.messageId, msg.data.data, msg.data.requestId);
+      this.logIncomingMessage(msg);
+      this.handleIncomingMessage(msg.data);
     }
-  }
-
-  private handleIncomingMessage(
-    messageId: InterfaceMessageIds,
-    payload: InterfaceMessageToPayload[InterfaceMessageIds],
-    requestId: RequestId,
-  ): void {
-    console.log(payload, requestId);
-    switch (messageId) {
-      case INTERFACE_MESSAGES.ENV_INFO:
-        // const typedPayload = payload as InterfaceMessageToPayload[typeof INTERFACE_MESSAGES.ENV_INFO];
+  };
 
-        break;
+  private handleIncomingMessage = (payload: InterfaceMessageEvent['data']): void => {
+    const { id } = payload;
 
-      case INTERFACE_MESSAGES.ON_SAFE_INFO: {
-        /* tslint:disable-next-line:no-shadowed-variable */
-        // const typedPayload = payload as InterfaceMessageToPayload[typeof INTERFACE_MESSAGES.ON_SAFE_INFO];
+    const cb = this.callbacks.get(id);
+    if (cb) {
+      cb(payload);
 
-        break;
-      }
-
-      case INTERFACE_MESSAGES.TRANSACTION_CONFIRMED: {
-        /* tslint:disable-next-line:no-shadowed-variable */
-        // const typedPayload = payload as InterfaceMessageToPayload[typeof INTERFACE_MESSAGES.TRANSACTION_CONFIRMED];
-
-        break;
-      }
-
-      case INTERFACE_MESSAGES.TRANSACTION_REJECTED: {
-        break;
-      }
-
-      default: {
-        console.warn(
-          `SafeConnector: A message was received from origin ${origin} with an unknown message id: ${messageId}`,
-        );
-        break;
-      }
+      this.callbacks.delete(id);
     }
-  }
+  };
 
-  public send<T extends SDKMessageIds, D = SDKMessageToPayload[T]>(
-    messageId: T,
-    data: D,
-    requestId?: RequestId,
-  ): SentSDKMessage<T, D> {
-    if (!requestId) {
-      if (typeof window !== 'undefined') {
-        requestId = Math.trunc(window?.performance.now());
-      } else {
-        requestId = Math.trunc(Date.now());
-      }
-    }
-    const message = {
-      messageId,
-      requestId,
-      data,
-    };
+  public send = <M extends Methods, P, R>(method: M, params: P): Promise<Response<R>> => {
+    const request = MessageFormatter.makeRequest(method, params);
 
-    if (typeof window !== 'undefined') {
-      window.parent.postMessage(message, '*');
+    if (typeof window === 'undefined') {
+      throw new Error("Window doesn't exist");
     }
 
-    return message;
-  }
+    window.parent.postMessage(request, '*');
+    return new Promise((resolve) => {
+      this.callbacks.set(request.id, (response: Response<R>) => {
+        resolve(response);
+      });
+    });
+  };
 }
 
-export default InterfaceCommunicator;
-export * from './messageIds';
+export default PostMessageCommunicator;
+export * from './methods';

src/communication/messageFormatter.ts

@@ -0,0 +1,34 @@
+import { ErrorResponse, SDKRequestData, Methods, RequestId, SuccessResponse, MethodToResponse } from '../types';
+import { generateRequestId } from './utils';
+import { getSDKVersion } from '../utils';
+
+class MessageFormatter {
+  static makeRequest = <M extends Methods = Methods, P = unknown>(method: M, params: P): SDKRequestData<M, P> => {
+    const id = generateRequestId();
+
+    return {
+      id,
+      method,
+      params,
+      env: {
+        sdkVersion: getSDKVersion(),
+      },
+    };
+  };
+
+  static makeResponse = (id: RequestId, data: MethodToResponse[Methods], version: string): SuccessResponse => ({
+    id,
+    success: true,
+    version,
+    data,
+  });
+
+  static makeErrorResponse = (id: RequestId, error: string, version: string): ErrorResponse => ({
+    id,
+    success: false,
+    error,
+    version,
+  });
+}
+
+export { MessageFormatter };

src/communication/methods.ts

@@ -0,0 +1,6 @@
+export const METHODS = {
+  getEnvInfo: 'getEnvInfo',
+  sendTransactions: 'sendTransactions',
+  rpcCall: 'rpcCall',
+  getSafeInfo: 'getSafeInfo',
+} as const;