@spritz-finance/api-client 0.0.4 → 0.0.6

package/LICENCE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2023, Spritz Finance Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -23,13 +23,20 @@ A Typescript library for interacting with the Spritz Finance API
 ```typescript
 import { SpritzApiClient, Environment } from '@spritz-finance/api-client'
 
-const client = SpritzApiClient.initialize(Environment.Staging, 'YOUR_API_KEY_HERE')
+const client = SpritzApiClient.initialize({
+	environment: Environment.Staging, 
+	apiKey: 'YOUR_API_KEY_HERE'
+})
 ```
 
 ## Bank Accounts
 
+Spritz provides robust support for bank accounts, allowing you to easily manage and interact with a user's bank account. To leverage these capabilities, you can utilize our specific methods and functionalities designed for bank accounts.
+
 ### List user bank accounts
 
+You can retrieve a comprehensive list of all bank accounts that have been linked to a user's account using this functionality.
+
 ```typescript
 const bankAccounts = await client.bankAccounts.list()
 ```
@@ -40,33 +47,37 @@ The bank accounts endpoint returns a standard response comprising an array of al
 
 ```typescript
 const bankAccounts = [{
-	id: "62d17d3b377dab6c1342136e",
-	name: "Precious Savings",
-	type: "BankAccount",
-	bankAccountType: "USBankAccount",
-	bankAccountSubType: "Checking",
-	userId: "62d17d3b377dab6c1342136e",
-	accountNumber: "1234567",
-	bankAccountDetails: {
-		routingNumber: "00000123",
-	}
-	country: "US",
-	currency: "USD",
-	email: "bilbo@shiremail.net",
-	holder: "Bilbo Baggins",
-	institution: {
-		id: "62d27d4b277dab3c1342126e",
-		name: "Shire Bank",
-		logo: "https://tinyurl.com/shire-bank-logo",
-	},
-	ownedByUser: true,
-	createdAt: "2023-05-03T11:25:02.401Z",
+  id: "62d17d3b377dab6c1342136e",
+  name: "Precious Savings",
+  type: "BankAccount",
+  bankAccountType: "USBankAccount",
+  bankAccountSubType: "Checking",
+  userId: "62d17d3b377dab6c1342136e",
+  accountNumber: "1234567",
+  bankAccountDetails: {
+    routingNumber: "00000123",
+  }
+  country: "US",
+  currency: "USD",
+  email: "bilbo@shiremail.net",
+  holder: "Bilbo Baggins",
+  institution: {
+    id: "62d27d4b277dab3c1342126e",
+    name: "Shire Bank",
+	logo: "https://tinyurl.com/shire-bank-logo",
+  },
+  ownedByUser: true,
+  createdAt: "2023-05-03T11:25:02.401Z",
 }];
 ```
 
 ### Add US bank account
 
