Metadata-Version: 2.5
Name: beamcode
Version: 1.1.0
Summary: Beamcode — encrypted QR file transfer SDK and CLI (https://beamcode.vjyas.online)
Project-URL: Homepage, https://beamcode.vjyas.online
Project-URL: Documentation, https://beamcode.vjyas.online/how
Project-URL: Repository, https://github.com/jyoshnavi/QRFileTransfer
Author: Beamcode
License-Expression: MIT
Keywords: aes-gcm,beamcode,cli,encryption,file-transfer,qr,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: File Sharing
Classifier: Topic :: Security :: Cryptography
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=42
Requires-Dist: httpx>=0.27
Requires-Dist: pyperclip>=1.8
Requires-Dist: qrcode>=7.4
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Beamcode for Python

Encrypted QR file transfer — the same product as [beamcode.vjyas.online](https://beamcode.vjyas.online), available as an SDK and CLI.

```bash
pip install beamcode
```

## Why this exists

Share any file (PDF, video, archives, binaries) from a terminal or Python script. Files are encrypted on the client with AES-256-GCM before upload. Recipients open the link on any device — no shared Wi‑Fi, no accounts.

## CLI

```bash
# Send a local file — share_url is copied to the clipboard
beamcode send ./report.pdf

# Mix local files and remote URLs (PDF/docs fetched then attached)
beamcode send ./clip.mp4 https://example.com/whitepaper.pdf --ttl 24h

# Receive
beamcode receive "https://beamcode.vjyas.online/d/….…#k=…"
beamcode receive "bc:transferId:key"

# Ops
beamcode limits
beamcode doctor
beamcode revoke <id> --token <revokeToken>
```

Progress is staged with clear percentages: **Prepare → Fetch → Encrypt → Upload → Finalize** (and Download / Decrypt on receive).

## SDK

```python
from beamcode import BeamcodeClient, send_files, receive

result = send_files(
    ["./video.mp4", "https://example.com/doc.pdf"],
    ttl="1h",
    on_progress=lambda e: print(f"{e.stage.value} {e.percent:.0f}% overall {e.overall_percent:.0f}%"),
)

print(result.share_url)   # primary — copy and share this
print(result.compact)     # denser QR payload
print(result.pair_code)

paths = receive(result.share_url, out_dir="./inbox")
```

Low-level API access:

```python
from beamcode import BeamcodeClient

with BeamcodeClient() as client:
    print(client.get_limits())
    print(client.health())
```

## Configuration

| Variable / flag | Purpose |
|-----------------|---------|
| `BEAMCODE_API_URL` / `--api-url` | Override API host (default `https://beamcode.vjyas.online`) |
| `--allow-private-urls` | Allow fetching localhost / private IPs (off by default) |
| `--json` | Machine-readable output for scripts |
| `--watch` | After send, print open / download receipts |

## Security notes

- Encryption is **required**; keys live only in the URL fragment (`#k=`) or compact `bc:` payload.
- Large files use **disk-backed** encrypt/upload/download/decrypt (≈1 MiB crypto window) — not full-file RAM.
- Multipart uploads **resume** from local checkpoints after failure.
- Remote URL fetch blocks private/loopback hosts by default (SSRF protection, including redirects).
- Compatible with the web app: files sent via `pip` open in the browser, and vice versa.

## Production options

```bash
beamcode send ./video.mp4 --password 'long-secret' --ttl 24h
beamcode send ./a.pdf --turnstile-token "$TOKEN"   # when API enables CAPTCHA
beamcode extend <id> --token <revoke> --add-sec 3600
beamcode bump <id> --token <revoke> --add 3
```

Env: `BEAMCODE_API_URL`, `BEAMCODE_TURNSTILE_TOKEN`, `BEAMCODE_CHECKPOINT_DIR`.

## Development

```bash
cd python
pip install -e ".[dev]"
pytest
beamcode doctor
```

## Publish to PyPI (GitHub Actions)

Publishing is **tag-driven**. A normal push only runs tests; it will **not** upload to PyPI.

### 1. One-time: Trusted Publishing on PyPI

1. Create / sign in at [pypi.org](https://pypi.org).
2. Open [Publishing settings](https://pypi.org/manage/account/publishing/).
3. Under **Add a new pending publisher**:
   - **PyPI Project Name:** `beamcode`
   - **Owner:** your GitHub username or org
   - **Repository name:** `QRFileTransfer`
   - **Workflow name:** `python-package.yml` (exact filename)
   - **Environment name:** leave **blank** (do not set `pypi`)
4. You do **not** need GitHub → Settings → Environments for this setup.

No `PYPI_API_TOKEN` secret is required with Trusted Publishing.

### 2. Ship a release

Version in `python/pyproject.toml` / `python/src/beamcode/_version.py` must match the tag (e.g. `1.1.0` → `py-v1.1.0`).

```bash
git add python .github/workflows/python-package.yml
git commit -m "Release beamcode 1.1.0"
git push origin HEAD

git tag py-v1.1.0
git push origin py-v1.1.0
```

Then open **Actions → python-package** for that tag run. You should see jobs **test** and **publish**.

After success: `pip install beamcode` → https://pypi.org/project/beamcode/

### Why publish was skipped before

The publish job only runs when `github.ref` is `refs/tags/py-v…`. Branch/PR runs show **test** only — that is expected.

## License

MIT — same as the Beamcode monorepo.
