@band-ai/band-sdk-core 2.0.0 → 2.2.0

package/README.md

@@ -148,6 +148,57 @@ native `Error` with the same `.issues`/`.traceContext` contract as
 `type` are independent issues, both reported when both strings are
 invalid.
 
+### One-shot delivery lifecycle
+
+`evaluateDeliveryEvent`, `evaluateNextMessage`, `evaluateDrainCandidate`, and
+`evaluateAdapterResult` are the stateless one-shot delivery lifecycle
+decisions — design decisions live as rustdoc in
+`crates/core/src/runtime/delivery.rs`. Each returns a plain tagged object;
+there is no cross-invocation state, so there is no class here to construct.
+Decision fields stay snake_case (message-wire vocabulary: `room_id`,
+`sender_id`, `sender_type`, …), unlike this module's own camelCase
+function/argument names, so the same shape returns identically from both
+bindings.
+
+`evaluateDeliveryEvent(eventType, roomId, payload, agentId, traceContext?)`
+routes one inbound event: `"ignored"` for an unrecognized or out-of-scope
+`eventType`; `"cleanup"` for `room_removed`/`room_deleted`; `"skip_self"` or
+`"invocation"` for `message_created`, depending on whether the sender is
+this agent (`sender_type === "Agent"` and `sender_id === agentId`).
+`message_created` delegates to `validateEventPayload` for payload-shape
+validation, so a malformed `payload` throws the same `Error`, and
+additionally rejects an empty `payload.id` — a message with no identity
+cannot be claimed or acknowledged. `room_removed`/`room_deleted` need no
+payload shape and read `id` straight off the raw payload.
+
+`roomId` resolves from the caller-supplied `roomId` first, else the payload's
+own `chat_room_id` (message events) or `id` (room events). An empty string
+counts as absent at both steps. Unresolvable throws an `Error` with one issue
+on path `room_id`: code `missing` when the fallback field is absent or empty,
+`wrong_type` when it is present but not a string.
+
+`evaluateNextMessage(triggeringMessageId, nextMessageId)` compares the
+triggering message against the platform's authoritative "next open message"
+for a room (already fetched by the caller): `"no_pending"`,
+`"already_processed"`, or `"ready_to_claim"`.
+
+`evaluateDrainCandidate(candidate, seenIds, agentId)` classifies one
+already-fetched drain candidate — `candidate` is `{id, sender_id,
+sender_type}`, or `null`/`undefined` when the fetch returned nothing:
+`"no_candidate"`, `"self_echo"` (checked before the snapshot, so an echo
+never halts a drain), `"out_of_snapshot"` (stop), or `"drain"` (continue).
+The caller's own bounded or unbounded loop owns the cap; this function
+classifies one candidate per call.
+
+`evaluateAdapterResult(roomId, messageId, succeeded)` maps an adapter
+outcome to `"processed"` or `"failed"`.
+
+`isSelfEcho(senderId, senderType, agentId)` is the one definition of
+"self echo" (`senderType === "Agent" && senderId === agentId`) that
+`evaluateDeliveryEvent` and `evaluateDrainCandidate` use internally,
+exposed for a host's own call sites that classify a sender without going
+through either function.
+
 The public declaration is
 [`index.d.ts`](https://github.com/band-ai/band-sdk-core/blob/main/crates/wasm/index.d.ts).
 

package/band_sdk_core.js

@@ -1206,6 +1206,102 @@ function classifyUpgrade(status) {
 }
 exports.classifyUpgrade = classifyUpgrade;
 
+/**
+ * Adapter outcome -> ack decision. Throws a plain `Error` if `roomId`/
+ * `messageId` is not a string.
+ * @param {any} roomId
+ * @param {any} messageId
+ * @param {boolean} succeeded
+ * @returns {any}
+ */
+function evaluateAdapterResult(roomId, messageId, succeeded) {
+    const ret = wasm.evaluateAdapterResult(roomId, messageId, succeeded);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.evaluateAdapterResult = evaluateAdapterResult;
+
+/**
+ * Evaluate the routing decision for one inbound platform event.
+ *
+ * On failure throws a native `Error` with `.issues` (an array of
+ * `{path, code, message}` objects) and `.traceContext`. A non-string
+ * `eventType`/`roomId`/`agentId`/`traceContext`, or a `payload` that
+ * cannot be converted, throws a plain `Error` without `.issues`.
+ * @param {any} eventType
+ * @param {any} roomId
+ * @param {any} payload
+ * @param {any} agentId
+ * @param {any} traceContext
+ * @returns {any}
+ */
+function evaluateDeliveryEvent(eventType, roomId, payload, agentId, traceContext) {
+    const ret = wasm.evaluateDeliveryEvent(eventType, roomId, payload, agentId, traceContext);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.evaluateDeliveryEvent = evaluateDeliveryEvent;
+
+/**
+ * One step of the drain loop. `candidate` is `{id, sender_id,
+ * sender_type}` or `null`/`undefined` when the host's fetch returned no
+ * candidate; a malformed object throws a plain `Error`.
+ * @param {any} candidate
+ * @param {any} seenIds
+ * @param {any} agentId
+ * @returns {any}
+ */
+function evaluateDrainCandidate(candidate, seenIds, agentId) {
+    const ret = wasm.evaluateDrainCandidate(candidate, seenIds, agentId);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.evaluateDrainCandidate = evaluateDrainCandidate;
+
+/**
+ * Compares the triggering message against the platform's authoritative
+ * "next open message" for a room. Throws a plain `Error` if
+ * `triggeringMessageId`/`nextMessageId` is not a string (or `null`/
+ * `undefined` for `nextMessageId`).
+ * @param {any} triggeringMessageId
+ * @param {any} nextMessageId
+ * @returns {any}
+ */
+function evaluateNextMessage(triggeringMessageId, nextMessageId) {
+    const ret = wasm.evaluateNextMessage(triggeringMessageId, nextMessageId);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.evaluateNextMessage = evaluateNextMessage;
+
+/**
+ * The one definition of "self echo" (`senderType === "Agent" &&
+ * senderId === agentId`), shared by `evaluateDeliveryEvent` and
+ * `evaluateDrainCandidate` internally and exposed here for a host's own
+ * call sites that don't go through either. Throws a plain `Error` if
+ * `senderId`/`senderType`/`agentId` is not a string.
+ * @param {any} senderId
+ * @param {any} senderType
+ * @param {any} agentId
+ * @returns {boolean}
+ */
+function isSelfEcho(senderId, senderType, agentId) {
+    const ret = wasm.isSelfEcho(senderId, senderType, agentId);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return ret[0] !== 0;
+}
+exports.isSelfEcho = isSelfEcho;
+
 /**
  * This platform's Phoenix Channels topic for a room's `room_participants`
  * channel.
@@ -1386,6 +1482,10 @@ function __wbg_get_imports() {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
+        __wbg_get_with_ref_key_6412cf3094599694: function(arg0, arg1) {
+            const ret = arg0[arg1];
+            return ret;
+        },
         __wbg_instanceof_ArrayBuffer_993d02d2d254cad1: function(arg0) {
             let result;
             try {

package/index.d.ts

@@ -364,3 +364,148 @@ export class RoomRoster {
   reconcile(currentRoomIds: string[]): RoomReconciliation;
   clear(): string[];
 }
+
+// The one-shot delivery lifecycle decisions: evaluateDeliveryEvent,
+// evaluateNextMessage, evaluateDrainCandidate, evaluateAdapterResult.
+// Each returns a plain tagged object -- these functions carry no
+// cross-invocation state, so there is no class here to construct. Decision
+// fields stay snake_case (message-wire vocabulary: `room_id`, `sender_id`,
+// `sender_type`, ...), unlike this module's own camelCase function/argument
+// names, so the same shape is returned identically from both bindings.
+
+export interface EventIgnored {
+  decision: "ignored";
+  event_type: string;
+}
+export interface EventCleanup {
+  decision: "cleanup";
+  room_id: string;
+}
+export interface EventSkipSelf {
+  decision: "skip_self";
+  room_id: string;
+  message_id: string;
+}
+export interface EventInvocation {
+  decision: "invocation";
+  room_id: string;
+  message_id: string;
+  sender_id: string;
+  sender_type: string;
+}
+export type EventDecision = EventIgnored | EventCleanup | EventSkipSelf | EventInvocation;
+
+/**
+ * Evaluate the routing decision for one inbound platform event.
+ *
+ * `message_created` delegates to {@link validateEventPayload}'s own
+ * validation; a rejection there throws the same native `Error` with
+ * `.issues`/`.traceContext`, as does an empty `payload.id`.
+ * `room_removed`/`room_deleted` need no payload shape and read `id` straight
+ * off the raw payload. Both event kinds throw that same `Error` shape when
+ * `roomId` resolves from neither the envelope nor the payload — an empty
+ * string counting as absent — with issue code `missing` when the fallback
+ * field is absent or empty and `wrong_type` when it is present but not a
+ * string. Throws a plain `Error` without `.issues` if
+ * `eventType`/`roomId`/`agentId`/`traceContext` is not a string (or not
+ * `null`/`undefined` for `roomId`/`traceContext`), or if `payload` cannot be
+ * converted.
+ */
+export function evaluateDeliveryEvent(
+  eventType: string,
+  roomId: string | null | undefined,
+  payload: unknown,
+  agentId: string,
+  traceContext?: string | null,
+): EventDecision;
+
+export interface NextMessageNoPending {
+  decision: "no_pending";
+}
+export interface NextMessageAlreadyProcessed {
+  decision: "already_processed";
+  next_open_id: string;
+}
+export interface NextMessageReadyToClaim {
+  decision: "ready_to_claim";
+}
+export type NextMessageDecision =
+  | NextMessageNoPending
+  | NextMessageAlreadyProcessed
+  | NextMessageReadyToClaim;
+
+/**
+ * Compares the triggering message against the platform's authoritative
+ * "next open message" for a room. Throws a plain `Error` if
+ * `triggeringMessageId` is not a string, or `nextMessageId` is not a
+ * string, `null`, or `undefined`.
+ */
+export function evaluateNextMessage(
+  triggeringMessageId: string,
+  nextMessageId: string | null | undefined,
+): NextMessageDecision;
+
+/** One already-fetched drain candidate, matching `evaluateDeliveryEvent`'s own field names. */
+export interface DrainCandidate {
+  id: string;
+  sender_id: string;
+  sender_type: string;
+}
+export interface DrainNoCandidate {
+  decision: "no_candidate";
+}
+export interface DrainOutOfSnapshot {
+  decision: "out_of_snapshot";
+  message_id: string;
+}
+export interface DrainSelfEcho {
+  decision: "self_echo";
+  message_id: string;
+}
+export interface DrainMessage {
+  decision: "drain";
+  message_id: string;
+}
+export type DrainStep = DrainNoCandidate | DrainOutOfSnapshot | DrainSelfEcho | DrainMessage;
+
+/**
+ * One step of the drain loop. `candidate` is `null`/`undefined` when the
+ * host's fetch returned no candidate. Throws a plain `Error` if
+ * `candidate` is present but malformed, or if `agentId` is not a string.
+ */
+export function evaluateDrainCandidate(
+  candidate: DrainCandidate | null | undefined,
+  seenIds: string[],
+  agentId: string,
+): DrainStep;
+
+export interface AckProcessed {
+  decision: "processed";
+  room_id: string;
+  message_id: string;
+}
+export interface AckFailed {
+  decision: "failed";
+  room_id: string;
+  message_id: string;
+}
+export type AckDecision = AckProcessed | AckFailed;
+
+/**
+ * Adapter outcome -> ack decision. Throws a plain `Error` if `roomId`/
+ * `messageId` is not a string.
+ */
+export function evaluateAdapterResult(
+  roomId: string,
+  messageId: string,
+  succeeded: boolean,
+): AckDecision;
+
+/**
+ * The one definition of "self echo" (`senderType === "Agent" &&
+ * senderId === agentId`), shared by {@link evaluateDeliveryEvent} and
+ * {@link evaluateDrainCandidate} internally and exposed here for a host's
+ * own call sites that don't go through either. Throws a plain `Error` if
+ * `senderId`/`senderType`/`agentId` is not a string.
+ */
+export function isSelfEcho(senderId: string, senderType: string, agentId: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@band-ai/band-sdk-core",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Shared Band event-payload validation",
   "license": "MIT",
   "repository": {