tapass 0.1.0 → 0.2.0

package/src/tapd_methods/channels/get_asset_invoices.ts

@@ -0,0 +1,258 @@
+import {auto as asyncAuto} from 'async';
+import {returnResult} from 'asyncjs-util';
+
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isMethodUnsupported} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import {assetChannelRpcError} from '../../tapd_responses/index.js';
+import {rpcAssetInvoiceAsInvoice} from '../../tapd_responses/index.js';
+import type {AssetInvoice} from '../../tapd_responses/index.js';
+import type {AuthenticatedTapdArgs} from '../../typescript/index.js';
+import type {TapdCallback} from '../../typescript/index.js';
+import type {TapdError} from '../../typescript/index.js';
+import type {TapdMethod} from '../../typescript/index.js';
+
+const asEnd = (n?: string) => (!n ? 0 : Math.ceil(Date.parse(n) / 1e3));
+const asStart = (n?: string) => (!n ? 0 : Math.floor(Date.parse(n) / 1e3));
+const defaultLimit = 100;
+const {isArray} = Array;
+const isDate = (n: string) => Date.parse(n) > 0;
+const {isSafeInteger} = Number;
+const isString = (n: unknown) => typeof n === 'string';
+const lastPageFirstIndexOffset = 1;
+const method = 'listInvoices';
+const {parse} = JSON;
+const {stringify} = JSON;
+const type = 'tapchannel';
+
+export type GetAssetInvoicesArgs = AuthenticatedTapdArgs<{
+  /** Created At or After ISO 8601 Date String */
+  created_after?: string;
+  /** Created At or Before ISO 8601 Date String */
+  created_before?: string;
+  /** Only Unconfirmed Invoices Bool */
+  is_unconfirmed?: boolean;
+  /** Page Result Limit Number */
+  limit?: number;
+  /** Opaque Paging Token String */
+  token?: string;
+}>;
+
+export type GetAssetInvoicesResult = {
+  invoices: AssetInvoice[];
+  /** Next Opaque Paging Token */
+  next?: string;
+};
+
+type Tasks = {
+  getInvoices: {invoices: unknown[]; token?: string};
+  invoices: GetAssetInvoicesResult;
+  validate: undefined;
+};
+
+/** Get invoices that received an asset, newest first
+
+  lnd pages over all invoices, then tapd keeps only the asset invoices, so a
+  page can have fewer invoices than the limit. Use `next` until it is empty.
+
+  Requires `channels:read` permission
+
+  This method needs tapd v0.8.1 or later
+
+  The invoice fields are the same as in lightning getInvoices
+
+  {
+    [created_after]: <Created At or After ISO 8601 Date String>
+    [created_before]: <Created At or Before ISO 8601 Date String>
+    [is_unconfirmed]: <Only Unconfirmed Invoices Bool>
+    [limit]: <Page Result Limit Number>
+    tapd: <Authenticated tapd API Object>
+    [token]: <Opaque Paging Token String>
+  }
+
+  @returns via cbk or Promise
+  {
+    invoices: [{
+      assets: [{
+        amount: <Asset Units Numeric String>
+        asset_id: <Asset Id Hex String>
+        [group_key]: <Asset Group Key Hex String>
+      }]
+      [chain_address]: <Fallback Chain Address String>
+      cltv_delta: <Final CLTV Delta Number>
+      [confirmed_at]: <Settled at ISO 8601 Date String>
+      [confirmed_index]: <Confirmed Index Number>
+      created_at: <ISO 8601 Date String>
+      description: <Description String>
+      [description_hash]: <Description Hash Hex String>
+      expires_at: <ISO 8601 Date String>
+      features: [{
+        bit: <BOLT 09 Feature Bit Number>
+        is_known: <Feature is Known Bool>
+        is_required: <Feature Support is Required To Pay Bool>
+        type: <Feature Type String>
+      }]
+      id: <Payment Hash Hex String>
+      index: <Invoice Add Index Number>
+      [is_canceled]: <Invoice is Canceled Bool>
+      is_confirmed: <Invoice is Confirmed Bool>
+      [is_held]: <HTLC is Held Bool>
+      is_private: <Invoice is Private Bool>
+      [is_push]: <Invoice is Push Payment Bool>
+      mtokens: <Millitokens String>
+      [payment]: <Payment Identifying Secret Hex String>
+      payments: [<lightning Invoice Payment Object>]
+      received: <Received Tokens Number>
+      received_mtokens: <Received Millitokens String>
+      [request]: <Bolt 11 Invoice String>
+      secret: <Secret Preimage Hex String>
+      tokens: <Tokens Number>
+    }]
+    [next]: <Next Opaque Paging Token String>
+  }
+*/
+const getAssetInvoices: TapdMethod<
+  GetAssetInvoicesArgs,
+  GetAssetInvoicesResult
+> = (
+  args: GetAssetInvoicesArgs,
+  cbk?: TapdCallback<GetAssetInvoicesResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!!args.created_after && !isDate(args.created_after)) {
+            return cbk([400, 'ExpectedCreatedAfterDateToGetAssetInvoices']);
+          }
+
+          if (!!args.created_before && !isDate(args.created_before)) {
+            return cbk([400, 'ExpectedCreatedBeforeDateToGetAssetInvoices']);
+          }
+
+          const limit = args.limit;
+
+          if (limit !== undefined && (!isSafeInteger(limit) || limit < 1)) {
+            return cbk([400, 'ExpectedPositiveLimitToGetAssetInvoices']);
+          }
+
+          if (!!args.limit && !!args.token) {
+            return cbk([400, 'UnexpectedLimitWhenPagingAssetInvoices']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToGetAssetInvoices']);
+          }
+
+          return cbk();
+        },
+
+        // Get the page of invoices
+        getInvoices: [
+          'validate',
+          ({}, cbk) => {
+            let after = asStart(args.created_after);
+            let before = asEnd(args.created_before);
+            let limit = args.limit || defaultLimit;
+            let offset = 0;
+
+            // When there is a token, the token has the page details
+            if (!!args.token) {
+              try {
+                const pagingToken = parse(args.token);
+
+                after = pagingToken.after;
+                before = pagingToken.before;
+                limit = pagingToken.limit;
+                offset = pagingToken.offset;
+              } catch (err) {
+                return cbk([400, 'ExpectedValidPagingTokenForInvoices', {err}]);
+              }
+
+              const values = [after, before, limit, offset];
+
+              if (!values.every(isSafeInteger) || limit < 1) {
+                return cbk([400, 'ExpectedValidPagingTokenForInvoices']);
+              }
+            }
+
+            const request = {
+              request: {
+                creation_date_end: before,
+                creation_date_start: after,
+                index_offset: offset,
+                num_max_invoices: limit,
+                pending_only: args.is_unconfirmed === true,
+                reversed: true,
+              },
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToGetAssetInvoices']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToGetAssetInvoices']);
+              }
+
+              if (isMethodUnsupported({err})) {
+                return cbk([501, 'ExpectedNewerTapdToGetAssetInvoices']);
+              }
+
+              const knownError = assetChannelRpcError({err});
+
+              if (!!knownError) {
+                return cbk(knownError);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorGettingAssetInvoices', {err}]);
+              }
+
+              if (!res || !isArray(res.invoices)) {
+                return cbk([503, 'ExpectedAssetInvoicesInListResponse']);
+              }
+
+              if (!isString(res.first_index_offset)) {
+                return cbk([503, 'ExpectedFirstIndexOffsetInAssetInvoices']);
+              }
+
+              const nextOffset = Number(res.first_index_offset);
+
+              const isLastPage = nextOffset <= lastPageFirstIndexOffset;
+
+              return cbk(null, {
+                invoices: res.invoices,
+                token: isLastPage
+                  ? undefined
+                  : stringify({after, before, limit, offset: nextOffset}),
+              });
+            });
+          },
+        ],
+
+        // Map the invoices
+        invoices: [
+          'getInvoices',
+          ({getInvoices}, cbk) => {
+            try {
+              const invoices = getInvoices.invoices
+                .map(n => rpcAssetInvoiceAsInvoice(n as any))
+                .sort((a, b) => b.created_at.localeCompare(a.created_at));
+
+              return cbk(null, {invoices, next: getInvoices.token});
+            } catch (err: any) {
+              return cbk([503, err.message]);
+            }
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'invoices'}, cbk),
+    );
+  });
+};
+
+export default getAssetInvoices;

