xumm-sdk - npm Package Compare versions

Comparing version 0.1.2 to 0.1.4

dist/package.json

 {
     "name": "xumm-sdk",
-    "version": "0.1.2",
+    "version": "0.1.4",
     "description": "Interact with the Xumm Developer API",
@@ -5,0 +5,0 @@ "main": "dist/src/index.js",

dist/src/Meta.d.ts

@@ -1,2 +0,2 @@
-import type { ApplicationDetails, AnyJson, CuratedAssetsResponse } from './types';
+import type { ApplicationDetails, CreatePayload, AnyJson, CuratedAssetsResponse } from './types';
 export declare class Meta {
@@ -6,5 +6,5 @@ private apiKey;
     constructor(apiKey: string, apiSecret: string);
-    call<T>(endpoint: string, httpMethod?: string, data?: AnyJson | string): Promise<T>;
+    call<T>(endpoint: string, httpMethod?: string, data?: CreatePayload | AnyJson): Promise<T>;
     ping(): Promise<ApplicationDetails>;
     getCuratedAssets(): Promise<CuratedAssetsResponse>;
 }

dist/src/types/Meta/AnyJson.d.ts

@@ -1,3 +0,1 @@
-export interface AnyJson {
-    [key: string]: AnyJson | any;
-}
+export declare type AnyJson = Record<string, unknown>;

dist/src/types/Meta/ApplicationDetails.d.ts

 export interface ApplicationDetails {
-    quota: object;
+    quota: Record<string, unknown>;
     application: {
@@ -4,0 +4,0 @@ uuidv4: string;

dist/src/types/Payload/onPayloadEvent.d.ts

 import type { SubscriptionCallbackParams } from './SubscriptionCallbackParams';
-export declare type onPayloadEvent = (subscriptionCallback: SubscriptionCallbackParams) => any | Promise<any> | void;
+export declare type onPayloadEvent = (subscriptionCallback: SubscriptionCallbackParams) => unknown | Promise<unknown> | void;

dist/src/types/Payload/PayloadSubscription.d.ts

@@ -5,5 +5,5 @@ import type WebSocket from 'ws';
     payload: XummPayload;
-    resolved: Promise<any> | undefined;
-    resolve: (resolveData?: any) => void;
+    resolved: Promise<unknown> | undefined;
+    resolve: (resolveData?: unknown) => void;
     websocket: WebSocket;
 }

dist/src/types/Payload/SubscriptionCallbackParams.d.ts

@@ -5,4 +5,4 @@ import type { AnyJson, XummGetPayloadResponse as XummPayload } from '../';
     data: AnyJson;
-    resolve: (resolveData?: any) => void;
+    resolve: (resolveData?: unknown) => void;
     payload: XummPayload;
 }

dist/src/types/xumm-api/index.d.ts

@@ -8,11 +8,8 @@ declare const XummTxTypes: readonly ["SignIn"];
 export declare type XummQrQuality = 'm' | 'q' | 'h';
-export interface XummJsonTransaction {
+export interface XummJsonTransaction extends Record<string, unknown> {
     TransactionType: XummTransactionType | XrplTransactionType;
-    [key: string]: any;
 }
 export interface XummCustomMeta {
     identifier?: string | null;
-    blob?: {
-        [key: string]: any;
-    } | null;
+    blob?: Record<string, unknown> | null;
     instruction?: string | null;
@@ -92,5 +89,3 @@ }
         expires_in_seconds: number;
-        computed?: {
-            [key: string]: any;
-        };
+        computed?: Record<string, unknown>;
     };
@@ -97,0 +92,0 @@ response: {

dist/src/utils.d.ts

@@ -13,6 +13,6 @@ export interface FatalApiError {
     private rejectFn;
-    promise: Promise<any>;
+    promise: Promise<unknown>;
     constructor();
-    resolve(arg?: any): Promise<any>;
-    reject(arg?: any): Promise<any>;
+    resolve(arg?: unknown): Promise<unknown>;
+    reject(arg?: unknown): Promise<unknown>;
 }

package.json

 {
   "name": "xumm-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Interact with the Xumm Developer API",
@@ -5,0 +5,0 @@ "main": "dist/src/index.js",

README.md

@@ -1,2 +0,2 @@
-# XUMM SDK (JS/TS)  [![npm version](https://badge.fury.io/js/xumm-sdk.svg)](https://www.npmjs.com/xumm-sdk)
+# XUMM SDK (JS/TS) [![npm version](https://badge.fury.io/js/xumm-sdk.svg)](https://www.npmjs.com/xumm-sdk) [![GitHub Actions NodeJS status](https://github.com/XRPL-Labs/XUMM-SDK/workflows/NodeJS/badge.svg?branch=master)](https://github.com/XRPL-Labs/XUMM-SDK/actions) [![GitHub Actions Deno status](https://github.com/XRPL-Labs/XUMM-SDK/workflows/Deno/badge.svg?branch=master)](https://github.com/XRPL-Labs/XUMM-SDK/actions)
 
@@ -7,3 +7,3 @@ Interact with the XUMM SDK from Javascript / Typescript environments.
 
-Get the SDK straight from npm: `npm install xumm-sdk`.
+Get the SDK straight from npm: `npm install xumm-sdk`. The SDK is [also available](https://deno.land/x/xumm) for [Deno](https://deno.land) ([XUMM SDK Deno Readme](https://github.com/XRPL-Labs/XUMM-SDK/blob/master/deno/README.md)).
 
@@ -33,5 +33,3 @@ Initialize the SDK in Javascript:
 
-The SDK will look in your environment or dotenv file (`.env`) for the `XUMM_APIKEY` and `XUMM_APISECRET` values.
-A [sample dotenv file looks like this](https://github.com/XRPL-Labs/XUMM-SDK/blob/master/sample.env). Alternatively
-you can provide your XUMM API Key & Secret by passing them to the XummSdk constructor. If both your environment and the SDK constructor contain credentials, the values provided to the constructor will be used.
+The SDK will look in your environment or dotenv file (`.env`) for the `XUMM_APIKEY` and `XUMM_APISECRET` values. A `.env.sample` file is provided in this repository. A [sample dotenv file looks like this](https://github.com/XRPL-Labs/XUMM-SDK/blob/master/sample.env). Alternatively you can provide your XUMM API Key & Secret by passing them to the XummSdk constructor. If both your environment and the SDK constructor contain credentials, the values provided to the constructor will be used.
 
@@ -203,4 +201,27 @@ Create your app and get your XUMM API credentials at the XUMM Developer Console:
 
-WIP
+To create a payload, a `txjson` XRPL transaction can be provided. Alternatively, a transaction formatted as HEX blob (string) can be provided in a `txblob` property. **See the [intro](#intro) for more information about payloads.** Take a look at the [Developer Docs for more information about payloads](https://xumm.readme.io/docs/your-first-payload).
 
+The response (see: [Developer Docs](https://xumm.readme.io/docs/payload-response-resources)) of a `Sdk.payload.create()` operation, a `<CreatedPayload>` object, looks like this:
+
+```json
+{
+  "uuid": "1289e9ae-7d5d-4d5f-b89c-18633112ce09",
+  "next": {
+    "always": "https://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09",
+    "no_push_msg_received": "https://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09/qr"
+  },
+  "refs": {
+    "qr_png": "https://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09_q.png",
+    "qr_matrix": "https://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09_q.json",
+    "qr_uri_quality_opts": [ "m", "q", "h" ],
+    "websocket_status": "wss://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09"
+  },
+  "pushed": true
+}
+```
+
+The `next.always` URL is the URL to send the end user to, to scan a QR code or automatically open the XUMM app (if on mobile). If a `user_token` has been provided as part of the payload data provided to `Sdk.payload.create()`, you can see if the payload has been pushed to the end user. A button "didn't receive a push notification" could then take the user to the `next.no_push_msg_received` URL. The 
+
+Alternatively user routing / instruction flows can be custom built using the QR information provided in the `refs` object, and a subscription for live status updates (opened, signed, etc.) using a WebSocket client can be setup by conneting to the `refs.websocket_status` URL. **Please note: this SDK already offers subscriptions. There's no need to setup your own WebSocket client, see [Payload subscriptions: live updates](#payload-subscriptions-live-updates).** There's more information about the [payload workflow](https://xumm.readme.io/docs/payload-workflow) and a [paylaod lifecycle](https://xumm.readme.io/docs/doc-payload-life-cycle) in the Developer Docs.
+
 ##### Sdk.payload.cancel
@@ -215,12 +236,37 @@
 
-WIP
+To cancel a payload, provide a payload UUID (string), a `<XummPayload>` (by performing a `Sdk.payload.get()` first) or a `<CreatedPayload>` (by using the response of a `Sdk.payload.create()` call). By cancelling an existing payload, the payload will be marked as expired and can no longer be opened by users. 
 
+**Please note**: *if a user already opened the payload in XUMM APP, the payload cannot be cancelled: the user may still be resolving the payload in the XUMM App, and should have a chance to complete that process*.
+
+A response (generic API types [here](https://github.com/XRPL-Labs/XUMM-SDK/blob/master/src/types/xumm-api/index.ts)) looks like:
+```javascript
+{
+  result: {
+    cancelled: boolean
+    reason: XummCancelReason
+  }
+  meta: XummPayloadMeta
+  custom_meta: XummCustomMeta
+}
+```
+
 #### Payload subscriptions: live updates
 
-WIP
+To subscribe to live payload status updates, the XUMM SDK can setup a WebSocket connection and monitor live status events. Emitted events include:
 
-- Note: Two methods: callback + return non void = break, of return object en resolve()
-  - onPayloadEvent
-- Reminder: type for callback event?
+- The payload is opened by a XUMM App user (webpage)
+- The payload is opened by a XUMM App user (in the app)
+- Payload expiration updates (remaining time in seconds)
+- The payload was resolved by rejecting
+- The payload was resolved by accepting (signing)
 
+More information about the status update events & sample event data [can be found in the Developer Docs](https://xumm.readme.io/docs/payload-status).
+
+Status updates can be processed by providing a *callback function* to the `Sdk.payload.subscribe()` method. Alternatively, the (by the `Sdk.payload.subscribe()` method) returned raw websocket can be used to listen for WebSocket `onmessage` events.
+
+The subscription will be closed by either:
+
+- Returning non-void in the *callback function* passed to the `Sdk.payload.subscribe()` method
+- Manually calling `.resolve()` on the object returned by the `Sdk.payload.subscribe()` method
+
 ##### Sdk.payload.subscribe
@@ -230,11 +276,31 @@
 async Sdk.payload.subscribe (
-    payload: string | XummPayload | CreatedPayload,
-    callback?: onPayloadEvent
-  ): Promise<PayloadSubscription>
+  payload: string | XummPayload | CreatedPayload,
+  callback?: onPayloadEvent
+): Promise<PayloadSubscription>
 ```
 
+If a callback function is not provided, the subscription will stay active until the `<PayloadSubscription>.resolve()` method is called manually, eg. based on handling `<PayloadSubscription>.websocket.onmessage` events.
+
+When a callback function is provided, for every paylaod specific event the callback function will be called with [`<SubscriptionCallbackParams>`](https://github.com/XRPL-Labs/XUMM-SDK/blob/651bd409ee2aab47fb9151513b8cf981cc1a4f30/src/types/Payload/SubscriptionCallbackParams.ts). The `<SubscriptionCallbackParams>.data` property contains parsed JSON containing event information. Either by calling `<SubscriptionCallbackParams>.resolve()` or by returning a non-void value in the *callback function* the subscription will be ended, and the `<PayloadSubscription>.resolved` promise will resolve with the value returned or passed to the `<SubscriptionCallbackParams>.resolve()` method.
+
+Resolving (by returning non-void in the callback or calling `resolve()` manually) closes the WebSocket client the XUMM SDK sets up 'under the hood'.
+
 The [`<PayloadSubscription>`](https://github.com/XRPL-Labs/XUMM-SDK/blob/master/src/types/Payload/PayloadSubscription.ts) object looks like this:
 
-WIP
+```javascript
+{
+  payload: XummPayload,
+  resolved: Promise<unknown> | undefined
+  resolve: (resolveData?: unknown) => void
+  websocket: WebSocket
+}
+```
 
+Examples:
+
+- [Async process after returning data in the callback function](https://gist.github.com/WietseWind/e13ab068f06b5e9f2f4a0aeac96f6e2e)
+- [Await based on returning data in the callback function](https://gist.github.com/WietseWind/698ff9a5838e600a8ae36ddcc45d0793)
+- [Await based on resolving a callback event](https://gist.github.com/WietseWind/1afaf3a23b8ea18ded526bbbf1b577dd)
+- [Await based on resolving without using a callback function](https://gist.github.com/WietseWind/76890afd39a01e9876c8a629b3e58174)
+
 ##### Sdk.payload.createAndSubscribe
@@ -251,4 +317,7 @@
 
-WIP
+All information that applies on [`Sdk.payload.create()`](#sdk.payload.create) and [`Sdk.payload.subscribe()`](#sdk.payload.subscribe) applies. Differences are:
 
+1. The input for a `Sdk.payload.createAndSubscribe()` call isn't a payload UUID / existing payload, but a paykiad to create. 
+2. The response object also contains (`<PayloadAndSubscription>.created`) the response obtained when creating the payload
+
 ## Debugging (logging)
@@ -288,46 +357,4 @@
 
-Build, run, show debug output & watch `/dist/samples/dev.js`, compiled from `/samples/dev.ts` using `npm run dev`. The `/samples/dev.ts` file is **not included by default**. A sample file could contain:
+Build, run, show debug output & watch `dist/samples/dev.js`, compiled from `samples/dev.ts` using `npm run dev`. The `samples/dev.ts` file is **not included by default**.
 
-```typescript
-import Debug from 'debug'
-import {XummSdk, XummTypes} from '../src/'
-
-const log = Debug('xumm-sdk:sample')
-
-const main = async () => {
-  try {
-    const Sdk = new XummSdk('someAppKey', 'someAppSecret')
-    const pong = await Sdk.ping()
-    log({pong})
-
-    const curatedAssets = await Sdk.getCuratedAssets()
-    log({curatedAssets})
-
-    const PaymentPayload: XummTypes.CreatePayload = {
-      txjson: {
-        TransactionType : 'Payment',
-        Destination : 'rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY',
-        DestinationTag: 495,
-        Amount: '1337'
-      }
-    }
-
-    const payload = await Sdk.payload.create(PaymentPayload)
-    log({payload})
-
-    if (payload) {
-      await Sdk.payload.subscribe(payload, event => {
-        log('Subscription Event data', event.data)
-
-        if (typeof event.data.expired !== 'undefined' || typeof event.data.signed !== 'undefined') {
-          return event.data
-        }
-      })
-    }
-  } catch (e) {
-    log({error: e.message, stack: e.stack})
-  }
-}
-
-main()
-```
+[Here's a sample `samples/dev.ts` file](https://gist.github.com/WietseWind/e2e9729619872cb736fe29b486e9c623).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

50935

increased by12.45%

Number of lines in readme file

354

increased by8.26%

Worsened metrics

Lines of code

781

decreased by-0.89%

No dependency changes