HomeCloud SDK

Polyglot SDK for HomeCloud — Python at the repo root (pip install homecloud-sdk), Node.js under js/ (@homecloud-platform/sdk), Go under go/ (github.com/HomeCloudLab/homecloud-sdk/go), Java under java/ (com.homecloudlab:homecloud-sdk).

Parity goal: same HomeCloud capabilities on the same semver. Track gaps in js/PARITY.md. Go follows ADR-051 and Java follows ADR-052: idiomatic public API, behavioral parity, no bug-parity for unsafe retries.

Auth model (cloud-style)

Access Keys are created once in the Console (human + MFA there). Runtime SDK calls do not re-prompt MFA.

from homecloud import HomeCloud

# Recommended — explicit credentials (CI / servers)
client = HomeCloud(
    access_key="HCAK...",
    secret_key="...",
)

# Or environment (HOMECLOUD_* / HC_*)
client = HomeCloud.from_env()

# Or ~/.homecloud/credentials (+ optional HC_PROFILE)
client = HomeCloud()

# Data plane — Access Key only, no login
client.so.upload("docs", "./file.txt", key="a.txt")
client.so.upload(
    "media",
    body=video_bytes,
    key="videos/clip.mp4",
    content_type="video/mp4",
)
client.mq.send("orders", {"id": 1})
client.mq.send("orders", [{"id": 1}, {"id": 2}])  # batch (1–10)

# Interactive helpers only (CLI/tools) — may involve MFA
# client.login("100200300400", "alice", "…")  # account number or alias, then username/password
# client.login_browser()

Node.js (@homecloud-platform/sdk)

const { HomeCloud } = require("@homecloud-platform/sdk");

const client = HomeCloud.fromSts(context.sts.archive, {
  accountId: context.account_id,
});
await client.so.putJson("docs", "a.json", { ok: true });

See js/README.md. Same STS / mailapi rewrite rules as Python ≥0.4.9.

Go (github.com/HomeCloudLab/homecloud-sdk/go)

client, err := homecloud.FromEnv()
_, err = client.SO.PutJSON(ctx, "docs", "a.json", map[string]any{"ok": true})

See go/README.md. Release tags: v* (PyPI/npm/Java) and go/v* (Go module).

Java (com.homecloudlab:homecloud-sdk)

HomeCloud client = HomeCloud.fromEnv();
client.so().putJson("docs", "a.json", Map.of("ok", true));

See java/README.md. Requires Java 17. First publish: GitHub Packages; Maven Central is the public GA gate.

Async

from homecloud import AsyncHomeCloud

async with AsyncHomeCloud.from_env() as client:
    meta = await client.so.head_object("docs", "a.txt")
    await client.mq.send("orders", {"id": 1})
    await client.mq.receive("orders", max_messages=10, delete=True)

from homecloud_sdk import … still works (compatibility). Prefer from homecloud import ….

Errors

HTTP failures raise typed subclasses of HomeCloudError (catch specific types or the base):

from homecloud import HomeCloud, NotFoundError, HomeCloudError

client = HomeCloud()
try:
    client.so.head_object("docs", "a.txt")
except NotFoundError as exc:
    print(exc.resource_type, exc.resource, exc)  # object / docs/a.txt / …
except HomeCloudError as exc:
    print(exc.status_code, exc)

Architecture

homecloud/          ← preferred public import (Python)
homecloud_core/     ← auth, routing, signing, sessions, MFA helpers
homecloud_sdk/      ← HomeCloud + AsyncHomeCloud
js/                 ← @homecloud-platform/sdk (Node.js 20+)
go/                 ← github.com/HomeCloudLab/homecloud-sdk/go (Go 1.22+)
java/               ← com.homecloudlab:homecloud-sdk (Java 17+)
testdata/contracts/ ← shared SigV1 + error fixtures

CLI (homecloud-cli) is a Typer/Rich wrapper; it opts into interactive_mfa=True on the sync client.

Install

pip install homecloud-sdk

Until PyPI is configured, use a Git checkout or sibling editable install:

pip install -e "../homecloud-sdk"

PyPI publish is wired via .github/workflows/publish-pypi.yml (tag v* + Trusted Publishing). npm publish is wired via .github/workflows/publish-npm.yml (same v* tag → aligned versions).

./scripts/bump-version.sh 0.5.0
# commit, push, then:
git tag v0.5.0 && git push origin v0.5.0

Operations by plane

Async mirrors the same surface on AsyncHomeCloud (await client.so.…).

Configuration

Profile / env

1. Constructor profile= / access_key_id= …
2. HOMECLOUD_PROFILE / HC_PROFILE
3. credentials default_profile
4. default

Development

pip install -e ".[dev]"
pytest tests/ -q
pytest tests/test_live_integration.py -q   # needs Access Keys in ~/.homecloud

cd js && npm test
cd go && go test ./...
cd java && mvn test

Service-account verification (pre-PyPI)

Mints a dedicated Access Key named homecloud-sdk-test (requires a one-time homecloud login to create the key), then runs a clean subprocess with HomeCloud.from_env() — no JWT session, no MFA, no browser:

python scripts/verify_service_account_flow.py

Expected: PASS: service-account flow works without login/JWT/MFA/browser.