# Control Plane Client

`ControlPlaneClient` is the main public entry point for plugins.

```java
ControlPlaneClient client = NetworkPlugin.client();
```

## Public Clients

```java
client.server();    // ServerClient
client.presence();  // PresenceClient
client.players();   // PlayersClient
client.batch();     // BatchClient
client.cache();     // ApiDataCacheClient
```

## Handwritten Domain Clients

`ServerClient`

```java
ServerProfile profile = client.server().currentProfile();
```

`PresenceClient`

```java
client.presence().register(instanceId, registrationPayload);
client.presence().heartbeat(instanceId, HeartbeatPayload.running(12, 150));
client.presence().shutdown(instanceId, "restart");
```

`PlayersClient`

```java
PlayerSessionProfile profile = client.players().getSessionProfile(playerId);
List<PlayerEntitlement> entitlements = client.players().getEntitlements(playerId);
```

## Error Handling

Transport errors use checked `ControlPlaneException` subclasses:

- `AuthException` for `401` and `403`
- `NotFoundException` for `404`
- `ValidationException` for `422`
- `RemoteException` for `5xx`
- `ControlPlaneException` for other transport or parsing failures

Example:

```java
try {
    ServerProfile profile = client.server().currentProfile();
} catch (AuthException e) {
    // token is missing, invalid, inactive, or lacks ability
} catch (ControlPlaneException e) {
    // generic control-plane failure
}
```

## Endpoint Descriptors

Generated endpoint descriptors are available under:

```text
net.kewwbec.network.generated.api.v1
```

Use them for stable route metadata and URI templates. Resolve path variables with `PathBuilder`.

```java
String uri = PathBuilder.resolve(
    SessionProfileEndpoint.VALUE.uri(),
    "player",
    playerId
);
```

Do not edit generated descriptors manually. Update routes in `core-control-plane`, then run the SDK sync command from that repo.