feat: add location data with schema validation

[PatrickHeneise]

Summary

Adds location data fetching with schema validation for consistent
venue/location data structure.

Closes #9

Changes

• ✨ Add getLocations() function with schema validation
• 📋 Define consistent location schema
• ✅ Validate required and optional fields
• 🔧 Support custom fields while normalizing core schema
• ✅ Add comprehensive test suite
• 📚 Update README with schema documentation

API Usage

import { getLocations } from 'gitevents-fetch'

const result = await getLocations('org', 'events')

// Access validated locations
result.locations.forEach(location => {
  console.log(location.name, location.coordinates)
})

// Check for validation errors
if (result.errors) {
  console.log('Invalid locations:', result.errors)
}

Location Schema

Required fields:

• id (string) - Unique identifier
• name (string) - Location name

Optional fields:

• address (string) - Physical address
• coordinates (object) - { lat: number, lng: number }
• url (string) - Location website
• what3words (string) - what3words address
• description (string) - Description
• capacity (number) - Venue capacity
• accessibility (string) - Accessibility info
• Custom fields are preserved

Features

• ✅ Schema validation for all locations
• ✅ Returns valid locations + validation errors
• ✅ Normalizes optional fields to null if missing
• ✅ Preserves custom fields beyond core schema
• ✅ Support custom file names and branches
• ✅ Comprehensive error reporting per location

Test Plan

• Unit tests for parameter validation
• Unit tests for valid location data
• Unit tests for minimal location data
• Unit tests for validation errors
• Unit tests for custom fields
• Unit tests for non-array data rejection
• Unit tests for custom file name/branch
• README documentation with examples

🤖 Generated with Claude Code

[Copilot]

Pull Request Overview

This PR adds location management functionality to the gitevents-fetch library, enabling users to fetch and validate venue/location data from GitHub repositories. The implementation introduces a new getLocations API function with schema validation and comprehensive test coverage.

Key Changes:

• Added getLocations function with location schema validation (id, name, coordinates, etc.)
• Comprehensive test suite covering parameter validation, data normalization, custom fields, and error handling
• Updated package version from 0.0.3-dev to 0.0.4

Reviewed Changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/locations.js	Implements location fetching and validation logic with schema normalization
src/index.js	Exports the new getLocations function as part of the public API
test/locations.test.js	Comprehensive test suite covering all location functionality scenarios
package.json	Version bump to 0.0.4
package-lock.json	Lock file updated for version 0.0.4
README.md	Documentation for the new getLocations API including schema details and examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The imported module './files.js' does not exist in the codebase. This will cause a runtime error when the getLocations function is called. Either create the missing files.js module or replace this with the appropriate file-fetching implementation using the graphql client directly.

[Copilot]

The validation logic doesn't check if both lat and lng exist when coordinates is provided. If coordinates is an object but missing lat or lng properties, the validation will pass (no error added) but lines 86-87 will attempt to destructure undefined values, resulting in a location object with { lat: undefined, lng: undefined } instead of null.

[Copilot]

The comment states 'Mock getFile function' but the code that follows actually mocks the graphql function, not getFile. Update comment to 'Mock graphql function for file fetching' to accurately describe what createMockGraphql does.

Suggested change

	// Mock getFile function
	// Mock graphql function for file fetching

[PatrickHeneise]

Review Updates

Addressed Copilot review comments:

✅ Fixed coordinates validation - Added explicit checks for missing lat or lng properties in coordinates object to prevent undefined values

✅ Fixed test comment - Updated comment to accurately describe mocking graphql function instead of getFile

✅ Added test case - Added comprehensive test for missing lat/lng in coordinates

Dependency Note

⚠️ This PR depends on #12 (File Fetching Support) being merged first, as it imports getFile from ./files.js.

The files.js module exists in PR #12 and provides the file fetching functionality that this locations feature builds upon.

Suggested merge order:

1. Merge PR feat: add file fetching support #12 first
2. Rebase/merge this PR feat: add location data with schema validation #15 to include the files.js dependency
3. Then this PR can be merged

Alternatively, all file-fetching related PRs (#5, #12) can be reviewed together as they form the foundation for this location data feature.

[Copilot]

Pull Request Overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Duplicated code: The validateParams function is duplicated from src/lib/validateParams.js. Import and use the existing utility function instead of redefining it.

Suggested change

	function validateParams(params) {
	const missing = []
	for (const [key, value] of Object.entries(params)) {
	if (!value) missing.push(key)
	}
	if (missing.length > 0) {
	throw new Error(`Missing required parameters: ${missing.join(', ')}`)
	}
	}
	import { validateParams } from './lib/validateParams.js'

[Copilot]

Incorrect falsy value handling: Using || will convert capacity: 0 to null. Use nullish coalescing (??) instead to preserve zero values.

Suggested change

	capacity: location.capacity || null,
	capacity: location.capacity ?? null,

[github-actions]

🎉 This PR is included in version 1.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