Skip to content

Commit 75175ae

Browse files
bshahinbshahin
committed
Add CaptchaAI Quickstart example with multi-language support
- Created README.md for the CaptchaAI Examples repository with setup instructions and repository structure. - Added .env.example for the captchaai-quickstart article to define required environment variables. - Included .gitignore for the captchaai-quickstart article to exclude sensitive files and directories. - Developed README.md for the captchaai-quickstart article detailing prerequisites, setup, and usage instructions. - Implemented Node.js example with package.json and solve.js for solving Cloudflare Turnstile. - Created PHP example with composer.json and solve.php for solving Cloudflare Turnstile. - Developed Python example with requirements.txt and solve.py for solving Cloudflare Turnstile. - Added starter templates for Node.js and PHP examples to facilitate new example creation.
0 parents  commit 75175ae

19 files changed

Lines changed: 1436 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
lint-python:
11+
name: Lint Python examples
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- uses: actions/setup-python@v5
17+
with:
18+
python-version: "3.11"
19+
20+
- name: Install linting tools
21+
run: pip install ruff
22+
23+
- name: Check Python syntax and style
24+
run: ruff check articles/*/python/ --select=E,F,W --ignore=E501
25+
26+
lint-node:
27+
name: Lint Node.js examples
28+
runs-on: ubuntu-latest
29+
steps:
30+
- uses: actions/checkout@v4
31+
32+
- uses: actions/setup-node@v4
33+
with:
34+
node-version: "20"
35+
36+
- name: Check JavaScript syntax
37+
run: |
38+
npm install -g acorn
39+
find articles/*/node -name "*.js" -exec acorn --ecma2020 {} \;
40+
41+
lint-php:
42+
name: Lint PHP examples
43+
runs-on: ubuntu-latest
44+
steps:
45+
- uses: actions/checkout@v4
46+
47+
- uses: shivammathur/setup-php@v2
48+
with:
49+
php-version: "8.2"
50+
51+
- name: Check PHP syntax
52+
run: find articles/*/php -name "*.php" -exec php -l {} \;
53+
54+
validate-structure:
55+
name: Validate example pack structure
56+
runs-on: ubuntu-latest
57+
steps:
58+
- uses: actions/checkout@v4
59+
60+
- name: Check required files
61+
run: |
62+
errors=0
63+
for dir in articles/*/; do
64+
slug=$(basename "$dir")
65+
if [ ! -f "$dir/README.md" ]; then
66+
echo "ERROR: $dir is missing README.md"
67+
errors=$((errors + 1))
68+
fi
69+
if [ ! -f "$dir/.env.example" ]; then
70+
echo "ERROR: $dir is missing .env.example"
71+
errors=$((errors + 1))
72+
fi
73+
# Check that at least one language directory exists
74+
has_lang=0
75+
for lang in python node php go; do
76+
if [ -d "$dir/$lang" ]; then
77+
has_lang=1
78+
fi
79+
done
80+
if [ $has_lang -eq 0 ]; then
81+
echo "ERROR: $dir has no language directory (python/node/php/go)"
82+
errors=$((errors + 1))
83+
fi
84+
done
85+
if [ $errors -gt 0 ]; then
86+
echo "Found $errors structural errors"
87+
exit 1
88+
fi
89+
echo "All example packs have valid structure"
90+
91+
- name: Check no .env files committed
92+
run: |
93+
if find . -name ".env" -not -path "./.git/*" | grep -q .; then
94+
echo "ERROR: .env files should not be committed"
95+
find . -name ".env" -not -path "./.git/*"
96+
exit 1
97+
fi
98+
echo "No .env files found (good)"
99+
100+
- name: Check README links to blog
101+
run: |
102+
errors=0
103+
for dir in articles/*/; do
104+
slug=$(basename "$dir")
105+
readme="$dir/README.md"
106+
if [ -f "$readme" ]; then
107+
if ! grep -q "blog.captchaai.com" "$readme"; then
108+
echo "WARNING: $readme does not link to blog.captchaai.com"
109+
errors=$((errors + 1))
110+
fi
111+
fi
112+
done
113+
if [ $errors -gt 0 ]; then
114+
echo "Found $errors README files without blog links"
115+
exit 1
116+
fi
117+
echo "All READMEs link to the blog"

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.env
2+
__pycache__/
3+
*.pyc
4+
node_modules/
5+
vendor/
6+
composer.lock
7+
package-lock.json
8+
.DS_Store
9+
Thumbs.db

‎CONTRIBUTING.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Contributing to CaptchaAI Examples
2+
3+
## Overview
4+
5+
This repository holds full working code examples that accompany [CaptchaAI blog articles](https://blog.captchaai.com). Each example is a complete, runnable project — not a snippet.
6+
7+
## When to add an example
8+
9+
An example pack should be created when:
10+
11+
- The blog article type is: API tutorial, Tutorial, Integration guide, Framework, DevOps tutorial, Project tutorial, or Use case guide
12+
- The example provides clear value beyond the in-article code snippets
13+
- The article has a complete draft (not a placeholder)
14+
- The article's `editorial_review` is not `manual-only`
15+
16+
Do **not** create an example pack when:
17+
18+
- The in-article snippet is sufficient on its own
19+
- The article is a comparison, explainer, or reference with no meaningful runnable code
20+
- The example would be shallow or trivial (single API call with no workflow)
21+
22+
## Structure
23+
24+
Every example pack lives under `articles/{slug}/` and must contain:
25+
26+
```
27+
articles/{slug}/
28+
README.md # Setup, usage, expected output, troubleshooting
29+
.env.example # All required environment variables
30+
.gitignore # Excludes .env, node_modules, vendor, __pycache__
31+
python/ # Python implementation (if applicable)
32+
solve.py
33+
requirements.txt
34+
node/ # Node.js implementation (if applicable)
35+
solve.js
36+
package.json
37+
php/ # PHP implementation (if applicable)
38+
solve.php
39+
composer.json
40+
```
41+
42+
## Code requirements
43+
44+
### API endpoints
45+
46+
- Submit: `https://ocr.captchaai.com/in.php`
47+
- Poll: `https://ocr.captchaai.com/res.php`
48+
- Always use `json=1` for structured responses
49+
50+
### Credentials
51+
52+
- Load from `.env` file using dotenv
53+
- Use `YOUR_API_KEY` as the placeholder in `.env.example`
54+
- Never commit real API keys
55+
56+
### Polling
57+
58+
- Wait 15-20 seconds before first poll
59+
- Poll every 5 seconds
60+
- Handle `CAPCHA_NOT_READY` as normal in-progress
61+
- Implement a maximum timeout (default: 120 seconds)
62+
63+
### Error handling
64+
65+
Handle all documented error categories:
66+
- Auth errors → clear message about API key
67+
- Balance errors → message to top up
68+
- Input errors → parameter validation message
69+
- Transient errors → retry with exponential backoff
70+
- Solve errors → log and suggest parameter check
71+
72+
### Expected output
73+
74+
Include a section in the README showing what a successful run looks like.
75+
76+
## README template
77+
78+
Every example README must include:
79+
80+
1. Title (matches the article)
81+
2. Description
82+
3. Link to the blog article
83+
4. Prerequisites
84+
5. Setup instructions (clone → install → configure → run)
85+
6. Environment variables table
86+
7. How it works
87+
8. Expected output
88+
9. Common errors table
89+
10. Troubleshooting
90+
11. API docs link
91+
12. Related examples
92+
93+
## Linking
94+
95+
- Example README links to: blog article, API docs, related examples
96+
- Blog article links to: example repo path
97+
98+
## Quality checklist
99+
100+
Before submitting:
101+
102+
- [ ] Code uses real CaptchaAI API endpoints
103+
- [ ] `.env.example` lists all required variables
104+
- [ ] Setup instructions work from clone to first run
105+
- [ ] Error handling covers all documented error categories
106+
- [ ] Expected output is accurate
107+
- [ ] README links back to the blog article
108+
- [ ] No real API keys or secrets in the code
109+
- [ ] Code follows the language's standard style guide
110+
111+
## Scaffolding
112+
113+
New example packs are scaffolded using the tool in the `cai_content` repository:
114+
115+
```bash
116+
python scripts/scaffold_example_pack.py articles/{slug}.md --examples-repo ../CaptchaAI-Examples
117+
```
118+
119+
This generates the directory structure, README template, `.env.example`, and starter code files.
120+
121+
## Languages
122+
123+
- Primary language is selected based on the article's ICP (Ideal Customer Profile)
124+
- 1 canonical full implementation per example
125+
- Optionally 2 languages for high-value articles
126+
- Do not force all languages for every example

‎README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# CaptchaAI Examples
2+
3+
Full working code examples for the [CaptchaAI](https://captchaai.com) CAPTCHA solving API.
4+
5+
Every example in this repository is a complete, runnable project with setup instructions, environment configuration, polling, retries, error handling, and expected output.
6+
7+
## Quick start
8+
9+
1. Get your API key from [captchaai.com](https://captchaai.com)
10+
2. Clone this repository:
11+
```bash
12+
git clone https://github.com/CaptchaAI/CaptchaAI-Examples.git
13+
cd CaptchaAI-Examples
14+
```
15+
3. Pick an example from the `articles/` directory
16+
4. Follow the README inside that example folder
17+
18+
## Repository structure
19+
20+
```
21+
CaptchaAI-Examples/
22+
articles/ # Full example packs, one per article
23+
{slug}/
24+
README.md # Setup, usage, expected output, troubleshooting
25+
.env.example # Required environment variables
26+
python/ # Python implementation
27+
node/ # Node.js implementation
28+
php/ # PHP implementation
29+
templates/ # Starter templates for new examples
30+
python-basic/
31+
node-basic/
32+
php-basic/
33+
```
34+
35+
## Examples
36+
37+
| Example | CAPTCHA Type | Languages | Article |
38+
|---------|-------------|-----------|---------|
39+
| [captchaai-quickstart](articles/captchaai-quickstart/) | reCAPTCHA v2 | Python, Node.js, PHP | [Blog](https://blog.captchaai.com/captchaai-quickstart) |
40+
41+
_More examples are added as articles are published. Check back regularly._
42+
43+
## How each example works
44+
45+
Every example follows the same pattern:
46+
47+
1. **Submit** — Send CAPTCHA parameters to `https://ocr.captchaai.com/in.php`
48+
2. **Wait** — Pause 15-20 seconds for initial processing
49+
3. **Poll** — Check `https://ocr.captchaai.com/res.php` every 5 seconds
50+
4. **Result** — Receive the solved token for injection
51+
52+
## Prerequisites
53+
54+
- A CaptchaAI account with API key ([sign up](https://captchaai.com))
55+
- Python 3.8+, Node.js 16+, or PHP 8.0+ depending on the example
56+
57+
## Environment setup
58+
59+
Every example uses a `.env` file for configuration. Copy `.env.example` and add your credentials:
60+
61+
```bash
62+
cp .env.example .env
63+
# Edit .env with your API key and target page details
64+
```
65+
66+
**Never commit your `.env` file.** It contains your API key.
67+
68+
## Error handling
69+
70+
Every example handles these error categories:
71+
72+
| Category | Errors | What happens |
73+
|----------|--------|-------------|
74+
| Auth | `ERROR_WRONG_USER_KEY`, `ERROR_KEY_DOES_NOT_EXIST` | Clear message about API key |
75+
| Balance | `ERROR_ZERO_BALANCE` | Message to top up account |
76+
| Input | `ERROR_PAGEURL`, `ERROR_WRONG_GOOGLEKEY` | Parameter validation message |
77+
| Transient | `ERROR_SERVER_ERROR` | Automatic retry with backoff |
78+
| Solve | `ERROR_CAPTCHA_UNSOLVABLE` | Log and suggest parameter check |
79+
| Polling | `CAPCHA_NOT_READY` | Normal — keeps polling |
80+
81+
## Contributing
82+
83+
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding new examples.
84+
85+
## Links
86+
87+
- [CaptchaAI Website](https://captchaai.com)
88+
- [API Documentation](https://captchaai.com/api-docs)
89+
- [CaptchaAI Blog](https://blog.captchaai.com)
90+
91+
## License
92+
93+
MIT

‎articles/captchaai-quickstart/.env.example‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# CaptchaAI API credentials
2+
# Get your API key from https://captchaai.com/dashboard
3+
CAPTCHAAI_API_KEY=YOUR_API_KEY
4+
5+
# Target page configuration
6+
CAPTCHA_SITEKEY=SITE_KEY
7+
CAPTCHA_PAGEURL=PAGE_URL
8+
9+
# Polling configuration (optional)
10+
POLL_INTERVAL=5
11+
MAX_TIMEOUT=120

‎articles/captchaai-quickstart/.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.env
2+
__pycache__/
3+
*.pyc
4+
node_modules/
5+
vendor/
6+
composer.lock
7+
package-lock.json

0 commit comments

Comments
 (0)