🐛 server: make card creation idempotent

Author: nfmelendez

.changeset/swift-pandas-reconcile.md

@@ -0,0 +1,5 @@
+---
+"@exactly/server": patch
+---
+
+🐛 make card creation idempotent

server/api/card.ts

@@ -46,6 +46,7 @@ import {
   createCard,
   getApplicationStatus,
   getCard,
+  getCards,
   getNonce,
   getPIN,
   getProcessorDetails,
@@ -431,6 +432,14 @@ function decrypt(base64Secret: string, base64Iv: string, secretKey: string): str
             },
           },
         },
+        409: {
+          description: "Conflict",
+          content: {
+            "application/json": {
+              schema: resolver(object({ code: literal("card limit reached") }), { errorMode: "ignore" }),
+            },
+          },
+        },
       },
     }),
     async (c) => {
@@ -453,6 +462,7 @@ function decrypt(base64Secret: string, base64Iv: string, secretKey: string): str
           setUser({ id: account });
 
           if (!credential.pandaId) return c.json({ code: "no panda" }, 403);
+          const pandaId = credential.pandaId;
 
           let isUpgradeFromPlatinum = credential.cards.some(
             ({ status, productId }) => status === "DELETED" && productId === PLATINUM_PRODUCT_ID,
@@ -480,26 +490,44 @@ function decrypt(base64Secret: string, base64Iv: string, secretKey: string): str
           }
           if (cardCount > 0) return c.json({ code: "already created" }, 400);
           try {
-            const kyc = await getApplicationStatus(credential.pandaId);
+            const kyc = await getApplicationStatus(pandaId);
             if (kyc.applicationStatus !== "approved") {
               return c.json({ code: "kyc not approved" }, 403);
             }
-            const card = await createCard(
-              credential.pandaId,
-              SIGNATURE_PRODUCT_ID,
-              await getAccount(credentialId, "cardLimit")
-                .then((persona) =>
-                  persona?.attributes.fields.card_limit_usd?.value == null
-                    ? undefined
-                    : persona.attributes.fields.card_limit_usd.value * 100,
-                )
-                .catch((error: unknown): undefined => {
-                  captureException(error, {
-                    level: "error",
-                    contexts: { details: { credentialId, scope: "cardLimit" } },
+            const card = await getCards(pandaId)
+              .then((pandaCards) => pandaCards.find(({ status }) => status === "active"))
+              .then(async (orphan) => {
+                if (orphan) {
+                  captureException(new Error("orphan card adopted"), {
+                    level: "warning",
+                    fingerprint: ["orphan-card-adopted"],
+                    extra: {
+                      credentialId,
+                      pandaId,
+                      cardId: orphan.id,
+                    },
                   });
-                }),
-            );
+                  return orphan;
+                } else {
+                  return createCard(
+                    pandaId,
+                    SIGNATURE_PRODUCT_ID,
+                    await getAccount(credentialId, "cardLimit")
+                      .then((persona) =>
+                        persona?.attributes.fields.card_limit_usd?.value == null
+                          ? undefined
+                          : persona.attributes.fields.card_limit_usd.value * 100,
+                      )
+                      .catch((error: unknown): undefined => {
+                        captureException(error, {
+                          level: "error",
+                          contexts: { details: { credentialId, scope: "cardLimit" } },
+                        });
+                      }),
+                  );
+                }
+              });
+
             let mode = 0;
             try {
               if (await autoCredit(account)) mode = 1;
@@ -551,6 +579,18 @@ function decrypt(base64Secret: string, base64Iv: string, secretKey: string): str
               200,
             );
           } catch (error) {
+            if (
+              error instanceof ServiceError &&
+              error.status === 400 &&
+              error.message.includes("maximum number of cards allowed")
+            ) {
+              captureException(error, {
+                level: "warning",
+                fingerprint: ["card-limit-reached"],
+                extra: { credentialId, pandaId },
+              });
+              return c.json({ code: "card limit reached" }, 409);
+            }
             const issue = noUser(error);
             if (!issue) throw error;
             const hasCardHistory = credential.cards.length > 0;
@@ -567,7 +607,7 @@ function decrypt(base64Secret: string, base64Iv: string, secretKey: string): str
                   extra: {
                     credentialId,
                     hasCardHistory,
-                    pandaId: credential.pandaId,
+                    pandaId,
                     statuses: credential.cards.map(({ status }) => status),
                     userIssue: issue.type,
                   },

server/test/api/card.test.ts

@@ -134,6 +134,7 @@ describe("authenticated", () => {
   afterEach(() => vi.resetAllMocks());
   beforeEach(() => {
     vi.spyOn(persona, "getAccount").mockResolvedValue(undefined); // eslint-disable-line unicorn/no-useless-undefined
+    vi.spyOn(panda, "getCards").mockResolvedValue([]);
   });
 
   it("returns 404 card not found", async () => {
@@ -532,6 +533,232 @@ describe("authenticated", () => {
     expect(captureException).not.toHaveBeenCalled();
   });
 
+  it("returns 409 card limit reached when panda rejects with the max cards error", async () => {
+    const credentialId = "card-limit-reached";
+    await database.insert(credentials).values({
+      id: credentialId,
+      publicKey: new Uint8Array(),
+      account: padHex("0x4042", { size: 20 }),
+      factory: inject("ExaAccountFactory"),
+      pandaId: credentialId,
+    });
+
+    vi.spyOn(panda, "getApplicationStatus").mockResolvedValueOnce({ id: "pandaId", applicationStatus: "approved" });
+    const createCard = vi
+      .spyOn(panda, "createCard")
+      .mockRejectedValueOnce(
+        new ServiceError(
+          "Panda",
+          400,
+          '{"message":"User has reached the maximum number of cards allowed: 3","error":"BadRequestError","statusCode":400}',
+        ),
+      );
+
+    const response = await appClient.index.$post({ header: { "test-credential-id": credentialId } });
+
+    expect(response.status).toBe(409);
+    await expect(response.json()).resolves.toStrictEqual({ code: "card limit reached" });
+    expect(createCard).toHaveBeenCalledOnce();
+    expect(captureException).toHaveBeenCalledExactlyOnceWith(expect.any(ServiceError) as ServiceError, {
+      level: "warning",
+      fingerprint: ["card-limit-reached"],
+      extra: { credentialId, pandaId: credentialId },
+    });
+    const persisted = await database.query.cards.findFirst({ where: eq(cards.credentialId, credentialId) });
+    expect(persisted).toBeUndefined();
+  });
+
+  it("throws when createCard fails with an unrelated 400 error", async () => {
+    const credentialId = "card-bad-request";
+    await database.insert(credentials).values({
+      id: credentialId,
+      publicKey: new Uint8Array(),
+      account: padHex("0x4043", { size: 20 }),
+      factory: inject("ExaAccountFactory"),
+      pandaId: credentialId,
+    });
+
+    vi.spyOn(panda, "getApplicationStatus").mockResolvedValueOnce({ id: "pandaId", applicationStatus: "approved" });
+    const createCard = vi
+      .spyOn(panda, "createCard")
+      .mockRejectedValueOnce(
+        new ServiceError("Panda", 400, '{"message":"Invalid request","error":"BadRequestError","statusCode":400}'),
+      );
+
+    const response = await appClient.index.$post({ header: { "test-credential-id": credentialId } });
+
+    expect(response.status).toBe(500);
+    expect(createCard).toHaveBeenCalledOnce();
+    expect(captureException).not.toHaveBeenCalled();
+  });
+
+  it("adopts an existing active panda card instead of creating a duplicate", async () => {
+    const credentialId = "orphan-adopt";
+    const orphanId = "00000000-0000-4000-8000-0000000000aa";
+    await database.insert(credentials).values({
+      id: credentialId,
+      publicKey: new Uint8Array(),
+      account: padHex("0x4051", { size: 20 }),
+      factory: inject("ExaAccountFactory"),
+      pandaId: credentialId,
+    });
+
+    vi.spyOn(panda, "getApplicationStatus").mockResolvedValueOnce({ id: "pandaId", applicationStatus: "approved" });
+    vi.spyOn(panda, "getCards").mockResolvedValueOnce([
+      { id: orphanId, status: "active", last4: "4242", expirationMonth: "9", expirationYear: "2029" },
+    ]);
+    const createCard = vi.spyOn(panda, "createCard");
+    const getAccount = vi.spyOn(persona, "getAccount");
+
+    const response = await appClient.index.$post({ header: { "test-credential-id": credentialId } });
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toStrictEqual({
+      status: "ACTIVE",
+      lastFour: "4242",
+      cardId: orphanId,
+      productId: SIGNATURE_PRODUCT_ID,
+    });
+    expect(createCard).not.toHaveBeenCalled();
+    expect(getAccount).not.toHaveBeenCalled();
+    const adopted = await database.query.cards.findFirst({
+      columns: { id: true, status: true, lastFour: true, productId: true },
+      where: eq(cards.credentialId, credentialId),
+    });
+    expect(adopted).toStrictEqual({
+      id: orphanId,
+      status: "ACTIVE",
+      lastFour: "4242",
+      productId: SIGNATURE_PRODUCT_ID,
+    });
+    expect(captureException).toHaveBeenCalledExactlyOnceWith(expect.any(Error) as Error, {
+      level: "warning",
+      fingerprint: ["orphan-card-adopted"],
+      extra: { credentialId, pandaId: credentialId, cardId: orphanId },
+    });
+  });
+
+  it("adopts only the first active card when panda has multiple orphans", async () => {
+    const credentialId = "orphan-multi";
+    const first = "00000000-0000-4000-8000-0000000000c1";
+    const second = "00000000-0000-4000-8000-0000000000c2";
+    await database.insert(credentials).values({
+      id: credentialId,
+      publicKey: new Uint8Array(),
+      account: padHex("0x4053", { size: 20 }),
+      factory: inject("ExaAccountFactory"),
+      pandaId: credentialId,
+    });
+
+    vi.spyOn(panda, "getApplicationStatus").mockResolvedValueOnce({ id: "pandaId", applicationStatus: "approved" });
+    vi.spyOn(panda, "getCards").mockResolvedValueOnce([
+      { id: first, status: "active", last4: "4444", expirationMonth: "9", expirationYear: "2029" },
+      { id: second, status: "active", last4: "5555", expirationMonth: "9", expirationYear: "2029" },
+      {
+        id: "00000000-0000-4000-8000-0000000000c3",
+        status: "canceled",
+        last4: "6666",
+        expirationMonth: "9",
+        expirationYear: "2029",
+      },
+    ]);
+    const createCard = vi.spyOn(panda, "createCard");
+
+    const response = await appClient.index.$post({ header: { "test-credential-id": credentialId } });
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toStrictEqual({
+      status: "ACTIVE",
+      lastFour: "4444",
+      cardId: first,
+      productId: SIGNATURE_PRODUCT_ID,
+    });
+    expect(createCard).not.toHaveBeenCalled();
+    const persisted = await database.query.cards.findMany({
+      columns: { id: true },
+      where: eq(cards.credentialId, credentialId),
+    });
+    expect(persisted).toStrictEqual([{ id: first }]);
+    expect(captureException).toHaveBeenCalledExactlyOnceWith(expect.any(Error) as Error, {
+      level: "warning",
+      fingerprint: ["orphan-card-adopted"],
+      extra: { credentialId, pandaId: credentialId, cardId: first },
+    });
+  });
+
+  it("creates a new card when panda has only non-active cards", async () => {
+    const credentialId = "orphan-nonactive";
+    const createdId = "00000000-0000-4000-8000-0000000000bb";
+    await database.insert(credentials).values({
+      id: credentialId,
+      publicKey: new Uint8Array(),
+      account: padHex("0x4052", { size: 20 }),
+      factory: inject("ExaAccountFactory"),
+      pandaId: credentialId,
+    });
+
+    vi.spyOn(panda, "getApplicationStatus").mockResolvedValueOnce({ id: "pandaId", applicationStatus: "approved" });
+    vi.spyOn(panda, "getCards").mockResolvedValueOnce([
+      {
+        id: "00000000-0000-4000-8000-0000000000b1",
+        status: "canceled",
+        last4: "1111",
+        expirationMonth: "9",
+        expirationYear: "2029",
+      },
+      {
+        id: "00000000-0000-4000-8000-0000000000b2",
+        status: "locked",
+        last4: "2222",
+        expirationMonth: "9",
+        expirationYear: "2029",
+      },
+    ]);
+    const createCard = vi
+      .spyOn(panda, "createCard")
+      .mockResolvedValueOnce({ ...cardTemplate, id: createdId, last4: "3333" });
+
+    const response = await appClient.index.$post({ header: { "test-credential-id": credentialId } });
+
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toStrictEqual({
+      status: "ACTIVE",
+      lastFour: "3333",
+      cardId: createdId,
+      productId: SIGNATURE_PRODUCT_ID,
+    });
+    expect(createCard).toHaveBeenCalledOnce();
+    expect(captureException).not.toHaveBeenCalled();
+    const created = await database.query.cards.findFirst({
+      columns: { id: true },
+      where: eq(cards.credentialId, credentialId),
+    });
+    expect(created).toStrictEqual({ id: createdId });
+  });
+
+  it("throws and does not create a card when getCards fails", async () => {
+    const credentialId = "orphan-list-fail";
+    await database.insert(credentials).values({
+      id: credentialId,
+      publicKey: new Uint8Array(),
+      account: padHex("0x4054", { size: 20 }),
+      factory: inject("ExaAccountFactory"),
+      pandaId: credentialId,
+    });
+
+    vi.spyOn(panda, "getApplicationStatus").mockResolvedValueOnce({ id: "pandaId", applicationStatus: "approved" });
+    vi.spyOn(panda, "getCards").mockRejectedValueOnce(new ServiceError("Panda", 500, "internal error"));
+    const createCard = vi.spyOn(panda, "createCard");
+
+    const response = await appClient.index.$post({ header: { "test-credential-id": credentialId } });
+
+    expect(response.status).toBe(500);
+    expect(createCard).not.toHaveBeenCalled();
+    expect(captureException).not.toHaveBeenCalled();
+    const persisted = await database.query.cards.findFirst({ where: eq(cards.credentialId, credentialId) });
+    expect(persisted).toBeUndefined();
+  });
+
   it("returns 403 no panda when getApplicationStatus reports user not found", async () => {
     const credentialId = "stale-panda-id";
     await database.insert(credentials).values({

server/test/e2e.ts

@@ -85,6 +85,7 @@ vi.mock("../utils/panda", async (importOriginal: () => Promise<typeof panda>) =>
       return Promise.resolve({ id });
     }),
     getCard: vi.fn().mockImplementation((cardId: string) => Promise.resolve(cards.get(cardId))),
+    getCards: vi.fn().mockResolvedValue([]),
     getPIN: vi.fn().mockResolvedValue({ pin: null }),
     getProcessorDetails: vi
       .fn()