Add JoinRequest custom content type with optional profile and metadata

[yewreeka]

• New JoinRequestContent model with inviteSlug (required), profile
  (optional), and metadata map (optional) for extensible fields like
  deviceName and confirmationCode
• JoinRequestCodec for encoding/decoding with JSON serialization
• Update InviteCoordinator.sendJoinRequest to send structured content
  type instead of plain text slug
• Update InviteCoordinator.processMessage to handle both new content
  type and legacy plain text for backward compatibility
• Update processDm and lastMessageAsSignedInvite for both formats
• Pass profile and metadata through JoinRequest, JoinResult, and
  JoinRequestResult
• Register JoinRequestCodec in XMTP client codecs
• 17 new tests for codec encode/decode, edge cases, and compatibility

Note

Add JoinRequest custom content type with optional profile and metadata to invite flows

• Adds JoinRequestContent and JoinRequestCodec in JoinRequestCodec.swift as a new XMTP content type carrying an invite slug plus optional joiner profile (name, avatar, member kind) and arbitrary metadata.
• InviteCoordinator.sendJoinRequest now sends a structured JoinRequestContent message first, then a plain text slug as a backward-compatible fallback.
• InviteCoordinator.processMessage and processDm accept both the new content type and legacy plain text, propagating profile and metadata through JoinRequest and JoinResult.
• InviteJoinRequestsManager persists the joiner's profile to the local database (DBMember/DBMemberProfile) when present; all call sites now pass a DatabaseWriter to the manager.
• JoinRequestCodec is registered on XMTP clients created by InboxStateMachine, StreamProcessor, and SyncingManager.

^{Macroscope summarized 5227da4.}

[yewreeka]

• Add Convos Vault technical implementation plan #558
• Add JoinRequest custom content type with optional profile and metadata #556 👈 (View in Graphite)
• dev

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Claude finished @yewreeka's task —— View job

---

PR Review Complete

I've thoroughly reviewed this PR. Here's my detailed feedback:

---

Overview

This PR successfully adds a custom XMTP content type (convos.org/join_request v1.0) that extends join requests with optional profile data and metadata. The implementation is well-structured with good backward compatibility, but there are several issues to address.

---

Critical Issues

1. Partial Send Failure Creates False Error State ⚠️ InviteCoordinator.swift:123-127

Macroscope correctly identified a critical issue. The sendJoinRequest method sends two messages sequentially:

// Line 123: Send structured content
_ = try await dm.send(content: joinRequest, options: .init(contentType: codec.contentType))
// Line 127: Send plain text fallback
_ = try await dm.send(content: slug)

Problem: If the second send throws after the first succeeds, the caller receives an exception even though the structured message was already delivered and the receiver can process it independently. This leads to:

• False failure UI for the user
• Potential duplicate retry attempts
• Inconsistent state between sender and receiver

Recommendation:

• Wrap both sends in a single transaction-like operation with error recovery
• OR catch and log the second send failure without propagating it (since the first message is sufficient)
• OR send only the structured content type (legacy clients are already unsupported by other recent changes)

---

Code Quality Issues

2. Missing Input Validation JoinRequestCodec.swift:60-65

The codec doesn't validate the inviteSlug field:

public func encode(content: JoinRequestContent) throws -> EncodedContent {
    var encodedContent = EncodedContent()
    encodedContent.type = ContentTypeJoinRequest
    encodedContent.content = try JSONEncoder().encode(content)
    return encodedContent
}

Issues:

• Empty inviteSlug is accepted (would fail later during decryption)
• No length limits on metadata keys/values (could cause issues with very large payloads)
• imageURL in JoinRequestProfile isn't validated as a valid URL

Recommendation:

guard !content.inviteSlug.isEmpty else { 
    throw JoinRequestCodecError.emptySlug 
}
// Consider max length for metadata values

3. Inconsistent Error Handling InviteCoordinator.swift:354-368

The processDm method silently ignores malformed messages:

let candidates = messages.filter { message in
    guard let contentType = try? message.encodedContent.type,
          contentType == ContentTypeText || contentType == ContentTypeJoinRequest,
          message.senderInboxId != client.inviteInboxId else {
        return false
    }
    return true
}

