Acknowledgements
Acknowledgements
Hosts answer effects with augeo.ack. Join on ack.eventId === event.id.
First settlement wins. Later acks for the same eventId are ignored.
Hosts never send outcome.status unacknowledged. The waiting layer mints that locally.
Cart and wishlist writes are recommend-only. The host composes its own mutations.
Prerequisites
| Item | Requirement |
|---|---|
| Persona | loyalty-concierge only |
| Bundle global | window.AugeoChatSdkLoyaltyConcierge |
| Upward event | Compact augeo.event with a non-empty id |
Read Events and Event envelope first.
Constants
| Name | Value | Use |
|---|---|---|
AUGEO_ACK_EVENT | augeo.ack | Downward CustomEvent name |
| Spec | augeo.ack | Value of spec on every ack |
| Spec version | 1.0 | Value of specversion |
| Default bound | 5000 ms | HOST_MUTATION_ACK_TIMEOUT_MS |
subscribeAugeoAcks drops unacknowledged outcomes. Hosts must not send that status.
Ack envelope
| Field | Required | Meaning |
|---|---|---|
spec | yes | Constant augeo.ack |
specversion | yes | Constant 1.0 |
eventId | yes | Matching upward event.id |
time | yes | Ack time in epoch milliseconds |
outcome | yes | fulfilled or rejected from hosts |
effectId | no | Effect id from the upward event |
context | no | Optional context bags |
Outcomes
outcome.status | Host may send | Shape |
|---|---|---|
fulfilled | yes | { status: 'fulfilled', data?: unknown } |
rejected | yes | { status: 'rejected', error: AugeoError } |
unacknowledged | no | Widget-only after timeout |
Rejected error
| Field | Required | Meaning |
|---|---|---|
code | yes | Stable machine code |
message | yes | One human-readable sentence |
class | yes | Failure class listed below |
retryable | no | Whether a retry is meaningful |
details | no | Ignore-unknown extension channel |
error.class | Meaning |
|---|---|
offline | Member device is offline |
unreachable | Host endpoint could not be reached |
timeout | Host operation timed out |
rate-limited | Host refused the write as too frequent |
unauthorized | Member session is not allowed |
content-filtered | Host blocked the content |
cancelled | Member or host cancelled the write |
server | Host server failure |
unknown | None of the classes above |
cart.add fulfilled data
Fulfilled cart-add data is CartAddAckResult. Every number must be finite and non-negative.
| Field | Type |
|---|---|
cartTransition.beforePointsTotal | number |
cartTransition.afterPointsTotal | number |
cartTransition.memberPointsBalance | number |
The host supplies all three values from its cart mutation. The widget never calculates, clamps, or substitutes them.
Missing, negative, NaN, or infinite values are not reportable. Extra fields are ignored.
Dispatch a fulfilled ack
const { AUGEO_ACK_EVENT, dispatchAugeoAck } =
window.AugeoChatSdkLoyaltyConcierge;
const ack = {
spec: 'augeo.ack',
specversion: '1.0',
eventId: event.id,
time: Date.now(),
outcome: {
status: 'fulfilled',
data: {
cartTransition: {
beforePointsTotal: 100,
afterPointsTotal: 700,
memberPointsBalance: 500,
},
},
},
};
document.dispatchEvent(
new CustomEvent(AUGEO_ACK_EVENT, {
detail: ack,
bubbles: true,
composed: true,
}),
);
// Same payload through the helper:
dispatchAugeoAck(document, ack);Dispatch a rejected ack
document.dispatchEvent(
new CustomEvent(AUGEO_ACK_EVENT, {
detail: {
spec: 'augeo.ack',
specversion: '1.0',
eventId: event.id,
time: Date.now(),
outcome: {
status: 'rejected',
error: {
code: 'out_of_stock',
message: 'Item is out of stock.',
class: 'unknown',
retryable: false,
},
},
},
bubbles: true,
composed: true,
}),
);Subscribe to acks
const { subscribeAugeoAcks } = window.AugeoChatSdkLoyaltyConcierge;
const unsubscribe = subscribeAugeoAcks(document, (ack) => {
recordHostAck(ack);
});- Read
event.idfrom the upwardaugeo.event. - Write an
augeo.ackwith matchingeventId. - Call
document.dispatchEventwithbubblesandcomposed. - Write
fulfilledorrejectedonly. - Supply
CartAddAckResultdata for a fulfilled cart add.
Join the ack to the upward event you are settling. Measured siblings mint a new id.
Related pages
| Topic | Page |
|---|---|
| Handling rules | Events |
| Compact field list | Event envelope |
| Names this widget emits | Event catalog |
| JSON schema | Events v1 |
| Public helpers | API |
| Event capability options | Event options |
| Widget configuration | Configuration |
| Product scope | Overview |