salamandr-plugin-sdk 0.3.0

Write Salamandr helpdesk extensions in Rust: safe typed wrappers for every host capability, the fetch_context wire contract, and an in-process mock host for testing.
Documentation
//! The wire contract of `chatops_post_root`/`chatops_post_reply`/
//! `chatops_receive` — the fixed entrypoint trio a `kind = "chatops"`
//! plugin must implement (see `extwasm.KindChatops`'s manifest
//! requirement) — plus the optional `chatops_search_members`/
//! `chatops_list_channels`/`chatops_message_url`.
//!
//! These types are a field-for-field mirror of
//! internal/extwasm/adapter.go's Chatops*/ThreadNoteInput types. Parity
//! is pinned from the Go side by internal/extwasm/sdkcontract_test.go,
//! the same way [`crate::channel`]'s types are.
//!
//! # `chatops_post_root`/`chatops_post_reply` receive already-rendered text
//!
//! `internal/chatops/markdown.go` renders the ticket event into the
//! dialect this plugin's manifest declares (`dialect = "markdown"` or
//! `"mrkdwn"`) *before* calling either op — a chatops plugin never
//! implements markdown rendering itself, only delivery (via
//! [`crate::http_fetch`]) and reporting back the vendor's own message id.
//!
//! # `chatops_receive` is a pure function
//!
//! Same shape as [`crate::channel`]'s `channel_receive`: it answers "what
//! notes does this webhook payload contain", nothing more — no note is
//! recorded by the call itself. The host's own chatops webhook dispatcher
//! records each returned [`ThreadNoteInput`] afterwards, unconditionally.

use serde::{Deserialize, Serialize};

/// PostRootRequest is what the host passes to `chatops_post_root`
/// — `text` is already rendered, see this module's doc comment.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct PostRootRequest {
    pub text: String,
}

/// PostRootResponse is `chatops_post_root`'s successful answer —
/// the vendor's own id for the message it just created.
#[derive(Debug, Clone, Default, Serialize)]
pub struct PostRootResponse {
    pub root_message_id: String,
}

/// PostRootResult is the exact return type `chatops_post_root`
/// must have.
pub type PostRootResult = Result<PostRootResponse, crate::OpError>;

/// PostReplyRequest is what the host passes to `chatops_post_reply`.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct PostReplyRequest {
    pub root_message_id: String,
    pub text: String,
}

/// PostReplyResponse is `chatops_post_reply`'s successful answer.
#[derive(Debug, Clone, Default, Serialize)]
pub struct PostReplyResponse {
    pub message_id: String,
}

/// PostReplyResult is the exact return type `chatops_post_reply`
/// must have.
pub type PostReplyResult = Result<PostReplyResponse, crate::OpError>;

/// ThreadNoteInput is one already-parsed inbound note `chatops_receive`
/// answers with — mirrors what internal/chatops.Service.RecordThreadNote
/// takes, minus tenant/provider/ticket context the host already knows.
/// `external_thread_id` is the vendor's own root-message id (how the host
/// finds which ticket this belongs to); `occurred_at`, if set, is
/// RFC 3339 — the host falls back to "now" when empty.
#[derive(Debug, Clone, Default, Serialize)]
pub struct ThreadNoteInput {
    pub external_thread_id: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub external_message_id: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub author_name: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub author_email: String,
    pub body: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub occurred_at: String,
}

/// ReceiveResponse is `chatops_receive`'s successful answer — a
/// plain list, no partial-failure shape: a webhook delivery carrying zero
/// notes (a vendor's own handshake/ping event, say) is
/// `Ok(ReceiveResponse { notes: vec![] })`, not an error.
#[derive(Debug, Clone, Default, Serialize)]
pub struct ReceiveResponse {
    pub notes: Vec<ThreadNoteInput>,
}

/// ReceiveResult is the exact return type `chatops_receive` must
/// have.
pub type ReceiveResult = Result<ReceiveResponse, crate::OpError>;

/// Mention mirrors internal/chatops.Mention — one live search
/// result from the optional `chatops_search_members`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct Mention {
    pub external_id: String,
    pub display_name: String,
}

/// Channel mirrors internal/chatops.Channel — one entry from the
/// optional `chatops_list_channels`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct Channel {
    pub id: String,
    pub name: String,
}

/// SearchMembersRequest is what the optional `chatops_search_members`
/// receives.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct SearchMembersRequest {
    pub query: String,
}

/// MessageURLRequest is what the optional `chatops_message_url`
/// receives.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct MessageURLRequest {
    pub message_id: String,
}

/// ListChannelsRequest is what the optional `chatops_list_channels`
/// receives — no fields, but a struct (not `()`) since the host always
/// sends `{}`, not an empty payload.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct ListChannelsRequest {}

/// Return types for the three optional ops — plain lists/strings, no
/// dedicated response wrapper struct needed.
pub type SearchMembersResult = Result<Vec<Mention>, crate::OpError>;
pub type ListChannelsResult = Result<Vec<Channel>, crate::OpError>;
pub type MessageURLResult = Result<String, crate::OpError>;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn post_root_response_serializes_to_the_go_wire_shape() {
        let got = serde_json::to_value(PostRootResponse { root_message_id: "m1".into() }).expect("serialize");
        assert_eq!(got, serde_json::json!({"root_message_id": "m1"}));
    }

    #[test]
    fn receive_response_omits_blank_optional_note_fields() {
        let resp = ReceiveResponse {
            notes: vec![ThreadNoteInput {
                external_thread_id: "root-1".into(),
                body: "hi".into(),
                ..Default::default()
            }],
        };
        let got = serde_json::to_value(&resp).expect("serialize");
        let note = &got["notes"][0];
        assert_eq!(note["external_thread_id"], "root-1");
        assert_eq!(note["body"], "hi");
        assert!(note.get("author_name").is_none(), "blank author_name must be omitted, got {note}");
        assert!(note.get("occurred_at").is_none(), "blank occurred_at must be omitted, got {note}");
    }

    #[test]
    fn post_root_request_decodes_the_host_input() {
        let req: PostRootRequest = serde_json::from_str(r#"{"text":"a new ticket"}"#).expect("decode");
        assert_eq!(req.text, "a new ticket");
    }

    #[test]
    fn list_channels_request_decodes_an_empty_object() {
        let _req: ListChannelsRequest = serde_json::from_str("{}").expect("decode");
    }
}