Skip to content

Commit b8db139

Browse files
jesse-validkitjesse-validkit
committed
feat: add TypeScript SDK for ValidKit API
Full TypeScript implementation: - Complete type definitions and IntelliSense support - Async/await patterns for modern JavaScript - Batch processing up to 10K emails - Automatic retries with exponential backoff - Smart error handling and recovery - Comprehensive examples for all use cases - Integration guides for popular frameworks - Optimized for AI agents with token-efficient responses
0 parents  commit b8db139

15 files changed

+2713
-0
lines changed

‎.env.example‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# ValidKit API Configuration
2+
# Get your API key at https://validkit.com
3+
4+
# Required: Your ValidKit API key
5+
VALIDKIT_API_KEY=your_api_key_here
6+
7+
# Optional: API endpoint (defaults to production)
8+
# VALIDKIT_API_URL=https://api.validkit.com

‎.gitignore‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Dependencies
2+
node_modules/
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
8+
# Build output
9+
dist/
10+
lib/
11+
*.tgz
12+
13+
# Environment files
14+
.env
15+
.env.*
16+
!.env.example
17+
18+
# OS files
19+
.DS_Store
20+
Thumbs.db
21+
22+
# IDE
23+
.vscode/
24+
.idea/
25+
*.swp
26+
*.swo
27+
28+
# Coverage
29+
coverage/
30+
.nyc_output/
31+
32+
# Private keys or credentials
33+
*.pem
34+
*.key
35+
*.cert
36+
*credentials*
37+
*secrets*
38+
*.private
39+
40+
# Test artifacts
41+
*.test.js
42+
*.spec.js
43+
44+
# Temporary files
45+
*.tmp
46+
*.temp
47+
.cache/