+At present, you can only add US bank accounts to a user's account. To add a US bank account for the user, you can use the following.
+
 ```typescript
+// Input arguments for creating a US bank account
+
 export interface USBankAccountInput {
     accountNumber: string
     email: string
@@ -94,12 +105,144 @@ const bankAccounts = await client.bankAccounts.create(BankAccountType.USBankAcco
 
 ### Rename a bank account
 
+You can conveniently change the display name of a bank account using the following endpoint. The first argument specifies the ID of the bank account, while the second argument represents the desired new name for the account.
+
 ```typescript
 const updateAccount = await client.bankAccounts.rename('62d17d3b377dab6c1342136e', 'My new account')
 ```
 
 ### Delete a bank account
 
+To remove a bank account from a user's account, you can use the following endpoint. You only need to specify the ID of the bank account that you want to delete as an argument.
+
 ```typescript
 await client.bankAccounts.delete('62d17d3b377dab6c1342136e')
 ```
+
+## Payment Requests
+
+A payment request refers to the intent to initiate a payment to a specific account. Once a payment request is created, a blockchain transaction is required to fulfill it. After the blockchain transaction settles, the payment request is completed, and a fiat payment is issued to the designated account.
+
+### Create a payment request
+
+To initiate a payment request for a specific account, you can use the following functionality. The required inputs for creating a payment request include the ID of the account to be paid, the amount of the fiat payment in USD, and the network on which the blockchain transaction will settle.
+
+```typescript
+import {PaymentNetwork} from '@spritz-finance/api-client';
+
+const paymentRequest = await client.paymentRequest.create({
+	amount: 100,
+	accountId: account.id,
+	network: PaymentNetwork.Ethereum,
+});
+
+// Example response
+
+{
+  id: '645399c8c1ac408007b12273',
+  userId: '63d12d3B577fab6c6382136e',
+  accountId: '6322445f10d3f4d19c4d72fe',
+  status: 'CREATED',
+  amount: 100,
+  feeAmount: 0,
+  amountDue: 100,
+  network: 'ethereum',
+  createdAt: '2023-05-04T11:40:56.488Z'
+}
+```
+
+### Fulfil a payment request (EVM transactions)
+
+After creating a payment request, you must issue a blockchain transaction to settle the payment request. For EVM compatible networks, this involves interacting with the SpritzPay smart contract (see: [SpritzPay deployments](https://docs.spritz.finance/docs/deployment-addresses)).
+
+To obtain the data needed for the transaction, you can use the following endpoint.
+
+```typescript
+import {PaymentNetwork} from '@spritz-finance/api-client';
+
+const paymentRequest = await client.paymentRequest.create({
+	amount: 100,
+	accountId: account.id,
+	network: PaymentNetwork.Ethereum,
+});
+
+const transactionData = await client.paymentRequest.getWeb3PaymentParams({
+	paymentRequest,
+	paymentTokenAddress: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC on mainnet
+})
+
+// Example response
+
+{
+  contractAddress: '0xbF7Abc15f00a8C2d6b13A952c58d12b7c194A8D0',
+  method: 'payWithToken',
+  calldata: '0xd71d9632000000000000000000000000a0b86991c6218b36c1d19d4a2e9eb0ce3606eb480000000000000000000000000000000000000000000000000000000005f5e100000000000000000000000000000000000000000064539a31c1ac408007b12277',
+  value: null,
+  requiredTokenInput: '100000000',
+  suggestedGasLimit: '110000'
+}
+```
+
+The contract address (to), calldata (data), and value are the primary components used to execute the blockchain transaction. You can use the `requiredTokenInput` to verify that the user's wallet has sufficient funds to complete the payment before initiating the transaction.
+
+### Transaction fees
+
+Transaction fees are applied once the monthly transaction volume exceeds $100. To determine the fee amount for a specific payment value, you can use the following endpoint.
+
+```typescript
+const fees = await client.paymentRequest.transactionPrice(101)
+
+// Example response
+0.01
+```
+
+## Payments
+
+Payments represent a fiat payment that has been issued to the account. Once the status of the Payment Request has moved to `Confirmed` then the Payment will be created.
+
+### Retrieve the payment for a payment request
+
+```typescript
+import {PaymentNetwork} from '@spritz-finance/api-client';
+
+const paymentRequest = await client.paymentRequest.create({
+	amount: 100,
+	accountId: account.id,
+	network: PaymentNetwork.Ethereum,
+});
+
+const payment = await client.payment.getForPaymentRequest(paymentRequest.id);
+
+// Example response
+
+ {
+    id: '6368e3a3ec516e9572bbd23b',
+    userId: '63d12d3B577fab6c6382136e',
+    status: 'PENDING',
+    accountId: '6322445f10d3f4d19c4d72fe',
+    amount: 100,
+    feeAmount: null,
+    createdAt: '2022-11-07T10:53:23.998Z'
+  }
+
+```
+
+### Retrieve all payments for an account
+
+```typescript
+const payments = await client.payment.listForAccount(account.id)
+
+// Example response
+
+[
+    {
+        id: '6368e3a3ec516e9572bbd23b',
+        userId: '63d12d3B577fab6c6382136e',
+        status: 'PENDING',
+        accountId: '6322445f10d3f4d19c4d72fe',
+        amount: 100,
+        feeAmount: null,
+        createdAt: '2022-11-07T10:53:23.998Z',
+    },
+]
+```

package/dist/spritz-api-client.d.ts

@@ -41,6 +41,18 @@ declare enum PayableAccountType {
     Bill = "Bill",
     DebitCard = "DebitCard"
 }
+declare enum PaymentStatus {
+    CANCELLED = "CANCELLED",
+    COMPLETED = "COMPLETED",
+    FAILED = "FAILED",
+    INITIALIZED = "INITIALIZED",
+    PENDING = "PENDING",
+    REFUNDED = "REFUNDED",
+    REVERSAL_IN_PROGRESS = "REVERSAL_IN_PROGRESS",
+    REVERSED = "REVERSED",
+    SCHEDULED = "SCHEDULED",
+    SENT = "SENT"
+}
 interface CreateDirectPaymentInput {
     accountId: string;
     amount: number;
@@ -139,6 +151,23 @@ interface RenameBankAccount_renamePayableAccount_BankAccount {
 }
 type RenameBankAccount_renamePayableAccount = RenameBankAccount_renamePayableAccount_Bill | RenameBankAccount_renamePayableAccount_BankAccount;
 
+interface AccountPayments_paymentsForAccount {
+    __typename: 'Payment';
+    id: string;
+    userId: any;
+    status: PaymentStatus;
+    accountId: any | null;
+    amount: number | null;
+    feeAmount: number | null;
+    createdAt: any;
+}
+interface AccountPayments {
+    paymentsForAccount: AccountPayments_paymentsForAccount[];
+}
+interface AccountPaymentsVariables {
+    accountId: string;
+}
+
 interface BankAccountFragment_bankAccountDetails_CanadianBankAccountDetails {
     __typename: 'CanadianBankAccountDetails';
 }
@@ -264,6 +293,17 @@ interface PayableAccountFragment_BankAccount {
 }
 type PayableAccountFragment = PayableAccountFragment_Bill | PayableAccountFragment_BankAccount;
 
+interface PaymentFragment {
+    __typename: 'Payment';
+    id: string;
+    userId: any;
+    status: PaymentStatus;
+    accountId: any | null;
+    amount: number | null;
+    feeAmount: number | null;
+    createdAt: any;
+}
+
 interface PaymentRequestFragment {
     __typename: 'DirectPayment';
     id: string;
@@ -271,10 +311,29 @@ interface PaymentRequestFragment {
     accountId: any;
     status: DirectPaymentStatus;
     amount: number;
+    feeAmount: number | null;
+    amountDue: number;
     network: string;
     createdAt: any;
 }
 
+interface PaymentRequestPayment_paymentForPaymentRequest {
+    __typename: 'Payment';
+    id: string;
+    userId: any;
+    status: PaymentStatus;
+    accountId: any | null;
+    amount: number | null;
+    feeAmount: number | null;
+    createdAt: any;
+}
+interface PaymentRequestPayment {
+    paymentForPaymentRequest: PaymentRequestPayment_paymentForPaymentRequest | null;
+}
+interface PaymentRequestPaymentVariables {
+    paymentRequestId: string;
+}
+
 interface TokenBalanceFragment {
     __typename: 'TokenBalance';
     /**
@@ -298,6 +357,13 @@ interface TokenBalanceFragment {
     tokenImageUrl: string;
 }
 
+interface TransactionPrice {
+    transactionPrice: number;
+}
+interface TransactionPriceVariables {
+    amount: number;
+}
+
 interface UserBankAccounts_userBankAccounts_bankAccountDetails_CanadianBankAccountDetails {
     __typename: 'CanadianBankAccountDetails';
 }
@@ -507,7 +573,7 @@ interface QueryParams<V = any> {
 }
 declare class GraphClient {
     client: AxiosInstance;
-    constructor(environment: Environment, apiKey: string);
+    constructor(environment: Environment, apiKey: string, integrationKey?: string);
     query<Q = any, V = any>({ query, variables }: QueryParams<V>): Promise<Q>;
 }
 
@@ -530,6 +596,13 @@ declare class BankAccountService {
     create<T extends BankAccountType>(type: T, input: CreateInputMapping[T]): Promise<NonNullable<CreateMutationMapping[T]["query"][keyof CreateMutationMapping[T]["query"]]> | null>;
 }
 
+declare class PaymentService {
+    private client;
+    constructor(client: GraphClient);
+    listForAccount(accountId: string): Promise<AccountPayments_paymentsForAccount[]>;
+    getForPaymentRequest(paymentRequestId: string): Promise<PaymentRequestPayment_paymentForPaymentRequest | null>;
+}
+
 interface CreatePaymentRequest_createDirectPayment {
     __typename: 'DirectPayment';
     id: string;
@@ -537,6 +610,8 @@ interface CreatePaymentRequest_createDirectPayment {
     accountId: any;
     status: DirectPaymentStatus;
     amount: number;
+    feeAmount: number | null;
+    amountDue: number;
     network: string;
     createdAt: any;
 }
@@ -559,30 +634,17 @@ interface CreatePaymentRequestInput {
     network: PaymentNetwork;
 }
 
+type PaymentRequest = CreatePaymentRequest_createDirectPayment;
+type Web3PaymentParams = GetSpritzPayParams_spritzPayParams;
 declare class PaymentRequestService {
     private client;
     constructor(client: GraphClient);
     create(input: CreatePaymentRequestInput): Promise<CreatePaymentRequest_createDirectPayment>;
-    /**
-     * Retrieves the Web3 payment parameters for a specified payment request.
-     *
-     * @async
-     * @param {Object} input - The input object containing payment request details.
-     * @param {string} input.paymentRequestId - The unique identifier for the payment request.
-     * @param {number} input.amount - The amount to be paid in the transaction, decimals in USD (eg. 12.45)
-     * @param {PaymentNetwork} input.network - The Ethereum network to be used for the transaction
-     * @param {string} input.paymentTokenAddress - The Ethereum address of the ERC20 token used for payment.
-     * @param {boolean} [validateChecksum=false] - Optional flag to validate the EIP-55 checksum of the paymentTokenAddress.
-     * If set to true, the function will throw an error if the checksum is invalid. Default is false.
-     * @returns {Promise<Object>} A Promise that resolves to an object containing the Web3 payment parameters.
-     * @throws {Error} If the validateChecksum flag is true and the paymentTokenAddress has an invalid EIP-55 checksum.
-     */
+    transactionPrice(paymentAmount: number): Promise<number>;
     getWeb3PaymentParams(input: {
-        paymentRequestId: string;
-        amount: number;
-        network: PaymentNetwork;
+        paymentRequest: PaymentRequest;
         paymentTokenAddress: string;
-    }, validateChecksum?: boolean): Promise<GetSpritzPayParams_spritzPayParams>;
+    }): Promise<Web3PaymentParams>;
 }
 
 declare class UserService {
@@ -592,13 +654,19 @@ declare class UserService {
     getUserVerification(): Promise<UserVerification_verification>;
 }
 
+type ClientParams = {
+    environment: Environment;
+    apiKey: string;
+    integrationKey?: string;
+};
 declare class SpritzApiClient {
     private client;
     user: UserService;
     bankAccount: BankAccountService;
     paymentRequest: PaymentRequestService;
-    static initialize(environment: Environment, apiKey: string): SpritzApiClient;
+    payment: PaymentService;
+    static initialize({ environment, apiKey, integrationKey }: ClientParams): SpritzApiClient;
     private init;
 }
 
-export { AccountProvider, BankAccountFragment, BankAccountFragment_bankAccountDetails, BankAccountFragment_bankAccountDetails_CanadianBankAccountDetails, BankAccountFragment_bankAccountDetails_USBankAccountDetails, BankAccountFragment_institution, BankAccountSubType, BankAccountType, CreateDirectPaymentInput, CreatePaymentRequestInput, CurrentUser, CurrentUser_me, DirectPaymentStatus, Environment, GetSpritzPayParams, GetSpritzPayParamsVariables, GetSpritzPayParams_spritzPayParams, ModuleStatus, PayableAccountFragment, PayableAccountFragment_BankAccount, PayableAccountFragment_BankAccount_bankAccountDetails, PayableAccountFragment_BankAccount_bankAccountDetails_CanadianBankAccountDetails, PayableAccountFragment_BankAccount_bankAccountDetails_USBankAccountDetails, PayableAccountFragment_BankAccount_institution, PayableAccountFragment_Bill, PayableAccountFragment_Bill_institution, PayableAccountType, PaymentNetwork, PaymentRequestFragment, SpritzApiClient, TokenBalanceFragment, USBankAccountInput, UserBankAccounts, UserBankAccounts_userBankAccounts, UserBankAccounts_userBankAccounts_bankAccountDetails, UserBankAccounts_userBankAccounts_bankAccountDetails_CanadianBankAccountDetails, UserBankAccounts_userBankAccounts_bankAccountDetails_USBankAccountDetails, UserBankAccounts_userBankAccounts_institution, UserFragment, UserPayableAccounts, UserPayableAccounts_payableAccounts, UserPayableAccounts_payableAccounts_BankAccount, UserPayableAccounts_payableAccounts_BankAccount_bankAccountDetails, UserPayableAccounts_payableAccounts_BankAccount_bankAccountDetails_CanadianBankAccountDetails, UserPayableAccounts_payableAccounts_BankAccount_bankAccountDetails_USBankAccountDetails, UserPayableAccounts_payableAccounts_BankAccount_institution, UserPayableAccounts_payableAccounts_Bill, UserPayableAccounts_payableAccounts_Bill_institution, UserVerification, UserVerification_verification, UserVerification_verification_identity, UserVerification_verification_identity_user, WalletTokenBalances, WalletTokenBalancesVariables, WalletTokenBalances_tokenBalances };
+export { AccountPayments, AccountPaymentsVariables, AccountPayments_paymentsForAccount, AccountProvider, BankAccountFragment, BankAccountFragment_bankAccountDetails, BankAccountFragment_bankAccountDetails_CanadianBankAccountDetails, BankAccountFragment_bankAccountDetails_USBankAccountDetails, BankAccountFragment_institution, BankAccountSubType, BankAccountType, CreateDirectPaymentInput, CreatePaymentRequestInput, CurrentUser, CurrentUser_me, DirectPaymentStatus, Environment, GetSpritzPayParams, GetSpritzPayParamsVariables, GetSpritzPayParams_spritzPayParams, ModuleStatus, PayableAccountFragment, PayableAccountFragment_BankAccount, PayableAccountFragment_BankAccount_bankAccountDetails, PayableAccountFragment_BankAccount_bankAccountDetails_CanadianBankAccountDetails, PayableAccountFragment_BankAccount_bankAccountDetails_USBankAccountDetails, PayableAccountFragment_BankAccount_institution, PayableAccountFragment_Bill, PayableAccountFragment_Bill_institution, PayableAccountType, PaymentFragment, PaymentNetwork, PaymentRequestFragment, PaymentRequestPayment, PaymentRequestPaymentVariables, PaymentRequestPayment_paymentForPaymentRequest, PaymentStatus, SpritzApiClient, TokenBalanceFragment, TransactionPrice, TransactionPriceVariables, USBankAccountInput, UserBankAccounts, UserBankAccounts_userBankAccounts, UserBankAccounts_userBankAccounts_bankAccountDetails, UserBankAccounts_userBankAccounts_bankAccountDetails_CanadianBankAccountDetails, UserBankAccounts_userBankAccounts_bankAccountDetails_USBankAccountDetails, UserBankAccounts_userBankAccounts_institution, UserFragment, UserPayableAccounts, UserPayableAccounts_payableAccounts, UserPayableAccounts_payableAccounts_BankAccount, UserPayableAccounts_payableAccounts_BankAccount_bankAccountDetails, UserPayableAccounts_payableAccounts_BankAccount_bankAccountDetails_CanadianBankAccountDetails, UserPayableAccounts_payableAccounts_BankAccount_bankAccountDetails_USBankAccountDetails, UserPayableAccounts_payableAccounts_BankAccount_institution, UserPayableAccounts_payableAccounts_Bill, UserPayableAccounts_payableAccounts_Bill_institution, UserVerification, UserVerification_verification, UserVerification_verification_identity, UserVerification_verification_identity_user, WalletTokenBalances, WalletTokenBalancesVariables, WalletTokenBalances_tokenBalances };