fix(api-key): correct refill interval time calculation (#4871)

Co-authored-by: Alex Yang <himself65@outlook.com>

Author: Pankaj3112

packages/better-auth/src/plugins/api-key/api-key.test.ts

@@ -2120,4 +2120,184 @@ describe("api-key", async () => {
 expect(apiKey).not.toBeNull();
 expect(apiKey.permissions).toEqual(permissions);
 });
+
+it("should refill API key credits after refill interval (milliseconds)", async () => {
+vi.useRealTimers();
+
+const refillInterval = 3600000; // 1 hour in milliseconds
+const refillAmount = 5;
+const initialRemaining = 2;
+
+const apiKey = await auth.api.createApiKey({
+body: {
+userId: user.id,
+remaining: initialRemaining,
+refillInterval: refillInterval,
+refillAmount: refillAmount,
+},
+});
+
+// First verification - should reduce remaining to 1
+let result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+expect(result.key?.remaining).toBe(initialRemaining - 1);
+
+// Second verification - should reduce remaining to 0
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+expect(result.key?.remaining).toBe(0);
+
+// Third verification - should fail due to no remaining credits
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(false);
+expect(result.error?.code).toBe("USAGE_EXCEEDED");
+
+// Advance time by more than refill interval
+vi.useFakeTimers();
+await vi.advanceTimersByTimeAsync(refillInterval + 1000);
+
+// Fourth verification - should succeed with refilled credits
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+expect(result.key?.remaining).toBe(refillAmount - 1);
+
+vi.useRealTimers();
+});
+
+it("should not refill API key credits before refill interval expires", async () => {
+vi.useRealTimers();
+
+const refillInterval = 86400000; // 24 hours in milliseconds
+const refillAmount = 10;
+const initialRemaining = 1;
+
+const apiKey = await auth.api.createApiKey({
+body: {
+userId: user.id,
+remaining: initialRemaining,
+refillInterval: refillInterval,
+refillAmount: refillAmount,
+},
+});
+
+// First verification - should reduce remaining to 0
+let result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+expect(result.key?.remaining).toBe(0);
+
+// Advance time by less than refill interval
+vi.useFakeTimers();
+await vi.advanceTimersByTimeAsync(refillInterval / 2); // Only advance half the interval
+
+// Second verification - should still fail (no refill yet)
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(false);
+expect(result.error?.code).toBe("USAGE_EXCEEDED");
+
+// Advance time to complete the refill interval
+await vi.advanceTimersByTimeAsync(refillInterval / 2 + 1000);
+
+// Third verification - should succeed with refilled credits
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+expect(result.key?.remaining).toBe(refillAmount - 1);
+
+vi.useRealTimers();
+});
+
+it("should handle multiple refill cycles correctly", async () => {
+vi.useRealTimers();
+
+const refillInterval = 3600000; // 1 hour in milliseconds
+const refillAmount = 3;
+
+const apiKey = await auth.api.createApiKey({
+body: {
+userId: user.id,
+remaining: 1,
+refillInterval: refillInterval,
+refillAmount: refillAmount,
+},
+});
+
+// Use the initial credit
+let result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+expect(result.key?.remaining).toBe(0);
+
+vi.useFakeTimers();
+
+// First refill cycle
+await vi.advanceTimersByTimeAsync(refillInterval + 1000);
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+expect(result.key?.remaining).toBe(refillAmount - 1);
+
+// Use all refilled credits
+for (let i = 0; i < refillAmount - 1; i++) {
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+}
+
+// Should be out of credits now
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(false);
+expect(result.error?.code).toBe("USAGE_EXCEEDED");
+
+// Second refill cycle
+await vi.advanceTimersByTimeAsync(refillInterval + 1000);
+result = await auth.api.verifyApiKey({
+body: {
+key: apiKey.key,
+},
+});
+expect(result.valid).toBe(true);
+expect(result.key?.remaining).toBe(refillAmount - 1);
+
+vi.useRealTimers();
+});
 });

packages/better-auth/src/plugins/api-key/routes/get-api-key.ts

@@ -69,7 +69,7 @@ export function getApiKey({
 type: "number",
 nullable: true,
 description:
-"The interval in which the `remaining` count is refilled by day. Example: 1 // every day",
+"The interval in milliseconds between refills of the `remaining` count. Example: 3600000 // refill every hour (3600000ms = 1h)",
 },
 refillAmount: {
 type: "number",

packages/better-auth/src/plugins/api-key/routes/list-api-keys.ts

@@ -64,7 +64,7 @@ export function listApiKeys({
 type: "number",
 nullable: true,
 description:
-"The interval in which the `remaining` count is refilled by day. Example: 1 // every day",
+"The interval in milliseconds between refills of the `remaining` count. Example: 3600000 // refill every hour (3600000ms = 1h)",
 },
 refillAmount: {
 type: "number",

packages/better-auth/src/plugins/api-key/routes/update-api-key.ts

@@ -143,7 +143,7 @@ export function updateApiKey({
 type: "number",
 nullable: true,
 description:
-"The interval in which the `remaining` count is refilled by day. Example: 1 // every day",
+"The interval in milliseconds between refills of the `remaining` count. Example: 3600000 // refill every hour (3600000ms = 1h)",
 },
 refillAmount: {
 type: "number",

packages/better-auth/src/plugins/api-key/routes/verify-api-key.ts

@@ -126,7 +126,7 @@ export async function validateApiKey({
 if (refillInterval && refillAmount) {
 // if they provide refill info, then we should refill once the interval is reached.
 
-const timeSinceLastRequest = (now - lastTime) / (1000 * 60 * 60 * 24); // in days
+const timeSinceLastRequest = now - lastTime;
 if (timeSinceLastRequest > refillInterval) {
 remaining = refillAmount;
 lastRefillAt = new Date();

packages/better-auth/src/plugins/api-key/types.ts

@@ -221,9 +221,9 @@ export type ApiKey = {
  */
 userId: string;
 /**
- * The interval in which the `remaining` count is refilled by day
+ * The interval in milliseconds between refills of the `remaining` count
  *
- * @example 1 // every day
+ * @example 3600000 // refill every hour (3600000ms = 1h)
  */
 refillInterval: number | null;
 /**