Merge branch 'main' into dan/custom-code-exchange

Author: radenkovic

packages/nylas-connect/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @nylas/connect
 
+## 0.1.0
+
+### Minor Changes
+
+- 356ac8f: Add automatic API URL version suffix handling
+
+  The NylasConnect client now automatically appends `/v3` to API URLs that don't already have a version suffix. This ensures all API calls use versioned endpoints while preserving any explicitly set versions.
+
+  **Features:**
+  - Automatically appends `/v3` to API URLs without version suffixes
+  - Preserves existing version suffixes (e.g., `/v1`, `/v2`, `/v10`)
+  - Handles trailing slashes correctly
+  - Works with custom API URLs and regional endpoints
+
+  **Examples:**
+  - `https://api.us.nylas.com` → `https://api.us.nylas.com/v3`
+  - `https://api.us.nylas.com/v2` → `https://api.us.nylas.com/v2` (unchanged)
+  - `https://custom.api.com` → `https://custom.api.com/v3`
+
+  This change is backward compatible and doesn't affect existing functionality.
+
 ## 0.0.3
 
 ### Patch Changes

packages/nylas-connect/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylas/connect",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Modern, lightweight Nylas connection library with PKCE support",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -50,7 +50,7 @@
   "devDependencies": {
     "@types/node": "^20.11.13",
     "@vitest/coverage-v8": "^2.1.9",
-    "happy-dom": "^13.10.1",
+    "happy-dom": "^15.10.2",
     "typescript": "^5.3.3",
     "vite": "^5.0.10",
     "vite-plugin-dts": "^3.7.0",

packages/nylas-connect/src/connect-client.test.ts

@@ -1164,7 +1164,7 @@ describe("NylasConnect (custom code exchange)", () => {
     expect(result.accessToken).toBe("builtin_access_token");
     expect(result.grantId).toBe("builtin_grant_123");
     expect(fetch).toHaveBeenCalledWith(
-      "https://api.us.nylas.com/connect/token",
+      "https://api.us.nylas.com/v3/connect/token",
       expect.objectContaining({
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
@@ -1187,3 +1187,129 @@ describe("NylasConnect (custom code exchange)", () => {
     return [base64url(header), base64url(payload), "signature"].join(".");
   }
 });
+
+describe("NylasConnect (API URL normalization)", () => {
+  const clientId = "client_123";
+  const redirectUri = "https://app.example/callback";
+
+  beforeEach(() => {
+    localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("should append /v3 to default API URL when no version is present", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://api.us.nylas.com",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.us.nylas.com/v3/connect/auth");
+  });
+
+  it("should append /v3 to custom API URL when no version is present", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://custom.api.com",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://custom.api.com/v3/connect/auth");
+  });
+
+  it("should preserve existing version suffix (v2)", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://api.us.nylas.com/v2",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.us.nylas.com/v2/connect/auth");
+    expect(url).not.toContain("/v3");
+  });
+
+  it("should preserve existing version suffix (v1)", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://api.us.nylas.com/v1",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.us.nylas.com/v1/connect/auth");
+    expect(url).not.toContain("/v3");
+  });
+
+  it("should handle trailing slashes correctly", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://api.us.nylas.com/",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.us.nylas.com/v3/connect/auth");
+    expect(url).not.toContain("//v3"); // Should not have double slashes
+  });
+
+  it("should handle multiple trailing slashes correctly", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://api.us.nylas.com///",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.us.nylas.com/v3/connect/auth");
+    expect(url).not.toContain("//v3"); // Should not have double slashes
+  });
+
+  it("should preserve version with trailing slashes", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://api.us.nylas.com/v2/",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.us.nylas.com/v2/connect/auth");
+    expect(url).not.toContain("/v3");
+  });
+
+  it("should append /v3 to default URL when no apiUrl is provided", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      // No apiUrl provided - should use default
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.us.nylas.com/v3/connect/auth");
+  });
+
+  it("should handle EU API URL correctly", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://api.eu.nylas.com",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.eu.nylas.com/v3/connect/auth");
+  });
+
+  it("should work with higher version numbers", async () => {
+    const auth = new NylasConnect({
+      clientId,
+      redirectUri,
+      apiUrl: "https://api.us.nylas.com/v10",
+    });
+
+    const { url } = await auth.getAuthUrl();
+    expect(url).toContain("https://api.us.nylas.com/v10/connect/auth");
+    expect(url).not.toContain("/v3");
+  });
+});

packages/nylas-connect/src/connect-client.ts

@@ -93,19 +93,35 @@ export class NylasConnect {
     });
   }
 
+  /**
+   * Normalize API URL to ensure it has a version suffix
+   */
+  private normalizeApiUrl(apiUrl: string): string {
+    // Remove trailing slashes
+    const cleanUrl = apiUrl.replace(/\/+$/, "");
+    // Check if URL already has a version suffix (e.g., /v3, /v2, etc.)
+    const versionPattern = /\/v\d+$/;
+    if (versionPattern.test(cleanUrl)) {
+      return cleanUrl;
+    }
+    // Append /v3 if no version suffix is present
+    return `${cleanUrl}/v3`;
+  }
+
   /**
    * Resolve configuration with environment variables and smart defaults
    */
   private resolveConfig(config: ConnectConfig): ConnectConfig {
     const environment = this.detectEnvironment(config.environment);
+    const baseApiUrl = config.apiUrl || "https://api.us.nylas.com";
 
     return {
       clientId: config.clientId || this.getEnvVar("NYLAS_CLIENT_ID"),
       redirectUri:
         config.redirectUri ||
         this.getEnvVar("NYLAS_REDIRECT_URI") ||
         this.detectRedirectUri(),
-      apiUrl: config.apiUrl || "https://api.us.nylas.com",
+      apiUrl: this.normalizeApiUrl(baseApiUrl),
       environment,
       defaultScopes: config.defaultScopes,
       debug: config.debug ?? environment === "development",