ambleloftMessages and action result API
@ambleloft/extension-sdk/messages-preview: local business messages, concurrent updates and traceable actions.
Browse contracts, signatures, fields and examples. Unspecified defaults are not inferred.
On this page
01LocalMessageInput
Preview capability · SDK 0.1.0-alpha.9
Input to publish. expiresAt is Unix milliseconds, a nonnegative safe integer or null. At most two actions, bound to same-extension page operations.
type LocalizedText = string | { key: string; args?: Record<string, string | number | boolean> };
interface LocalMessageInput {
eventKey: string; title: LocalizedText; body: LocalizedText;
category: 'notice' | 'actionRequired';
severity?: 'info' | 'warning' | 'error';
businessType?: string | null;
expiresAt?: number | null;
actions?: { id: string; label: LocalizedText; commandId: string;
arguments?: Record<string, unknown> }[];
}02LocalMessages methods
Preview capability · SDK 0.1.0-alpha.9
Methods act on the current extension local messages. There is no method to read all user messages or retrieve account tokens. getMessages(context) returns the API synchronously. getMessages checks all seven methods and throws UNSUPPORTED if any is missing. This does not grant permission or bypass user preferences.
| Field / API | Contract |
|---|---|
| publish(input): Promise<PublishResult> | Publish or return duplicate / dismissed / rejected. |
| getByEventKey(eventKey): Promise<LocalMessage|null> | Look up a stable business key. |
| update(id,patch,expectedRevision): Promise<LocalMessage|null> | Revision-checked update; may return null when absent. |
| withdraw(id,expectedRevision): Promise<LocalMessage|null> | Revision-checked withdrawal. |
| getPreferences(): Promise<MessagePreferences> | Returns {receive:boolean, muted:boolean}. |
| listActionInvocations(): Promise<MessageActionInvocation[]> | Only dispatching, accepted and unknown actions; not complete history. |
| reportActionResult(input): Promise<{invocation,message}> | Report an outcome; message is LocalMessage or null. |
03Publication results and message state
Preview capability · SDK 0.1.0-alpha.9
LocalMessage contains id, eventKey, title, body, category, severity, businessType, actions, expiresAt, revision, receivedAt and updatedAt. It does not expose readAt, dismissedAt, user identity or credentials.
type PublishResult =
| { status: 'published'; id: string; revision: number; remind: boolean }
| { status: 'duplicate' | 'dismissed'; id: string }
| { status: 'rejected' };
// Additional LocalMessage state fields:
// validity: 'active' | 'expired' | 'withdrawn'
// businessState: 'pending' | 'resolved' | null04Patches and invocation records
Preview capability · SDK 0.1.0-alpha.9
LocalMessagePatch optionally updates title, body, severity, actions, expiresAt, businessState and validity. It cannot change eventKey or category. MessageActionInvocation contains id, messageId, actionId, operationId, revision, state, optional remoteTaskId, createdAt and updatedAt. The record includes effect: 'read' | 'write'. Its id becomes invocationId in reports. A successful handler return does not automatically mean completed.
type InvocationState = 'prepared' | 'dispatching' | 'accepted'
| 'completed' | 'failed' | 'unknown' | 'notExecuted';05ActionResultReport
Preview capability · SDK 0.1.0-alpha.9
The two revisions belong to the invocation record and the message respectively. reportId must stably identify one report; do not reuse it for different content.
interface ActionResultReport {
invocationId: string;
reportId: string;
expectedRevision: number;
outcome: 'accepted' | 'completed' | 'failed' | 'unknown';
remoteTaskId?: string;
messageUpdate?: { patch: LocalMessagePatch; expectedRevision: number };
}