@homeflare/distilled-netbox
v0.3.2
Published
Interim npm home for @distilled.cloud/netbox — see docs/distilled-interim.md. Not published upstream yet; the kit aliases @distilled.cloud/netbox onto this package until it is.
Readme
@homeflare/distilled-netbox
This package is not a HomeFlare SDK. It is an unmodified copy of
@distilled.cloud/netbox, generated by the distilled
pipeline from NetBox's own committed OpenAPI 3.0.3 document
(contrib/openapi.json at netbox-community/[email protected]), published here
under its own name only because @distilled.cloud/netbox does not exist on
npm yet — the kit builds it in a local clone of alchemy-run/distilled but,
per house policy, never pushes to that upstream. See
../alchemy/docs/distilled-interim.md
for the full route every distilled-sourced vendor package follows, and why
this one exists at all.
⛔ Do not hand-edit anything under src/. The whole point of the route
above is that this directory is copied, not written — a fix belongs in the
distilled clone's packages/netbox/, regenerated, then copied back here.
⚠️ License. Apache-2.0, not the kit's usual MIT — this content is a
redistribution of alchemy-run/distilled's own Apache-2.0-licensed output,
and relicensing a copy would misstate what it is. See LICENSE.
What's in it
13 service modules, one per NetBox API tag — dcim, ipam, circuits,
virtualization, tenancy, vpn, wireless, users, extras, core,
plus the single-endpoint schema, status and authentication_check — an
Effect-typed operation per NetBox REST endpoint (1,256 total), with catchTag-able
errors for every status NetBox actually produces, including the ones its own
OpenAPI document omits (404 on every detail operation, 403 on every read, 400
on every list — see the distilled package's patches/<tag>/_undeclared-errors.json
for the evidence).
import * as Netbox from '@distilled.cloud/netbox'; // aliased onto this package — see docs/distilled-interim.md
import * as Effect from 'effect/Effect';
const program = Netbox.Services.ipam
.listIpamPrefixes({})
.pipe(
Effect.provide(Netbox.NetboxProtocol),
Effect.provide(Netbox.credentials({ token: '...', baseUrl: 'https://netbox.example.com' })),
);Every list* operation also carries .pages() (a Stream of raw pages) and
.items() (a Stream flattened to results' element type), following
NetBox's next URL via the hand-written netboxPaginate strategy in
src/pagination.ts — core's generic pagination strategies can't follow a
URL-valued next directly, see that file for why.
Kit code never imports @homeflare/distilled-netbox directly — always
@distilled.cloud/netbox, aliased in the consuming package's package.json
("@distilled.cloud/netbox": "npm:@homeflare/distilled-netbox@<version>"), so
the eventual cutover to the real published package is a one-line alias swap
with no import changes anywhere in the kit.
Updating it
From the distilled clone's homeflare/netbox worktree:
DISTILLED_SPECS_LOCAL=1 pnpm --filter @distilled.cloud/netbox run generate
pnpm --filter @distilled.cloud/netbox run typecheck
pnpm format && pnpm specs:checkThen copy src/ here verbatim, add a changeset (patch — the generated
content changed but nothing new is callable; minor — a new capability like
pagination becomes callable, per the kit's own new-feature-vs-swap
convention), and let the kit's normal release flow publish it and bump this
package's own version.
License
Apache-2.0 (see LICENSE) — not the kit's usual MIT. src/ is an
unmodified copy of @distilled.cloud/netbox'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.