‎CONTRIBUTING.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Contributing to ValidKit TypeScript SDK
2+
3+
Thank you for your interest in contributing to ValidKit! We welcome contributions from the community.
4+
5+
## Commit Message Convention
6+
7+
We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for clear and consistent commit history.
8+
9+
### Format
10+
```
11+
<type>[optional scope]: <description>
12+
13+
[optional body]
14+
15+
[optional footer(s)]
16+
```
17+
18+
### Types
19+
- `feat`: New feature
20+
- `fix`: Bug fix
21+
- `docs`: Documentation only changes
22+
- `style`: Code style changes (formatting, missing semicolons, etc)
23+
- `refactor`: Code change that neither fixes a bug nor adds a feature
24+
- `perf`: Performance improvements
25+
- `test`: Adding missing tests or correcting existing tests
26+
- `build`: Changes that affect the build system or external dependencies
27+
- `ci`: Changes to CI configuration files and scripts
28+
- `chore`: Other changes that don't modify src or test files
29+
30+
### Examples
31+
```
32+
feat: add support for custom timeout configuration
33+
34+
fix: handle network errors gracefully in batch processing
35+
36+
docs: improve TypeScript examples in README
37+
```
38+
39+
## Code of Conduct
40+
41+
By participating in this project, you agree to abide by our Code of Conduct:
42+
- Be respectful and inclusive
43+
- Welcome newcomers and help them get started
44+
- Focus on constructive criticism
45+
- Respect differing viewpoints and experiences
46+
47+
## How to Contribute
48+
49+
### Reporting Bugs
50+
51+
1. Check if the bug has already been reported in [Issues](https://github.com/validkit/typescript-sdk/issues)
52+
2. If not, create a new issue with:
53+
- Clear title and description
54+
- Steps to reproduce
55+
- Expected vs actual behavior
56+
- Node.js/TypeScript version
57+
- Relevant code snippets
58+
59+
### Suggesting Features
60+
61+
1. Check if the feature has been requested
62+
2. Open a new issue with:
63+
- Clear use case
64+
- Proposed API design
65+
- Benefits to users
66+
67+
### Pull Request Guidelines
68+
69+
#### Before Creating a PR
70+
71+
1. Fork the repository and clone locally
72+
2. Create a feature branch from `main`:
73+
```bash
74+
git checkout -b feat/your-feature-name
75+
# or
76+
git checkout -b fix/your-bug-fix
77+
```
78+
79+
3. Make your changes following TypeScript best practices
80+
4. Write/update tests to maintain coverage
81+
5. Run all checks:
82+
```bash
83+
npm run typecheck
84+
npm run lint
85+
npm test
86+
npm run build
87+
```
88+
89+
#### Commit Your Changes
90+
91+
Follow our commit convention:
92+
```bash
93+
# Single line commit
94+
git commit -m "feat: add retry configuration options"
95+
96+
# Multi-line commit with details
97+
git commit -m "feat: add custom headers support" -m "- Allow setting custom headers via options
98+
- Add X-Trace-ID header for request tracking
99+
- Update TypeScript definitions
100+
- Add examples to documentation"
101+
```
102+
103+
#### PR Title and Description
104+
105+
Your PR title should follow the same convention as commits:
106+
- `feat: add WebSocket support for real-time validation`
107+
- `fix: handle network timeouts gracefully`
108+
- `docs: improve TypeScript examples`
109+
- `perf: optimize batch processing memory usage`
110+
111+
In your PR description, include:
112+
113+
```markdown
114+
## What
115+
Brief description of what this PR does
116+
117+
## Why
118+
The problem it solves or feature it adds
119+
Closes #[issue number]
120+
121+
## How
122+
- Technical approach taken
123+
- Any design decisions made
124+
- Breaking changes (if any)
125+
126+
## Testing
127+
- Unit tests added/updated
128+
- Manual testing performed
129+
- Performance impact (if relevant)
130+
131+
## Checklist
132+
- [ ] Tests pass locally
133+
- [ ] TypeScript types are correct
134+
- [ ] Documentation updated
135+
- [ ] No breaking changes (or documented)
136+
```
137+
138+
#### After Creating Your PR
139+
140+
1. Ensure all GitHub Actions checks pass
141+
2. Respond to code review feedback promptly
142+
3. Keep your branch up to date with `main`
143+
4. Be prepared to make changes based on feedback
144+
145+
### Development Setup
146+
147+
```bash
148+
# Clone your fork
149+
git clone https://github.com/YOUR_USERNAME/typescript-sdk.git
150+
cd typescript-sdk
151+
152+
# Install dependencies
153+
npm install
154+
155+
# Build the project
156+
npm run build
157+
158+
# Run tests in watch mode
159+
npm run test:watch
160+
```
161+
162+
### Testing
163+
164+
```bash
165+
# Run all tests
166+
npm test
167+
168+
# Run tests with coverage
169+
npm run test:coverage
170+
171+
# Run specific test file
172+
npm test -- src/client.test.ts
173+
174+
# Run tests in watch mode
175+
npm run test:watch
176+
```
177+
178+
### Code Style
179+
180+
We use:
181+
- ESLint for linting
182+
- Prettier for formatting
183+
- TypeScript strict mode
184+
185+
Run all checks:
186+
```bash
187+
# Run linter
188+
npm run lint
189+
190+
# Fix linting issues
191+
npm run lint:fix
192+
193+
# Format code
194+
npm run format
195+
196+
# Type check
197+
npm run type-check
198+
```
199+
200+
### Building
201+
202+
```bash
203+
# Build for production
204+
npm run build
205+
206+
# Build in watch mode
207+
npm run build:watch
208+
209+
# Build for different targets
210+
npm run build:node # Node.js
211+
npm run build:browser # Browser bundle
212+
```
213+
214+
### Documentation
215+
216+
- Add JSDoc comments to all public APIs
217+
- Update README.md for user-facing changes
218+
- Add examples for new features
219+
- Ensure TypeScript types are well-documented
220+
221+
### Commit Messages
222+
223+
Follow conventional commits:
224+
- `feat:` New feature
225+
- `fix:` Bug fix
226+
- `docs:` Documentation changes
227+
- `test:` Test additions/changes
228+
- `refactor:` Code refactoring
229+
- `style:` Code style changes
230+
- `chore:` Maintenance tasks
231+
- `perf:` Performance improvements
232+
233+
Examples:
234+
```
235+
feat: add webhook support for batch processing
236+
fix: handle rate limit errors correctly
237+
docs: update batch verification examples
238+
perf: optimize batch processing for large datasets
239+
```
240+
241+
## API Design Guidelines
242+
243+
- Keep the API surface small and focused
244+
- Prioritize developer experience
245+
- Maintain backward compatibility
246+
- Use TypeScript types for better IDE support
247+
- Follow existing naming conventions
248+
249+
## Testing Guidelines
250+
251+
- Write tests for all new features
252+
- Maintain >90% code coverage
253+
- Test edge cases and error scenarios
254+
- Use descriptive test names
255+
- Mock external dependencies
256+
257+
## Release Process
258+
259+
1. Update version in `package.json`
260+
2. Update CHANGELOG.md
261+
3. Run `npm run build`
262+
4. Create release PR
263+
5. After merge, tag release: `git tag v1.2.3`
264+
6. Push tags: `git push --tags`
265+
7. GitHub Actions will publish to npm
266+
267+
## Questions?
268+
269+
- Open an issue for questions
270+
- Join our [Discord](https://discord.gg/validkit)
271+
- Email: developers@validkit.com
272+
273+
Thank you for contributing! 🎉

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 ValidKit
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)