SDK
There is a first-party TypeScript client for this API. It is not published yet, so this page tells you what it does, what it is missing, and how to proceed without it — which is a supported path, not a workaround.
Availability
Section titled “Availability”@wamp/app-sdk is at version 0.1.0 and is not on the public npm registry —
npm view @wamp/app-sdk returns a 404, and no workflow in the repository
publishes it. Nothing about the API depends on it.
If you cannot wait for the package: every operation on this site is plain HTTPS
against the OpenAPI contract, and the only part that is not a
fetch call is signing the app assertion, which is about ten lines of jose.
Authentication shows it.
Why the client is worth using when it ships
Section titled “Why the client is worth using when it ships”One property is unusual enough to be worth stating: 26 of the 28 operations in
the OpenAPI contract carry an x-wamp-sdk-method extension naming their client
method, and a test locks that mapping one-for-one in both directions. So the
client cannot quietly fall behind the API, and the API cannot gain an operation
the client silently lacks. That is the same reason the reference pages on this
site are generated from the contract rather than written: the contract is the one
artifact everything else is checked against.
The surface
Section titled “The surface”Two classes and an error type.
WampApp handles identity — the pieces you need before any Cloud call:
| Member | Purpose |
|---|---|
generateAppKeypair() |
One-time Ed25519 key generation. Register the public half; the private half never leaves your backend |
new WampApp(options) |
Holds your app slug and private key |
issueUserToken(options) |
Sign an end-user session token for a client to send to the AI proxy |
installationToken() |
Mint the tenant- and resource-exact backend token |
createInstallationIntent() / getInstallationIntent() |
Drive the installation handshake |
buildAssertion() |
Build the signed assertion the token exchange consumes |
verifyWebhook(options) |
Constant-time signature verification with replay protection — see Receive webhooks |
WampCloud is the API client. Its methods map onto the operations documented
under Operations:
| Area | Methods |
|---|---|
| Discovery | capabilities |
| Sessions | createSession, getSession, updateSession, listSessions, archiveSession |
| Turns and runs | submitTurn, listTurns, getRun, cancelRun |
| Following work | listSessionEvents, listOpenInteractions |
| Artifacts | listArtifacts, getArtifact, getArtifactText, getArtifactContent |
| Repositories | listRepositoryGrants, resolveRepositoryGrant, reviewRepository |
| Publications | publishRepository, listPublications, getPublication, mergePublication, getPublicationMerge |
WampCloudError carries the API’s error code and status, so the handling
described in Errors applies unchanged.
Two audience constants are exported for callers that validate tokens themselves:
END_USER_TOKEN_AUDIENCE and WAMP_CLOUD_RESOURCE_AUDIENCE.
A gap worth knowing before you type against it
Section titled “A gap worth knowing before you type against it”The client declares 49 types in its Cloud module and re-exports 42. Seven are not exported, so you cannot name them in your own code:
CloudSessionContinuation, CloudMessageCreatedEvent,
CloudActivityCompletedEvent, CloudContextCompactedEvent,
CloudConversationClearedEvent, CloudTimelineTruncatedEvent,
CloudSafeTimelineEvent.
Five of those are timeline event types — which means the event stream is the one
place where a TypeScript consumer cannot write an exhaustive switch over what
they receive without redeclaring the shapes locally. If you are building a
follow-a-run loop, expect to do that until they are exported. The
Events reference lists every event type and payload, so the
declarations are available to copy.