package/src/tapd_methods/channels/get_asset_payments.ts

@@ -0,0 +1,243 @@
+import {auto as asyncAuto} from 'async';
+import {returnResult} from 'asyncjs-util';
+
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isMethodUnsupported} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import {assetChannelRpcError} from '../../tapd_responses/index.js';
+import {rpcAssetPaymentAsPayment} from '../../tapd_responses/index.js';
+import type {AssetPayment} from '../../tapd_responses/index.js';
+import type {AuthenticatedTapdArgs} from '../../typescript/index.js';
+import type {TapdCallback} from '../../typescript/index.js';
+import type {TapdError} from '../../typescript/index.js';
+import type {TapdMethod} from '../../typescript/index.js';
+
+const asEnd = (n?: string) => (!n ? 0 : Math.ceil(Date.parse(n) / 1e3));
+const asStart = (n?: string) => (!n ? 0 : Math.floor(Date.parse(n) / 1e3));
+const defaultLimit = 250;
+const {isArray} = Array;
+const isDate = (n: string) => Date.parse(n) > 0;
+const {isSafeInteger} = Number;
+const isString = (n: unknown) => typeof n === 'string';
+const lastPageFirstIndexOffset = 1;
+const method = 'listPayments';
+const {parse} = JSON;
+const {stringify} = JSON;
+const type = 'tapchannel';
+
+export type GetAssetPaymentsArgs = AuthenticatedTapdArgs<{
+  /** Created At or After ISO 8601 Date String */
+  created_after?: string;
+  /** Created At or Before ISO 8601 Date String */
+  created_before?: string;
+  /** Page Result Limit Number */
+  limit?: number;
+  /** Opaque Paging Token String */
+  token?: string;
+}>;
+
+export type GetAssetPaymentsResult = {
+  payments: AssetPayment[];
+  /** Next Opaque Paging Token */
+  next?: string;
+};
+
+type Tasks = {
+  getPayments: {payments: unknown[]; token?: string};
+  payments: GetAssetPaymentsResult;
+  validate: undefined;
+};
+
+/** Get confirmed payments that sent an asset, newest first
+
+  lnd pages over all payments, then tapd keeps only the asset payments, so a
+  page can have fewer payments than the limit. Use `next` until it is empty.
+
+  Requires `channels:read` permission
+
+  This method needs tapd v0.8.1 or later
+
+  The payment fields are the same as in lightning getPayments
+
+  {
+    [created_after]: <Created At or After ISO 8601 Date String>
+    [created_before]: <Created At or Before ISO 8601 Date String>
+    [limit]: <Page Result Limit Number>
+    tapd: <Authenticated tapd API Object>
+    [token]: <Opaque Paging Token String>
+  }
+
+  @returns via cbk or Promise
+  {
+    payments: [{
+      assets: [{
+        amount: <Asset Units Numeric String>
+        asset_id: <Asset Id Hex String>
+        [group_key]: <Asset Group Key Hex String>
+      }]
+      attempts: [<lightning Payment Attempt Object>]
+      [confirmed_at]: <Payment Confirmed At ISO 8601 Date String>
+      created_at: <Payment at ISO-8601 Date String>
+      [destination]: <Destination Node Public Key Hex String>
+      [fee]: <Paid Routing Fee Rounded Down Tokens Number>
+      [fee_mtokens]: <Paid Routing Fee in Millitokens String>
+      hops: [<First Route Hop Public Key Hex String>]
+      id: <Payment Preimage Hash String>
+      [index]: <Payment Add Index Number>
+      is_confirmed: <Payment is Confirmed Bool>
+      is_outgoing: <Transaction Is Outgoing Bool>
+      mtokens: <Millitokens Sent to Destination String>
+      [request]: <BOLT 11 Payment Request String>
+      [safe_fee]: <Payment Forwarding Fee Rounded Up Tokens Number>
+      safe_tokens: <Payment Tokens Rounded Up Number>
+      [secret]: <Payment Preimage Hex String>
+      tokens: <Rounded Down Tokens Sent to Destination Number>
+    }]
+    [next]: <Next Opaque Paging Token String>
+  }
+*/
+const getAssetPayments: TapdMethod<
+  GetAssetPaymentsArgs,
+  GetAssetPaymentsResult
+> = (
+  args: GetAssetPaymentsArgs,
+  cbk?: TapdCallback<GetAssetPaymentsResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!!args.created_after && !isDate(args.created_after)) {
+            return cbk([400, 'ExpectedCreatedAfterDateToGetAssetPayments']);
+          }
+
+          if (!!args.created_before && !isDate(args.created_before)) {
+            return cbk([400, 'ExpectedCreatedBeforeDateToGetAssetPayments']);
+          }
+
+          const limit = args.limit;
+
+          if (limit !== undefined && (!isSafeInteger(limit) || limit < 1)) {
+            return cbk([400, 'ExpectedPositiveLimitToGetAssetPayments']);
+          }
+
+          if (!!args.limit && !!args.token) {
+            return cbk([400, 'UnexpectedLimitWhenPagingAssetPayments']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToGetAssetPayments']);
+          }
+
+          return cbk();
+        },
+
+        // Get the page of payments
+        getPayments: [
+          'validate',
+          ({}, cbk) => {
+            let after = asStart(args.created_after);
+            let before = asEnd(args.created_before);
+            let limit = args.limit || defaultLimit;
+            let offset = 0;
+
+            // When there is a token, the token has the page details
+            if (!!args.token) {
+              try {
+                const pagingToken = parse(args.token);
+
+                after = pagingToken.after;
+                before = pagingToken.before;
+                limit = pagingToken.limit;
+                offset = pagingToken.offset;
+              } catch (err) {
+                return cbk([400, 'ExpectedValidPagingTokenForPayments', {err}]);
+              }
+
+              const values = [after, before, limit, offset];
+
+              if (!values.every(isSafeInteger) || limit < 1) {
+                return cbk([400, 'ExpectedValidPagingTokenForPayments']);
+              }
+            }
+
+            const request = {
+              request: {
+                creation_date_end: before,
+                creation_date_start: after,
+                include_incomplete: false,
+                index_offset: offset,
+                max_payments: limit,
+                reversed: true,
+              },
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToGetAssetPayments']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToGetAssetPayments']);
+              }
+
+              if (isMethodUnsupported({err})) {
+                return cbk([501, 'ExpectedNewerTapdToGetAssetPayments']);
+              }
+
+              const knownError = assetChannelRpcError({err});
+
+              if (!!knownError) {
+                return cbk(knownError);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorGettingAssetPayments', {err}]);
+              }
+
+              if (!res || !isArray(res.payments)) {
+                return cbk([503, 'ExpectedAssetPaymentsInListResponse']);
+              }
+
+              if (!isString(res.first_index_offset)) {
+                return cbk([503, 'ExpectedFirstIndexOffsetInAssetPayments']);
+              }
+
+              const nextOffset = Number(res.first_index_offset);
+
+              const isLastPage = nextOffset <= lastPageFirstIndexOffset;
+
+              return cbk(null, {
+                payments: res.payments,
+                token: isLastPage
+                  ? undefined
+                  : stringify({after, before, limit, offset: nextOffset}),
+              });
+            });
+          },
+        ],
+
+        // Map the payments
+        payments: [
+          'getPayments',
+          ({getPayments}, cbk) => {
+            try {
+              const payments = getPayments.payments
+                .map(n => rpcAssetPaymentAsPayment(n as any))
+                .sort((a, b) => b.created_at.localeCompare(a.created_at));
+
+              return cbk(null, {payments, next: getPayments.token});
+            } catch (err: any) {
+              return cbk([503, err.message]);
+            }
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'payments'}, cbk),
+    );
+  });
+};
+
+export default getAssetPayments;

