feat: implement tags for keys and fix some typescript and biome errors

FEATURE_SUGGESTIONS.md

@@ -4,6 +4,7 @@
 - ✅ Custom alphabet for key generation
 - ✅ Salt for hashing
 - ✅ Update last used timestamp
+- ✅ Key tags/labels
 
 ## Recommended Additions
 
@@ -44,18 +45,7 @@ await keys.trackUsage(keyId, {
 const stats = await keys.getUsageStats(keyId)
 ```
 
-### 4. Key Tags/Labels
-```typescript
-await keys.create({
-  ownerId: 'user_123',
-  tags: ['production', 'billing-api'],
-})
-
-// Find by tag
-const keys = await keys.findByTag('production')
-```
-
-### 5. Webhook Events
+### 4. Webhook Events
 ```typescript
 keys.on('key.created', async (event) => {
   await sendWebhook(event.ownerId, 'key_created', event.data)
@@ -70,7 +60,7 @@ keys.on('key.expired', async (event) => {
 })
 ```
 
-### 6. IP Whitelisting
+### 5. IP Whitelisting
 ```typescript
 await keys.create({
   ownerId: 'user_123',
@@ -80,7 +70,7 @@ await keys.create({
 await keys.verify(key, { ipAddress: req.ip })
 ```
 
-### 7. Request Signing
+### 6. Request Signing
 ```typescript
 // HMAC-based request signing
 const signature = keys.sign(request, apiKey)
@@ -89,7 +79,7 @@ const signature = keys.sign(request, apiKey)
 const isValid = await keys.verifySignature(request, signature, keyId)
 ```
 
-### 8. Bulk Operations
+### 7. Bulk Operations
 ```typescript
 // Bulk create
 const results = await keys.createBulk([
@@ -101,7 +91,7 @@ const results = await keys.createBulk([
 await keys.revokeBulk(['key_1', 'key_2', 'key_3'])
 ```
 
-### 9. Key Templates
+### 8. Key Templates
 ```typescript
 // Define reusable templates
 keys.defineTemplate('readonly', {
@@ -114,7 +104,7 @@ const { key } = await keys.createFromTemplate('readonly', {
 })
 ```
 
-### 10. Audit Logging
+### 9. Audit Logging
 ```typescript
 interface AuditLog {
   action: 'created' | 'verified' | 'revoked' | 'updated'

README.md

@@ -267,6 +267,7 @@ const customStorage: Storage = {
   findByHash: async (keyHash) => { /* ... */ },
   findById: async (id) => { /* ... */ },
   findByOwner: async (ownerId) => { /* ... */ },
+  findByTag: async (tag, ownerId) => { /* ... */ },
   updateMetadata: async (id, metadata) => { /* ... */ },
   delete: async (id) => { /* ... */ },
   deleteByOwner: async (ownerId) => { /* ... */ },

biome.jsonc

@@ -5,5 +5,17 @@
     "enabled": true,
     "indentWidth": 2,
     "indentStyle": "tab"
+  },
+  "linter": {
+    "rules": {
+      "complexity": {
+        "noExcessiveCognitiveComplexity": {
+          "level": "warn",
+          "options": {
+            "maxAllowedComplexity": 50
+          }
+        }
+      }
+    }
   }
 }

src/manager.ts

@@ -270,6 +270,7 @@ export class ApiKeyManager {
 		const key = this.generateKey();
 		const keyHash = this.hashKey(key);
 		const now = new Date().toISOString();
+		const tags = metadata.tags?.map((t) => t.toLowerCase());
 
 		const record: ApiKeyRecord = {
 			id: nanoid(),
@@ -286,6 +287,7 @@ export class ApiKeyManager {
 				enabled: metadata.enabled ?? true,
 				revokedAt: null,
 				rotatedTo: null,
+				tags,
 			},
 		};
 
@@ -301,6 +303,13 @@ export class ApiKeyManager {
 		return await this.storage.findById(id);
 	}
 
+	async findByTag(
+		tag: string | string[],
+		ownerId?: string
+	): Promise<ApiKeyRecord[]> {
+		return await this.storage.findByTag(tag, ownerId);
+	}
+
 	async list(ownerId: string): Promise<ApiKeyRecord[]> {
 		return await this.storage.findByOwner(ownerId);
 	}
@@ -394,6 +403,7 @@ export class ApiKeyManager {
 			scopes: metadata?.scopes ?? oldRecord.metadata.scopes,
 			resources: metadata?.resources ?? oldRecord.metadata.resources,
 			expiresAt: metadata?.expiresAt ?? oldRecord.metadata.expiresAt,
+			tags: metadata?.tags ?? oldRecord.metadata.tags,
 		});
 
 		await this.storage.updateMetadata(id, {

src/storage/drizzle.test.ts

@@ -188,6 +188,41 @@ describe("DrizzleStore", () => {
 		});
 	});
 
+	describe("findByTag", () => {
+		it("should find all records by one tag", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag("test");
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+
+		it("should find all records by multiple tags", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag(["test", "key"]);
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+
+		it("should find all records by owner and tag", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag("test", "user_123");
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+	});
+
 	describe("updateMetadata", () => {
 		it("should update metadata", async () => {
 			const { record } = await keys.create({
@@ -608,7 +643,11 @@ describe("DrizzleStore", () => {
 			await Promise.all(promises);
 
 			for (let i = 0; i < records.length; i++) {
-				const found = await store.findById(records[i].record.id);
+				const record = records.at(i);
+				if (!record) {
+					continue;
+				}
+				const found = await store.findById(record.record.id);
 				expect(found?.metadata.name).toBe(`Updated ${i}`);
 			}
 		});

src/storage/drizzle.ts

@@ -1,4 +1,4 @@
-import { arrayContains, eq } from "drizzle-orm";
+import { and, arrayContains, eq, type SQL, sql } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { PgTable } from "drizzle-orm/pg-core";
 import type { apikey } from "../drizzle/schema";
@@ -57,7 +57,7 @@ export class DrizzleStore implements Storage {
 			.where(eq(this.table.keyHash, keyHash))
 			.limit(1);
 
-		return rows.length > 0 ? this.toRecord(rows[0]) : null;
+		return rows.length > 0 && rows[0] ? this.toRecord(rows[0]) : null;
 	}
 
 	async findById(id: string): Promise<ApiKeyRecord | null> {
@@ -67,7 +67,7 @@ export class DrizzleStore implements Storage {
 			.where(eq(this.table.id, id))
 			.limit(1);
 
-		return rows.length > 0 ? this.toRecord(rows[0]) : null;
+		return rows.length > 0 && rows[0] ? this.toRecord(rows[0]) : null;
 	}
 
 	async findByOwner(ownerId: string): Promise<ApiKeyRecord[]> {
@@ -79,6 +79,35 @@ export class DrizzleStore implements Storage {
 		return rows.map(this.toRecord);
 	}
 
+	async findByTag(
+		tag: string | string[],
+		ownerId?: string
+	): Promise<ApiKeyRecord[]> {
+		const tagArray = Array.isArray(tag)
+			? tag.map((t) => t.toLowerCase())
+			: [tag.toLowerCase()];
+
+		const conditions: SQL[] = [];
+
+		if (tagArray.length > 0) {
+			// case insensitive tag matching
+			conditions.push(
+				sql`${this.table.metadata}->'tags' ?| ARRAY[${tagArray.join(",")}]`
+			);
+		}
+
+		if (ownerId) {
+			conditions.push(arrayContains(this.table.metadata, { ownerId }));
+		}
+
+		const rows = await this.db
+			.select()
+			.from(this.table)
+			.where(and(...conditions));
+
+		return rows.map(this.toRecord);
+	}
+
 	async updateMetadata(
 		id: string,
 		metadata: Partial<ApiKeyMetadata>

src/storage/memory.test.ts

@@ -130,6 +130,41 @@ describe("MemoryStore", () => {
 		});
 	});
 
+	describe("findByTag", () => {
+		it("should find all records by one tag", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag("test");
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+
+		it("should find all records by multiple tags", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag(["test", "key"]);
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+
+		it("should find all records by owner and tag", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag("test", "user_123");
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+	});
+
 	describe("updateMetadata", () => {
 		it("should update metadata for a record", async () => {
 			const { record } = await keys.create({

src/storage/memory.ts

@@ -31,6 +31,23 @@ export class MemoryStore implements Storage {
 		);
 	}
 
+	async findByTag(
+		tag: string | string[],
+		ownerId?: string
+	): Promise<ApiKeyRecord[]> {
+		return Array.from(await this.keys.values()).filter((record) => {
+			if (ownerId && record.metadata.ownerId !== ownerId) {
+				return false;
+			}
+			const recordTags = record.metadata.tags?.map((t) => t.toLowerCase());
+			// case insensitive tag matching
+			if (Array.isArray(tag)) {
+				return tag.some((t) => recordTags?.includes(t.toLowerCase()));
+			}
+			return recordTags?.includes(tag.toLowerCase());
+		});
+	}
+
 	async updateMetadata(
 		id: string,
 		metadata: Partial<ApiKeyMetadata>

src/storage/redis.test.ts

@@ -167,6 +167,41 @@ describe("RedisStore", () => {
 		});
 	});
 
+	describe("findByTag", () => {
+		it("should find all records by one tag", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag("test");
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+
+		it("should find all records by multiple tags", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag(["test", "key"]);
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+
+		it("should find all records by owner and tag", async () => {
+			const { record } = await keys.create({
+				ownerId: "user_123",
+				tags: ["test", "key", "more", "tags"],
+			});
+
+			const found = await store.findByTag("test", "user_123");
+			expect(found).toHaveLength(1);
+			expect(found[0]?.id).toBe(record.id);
+		});
+	});
+
 	describe("updateMetadata", () => {
 		it("should update metadata for a record", async () => {
 			const { record } = await keys.create({