@gr4vy/sdk 2.1.2 → 2.1.3

package/tests/flows/transaction-lifecycle.test.ts

@@ -0,0 +1,151 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { Transaction } from "../../src/models/components";
+import {
+  APPROVING_CARD,
+  cartItem,
+  uniqueId,
+  unwrapTransaction,
+} from "../utils/fixtures";
+import { putCheckoutSessionCard } from "../utils/fields";
+import { pollUntil } from "../utils/poll";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+/**
+ * Authorises a transaction the way a real integration does: open a checkout
+ * session, tokenise a card into it via the secure-fields endpoint, then create
+ * the transaction against that session.
+ */
+const authorize = async (
+  amount: number,
+  intent: "authorize" | "capture" = "authorize"
+): Promise<Transaction> => {
+  const session = await gr4vy.checkoutSessions.create();
+  await putCheckoutSessionCard(session, APPROVING_CARD);
+  return gr4vy.transactions.create({
+    amount,
+    currency: "USD",
+    intent,
+    externalIdentifier: uniqueId("txn"),
+    cartItems: [cartItem({ unitAmount: amount })],
+    paymentMethod: { method: "checkout-session", id: session.id },
+  });
+};
+
+describe("Transaction lifecycle", () => {
+  test("authorize → capture (full) → refund (partial then full)", async () => {
+    const transaction = await authorize(5000);
+    expect(transaction.status).toBe("authorization_succeeded");
+    expect(transaction.amount).toBe(5000);
+
+    // Capture the full amount.
+    const captured = unwrapTransaction(
+      await gr4vy.transactions.capture({
+        transactionId: transaction.id,
+        transactionCaptureCreate: { amount: 5000 },
+      })
+    );
+    expect(captured.id).toBe(transaction.id);
+
+    const settled = await pollUntil(
+      () => gr4vy.transactions.get(transaction.id),
+      (t) => t.status === "capture_succeeded",
+      { description: "capture to succeed" }
+    );
+    expect(settled.capturedAmount).toBe(5000);
+
+    // Partial refund, then refund the remainder.
+    const partialRefund = await gr4vy.transactions.refunds.create(
+      { amount: 2000, reason: "partial" },
+      transaction.id
+    );
+    expect(partialRefund.amount).toBe(2000);
+    expect(["processing", "succeeded"]).toContain(partialRefund.status);
+
+    const fullRefund = await gr4vy.transactions.refunds.all.create(transaction.id);
+    expect(fullRefund.items.length).toBeGreaterThanOrEqual(1);
+
+    // Read the refund back through both refund accessors.
+    const refunds = await gr4vy.transactions.refunds.list(transaction.id);
+    expect(refunds.items.length).toBeGreaterThanOrEqual(1);
+    const firstRefundId = refunds.items[0]!.id;
+    const fetched = await gr4vy.transactions.refunds.get(
+      transaction.id,
+      firstRefundId
+    );
+    expect(fetched.id).toBe(firstRefundId);
+    const topLevel = await gr4vy.refunds.get(firstRefundId);
+    expect(topLevel.id).toBe(firstRefundId);
+  });
+
+  test("authorize → void releases the authorization", async () => {
+    const transaction = await authorize(3300);
+    expect(transaction.status).toBe("authorization_succeeded");
+
+    const voided = unwrapTransaction(
+      await gr4vy.transactions.void(transaction.id)
+    );
+    expect(voided.id).toBe(transaction.id);
+
+    const after = await pollUntil(
+      () => gr4vy.transactions.get(transaction.id),
+      (t) =>
+        t.status === "authorization_voided" ||
+        t.status === "authorization_void_pending",
+      { description: "void to be reflected" }
+    );
+    expect(["authorization_voided", "authorization_void_pending"]).toContain(
+      after.status
+    );
+  });
+
+  // `cancel` is not supported by the mock-card connector, so the call is
+  // exercised at the request level: the SDK forms the request and the API
+  // rejects it with a clear "not supported" error.
+  test("authorize → cancel is exercised at the request level", async () => {
+    const transaction = await authorize(1500);
+    await expect(gr4vy.transactions.cancel(transaction.id)).rejects.toThrow();
+  });
+
+  test("intent=capture authorizes and captures in one step", async () => {
+    const transaction = await authorize(2500, "capture");
+    expect(["capture_succeeded", "capture_pending"]).toContain(
+      transaction.status
+    );
+  });
+
+  test("exposes actions, events and settlements for a transaction", async () => {
+    const transaction = await authorize(4200, "capture");
+
+    const actions = await gr4vy.transactions.actions.list(transaction.id);
+    expect(Array.isArray(actions.items)).toBe(true);
+
+    const events = await gr4vy.transactions.events.list(transaction.id);
+    expect(events).toBeDefined();
+
+    const settlements = await gr4vy.transactions.settlements.list(transaction.id);
+    expect(settlements).toBeDefined();
+
+    // No settlement exists yet for a freshly captured transaction in the mock
+    // env, so fetching one by id is exercised at the request level.
+    await expect(
+      gr4vy.transactions.settlements.get(
+        transaction.id,
+        "00000000-0000-0000-0000-000000000000"
+      )
+    ).rejects.toThrow();
+  });
+
+  // `sync` is not supported by the mock-card connector; exercise the call shape
+  // and assert the API rejects it rather than skipping the endpoint.
+  test("sync is exercised at the request level", async () => {
+    const transaction = await authorize(1700);
+    await expect(gr4vy.transactions.sync(transaction.id)).rejects.toThrow();
+  });
+});

