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
//! Domain models for github sync operations (webhooks and sync app).
use std::collections::HashSet;
use std::fmt;
use std::sync::LazyLock;
use models_properties::service::property_change_source::{GithubAccount, PropertyChangeSource};
use regex::Regex;
use serde::Deserialize;
use super::GithubError;
/// Action reported by GitHub after an installation setup flow.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GithubInstallationSetupAction {
/// A new GitHub App installation was created.
Install,
/// An existing installation's repository selection was updated.
Update,
/// Installation was requested from an organization administrator.
Request,
}
impl TryFrom<&str> for GithubInstallationSetupAction {
type Error = GithubError;
fn try_from(value: &str) -> Result<Self, Self::Error> {
match value {
"install" => Ok(Self::Install),
"update" => Ok(Self::Update),
"request" => Ok(Self::Request),
_ => Err(GithubError::InvalidInstallationSetupAction),
}
}
}
/// OAuth access token returned after exchanging a GitHub App setup code.
#[derive(Clone, Deserialize)]
pub struct GithubSetupAccessToken {
access_token: String,
}
impl GithubSetupAccessToken {
/// Creates an access token from GitHub's OAuth response value.
pub fn new(access_token: String) -> Self {
Self { access_token }
}
/// Returns the access token without transferring ownership of the secret.
pub fn as_str(&self) -> &str {
&self.access_token
}
}
/// A GitHub App installation visible to an authenticated GitHub user.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct GithubUserInstallation {
/// GitHub's numeric installation identifier.
pub id: u64,
}
/// The GitHub user behind an OAuth user access token.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct GithubAuthenticatedUser {
/// GitHub's stable numeric user identifier.
pub id: u64,
}
/// One page of installations visible to an authenticated GitHub user.
#[derive(Debug, Clone, Deserialize)]
pub struct GithubUserInstallationsPage {
/// Number of installations visible across every page.
pub total_count: u64,
/// Installations returned on this page.
pub installations: Vec<GithubUserInstallation>,
}
/// GitHub App installation access token response
#[derive(Clone, Deserialize)]
pub struct GithubInstallationAccessToken {
/// The installation access token
pub token: String,
/// When the token expires, as GitHub sent it (RFC 3339).
pub expires_at: String,
}
impl std::fmt::Debug for GithubInstallationAccessToken {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("GithubInstallationAccessToken")
.field("token", &"[REDACTED]")
.field("expires_at", &self.expires_at)
.finish()
}
}
impl GithubInstallationAccessToken {
/// When this token expires.
///
/// Parsed here rather than by callers: the field is a string because that
/// is how GitHub sends it, and a caller that has to know the format in
/// order to cache the token would be the second place that knowledge
/// lives.
pub fn expires_at(&self) -> Result<chrono::DateTime<chrono::Utc>, GithubError> {
chrono::DateTime::parse_from_rfc3339(&self.expires_at)
.map(|expiry| expiry.with_timezone(&chrono::Utc))
.map_err(|error| {
GithubError::Internal(anyhow::anyhow!(
"github sent an unparseable token expiry {:?}: {error}",
self.expires_at
))
})
}
}
/// Source that grants a GitHub App installation access to Macro sync data.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum GithubAppInstallationSource {
/// A Macro team source.
Team(uuid::Uuid),
/// A Macro user source.
User(String),
}
impl GithubAppInstallationSource {
/// Returns the value persisted in `github_app_installation.source_id`.
pub fn source_id(&self) -> String {
match self {
Self::Team(team_id) => team_id.to_string(),
Self::User(user_id) => user_id.clone(),
}
}
/// Returns the value persisted in `github_app_installation.source_type`.
pub fn source_type(&self) -> &'static str {
match self {
Self::Team(_) => "team",
Self::User(_) => "user",
}
}
}
/// A validated github webhook event
#[derive(Debug)]
pub struct ValidatedGithubWebhookEvent {
/// The event type from the `X-GitHub-Event` header
pub event_type: String,
/// The parsed JSON payload
pub payload: serde_json::Value,
/// The `X-GitHub-Delivery` header, when the request carried one.
pub delivery_id: Option<String>,
}
impl ValidatedGithubWebhookEvent {
/// Create a new ValidatedGithubWebhookEvent
pub fn new(event_type: String, payload: serde_json::Value) -> Self {
Self {
event_type,
payload,
delivery_id: None,
}
}
/// Record the delivery id GitHub sent with the event.
pub fn with_delivery_id(mut self, delivery_id: Option<String>) -> Self {
self.delivery_id = delivery_id;
self
}
/// Parse the raw event type string into a [`GithubWebhookEventType`].
pub fn parsed_event_type(&self) -> GithubWebhookEventType {
GithubWebhookEventType::from_event_header(&self.event_type)
}
/// Extract all text fields worth searching for task IDs, based on event type.
///
/// Markdown code (fenced blocks and inline spans) is stripped from prose
/// fields before they are returned: quoted diffs and code snippets are full
/// of `identifier-number` tokens (e.g. the Tailwind class `py-6`) that must
/// never be mistaken for task references. Branch names are kept verbatim —
/// they cannot contain markdown.
pub fn extract_searchable_text(&self) -> Vec<String> {
let mut texts = Vec::new();
match self.parsed_event_type() {
GithubWebhookEventType::PullRequest => {
if let Some(pr) = self.payload.get("pull_request") {
if let Some(s) = pr.get("title").and_then(|v| v.as_str()) {
texts.push(strip_markdown_code(s));
}
if let Some(s) = pr.get("body").and_then(|v| v.as_str()) {
texts.push(strip_markdown_code(s));
}
if let Some(s) = pr
.get("head")
.and_then(|h| h.get("ref"))
.and_then(|v| v.as_str())
{
texts.push(s.to_string());
}
}
}
GithubWebhookEventType::IssueComment
| GithubWebhookEventType::PullRequestReviewComment => {
if let Some(s) = self
.payload
.get("comment")
.and_then(|c| c.get("body"))
.and_then(|v| v.as_str())
{
texts.push(strip_markdown_code(s));
}
}
GithubWebhookEventType::PullRequestReview => {
if let Some(s) = self
.payload
.get("review")
.and_then(|r| r.get("body"))
.and_then(|v| v.as_str())
{
texts.push(strip_markdown_code(s));
}
}
GithubWebhookEventType::CheckRun
| GithubWebhookEventType::Installation
| GithubWebhookEventType::Unknown(_) => {}
}
texts
}
/// Extract the `action` field from the webhook payload (e.g. "opened", "closed", "created").
pub fn action(&self) -> Option<&str> {
self.payload.get("action").and_then(|v| v.as_str())
}
/// Whether the pull request was merged (only meaningful for `closed` actions).
pub fn is_merged(&self) -> bool {
self.payload
.get("pull_request")
.and_then(|pr| pr.get("merged"))
.and_then(|v| v.as_bool())
.unwrap_or(false)
}
/// Derive the task status string based on the event, if applicable.
///
/// For `pull_request` events: `opened`/`reopened` → `"In Review"`,
/// `closed` + merged → `"Completed"`, `closed` without merge →
/// `"Not Started"` (the TODO status).
///
/// For comment/review events that newly associate a task with an open PR,
/// returns `"In Review"`.
///
/// Returns `None` when no status change is warranted.
pub fn task_status_for_event(&self) -> Option<&'static str> {
match self.parsed_event_type() {
GithubWebhookEventType::PullRequest => match self.action() {
Some("opened" | "reopened" | "edited") => Some("In Review"),
Some("closed") if self.is_merged() => Some("Completed"),
Some("closed") => Some("Not Started"),
_ => None,
},
GithubWebhookEventType::IssueComment
| GithubWebhookEventType::PullRequestReview
| GithubWebhookEventType::PullRequestReviewComment => {
// A comment/review that introduces a new task association on an
// open PR should mark the task as "In Review".
let is_open = self
.payload
.get("pull_request")
.or_else(|| self.payload.get("issue"))
.and_then(|pr| pr.get("state"))
.and_then(|v| v.as_str())
== Some("open");
if is_open { Some("In Review") } else { None }
}
GithubWebhookEventType::CheckRun
| GithubWebhookEventType::Installation
| GithubWebhookEventType::Unknown(_) => None,
}
}
/// Extract the pull request / issue number from the webhook payload.
pub fn pull_number(&self) -> Option<u64> {
self.payload
.get("pull_request")
.and_then(|pr| pr.get("number"))
.or_else(|| {
self.payload
.get("issue")
.and_then(|issue| issue.get("number"))
})
.or_else(|| {
self.payload
.get("check_run")
.and_then(|check_run| check_run.get("pull_requests"))
.and_then(|pull_requests| pull_requests.as_array())
.and_then(|pull_requests| pull_requests.first())
.and_then(|pull_request| pull_request.get("number"))
})
.and_then(|v| v.as_u64())
}
/// Returns whether this webhook payload is associated with a pull request.
pub fn is_associated_with_pull_request(&self) -> bool {
match self.parsed_event_type() {
GithubWebhookEventType::PullRequest => self.payload.get("pull_request").is_some(),
GithubWebhookEventType::IssueComment => self
.payload
.get("issue")
.and_then(|issue| issue.get("pull_request"))
.is_some(),
GithubWebhookEventType::PullRequestReview
| GithubWebhookEventType::PullRequestReviewComment => {
self.payload.get("pull_request").is_some()
}
GithubWebhookEventType::CheckRun => self.pull_number().is_some(),
GithubWebhookEventType::Installation | GithubWebhookEventType::Unknown(_) => false,
}
}
/// Extract the repository owner login from the webhook payload.
pub fn repo_owner(&self) -> Option<&str> {
self.payload
.get("repository")
.and_then(|r| r.get("owner"))
.and_then(|o| o.get("login"))
.and_then(|v| v.as_str())
}
/// Extract the repository name from the webhook payload.
pub fn repo_name(&self) -> Option<&str> {
self.payload
.get("repository")
.and_then(|r| r.get("name"))
.and_then(|v| v.as_str())
}
/// Extract the GitHub App installation ID from the webhook payload.
pub fn installation_id(&self) -> Option<u64> {
self.payload
.get("installation")
.and_then(|i| i.get("id"))
.and_then(|v| v.as_u64())
}
/// The pull request and GitHub account behind this event's task status
/// change: whoever merged it on a merge, the webhook sender otherwise. A
/// comment on a plain issue also changes status, but has no pull request.
pub fn task_status_source(&self) -> Option<PropertyChangeSource> {
if !self.is_associated_with_pull_request() {
return None;
}
let pull_request = self
.payload
.get("pull_request")
.or_else(|| self.payload.get("issue"))?;
let merged_by = pull_request
.get("merged_by")
.filter(|merged_by| !merged_by.is_null() && self.action() == Some("closed"));
let account = merged_by.or_else(|| self.payload.get("sender"))?;
Some(PropertyChangeSource::GithubPullRequest {
url: pull_request.get("html_url")?.as_str()?.to_string(),
account: GithubAccount {
id: account.get("id")?.as_u64()?.to_string(),
login: account.get("login")?.as_str()?.to_string(),
},
})
}
/// Extract the sender's GitHub user ID from the webhook payload.
///
/// Uses the numeric `sender.id` rather than `sender.login` because
/// GitHub usernames can change but user IDs are stable.
pub fn sender_github_user_id(&self) -> Option<String> {
self.payload
.get("sender")
.and_then(|s| s.get("id"))
.and_then(|v| v.as_u64())
.map(|id| id.to_string())
}
/// Extract the requester's GitHub user ID from the webhook payload.
///
/// `requester` is only present on `installation` events created by an
/// org admin approving another user's installation request; it identifies
/// the user who originally requested the install (the `sender` is the
/// approving admin). Uses the numeric `requester.id` rather than
/// `requester.login` because GitHub usernames can change but user IDs are
/// stable.
pub fn requester_github_user_id(&self) -> Option<String> {
self.payload
.get("requester")
.and_then(|r| r.get("id"))
.and_then(|v| v.as_u64())
.map(|id| id.to_string())
}
/// Extract text from the PR context (title, body, branch) regardless of
/// event type. For comment/review events this returns the surrounding PR
/// info so callers can determine which task IDs are already associated
/// with the PR itself. Returns empty for `PullRequest` events (since the
/// event *is* the PR context) and unknown events.
pub fn extract_pr_context_text(&self) -> Vec<String> {
let mut texts = Vec::new();
let pr = match self.parsed_event_type() {
// For PR events, the event itself is the context — nothing to compare against.
GithubWebhookEventType::PullRequest
| GithubWebhookEventType::CheckRun
| GithubWebhookEventType::Installation
| GithubWebhookEventType::Unknown(_) => {
return texts;
}
// issue_comment payloads embed the issue (which contains PR title/body).
GithubWebhookEventType::IssueComment => self.payload.get("issue"),
// review / review_comment payloads embed the full pull_request object.
GithubWebhookEventType::PullRequestReview
| GithubWebhookEventType::PullRequestReviewComment => self.payload.get("pull_request"),
};
if let Some(pr) = pr {
if let Some(s) = pr.get("title").and_then(|v| v.as_str()) {
texts.push(strip_markdown_code(s));
}
if let Some(s) = pr.get("body").and_then(|v| v.as_str()) {
texts.push(strip_markdown_code(s));
}
if let Some(s) = pr
.get("head")
.and_then(|h| h.get("ref"))
.and_then(|v| v.as_str())
{
texts.push(s.to_string());
}
}
texts
}
}
/// Remove markdown code from text before task reference extraction: fenced
/// code blocks (``` or ~~~) and inline code spans (`...`).
///
/// Code-formatted text is where `identifier-number` tokens live — quoted
/// diffs, CSS utility classes like `py-6`, config keys — and those must never
/// be mistaken for team task references. Removed spans are replaced with a
/// single space so the surrounding prose keeps its token boundaries.
pub fn strip_markdown_code(text: &str) -> String {
strip_inline_code_spans(&strip_fenced_code_blocks(text))
}
/// Returns the fence marker (character and run length) opening or closing a
/// fenced code block on this line, if any.
fn fence_marker(line: &str) -> Option<(char, usize)> {
let trimmed = line.trim_start();
let first = trimmed.chars().next()?;
if first != '`' && first != '~' {
return None;
}
let run = trimmed.chars().take_while(|c| *c == first).count();
(run >= 3).then_some((first, run))
}
/// Drop every line belonging to a fenced code block, fences included. An
/// unclosed fence swallows the rest of the text, matching how markdown
/// renders it.
fn strip_fenced_code_blocks(text: &str) -> String {
let mut kept = Vec::new();
let mut open_fence: Option<(char, usize)> = None;
for line in text.lines() {
match (open_fence, fence_marker(line)) {
// Closing fence: same character, at least as long, nothing else on
// the line after the marker.
(Some((open_char, open_run)), Some((close_char, close_run)))
if close_char == open_char
&& close_run >= open_run
&& line
.trim_start()
.trim_start_matches(open_char)
.trim()
.is_empty() =>
{
open_fence = None;
}
(Some(_), _) => {}
(None, Some(marker)) => {
open_fence = Some(marker);
}
(None, None) => kept.push(line),
}
}
kept.join("\n")
}
/// Drop inline code spans: a run of N backticks closed by the next run of
/// exactly N backticks (CommonMark semantics). Unmatched backtick runs are
/// kept as literal text.
fn strip_inline_code_spans(text: &str) -> String {
let chars: Vec<char> = text.chars().collect();
let mut out = String::with_capacity(text.len());
let mut i = 0;
while i < chars.len() {
if chars[i] != '`' {
out.push(chars[i]);
i += 1;
continue;
}
let open_run = chars[i..].iter().take_while(|c| **c == '`').count();
let span_start = i + open_run;
// Find the next backtick run of exactly `open_run` length.
let mut j = span_start;
let mut close_at = None;
while j < chars.len() {
if chars[j] == '`' {
let run = chars[j..].iter().take_while(|c| **c == '`').count();
if run == open_run {
close_at = Some(j);
break;
}
j += run;
} else {
j += 1;
}
}
match close_at {
Some(close) => {
out.push(' ');
i = close + open_run;
}
None => {
// No closer: keep the backticks as literal text.
for _ in 0..open_run {
out.push('`');
}
i = span_start;
}
}
}
out
}
/// Known GitHub webhook event types we handle.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum GithubWebhookEventType {
/// `pull_request` events
PullRequest,
/// `issue_comment` events (includes comments on PRs)
IssueComment,
/// `pull_request_review` events
PullRequestReview,
/// `pull_request_review_comment` events
PullRequestReviewComment,
/// `check_run` events
CheckRun,
/// `installation` events (app installed/uninstalled)
Installation,
/// Any event type we don't handle
Unknown(String),
}
impl GithubWebhookEventType {
/// Map the raw `X-GitHub-Event` header value to a variant.
pub fn from_event_header(s: &str) -> Self {
match s {
"pull_request" => Self::PullRequest,
"issue_comment" => Self::IssueComment,
"pull_request_review" => Self::PullRequestReview,
"pull_request_review_comment" => Self::PullRequestReviewComment,
"check_run" => Self::CheckRun,
"installation" => Self::Installation,
other => Self::Unknown(other.to_string()),
}
}
}
/// Regex matching `MACRO-{short_uuid}` (case-insensitive).
/// The capture group contains only the Flickr base58 short UUID portion.
static MACRO_TASK_ID_RE: LazyLock<Regex> = LazyLock::new(|| {
Regex::new(r"(?i)macro-([123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ]+)")
.expect("valid regex")
});
/// Regex matching `{team_slug}-{team_task_id}` references.
///
/// The slug follows the team slug format used in generated branch names
/// (letters/numbers/underscores, matched case-insensitively). The numeric
/// portion is the per-team task number.
static TEAM_TASK_REFERENCE_RE: LazyLock<Regex> = LazyLock::new(|| {
Regex::new(r"(?i)(?:^|[^a-z0-9_])([a-z][a-z0-9_]{0,19})-([1-9][0-9]*)(?:$|[^a-z0-9_])")
.expect("valid regex")
});
/// Regex matching GitHub `@login` mentions in markdown-ish text.
///
/// The leading guard requires the `@` to start the text or follow a
/// non-login character, which also rejects email addresses (`[email protected]`).
/// The login follows GitHub's username grammar: 1-39 alphanumerics or
/// non-leading/non-trailing hyphens. Code spans are not treated specially.
static GITHUB_MENTION_RE: LazyLock<Regex> = LazyLock::new(|| {
Regex::new(r"(?i)(?:^|[^a-z0-9-])@([a-z0-9](?:-?[a-z0-9]){0,38})").expect("valid regex")
});
/// Extract unique GitHub `@login` mentions from text, normalized to lowercase.
///
/// Results are sorted for determinism.
pub fn extract_github_mentions(text: &str) -> Vec<String> {
let logins: std::collections::BTreeSet<String> = GITHUB_MENTION_RE
.captures_iter(text)
.map(|caps| caps[1].to_lowercase())
.collect();
logins.into_iter().collect()
}
/// A team-scoped task reference in the form `{team_slug}-{team_task_id}`.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TeamTaskReference {
/// Team slug as it appears in the reference, normalized to lowercase.
pub team_slug: String,
/// Positive per-team task number.
pub team_task_id: i32,
}
impl TeamTaskReference {
/// Create a normalized team task reference.
pub fn new(team_slug: &str, team_task_id: i32) -> Option<Self> {
let team_slug = team_slug.trim().to_ascii_lowercase();
if team_slug.is_empty() || team_task_id <= 0 {
return None;
}
Some(Self {
team_slug,
team_task_id,
})
}
/// Extract all unique `{team_slug}-{team_task_id}` references from text.
pub fn extract_from_text(text: &str) -> Vec<Self> {
let mut seen = HashSet::new();
let mut results = Vec::new();
for caps in TEAM_TASK_REFERENCE_RE.captures_iter(text) {
let Some(task_num) = caps[2].parse::<i32>().ok() else {
continue;
};
let Some(reference) = Self::new(&caps[1], task_num) else {
continue;
};
if seen.insert((reference.team_slug.clone(), reference.team_task_id)) {
results.push(reference);
}
}
results
}
}
/// The text to put in a pull request so the webhook links it to `task`: the team reference
/// when the webhook's parser reads it back, else `MACRO-{short_uuid}`.
pub fn pull_request_task_reference(task: &MacroTaskId, team: Option<&TeamTaskReference>) -> String {
team.and_then(|team| {
let reference = format!(
"{}-{}",
team.team_slug.to_ascii_uppercase(),
team.team_task_id
);
(TeamTaskReference::extract_from_text(&reference).as_slice() == std::slice::from_ref(team))
.then_some(reference)
})
.unwrap_or_else(|| task.to_task_id_string())
}
/// A [`TeamTaskReference`] resolved against a concrete team.
///
/// Because team slugs are not unique, one reference can resolve in more than
/// one of an installation's teams; callers must treat such references as
/// ambiguous rather than linking every match.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ResolvedTeamTaskReference {
/// The reference that was resolved.
pub reference: TeamTaskReference,
/// The team whose slug and task number matched the reference.
pub team_id: uuid::Uuid,
/// The task document backing the team task.
pub task_id: MacroTaskId,
}
/// A Macro task ID in the form `MACRO-{short_uuid}`.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct MacroTaskId {
/// The Flickr base58 short UUID portion
pub short_uuid: String,
}
impl MacroTaskId {
/// Create from a raw short UUID string, validating that all characters
/// are in the Flickr base58 alphabet.
pub fn from_short_uuid(s: &str) -> Option<Self> {
let converter = macro_uuid::ShortUuidConverter::default();
if converter.is_short_uuid(s) {
Some(Self {
short_uuid: s.to_string(),
})
} else {
None
}
}
/// Create from a full UUID by converting to a short UUID.
pub fn from_uuid(uuid: &uuid::Uuid) -> Self {
let converter = macro_uuid::ShortUuidConverter::default();
Self {
short_uuid: converter.from_uuid(uuid),
}
}
/// Convert back to a full UUID.
pub fn to_uuid(&self) -> anyhow::Result<uuid::Uuid> {
let converter = macro_uuid::ShortUuidConverter::default();
converter.to_uuid(&self.short_uuid)
}
/// Returns the canonical `MACRO-{short_uuid}` string.
pub fn to_task_id_string(&self) -> String {
format!("MACRO-{}", self.short_uuid)
}
/// Extract all unique `MACRO-{short_uuid}` references from text.
/// Matching is case-insensitive on the `MACRO-` prefix; the short UUID
/// portion is preserved as captured.
///
/// Only short UUIDs that decode to an RFC 4122 UUID are kept. Free text is
/// full of `macro-` words that are valid base58 but are not task ids, such
/// as the `macro-inc` org in GitHub URLs or `MACRO-3692` team task numbers.
pub fn extract_from_text(text: &str) -> Vec<MacroTaskId> {
let mut seen = HashSet::new();
let mut results = Vec::new();
for caps in MACRO_TASK_ID_RE.captures_iter(text) {
let short = &caps[1];
if seen.insert(short.to_string())
&& let Some(task_id) = Self::from_short_uuid(short)
&& task_id.to_uuid().is_ok_and(|uuid| is_rfc4122_uuid(&uuid))
{
results.push(task_id);
}
}
results
}
}
fn is_rfc4122_uuid(uuid: &uuid::Uuid) -> bool {
uuid.get_variant() == uuid::Variant::RFC4122 && uuid.get_version().is_some()
}
impl fmt::Display for MacroTaskId {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "MACRO-{}", self.short_uuid)
}
}