Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

3.4 KB
Raw Blame

Bots crate

This crate owns bot models, persistence ports, service policy, and HTTP adapters. The bot service also produces sanitized lifecycle events for successful bot mutations.

Lifecycle event producer

Successful create, patch, and soft-delete mutations publish schema-version-1 events to the macro.bots Kafka topic. Every record uses the subject bot's bare UUID string as its Kafka key (for example, 0197f776-6e7b-7c69-a251-780ae754d3e4, without a bot| prefix). Events for one bot therefore use the same Kafka partition key. The Kafka key is not part of the JSON envelope.

Event name Emitted after Metadata
bot.created Regular or channel-scoped bot creation bot_id, kind, owner, name, handle, description, avatar_url, created_by_user_id, channel_id, created_at
bot.updated Bot PATCH bot_id, owner, actor_user_id, requested name, handle, description, and avatar_url fields, plus updated_at
bot.deleted Bot soft deletion bot_id, owner, actor_user_id

owner is a tagged union. A user owner is encoded as {"type":"user","user_id":"..."}, while a team owner is encoded as {"type":"team","team_id":"..."}. On bot.created, channel_id is the channel UUID for channel-scoped creation and null for regular creation. On bot.updated, the mutable fields describe the requested PATCH rather than a full bot snapshot; an omitted field is serialized as null.

A created event has this wire-envelope shape:

{
  "event_id": "01998a30-1a2b-7c3d-9e4f-5a6b7c8d9e0f",
  "schema_version": 1,
  "event_type": "bot.created",
  "metadata": {
    "bot_id": "0197f776-6e7b-7c69-a251-780ae754d3e4",
    "kind": "owned",
    "owner": {
      "type": "team",
      "team_id": "3f6f8b0a-6f9f-4a3f-9c3a-2b1e5d4c7a90"
    },
    "name": "Deploy Bot",
    "handle": "deploy-bot",
    "description": null,
    "avatar_url": null,
    "created_by_user_id": "macro|[email protected]",
    "channel_id": null,
    "created_at": "2026-07-20T17:01:02Z"
  }
}

Sanitization and excluded flows

Lifecycle payloads never expose bot token values, hashes, IDs, prefixes, labels, or expiration metadata. This applies to channel-scoped creation even though its HTTP response contains newly generated token material.

Only successful bot creation, PATCH, and soft deletion produce lifecycle events. Read and list operations, token creation, use, rotation, revocation, and other token lifecycle operations do not publish them. Channel-membership flows also do not publish bot lifecycle events.

Webhook consumption of macro.bots is not included in this change. The webhook Kafka consumer and webhook delivery pipeline do not consume or deliver these bot events.

Delivery semantics and rollout

Publication occurs after the repository mutation and is fire-and-forget. The API does not wait for Kafka delivery, and a scheduling or publication failure is logged without rolling back or failing an otherwise successful mutation. There is no transaction, outbox, or retry coupling database persistence to event publication. A persisted mutation can therefore have no corresponding event; production is at-most-once relative to bot lifecycle mutations.

Provision macro.bots before deploying the Document Storage Service (DSS) producer. If DSS is deployed first, mutations still succeed, but events emitted before the topic is available can be benignly lost under the at-most-once contract.