package/tests/processing/buyers.test.ts

@@ -0,0 +1,119 @@
+import fc from "fast-check";
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { address, billingDetails, buyer, uniqueId } from "../utils/fixtures";
+import { fcParams, name } from "../utils/arbitraries";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+describe("Buyers", () => {
+  test("create → get → list → delete", async () => {
+    const created = await gr4vy.buyers.create(buyer());
+    expect(created.id).toBeDefined();
+
+    const fetched = await gr4vy.buyers.get(created.id!);
+    expect(fetched.id).toBe(created.id);
+
+    const page = await gr4vy.buyers.list({ search: created.id });
+    expect(page).toBeDefined();
+
+    await gr4vy.buyers.delete(created.id!);
+    await expect(() => gr4vy.buyers.get(created.id!)).rejects.toThrow();
+  });
+
+  test("can be looked up by external identifier", async () => {
+    const externalIdentifier = uniqueId("buyer-ext");
+    const created = await gr4vy.buyers.create(buyer({ externalIdentifier }));
+    expect(created.externalIdentifier).toBe(externalIdentifier);
+  });
+
+  // Property: a partial update changes only the fields supplied and leaves every
+  // other field untouched. The subset of fields to mutate is itself generated,
+  // so we cover many partial-update combinations cheaply against the live API.
+  test("partial update only touches the supplied fields", async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.record(
+          {
+            displayName: name(),
+            accountNumber: fc.string({ minLength: 1, maxLength: 12 }),
+          },
+          { requiredKeys: [] }
+        ),
+        async (patch) => {
+          fc.pre(Object.keys(patch).length > 0);
+
+          const original = await gr4vy.buyers.create(
+            buyer({
+              displayName: "Original Name",
+              accountNumber: "ACC-ORIGINAL",
+              billingDetails: billingDetails({ firstName: "Keep", lastName: "Me" }),
+            })
+          );
+
+          const updated = await gr4vy.buyers.update(patch, original.id!);
+
+          // Changed fields took effect.
+          if (patch.displayName !== undefined) {
+            expect(updated.displayName).toBe(patch.displayName);
+          }
+          if (patch.accountNumber !== undefined) {
+            expect(updated.accountNumber).toBe(patch.accountNumber);
+          }
+          // Untouched fields retained their original values.
+          if (patch.displayName === undefined) {
+            expect(updated.displayName).toBe("Original Name");
+          }
+          if (patch.accountNumber === undefined) {
+            expect(updated.accountNumber).toBe("ACC-ORIGINAL");
+          }
+          // Billing details were never in the patch, so they must be preserved.
+          expect(updated.billingDetails?.firstName).toBe("Keep");
+          expect(updated.billingDetails?.lastName).toBe("Me");
+
+          await gr4vy.buyers.delete(original.id!);
+        }
+      ),
+      fcParams(4)
+    );
+  });
+
+  describe("shipping details", () => {
+    test("create → list → get → update (partial) → delete", async () => {
+      const owner = await gr4vy.buyers.create(buyer());
+
+      const created = await gr4vy.buyers.shippingDetails.create(
+        {
+          firstName: "Ship",
+          lastName: "Here",
+          emailAddress: "ship@example.com",
+          address: address({ city: "London" }),
+        },
+        owner.id!
+      );
+      expect(created.id).toBeDefined();
+
+      const list = await gr4vy.buyers.shippingDetails.list(owner.id!);
+      expect(list.items.some((s) => s.id === created.id)).toBe(true);
+
+      const fetched = await gr4vy.buyers.shippingDetails.get(owner.id!, created.id!);
+      expect(fetched.id).toBe(created.id);
+
+      // Partial update: change only the first name.
+      const updated = await gr4vy.buyers.shippingDetails.update(
+        { firstName: "Renamed" },
+        owner.id!,
+        created.id!
+      );
+      expect(updated.firstName).toBe("Renamed");
+      expect(updated.lastName).toBe("Here");
+
+      await gr4vy.buyers.shippingDetails.delete(owner.id!, created.id!);
+    });
+  });
+});

