convos-shared

Cross-platform shared artifacts that back the Convos iOS and Android clients.

Layout

• metrics/ — Kotlin Gradle project. Declares metrics descriptors (events, user properties, navigation graph) and runs KSP codegen against them.
• ConvosMetrics/ — generated Swift Package, mirrored out of the KSP build so iOS can consume it as an SPM dependency. Do not hand-edit. Re-run ./gradlew build inside metrics/ to regenerate.
• docs/ — protocol notes.
• .githooks/ — shared git hooks. Install once with ./scripts/install-hooks.sh.

Building

cd metrics
./gradlew build

This runs KSP, regenerates the Swift package into <repo>/ConvosMetrics/, and splices the metrics catalog below into this README.

Pre-commit

A pre-commit hook runs ./gradlew build and aborts the commit if the regenerated Swift package or this README differ from what's staged. Activate it once per clone with:

./scripts/install-hooks.sh

That sets core.hooksPath=.githooks for the local repo.

Metrics catalog

The section between the AUTOGEN markers below is regenerated by the build from the descriptors under metrics/descriptors/src/main/kotlin/org/convos/metrics/descriptors/.

Metrics

Core Actions

Event	Function	Parameters
started_conversation	startedConversation	none
joined_conversation	joinedConversation	verification_duration: Float member_count: Int has_assistant: Boolean source: ConversationSource { URL, Scan, Paste, Message }
invited_to_conversation	invitedToConversation	member_count: Int has_assistant: Boolean
added_assistant	addedAssistant	member_count: Int
sent_message	sentMessage	sending_time: Float member_count: Int attachment_types: List has_text: Boolean has_assistant: Boolean is_success: Boolean
shared_conversation	sharedConversation	member_count: Int has_assistant: Boolean share_target: ShareTarget { MESSAGES, MAIL, COPY, QR_CODE, AIRDROP, OTHER, CANCELLED } has_expiration: Boolean expires_after_use: Boolean is_success: Boolean
built_agent	builtAgent	build_duration: Float instruction_char_count: Int instruction_word_count: Int attachment_types: List has_voice_memo: Boolean voice_memo_duration: Float connection_types: List entry_mode: AgentBuilderEntryMode { COMPOSER, VOICE_MEMO } is_success: Boolean
purchase_initiated	purchaseInitiated	product_id: String tier: SubscriptionTier { BUILDER, PRO } period: SubscriptionPeriod { MONTHLY, ANNUAL } source: PaywallSource { SETTINGS, LOW_BALANCE_BANNER, ONBOARDING, MEMBER_CARD, DEBUG }
purchase_succeeded	purchaseSucceeded	product_id: String tier: SubscriptionTier { BUILDER, PRO } period: SubscriptionPeriod { MONTHLY, ANNUAL } source: PaywallSource { SETTINGS, LOW_BALANCE_BANNER, ONBOARDING, MEMBER_CARD, DEBUG } duration_secs: Float
purchase_cancelled	purchaseCancelled	product_id: String source: PaywallSource { SETTINGS, LOW_BALANCE_BANNER, ONBOARDING, MEMBER_CARD, DEBUG }
purchase_failed	purchaseFailed	product_id: String source: PaywallSource { SETTINGS, LOW_BALANCE_BANNER, ONBOARDING, MEMBER_CARD, DEBUG } reason: PurchaseFailureReason { PRODUCT_NOT_FOUND, PURCHASE_PENDING, PURCHASE_UNVERIFIED, BACKEND_VERIFY_UNAVAILABLE, BILLING_CLIENT_UNAVAILABLE, UNKNOWN }
purchases_restored	purchasesRestored	restored_count: Int

User Properties

Key	Field	Type	Nullable
has_messaged_assistant	hasMessagedAssistant	Boolean	no
last_assistant_message_timestamp	lastAssistantMessageTimestamp	String	yes
contact_count	contactCount	Int	no
conversation_count	conversationCount	Int	no
assistant_conversation_count	assistantConversationCount	Int	no
conversation_count24_hours	conversationCount24Hours	Int	no
conversation_count7_days	conversationCount7Days	Int	no
max_active_convo_age	maxActiveConvoAge	Float	no

Navigators

Graph source: navigators.dot. navigators.png is re-rendered by the build when Graphviz is installed.

