Sloppy Voice DevelopersSloppy Voice ↗

Developer API and library

Document: SPEC-028. Revision: 0.1. Date: 2026-11-08. Lifecycle: partially confirmed by the human's developer API request; unresolved behaviour is explicitly OPEN.

Authority and scope

CONFIRMED: publish an API/library for creating accounts, channels and servers, searchable usage documentation at developer.sloppyvoice.com, and a technical protocol-design document. Add an API-only non-visible channel-message option for bot/plugin control traffic; official clients must not expose a composer option or display these messages.

The existing SPEC-009/010/011/012/015/022/027 protocols remain authoritative. The library wraps those APIs rather than granting a separate administrative identity. Authentication, current permissions, immutable channel encryption, device proofs, membership history, command idempotency and expiry remain enforced by the server. Account creation uses existing registration/invitation policy; channel creation remains owner-only.

CONFIRMED by the human follow-up: create multiple logical servers inside one instance. Accounts are shared across the instance; any signed-in account may create a server. Each server has independent owners, members, channels and settings. The existing server and its identities/channels remain unchanged. Logical-server creation is distinct from operator bootstrap and infrastructure provisioning.

CONFIRMED by the human follow-up: non-visible messages retain channel access, encryption, retention and API retrieval, while remaining absent from client transcripts, search, unread counts and notifications.

Logical-server wire profile

Engineering profile logical-servers/1: instance account routes and credentials remain at the existing base URL. GET /api/servers lists only servers of which the caller is a member. POST /api/servers/tickets and /commands accept server.create with {name}; any enabled local account may create one and becomes its first owner. Visitors cannot create servers. Existing instance ownership grants no implicit logical-server membership. UUID identities are independent from the deployment's existing server identity.

/api/servers/<server>/state, /channels, /tickets and /commands provide member-authorized management. Commands are channel.create (SPEC-012 properties), member.set (target, role: owner|moderator|member|null), and server.settings (name, pttMaxSeconds, pttRequired). Owners manage server membership and settings; the last owner cannot be removed or demoted. A member must be an enabled existing local instance account. Removing membership closes its open channel intervals and prevents further reads; re-adding does not restore absent-period history. Logical ownership never grants instance account administration. Server settings start with the existing shared PTT defaults; no separate registration or credential policy exists within a logical server.

/api/servers/<server>/channels/<channel>/{state,history,tickets,commands} provides explicit channel admission and messaging. Commands are channel.join, channel.leave, channel.permission (owner-only exact permissions SPEC-022 ACL), channel.settings (owner-only name), and message.send. Channel properties/encryption limits and the SPEC-022 permission resolver are reused. Server membership propagates through inheriting channels, denials win, and owner protections remain. Creation admits its creator; grants to others require explicit joins. Parent channels must belong to the same server. API states supply current admitted participants/device rosters and immutable encryption metadata. This profile exposes resource administration and text/control exchange; it does not advertise a logical-server voice/media transport or client navigation capability. Existing deployed-server voice/client APIs remain available separately.

All commands use the existing five-minute ticket/24-hour result bounds, audience/account/device/resource binding, exact-payload fingerprints, transactional mutation/result commit and current authorization before replay. Revisions are mandatory except creation of an independent server/channel. Server/channel capacities reuse the fixed 100-resource bounds, per-instance for logical servers and per-server for channels; accounts and retained messages retain existing instance quotas. No automatic Lobby is created for a logical server. Unknown/inaccessible logical resources both return 404. All state is stored durably with atomic server, membership, channel and result records; root clients never list logical channels as ordinary instance channels.

Non-visible message wire profile

Engineering profile channel-control-messages/1: signed envelope nonVisible is optional boolean, omission/false means ordinary visible message. True also binds the encrypted inner payload. Reject null and non-booleans before mutation. Existing sender, recipient, quota, rate, idempotency, membership and retention checks apply. This is a presentation distinction, not secrecy from authorized channel members or executable bot authority. Control consumers must authenticate/decrypt before acting on their own application payloads.

