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 `calendar_sync_meeting`/`calendar_sync_delete_meeting`/
//! `calendar_sync_free_busy`/`calendar_sync_ensure_watch` — the four
//! entrypoints a `kind = "connector"` plugin implements when it also
//! declares `scopes.calendar_sync = true` (see `extwasm.Scopes.CalendarSync`'s
//! manifest requirement). Register them through the same
//! [`crate::Registry::connector_op`]/`connector_ops:` block
//! [`crate::connector`]'s trio uses — a calendar-sync connector is, at the
//! wire level, still "the host calls one of my ops and decodes the answer
//! directly with no `Outcome` wrapper."
//!
//! These types are a field-for-field mirror of internal/extwasm/adapter.go's
//! CalendarSync* types. Parity is pinned from the Go side by
//! internal/extwasm/sdkcontract_test.go.
//!
//! Network access is the same [`crate::oauth_fetch`] every connector op
//! uses. The one new direction, reporting an external move/cancellation
//! back to the host, is not a `calendar_sync_*` op at all — see
//! [`crate::core::apply_external_calendar_update`], callable from inside a
//! `webhook_receive` or `scheduled_run` handler after the plugin re-fetches
//! the changed event itself.

use serde::{Deserialize, Serialize};

/// MeetingRequest is what the host passes to
/// `calendar_sync_meeting`. A `None` `existing_external_event_id` means
/// create; `Some` means update the event already mirrored under that id.
/// `start`/`end` are RFC 3339.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct MeetingRequest {
    pub connection_user_id: String,
    pub existing_external_event_id: Option<String>,
    pub title: String,
    pub description: String,
    pub location_url: String,
    pub recurrence_rule: String,
    pub start: String,
    pub end: String,
}

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

/// MeetingResult is the exact return type `calendar_sync_meeting`
/// must have.
pub type MeetingResult = Result<MeetingResponse, crate::OpError>;

/// DeleteMeetingRequest is what the host passes to
/// `calendar_sync_delete_meeting`.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct DeleteMeetingRequest {
    pub connection_user_id: String,
    pub external_event_id: String,
}

/// DeleteMeetingResult is the exact return type
/// `calendar_sync_delete_meeting` must have — a bare acknowledgement.
pub type DeleteMeetingResult = Result<(), crate::OpError>;

/// FreeBusyRequest is what the host passes to
/// `calendar_sync_free_busy`. `exclude_external_event_id` (empty when
/// there's nothing to exclude) is the remote event id of the meeting
/// currently being edited — it is mirrored into this very calendar and
/// would otherwise always read as a conflict with itself.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct FreeBusyRequest {
    pub connection_user_id: String,
    pub start: String,
    pub end: String,
    pub exclude_external_event_id: String,
}

/// FreeBusyResponse is `calendar_sync_free_busy`'s successful
/// answer.
#[derive(Debug, Clone, Default, Serialize)]
pub struct FreeBusyResponse {
    pub busy: bool,
}

/// FreeBusyResult is the exact return type
/// `calendar_sync_free_busy` must have.
pub type FreeBusyResult = Result<FreeBusyResponse, crate::OpError>;

/// EnsureWatchRequest is what the host passes to
/// `calendar_sync_ensure_watch` — its own op rather than folded into
/// `calendar_sync_meeting`, since a watch is renewed on its own schedule
/// (typically from `scheduled_run`), independent of any particular
/// meeting being saved.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct EnsureWatchRequest {
    pub connection_user_id: String,
}

/// EnsureWatchResult is the exact return type
/// `calendar_sync_ensure_watch` must have — a bare acknowledgement.
pub type EnsureWatchResult = Result<(), crate::OpError>;

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

    #[test]
    fn meeting_response_serializes_to_the_go_wire_shape() {
        let got = serde_json::to_value(MeetingResponse {
            external_event_id: "evt_123".into(),
        })
        .expect("serialize");
        assert_eq!(got, serde_json::json!({"external_event_id": "evt_123"}));
    }

    #[test]
    fn meeting_request_decodes_the_host_input() {
        let req: MeetingRequest = serde_json::from_str(
            r#"{"connection_user_id":"u1","existing_external_event_id":null,"title":"Renewal call","description":"","location_url":"","recurrence_rule":"","start":"2026-08-12T10:00:00Z","end":"2026-08-12T10:30:00Z"}"#,
        )
        .expect("decode");
        assert_eq!(req.connection_user_id, "u1");
        assert_eq!(req.existing_external_event_id, None);
        assert_eq!(req.title, "Renewal call");
    }

    #[test]
    fn free_busy_response_serializes_to_the_go_wire_shape() {
        let got = serde_json::to_value(FreeBusyResponse { busy: true }).expect("serialize");
        assert_eq!(got, serde_json::json!({"busy": true}));
    }
}