@gr4vy/sdk 2.1.1 → 2.1.3

package/tests/utils/fields.ts

@@ -0,0 +1,65 @@
+import { CheckoutSession } from "../../src/models/components";
+
+const FIELDS_BASE_URL = "https://api.sandbox.e2e.gr4vy.app";
+
+/**
+ * Submits payment-method fields to a checkout session.
+ *
+ * `PUT /checkout/sessions/{id}/fields` is an Embed/secure-fields endpoint that is
+ * intentionally not exposed through the SDK (it is normally called by the
+ * client-side SDKs, not the server SDK). The original checkout-sessions test
+ * called it inline with a raw `fetch`; this helper centralises that so the
+ * lifecycle flows can tokenise a card into a session without duplicating it.
+ *
+ * Returns nothing; throws if the API does not return the expected `204`.
+ */
+const putFields = async (
+  session: CheckoutSession,
+  paymentMethod: Record<string, unknown>
+): Promise<void> => {
+  const response = await fetch(
+    `${FIELDS_BASE_URL}/checkout/sessions/${session.id}/fields`,
+    {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ payment_method: paymentMethod }),
+    }
+  );
+
+  if (response.status !== 204) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `Unexpected status ${response.status} submitting checkout session fields: ${body}`
+    );
+  }
+};
+
+export interface RawCard {
+  number: string;
+  expiration_date: string;
+  security_code: string;
+}
+
+/** Tokenises a raw card into the checkout session. */
+export const putCheckoutSessionCard = (
+  session: CheckoutSession,
+  card: RawCard
+): Promise<void> =>
+  putFields(session, {
+    method: "card",
+    number: card.number,
+    expiration_date: card.expiration_date,
+    security_code: card.security_code,
+  });
+
+/** Attaches a previously stored payment method to the checkout session. */
+export const putCheckoutSessionStoredMethod = (
+  session: CheckoutSession,
+  paymentMethodId: string,
+  securityCode?: string
+): Promise<void> =>
+  putFields(session, {
+    method: "id",
+    id: paymentMethodId,
+    ...(securityCode ? { security_code: securityCode } : {}),
+  });

package/tests/utils/fixtures.ts

@@ -0,0 +1,84 @@
+import crypto from "crypto";
+import {
+  Address,
+  BillingDetails,
+  BuyerCreate,
+  CardPaymentMethodCreate,
+  CartItem,
+  Transaction,
+} from "../../src/models/components";
+import { RawCard } from "./fields";
+
+/**
+ * Capture/void/cancel return either a bare {@link Transaction} or a wrapper that
+ * nests it under `transaction` (depending on the `Prefer` header). This narrows
+ * both shapes to the underlying transaction.
+ */
+export const unwrapTransaction = (
+  result: Transaction | { transaction: Transaction }
+): Transaction => ("transaction" in result ? result.transaction : result);
+
+/**
+ * Generates a process-unique identifier. Namespaced with a random suffix so
+ * external identifiers never collide across parallel test files / CI shards.
+ */
+export const uniqueId = (prefix = "ts-e2e"): string =>
+  `${prefix}-${crypto.randomBytes(6).toString("hex")}`;
+
+/**
+ * The `mock-card` connector used by the test merchant accepts this Visa test
+ * number and authorises it. Used both as raw fields (checkout sessions) and as
+ * an SDK `CardPaymentMethodCreate`.
+ */
+export const APPROVING_CARD: RawCard = {
+  number: "4111111111111111",
+  // Far-future expiry so the fixture never lapses and gets rejected as expired.
+  expiration_date: "12/35",
+  security_code: "123",
+};
+
+export const cardPaymentMethod = (
+  overrides: Partial<CardPaymentMethodCreate> = {}
+): CardPaymentMethodCreate => ({
+  method: "card",
+  number: APPROVING_CARD.number,
+  expirationDate: APPROVING_CARD.expiration_date,
+  securityCode: APPROVING_CARD.security_code,
+  ...overrides,
+});
+
+export const address = (overrides: Partial<Address> = {}): Address => ({
+  city: "London",
+  country: "US",
+  postalCode: "94110",
+  state: "CA",
+  line1: "123 Example Street",
+  line2: "Apt 4",
+  organization: "Gr4vy",
+  ...overrides,
+});
+
+export const billingDetails = (
+  overrides: Partial<BillingDetails> = {}
+): BillingDetails => ({
+  firstName: "John",
+  lastName: "Doe",
+  emailAddress: "john.doe@example.com",
+  phoneNumber: "+14155551234",
+  address: address(),
+  ...overrides,
+});
+
+export const buyer = (overrides: Partial<BuyerCreate> = {}): BuyerCreate => ({
+  displayName: "John Doe",
+  externalIdentifier: uniqueId("buyer"),
+  billingDetails: billingDetails(),
+  ...overrides,
+});
+
+export const cartItem = (overrides: Partial<CartItem> = {}): CartItem => ({
+  name: "Joust Duffle Bag",
+  quantity: 1,
+  unitAmount: 1299,
+  ...overrides,
+});