Screen	Args	Outgoing
tab_root	none	navigateTo → Conversations navigateTo → StuffOverview navigateTo → Contacts
conversations	none	navigateTo → Conversation present → AppSettings present → NewConversation present → ExplodeConfirmation present → ConnectionGrant present → ExplodeInfo present → PinLimitInfo present → ContactCard present → AgentBuilder
conversation	conversationId: String	present → Paywall present → ConversationInfo present → MyInfo present → MemberProfile present → ShareInvite present → NewConversation present → Reactions present → ExplodeInfo present → LockedConvoInfo present → FullConvoInfo present → ConversationForkedInfo present → RevealMediaInfo present → PhotosInfo present → AssistantConfirmation present → AgentInfo present → AgentPowerInfo present → ExplodedInviteInfo present → SetupProfile present → InviteAccepted present → RequestPushNotifications present → BackwardsSecrecyInfo present → AddMembers present → ContactCard present → AgentTemplateContactCard present → AgentBuilder present → ThinkingDetail present → AttachmentPreview
stuff_overview	none	navigateTo → StuffDetail present → AppSettings present → NewConversation present → AgentBuilder
stuff_detail	itemId: String conversationId: String?	leaf
app_settings	none	navigateTo → MyInfo navigateTo → CustomizeSettings navigateTo → AssistantSettings navigateTo → Connections navigateTo → BackupRestore navigateTo → DeleteAllData navigateTo → Devices present → Paywall
new_conversation	mode: NewConversationMode { CREATE, SCANNER, JOIN_INVITE } inviteCode: String?	navigateTo → Conversation
explode_confirmation	conversationId: String	leaf
conversation_info	conversationId: String	navigateTo → ConversationInfoEdit navigateTo → MembersList navigateTo → AgentFilesLinks navigateTo → AgentTemplateContactCard
conversation_info_edit	conversationId: String	leaf
members_list	conversationId: String	navigateTo → MemberProfile navigateTo → AgentTemplateContactCard
member_profile	conversationId: String memberId: String	leaf
share_invite	conversationId: String	leaf
reactions	conversationId: String messageId: String	leaf
agent_files_links	conversationId: String	present → AttachmentPreview
setup_profile	none	leaf
invite_accepted	none	leaf
request_push_notifications	none	leaf
my_info	none	navigateTo → QuicknameRandomizer
customize_settings	none	leaf
assistant_settings	none	present → InviteCodeEntry
connections	none	present → ConnectionGrant
backup_restore	none	leaf
delete_all_data	none	leaf
quickname_randomizer	none	leaf
invite_code_entry	none	leaf
connection_grant	serviceId: String conversationId: String	leaf
devices	none	present → PairDevice present → RemoveDevice
pair_device	pairingId: String? initiatorName: String? expiresAt: Long?	leaf
remove_device	deviceId: String	leaf
explode_info	none	leaf
pin_limit_info	none	leaf
locked_convo_info	conversationId: String	present → LockConvoConfirmation
full_convo_info	none	leaf
conversation_forked_info	conversationId: String	leaf
reveal_media_info	none	leaf
photos_info	none	leaf
assistant_confirmation	conversationId: String	leaf
agent_info	none	leaf
agent_power_info	none	leaf
exploded_invite_info	none	leaf
backwards_secrecy_info	none	leaf
lock_convo_confirmation	conversationId: String	leaf
contacts	none	navigateTo → ContactCard present → NewConversation present → AppSettings present → AgentBuilder
contact_card	inboxId: String conversationId: String?	navigateTo → Contacts
agent_template_contact_card	templateId: String inboxId: String conversationId: String?	leaf
add_members	conversationId: String conversationTitle: String?	leaf
agent_builder	conversationId: String entryMode: AgentBuilderEntryPoint { INLINE, SHEET }	navigateTo → Conversation
thinking_detail	conversationId: String senderInboxId: String messageId: String	leaf
attachment_preview	conversationId: String? senderInboxId: String?	navigateTo → ContactCard navigateTo → AgentTemplateContactCard
paywall	source: PaywallSource { SETTINGS, LOW_BALANCE_BANNER, ONBOARDING, MEMBER_CARD, DEBUG }	leaf
subscription_settings	none	present → Paywall
billing_debug	none	present → Paywall navigateTo → SubscriptionSettings