From 8ece6db9b7543cc1d387ece1dead6b434224a86a Mon Sep 17 00:00:00 2001
From: Martin Schuhfuss <m.schuhfuss@gmail.com>
Date: Mon, 27 Apr 2026 11:29:51 +0200
Subject: [PATCH] fix: add warning message about common "apiKey" misspelling

---
 src/index.test.ts | 12 ++++++++++++
 src/index.ts      |  9 +++++++++
 src/messages.ts   |  4 ++++
 3 files changed, 25 insertions(+)

diff --git a/src/index.test.ts b/src/index.test.ts
index a26262d1..348de249 100644
--- a/src/index.test.ts
+++ b/src/index.test.ts
@@ -16,6 +16,7 @@
 
 import { jest } from "@jest/globals";
 import type { bootstrap } from "./bootstrap.js";
+import type { APIOptions } from "./index.js";
 
 type ImportLibraryMock = jest.Mock<typeof google.maps.importLibrary>;
 
@@ -81,6 +82,17 @@ describe("importLibrary(): basic operation", () => {
     expect(mockBootstrap).toHaveBeenCalledWith(options);
   });
 
+  it("should log a warning when apiKey is used and use it as key", async () => {
+    const { setOptions } = await import("./index.js");
+    const { logDevWarning, MSG_API_KEY_USED } = await import("./messages.js");
+
+    const options = { apiKey: "foo" } as unknown as APIOptions;
+    setOptions(options);
+
+    expect(logDevWarning).toHaveBeenCalledWith(MSG_API_KEY_USED);
+    expect(options.key).toBe("foo");
+  });
+
   it("should return the value from importLibrary", async () => {
     const { setOptions, importLibrary } = await import("./index.js");
 
diff --git a/src/index.ts b/src/index.ts
index 15fa59e8..591fb14a 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -23,6 +23,7 @@ import {
   MSG_SCRIPT_ELEMENT_EXISTS,
   MSG_REPEATED_SET_OPTIONS,
   MSG_SET_OPTIONS_NOT_CALLED,
+  MSG_API_KEY_USED,
 } from "./messages.js";
 
 export type APIOptions = {
@@ -82,6 +83,14 @@ export function setOptions(options: APIOptions) {
     return;
   }
 
+  if ((options as Record<string, unknown>).apiKey) {
+    logDevWarning(MSG_API_KEY_USED);
+
+    if (!options.key) {
+      options.key = (options as Record<string, unknown>).apiKey as string;
+    }
+  }
+
   installImportLibrary_(options);
   setOptionsWasCalled_ = true;
 }
diff --git a/src/messages.ts b/src/messages.ts
index 1699ce46..341f7529 100644
--- a/src/messages.ts
+++ b/src/messages.ts
@@ -44,6 +44,10 @@ export const MSG_SCRIPT_ELEMENT_EXISTS =
   "problems using the API. Make sure to remove the script " +
   "loading the API.";
 
+export const MSG_API_KEY_USED =
+  "The 'apiKey' parameter was used in setOptions(), but 'key' is the correct " +
+  "parameter name. Please update your configuration.";
+
 // Development mode check - bundlers will replace process.env.NODE_ENV at build time
 declare const process: { env: { NODE_ENV?: string } };
 const __DEV__ = process.env.NODE_ENV !== 'production';