@gr4vy/sdk 2.1.2 → 2.1.4

package/tests/backoffice/reports.test.ts

@@ -0,0 +1,69 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { ReportCreate } from "../../src/models/components";
+import { uniqueId } from "../utils/fixtures";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+const reportCreate = (): ReportCreate => ({
+  name: uniqueId("report"),
+  schedule: "daily",
+  scheduleEnabled: true,
+  scheduleTimezone: "UTC",
+  spec: {
+    model: "transactions",
+    params: {
+      fields: ["id", "status"],
+      filters: { status: ["capture_succeeded"] },
+      sort: [{ field: "created_at", order: "desc" }],
+    },
+  },
+});
+
+describe("Reports", () => {
+  test("create → get → put (partial) → list", async () => {
+    const created = await gr4vy.reports.create(reportCreate());
+    expect(created.id).toBeDefined();
+
+    const fetched = await gr4vy.reports.get(created.id);
+    expect(fetched.id).toBe(created.id);
+
+    // Partial update: toggle the schedule without resending name/spec.
+    const updated = await gr4vy.reports.put(
+      { scheduleEnabled: false },
+      created.id
+    );
+    expect(updated.scheduleEnabled).toBe(false);
+
+    const page = await gr4vy.reports.list({});
+    expect(page).toBeDefined();
+  });
+
+  test("report executions are listable per-report and account-wide", async () => {
+    const created = await gr4vy.reports.create(reportCreate());
+
+    const perReport = await gr4vy.reports.executions.list(created.id);
+    expect(perReport).toBeDefined();
+
+    const accountWide = await gr4vy.reportExecutions.list({});
+    expect(accountWide).toBeDefined();
+  });
+
+  // A freshly created report has no executions yet, so fetching one / generating
+  // a download URL is exercised at the request level against a non-existent
+  // execution id; the API is expected to reject it.
+  test("fetching a missing execution / url is exercised at the request level", async () => {
+    const created = await gr4vy.reports.create(reportCreate());
+    const bogus = "00000000-0000-0000-0000-000000000000";
+
+    await expect(gr4vy.reports.executions.get(bogus)).rejects.toThrow();
+    await expect(
+      gr4vy.reports.executions.url(created.id, bogus)
+    ).rejects.toThrow();
+  });
+});

package/tests/backoffice/three-ds-scenarios.test.ts

@@ -0,0 +1,34 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { ThreeDSecureScenarioCreate } from "../../src/models/components";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+const scenario = (): ThreeDSecureScenarioCreate => ({
+  conditions: { amount: 5000 },
+  outcome: { authentication: { transactionStatus: "Y" } },
+});
+
+describe("3DS Scenarios", () => {
+  test("create → list → update (partial) → delete", async () => {
+    const created = await gr4vy.threeDsScenarios.create(scenario());
+    expect(created.id).toBeDefined();
+
+    const page = await gr4vy.threeDsScenarios.list();
+    expect(page).toBeDefined();
+
+    // Partial update: replace only the outcome, leaving the conditions intact.
+    const updated = await gr4vy.threeDsScenarios.update(
+      { outcome: { authentication: { transactionStatus: "N" } } },
+      created.id
+    );
+    expect(updated.id).toBe(created.id);
+
+    await gr4vy.threeDsScenarios.delete(created.id);
+  });
+});

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

@@ -0,0 +1,74 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import {
+  address,
+  billingDetails,
+  buyer,
+  cardPaymentMethod,
+  uniqueId,
+} from "../utils/fixtures";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+describe("Buyer lifecycle", () => {
+  test("create buyer, store a card against them, transact, and read it back", async () => {
+    // 1. Create a buyer.
+    const created = await gr4vy.buyers.create(buyer({ displayName: "Ada Lovelace" }));
+    expect(created.id).toBeDefined();
+    expect(created.displayName).toBe("Ada Lovelace");
+
+    // 2. Store a card payment method against the buyer.
+    const method = await gr4vy.paymentMethods.create({
+      ...cardPaymentMethod(),
+      buyerId: created.id,
+    });
+    expect(method.id).toBeDefined();
+
+    // 3. The stored method shows up under the buyer's payment methods.
+    const buyerMethods = await gr4vy.buyers.paymentMethods.list({
+      buyerId: created.id,
+    });
+    expect(buyerMethods.items.some((m) => m.id === method.id)).toBe(true);
+
+    // 4. Add shipping details for the buyer.
+    const shipping = await gr4vy.buyers.shippingDetails.create(
+      {
+        firstName: "Ada",
+        lastName: "Lovelace",
+        address: address(),
+      },
+      created.id!
+    );
+    expect(shipping.id).toBeDefined();
+
+    // 5. Charge the stored method, referencing the buyer + shipping details.
+    const transaction = await gr4vy.transactions.create({
+      amount: 1299,
+      currency: "USD",
+      buyerId: created.id,
+      shippingDetailsId: shipping.id,
+      externalIdentifier: uniqueId("txn"),
+      paymentMethod: { method: "id", id: method.id, securityCode: "123" },
+    });
+    expect(transaction.status).toBe("authorization_succeeded");
+
+    // 6. Gift cards list for the buyer is reachable (empty is fine).
+    const giftCards = await gr4vy.buyers.giftCards.list({ buyerId: created.id });
+    expect(Array.isArray(giftCards.items)).toBe(true);
+  });
+
+  test("buyer can be created with billing details and deleted", async () => {
+    const created = await gr4vy.buyers.create(
+      buyer({ billingDetails: billingDetails({ firstName: "Grace" }) })
+    );
+    expect(created.billingDetails?.firstName).toBe("Grace");
+
+    await gr4vy.buyers.delete(created.id!);
+    await expect(() => gr4vy.buyers.get(created.id!)).rejects.toThrow();
+  });
+});

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