package/tests/utils/poll.ts

@@ -0,0 +1,40 @@
+export interface PollOptions {
+  /** Maximum total time to wait before giving up. Defaults to 20s. */
+  timeoutMs?: number;
+  /** Delay between attempts. Defaults to 1s. */
+  intervalMs?: number;
+  /** Label used in the timeout error message. */
+  description?: string;
+}
+
+/**
+ * Repeatedly calls `fetchFn` until `predicate` returns true, then resolves with
+ * the last fetched value. Used for the eventually-consistent endpoints in the
+ * lifecycle flows (a capture settling, a report execution finishing, a payout
+ * status advancing) so tests don't race ahead of the backend. Bounded by
+ * `timeoutMs` so a stuck state fails fast instead of hanging the worker.
+ */
+export const pollUntil = async <T>(
+  fetchFn: () => Promise<T>,
+  predicate: (value: T) => boolean,
+  options: PollOptions = {}
+): Promise<T> => {
+  const { timeoutMs = 20_000, intervalMs = 1_000, description = "condition" } =
+    options;
+  const deadline = Date.now() + timeoutMs;
+  let last: T;
+
+  do {
+    last = await fetchFn();
+    if (predicate(last)) {
+      return last;
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  } while (Date.now() < deadline);
+
+  throw new Error(
+    `Timed out after ${timeoutMs}ms waiting for ${description}. Last value: ${JSON.stringify(
+      last!
+    )}`
+  );
+};

package/tests/utils/setup.ts

@@ -5,7 +5,7 @@ import { Gr4vy, withToken } from "../../src";
 import { HTTPClient } from "../../src/lib/http";
 
 const loadPrivateKey = (): string => {
-  let privateKey = process.env.PRIVATE_KEY;
+  let privateKey = process.env["PRIVATE_KEY"];
 
   if (!privateKey) {
     const filename = path.resolve(__dirname, "./../../private_key.pem");
@@ -15,12 +15,44 @@ const loadPrivateKey = (): string => {
   return privateKey;
 };
 
+// When GR4VY_TRACK_HTTP is set (the CI coverage job sets it), record every
+// outgoing request's method + path. scripts/endpoint-coverage.mjs uses these to
+// compute endpoint reach from *observed HTTP calls* rather than statement
+// coverage, so an operation only counts as reached if a request was actually
+// sent. Each worker writes its own file to avoid cross-process races.
+const httpLogDir = path.resolve(__dirname, "./../../coverage/http");
+let httpLogFile: string | undefined;
+const recordHttpCall = (method: string, url: string): void => {
+  if (!process.env["GR4VY_TRACK_HTTP"]) return;
+  try {
+    if (!httpLogFile) {
+      fs.mkdirSync(httpLogDir, { recursive: true });
+      const suffix = crypto.randomBytes(4).toString("hex");
+      httpLogFile = path.join(httpLogDir, `calls-${process.pid}-${suffix}.jsonl`);
+    }
+    const pathname = new URL(url).pathname;
+    // Fire-and-forget async append: keeps instrumentation off the request hot
+    // path (no synchronous I/O blocking the event loop). O_APPEND keeps each
+    // small line atomic, and errors are ignored — this is best-effort tracking.
+    fs.appendFile(
+      httpLogFile,
+      JSON.stringify({ method, pathname }) + "\n",
+      () => {}
+    );
+  } catch {
+    // best-effort instrumentation; never fail a test because of it
+  }
+};
+
 const httpClient = new HTTPClient({
   /**
    * Adds a custom HTTP client that inserts random fields in the response,
-   * ensuring we test for forward compatibility. 
+   * ensuring we test for forward compatibility.
    */
   fetcher: async (request) => {
+    if (request instanceof Request) {
+      recordHttpCall(request.method, request.url);
+    }
     const originalResponse = await fetch(request);
     const contentType = originalResponse.headers.get("content-type");
     if (!contentType || !contentType.includes("application/json")) {
@@ -50,7 +82,7 @@ const httpClient = new HTTPClient({
   },
 });
 
-const createGr4vyClient = (
+export const createGr4vyClient = (
   privateKey: string,
   merchantAccountId?: string
 ): Gr4vy => {
@@ -63,8 +95,22 @@ const createGr4vyClient = (
   });
 };
 
-export const setupEnvironment = async (): Promise<Gr4vy> => {
-  // Create a merchant account
+export interface TestMerchant {
+  /** Merchant-scoped client, with a `mock-card` payment service provisioned. */
+  client: Gr4vy;
+  /** The randomly generated merchant account id this client is scoped to. */
+  merchantAccountId: string;
+  /** The private key, for spinning up additional clients in the same suite. */
+  privateKey: string;
+}
+
+/**
+ * Provisions an isolated merchant account with a `mock-card` payment service and
+ * returns a merchant-scoped client plus its identifiers. Each test file should
+ * call this once in `beforeAll` so files never share state and can run in
+ * parallel across vitest workers / CI shards.
+ */
+export const setupMerchant = async (): Promise<TestMerchant> => {
   const privateKey = loadPrivateKey();
   const adminClient = createGr4vyClient(privateKey);
   const merchantAccountId = crypto.randomBytes(8).toString("hex");
@@ -72,9 +118,8 @@ export const setupEnvironment = async (): Promise<Gr4vy> => {
     id: merchantAccountId,
     displayName: merchantAccountId,
   });
-  const merchantClient = createGr4vyClient(privateKey, merchantAccount.id);
-  // Setup a payment service
-  await merchantClient.paymentServices.create({
+  const client = createGr4vyClient(privateKey, merchantAccount.id);
+  await client.paymentServices.create({
     acceptedCountries: ["US"],
     acceptedCurrencies: ["USD"],
     displayName: "Payment service",
@@ -82,9 +127,20 @@ export const setupEnvironment = async (): Promise<Gr4vy> => {
     fields: [{ key: "merchant_id", value: "test" }],
   });
 
-  return merchantClient;
+  return { client, merchantAccountId: merchantAccount.id, privateKey };
+};
+
+/**
+ * Back-compat helper used by the original suites: returns only the merchant
+ * client. New suites should prefer {@link setupMerchant} when they need the
+ * merchant id (e.g. to namespace external identifiers).
+ */
+export const setupEnvironment = async (): Promise<Gr4vy> => {
+  const { client } = await setupMerchant();
+  return client;
 };
 
 export const cleanupEnvironment = async (): Promise<void> => {
-  // no-op
+  // Merchant accounts in the sandbox are disposable and left in place; there is
+  // no public delete endpoint for them, so cleanup is intentionally a no-op.
 };

package/tests/utils/transactions.ts

@@ -0,0 +1,26 @@
+import { Gr4vy } from "../../src";
+import { Transaction, TransactionCreate } from "../../src/models/components";
+import { APPROVING_CARD, uniqueId } from "./fixtures";
+import { putCheckoutSessionCard } from "./fields";
+
+/**
+ * Authorises (or captures) a transaction the way a real integration does: open a
+ * checkout session, tokenise the approving test card into it, then create the
+ * transaction against that session. Extra `TransactionCreate` fields can be
+ * merged in via `overrides`.
+ */
+export const authorizeViaCheckoutSession = async (
+  client: Gr4vy,
+  amount: number,
+  overrides: Partial<TransactionCreate> = {}
+): Promise<Transaction> => {
+  const session = await client.checkoutSessions.create();
+  await putCheckoutSessionCard(session, APPROVING_CARD);
+  return client.transactions.create({
+    amount,
+    currency: "USD",
+    externalIdentifier: uniqueId("txn"),
+    ...overrides,
+    paymentMethod: { method: "checkout-session", id: session.id },
+  });
+};

package/vitest.config.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from "vitest/config";
+
+// E2E suites talk to the real sandbox at api.sandbox.e2e.gr4vy.app. Each test
+// file provisions its own merchant account (see tests/utils/setup.ts), so files
+// are fully isolated and safe to run in parallel across worker threads. CI shards
+// the files across jobs with `vitest run --shard=$i/$n`.
+export default defineConfig({
+  test: {
+    // Run test files concurrently across worker threads. Tests *within* a file
+    // still run sequentially, which keeps each file's merchant-scoped flow ordered.
+    fileParallelism: true,
+    // Network calls to a shared sandbox occasionally blip; a couple of retries
+    // keeps the auto-merge SDK-regen pipeline from flaking on transient errors.
+    retry: 2,
+    // Generous timeouts for the real network + eventually-consistent endpoints
+    // (capture settling, report execution). Mirrors the CI invocation flags.
+    testTimeout: 30_000,
+    hookTimeout: 30_000,
+    // Keep the offline unit tests (auth, webhook) and the live E2E suites together.
+    include: ["tests/**/*.test.{ts,js}"],
+    coverage: {
+      provider: "v8",
+      // `src/funcs/*` is one file per API operation, so coverage over this
+      // directory doubles as an "endpoints reached" metric (see
+      // scripts/endpoint-coverage.mjs). `src/sdk/*` are the namespace wrappers.
+      include: ["src/funcs/**", "src/sdk/**"],
+      reporter: ["text-summary", "json-summary", "json"],
+      reportsDirectory: "coverage",
+    },
+  },
+});

package/tests/checkout-sessions.test.ts

@@ -1,109 +0,0 @@
-import { afterAll, beforeAll, describe, expect, test } from 'vitest';
-import { CardPaymentMethodCreate } from '../src/models/components';
-import { cleanupEnvironment, setupEnvironment } from './utils/setup';
-
-let gr4vy;
-
-beforeAll(async () => {
-  gr4vy = await setupEnvironment()
-});
-
-afterAll(async () => {
-  await cleanupEnvironment()
-});
-
-describe("Checkout Sessions", () => {
-  test("should process a payment with a checkout session", async () => {
-    const checkoutSession = await gr4vy.checkoutSessions.create()
-    expect(checkoutSession.id).toBeDefined();
-
-    // We do not use the SDK here as we don't want to make this feature public
-    const response = await fetch(`https://api.sandbox.e2e.gr4vy.app/checkout/sessions/${checkoutSession.id}/fields`, {
-      method: "PUT",
-      headers: {
-        'content-type': 'application/json',
-      },
-      body: JSON.stringify({
-        "payment_method": {
-          "method": "card",
-          "number": "4111111111111111",
-          "expiration_date": "11/25",
-          "security_code": "123",
-        }
-      })
-    })
-    expect(response.status).toBe(204);
-
-    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",
-        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 = {
-      method: "card",
-      number: "4111111111111111",
-      expirationDate: "11/25",
-      securityCode: "123",
-    };
-
-    const paymentMethod = await gr4vy.paymentMethods.create(request)
-    expect(paymentMethod.id).toBeDefined()
-
-    const checkoutSession = await gr4vy.checkoutSessions.create()
-    expect(checkoutSession.id).toBeDefined();
-
-    // We do not use the SDK here as we don't want to make this feature public
-    const response = await fetch(`https://api.sandbox.e2e.gr4vy.app/checkout/sessions/${checkoutSession.id}/fields`, {
-      method: "PUT",
-      headers: {
-        'content-type': 'application/json',
-      },
-      body: JSON.stringify({
-        "payment_method": {
-          "method": "id",
-          "id": paymentMethod.id,
-          "security_code": "123",
-        }
-      })
-    })
-    expect(response.status).toBe(204);
-
-    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);
-  });
-});