polymarket-api/CONTRIBUTING.md

Node.js SDK for querying Polymarket prediction market data. Get new prediction markets, resolved predictions, position tokens, and trading data from Polymarket using Bitquery APIs.

# Contributing to Polymarket API

Thank you for your interest in contributing to the Polymarket API npm package! This document provides guidelines and instructions for contributing.

## 🤝 How to Contribute

We welcome contributions of all kinds, including:

- Bug fixes
- New features
- Documentation improvements
- Code optimizations
- Test coverage
- Examples and use cases

## 📋 Getting Started

### Prerequisites

- Node.js (v14 or higher)
- npm or yarn
- Git

### Development Setup

1. **Fork the repository**

2. **Clone your fork**
   ```bash
   git clone https://github.com/bitquery/polymarket-api
   cd polymarket-api
   ```

3. **Install dependencies**
   ```bash
   npm install
   ```

4. **Create a branch**
   ```bash
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   ```

## 🔧 Development Guidelines

### Code Style

- Follow existing code style and formatting
- Use ES6+ features where appropriate
- Add JSDoc comments for all functions
- Keep functions focused and single-purpose
- Use meaningful variable and function names

### Function Documentation

All functions must include JSDoc comments following this format:

```javascript
/**
 * functionName
 * Brief description of what the function does
 * @param {type} paramName - parameter description
 * @param {type} [optionalParam] - optional parameter description
 * @returns {type} - return value description
 */
```

### Error Handling

- Always use try-catch blocks for async operations
- Provide meaningful error messages
- Re-throw errors to allow caller handling
- Document potential errors in JSDoc comments

### Testing

- Add tests for new features
- Ensure existing tests pass
- Test error cases and edge conditions
- Test with different parameter combinations

## 📝 Commit Guidelines

### Commit Message Format

Use clear, descriptive commit messages:

```
feat: add function to get market prices
fix: handle null responses in getNewQuestions
docs: update README with new examples
refactor: simplify query construction
test: add tests for streaming functions
```

### Commit 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

## 🚀 Pull Request Process

1. **Update Documentation**
   - Update README.md if adding new features
   - Add JSDoc comments for new functions
   - Update examples if API changes

2. **Test Your Changes**
   - Test all new functionality
   - Ensure existing functionality still works
   - Test error cases

3. **Create Pull Request**
   - Use a clear, descriptive title
   - Provide a detailed description of changes
   - Reference any related issues
   - Include examples of how to use new features

4. **PR Checklist**
   - [ ] Code follows project style guidelines
   - [ ] All functions have JSDoc comments
   - [ ] Error handling is implemented
   - [ ] Documentation is updated
   - [ ] Tests pass (if applicable)
   - [ ] No console.log or debug code left

## 🎯 Adding New Features

### Query Functions

When adding a new query function:

1. Create the query file in `queries/` directory
2. Export both query and stream versions
3. Add the function to `index.js` with:
   - Try-catch error handling
   - JSDoc documentation
   - Export in the export statement

Example structure:

```javascript
// queries/newFeatureQuery.js
export const newFeatureQuery = (params) => {
    // GraphQL query
};

export const newFeatureStream = {
    // Stream configuration
};
```

```javascript
// index.js
/**
 * getNewFeature
 * Description of the new feature
 * @param {string} token - your Bitquery OAuth token
 * @param {type} param - parameter description
 * @returns {Promise<Array>} - return description
 */
const getNewFeature = async (token, param) => {
    try {
        const result = await queryRunner(newFeatureQuery(param), token);
        return result.data.EVM.Events;
    } catch (error) {
        throw error;
    }
}
```

### Streaming Functions

When adding streaming functionality:

1. Ensure the stream query is exported from the query file
2. Add streaming function with proper options handling
3. Include error handling and documentation

## 🐛 Reporting Bugs

### Before Reporting

1. Check if the bug has already been reported
2. Verify it's not a configuration issue
3. Test with the latest version

### Bug Report Template

```markdown
**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Call function '...'
2. With parameters '...'
3. See error

**Expected behavior**
What you expected to happen.

**Error message**
Full error message if applicable.

**Environment:**
- Node.js version:
- Package version:
- Bitquery token status:

**Additional context**
Any other relevant information.
```

## 💡 Feature Requests

We welcome feature requests! When suggesting a feature:

1. **Check existing issues** - Your feature might already be requested
2. **Describe the use case** - Explain why this feature would be useful
3. **Provide examples** - Show how you'd use the feature
4. **Consider implementation** - If possible, suggest how it might work

## 📚 Documentation Contributions

Documentation improvements are highly valued:

- Fix typos and grammar
- Improve clarity and examples
- Add use cases and tutorials
- Translate documentation (if applicable)
- Update outdated information

## 🔍 Code Review

All contributions go through code review:

- Be open to feedback and suggestions
- Respond to review comments promptly
- Make requested changes or discuss alternatives
- Be respectful and constructive in discussions

## 📜 License

By contributing, you agree that your contributions will be licensed under the same license as the project (ISC).

## 🙏 Recognition

Contributors will be recognized in:
- README.md contributors section (if added)
- Release notes for significant contributions
- Project documentation

## ❓ Questions?

If you have questions about contributing:

1. Check existing issues and discussions
2. Review the codebase and examples
3. Open an issue with your question
4. Reach out to maintainers

## 🎉 Thank You!

Your contributions make this project better for everyone. Thank you for taking the time to contribute!

---

**Remember**: Good contributions are not just about code - they're about making the project more useful, reliable, and accessible for all users.