Publish and update business messages

01Get the preview messages API

Preview capability · SDK 0.1.0-alpha.9

Call getMessages(context) only in the extension backend. Unsupported hosts throw UNSUPPORTED; do not pretend publication succeeded. The function below can be called by a registered business operation, not by a browser page.

import type { ExtensionContext } from '@ambleloft/extension-sdk';
import { getMessages } from '@ambleloft/extension-sdk/messages-preview';

export async function notifyReady(context: ExtensionContext) {
  const messages = getMessages(context);
  return messages.publish({
    eventKey: 'report:quarterly:ready',
    title: 'Report ready',
    body: 'Your quarterly report is ready to review.',
    category: 'notice',
    severity: 'info',
    actions: []
  });
}

02Handle publish results

Use a stable business event identifier for eventKey. Do not invent a new random key for duplicates. Republishing is not a content update. Outcomes are published, duplicate, dismissed or rejected; only published includes revision and remind.

03Update and withdraw

Read the current revision before an optimistic update. On conflict, reread and decide rather than overwriting blindly. User preferences control receipt and muting; getPreferences returns receive and muted.

const message = await messages.getByEventKey('report:quarterly:ready');
if (message) {
  await messages.update(message.id, { body: 'Report reviewed.' }, message.revision);
}
// To withdraw, read the current revision again:
const current = await messages.getByEventKey('report:quarterly:ready');
if (current) await messages.withdraw(current.id, current.revision);

04Runnable sample and acceptance

Run local-messages. Publish twice with the same eventKey and verify no second fresh reminder. Update the body, withdraw it and inspect the state. This API writes to the host local message center; it does not send email, mobile push or subscribe to Agent tasks.