Nurama Developers
Namespaces

ai

Methods and types of the `ai` namespace (`client.ai` / `bot.ai`).

Interfaces

ComposeWithNuRequest

Properties

PropertyTypeDescription
chatIdstringChat being composed into. Read server-side for context and tone.
messagesComposeWithNuTurn[]-
projectId?string-
workspaceIdstring-

ComposeWithNuResponse

Properties

PropertyTypeDescription
balanceAfternumber | null-
billedCreditsnumber-
eventIdstring | null-
proposalstring | nullWording the user may put in their composer, or null for a pure question.
textstringWhat Nu said to the user. Never posted anywhere.

ComposeWithNuTurn

One turn of the drafting conversation, as sent back on each request.

Properties

PropertyTypeDescription
proposal?string | nullWording this turn offered. Held per turn so an earlier draft stays takeable after the conversation has moved on — the user may prefer the version from three turns ago.
role"user" | "assistant"-
textstring-

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

PropertyTypeDescription
assetId?stringAudit-only lineage — the originating asset id.
projectId?string-
sizeInMBnumber-
workspaceIdstring-

CreateRevisionSourceUploadResponse

Properties

PropertyTypeDescription
expiresstringISO-string TTL — the row is reaped after this.
keystringBucket-side keyPath. Pass to nuramaClient.asset.multipartUpload which threads it through into its session-progress + result shape.
scratchIdstringUse as source.scratchId on the subsequent generateRevision call.
uploadIdstringPass back to POST /v1/scratch/:id/complete-upload along with parts.
urlsstring[]One signed PUT URL per multipart part. Single-element array for sub-chunk-size payloads (1080p JPEG frames are well under).

GeneratedTask

Properties

PropertyType
descriptionstring
subjectstring

GenerateImageRevisionRequest

Properties

PropertyTypeDescription
assetId?stringAudit-only — the caller has already resolved the asset's media URL.
jobId?stringGroups 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.dataUrlstring-
projectId?string-
promptstring-
references?string[]Prior revisions to condition on (public URLs or data URLs).
sourceImageRevisionSource-
sourceAspect?numberSource 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.
workspaceIdstring-

GenerateImageRevisionResponse

Properties

PropertyTypeDescription
balanceAfternumber | null-
billedCreditsnumber-
eventIdstring | null-
modelstring-
qualitystring-
revisionIdstringScratch id. The FE forwards this in one of two outcomes: - "Upload to project" → call promoteRevision (this SDK module) to materialise as a project-scoped Asset. - "Attach to chat" → pass { scratchId } as a chat-message attachment item; the chat-send endpoint promotes it to a chat-scoped Asset at send time.
revisionUrlstring | nullPublic URL the FE can render directly.

GenerateTasksRequest

Properties

PropertyTypeDescription
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?stringOptional source chat message id — reserved for future audit linking.
messageTextstring-
projectIdstring-
workspaceIdstring-

GenerateTasksResponse

Properties

PropertyType
balanceAfternumber
billedCreditsnumber
eventIdstring | null
tasksGeneratedTask[]

ListTonesResponse

Properties

PropertyType
tonesToneEntry[]

PolishRequest

Properties

PropertyType
projectId?string
textstring
toneIdstring
workspaceIdstring

PolishResponse

Properties

PropertyType
balanceAfternumber
billedCreditsnumber
eventIdstring | null
polishedTextstring

SubmitAiFeedbackRequest

One Nu Feedback submission.

Properties

PropertyTypeDescription
chatIdstring-
contextItems?Record<string, unknown>[]-
messageId?string-
notes?stringThe user's own words on what worked or didn't. Optional.
pageContext?Record<string, unknown>Extras the client already holds, folded into the stored snapshot.
projectId?string-
rating"positive" | "negative"-
surface"chat" | "assist"Which AI surface produced the reply — the two are tuned separately.
workspaceId?string-

TaskGenerationContextMessage

Properties

PropertyTypeDescription
authorName?stringDisplay name of the message author. Optional but improves the prompt.
contentstring-

ToneEntry

Properties

PropertyType
idstring
labelstring

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 via createRevisionSourceUpload. 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 the scratchId flow.

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

ParameterType
clientdefault

Returns

NameTypeDescription
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.

On this page