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
//! Typed mirrors of internal/extwasm/core.go's `Core*` wire shapes, field
//! for field. Changing one side without the other is what these exist to
//! make obvious; core.go's DTO block is the authority.
//!
//! Two representation choices worth knowing:
//!
//!   - **Ids and timestamps are `String`.** A UUID crosses the wire as
//!     its canonical text and a timestamp as RFC 3339, and a plugin
//!     overwhelmingly passes them straight back to the host or into its
//!     own vendor's API. Parsing them here would mean two more
//!     dependencies in every plugin binary to buy nothing.
//!   - **`custom_fields`/`options` are `serde_json::Value`.** They are
//!     tenant-defined jsonb — there is no static shape to give them, and
//!     the host passes the column through verbatim.

use serde::Deserialize;
use serde_json::Value;

/// Page is what every list action answers with — see core.go's
/// `coreRows`. `has_more` is "the page came back full", not a count.
#[derive(Debug, Deserialize)]
pub struct Page<T> {
    #[serde(default = "Vec::new")]
    pub items: Vec<T>,
    #[serde(default)]
    pub has_more: bool,
}

// Hand-written rather than derived: `#[derive(Default)]` on a generic
// struct adds a `T: Default` bound, which none of these row types have
// and none of them should — an empty page of a type that has no zero
// value is perfectly ordinary.
impl<T> Default for Page<T> {
    fn default() -> Self {
        Self { items: Vec::new(), has_more: false }
    }
}

impl<T> Page<T> {
    pub fn len(&self) -> usize {
        self.items.len()
    }

    pub fn is_empty(&self) -> bool {
        self.items.is_empty()
    }

    pub fn iter(&self) -> std::slice::Iter<'_, T> {
        self.items.iter()
    }
}

impl<T> IntoIterator for Page<T> {
    type Item = T;
    type IntoIter = std::vec::IntoIter<T>;

    fn into_iter(self) -> Self::IntoIter {
        self.items.into_iter()
    }
}

#[derive(Debug, Clone, Deserialize)]
pub struct TicketType {
    pub id: String,
    pub name: String,
    #[serde(default)]
    pub is_default: bool,
    #[serde(default)]
    pub sort_order: i32,
}

#[derive(Debug, Clone, Deserialize)]
pub struct TicketStatus {
    pub id: String,
    pub name: String,
    #[serde(default)]
    pub is_closed: bool,
    #[serde(default)]
    pub is_default: bool,
    /// pauses_sla is what stops the SLA clock while a ticket sits in this
    /// status — see CLAUDE.md's SLA-pausing note.
    #[serde(default)]
    pub pauses_sla: bool,
    #[serde(default)]
    pub sort_order: i32,
}

#[derive(Debug, Clone, Deserialize)]
pub struct TicketPriority {
    pub id: String,
    pub name: String,
    #[serde(default)]
    pub level: i32,
    #[serde(default)]
    pub is_default: bool,
}

#[derive(Debug, Clone, Deserialize)]
pub struct Tag {
    pub id: String,
    pub name: String,
    #[serde(default)]
    pub color: String,
}

#[derive(Debug, Clone, Deserialize)]
pub struct Team {
    pub id: String,
    pub name: String,
}

