@homeflare/distilled-proxmox-backup

This package is not a HomeFlare SDK. It is an unmodified copy of @distilled.cloud/proxmox-backup, generated by the distilled pipeline from Proxmox Backup Server's own apidoc.js (the api-viewer's schema — PBS, like PVE, publishes no OpenAPI document), pinned to the vendor schema at proxmox-backup-server version 4.2.6-1 (sha256 274ab9f6fc075aeafb827370e6b65545507e3348a404f1c0b181fc2d9589458a, per the house schema manifest's pbs-apidoc entry), published here under its own name only because @distilled.cloud/proxmox-backup does not exist on npm yet. See ../alchemy/docs/distilled-interim.md for the full route every distilled-sourced vendor package follows.

⛔ Do not hand-edit anything under src/. A fix belongs in the distilled clone's packages/proxmox-backup/, regenerated, then copied back here.

⚠️ License. Apache-2.0, not the kit's usual MIT — see LICENSE.

Read-only verification on 2026-09-24 exercised the regenerated SDK against PBS 4.2.3: version, datastore, matcher and sendmail reads succeeded through its Credentials layer. No infrastructure write was used to test the transport. Protocol fixtures cover writes, repeated array fields and malformed responses.

What's in it

367 operations across 13 service modules, one per PBS top-level path segment — access, admin, backup, config, nodes, ping, pull, push, reader, root, status, tape, version — 0 skipped. Typed errors: the shared HTTP status classes and PBS's global ParameterVerificationFailed/non-retryable BadRequest fallback for a 400. Missing datastore, prune, sync and verification GETs carry precise typed tags: PBS returns these as plain-text 400s, measured read-only on 2026-09-24. Other 400s and sibling write errors keep their original failure semantics.

No ClusterNodeUnreachable. PVE's sibling package adds a typed 595 for cluster-forwarded requests; PBS is not a cluster product and the pinned schema has zero proxyto occurrences, so this package's awaitTask has a narrower error union than PVE's.

Also ships awaitTask (./Task): a PBS POST/PUT/DELETE that queues a long-running action (backup, sync, GC, tape write, …) answers 200 with a bare UPID the moment it is QUEUED — confirmed in the pinned schema (GET /nodes/{node}/tasks/{upid}/status exists, UPID-shaped pattern appears 44 times). awaitTask polls it until exitstatus appears and fails unless it is EXACTLY "OK".

import * as ProxmoxBackup from '@distilled.cloud/proxmox-backup'; // aliased onto this package
import * as Effect from 'effect/Effect';

const program = ProxmoxBackup.Services.version.getVersion({}).pipe(
  Effect.provide(ProxmoxBackup.ProxmoxBackupProtocol),
  Effect.provide(
    ProxmoxBackup.credentials({
      tokenId: 'backup@pbs!terraform',
      secret: '...',
      baseUrl: 'https://pbs1.example.com:8007',
    }),
  ),
);

⚠️ The auth header is PBSAPIToken=<id>:<secret> — a COLON, not the = PVE's PVEAPIToken uses. credentials() builds this correctly; the risk is a caller who copy-pastes PVE integration code and expects the same separator. See src/credentials.ts's header for the two independent, original documentation citations; the read-only SDK probe above now confirms it.

Kit code never imports @homeflare/distilled-proxmox-backup directly — always @distilled.cloud/proxmox-backup, aliased in the consuming package's package.json.

Updating it

From the distilled clone's homeflare/proxmox-backup worktree:

DISTILLED_SPECS_LOCAL=1 pnpm --filter @distilled.cloud/proxmox-backup run convert
DISTILLED_SPECS_LOCAL=1 pnpm --filter @distilled.cloud/proxmox-backup run generate
pnpm typecheck:ci
pnpm format

pnpm specs:check now passes the 81-mirror coherence gate. The generation above uses the pinned local schema; refreshing that schema is a separate operation.

Form arrays use repeated keys rather than the generic REST encoder's indexed keys. Successful responses are validated against the generated output schema; Unit data:null responses remain valid, and extra response fields are preserved. Malformed payloads raise ProxmoxBackupParseError without copying response data into diagnostics, because notification fields can contain secrets.

Then copy src/ here verbatim and add a changeset. The normal release flow versions and publishes the package.

License

Apache-2.0 (see LICENSE) — not the kit's usual MIT. src/ is an unmodified copy of @distilled.cloud/proxmox-backup's own output from alchemy-run/distilled, which is itself Apache-2.0; this package's own files (package.json, tsconfig.json, scripts/smoke.ts, this README) are offered under the same terms.