Integration guides
Capabilities
Give Rough Features access to your app's data and actions.
A capability is an operation your application makes available to a Rough Feature. You implement the operation; Rough uses its description, schemas, and sample output to help users build Features that call it.
This guide uses Zod 4. For constructor signatures and return types, see the SDK Reference. For a step-by-step first integration, see Expose your data.
Choose the capability type
| Class | Use it to | Example |
|---|---|---|
Query |
Read a value once. | List the latest messages. |
Mutation |
Change application data. | Mark a message as read. |
Subscription |
Send a current value and ongoing updates. | Watch the unread count. |
Use a Query when a snapshot is enough. Use a Subscription when a Feature needs to stay up to date without requesting the same data again. Use a Mutation for writes, even if the operation also returns data.
Describe inputs, outputs, and samples
Each capability has an id, name, description, inputSchema, outputSchema,
outputSample, and implementation.
- Give it a stable
idand a clear name. - Explain what it does and when to use it in
description. - Describe accepted arguments with a Zod 4
inputSchema. Usez.object({})when no arguments are needed. - Describe the result with
outputSchema. For a Subscription, this describes each emitted value. - Provide a representative
outputSamplefor Builder previews.
Use made-up sample data. Rough receives serialized schemas and samples, not your implementation code. Builder previews use samples instead of live implementations. Never put customer information or secrets in
outputSample.
Inputs are parsed before your implementation runs. Returned or emitted outputs are parsed before the Feature receives them. Validation catches mismatches between your implementation and its declared interface.
Query: read once
This self-contained example uses made-up data. In your application, replace the implementation with an authorized read from your data layer or backend.
import { Query } from '@roughapp/feature'
import { z } from 'zod'
const listMessages = new Query({
id: 'listMessages',
name: 'List messages',
description: 'Return the newest messages in the inbox.',
inputSchema: z.object({
limit: z.number().int().min(1).max(100).default(20),
}),
outputSchema: z.array(
z.object({
id: z.string(),
subject: z.string(),
}),
),
outputSample: [{ id: 'msg_1', subject: 'Welcome' }],
implementation: async ({ limit }) => {
const messages = [{ id: 'msg_1', subject: 'Welcome' }]
return messages.slice(0, limit)
},
})
The Feature supplies arguments such as { limit: 10 }. Zod checks them, then
your implementation receives the parsed input. Omitting limit uses the default
of 20.
You can also call the capability directly from your host app. This uses the same validation as a Feature call:
const messages = await listMessages.call({})
Mutation: change data
A Mutation has the same constructor shape as a Query, but represents a write.
The example below assumes you implement an authenticated /api/messages/read
endpoint that checks whether the caller may update that message.
import { Mutation } from '@roughapp/feature'
import { z } from 'zod'
const markRead = new Mutation({
id: 'markRead',
name: 'Mark read',
description: 'Mark a message in the current user’s inbox as read.',
inputSchema: z.object({ id: z.string() }),
outputSchema: z.object({ success: z.boolean() }),
outputSample: { success: true },
implementation: async ({ id }) => {
const response = await fetch('/api/messages/read', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ id }),
})
if (!response.ok) throw new Error('Could not mark the message as read')
return { success: true }
},
})
Schemas are not permissions. A valid message ID does not prove the user can read or change that message. Enforce authorization in your application and backend as you would for any other request. See Security.
Subscription: watch for updates
A Subscription receives emit first and parsed input second. Call emit with
the current value, then with each update. Return a function that stops your
listener, timer, or other source of updates.
This self-contained example emits the browser's connectivity status. It is a browser signal, not a guarantee that your backend is reachable.
import { Subscription } from '@roughapp/feature'
import { z } from 'zod'
const watchConnection = new Subscription({
id: 'watchConnection',
name: 'Watch connection',
description: 'Report when the browser goes online or offline.',
inputSchema: z.object({}),
outputSchema: z.boolean(),
outputSample: true,
implementation: async (emit, _input) => {
const report = () => emit(navigator.onLine)
report()
window.addEventListener('online', report)
window.addEventListener('offline', report)
return () => {
window.removeEventListener('online', report)
window.removeEventListener('offline', report)
}
},
})
For application data, replace the browser events with your app's observer or subscription mechanism. Send the current value as well as future changes, so a Feature does not have to wait for the next change to show data.
To call a Subscription from host code:
const unsubscribe = await watchConnection.subscribe(
(online) => console.log('Browser online:', online),
{},
)
// Register this with the owning view's teardown; do not call it immediately.
function cleanupConnection() {
unsubscribe()
}
Add capabilities to a Surface
A Feature can use the capabilities in its Surface's toolList. The property
name is toolList, even though the user-facing term is “capabilities”.
Using the capabilities defined above:
import { defineRoughSurface } from '@roughapp/feature'
const surface = defineRoughSurface({
key: 'inbox',
name: 'Inbox',
description: 'The signed-in user’s message inbox.',
toolList: [listMessages, markRead, watchConnection],
})
Keep the Surface and its capability list unchanged while in use. Use consistent definitions for a given Surface key: changing or removing capabilities can break existing Features. Do not push new capabilities into an already-in-use Surface.
Handle validation and implementation errors
For Query and Mutation calls, invalid input, invalid output, or an implementation failure rejects the returned promise. Catch errors from direct host calls where you invoke them.
For a Subscription, input validation and setup failures reject subscribe().
An invalid emitted value throws from emit. Later emissions may happen in event
handlers, after setup has completed: handle errors in those asynchronous sources
where they occur, rather than relying only on a catch around subscribe().
The client's onError handles authentication failures; it is not a global
capability error handler.
Schema input and output types
Most schemas have the same input and output types. Defaults and transformations can make them differ. For example, a schema with a default lets the caller omit a value while the implementation receives that value filled in.
| Boundary | Type |
|---|---|
| Arguments supplied by a caller | z.input<InputSchema> |
| Parsed input received by your implementation | z.output<InputSchema> |
| Output returned or emitted by your implementation | z.input<OutputSchema> |
| Parsed output received by the consumer | z.output<OutputSchema> |
outputSample |
z.output<OutputSchema> |
Use schemas that can be represented in JSON Schema for communication with Rough; not every Zod-specific behavior can be represented there. Keep your first capabilities simple, with JSON-shaped arguments and results.
For the complete constructor and method contracts, see Capabilities in the SDK Reference.