@gr4vy/sdk 2.1.1 → 2.1.3

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");
+  });
+});

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

@@ -0,0 +1,121 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { buyer, cardPaymentMethod } from "../utils/fixtures";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+const storeCard = () => gr4vy.paymentMethods.create(cardPaymentMethod());
+
+describe("Payment Methods", () => {
+  test("create → get → list → delete", async () => {
+    const created = await storeCard();
+    expect(created.id).toBeDefined();
+    expect(created.method).toBe("card");
+
+    const fetched = await gr4vy.paymentMethods.get(created.id);
+    expect(fetched.id).toBe(created.id);
+
+    const page = await gr4vy.paymentMethods.list({});
+    expect(page).toBeDefined();
+
+    await gr4vy.paymentMethods.delete(created.id);
+    await expect(() => gr4vy.paymentMethods.get(created.id)).rejects.toThrow();
+  });
+
+  test("update changes only the expiration date (partial)", async () => {
+    const created = await storeCard();
+    const updated = await gr4vy.paymentMethods.update(
+      { expirationDate: "12/30" },
+      created.id
+    );
+    expect(updated.id).toBe(created.id);
+    expect(updated.expirationDate).toBe("12/30");
+  });
+
+  test("can be stored against a buyer", async () => {
+    const owner = await gr4vy.buyers.create(buyer());
+    const method = await gr4vy.paymentMethods.create({
+      ...cardPaymentMethod(),
+      buyerId: owner.id,
+    });
+    expect(method.buyer?.id).toBe(owner.id);
+  });
+
+  describe("network tokens", () => {
+    test("listing tokens for a fresh card returns an empty collection", async () => {
+      const card = await storeCard();
+      const tokens = await gr4vy.paymentMethods.networkTokens.list(card.id);
+      expect(Array.isArray(tokens.items)).toBe(true);
+    });
+
+    // Provisioning a network token (and the suspend/resume/delete/cryptogram
+    // operations that follow it) requires the merchant account to be onboarded
+    // with the card schemes (Visa/Mastercard requestor IDs) — not available on
+    // the mock merchant. Each call is asserted to be well-formed and rejected by
+    // the API for a real reason rather than silently skipping coverage.
+    test("provision / suspend / resume / delete / cryptogram are exercised at the request level", async () => {
+      const card = await storeCard();
+      const bogusToken = "00000000-0000-0000-0000-000000000000";
+
+      await expect(
+        gr4vy.paymentMethods.networkTokens.create(
+          { merchantInitiated: true, isSubsequentPayment: false },
+          card.id
+        )
+      ).rejects.toThrow();
+
+      await expect(
+        gr4vy.paymentMethods.networkTokens.suspend(card.id, bogusToken)
+      ).rejects.toThrow();
+      await expect(
+        gr4vy.paymentMethods.networkTokens.resume(card.id, bogusToken)
+      ).rejects.toThrow();
+      await expect(
+        gr4vy.paymentMethods.networkTokens.delete(card.id, bogusToken)
+      ).rejects.toThrow();
+      await expect(
+        gr4vy.paymentMethods.networkTokens.cryptogram.create(
+          { merchantInitiated: true },
+          card.id,
+          bogusToken
+        )
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("payment service tokens", () => {
+    test("listing service tokens for a fresh card returns a collection", async () => {
+      const card = await storeCard();
+      const tokens = await gr4vy.paymentMethods.paymentServiceTokens.list(
+        card.id
+      );
+      expect(Array.isArray(tokens.items)).toBe(true);
+    });
+
+    // Creating/deleting a service token requires a tokenization-capable service,
+    // which mock-card is not; exercise the call shape at the request level.
+    test("create and delete are exercised at the request level", async () => {
+      const card = await storeCard();
+      await expect(
+        gr4vy.paymentMethods.paymentServiceTokens.create(
+          {
+            paymentServiceId: "00000000-0000-0000-0000-000000000000",
+            redirectUrl: "https://example.com/return",
+          },
+          card.id
+        )
+      ).rejects.toThrow();
+      await expect(
+        gr4vy.paymentMethods.paymentServiceTokens.delete(
+          card.id,
+          "00000000-0000-0000-0000-000000000000"
+        )
+      ).rejects.toThrow();
+    });
+  });
+});

package/tests/processing/transactions.test.ts

@@ -0,0 +1,118 @@
+import fc from "fast-check";
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { amount, currency, fcParams, metadata } from "../utils/arbitraries";
+import { buyer, cardPaymentMethod, uniqueId } from "../utils/fixtures";
+import { authorizeViaCheckoutSession } from "../utils/transactions";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+// There are two ways to start processing a payment:
+//   1. via a checkout session (covered throughout — see the lifecycle flow and
+//      the helper authorizeViaCheckoutSession), and
+//   2. by posting payment-method details directly to POST /transactions.
+// This block covers entry point (2) — both raw card details and a stored token.
+describe("Transaction entry points", () => {
+  test("creates a transaction with card details posted directly", async () => {
+    const transaction = await gr4vy.transactions.create({
+      amount: 1299,
+      currency: "USD",
+      externalIdentifier: uniqueId("txn"),
+      paymentMethod: cardPaymentMethod(),
+    });
+    expect(transaction.status).toBe("authorization_succeeded");
+    expect(transaction.amount).toBe(1299);
+  });
+
+  test("direct card details can be vaulted against a buyer with store=true", async () => {
+    const owner = await gr4vy.buyers.create(buyer());
+
+    const transaction = await gr4vy.transactions.create({
+      amount: 1299,
+      currency: "USD",
+      buyerId: owner.id,
+      store: true,
+      externalIdentifier: uniqueId("txn"),
+      paymentMethod: cardPaymentMethod(),
+    });
+    expect(transaction.status).toBe("authorization_succeeded");
+
+    // The vaulted method is now reusable as a stored token.
+    const stored = await gr4vy.buyers.paymentMethods.list({ buyerId: owner.id });
+    expect(stored.items.length).toBeGreaterThanOrEqual(1);
+
+    const reused = await gr4vy.transactions.create({
+      amount: 500,
+      currency: "USD",
+      externalIdentifier: uniqueId("txn"),
+      paymentMethod: { method: "id", id: stored.items[0]!.id, securityCode: "123" },
+    });
+    expect(reused.status).toBe("authorization_succeeded");
+  });
+});
+
+describe("Transactions", () => {
+  test("get and list reflect a created transaction", async () => {
+    const created = await authorizeViaCheckoutSession(gr4vy, 1299);
+
+    const fetched = await gr4vy.transactions.get(created.id);
+    expect(fetched.id).toBe(created.id);
+
+    const page = await gr4vy.transactions.list({});
+    expect(page).toBeDefined();
+  });
+
+  test("update overrides metadata and external identifier (partial)", async () => {
+    const created = await authorizeViaCheckoutSession(gr4vy, 1299, {
+      metadata: { original: "value" },
+    });
+
+    const newExternalIdentifier = uniqueId("txn-updated");
+    const updated = await gr4vy.transactions.update(
+      {
+        metadata: { updated: "value" },
+        externalIdentifier: newExternalIdentifier,
+      },
+      created.id
+    );
+    expect(updated.metadata?.["updated"]).toBe("value");
+    // metadata is fully replaced on update, per the API contract.
+    expect(updated.metadata?.["original"]).toBeUndefined();
+    expect(updated.externalIdentifier).toBe(newExternalIdentifier);
+  });
+
+  // Property: any accepted amount/currency authorises and the response echoes
+  // the amount and currency we sent.
+  test("authorizes across a range of amounts and echoes them back", async () => {
+    await fc.assert(
+      fc.asyncProperty(amount(), currency(), async (amt, cur) => {
+        const transaction = await authorizeViaCheckoutSession(gr4vy, amt, {
+          currency: cur,
+        });
+        expect(transaction.status).toBe("authorization_succeeded");
+        expect(transaction.amount).toBe(amt);
+        expect(transaction.currency).toBe(cur);
+      }),
+      fcParams(5)
+    );
+  });
+
+  // Property: arbitrary mixed-case metadata survives the create → get round-trip.
+  test("metadata round-trips through create and get unchanged", async () => {
+    await fc.assert(
+      fc.asyncProperty(metadata(), async (meta) => {
+        const created = await authorizeViaCheckoutSession(gr4vy, 1299, {
+          metadata: meta,
+        });
+        const fetched = await gr4vy.transactions.get(created.id);
+        expect(fetched.metadata).toEqual(meta);
+      }),
+      fcParams(4)
+    );
+  });
+});

package/tests/utils/arbitraries.ts

@@ -0,0 +1,87 @@
+import fc from "fast-check";
+import { Address, BillingDetails, CartItem } from "../../src/models/components";
+
+/**
+ * Shared fast-check parameters for E2E property tests. `numRuns` is deliberately
+ * small because every run is a real network round-trip — we want broad-ish input
+ * coverage without blowing the CI time budget. The seed is fixed (overridable via
+ * `FC_SEED`) so a failing case is reproducible from the CI logs.
+ */
+const DEFAULT_SEED = 42;
+
+// Use FC_SEED when it parses to a real number; otherwise fall back to the
+// default so a non-numeric env value (common in CI templating) can't turn the
+// seed into NaN and make fast-check behave unexpectedly.
+const resolveSeed = (): number => {
+  const raw = process.env["FC_SEED"];
+  if (!raw) return DEFAULT_SEED;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : DEFAULT_SEED;
+};
+
+export const fcParams = <Ts = unknown>(numRuns = 5): fc.Parameters<Ts> => ({
+  numRuns,
+  seed: resolveSeed(),
+});
+
+/** Minor-unit amount the mock connector reliably authorises. */
+export const amount = (): fc.Arbitrary<number> =>
+  fc.integer({ min: 50, max: 100_000 });
+
+/** Currencies the test merchant's `mock-card` service accepts. */
+export const currency = (): fc.Arbitrary<string> => fc.constantFrom("USD");
+
+/** Countries the test merchant's `mock-card` service accepts. */
+export const country = (): fc.Arbitrary<string> => fc.constantFrom("US");
+
+/**
+ * Metadata maps mixing camelCase and snake_case keys, to exercise the
+ * snakecase-keys serialisation boundary the way the auth/embed tests do. Values
+ * are always strings to match the transaction metadata type.
+ */
+export const metadata = (): fc.Arbitrary<Record<string, string>> =>
+  fc.dictionary(
+    fc.oneof(
+      fc.constantFrom("orderId", "campaign", "noteForOps"),
+      fc.constantFrom("order_id", "campaign_ref", "internal_note")
+    ),
+    fc.string({ minLength: 1, maxLength: 40 }),
+    { minKeys: 1, maxKeys: 4 }
+  );
+
+/** Human-ish names with the odd unicode/whitespace edge case. */
+export const name = (): fc.Arbitrary<string> =>
+  fc
+    .string({ minLength: 1, maxLength: 30 })
+    .filter((s) => s.trim().length > 0);
+
+export const addressArb = (): fc.Arbitrary<Address> =>
+  fc.record(
+    {
+      city: fc.constantFrom("London", "Paris", "Berlin", "San Francisco"),
+      country: country(),
+      postalCode: fc.constantFrom("94110", "10001", "SW1A 1AA"),
+      state: fc.constantFrom("CA", "NY", "TX"),
+      line1: fc.string({ minLength: 1, maxLength: 50 }),
+      line2: fc.option(fc.string({ maxLength: 20 }), { nil: undefined }),
+    },
+    { requiredKeys: ["country", "line1"] }
+  );
+
+export const billingDetailsArb = (): fc.Arbitrary<BillingDetails> =>
+  fc.record(
+    {
+      firstName: name(),
+      lastName: name(),
+      emailAddress: fc.emailAddress(),
+      address: addressArb(),
+    },
+    { requiredKeys: ["firstName", "lastName"] }
+  );
+
+export const cartItemArb = (): fc.Arbitrary<CartItem> =>
+  fc.record({
+    name: name(),
+    quantity: fc.integer({ min: 1, max: 5 }),
+    unitAmount: fc.integer({ min: 1, max: 5_000 }),
+  });