ai
Methods and types of the `ai` namespace (`client.ai` / `bot.ai`).
Interfaces
ComposeWithNuRequest
Properties
| Property | Type | Description |
|---|---|---|
chatId | string | Chat being composed into. Read server-side for context and tone. |
messages | ComposeWithNuTurn[] | - |
projectId? | string | - |
workspaceId | string | - |
ComposeWithNuResponse
Properties
ComposeWithNuTurn
One turn of the drafting conversation, as sent back on each request.
Properties
CreateRevisionSourceUploadRequest
Source-upload mint request. Returns a multipart upload bundle the
FE drives like any other scratch / asset upload (PUT each urls[i]
with the corresponding part, collect the ETags, call complete-
upload). Server hardcodes mime to image/jpeg — the only producer
is the captured video frame, which is always JPEG. Size cap
(matches OpenAI's images/edits per-image limit): 25 MB.
Properties
| Property | Type | Description |
|---|---|---|
assetId? | string | Audit-only lineage — the originating asset id. |
projectId? | string | - |
sizeInMB | number | - |
workspaceId | string | - |
CreateRevisionSourceUploadResponse
Properties
GeneratedTask
Properties
GenerateImageRevisionRequest
Properties
| Property | Type | Description |
|---|---|---|
assetId? | string | Audit-only — the caller has already resolved the asset's media URL. |
jobId? | string | Groups all revisions from one modal session. |
mask? | { dataUrl: string; } | Optional alpha-channel mask PNG (data URL) matching the source image's dimensions. Transparent pixels mark the edit region; opaque pixels are preserved. When supplied, the server forwards it as OpenAI's top-level mask field — NOT as another references[] entry — and auto-augments the prompt with a region directive. |
mask.dataUrl | string | - |
projectId? | string | - |
prompt | string | - |
references? | string[] | Prior revisions to condition on (public URLs or data URLs). |
source | ImageRevisionSource | - |
sourceAspect? | number | Source image's aspect ratio (width / height). Two effects when set: 1. The server picks the closest OpenAI-supported generation size — landscape, portrait, or square — instead of always generating 1024×1024. Reduces the gap between the model's output aspect and the source aspect before any padding. 2. After generation, the server pads the result with black bars (letterbox/pillarbox) so the final bytes exactly match this aspect. The user gets an output image whose framing matches the input they started from, with the generated content centred and the unfilled edges padded. Omit (or pass 1.0) for legacy square output. |
workspaceId | string | - |
GenerateImageRevisionResponse
Properties
GenerateTasksRequest
Properties
| Property | Type | Description |
|---|---|---|
contextMessages? | TaskGenerationContextMessage[] | Preceding chat messages (oldest first) to give the model conversational lead-in. Server caps at 10 messages and trims long content per-message; the focal messageText is the actual instruction. |
messageId? | string | Optional source chat message id — reserved for future audit linking. |
messageText | string | - |
projectId | string | - |
workspaceId | string | - |
GenerateTasksResponse
Properties
| Property | Type |
|---|---|
balanceAfter | number |
billedCredits | number |
eventId | string | null |
tasks | GeneratedTask[] |
ListTonesResponse
Properties
| Property | Type |
|---|---|
tones | ToneEntry[] |
PolishRequest
Properties
PolishResponse
Properties
SubmitAiFeedbackRequest
One Nu Feedback submission.
Properties
TaskGenerationContextMessage
Properties
| Property | Type | Description |
|---|---|---|
authorName? | string | Display name of the message author. Optional but improves the prompt. |
content | string | - |
ToneEntry
Properties
Type Aliases
ImageRevisionSource
type ImageRevisionSource =
| {
url: string;
}
| {
scratchId: string;
}
| {
dataUrl: string;
};Source for an image revision call. Exactly one of:
url— public media URL (typical for image assets).scratchId— id of a Scratch row the FE uploaded viacreateRevisionSourceUpload. Preferred for captured video frames so bytes never transit the API node.dataUrl— DEPRECATED legacy path: FE-captured video frame serialised as a base64 data URL inline in the request body. Kept here for back-compat during FE rollout; new code should always use thescratchIdflow.
Functions
default()
function default(client): {
composeWithNu: Promise<ComposeWithNuResponse>;
createRevisionSourceUpload: Promise<CreateRevisionSourceUploadResponse>;
generateRevision: Promise<GenerateImageRevisionResponse>;
generateTasks: Promise<GenerateTasksResponse>;
listTones: Promise<ListTonesResponse>;
polish: Promise<PolishResponse>;
submitFeedback: Promise<{
id: string;
}>;
};Methods for the Nu AI assistant integration points.
Nu is the platform-native AI feature set. Each integration point is gated
by workspace settings (allowAiFeatures master switch + per-feature toggle
- role allowlist) and metered against the workspace's credit balance.
MVP exposes a single integration point — Polish — used by the chat composer to rewrite a draft message in a selected tone.
Parameters
| Parameter | Type |
|---|---|
client | default |
Returns
| Name | Type | Description |
|---|---|---|
composeWithNu() | (data) => Promise<ComposeWithNuResponse> | One turn of a Compose-with-Nu drafting conversation. Send only the drafting thread — the chat being written into is read server-side from chatId, under the caller's own permissions. The result is Nu's commentary plus, when it has one, a proposed message. Nothing is posted: the proposal is the user's to take or discard. |
createRevisionSourceUpload() | (data) => Promise<CreateRevisionSourceUploadResponse> | Mint a signed-URL bundle for uploading a source image (typically a captured video frame) into Scratch BEFORE calling generateRevision. Use the resulting scratchId as the source.scratchId on the generate call. Why this exists: video frames are captured client-side and need to reach OpenAI as a public media URL. Posting the bytes inline (as dataUrl) makes the API node a pass-through for multi-MB payloads; staging on Scratch first keeps the node out of the byte path entirely. |
generateRevision() | (data) => Promise<GenerateImageRevisionResponse> | Generate one image revision (prompt-driven variant of a source image or video frame). The result is staged on Scratch — the FE then chooses one of two outcomes: - "Add to project" → call nuramaClient.scratch.promote(id) to create a project-scoped Asset immediately. - "Attach to chat" → leave the scratch id in the chat composer's pending attachments; the chat-send endpoint accepts { scratchId, name? } items in attachments[] and promotes each to a chat-scoped Asset at send time. |
generateTasks() | (data) => Promise<GenerateTasksResponse> | Convert a chat message into one or more board-task drafts. The frontend opens the EnhancedTaskCreatorModal in a loading state, calls this method, and seeds the modal's draft list from the response's tasks array. Requires both the AI add-on AND the Boards add-on on the workspace; the server returns productNotActive if either is missing. |
listTones() | () => Promise<ListTonesResponse> | Returns the catalogue of polish tones the platform supports. The FE uses this to populate the tone dropdown without hard-coding the IDs. |
polish() | (data) => Promise<PolishResponse> | - |
submitFeedback() | (data) => Promise<{ id: string; }> | Record a thumbs-up / thumbs-down on one assistant reply. chatId is required because it is what the server authorises against — a user can only rate a reply in a chat they can already read — and it is what the stored transcript snapshot is built from. |