Beamcode for Python

Encrypted QR file transfer — the same product as beamcode.vjyas.online, available as an SDK and CLI.

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

# 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

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:

from beamcode import BeamcodeClient

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

Configuration

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

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

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.
2. Open Publishing settings.
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).

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.