GET history and GET sync default includeNonVisible=0; 1 includes eligible control records alongside visible records, and other values fail. Filtering applies after a bounded eligible page; the returned cursor advances across omitted controls, so an empty page need not mean end of history. No control record may become a visible pin, thread root or reply parent; control envelopes cannot carry replyTo or direct-conversation policies. History-copy operations retain existing authorization and authenticated original envelopes. The first stored control message or logical server advances the durable schema marker to 10 so older servers refuse rollback rather than display hidden traffic. Schema 10 preserves existing schema-9 tables and bytes.

Library and publication

Engineering selection: publish a versioned installable JavaScript/TypeScript npm-format archive on the developer hostname. A public npm registry publication is not required to install this archive. Use the existing client request and cryptography implementations, bundled into an ESM package with declarations; original material retains Apache-2.0 and NOTICE. Node.js 22.13+ is the initial automation runtime; browser consumers need an ESM bundler and the service's existing exact-origin allowance. No unattended secret storage is provided.

Expose low-level requests and exact ticket retry plus named bootstrap, registration, login, account-invitation, channel creation/listing/join, state/history and signed/encrypted message helpers. Document pending ambiguous commands and credential/key persistence; do not invent automatic mutation replay or silently generate replacement device keys on login.

Documentation must be searchable locally in the page, link API operations to their wire routes, include working automation examples and downloads, distinguish implemented profiles from proposals, and publish the authoritative specification sources alongside a readable protocol-design explanation. Search must not send user queries to a third party. The developer host serves documentation/download assets without application credentials or control bindings.

Configuration

Library baseUrl: required string, no default; existing SPEC-010 service-base validation applies, HTTPS outside loopback development, including path prefixes. keys: required caller-owned device keys for account/messaging helpers, no default; generate explicitly using makeKeys, persist securely outside the library. token: optional login credential, omitted for anonymous operations; scoped to the supplied service base. Channel context defaults to lobby for existing API compatibility; explicit server context is @server. Request timeout and response budgets remain owned by the existing client API (15,000 ms default timeout); per-request abort/timeout overrides retain that implementation. Existing protocol/server configuration is referenced, not redefined.

Developer hosting uses a separate static-assets Worker and the custom domain developer.sloppyvoice.com; no database, media, account or secret bindings. Package versions and SHA-256 digests are publication metadata, not runtime configuration. No new application administrative policy is introduced by the library.

Testing

Unit-test helper proof construction, authenticated route/context selection, missing-key/identity failures, registration versus bootstrap and login challenge flow, channel commands and exact pending retry behaviour. Reuse existing client API and cryptographic tests for response limits, redirect rejection, canonical signatures, recipient coverage and history authentication. Test the built archive by installing it in an isolated project and importing the published entry point; exercise helpers against a disposable local service. Documentation checks verify search index coverage, links, package integrity and absence of private files. Hosted checks verify custom-domain TLS, searchable assets, archive digest and configured versus observed Worker version separately.

Acceptance criteria

  • A fresh Node.js project installs the published versioned archive and imports the documented entry point and declarations.
  • Generated fixture keys bootstrap a disposable local service, register an invited account, create/join a channel and exchange authenticated encrypted messages through the library.
  • Unauthorized account/channel operations retain existing errors and exact retries do not duplicate effects.
  • https://developer.sloppyvoice.com/ serves searchable API guides, the library download with SHA-256, and the technical protocol-design document with authoritative source links.
  • Publication contains no credentials, private build data or application authority bindings.
  • Any enabled local account creates a logical server; unrelated accounts cannot inspect or mutate it, and its owner cannot administer another server or change instance accounts.
  • Non-visible messages remain API-readable only to eligible members and never appear in default history, pinned messages, threads, client search, unread counts or notifications.