comic-vine-sdk 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -2,11 +2,7 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-## [1.3.0](https://github.com/AllyMurray/comic-vine/compare/v1.2.8...v1.3.0) (2025-07-03)
-
-### Features
-
-- complete migration from projen to standard npm project ([4c3ef8d](https://github.com/AllyMurray/comic-vine/commit/4c3ef8dbac71f10b17c6154421eaa750f1fa4ebf))
+### [1.3.1](https://github.com/AllyMurray/comic-vine/compare/v1.3.0...v1.3.1) (2025-07-03)
 
 ## [1.2.8] - 2024-01-01
 

package/CONTRIBUTING.md

@@ -0,0 +1,294 @@
+# Contributing to Comic Vine SDK
+
+Thank you for your interest in contributing to the Comic Vine SDK! This document provides guidelines and information to help you contribute effectively to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Development Workflow](#development-workflow)
+- [Code Standards](#code-standards)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Project Structure](#project-structure)
+- [Resources](#resources)
+
+## Code of Conduct
+
+This project adheres to a [Code of Conduct](./CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [allymurray88@gmail.com](mailto:allymurray88@gmail.com).
+
+## Getting Started
+
+### Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- **Node.js**: Version 20.0.0 or higher
+- **pnpm**: Version 9.15.4+ (specified in package.json)
+  ```bash
+  npm install -g pnpm@9.15.4
+  ```
+
+### Development Setup
+
+1. **Fork and Clone**
+
+   ```bash
+   git clone https://github.com/your-username/comic-vine.git
+   cd comic-vine
+   ```
+
+2. **Install Dependencies**
+
+   ```bash
+   pnpm install
+   ```
+
+3. **Verify Setup**
+   ```bash
+   pnpm test
+   ```
+
+If all tests pass, you're ready to start developing!
+
+## Development Workflow
+
+### Creating a Branch
+
+1. Create a feature branch from `main`:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/issue-description
+   ```
+
+2. Use descriptive branch names:
+   - `feature/add-search-pagination`
+   - `fix/handle-rate-limiting`
+   - `docs/update-readme-examples`
+
+### Making Changes
+
+1. **Write Code**: Follow the [Code Standards](#code-standards) below
+2. **Add Tests**: Ensure new functionality has corresponding tests
+3. **Run Tests**: `pnpm test` to run tests and linting
+4. **Build**: `pnpm compile` to ensure your changes compile correctly
+
+### Commit Messages
+
+Follow conventional commit format:
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+**Examples:**
+
+```
+feat(resources): add pagination support to character list
+fix(http-client): handle network timeout errors
+docs(readme): update installation instructions
+```
+
+## Code Standards
+
+### TypeScript Guidelines
+
+- **Type Safety**: Prefer explicit types over `any`
+- **Interfaces**: Use interfaces for object shapes
+- **Generics**: Leverage generics for reusable components
+- **Strict Mode**: The project uses strict TypeScript settings
+
+### Code Style
+
+The project uses **ESLint** and **Prettier** for code formatting:
+
+```bash
+# Auto-fix linting issues and format code
+pnpm lint
+
+# Check linting without fixing
+npx eslint src --ext .ts
+```
+
+**Key Style Rules:**
+
+- Use camelCase for variables and functions
+- Use PascalCase for classes and interfaces
+- Prefer `const` over `let` when possible
+- Use meaningful variable names
+- Add JSDoc comments for public APIs
+
+### Import Organization
+
+Imports should be organized as follows:
+
+```typescript
+// 1. Built-in Node.js modules
+import { readFile } from 'fs/promises';
+
+// 2. External dependencies
+import axios from 'axios';
+import { z } from 'zod';
+
+// 3. Internal modules (ordered alphabetically)
+import { BaseResource } from './base-resource';
+import { HttpClient } from './http-client';
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests with linting
+pnpm test
+
+# Run tests only (without linting)
+pnpm test:run
+
+# Run tests in watch mode
+npx vitest --dir=src
+```
+
+### Writing Tests
+
+1. **Location**: Place test files alongside source files with `.test.ts` extension
+2. **Naming**: Use descriptive test names that explain the behavior being tested
+3. **Structure**: Follow Arrange-Act-Assert pattern
+
+**Example Test:**
+
+```typescript
+import { describe, test, expect } from 'vitest';
+
+describe('ResourceName', () => {
+  test('should return correct data when field list is specified', async () => {
+    // Arrange
+    const expectedFields = ['id', 'name'];
+
+    // Act
+    const result = await resource.retrieve(123, { fieldList: expectedFields });
+
+    // Assert
+    expect(Object.keys(result)).toEqual(expectedFields);
+  });
+});
+```
+
+### Test Coverage
+
+- Write tests for all new functionality
+- Include both success and error scenarios
+- Mock external dependencies using **nock** for HTTP requests
+- Test files are located in `src/__mocks__/` for mock data
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Update Documentation**: Ensure README, JSDoc, and other docs reflect your changes
+
+2. **Verify Quality Checks**: All checks must pass before merging
+
+   ```bash
+   pnpm test:run  # All tests pass
+   pnpm lint      # No linting errors
+   pnpm compile   # Code compiles successfully
+   ```
+
+3. **Create Pull Request**:
+   - Use a descriptive title
+   - Reference any related issues
+   - Provide clear description of changes
+   - Include examples if adding new features
+
+4. **Review Process**:
+   - Maintainers will review your PR
+   - Address any feedback promptly
+   - See [CODE_REVIEW.md](./CODE_REVIEW.md) for review criteria
+
+### Pre-commit Hooks
+
+The project uses **Husky** and **lint-staged** to ensure code quality:
+
+- **Auto-formatting**: Prettier formats code on commit
+- **Linting**: ESLint checks are enforced
+- **Type checking**: TypeScript compilation is verified
+
+If pre-commit hooks fail, fix the issues before committing:
+
+```bash
+pnpm lint  # Fix linting issues
+git add .  # Stage the fixes
+git commit # Try committing again
+```
+
+## Project Structure
+
+```
+src/
+├── comic-vine.ts              # Main SDK class
+├── errors/                    # Custom error classes
+├── http-client/               # HTTP client and URL builder
+├── options/                   # Configuration options
+├── resources/                 # API resource implementations
+│   ├── base-resource.ts       # Base class for all resources
+│   ├── character/             # Character-specific code
+│   ├── issue/                 # Issue-specific code
+│   └── ...                    # Other Comic Vine resources
+├── types/                     # TypeScript type definitions
+└── utils/                     # Utility functions
+```
+
+### Adding New Resources
+
+When adding support for a new Comic Vine API resource:
+
+1. Create a new directory under `src/resources/`
+2. Implement the resource class extending `BaseResource`
+3. Add TypeScript types in a `types/` subdirectory
+4. Write comprehensive tests
+5. Update the main `ComicVine` class to include the new resource
+6. Add mock data for testing
+
+## Resources
+
+### Documentation
+
+- [Comic Vine API Documentation](https://comicvine.gamespot.com/api/documentation)
+- [Project README](./README.md)
+- [Code Review Guidelines](./CODE_REVIEW.md)
+
+### Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/AllyMurray/comic-vine/issues)
+- **Discussions**: Use GitHub Discussions for questions
+
+### Development Tools
+
+- **Package Manager**: [pnpm](https://pnpm.io/)
+- **Testing**: [Vitest](https://vitest.dev/)
+- **Linting**: [ESLint](https://eslint.org/) + [TypeScript ESLint](https://typescript-eslint.io/)
+- **Formatting**: [Prettier](https://prettier.io/)
+- **Git Hooks**: [Husky](https://typicode.github.io/husky/)
+
+---
+
+Thank you for contributing to Comic Vine SDK! Your contributions help make this library better for everyone. 🚀

package/README.md

@@ -1,10 +1,21 @@
 # Comic Vine SDK
 
+[![NPM Version](https://img.shields.io/npm/v/comic-vine-sdk)](https://www.npmjs.com/package/comic-vine-sdk)
+[![License](https://img.shields.io/npm/l/comic-vine-sdk)](https://github.com/AllyMurray/comic-vine/blob/main/LICENSE)
+[![Node.js Version](https://img.shields.io/node/v/comic-vine-sdk)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
+
 The Comic Vine SDK provides convenient access to the [Comic Vine API][comic-vine-api] from applications written in JavaScript/TypeScript. The API provides full access to the structured-wiki content.
 
 ## Table of Contents
 
+- [Requirements](#requirements)
 - [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Key Security](#api-key-security)
+- [Rate Limiting](#rate-limiting)
+- [Error Handling](#error-handling)
+- [Advanced Usage](#advanced-usage)
 - [Roadmap](#roadmap)
 - [Comic Vine Resources](#comic-vine-resources)
 - [Usage/Examples](#usageexamples)
@@ -18,19 +29,426 @@ The Comic Vine SDK provides convenient access to the [Comic Vine API][comic-vine
 - [Run Locally](#run-locally)
 - [Authors](#authors)
 
+## Requirements
+
+- Node.js 20.0.0 or higher
+- npm, yarn, or pnpm
+
 ## Installation
 
-Install the package with:
+Choose your preferred package manager:
+
+**pnpm**
+
+```sh
+pnpm add comic-vine-sdk
+```
+
+**npm**
 
 ```sh
 npm install comic-vine-sdk
-# or
+```
+
+**yarn**
+
+```sh
 yarn add comic-vine-sdk
 ```
 
+## Quick Start
+
+```js
+import ComicVine from 'comic-vine-sdk';
+
+// Initialize the client
+const comicVine = new ComicVine('your-api-key-here');
+
+// Fetch a single publisher
+const publisher = await comicVine.publisher.retrieve(1859);
+console.log(publisher.name);
+
+// Fetch a list of issues
+const issues = await comicVine.issue.list({ limit: 10 });
+console.log(issues.data.map((issue) => issue.name));
+
+// Fetch with field limiting
+const limitedIssue = await comicVine.issue.retrieve(1234, {
+  fieldList: ['id', 'name', 'description'],
+});
+console.log(limitedIssue.name);
+```
+
+## API Key Security
+
+⚠️ **Important**: Never expose your API key in client-side code or commit it to version control.
+
+### Environment Variables (Recommended)
+
+**Create a .env file:**
+
+```bash
+# .env file
+COMIC_VINE_API_KEY=your-api-key-here
+```
+
+**Use in your application:**
+
+```js
+import ComicVine from 'comic-vine-sdk';
+
+const comicVine = new ComicVine(process.env.COMIC_VINE_API_KEY);
+```
+
+### Browser Usage
+
+The Comic Vine API doesn't support CORS. For browser usage, you'll need:
+
+- A backend proxy to make API calls
+- Server-side API key storage (never send keys to the browser)
+
+**Example proxy setup:**
+
+```js
+// Backend API route (Express.js example)
+app.get('/api/comic-vine/publisher/:id', async (req, res) => {
+  try {
+    const comicVine = new ComicVine(process.env.COMIC_VINE_API_KEY);
+    const publisher = await comicVine.publisher.retrieve(req.params.id);
+    res.json(publisher);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
 ## TypeScript Typings
 
-There's a good change you may find an issue with the typings in the API response objects. They were generated using sample data from the API, if you find a problem [open an issue](https://github.com/AllyMurray/comic-vine/issues/new) detailing the problem along with the request details so I can add that request to the sample dataset. While you wait for it to be fixed add `// @ts-expect-error` above the line causing the problem. This will allow you to compile in the meantime but will flag when the problem has been fixed.
+There's a good chance you may find an issue with the typings in the API response objects. They were generated using sample data from the API, if you find a problem [open an issue](https://github.com/AllyMurray/comic-vine/issues/new) detailing the problem along with the request details so I can add that request to the sample dataset. While you wait for it to be fixed add `// @ts-expect-error` above the line causing the problem. This will allow you to compile in the meantime but will flag when the problem has been fixed.
+
+## Rate Limiting
+
+The Comic Vine API implements rate limiting to ensure fair usage and API health for all users.
+
+> ⚠️ **Note**: This library will soon include built-in solutions for caching, request deduplication, and rate limiting. The examples below are temporary workarounds until these features are available.
+
+### Limits
+
+- **200 requests per resource per hour** - Official limit per user
+- **Velocity detection** - Prevents too many requests per second
+- **Temporary blocks** - May occur if limits are exceeded
+
+### Best Practices
+
+**Cache responses** to avoid duplicate requests:
+
+```js
+// Example: Simple in-memory cache
+const cache = new Map();
+
+async function getCachedPublisher(id) {
+  const cacheKey = `publisher-${id}`;
+
+  if (cache.has(cacheKey)) {
+    return cache.get(cacheKey);
+  }
+
+  const publisher = await comicVine.publisher.retrieve(id);
+  cache.set(cacheKey, publisher);
+
+  return publisher;
+}
+```
+
+**Implement delays** between requests:
+
+```js
+// Example: Add delay between requests
+async function fetchMultipleIssues(ids) {
+  const issues = [];
+
+  for (const id of ids) {
+    const issue = await comicVine.issue.retrieve(id);
+    issues.push(issue);
+
+    // Wait 100ms between requests
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  return issues;
+}
+```
+
+**Use pagination wisely**:
+
+```js
+// Instead of making many small requests
+const issues = await comicVine.issue.list({ limit: 100 }); // Better
+// Rather than
+const issues = await comicVine.issue.list({ limit: 10 }); // Less efficient
+```
+
+## Error Handling
+
+The Comic Vine SDK provides specific error types to help you handle different failure scenarios gracefully.
+
+### Error Types
+
+All errors extend the base `BaseError` class and include:
+
+- `message`: Human-readable error description
+- `help`: Guidance on how to resolve the issue
+
+**Common Error Types:**
+
+| Error Type                     | When It Occurs          | How to Handle                    |
+| ------------------------------ | ----------------------- | -------------------------------- |
+| `ComicVineUnauthorizedError`   | Invalid API key         | Check your API key               |
+| `ComicVineObjectNotFoundError` | Resource doesn't exist  | Verify the resource ID           |
+| `OptionsValidationError`       | Invalid request options | Check your parameters            |
+| `ComicVineGenericRequestError` | API request failed      | Retry or check API status        |
+| `ComicVineSubscriberOnlyError` | Premium content access  | Requires Comic Vine subscription |
+
+### Basic Error Handling
+
+**Simple try-catch:**
+
+```js
+import ComicVine from 'comic-vine-sdk';
+
+const comicVine = new ComicVine('your-api-key-here');
+
+try {
+  const publisher = await comicVine.publisher.retrieve(999999);
+  console.log(publisher.name);
+} catch (error) {
+  console.error('Error:', error.message);
+  console.error('Help:', error.help);
+}
+```
+
+### Specific Error Handling
+
+**Handle different error types:**
+
+```js
+import ComicVine, {
+  ComicVineUnauthorizedError,
+  ComicVineObjectNotFoundError,
+  OptionsValidationError,
+} from 'comic-vine-sdk';
+
+const comicVine = new ComicVine('your-api-key-here');
+
+try {
+  const issue = await comicVine.issue.retrieve(999999);
+} catch (error) {
+  if (error instanceof ComicVineUnauthorizedError) {
+    console.error(
+      'Invalid API key. Get one from: https://comicvine.gamespot.com/api/',
+    );
+  } else if (error instanceof ComicVineObjectNotFoundError) {
+    console.error('Issue not found. Please check the ID.');
+  } else if (error instanceof OptionsValidationError) {
+    console.error('Invalid request parameters:', error.message);
+  } else {
+    console.error('Unexpected error:', error.message);
+  }
+}
+```
+
+### Robust Error Handling with Retry
+
+**Implement retry logic for transient errors:**
+
+```js
+async function fetchWithRetry(fetchFn, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await fetchFn();
+    } catch (error) {
+      // Don't retry on client errors
+      if (
+        error instanceof ComicVineUnauthorizedError ||
+        error instanceof ComicVineObjectNotFoundError ||
+        error instanceof OptionsValidationError
+      ) {
+        throw error;
+      }
+
+      // Retry on server errors
+      if (attempt === maxRetries) {
+        throw error;
+      }
+
+      // Wait before retrying (exponential backoff)
+      const delay = Math.pow(2, attempt) * 1000;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+
+// Usage
+try {
+  const publisher = await fetchWithRetry(() =>
+    comicVine.publisher.retrieve(1859),
+  );
+  console.log(publisher.name);
+} catch (error) {
+  console.error('Failed after retries:', error.message);
+}
+```
+
+### Error Handling in Lists
+
+**Handle errors when processing multiple items:**
+
+```js
+async function fetchMultipleIssues(ids) {
+  const results = [];
+  const errors = [];
+
+  for (const id of ids) {
+    try {
+      const issue = await comicVine.issue.retrieve(id);
+      results.push({ id, issue });
+    } catch (error) {
+      errors.push({ id, error: error.message });
+    }
+  }
+
+  return { results, errors };
+}
+
+// Usage
+const { results, errors } = await fetchMultipleIssues([1, 2, 999999]);
+console.log(`Successfully fetched: ${results.length}`);
+console.log(`Errors: ${errors.length}`);
+```
+
+## Advanced Usage
+
+### Available Filters
+
+Common filter options for list methods:
+
+**Filter by name:**
+
+```js
+const issues = await comicVine.issue.list({
+  filter: { name: 'The Boys' },
+});
+```
+
+**Filter by date range:**
+
+```js
+const recentIssues = await comicVine.issue.list({
+  filter: {
+    date_added: '2024-01-01 00:00:00|2024-12-31 23:59:59',
+  },
+});
+```
+
+**Multiple filters:**
+
+```js
+const filteredIssues = await comicVine.issue.list({
+  filter: {
+    name: 'Spider-Man',
+    date_added: '2024-01-01 00:00:00|2024-12-31 23:59:59',
+  },
+});
+```
+
+**Publisher-specific content:**
+
+```js
+const marvelIssues = await comicVine.issue.list({
+  filter: {
+    publisher: 'Marvel Comics',
+  },
+  limit: 50,
+});
+```
+
+### Common Field Lists
+
+**Minimal issue data:**
+
+```js
+const lightIssue = await comicVine.issue.retrieve(1234, {
+  fieldList: ['id', 'name', 'issue_number'],
+});
+```
+
+**Full issue details:**
+
+```js
+const fullIssue = await comicVine.issue.retrieve(1234, {
+  fieldList: ['id', 'name', 'description', 'cover_date', 'image', 'volume'],
+});
+```
+
+**Character essentials:**
+
+```js
+const character = await comicVine.character.retrieve(1234, {
+  fieldList: ['id', 'name', 'description', 'image', 'publisher', 'powers'],
+});
+```
+
+**Publisher overview:**
+
+```js
+const publisher = await comicVine.publisher.retrieve(1234, {
+  fieldList: [
+    'id',
+    'name',
+    'description',
+    'image',
+    'date_added',
+    'location_city',
+  ],
+});
+```
+
+### Sorting and Ordering
+
+**Sort by date (newest first):**
+
+```js
+const recentIssues = await comicVine.issue.list({
+  sort: 'date_added:desc',
+  limit: 10,
+});
+```
+
+**Sort by name:**
+
+```js
+const sortedCharacters = await comicVine.character.list({
+  sort: 'name:asc',
+  limit: 100,
+});
+```
+
+### Complex Queries
+
+**Combine multiple options:**
+
+```js
+const complexQuery = await comicVine.issue.list({
+  filter: {
+    name: 'Spider-Man',
+    date_added: '2024-01-01 00:00:00|2024-12-31 23:59:59',
+  },
+  fieldList: ['id', 'name', 'issue_number', 'cover_date', 'image'],
+  sort: 'cover_date:desc',
+  limit: 25,
+  offset: 0,
+});
+```
 
 ## Roadmap
 
@@ -82,7 +500,7 @@ const comicVine = new ComicVine('your-api-key-here');
 
 comicVine.publisher
   .retrieve(1859)
-  .then((customer) => console.log(customer.id))
+  .then((publisher) => console.log(publisher.id))
   .catch((error) => console.error(error));
 ```
 
@@ -160,7 +578,7 @@ const comicVine = new ComicVine('your-api-key-here');
 
 ### Fetch a resource list
 
-All resources have a retrieve method, the following example retrieves a list of publishers
+All resources have a list method, the following example retrieves a list of publishers
 
 ```js
 import ComicVine from 'comic-vine-sdk';
@@ -188,7 +606,7 @@ const comicVine = new ComicVine('your-api-key-here');
 
 (async () => {
   try {
-    const issue = await comicVine.issue.retrieve(id, {
+    const issue = await comicVine.issue.retrieve(1234, {
       fieldList: ['id', 'name', 'description'],
     });
 
@@ -219,18 +637,22 @@ const comicVine = new ComicVine('your-api-key-here');
 
 (async () => {
   try {
-    const limit: 50;
-    const filter: { name: 'The Boys' },
+    const limit = 50;
+    const filter = { name: 'The Boys' };
 
     // Retrieve the first 50 issues of The Boys (Page 1)
     const issuesPage1 = await comicVine.issue.list({ limit, filter });
     console.log(`Total issues: ${issuesPage1.data.length}`);
-    console.log(issuesPage1.data.map(issue => issue.name).join(', '));
+    console.log(issuesPage1.data.map((issue) => issue.name).join(', '));
 
     // Retrieve the next 50 issues of The Boys (Page 2)
-    const issuesPage2 = await comicVine.issue.list({ limit, filter, offset: 50 });
+    const issuesPage2 = await comicVine.issue.list({
+      limit,
+      filter,
+      offset: 50,
+    });
     console.log(`Total issues: ${issuesPage2.data.length}`);
-    console.log(issuesPage2.data.map(issue => issue.name).join(', '));
+    console.log(issuesPage2.data.map((issue) => issue.name).join(', '));
   } catch (error) {
     console.error(error);
   }
@@ -256,7 +678,7 @@ const comicVine = new ComicVine('your-api-key-here');
 
     let issueNames = [];
     for await (const issue of comicVine.issue.list(listOptions)) {
-      issueName.push(issue.name);
+      issueNames.push(issue.name);
     }
 
     console.log(`Total issues: ${issueNames.length}`);

package/package.json

@@ -66,12 +66,12 @@
     "metadata"
   ],
   "engines": {
-    "node": ">= 18.0.0"
+    "node": ">= 20.0.0"
   },
   "main": "lib/cjs/index.js",
   "license": "MIT",
   "homepage": "https://github.com/AllyMurray/comic-vine#readme",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "bugs": {
     "url": "https://github.com/AllyMurray/comic-vine/issues"
   },