# Changelog ## 2026-09-18 - 32.0.0 ### Breaking Changes - Require `@serve.zone/interfaces` `^32.0.0` and release as 32.0.0, the one major the serve.zone control plane speaks. Interfaces 32 strips every version suffix and removes every `schemaVersion`, so the names below change with no alias and no tolerance for an older body. - The socket session registration is `registerCloudlyClientSession` (was `registerCloudlyClientSessionV1`), its body carries a protocol offer instead of a `schemaVersion`, and its answer carries the controller's own offer. A Cloudly that serves only the 31 method cannot authenticate this client at all. - A protocol refusal is surfaced as the new `CloudlyProtocolIncompatibleError`, exported from the root beside the client's own offer `cloudlyClientProtocolOffer`. The error carries the `IProtocolRefusal` — its reason and both sides' offers — and its message is the shared `describeProtocolRefusal` line; the transport error stays attached as the cause. A refusal is never retried: the registration fires with retries disabled, an authentication call rejects with the named error after closing the ambiguous socket, and a refusal met while a reconnect restores a session leaves that restoration denied, which is never reconnected from. - A refusal met while a connection restores the retained session — the registration `start()` and every reconnect run — reaches no caller: the transport denies that restoration terminally and carries the refusal as the denial's `cause`, so `start()` rejects with that denial and a reconnect publishes one `restoreDenied` diagnostic on the socket's `diagnosticsSubject`. The client ends its own socket lifecycle in step: it releases `typedsocketClient`, retains the refusal on the new `lastProtocolRefusal`, and keeps the session credential. `start()` opens a new socket lifetime, clears that refusal and re-offers the retained credential, so recovery once an operator upgraded a side is `start()` or a fresh authentication. - An accepted registration is negotiated from this client's side as well: a controller that answers an offer this build cannot serve is refused with the same named error rather than used. - `backup.createIsolatedRestore` takes `targetNodeId` instead of `targetNodeName`. The node name is what the signed grant authorizes and is now refused as caller input; `getIsolatedRestores` filters by either. - `secrets.purgeSecretVersion` no longer takes `schemaVersion`; the remaining fences are unchanged. - `PrivateNetworkClient` calls the unsuffixed request methods (`listOwnedOrganizations`, `listPrivateNetworkServiceCandidates`, `listPrivateNetworks`, `getPrivateNetwork`, `mutatePrivateNetwork`, `getServicePrivateNetworks`, `setServicePrivateNetworks`, `getServicePublishedPorts`, `setServicePublishedPorts`) and its mutation arguments are `TPrivateNetworkMutation`, `ISetServicePrivateNetworks` and `ISetServicePublishedPorts`, none of which carries a shape version any more. A mutation that still states one is refused before dispatch, because the interfaces snapshots are exact-key. - `SecretRuntimeClient` DTOs follow the same strip: `ICorestoreControlCredentialMaterial`, `ICorestoreCredentialPublicationGrant`, `ICorestoreCredentialPublicationReceipt` and `TSecretDeploymentReport`, all without `schemaVersion`. The X25519 envelope keeps its own `schemaVersion`: it belongs to `@push.rocks/smartcrypto`. - The CoreMail desired state carries no `schemaVersion` and its credential verifier format is `argon2id`; the verification-hash bytes are unchanged. ### Features - Add `ts/protocol.ts`, this package's one protocol module: `cloudlyClientProtocolOffer` is the offer for the single session kind the client opens, built from the installed `@serve.zone/interfaces` release with a minimum peer of 32.0.0, raised only by the commit that starts depending on a later interfaces minor. ### Maintenance - Require `@api.global/typedsocket` `^8.4.0`, which makes a refused connection restoration terminal and observable: the denial carries the refusal the restore hook threw as its standard `cause`, and a reconnect that met one publishes a single `restoreDenied` diagnostic instead of staying in a reconnect state it never leaves. - Commit `release.versionFloor: "32.0.0"` in `.smartconfig.json`, so this package releases into the platform's common major. - Cover the handshake on the real socket: a refused offer is named to the caller and leaves no session, a refusal met while restoring a session is not retried, ends the client's socket lifecycle with the refusal retained and is published once as the transport's denied restoration with that refusal as its cause, and an accepted registration answered from another major is refused by the client itself. ## 2026-09-16 - 16.0.0 ### Breaking Changes - Coreflow retirement, step 2 (dead client surface): remove the `CloudlyApiClient` members that carried the Coreflow server lifecycle but were never wired end to end. - Remove the public `serverActionSubject` and the `triggerServerAction` TypedRouter handler that fed it. The handler was registered but had no subscriber anywhere in the workspace, no caller, and no Cloudly route. `configUpdateSubject` and its `pushClusterConfig` handler are unchanged. - Remove the public `getServerConfigFromCloudlyByIdentity()`. It fired `getServerConfig` with a hardcoded empty `serverId` and Cloudly never registered a handler for that method, so every call threw. `getClusterConfigFromCloudlyByIdentity()` is unchanged. - Remove the dead `ts/classes.server.ts` stub (`Server.getServers()`): an empty body, never exported from `ts/index.ts` and referenced nowhere. - Require `@serve.zone/interfaces` `^31.0.0`, which deletes the backing contracts `requests.server` (`IRequest_Any_Cloudly_ServerStatus`, `IRequest_TriggerServerAction`), `IRequest_Any_Cloudly_GetServerConfig`, `IRequest_Coreflow_Cloudly_CoreflowManagerStatusupdate` and `data/server.ts`. ## 2026-09-16 - 15.3.0 ### Features - Add `getServicePublishedPorts` and `setServicePublishedPorts` to `PrivateNetworkClient`. - Mirrors the service-membership pair exactly: server-side identity injection, the shared typed-request path with retries disabled, and contract validation through the published `snapshotSetServicePublishedPortsV1` before dispatch. - Requires `@serve.zone/interfaces` `^30.17.0` for the published-port request and document contracts. ## 2026-09-15 - 15.2.1 ### Fixes - Use dependency ranges for typedrequest and interfaces so consumers dedupe a single runtime copy. - `@api.global/typedrequest` and `@serve.zone/interfaces` were pinned exactly, so any consumer resolving a different exact version embedded two copies of each and tripped its single-runtime guard. ## 2026-09-15 - 15.2.0 ### Features - Add `CoreMailControlClient`, the control-plane client for a CoreMail instance. - Requires `@serve.zone/interfaces` 30.13.0 (exact pin) for the CoreMail control and statistics contracts. - Authenticates a CoreMail control session, exposes the replica identity, and pushes desired state through prepare, an HTTP transfer-grant PUT of the canonical bytes, and apply. - Computes canonical bytes and the desired-state digest with the `@serve.zone/interfaces` helpers, enforces a strictly increasing `configEpoch`, and resolves an apply that committed without answering by probing reconciliation status instead of retrying into a fence conflict. - Reads per-service mail statistics over the control session using the `@serve.zone/interfaces` 30.13.0 `coreMailGetServiceMailStatistics` contract, validating every entry with the published `normalizeCoreMailServiceMailStatistics` and cross-checking each page against the requested day range, service filter and limit. - Keeps the HTTP transfer hop in one swappable `uploadDesiredState` method, ahead of the planned TypedSocket-native byte transfer. - Adds no argon2 or other native dependency: credential verifiers stay with their producers. ### Maintenance - Update pnpm to 12.4.0 and Node typings to 26.5.0 for the release. ## 2026-09-13 - 15.1.0 ### Fixes - update @git.zone/tstest to 6.0.0 (dev-deps) - Updates the @git.zone/tstest dev dependency from ^4.0.0 to 6.0.0. - Pins the tstest version instead of using a caret range. - Use current eligible pnpm and TSBuild tooling, explicit release verification and the canonical license filename. ### Features - Expose owner organization pickers and scoped network and service membership operations with exact JWT credentials and explicit mutation retries. ## 2026-09-09 - 15.0.0 ### Breaking Changes - migrate client transport to TypedSocket 8 session registration (transport) - Require TypedRequest 8, TypedSocket 8, and Interfaces 30 with registerCloudlyClientSessionV1 support. - Replace client-owned socket identity tags with authenticated session registration and reconnect restoration. - Make socket lifecycle explicit with shared start, joined stop, abort handling, and requireTypedSocket() guards. - Update image transfer handling to use connection-bound directional virtual streams with proper acceptance, cancellation, and cleanup. - make Cloudly client identity optional with explicit lifecycle helpers (auth) - Add setIdentity() for adopting existing identities while registering the active socket and reconnect credential. - Add clearIdentity() to immediately clear authentication state, invalidate pending auth work, and close the authenticated connection. - Route authenticated request helpers through requireIdentity() so logged-out calls fail fast. - Prevent stale authentication cleanup from disconnecting newer socket lifecycles. ### Fixes - update dev tooling dependencies and pnpm (deps) - Bump @git.zone/tsdoc to ^2.2.0 and @git.zone/tstest to ^4.0.0 - Pin @types/node to 26.4.1 and update pnpm to 12.2.1 - clarify clearIdentity authenticated connection behavior (changelog) - Update changelog text to state clearIdentity closes the authenticated connection instead of restarting anonymously. ### Features - support cancellable image uploads with configurable acceptance timeouts (image) - Add abortSignal support for image.update() and image.pushImageVersion(), including cancellation during transfer, after readable EOF, and during the final metadata refresh. - Add acceptanceTimeoutMs for pushImageVersion() with a ten-minute default for receiver acceptance after FIN. - Bump @api.global/typedsocket to ^8.1.0 for virtual stream acceptance timeout support. ## 2026-08-10 - 14.0.0 ### Breaking Changes - update @serve.zone/interfaces to 27.1.0 (deps) - Bumps @serve.zone/interfaces from 26.0.0 to 27.1.0. - Updates README references to document the Interfaces 27 request surface. ## 2026-08-10 - 13.0.0 ### Breaking Changes - align Corestore runtime receipts with Interfaces 26 (runtime) - Replace the two logical objectstorage coverage keys with the six canonical S3 and AWS Secret aliases returned by credential publication receipts. - Advance objectstorage target Secrets revisions by six exact Secret versions. - Upgrade the public runtime request and response types to Interfaces 26. ## 2026-08-10 - 12.1.0 ### Features - add Corestore credential runtime operations (runtime) - Add typed retrieval of sealed Corestore control credentials and publication of sealed service credentials through the Node-only runtime client. - Preserve exact mutation, grant, recipient, and envelope fences without exposing the runtime methods through the browser-safe root client. - Upgrade to Interfaces 25.3 runtime contracts. ## 2026-08-02 - 12.0.1 ### Fixes - update typedrequest and typedsocket dependencies (deps) - Bump @api.global/typedrequest from 3.5.0 to 3.8.0 - Bump @api.global/typedsocket from ^5.0.1 to ^5.1.2 ## 2026-08-01 - 12.0.0 ### Breaking Changes - move secret runtime APIs to a Node-only entry point (runtime) - Keeps the root CloudlyApiClient browser-safe and exposes secretRuntime through the ./runtime export. - Consumers that use secretRuntime must import the runtime client entry point instead of the root package entry. - Upgrades to Interfaces 25 and requires createService callers to send organizationId separately from serviceData. - Adds browser, runtime transport, service-authority, and package-entry documentation coverage. ## 2026-07-31 - 11.0.0 ### Breaking Changes - upgrade secrets API to Interfaces 24 (secrets) - Bumps @serve.zone/interfaces to ^24.0.0 for the v24 administrative and runtime secret surfaces. - Adds purgeSecretVersion and cursor/limit support for purge preflight requests with request and response validation. - Validates ingress recipient and runtime registration expectation responses as exact schemas, rejecting inactive, stale, legacy, or extra-field responses. ## 2026-07-31 - 10.1.1 ### Fixes - correct constructor log client name (cloudlyapiclient) - Renamed the constructor log label from LoleCloudlyClient to CloudlyApiClient. ## 2026-07-31 - 10.1.0 ### Features - add the cluster secret runtime client (secrets) - Add JWT-scoped recipient enrollment, registration expectation, sealed material, and deployment report methods. - Reconstruct exact runtime DTOs, disable automatic retries, and fail closed on unknown report statuses. - Consume `@serve.zone/interfaces` 23.2.0 for the canonical registration request and tag contract. ## 2026-07-30 - 10.0.0 ### Breaking Changes - replace grouped secret APIs with the sealed Interfaces 23 secret client - Remove `CloudlyApiClient.secretgroup`, `CloudlyApiClient.secretbundle`, the SecretGroup and SecretBundle classes, and `Service.getSecretBundleAsFlatObject()` without aliases or compatibility fallbacks. - Add `CloudlyApiClient.secrets` with the complete Interfaces 23 administrative Secret and SecretSet RPC surface, exact response and revision passthrough, and JWT-only request credentials. - Add caller-preserving `provided-bytes` create and rotate inputs that use a fresh active ingress recipient, context-bound SmartCrypto envelopes, zero mutation retries, and deterministic owned-buffer cleanup. - Keep generated and externally sealed inputs value-free on the API wire and skip ingress-recipient lookup for those modes. - Require Cloudly v23 or newer before the new secret RPC calls can function. - Update `@serve.zone/interfaces` to `^23.0.0`, add direct `@push.rocks/smartcrypto` `^2.2.0`, and refresh the compatible development dependency graph away from the vulnerable Sharp release. ## 2026-07-29 - 9.0.0 ### Breaking Changes - align the Cloudly client with `@serve.zone/interfaces` 20.1.0 - Accept services without a legacy `secretBundleId` while preserving the released Secret, SecretVersion, SecretSet, attachment, manifest, and storage-migration contracts. - align Cloudly client with @serve.zone/interfaces 20.1.0 (interfaces) - Update @serve.zone/interfaces from ^19.8.0 to ^20.1.0. - Accept services without a legacy secretBundleId while preserving Secret, SecretVersion, SecretSet, attachment, manifest, and storage-migration contracts. - Update package manager metadata to pnpm 11.18.0. ## 2026-07-29 - 8.0.1 ### Fixes - align the API client's TypedRequest dependency with the current transport stack so consumers resolve one compatible handler implementation (deps) - Update @api.global/typedrequest to 3.5.0 and @api.global/typedrequest-interfaces to ^4.0.0 - Update @serve.zone/interfaces to ^19.8.0 and refresh runtime/test tooling dependencies ## 2026-07-24 - 8.0.0 ### Breaking Changes - bump typedsocket and serve.zone interfaces major versions (deps) - Upgrade @api.global/typedsocket from ^4.2.1 to ^5.0.1. - Upgrade @serve.zone/interfaces from ^11.0.0 to ^19.0.0. - Update @types/node to ^26.1.1 and pnpm to 11.17.0. ## 2026-07-13 - 7.1.0 ### Features - add isolated restore lifecycle helpers (backup) - Expose create, list, fetch-by-id, and cleanup methods on CloudlyApiClient.backup. - Require JWT credentials and whitelist isolated restore request payload fields before transport. - Document the isolated restore lifecycle and add tests for payload filtering and missing JWT handling. - Update @serve.zone/interfaces to ^11.0.0 and build with strict tsbuild defaults. ## 2026-07-10 - 7.0.0 ### Breaking Changes - use JWT-only identity credentials for Cloudly auth (cloudly-client) - Validate identity JWTs before storing identities, tagging WebSocket connections, or requesting cluster config. - Preserve full identity state while sending only credential payloads for auth-sensitive operations. - Update @serve.zone/interfaces to ^10.0.0 and add pnpm build approvals. ## 2026-07-06 - 6.0.0 ### Breaking Changes - bump @serve.zone/interfaces to v8 (deps) - Updates @serve.zone/interfaces from ^7.25.0 to ^8.0.0. - Updates @git.zone/tsrun to ^2.0.5 and @types/node to ^26.0.1. ## 2026-06-16 - 5.8.0 ### Features - add base service reconciliation command (cloudly) - Expose CloudlyApiClient.reconcileBaseServices() to send the admin command with the client identity. - Bump @serve.zone/interfaces to ^7.25.0 for reconciliation request types. - Add test coverage for the reconciliation request and response passthrough. ### Fixes - update development dependencies (deps-dev) - Update @git.zone/tsdoc from ^2.0.6 to ^2.1.1 - Update @types/node from ^25.9.1 to ^25.9.2 ## 2026-06-10 - 5.7.0 ### Features - support including archived deployments (deployments) - Add optional includeArchived option to getDeployments requests. - Bump @serve.zone/interfaces to ^7.9.1 for updated deployment request types. ## 2026-06-10 - 5.6.1 ### Fixes - bump @api.global/typedsocket to ^4.2.1 (deps) - Updates @api.global/typedsocket from ^4.2.0 to ^4.2.1. ## 2026-06-10 - 5.6.0 ### Features - add kill deployment request support (cloudly) - Add a Cloudly client method for killing deployments with WebSocket support and HTTP fallback. - Bump @serve.zone/interfaces to ^7.6.0 for the killDeployment request type. ## 2026-06-09 - 5.5.0 ### Features - add node lookup and deletion helpers (node) - Add CloudlyApiClient node helpers for listing nodes, fetching a node by ID, checking deletion impact, and deleting nodes via typed requests. - Add tests for node helper operation routing and response unwrapping. - Bump @serve.zone/interfaces to ^7.2.0 for node request types. ## 2026-06-09 - 5.4.0 ### Features - support configurable typed socket client options (cloudly-client) - Add typed socket option interfaces for reconnect, retry backoff, and abort signal settings - Allow options to be provided in the client constructor or when starting the connection - Bump @api.global/typedsocket to ^4.2.0 and forward options to TypedSocket.createClient - Make stop safe when the typed socket client has not been started ### Fixes - stop logging identity tokens during Cloudly lookups (cloudlyapiclient) - Replaces the identity lookup log output with a generic message that does not include the supplied token. ## 2026-05-27 - 5.3.9 ### Fixes - bump `@api.global/typedrequest` to `3.3.2` so downstream consumers use sanitized typed errors consistently - bump typedrequest to 3.3.2 (deps) - Updates @api.global/typedrequest from 3.3.1 to 3.3.2 for consistent sanitized typed errors. - Documents the dependency fix in the pending changelog. ## 2026-05-24 - 5.3.8 - feat(cloudly-client): add node jump command helper - expose `node.createNodeJumpCommand()` on `CloudlyApiClient` - consume the shared Cloudly node jump request contract from `@serve.zone/interfaces@^5.9.0` - migrate release config to schema v2 and refresh release tooling ## 2026-05-08 - 5.3.7 - fix(cloudly-client) correct Cloudly request handling for cluster config, cluster updates, and image pushes - Return the full cluster config response instead of only configData to match the typed request contract - Use the provided identity when requesting certificates and include clusterId in cluster update requests - Send the actual image version during pushes and fail early when Cloudly rejects the upload ## 2026-05-08 - 5.3.6 - fix(deps) bump @api.global/typedrequest and @api.global/typedsocket patch versions - update @api.global/typedrequest from 3.3.0 to 3.3.1 - update @api.global/typedsocket from ^4.1.2 to ^4.1.3 ## 2026-05-08 - 5.3.5 - fix(cloudlyapiclient) update typedsocket identity tagging to use async setTag API - replace typedsocketClient.addTag calls with awaited setTag in identity tagging flows - align client implementation with typedsocket v4 dependency update - refresh runtime and development dependencies to compatible newer versions ## 2026-04-25 - 5.3.1 - fix(package) - Extract `@serve.zone/api` into a standalone package. - Build directly against `@serve.zone/interfaces@^5.4.3` to avoid stale generated interface declarations.