@spritz-finance/api-client 0.1.6 → 0.2.0

package/README.md

@@ -63,6 +63,11 @@ A Typescript library for interacting with the Spritz Finance API
 - [Payments](#payments)
   - [Retrieve the payment for a payment request](#retrieve-the-payment-for-a-payment-request)
   - [Retrieve all payments for an account](#retrieve-all-payments-for-an-account)
+- [Webhooks](#webhooks)
+  - [Supported webhook events](#supported-webhook-events)
+    - [Account Events](#account-events)
+    - [Payment Events](#payment-events)
+  - [Setting up webhooks](#setting-up-webhooks)
 
 ## Interacting with the Spritz API
 
@@ -630,3 +635,50 @@ const payments = await client.payment.listForAccount(account.id)
     },
 ]
 ```
+
+## Webhooks
+
+Instead of making a request to get information, webhooks send information to your specified endpoint as soon as an event occurs. Spritz's integration offers a variety of webhook events that can be crucial for maintaining data integrity and responsiveness in applications. Let's dive into how you can best utilize these.
+
+### Supported webhook events
+
+Spritz currently supports the following webhook events:
+
+#### Account Events
+
+- `account.created`: Triggered when a new account is created.
+- `account.updated`: Triggered when details of an account are updated.
+- `account.deleted`: Triggered when an account is deleted.
+
+#### Payment Events
+
+- `payment.created`: Triggered when a new payment is initiated.
+- `payment.updated`: Triggered when details of a payment are updated.
+- `payment.completed`: Triggered when a payment is successfully completed.
+- `payment.refunded`: Triggered when a payment is refunded.
+
+These events allow you to respond to changes in the account and payments for a user.
+
+### Setting up webhooks
+
+To set up a webhook with Spritz, you'll need to provide:
+
+1. **URL**: The endpoint URL where Spritz will send the webhook data.
+2. **Events**: The specific events you want to listen for.
+
+```typescript
+const webhook = await client.webhook.create({
+  url: 'https://my.webhook.url/spritz',
+  events: ['account.created', 'account.updated', 'account.deleted'],
+})
+```
+
+Upon receiving a webhook, your server will get a payload with the following structure:
+
+```json
+{
+  "userId": "user-id-here",
+  "id": "resource-id-here",
+  "eventName": "name-of-the-event-here"
+}
+```

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

@@ -1,4 +1,3 @@
-import { AxiosInstance } from 'axios';
 import { DocumentNode } from 'graphql';
 
 declare enum Environment {
@@ -978,15 +977,61 @@ interface RenameBankAccount_renamePayableAccount_BankAccount {
     institution: RenameBankAccount_renamePayableAccount_BankAccount_institution | null;
 }
 
+type Headers = Record<string, string | null | undefined>;
+
 interface QueryParams<V = any> {
     query: DocumentNode;
-    variables?: V;
+    variables?: V | undefined;
 }
-declare class GraphClient {
-    client: AxiosInstance;
-    baseClient: AxiosInstance;
-    constructor(environment: Environment, apiKey: string, integrationKey?: string);
+type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+declare class SpritzClient {
+    private baseGraphURL;
+    private baseRestURL;
+    private timeout;
+    private apiKey;
+    private integrationKey;
+    constructor({ environment, timeout, // 5 minutes
+    apiKey, integrationKey, }: {
+        environment: Environment;
+        timeout?: number | undefined;
+        integrationKey: string | undefined;
+        apiKey: string | undefined;
+    });
     query<Q = any, V = any>({ query, variables }: QueryParams<V>): Promise<Q>;
+    request<Response, Request extends Record<string, any> = Record<string, any>>({ method, path, body, }: {
+        method: HTTPMethod;
+        path: string;
+        body?: Request | undefined;
+    }): Promise<Response>;
+    sendQuery<V = any>({ query: documentNodeQuery, variables: inputVariables, }: QueryParams<V>): Promise<{
+        response: Response;
+        controller: AbortController;
+        headers: {
+            traceId: string | null;
+            requestId: string | null;
+        };
+    }>;
+    sendRequest({ method, path, body, }: {
+        method: HTTPMethod;
+        path: string;
+        body: Record<string, any> | undefined;
+    }): Promise<{
+        response: Response;
+        controller: AbortController;
+        headers: {
+            traceId: string | null;
+            requestId: string | null;
+        };
+    }>;
+    private sendHTTPRequest;
+    private getResponseHeaders;
+    private fetchWithTimeout;
+    private buildGraphRequest;
+    private buildRestRequest;
+    private defaultHeaders;
+    private calculateContentLength;
+    protected authHeaders(): Headers;
+    private makeStatusError;
 }
 
 type CreateInputMapping$1 = {
@@ -1001,7 +1046,7 @@ type CreateMutationMapping$1 = {
 };
 declare class BankAccountService {
     private client;
-    constructor(client: GraphClient);
+    constructor(client: SpritzClient);
     list(): Promise<UserBankAccounts_bankAccounts[]>;
     rename(accountId: string, name: string): Promise<RenameBankAccount_renamePayableAccount_BankAccount>;
     delete(accountId: string): Promise<DeletePayableAccount_deletePayableAccount_BankAccount>;
@@ -1050,7 +1095,7 @@ interface CreateUSBill_addUSBill {
 
 declare class BillService {
     private client;
-    constructor(client: GraphClient);
+    constructor(client: SpritzClient);
     list(): Promise<UserBills_bills[]>;
     rename(accountId: string, name: string): Promise<RenameBankAccount_renamePayableAccount_Bill>;
     delete(accountId: string): Promise<DeletePayableAccount_deletePayableAccount_Bill>;
@@ -1059,14 +1104,14 @@ declare class BillService {
 
 declare class InstitutionService {
     private client;
-    constructor(client: GraphClient);
+    constructor(client: SpritzClient);
     popularUSBillInstitutions(type?: BillType): Promise<PopularBillInstitutions_popularUSBillInstitutions[]>;
     searchUSBillInstitutions(searchTerm: string, type?: BillType): Promise<SearchUSBillInstitutions_searchUSBillInstitutions[]>;
 }
 
 declare class PaymentService {
     private client;
-    constructor(client: GraphClient);
+    constructor(client: SpritzClient);
     listForAccount(accountId: string): Promise<AccountPayments_paymentsForAccount[]>;
     getForPaymentRequest(paymentRequestId: string): Promise<PaymentRequestPayment_paymentForPaymentRequest | null>;
 }
@@ -1103,16 +1148,15 @@ interface CreatePaymentRequestInput {
 }
 
 type PaymentRequest = CreatePaymentRequest_createDirectPayment;
-type Web3PaymentParams = GetSpritzPayParams_spritzPayParams;
 declare class PaymentRequestService {
     private client;
-    constructor(client: GraphClient);
+    constructor(client: SpritzClient);
     create(input: CreatePaymentRequestInput): Promise<CreatePaymentRequest_createDirectPayment>;
     transactionPrice(paymentAmount: number): Promise<number>;
     getWeb3PaymentParams(input: {
         paymentRequest: PaymentRequest;
         paymentTokenAddress: string;
-    }): Promise<Web3PaymentParams>;
+    }): Promise<GetSpritzPayParams_spritzPayParams>;
 }
 
 interface CreateUserResponse {
@@ -1120,14 +1164,14 @@ interface CreateUserResponse {
     email: string;
     apiKey: string;
 }
-interface CreateUserArgs {
+interface CreateUserParams {
     email: string;
 }
 declare class UserService {
     private client;
-    constructor(client: GraphClient);
-    createUser(args: CreateUserArgs): Promise<CreateUserResponse>;
-    create(args: CreateUserArgs): Promise<CreateUserResponse>;
+    constructor(client: SpritzClient);
+    createUser(args: CreateUserParams): Promise<CreateUserResponse>;
+    create(args: CreateUserParams): Promise<CreateUserResponse>;
     getCurrentUser(): Promise<CurrentUser_me>;
     getUserVerification(): Promise<UserVerification_verification | null>;
 }
@@ -1179,20 +1223,59 @@ type CreateMutationMapping = {
 };
 declare class VirtualCardService {
     private client;
-    constructor(client: GraphClient);
+    constructor(client: SpritzClient);
     fetch(): Promise<UserVirtualDebitCard_virtualDebitCard | null>;
     create<T extends VirtualCardType>(type: T, input: CreateInputMapping[T]): Promise<NonNullable<CreateMutationMapping[T]["query"][keyof CreateMutationMapping[T]["query"]]> | null>;
 }
 
-type ClientParams = {
-    environment: Environment;
+declare const EVENTS: readonly ["account.created", "account.updated", "account.deleted", "payment.created", "payment.updated", "payment.completed", "payment.refunded"];
+type WebhookEvent = (typeof EVENTS)[number];
+type IntegratorWebhook = {
+    id: string;
+    integratorId: string;
+    failureCount: number;
+    events: string[];
+    url: string;
+    createdAt: string;
+};
+type CreateWebhookParams = {
+    url: string;
+    events: WebhookEvent[];
+};
+declare class WebhookService {
+    private client;
+    constructor(client: SpritzClient);
+    create(args: CreateWebhookParams): Promise<IntegratorWebhook>;
+}
+
+type ClientOptions = {
+    /**
+     * Defaults to Environment.Staging.
+     */
+    environment?: Environment;
     apiKey?: string;
     integrationKey?: string;
+    /**
+     * The client will wait up to a specified duration (in milliseconds)
+     * for a response from the server before considering a single request as timed out.
+     *
+     * Please be aware that requests are automatically retried by default.
+     * This means that in some situations, the actual wait time could exceed the set timeout
+     * before the process is either completed or terminated.
+     */
+    timeout?: number;
+    /**
+     * For security reasons, using this library on the client-side is not recommended
+     * because it could potentially reveal your confidential Integrator Key.
+     * Please enable this option to 'true' only if you're fully aware of the risks and
+     * have implemented the necessary protective measures.
+     */
+    dangerouslyAllowBrowser?: boolean;
 };
 declare class SpritzApiClient {
+    private environment;
     private apiKey;
     private integrationKey;
-    private environment;
     private client;
     user: UserService;
     bankAccount: BankAccountService;
@@ -1201,8 +1284,9 @@ declare class SpritzApiClient {
     virtualCard: VirtualCardService;
     bill: BillService;
     institution: InstitutionService;
-    constructor(apiKey: string, integrationKey: string, environment: Environment);
-    static initialize({ environment, apiKey, integrationKey }: ClientParams): SpritzApiClient;
+    webhook: WebhookService;
+    constructor(environment: Environment, apiKey?: string, integrationKey?: string, dangerouslyAllowBrowser?: boolean);
+    static initialize({ environment, apiKey, integrationKey, dangerouslyAllowBrowser, }: ClientOptions): SpritzApiClient;
     private init;
     setApiKey(_apiKey: string): this;
 }