package/src/tapd_methods/channels/index.ts

@@ -0,0 +1,30 @@
+export {default as createAssetInvoice} from './create_asset_invoice.js';
+export type {CreateAssetInvoiceArgs} from './create_asset_invoice.js';
+export type {CreateAssetInvoiceResult} from './create_asset_invoice.js';
+export {default as decodeAssetPaymentRequest} from './decode_asset_payment_request.js';
+export type {DecodeAssetPaymentRequestArgs} from './decode_asset_payment_request.js';
+export type {DecodeAssetPaymentRequestResult} from './decode_asset_payment_request.js';
+export {default as encodeAssetCustomRecords} from './encode_asset_custom_records.js';
+export type {EncodeAssetCustomRecordsArgs} from './encode_asset_custom_records.js';
+export type {EncodeAssetCustomRecordsResult} from './encode_asset_custom_records.js';
+export {default as getAssetInvoices} from './get_asset_invoices.js';
+export type {GetAssetInvoicesArgs} from './get_asset_invoices.js';
+export type {GetAssetInvoicesResult} from './get_asset_invoices.js';
+export {default as getAssetPayments} from './get_asset_payments.js';
+export type {GetAssetPaymentsArgs} from './get_asset_payments.js';
+export type {GetAssetPaymentsResult} from './get_asset_payments.js';
+export {default as openAssetChannel} from './open_asset_channel.js';
+export type {OpenAssetChannelArgs} from './open_asset_channel.js';
+export type {OpenAssetChannelResult} from './open_asset_channel.js';
+export {default as payAssetInvoice} from './pay_asset_invoice.js';
+export type {PayAssetInvoiceArgs} from './pay_asset_invoice.js';
+export type {PayAssetInvoiceResult} from './pay_asset_invoice.js';
+export {default as sendAssetKeysend} from './send_asset_keysend.js';
+export type {SendAssetKeysendArgs} from './send_asset_keysend.js';
+export type {SendAssetKeysendResult} from './send_asset_keysend.js';
+export {default as subscribeToAssetInvoices} from './subscribe_to_asset_invoices.js';
+export type {SubscribeToAssetInvoicesArgs} from './subscribe_to_asset_invoices.js';
+export {default as subscribeToAssetPayments} from './subscribe_to_asset_payments.js';
+export type {SubscribeToAssetPaymentsArgs} from './subscribe_to_asset_payments.js';
+export {default as subscribeToPastAssetPayment} from './subscribe_to_past_asset_payment.js';
+export type {SubscribeToPastAssetPaymentArgs} from './subscribe_to_past_asset_payment.js';