/// User is deliberately narrower than the `users` row: no password hash,
/// no calendar feed token, no per-channel ids, no staff-written internal
/// notes — see core.go's DTO block for why each is left out.
#[derive(Debug, Clone, Deserialize)]
pub struct User {
    pub id: String,
    pub email: String,
    #[serde(default)]
    pub alternate_emails: Vec<String>,
    pub name: String,
    /// role is "admin" | "agent" | "customer".
    pub role: String,
    #[serde(default)]
    pub is_active: bool,
    #[serde(default)]
    pub organization_id: Option<String>,
    #[serde(default)]
    pub phone: Option<String>,
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub department: Option<String>,
    #[serde(default)]
    pub country: Option<String>,
    #[serde(default)]
    pub is_vip: bool,
    #[serde(default)]
    pub vip_level: Option<i32>,
    #[serde(default)]
    pub is_org_admin: bool,
    #[serde(default)]
    pub custom_fields: Option<Value>,
    #[serde(default)]
    pub created_at: Option<String>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct Organization {
    pub id: String,
    pub name: String,
    #[serde(default)]
    pub domain: Option<String>,
    #[serde(default)]
    pub website: Option<String>,
    #[serde(default)]
    pub phone: Option<String>,
    #[serde(default)]
    pub address: Option<String>,
    #[serde(default)]
    pub share_tickets_with_org: bool,
    #[serde(default)]
    pub custom_fields: Option<Value>,
}

#[derive(Debug, Clone, Deserialize)]
pub struct SlaPolicy {
    pub id: String,
    pub priority_id: String,
    pub resolve_hours: i32,
}

#[derive(Debug, Clone, Deserialize)]
pub struct CustomField {
    pub id: String,
    /// entity is "ticket" | "customer" | "organization".
    pub entity: String,
    pub key: String,
    pub label: String,
    pub field_type: String,
    #[serde(default)]
    pub options: Option<Value>,
    #[serde(default)]
    pub is_required: bool,
    #[serde(default)]
    pub is_active: bool,
    #[serde(default)]
    pub staff_only: bool,
    #[serde(default)]
    pub ticket_type_id: Option<String>,
    #[serde(default)]
    pub sort_order: i32,
}

/// BusinessHours is the tenant's working calendar. `enabled == false`
/// means the tenant never turned the feature on and every deadline is
/// plain wall-clock — read that flag rather than assuming the windows
/// apply.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct BusinessHours {
    #[serde(default)]
    pub enabled: bool,
    #[serde(default)]
    pub timezone: String,
    #[serde(default)]
    pub windows: Vec<BusinessHoursWindow>,
    #[serde(default)]
    pub holidays: Vec<BusinessHoliday>,
}

/// One working span on one weekday, in minutes from local midnight.
/// Several per weekday is how a lunch break is expressed.
#[derive(Debug, Clone, Deserialize)]
pub struct BusinessHoursWindow {
    /// 0 = Sunday .. 6 = Saturday, matching Go's time.Weekday.
    pub weekday: i16,
    pub start_minute: i32,
    pub end_minute: i32,
}

#[derive(Debug, Clone, Deserialize)]
pub struct BusinessHoliday {
    /// A plain calendar date (YYYY-MM-DD) in the tenant's own timezone.
    pub day: String,
    #[serde(default)]
    pub name: String,
}

#[derive(Debug, Clone, Deserialize)]
pub struct Ticket {
    pub id: String,
    pub ticket_number: i64,
    pub subject: String,
    pub requester_id: String,
    #[serde(default)]
    pub assigned_agent_id: Option<String>,
    #[serde(default)]
    pub team_id: Option<String>,
    pub status_id: String,
    pub priority_id: String,
    #[serde(default)]
    pub type_id: Option<String>,
    #[serde(default)]
    pub channel: String,
    #[serde(default)]
    pub summary: Option<String>,
    #[serde(default)]
    pub external_ref: Option<String>,
    #[serde(default)]
    pub custom_fields: Option<Value>,
    #[serde(default)]
    pub sla_due_at: Option<String>,
    #[serde(default)]
    pub sla_breached_at: Option<String>,
    #[serde(default)]
    pub sla_paused_minutes: i32,
    #[serde(default)]
    pub created_at: Option<String>,
    #[serde(default)]
    pub updated_at: Option<String>,
    #[serde(default)]
    pub closed_at: Option<String>,
    #[serde(default)]
    pub last_activity_at: Option<String>,
}

/// TicketMessage carries `body_text` only, never the rendered HTML — see
/// core.go's note on why.
#[derive(Debug, Clone, Deserialize)]
pub struct TicketMessage {
    pub id: String,
    pub ticket_id: String,
    pub author_id: String,
    #[serde(default)]
    pub author_name: String,
    #[serde(default)]
    pub author_email: String,
    #[serde(default)]
    pub is_private: bool,
    #[serde(default)]
    pub body_text: String,
    #[serde(default)]
    pub channel: String,
    #[serde(default)]
    pub message_type: String,
    #[serde(default)]
    pub created_at: Option<String>,
}