Cosmos Pet (cosmospet.redbroomsoftware.com)

Veterinary clinic management platform — patient records, appointment scheduling, POS for clinic services, AI-assisted client context, and a client-facing booking portal.

URL: https://cosmospet.redbroomsoftware.comStatus: LIVE Tier: T2 (vertical SaaS primitive)

T1 apps are indispensable horizontal primitives. T2 apps are vertical SaaS or single-domain primitives — primitive-like in their domain but not universal dependencies.

What you can integrate

• Appointment events — receive appointment.completed when a vet consultation is marked finished; triggers Colectiva billing and Constanza invoicing
• Activity logging — activity.logged provides a granular audit trail of clinic-side actions for Camino CRM enrichment
• Client lookup — look up a client by phone or profile identifier for cross-app consumer linking
• Booking portal — client-facing availability and booking endpoints require no operator credentials
• Subscription gating — clinic features are gated by Camino subscription tier including a suspended state for past-due accounts

Authentication

Authorization: Bearer <api_key>
Content-Type: application/json

Clinic staff use Camino SSO via /auth/rbs. Client portal flows use session tokens scoped to the patient owner. Server-to-server integrations use per-clinic API keys.

Endpoints

Method	Path
GET	/api/clients/:id/context
POST	/api/clients/lookup
GET	/api/clinic
GET, POST	/api/clinic/payment-config
GET	/api/ecosystem/customer-insights
GET	/api/ecosystem/feature-access
POST	/api/ecosystem/register
GET	/api/ecosystem/upsell-recommendations
POST	/api/ecosystem/upsell-track
GET, POST	/api/ecosystem/webhooks

26 total — 2 admin/cron/internal (hidden) — +14 more primary endpoints not shown. Source: src/routes/api/**/+server.{ts,js} in the Cosmos-pet repo.

Events emitted

Event	Receivers	Description
activity.logged	camino	A billable or tracked activity has been logged (time entry from Agora ghost timer, POS customer action in Caracol, vet/hotel log in Cosmos Pet or Madriguera) and sent to Camino for CRM activity tracking
appointment.completed	colectiva, camino	A therapy or veterinary appointment has been completed and paid
sale.completed	colectiva, constanza	A POS sale has been completed

Events consumed

Event	Senders	Description
cfdi.stamped	constanza	A CFDI invoice has been stamped by the SAT via Constanza — receiver apps attach the UUID to their local invoice record and update status.
customer.merged	camino	Two duplicate customer records were merged in Camino — receiver apps update their local foreign keys to the canonical customer ID.
customer.updated	camino, constanza, caracol	A customer/contact record was updated in Camino — receiver apps sync the changed fields to their local customer records for display and invoicing accuracy.
employee.missing_data	constanza	Constanza detected an employee with missing fiscal data (RFC/CURP/etc.) — routed back to the source app that created the employee so the missing fields can be completed.
fiscal.resico_warning	constanza	Constanza detected an organization whose RESICO income utilization crossed the warning threshold (>=90%). Routed to accounting-sensitive apps so they can surface limit warnings in POS/invoice flows.
handoff.completed	baul	Generic physical handoff completed with proof. Covers document delivery, product returns, sample collection, key handoff, equipment transfer. Baul physical layer event.
insights.available	camino	Camino's AI engine generated new business insights for a tenant — receiver apps surface the insights in their dashboards for operator review.
invoice.compliance_issue	constanza	Constanza detected an invoice compliance issue (missing/invalid RFC, duplicate, format error) — routed back to the source app for review.
payment.cancelled	(none declared)	A payment was cancelled before capture (abandoned/voided checkout) — distinct from payment.refunded (post-capture reversal). Receivers release any provisional hold/order tied to the payment. S410 registry-integrity reconciliation: caracol + cosmos-pet declared this receiver in apps.json without a matching events.json entry; no ecosystem sender is wired yet (senders:[] until a payment source emits it).
payment.chargeback_resolved	colectiva	A MercadoPago chargeback reached a terminal state. Colectiva emits this when verdict.terminal && outcome ∈ {lost, won, coverage}. Constanza uses it to post a counter-póliza and (on lost + originalCfdiUuid present) cancel the original CFDI. Canonical contract is whatever colectiva/src/lib/services/ecosystem-webhook.service.js notifyPaymentChargebackResolved emits.
payment.completed	colectiva	A payment transaction was fully completed in Colectiva — source apps confirm the payment for delivery orders, subscriptions, or escrow. Used by baul to confirm delivery payment, mancha for reservation payment, constanza for accounting, and cosmos-pet for vet clinic subscription payments.
payment.expired	colectiva	A pending payment expired without being completed — Colectiva notifies the originating app to cancel the pending reservation or order. cosmos-pet uses it to mark vet-clinic subscription payments as expired.
payment.received	colectiva, constanza	A payment has been processed via Colectiva
payment.reconciled	constanza	Constanza completed bank reconciliation for a payment — receiver apps update their local payment records to mark the payment as reconciled against the bank statement.
payment.refunded	colectiva, comal	A payment was refunded by Colectiva — voluntary refund initiated by a tenant app or by Colectiva ops, OR an involuntary MP-platform-side refund. Receivers branch on paymentReferenceType. For voluntary refunds with proration, isPartial=true and proration block carries period bounds. paymentLayer is the primary routing discriminator; receivers MUST check it before paymentReferenceType.
subscription.activated	camino, colectiva	A subscription plan has been activated for a tenant — all apps that gate features behind the subscription tier update their local tier state.
subscription.cancelled	camino, colectiva	A subscription has been cancelled — all apps that gate features behind the subscription tier update their local tier state to free/cancelled.
subscription.changed	camino	A subscription plan has been upgraded or downgraded — receiver apps update their tier gates and feature access accordingly.
subscription.limit_approaching	camino	A tenant's subscription usage is approaching the plan limit — Camino notifies subscriber apps to surface a plan-upgrade prompt to the tenant operator.
subscription.suspended	camino	A subscription was suspended due to non-payment or compliance issue — Camino disables access until resolution. Receiver apps lock out the tenant and surface a suspension banner.

Webhook signature

Standard ecosystem HMAC-SHA256 over the raw body with a 5-minute timestamp window. See Webhooks.

OpenAPI

Coming in the OpenAPI generator phase — see /reference/openapi.

SDK

See /sdk/ for @r-bsoftware/ecosystem-sdk helpers.

Gotchas

• Cosmos Pet and Madriguera both emit appointment.completed — they share the same event name because Colectiva and Mancha both use the same event for billing and scheduling. Use the source or clinicType field to differentiate vet appointments from dog hotel stays.
• The /api/clients/[id]/context endpoint calls the Colectiva AI enrichment layer and may have higher latency than standard CRUD endpoints. Do not call it inline in a checkout flow.
• subscription.suspended is consumed in addition to the standard pair. Build for three states (active / suspended / cancelled) — suspended clinics retain read access but cannot create new appointments.