package/tests/processing/checkout-sessions.test.ts

@@ -0,0 +1,99 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { CardPaymentMethodCreate } from "../../src/models/components";
+import {
+  APPROVING_CARD,
+  cardPaymentMethod,
+  cartItem,
+} from "../utils/fixtures";
+import {
+  putCheckoutSessionCard,
+  putCheckoutSessionStoredMethod,
+} from "../utils/fields";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+describe("Checkout Sessions", () => {
+  test("should process a payment with a checkout session", async () => {
+    const checkoutSession = await gr4vy.checkoutSessions.create();
+    expect(checkoutSession.id).toBeDefined();
+
+    await putCheckoutSessionCard(checkoutSession, APPROVING_CARD);
+
+    const transaction = await gr4vy.transactions.create({
+      amount: 1299,
+      currency: "USD",
+      paymentMethod: { method: "checkout-session", id: checkoutSession.id },
+    });
+
+    expect(transaction.id).toBeDefined();
+    expect(transaction.status).toBe("authorization_succeeded");
+    expect(transaction.amount).toBe(1299);
+  });
+
+  test("should handle the error raised on missing card data", async () => {
+    const checkoutSession = await gr4vy.checkoutSessions.create();
+    expect(checkoutSession.id).toBeDefined();
+
+    const request = {
+      amount: 1299,
+      currency: "USD",
+      paymentMethod: {
+        method: "checkout-session" as const,
+        id: checkoutSession.id,
+      },
+    };
+    await expect(() => gr4vy.transactions.create(request)).rejects.toThrowError(
+      "Request failed validation"
+    );
+  });
+
+  test("should handle a stored payment method", async () => {
+    const request: CardPaymentMethodCreate = cardPaymentMethod();
+    const paymentMethod = await gr4vy.paymentMethods.create(request);
+    expect(paymentMethod.id).toBeDefined();
+
+    const checkoutSession = await gr4vy.checkoutSessions.create();
+    await putCheckoutSessionStoredMethod(
+      checkoutSession,
+      paymentMethod.id,
+      "123"
+    );
+
+    const transaction = await gr4vy.transactions.create({
+      amount: 1299,
+      currency: "USD",
+      paymentMethod: { method: "checkout-session", id: checkoutSession.id },
+    });
+
+    expect(transaction.id).toBeDefined();
+    expect(transaction.status).toBe("authorization_succeeded");
+    expect(transaction.amount).toBe(1299);
+  });
+
+  test("create → get → update (partial) → delete", async () => {
+    const created = await gr4vy.checkoutSessions.create({
+      cartItems: [cartItem()],
+      metadata: { source: "test" },
+    });
+    expect(created.id).toBeDefined();
+
+    const fetched = await gr4vy.checkoutSessions.get(created.id);
+    expect(fetched.id).toBe(created.id);
+
+    // Partial update: change only the metadata, leave the cart items.
+    const updated = await gr4vy.checkoutSessions.update(
+      { metadata: { source: "updated" } },
+      created.id
+    );
+    expect(updated.metadata?.["source"]).toBe("updated");
+
+    await gr4vy.checkoutSessions.delete(created.id);
+    await expect(() => gr4vy.checkoutSessions.get(created.id)).rejects.toThrow();
+  });
+});

