@gr4vy/sdk 2.1.1 → 2.1.3

package/tests/backoffice/merchant-accounts.test.ts

@@ -0,0 +1,77 @@
+import crypto from "crypto";
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { createGr4vyClient, setupMerchant } from "../utils/setup";
+
+let admin: Gr4vy;
+let privateKey: string;
+
+beforeAll(async () => {
+  // merchant-accounts are an admin-level resource, so use an un-scoped client.
+  ({ privateKey } = await setupMerchant());
+  admin = createGr4vyClient(privateKey);
+});
+
+const newMerchantId = () => crypto.randomBytes(8).toString("hex");
+
+describe("Merchant Accounts", () => {
+  test("create → get → list → update (partial)", async () => {
+    const id = newMerchantId();
+    const created = await admin.merchantAccounts.create({
+      id,
+      displayName: "Original Display",
+    });
+    expect(created.id).toBe(id);
+
+    const fetched = await admin.merchantAccounts.get(id);
+    expect(fetched.id).toBe(id);
+
+    const page = await admin.merchantAccounts.list();
+    expect(page).toBeDefined();
+
+    // Partial update: change only the display name, leave everything else.
+    const updated = await admin.merchantAccounts.update(
+      { displayName: "Renamed Display" },
+      id
+    );
+    expect(updated.displayName).toBe("Renamed Display");
+    expect(updated.id).toBe(id);
+  });
+
+  describe("3DS configuration", () => {
+    // 3DS configuration is keyed per scheme/currency on the merchant account.
+    test("create → list → update (partial) → delete", async () => {
+      const id = newMerchantId();
+      await admin.merchantAccounts.create({ id, displayName: id });
+
+      const created =
+        await admin.merchantAccounts.threeDsConfiguration.create(
+          {
+            merchantAcquirerBin: "516327",
+            merchantAcquirerId: "123456789012345",
+            merchantName: "Gr4vy E2E",
+            merchantCountryCode: "840",
+            merchantCategoryCode: "1234",
+            merchantUrl: "https://example.com",
+            scheme: "visa",
+            metadata: { env: "e2e" },
+          },
+          id
+        );
+      expect(created.id).toBeDefined();
+
+      const list = await admin.merchantAccounts.threeDsConfiguration.list(id);
+      expect(list).toBeDefined();
+
+      const updated =
+        await admin.merchantAccounts.threeDsConfiguration.update(
+          { merchantName: "Renamed Merchant" },
+          id,
+          created.id!
+        );
+      expect(updated.merchantName).toBe("Renamed Merchant");
+
+      await admin.merchantAccounts.threeDsConfiguration.delete(id, created.id!);
+    });
+  });
+});

package/tests/backoffice/payment-services.test.ts

@@ -0,0 +1,95 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { PaymentServiceCreate } from "../../src/models/components";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+const mockCardService = (
+  overrides: Partial<PaymentServiceCreate> = {}
+): PaymentServiceCreate => ({
+  displayName: "Mock card service",
+  paymentServiceDefinitionId: "mock-card",
+  acceptedCurrencies: ["USD"],
+  acceptedCountries: ["US"],
+  fields: [{ key: "merchant_id", value: "test" }],
+  ...overrides,
+});
+
+describe("Payment Services", () => {
+  test("create → get → list → update (partial) → delete", async () => {
+    const created = await gr4vy.paymentServices.create(mockCardService());
+    expect(created.id).toBeDefined();
+
+    const fetched = await gr4vy.paymentServices.get(created.id!);
+    expect(fetched.id).toBe(created.id);
+
+    const page = await gr4vy.paymentServices.list({});
+    expect(page).toBeDefined();
+
+    // Partial update: change only the display name.
+    const updated = await gr4vy.paymentServices.update(
+      { displayName: "Renamed service" },
+      created.id!
+    );
+    expect(updated.displayName).toBe("Renamed service");
+
+    await gr4vy.paymentServices.delete(created.id!);
+    await expect(() => gr4vy.paymentServices.get(created.id!)).rejects.toThrow();
+  });
+
+  // Credential verification and session creation are not meaningfully supported
+  // by the mock-card connector (verify returns a non-JSON body; session is
+  // explicitly unsupported), so both are exercised at the request level.
+  test("verify is exercised at the request level", async () => {
+    await expect(
+      gr4vy.paymentServices.verify({
+        paymentServiceDefinitionId: "mock-card",
+        fields: [{ key: "merchant_id", value: "test" }],
+      })
+    ).rejects.toThrow();
+  });
+
+  test("create a session is exercised at the request level", async () => {
+    const created = await gr4vy.paymentServices.create(mockCardService());
+    await expect(
+      gr4vy.paymentServices.session({}, created.id!)
+    ).rejects.toThrow();
+  });
+
+  describe("definitions, options and card schemes", () => {
+    test("list and get payment service definitions", async () => {
+      const page = await gr4vy.paymentServiceDefinitions.list();
+      expect(page).toBeDefined();
+
+      const definition =
+        await gr4vy.paymentServiceDefinitions.get("mock-card");
+      expect(definition.id).toBe("mock-card");
+    });
+
+    test("create a session for a definition is exercised at the request level", async () => {
+      // Session creation is not supported for the mock-card definition.
+      await expect(
+        gr4vy.paymentServiceDefinitions.session({}, "mock-card")
+      ).rejects.toThrow();
+    });
+
+    test("list payment options for a cart", async () => {
+      const options = await gr4vy.paymentOptions.list({
+        country: "US",
+        currency: "USD",
+        amount: 1299,
+      });
+      expect(options).toBeDefined();
+    });
+
+    test("list card scheme definitions", async () => {
+      const schemes = await gr4vy.cardSchemeDefinitions.list();
+      expect(schemes).toBeDefined();
+    });
+  });
+});

package/tests/backoffice/payouts.test.ts

@@ -0,0 +1,49 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { Gr4vy } from "../../src";
+import { APPROVING_CARD } from "../utils/fixtures";
+import { setupMerchant } from "../utils/setup";
+
+let gr4vy: Gr4vy;
+
+beforeAll(async () => {
+  ({ client: gr4vy } = await setupMerchant());
+});
+
+describe("Payouts", () => {
+  test("listing payouts returns a page", async () => {
+    const page = await gr4vy.payouts.list();
+    expect(page).toBeDefined();
+  });
+
+  // The mock-card service is not a payout-capable connection, so creating a
+  // payout is exercised at the request level — the SDK serialises the payload
+  // and the API rejects it for a real reason rather than the test skipping it.
+  test("create is exercised at the request level", async () => {
+    const service = await gr4vy.paymentServices.create({
+      displayName: "Mock card service",
+      paymentServiceDefinitionId: "mock-card",
+      acceptedCurrencies: ["USD"],
+      acceptedCountries: ["US"],
+      fields: [{ key: "merchant_id", value: "test" }],
+    });
+
+    await expect(
+      gr4vy.payouts.create({
+        amount: 1299,
+        currency: "USD",
+        paymentServiceId: service.id,
+        paymentMethod: {
+          method: "card",
+          number: APPROVING_CARD.number,
+          expirationDate: APPROVING_CARD.expiration_date,
+        },
+      })
+    ).rejects.toThrow();
+  });
+
+  test("fetching a missing payout is exercised at the request level", async () => {
+    await expect(
+      gr4vy.payouts.get("00000000-0000-0000-0000-000000000000")
+    ).rejects.toThrow();
+  });
+});

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