Issue: Using try? swallows decoding errors without logging. This makes debugging difficult when messages fail to process.

Recommendation: Log decode failures at debug level for troubleshooting.

4. Potential Race Condition InviteJoinRequestsManager.swift:93-117

The persistJoinerProfile method is called asynchronously but isn't awaited in the caller:

// Line 56: Fire and forget
await persistJoinerProfile(result)

Issue: If profile persistence fails, there's no error propagation or retry mechanism. The member is added to the group but their profile might not be saved.

Recommendation: Either:

• Make profile persistence synchronous (await + handle errors)
• OR add logging/metrics for persistence failures
• OR implement a retry mechanism

---

Architecture & Design

5. Good: Protocol-Based Abstraction ✅

The PR correctly uses InviteClientProvider protocol wrappers instead of direct XMTP SDK types, following the project's testability patterns.

6. Good: Backward Compatibility ✅

The dual-message approach (structured + plain text) ensures compatibility with legacy clients, though this creates the issue noted in #1.

7. Good: Profile Persistence Integration ✅ InviteJoinRequestsManager.swift:93-117

The profile data is automatically persisted to DBMemberProfile with support for the memberKind field (agent detection). This is well-integrated with the existing profile system.

---

Test Coverage

8. Excellent Unit Test Coverage ✅ JoinRequestCodecTests.swift

17 tests covering:

• Encode/decode with all field combinations
• Edge cases (empty metadata, special characters, long slugs)
• Error cases (empty content, malformed JSON, missing slug)
• Forward compatibility (unknown fields ignored)

9. Good Integration Tests ✅ InviteJoinRequestIntegrationTests.swift

Tests cover:

• End-to-end join flow with new content type
• Backward compatibility with plain text
• Tag revocation
• Profile and metadata propagation

Missing test coverage:

• The partial send failure scenario (issue [Screen] Onboarding #1)
• Metadata validation limits
• Invalid URL in profile imageURL

---

Performance Considerations

10. Minor: Redundant Message Processing InviteCoordinator.swift:123-127

Sending both structured and plain text messages doubles network traffic. Consider:

• Sending only structured content (with fallback in same message via XMTP's fallback mechanism)
• OR deprecating plain text support entirely if all clients are now on newer versions

---

Security Review

11. No Security Issues Identified ✅

• SignedInvite cryptographic verification is preserved
• No new credential exposure
• Metadata is arbitrary but scoped per-request (no injection risks)
• Profile data is validated before persistence

---

SwiftLint Compliance

12. Follows Project Conventions ✅

Code adheres to CLAUDE.md guidelines:

• No force unwrapping (!)
• No implicitly unwrapped optionals
• Proper use of guard for early returns
• Appropriate use of @preconcurrency for XMTP types
• No trailing whitespace or formatting issues
• Proper modifier order

13. Codec Registration ✅ InboxStateMachine.swift:1077

The JoinRequestCodec is properly registered in the client options alongside other custom codecs.

---

Summary

Recommendation: Request Changes

This is a well-implemented feature with good test coverage and proper architectural patterns. However, the partial send failure issue (#1) is a critical bug that must be fixed before merging. The other issues are lower priority but should be addressed for production readiness.

Priority fixes:

1. ⚠️ Critical: Fix partial send failure handling in sendJoinRequest (issue [Screen] Onboarding #1)
2. Add input validation for inviteSlug and metadata (issue Contact Card Creation UI #2)
3. Improve error logging for decode failures (issue Privy Integration #3)
4. Handle profile persistence failures (issue Add PostHog for Analytics #4)

Nice to have:

• Add test coverage for partial send failure scenario
• Consider deprecating dual-message approach for simplicity

---

Files Changed: 12 files (+668/-479)
Test Coverage: 17 new unit tests + 5 integration tests
| Branch

[macroscopeapp]

Approvability

Verdict: Needs human review

This adds a new custom content type and database persistence for join request profiles, introducing user‑facing behavior and writes. I’d recommend a human verify the new functionality and data changes.

^{You can customize Macroscope's approvability policy. Learn more.}