feat: Request Optimization

.cursor/rules/pnpm-package-manager.mdc

@@ -0,0 +1,23 @@
+---
+description: Always use pnpm for package management in this project
+globs: ['package.json', 'pnpm-lock.yaml', '**/*.ts', '**/*.js', '**/*.md']
+alwaysApply: true
+---
+
+# Package Manager Rules
+
+## Always use pnpm instead of npm or yarn
+
+- Use `pnpm install` instead of `npm install`
+- Use `pnpm run <script>` instead of `npm run <script>`
+- Use `pnpm test` instead of `npm test`
+- Use `pnpm add <package>` instead of `npm install <package>`
+- Use `pnpm remove <package>` instead of `npm uninstall <package>`
+
+## Project Context
+
+- This is a TypeScript library for the Comic Vine API
+- The project uses Vitest for testing
+- The project has both CommonJS and ESM builds
+- Always respect the existing code structure and patterns
+- When suggesting terminal commands, always use pnpm commands

.cursor/rules/typescript-type-safety.mdc

@@ -0,0 +1,93 @@
+---
+description: Always use TypeScript types and avoid using any or unknown unless necessary
+globs: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx']
+alwaysApply: true
+---
+
+# TypeScript Type Safety Rules
+
+## Type Safety Rules
+
+### Never use `any` type
+
+- Always use proper TypeScript types
+- Use `unknown` **only** when the type is genuinely unknown at compile time
+- **Never use `unknown` as a way to bypass type safety** - always use proper type narrowing
+- Use union types when multiple types are possible
+- Use generics when types need to be parameterized
+- Use type assertions sparingly and only when absolutely necessary
+
+### Never use forceful casting
+
+- Avoid using `as` type assertions unless absolutely necessary
+- **Never cast from `unknown` without proper type checking first**
+- Use type guards instead of casting
+- Use proper type narrowing techniques
+- If casting is unavoidable, add detailed comments explaining why
+
+### Preferred approaches:
+
+- Use `unknown` **only** when you truly don't know the type (e.g., JSON.parse, external APIs)
+- **Always narrow `unknown` types using type guards** before using them
+- Use type guards: `if (typeof x === 'string')`
+- Use `in` operator: `if ('property' in obj)`
+- Use `instanceof` checks: `if (obj instanceof SomeClass)`
+- Use discriminated unions with literal types
+- Use proper generic constraints
+
+### Examples of what NOT to do:
+
+```typescript
+// ❌ Don't use any
+function badFunction(param: any): any {}
+
+// ❌ Don't forcefully cast
+const result = data as SomeType;
+
+// ❌ Don't use unknown as a type escape hatch
+function badUnknownUsage(data: unknown): SomeType {
+  return data as SomeType; // This defeats the purpose of unknown!
+}
+
+// ❌ Don't use unknown when you know the type
+function badParameterType(param: unknown): string {
+  // If you know it should be a string, type it as string!
+  return param as string;
+}
+```
+
+### Examples of what TO do:
+
+```typescript
+// ✅ Use unknown with proper type narrowing
+function goodFunction(param: unknown): string {
+  if (typeof param === 'string') {
+    return param;
+  }
+  throw new Error('Expected string');
+}
+
+// ✅ Use proper generics when types are known
+function genericFunction<T>(param: T): T {
+  return param;
+}
+
+// ✅ Use unknown for truly unknown data (like JSON parsing)
+function parseApiResponse(jsonString: string): User | null {
+  const data: unknown = JSON.parse(jsonString);
+
+  // Proper type checking before using
+  if (
+    typeof data === 'object' &&
+    data !== null &&
+    'id' in data &&
+    'name' in data &&
+    typeof data.id === 'number' &&
+    typeof data.name === 'string'
+  ) {
+    return { id: data.id, name: data.name };
+  }
+
+  return null;
+}
+```

.husky/pre-commit

@@ -1 +1 @@
-npx lint-staged
+pnpm pre-commit

CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Package Management
+
+- Always use `pnpm` instead of npm or yarn
+- Install dependencies: `pnpm install`
+- Build all packages: `pnpm run build`
+- Run tests: `pnpm run test`
+- Run linting: `pnpm run lint`
+- Fix linting issues: `pnpm run lint:fix`
+- Format code: `pnpm run format`
+
+### Development Workflow
+
+- Pre-commit checks: `pnpm run pre-commit`
+- Parallel development: `pnpm run dev`
+- Clean build artifacts: `pnpm run clean`
+- Release workflow: `pnpm run changeset` → `pnpm run version-packages` → `pnpm run release`
+
+## Architecture Overview
+
+This is a TypeScript monorepo for the Comic Vine API client library with the following structure:
+
+### Core Packages
+
+- **`packages/client`** - Main Comic Vine API client with resource classes, HTTP client, and type definitions
+- **`packages/in-memory-store`** - In-memory implementations of cache, deduplication, and rate limiting stores
+- **`packages/sqlite-store`** - SQLite-based persistent store implementations
+- **`packages/eslint-config`** - Shared ESLint configurations
+- **`packages/tsup-config`** - Shared build configurations
+- **`packages/vitest-config`** - Shared test configurations
+
+### Key Architecture Patterns
+
+#### Resource-Based API Structure
+
+- Each Comic Vine resource (character, issue, volume, etc.) has its own class in `packages/client/src/resources/`
+- Resources inherit from `BaseResource` and implement `list()` and `retrieve()` methods
+- Type definitions are organized by resource with separate types for list items and detail responses
+
+#### Store Pattern for Cross-Cutting Concerns
+
+- **Cache Store**: Implements caching with TTL support
+- **Dedupe Store**: Prevents duplicate concurrent requests
+- **Rate Limit Store**: Handles API rate limiting per resource type
+- Stores can be swapped between in-memory and SQLite implementations
+
+#### HTTP Client Architecture
+
+- `HttpClient` handles all API communication with built-in retry logic
+- `UrlBuilder` constructs Comic Vine API URLs with proper parameter formatting
+- `HttpClientFactory` creates clients with appropriate store configurations
+
+### TypeScript Conventions
+
+- Never use `any` type - always use proper TypeScript types
+- Use `unknown` only when genuinely unknown (e.g., JSON parsing) and always narrow with type guards
+- Avoid type assertions (`as`) - use type guards instead
+- All resources have detailed type definitions for both list and detail responses
+
+### Testing Strategy
+
+- Uses Vitest for all testing
+- Comprehensive test coverage with mocked API responses in `__mocks__/`
+- Each resource and utility has corresponding `.test.ts` files
+- Tests focus on type safety, error handling, and API contract compliance
+
+### Build System
+
+- Uses Turbo for monorepo management
+- Dual ESM/CJS builds via tsup
+- Automatic type generation with TypeScript
+- Changesets for version management and publishing