Tiers & entry points

@edgible-team/sdk is one package with five entry points. The split is not cosmetic — it partitions the SDK by where the code is allowed to run and what it may touch, enforced at the package boundary. A browser bundle physically cannot pull in agent-install code, and a non-admin consumer cannot call admin endpoints by accident, because those symbols simply don’t exist on the surface it imports.

Two terms used throughout:

• Control plane — the Edgible HTTP API: pure network calls that work from anywhere (manage applications, devices, storage, organizations…).
• Device host — a machine that runs (or will run) the Edgible agent. Operating on it locally (installing the agent, controlling its daemon) requires Node and OS privileges.

The matrix

Entry point	Tier	Runs in	What’s on it
@edgible-team/sdk	1 + 3	Browser · Node · CI	createClient() and every resource namespace (applications, devices, storage, organizations, secrets, catalog, …), the deploy waiter, and stacks (declarative multi-app orchestration). The browser build is verified free of Node builtins on every build.
@edgible-team/sdk/node	1 + 3 (Node halves)	Node · CI	Named Node-only pieces: FileCredentialStore (shares the CLI’s login session), loadStackFile/findStackFile (stack files, .env, compose embedding), NodeStorageSeeder, and VM lifecycle helpers (prepareVm, provisionVmWithAgent).
@edgible-team/sdk/host	2	Device host (Node, privileged)	Local host automation: installAgent/uninstallAgent, daemon managers (startAgent, stopAgent, getDaemonStatus), detectHost, connectivity probes, runRemoteCommand, collectDiagnostics. Never importable from the root.
@edgible-team/sdk/agent	—	The Edgible device agent	The agent’s inward-reporting endpoints (status, deployment state, log/usage ingest). Platform-internal — not for general use.
@edgible-team/sdk/admin	—	Admin tooling	Admin-gated operations, which require platform-admin rights. Platform-internal — not part of the published developer surface.

The tier numbers: tier 1 is the control-plane client, tier 2 is privileged host automation, tier 3 is orchestration built on tier 1 (stack graphs, waiters). Tiers 1 and 3 share the root entry; tier 2 is deliberately a separate import.

Two root namespaces worth a note beyond the CRUD nouns:

• client.secrets — organization secret management, write-only by design: set (create/rotate), list, get, delete never return a secret value, only metadata (key names + drift checksum).
• client.catalog — the app-catalog registry: template reads (list, get, getBundleUrl) work without credentials; publish, verification, and curation calls are admin-gated.

Which import do I need?

• Building a web UI, script, or CI job that manages Edgible resources? → @edgible-team/sdk. This is the surface for almost everyone: createClient(), deploy applications, wait for readiness, orchestrate stacks.
• On Node and need explicit credential wiring, stack-file loading, or VM helpers? → add @edgible-team/sdk/node. (You often don’t need it: the root entry on Node already defaults to the file credential store and stack seeding.)
• Writing automation that runs on the device itself — install the agent, control its daemon, collect diagnostics? → @edgible-team/sdk/host. Node-only, usually needs root. Note the split: remote provisioning of a cloud device is tier 1 (a backend call, works from a browser); /host is only for operating on the machine your code is running on.

The /agent and /admin entry points exist for the platform itself — the device agent and admin tooling, respectively. If you’re not one of those, you don’t want them, and they’re not documented here.

Guarantees behind the split

• Browser safety. Bundlers resolve the root import to a dedicated browser build with no Node builtins (fs, child_process, …) — enforced mechanically by a post-build check, not by convention. The Node-conditioned root build does use fs, by design: that’s what gives zero-config CLI-session sharing.
• Privilege isolation. Tier-2 host operations are never re-exported from the root, so a webapp cannot accidentally ship or call installAgent(). /host exposes plain functions (not a client object); where one needs the control plane, it takes a tier-1 client as an argument.
• Surface isolation. Agent and admin endpoints live on their own entry points so the type system itself signals “this is not for you” — importing them is an explicit, visible act.

How these surfaces are documented

The reference follows the same split: the public reference covers the root entry (and /node) — what general developers consume; /host is documented in a separate operator reference for people running device hosts; /agent and /admin are platform-internal and intentionally not part of the published developer docs.