package/tests/processing/digital-wallets.test.ts

@@ -0,0 +1,154 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { DigitalWallet } from "../../src/models/components";
+import { uniqueId } from "../utils/fixtures";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+const registerGoogleWallet = () =>
+  gr4vy.digitalWallets.create({
+    provider: "google",
+    merchantName: uniqueId("gr4vy-e2e"),
+    merchantDisplayName: "Gr4vy E2E",
+    acceptTermsAndConditions: true,
+  });
+
+// A merchant allows only one wallet per provider, so register a wallet, run the
+// callback against it, then always remove it — keeping the tests isolated even
+// though they share a merchant account.
+const withWallet = async (
+  fn: (wallet: DigitalWallet) => Promise<void>
+): Promise<void> => {
+  const wallet = await registerGoogleWallet();
+  try {
+    await fn(wallet);
+  } finally {
+    await gr4vy.digitalWallets.delete(wallet.id);
+  }
+};
+
+describe("Digital Wallets", () => {
+  test("register → get → list → update (partial) → delete", async () => {
+    const created = await registerGoogleWallet();
+    expect(created.id).toBeDefined();
+
+    const fetched = await gr4vy.digitalWallets.get(created.id);
+    expect(fetched.id).toBe(created.id);
+
+    const list = await gr4vy.digitalWallets.list();
+    expect(list.items.some((w) => w.id === created.id)).toBe(true);
+
+    // Partial update: change only the display name.
+    const updated = await gr4vy.digitalWallets.update(
+      { merchantDisplayName: "Renamed Display" },
+      created.id
+    );
+    expect(updated.merchantDisplayName).toBe("Renamed Display");
+
+    await gr4vy.digitalWallets.delete(created.id);
+    await expect(() => gr4vy.digitalWallets.get(created.id)).rejects.toThrow();
+  });
+
+  // A Google Pay session can be minted server-side from an origin domain; assert
+  // the SDK returns the gateway merchant id + session token.
+  test("creates a google pay session", async () => {
+    const session = await gr4vy.digitalWallets.sessions.googlePay({
+      originDomain: "not-a-registered-domain.example.com",
+    });
+    expect(session).toHaveProperty("token");
+  });
+
+  // The remaining wallet sessions (Apple Pay, Click to Pay, Paze + Paze mobile)
+  // need a verified wallet / real device payloads that can't be minted on the
+  // mock merchant. Each is exercised at the request level so the SDK request
+  // shape is covered and the API rejects it for a real reason.
+  describe("sessions exercised at the request level", () => {
+    test("apple pay session", async () => {
+      await expect(
+        gr4vy.digitalWallets.sessions.applePay({
+          validationUrl: "https://apple-pay-gateway.apple.com/paymentservices",
+          domainName: "not-a-registered-domain.example.com",
+        })
+      ).rejects.toThrow();
+    });
+
+    test("click to pay session", async () => {
+      await expect(
+        gr4vy.digitalWallets.sessions.clickToPay({
+          checkoutSessionId: "00000000-0000-0000-0000-000000000000",
+        })
+      ).rejects.toThrow();
+    });
+
+    test("paze session", async () => {
+      await expect(
+        gr4vy.digitalWallets.sessions.paze({
+          source: "web",
+          domainName: "not-a-registered-domain.example.com",
+        })
+      ).rejects.toThrow();
+    });
+
+    test("paze mobile session create / review / complete", async () => {
+      await expect(
+        gr4vy.digitalWallets.sessions.pazeMobileSessionCreate({
+          client: { id: "client-id" },
+          sessionId: "session-id",
+          accessToken: "access-token",
+          callbackURLScheme: "gr4vy",
+          intent: "EXPRESS_CHECKOUT",
+        })
+      ).rejects.toThrow();
+
+      await expect(
+        gr4vy.digitalWallets.sessions.pazeMobileSessionReview({
+          sessionId: "session-id",
+          code: "code",
+          accessToken: "access-token",
+        })
+      ).rejects.toThrow();
+
+      await expect(
+        gr4vy.digitalWallets.sessions.pazeMobileSessionComplete({
+          sessionId: "session-id",
+          code: "code",
+          accessToken: "access-token",
+          transactionType: "PURCHASE",
+        })
+      ).rejects.toThrow();
+    });
+  });
+
+  // Apple Pay domain registration needs an Apple-provider wallet onboarded with
+  // Apple; on the mock merchant both register and remove are rejected, which
+  // still exercises the domain create/delete request shapes.
+  describe("domains exercised at the request level", () => {
+    test("domain registration is rejected", async () => {
+      await withWallet(async (wallet) => {
+        await expect(
+          gr4vy.digitalWallets.domains.create(
+            { domainName: "example.com" },
+            wallet.id
+          )
+        ).rejects.toThrow();
+      });
+    });
+
+    test("domain removal is idempotent", async () => {
+      await withWallet(async (wallet) => {
+        // Removing a domain that was never registered resolves without error.
+        await expect(
+          gr4vy.digitalWallets.domains.delete(
+            { domainName: "example.com" },
+            wallet.id
+          )
+        ).resolves.toBeUndefined();
+      });
+    });
+  });
+});

