A good SDK gives app code a small surface and keeps Bitfield setup work outside app code. The public surface should stay narrow because the setup work is already packaged away.
The JavaScript Runtime Kit is the example. App code gets one read hook and one request function. Bitfield still handles boot, connection, package loading, storage readers, subscriptions, and validation outside that surface.A team wants the same package-backed feature to work from React today and a different app surface later. The SDK should preserve the same read/request shape instead of making every app call setup steps.App
Read named data. Send a named request. Render product states.
→
SDK
Connects, subscribes, decodes, retries, and keeps setup details out of app code.
→
Bitfield
Packages, data names, targets, local state, and runtime/device access stay outside app code.
The rule
Expose the read or request the app actually needs. Do not expose the setup steps Bitfield had to take to make that possible.Expose reads.
Give app code a stable way to receive data, loading, and error.
Expose requests.
Give app code a stable way to send a target plus payload.
Hide setup work.
Keep boot, package binding, storage addressing, byte subscriptions, and transport setup outside the app surface.
A public surface can be small
The setup surface can be large
The setup surface can do real work. It may connect to Bitfield, load packages, prepare read scopes, subscribe to updates, decode payloads, validate package files, or recover from resets.That does not mean the app surface should expose those details. App developers should not have to call setup code just to render data.The boundary test
Ask this before adding a public SDK function:Would an app developer call this because their product needs it, or because Bitfield setup needed a place to live?
If it is setup work, keep it outside the public app surface.Common failures
| Symptom | Cause | Fix |
|---|---|---|
| App code has to call three setup functions before reading data | The setup seam leaked into the app surface | Move setup into the SDK entry point |
| SDK exposes raw package material | The SDK is making app code understand package admission | Expose named data reads and named requests instead |
| Another language SDK has different product concepts | The SDK copied implementation details instead of the public shape | Keep every SDK around read, request, state, and error |
| Error handling is different on every screen | The SDK does not have a stable error contract | Return consistent loading, error, empty, and success states |