Merge pull request #334 from stripe/lm-payment-updates

feat(firestore-stripe-web-sdk): Added onCurrentUserPaymentUpdate() API

Author: lahirumaramba

firestore-stripe-web-sdk/etc/firestore-stripe-payments.api.md

@@ -110,6 +110,9 @@ export interface LineItemSessionCreateParams extends CommonSessionCreateParams {
     line_items: LineItemParams[];
 }
 
+// @public
+export function onCurrentUserPaymentUpdate(payments: StripePayments, onUpdate: (snapshot: PaymentSnapshot) => void, onError?: (error: StripePaymentsError) => void): () => void;
+
 // @public
 export function onCurrentUserSubscriptionUpdate(payments: StripePayments, onUpdate: (snapshot: SubscriptionSnapshot) => void, onError?: (error: StripePaymentsError) => void): () => void;
 
@@ -138,9 +141,23 @@ export interface Payment {
     readonly uid: string;
 }
 
+// @public
+export type PaymentChangeType = "added" | "modified" | "removed";
+
 // @public
 export type PaymentMethodType = "card" | "acss_debit" | "afterpay_clearpay" | "alipay" | "bacs_debit" | "bancontact" | "boleto" | "eps" | "fpx" | "giropay" | "grabpay" | "ideal" | "klarna" | "oxxo" | "p24" | "sepa_debit" | "sofort" | "wechat_pay";
 
+// @public
+export interface PaymentSnapshot {
+    changes: Array<{
+        type: PaymentChangeType;
+        payment: Payment;
+    }>;
+    empty: boolean;
+    payments: Payment[];
+    size: number;
+}
+
 // @public
 export type PaymentStatus = "requires_payment_method" | "requires_confirmation" | "requires_action" | "processing" | "requires_capture" | "cancelled" | "succeeded";
 

firestore-stripe-web-sdk/src/index.ts

@@ -41,9 +41,12 @@ export {
 export {
   GetPaymentsOptions,
   Payment,
+  PaymentChangeType,
+  PaymentSnapshot,
   PaymentStatus,
   getCurrentUserPayment,
   getCurrentUserPayments,
+  onCurrentUserPaymentUpdate,
 } from "./payment";
 
 export {

firestore-stripe-web-sdk/src/payment.ts

@@ -17,23 +17,27 @@
 import { FirebaseApp } from "@firebase/app";
 import {
   collection,
+  CollectionReference,
   doc,
+  DocumentChange,
   DocumentData,
   DocumentReference,
   DocumentSnapshot,
   Firestore,
   FirestoreDataConverter,
+  FirestoreError,
   getDoc,
   getDocs,
   getFirestore,
+  onSnapshot,
   query,
   Query,
   QueryDocumentSnapshot,
   QuerySnapshot,
   where,
 } from "@firebase/firestore";
 import { StripePayments, StripePaymentsError } from "./init";
-import { getCurrentUser } from "./user";
+import { getCurrentUser, getCurrentUserSync } from "./user";
 import { checkNonEmptyArray, checkNonEmptyString } from "./utils";
 
 /**
@@ -176,6 +180,68 @@ export function getCurrentUserPayments(
   });
 }
 
+/**
+ * Different types of changes that may occur on a payment object.
+ */
+export type PaymentChangeType = "added" | "modified" | "removed";
+
+/**
+ * Represents the current state of a set of payments owned by a user.
+ */
+export interface PaymentSnapshot {
+  /**
+   * A list of all currently available payments ordered by the payment ID. Empty
+   * if no payments are available.
+   */
+  payments: Payment[];
+
+  /**
+   * The list of changes in the payments since the last snapshot.
+   */
+  changes: Array<{
+    type: PaymentChangeType;
+    payment: Payment;
+  }>;
+
+  /**
+   * Number of currently available payments. This is same as the length of the
+   * `payments` array in the snapshot.
+   */
+  size: number;
+
+  /**
+   * True if there are no payments available. False whenever at least one payment is
+   * present. When True, the `payments` array is empty, and the `size` is 0.
+   */
+  empty: boolean;
+}
+
+/**
+ * Registers a listener to receive payment update events for the currently signed in
+ * user. If the user is not signed in throws an `unauthenticated` error, and no listener is
+ * registered.
+ *
+ * Upon successful registration, the `onUpdate` callback will fire once with
+ * the current state of all the payments. From then onwards, each update to a payment
+ * will fire the `onUpdate` callback with the latest state of the payments.
+ *
+ * @param payments - A valid {@link StripePayments} object.
+ * @param onUpdate - A callback that will fire whenever the current user's payments
+ *   are updated.
+ * @param onError - A callback that will fire whenever an error occurs while listening to
+ *   payment updates.
+ * @returns A function that can be called to cancel and unregister the listener.
+ */
+export function onCurrentUserPaymentUpdate(
+  payments: StripePayments,
+  onUpdate: (snapshot: PaymentSnapshot) => void,
+  onError?: (error: StripePaymentsError) => void
+): () => void {
+  const uid: string = getCurrentUserSync(payments);
+  const dao: PaymentDAO = getOrInitPaymentDAO(payments);
+  return dao.onPaymentUpdate(uid, onUpdate, onError);
+}
+
 function getStatusAsArray(
   status: PaymentStatus | PaymentStatus[]
 ): PaymentStatus[] {
@@ -199,6 +265,11 @@ export interface PaymentDAO {
     uid: string,
     options?: { status?: PaymentStatus[] }
   ): Promise<Payment[]>;
+  onPaymentUpdate(
+    uid: string,
+    onUpdate: (snapshot: PaymentSnapshot) => void,
+    onError?: (error: StripePaymentsError) => void
+  ): () => void;
 }
 
 const PAYMENT_CONVERTER: FirestoreDataConverter<Payment> = {
@@ -272,6 +343,51 @@ class FirestorePaymentDAO implements PaymentDAO {
     return payments;
   }
 
+  public onPaymentUpdate(
+    uid: string,
+    onUpdate: (snapshot: PaymentSnapshot) => void,
+    onError?: (error: StripePaymentsError) => void
+  ): () => void {
+    const payments: CollectionReference<Payment> = collection(
+      this.firestore,
+      this.customersCollection,
+      uid,
+      PAYMENTS_COLLECTION
+    ).withConverter(PAYMENT_CONVERTER);
+    return onSnapshot(
+      payments,
+      (querySnap: QuerySnapshot<Payment>) => {
+        const snapshot: PaymentSnapshot = {
+          payments: [],
+          changes: [],
+          size: querySnap.size,
+          empty: querySnap.empty,
+        };
+        querySnap.forEach((snap: QueryDocumentSnapshot<Payment>) => {
+          snapshot.payments.push(snap.data());
+        });
+        querySnap.docChanges().forEach((change: DocumentChange<Payment>) => {
+          snapshot.changes.push({
+            type: change.type,
+            payment: change.doc.data(),
+          });
+        });
+
+        onUpdate(snapshot);
+      },
+      (err: FirestoreError) => {
+        if (onError) {
+          const arg: StripePaymentsError = new StripePaymentsError(
+            "internal",
+            `Error while listening to database updates: ${err.message}`,
+            err
+          );
+          onError(arg);
+        }
+      }
+    );
+  }
+
   private async getPaymentSnapshotIfExists(
     uid: string,
     paymentId: string