package/tests/processing/gift-cards.test.ts

@@ -0,0 +1,45 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+describe("Gift Cards", () => {
+  test("listing gift cards returns a page", async () => {
+    const page = await gr4vy.giftCards.list({});
+    expect(page).toBeDefined();
+  });
+
+  // Creating a gift card and reading its balance requires a gift-card service
+  // (e.g. `mock-gift-card`) to be configured on the merchant. The mock merchant
+  // is provisioned only with `mock-card`, so these calls are exercised at the
+  // request level and the API is expected to reject them for a real reason.
+  test("create is exercised at the request level", async () => {
+    await expect(
+      gr4vy.giftCards.create({
+        number: "4111111111111111",
+        pin: "1234",
+      })
+    ).rejects.toThrow();
+  });
+
+  test("balance lookup is exercised at the request level", async () => {
+    await expect(
+      gr4vy.giftCards.balances.list({
+        items: [{ number: "4111111111111111", pin: "1234" }],
+      })
+    ).rejects.toThrow();
+  });
+
+  // No gift card exists to fetch/delete on the mock merchant, so get/delete are
+  // exercised against a non-existent id and expected to be rejected.
+  test("get and delete are exercised at the request level", async () => {
+    const bogus = "00000000-0000-0000-0000-000000000000";
+    await expect(gr4vy.giftCards.get(bogus)).rejects.toThrow();
+    await expect(gr4vy.giftCards.delete(bogus)).rejects.toThrow();
+  });
+});

package/tests/processing/payment-links.test.ts

@@ -0,0 +1,34 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { cartItem, uniqueId } from "../utils/fixtures";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+describe("Payment Links", () => {
+  test("create → get → list → expire", async () => {
+    const created = await gr4vy.paymentLinks.create({
+      amount: 1299,
+      currency: "USD",
+      country: "US",
+      externalIdentifier: uniqueId("plink"),
+      cartItems: [cartItem()],
+      merchantName: "Gr4vy E2E",
+    });
+    expect(created.id).toBeDefined();
+
+    const fetched = await gr4vy.paymentLinks.get(created.id);
+    expect(fetched.id).toBe(created.id);
+
+    const page = await gr4vy.paymentLinks.list();
+    expect(page).toBeDefined();
+
+    await gr4vy.paymentLinks.expire(created.id);
+    const afterExpiry = await gr4vy.paymentLinks.get(created.id);
+    expect(afterExpiry.status).toBe("expired");
+  });
+});