Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
use async_graphql::{Enum, ID};
use graphql_common::{GraphqlPropertyEntityType, parse_id};
use graphql_soup_filter_input::GraphqlEntityFilterAst;
use item_filters::ast::{EntityFilterAst, properties::PropertyEntityType};
use macro_user_id::user_id::MacroUserIdStr;
use models_grouping::{GroupByField, GroupingConfig};
/// Caller-defined property date-range inputs.
mod date_ranges;
use date_ranges::GraphqlPropertyBucketing;
use models_pagination::{Base64Str, CursorWithValAndFilter, NotifiedAt, SimpleSortMethod};
use soup::domain::models::{
DynamicSort, GroupedSortRequest, SoupQuery, SoupRequest, SoupSortDirection, SoupType,
};
use uuid::Uuid;
/// Input for `Query.soup`.
#[derive(async_graphql::OneofObject)]
pub enum SoupInput {
/// Start a new Soup query.
Initial(Box<SoupInitialInput>),
/// Continue a Soup query from an opaque cursor.
Continuation(SoupContinuationInput),
}
/// Input for starting a Soup query.
#[derive(async_graphql::InputObject)]
pub struct SoupInitialInput {
/// Maximum number of items to return. Defaults to 20, max 500.
limit: Option<u16>,
/// Whether to return expanded Soup items. Defaults to true.
expand: Option<bool>,
/// Timestamp or selected numeric property sort. Defaults to VIEWED_AT.
/// Frecency is not supported by this GraphQL adapter.
/// Flat PROPERTY reads omit calendar events, email, channels, calls, companies, and agent sessions.
sort_method: Option<GraphqlSimpleSortMethod>,
/// Property definition selected for numeric property sorting.
sort_property_definition_id: Option<ID>,
/// Email preview view used when hydrating email Soup items.
email_view: Option<GraphqlEmailView>,
/// AST-shaped filters applied to each Soup entity type.
filters: Option<GraphqlEntityFilterAst>,
/// Direction to order the page in. Defaults to DESC.
sort_direction: Option<GraphqlSortDirection>,
}
/// Input for continuing a Soup query.
#[derive(async_graphql::InputObject)]
pub struct SoupContinuationInput {
/// Opaque cursor returned by a previous GraphQL Soup response.
cursor: String,
/// Whether to return expanded Soup items. Defaults to true.
expand: Option<bool>,
/// Email preview view used when hydrating email Soup items.
email_view: Option<GraphqlEmailView>,
/// Direction to order the page in. Defaults to DESC.
///
/// The cursor does not carry it, so re-send whatever the initial query
/// used or the continuation flips order mid-list.
sort_direction: Option<GraphqlSortDirection>,
}
/// Direction a Soup page is ordered in.
#[derive(async_graphql::Enum, Copy, Clone, Eq, PartialEq)]
pub enum GraphqlSortDirection {
/// Oldest, or soonest-firing, first.
Asc,
/// Newest first.
Desc,
}
impl GraphqlSortDirection {
/// Convert this value into the domain representation.
fn into_model(self) -> SoupSortDirection {
match self {
GraphqlSortDirection::Asc => SoupSortDirection::Asc,
GraphqlSortDirection::Desc => SoupSortDirection::Desc,
}
}
}
/// Input for `Query.groupSoup`.
#[derive(async_graphql::OneofObject)]
pub enum GroupedSoupInput {
/// Start a new grouped Soup query.
Initial(Box<GroupedSoupInitialInput>),
/// Continue one bin from a cursor returned by a previous grouped query.
Continuation(GroupedSoupContinuationInput),
}
/// Input for starting a grouped Soup query.
#[derive(async_graphql::InputObject)]
pub struct GroupedSoupInitialInput {
/// The field used to divide Soup items into bins.
group_by: GraphqlGroupByInput,
/// Maximum number of items to return per bin. Defaults to 20, max 500.
limit: Option<u16>,
/// Sort order within each bin. Defaults to `VIEWED_UPDATED`.
/// Grouped PROPERTY reads retain calendar events; flat PROPERTY reads do not.
sort_method: Option<GraphqlSimpleSortMethod>,
/// Property definition selected for numeric property sorting.
sort_property_definition_id: Option<ID>,
/// Direction of property values. Defaults to DESC.
sort_direction: Option<GraphqlSortDirection>,
/// AST-shaped filters applied to each Soup entity type.
filters: Option<GraphqlEntityFilterAst>,
}
/// Input for continuing a single grouped Soup bin.
#[derive(async_graphql::InputObject)]
pub struct GroupedSoupContinuationInput {
/// The field used to divide Soup items into bins.
group_by: GraphqlGroupByInput,
/// The grouping key of the bin to continue.
group_key: String,
/// Opaque cursor returned for the bin by a previous grouped query.
cursor: String,
}
impl GroupedSoupInput {
/// Convert this value into the grouped Soup domain request.
pub(crate) fn into_request(
self,
macro_user_id: MacroUserIdStr<'static>,
) -> async_graphql::Result<GroupedSortRequest<'static>> {
match self {
Self::Initial(input) => input.into_request(macro_user_id),
Self::Continuation(input) => input.into_request(macro_user_id),
}
}
}
impl GroupedSoupInitialInput {
/// Convert an initial input into the grouped Soup domain request.
fn into_request(
self,
macro_user_id: MacroUserIdStr<'static>,
) -> async_graphql::Result<GroupedSortRequest<'static>> {
let filters = self
.filters
.map(GraphqlEntityFilterAst::into_ast)
.transpose()?
.unwrap_or_default();
let sort_method = selected_sort(
self.sort_method
.unwrap_or(GraphqlSimpleSortMethod::ViewedUpdated),
self.sort_property_definition_id,
self.sort_direction,
)?;
let limit = self.limit.unwrap_or(20).clamp(1, 500);
Ok(GroupedSortRequest::initial(
macro_user_id,
limit,
sort_method,
filters,
GroupingConfig {
field: self.group_by.into_group_by_field()?,
group_key: None,
per_group_limit: Some(u32::from(limit)),
},
))
}
}
impl GroupedSoupContinuationInput {
/// Decode a bin cursor into the grouped Soup domain request.
fn into_request(
self,
macro_user_id: MacroUserIdStr<'static>,
) -> async_graphql::Result<GroupedSortRequest<'static>> {
Ok(GroupedSortRequest::continue_from(
macro_user_id,
self.cursor,
GroupingConfig {
field: self.group_by.into_group_by_field()?,
group_key: Some(self.group_key),
per_group_limit: None,
},
None,
)?)
}
}
/// GraphQL representation of a field used to group Soup items.
#[derive(async_graphql::InputObject)]
struct GraphqlGroupByInput {
/// The kind of grouping to perform.
field: GraphqlGroupByField,
/// Property definition to group by when `field` is `PROPERTY`.
property_definition_id: Option<ID>,
/// Optional property entity type restriction.
entity_type: Option<GraphqlPropertyEntityType>,
/// Optional caller-defined date ranges; requires PROPERTY grouping.
bucketing: Option<GraphqlPropertyBucketing>,
}
impl GraphqlGroupByInput {
/// Convert this input into the grouping domain model.
fn into_group_by_field(self) -> async_graphql::Result<GroupByField> {
match self.field {
GraphqlGroupByField::Date => self.without_property_options(GroupByField::Date),
GraphqlGroupByField::EntityType => {
self.without_property_options(GroupByField::EntityType)
}
GraphqlGroupByField::Project => self.without_property_options(GroupByField::Project),
GraphqlGroupByField::Property => {
let property_definition_id = self.property_definition_id.ok_or_else(|| {
async_graphql::Error::new(
"propertyDefinitionId is required when grouping by PROPERTY",
)
})?;
let property_definition_id =
parse_id(property_definition_id, "propertyDefinitionId")?;
let entity_type = self
.entity_type
.map(PropertyEntityType::try_from)
.transpose()
.map_err(|_| {
async_graphql::Error::new(
"CALL_RECORD is not supported for property grouping",
)
})?
.map(|entity_type| entity_type.to_string());
Ok(GroupByField::Property {
property_definition_id,
entity_type,
bucketing: self.bucketing.map(TryInto::try_into).transpose()?,
})
}
}
}
/// Reject property-only options for non-property grouping modes.
fn without_property_options(
self,
group_by: GroupByField,
) -> async_graphql::Result<GroupByField> {
if self.property_definition_id.is_some()
|| self.entity_type.is_some()
|| self.bucketing.is_some()
{
return Err(async_graphql::Error::new(
"propertyDefinitionId, entityType and bucketing require PROPERTY grouping",
));
}
Ok(group_by)
}
}
/// Grouping modes supported by grouped Soup.
#[derive(async_graphql::Enum, Copy, Clone, Eq, PartialEq)]
enum GraphqlGroupByField {
/// Group into date buckets.
Date,
/// Group by Soup entity type.
EntityType,
/// Group by the Project property (initiative membership).
Project,
/// Group by a property value.
Property,
}
impl SoupInput {
/// Convert this value into the request representation.
pub(crate) fn into_request(
self,
macro_user_id: MacroUserIdStr<'static>,
link_ids: Vec<Uuid>,
) -> async_graphql::Result<SoupRequest<EntityFilterAst>> {
match self {
Self::Initial(input) => input.into_request(macro_user_id, link_ids),
Self::Continuation(input) => input.into_request(macro_user_id, link_ids),
}
}
}
impl SoupInitialInput {
/// Convert an initial input into the request representation.
fn into_request(
self,
macro_user_id: MacroUserIdStr<'static>,
link_ids: Vec<Uuid>,
) -> async_graphql::Result<SoupRequest<EntityFilterAst>> {
let filter = self
.filters
.map(GraphqlEntityFilterAst::into_ast)
.transpose()?
.unwrap_or_default();
let method = self
.sort_method
.unwrap_or(GraphqlSimpleSortMethod::ViewedAt);
let cursor = if method == GraphqlSimpleSortMethod::Property {
SoupQuery::Property(models_pagination::Query::Sort(
selected_sort(
method,
self.sort_property_definition_id,
self.sort_direction,
)?,
filter,
))
} else {
if self.sort_property_definition_id.is_some() {
return Err(async_graphql::Error::new(
"sortPropertyDefinitionId requires PROPERTY",
));
}
method.into_query(filter)?
};
Ok(SoupRequest {
soup_type: soup_type(self.expand),
limit: self.limit.unwrap_or(20).min(500),
sort_direction: sort_direction(&cursor, self.sort_direction)?,
cursor,
user: macro_user_id,
email_preview_view: email_preview_view(self.email_view)?,
link_ids,
})
}
}
impl SoupContinuationInput {
/// Decode a cursor continuation into the request representation.
fn into_request(
self,
macro_user_id: MacroUserIdStr<'static>,
link_ids: Vec<Uuid>,
) -> async_graphql::Result<SoupRequest<EntityFilterAst>> {
let cursor = Base64Str::<SoupContinuationCursor>::new_from_string(self.cursor)
.decode_json()
.map_err(|err| async_graphql::Error::new(format!("invalid cursor: {err}")))?;
let (limit, cursor) = match cursor {
SoupContinuationCursor::Property(cursor) => (
cursor.limit,
SoupQuery::Property(models_pagination::Query::Cursor(cursor)),
),
SoupContinuationCursor::Simple(cursor) => {
(cursor.limit, SoupQuery::new_cursor_simple(cursor))
}
SoupContinuationCursor::Notified(cursor) => {
(cursor.limit, SoupQuery::new_cursor_notified(cursor))
}
};
let limit = u16::try_from(limit).unwrap_or(500).min(500);
Ok(SoupRequest {
soup_type: soup_type(self.expand),
limit,
sort_direction: sort_direction(&cursor, self.sort_direction)?,
cursor,
user: macro_user_id,
email_preview_view: email_preview_view(self.email_view)?,
link_ids,
})
}
}
/// Decode ordinary timestamp, notification, and property position cursors.
#[derive(serde::Deserialize)]
#[serde(untagged)]
enum SoupContinuationCursor {
/// An existing timestamp-sorted continuation.
Simple(CursorWithValAndFilter<Uuid, SimpleSortMethod, EntityFilterAst>),
/// A notification continuation, including channel-thread string identifiers.
Notified(CursorWithValAndFilter<String, NotifiedAt, EntityFilterAst>),
/// Selected-property position through the ordinary query.
Property(CursorWithValAndFilter<Uuid, DynamicSort, EntityFilterAst>),
}
/// Convert the optional GraphQL sort direction into the domain representation.
/// Notified pages are keyset-ordered newest first, so ascending is rejected
/// rather than silently ignored.
fn sort_direction(
cursor: &SoupQuery<EntityFilterAst>,
direction: Option<GraphqlSortDirection>,
) -> async_graphql::Result<SoupSortDirection> {
let direction = direction
.map(GraphqlSortDirection::into_model)
.unwrap_or_default();
if direction == SoupSortDirection::Asc && matches!(cursor, SoupQuery::Notified(_)) {
return Err(async_graphql::Error::new(
"sortDirection ASC is not supported with NOTIFIED_AT",
));
}
Ok(direction)
}
/// Convert the optional GraphQL expansion flag into the domain representation.
fn soup_type(expand: Option<bool>) -> SoupType {
match expand {
Some(false) => SoupType::UnExpanded,
Some(true) | None => SoupType::Expanded,
}
}
/// Convert the optional GraphQL email view into the domain representation.
fn email_preview_view(
email_view: Option<GraphqlEmailView>,
) -> async_graphql::Result<email::domain::models::PreviewView> {
email_view
.map(GraphqlEmailView::as_preview_view_str)
.unwrap_or("inbox")
.parse()
.map_err(async_graphql::Error::new)
}
/// GraphQL input representing the email view.
#[derive(Enum, Copy, Clone, Eq, PartialEq)]
enum GraphqlEmailView {
/// The inbox option.
Inbox,
/// The drafts option.
Drafts,
/// The sent option.
Sent,
/// The all option.
All,
/// The starred option.
Starred,
/// The important option.
Important,
/// The other option.
Other,
}
impl GraphqlEmailView {
/// Return the corresponding email preview view name.
fn as_preview_view_str(self) -> &'static str {
match self {
Self::Inbox => "inbox",
Self::Drafts => "drafts",
Self::Sent => "sent",
Self::All => "all",
Self::Starred => "starred",
Self::Important => "important",
Self::Other => "other",
}
}
}
// Filter input types and their authoritative materialization live in
// `graphql_soup_filter_input`, shared with the browser cache composition root.
/// GraphQL representation of Soup timestamp, notification, and selected-property sorts.
#[derive(Enum, Copy, Clone, Eq, PartialEq)]
pub enum GraphqlSimpleSortMethod {
/// Sort by most recently viewed.
ViewedAt,
/// Sort by creation timestamp.
CreatedAt,
/// Sort by update timestamp.
UpdatedAt,
/// Sort by viewed timestamp, falling back to updated timestamp.
ViewedUpdated,
/// Only entities the caller holds a live notification for, most recently
/// notified first. Descending `soup` only; not supported by `groupSoup`.
NotifiedAt,
/// Sort by the selected property key, missing last, then newest update and ID.
/// Missing definitions and unsupported types use update-time ordering.
/// Email, channels, calls, companies, and agent sessions never appear.
Property,
}
impl GraphqlSimpleSortMethod {
/// Convert into a grouped sort, rejecting the flat-only notification mode.
pub fn into_model(self) -> async_graphql::Result<SimpleSortMethod> {
Ok(match self {
Self::ViewedAt => SimpleSortMethod::ViewedAt,
Self::CreatedAt => SimpleSortMethod::CreatedAt,
Self::UpdatedAt => SimpleSortMethod::UpdatedAt,
Self::ViewedUpdated => SimpleSortMethod::ViewedUpdated,
Self::Property => {
return Err(async_graphql::Error::new(
"property sort requires sortPropertyDefinitionId",
));
}
Self::NotifiedAt => {
return Err(async_graphql::Error::new(
"NOTIFIED_AT is only supported by soup",
));
}
})
}
/// Build an ordinary timestamp or notification query.
fn into_query<T>(self, filters: T) -> async_graphql::Result<SoupQuery<T>> {
if matches!(self, Self::NotifiedAt) {
return Ok(SoupQuery::new_sort_notified(filters));
}
Ok(SoupQuery::new_sort_simple(self.into_model()?, filters))
}
}
#[cfg(test)]
mod tests;
/// Select a numeric property or preserve the ordinary timestamp sort.
fn selected_sort(
method: GraphqlSimpleSortMethod,
property: Option<ID>,
direction: Option<GraphqlSortDirection>,
) -> async_graphql::Result<DynamicSort> {
if method == GraphqlSimpleSortMethod::Property {
return Ok(DynamicSort::Property {
property_definition_id: parse_id(
property.ok_or_else(|| {
async_graphql::Error::new("PROPERTY requires sortPropertyDefinitionId")
})?,
"sortPropertyDefinitionId",
)?,
direction: direction
.map(GraphqlSortDirection::into_model)
.unwrap_or_default(),
});
}
if property.is_some() {
return Err(async_graphql::Error::new(
"sortPropertyDefinitionId requires PROPERTY",
));
}
method.into_model().map(Into::into)
}