ResearchCave.Invitation.Client (1.0.0)
Installation
dotnet nuget add source --name ResearchCave --username your_username --password your_token https://git.researchcave.com/api/packages/ResearchCave/nuget/index.jsondotnet add package --source ResearchCave --version 1.0.0 ResearchCave.Invitation.ClientAbout this package
Fail-soft HTTP client for ResearchCave.Invitation.
ResearchCave.Invitation
Central invitation lifecycle service for ResearchCave. It owns opaque tokens, normalized targets, expiration, acceptance, decline, revoke, and resend state. It does not own registration, external-resource membership, email, SMS, or push delivery.
Calling services integrate through ResearchCave.Invitation.Client and invitation events.
They must treat this as an optional feature: do not add Invitation to core startup/readiness,
and never let an unavailable invitation request break the calling service's primary workflow.
Sensitive configuration belongs in a secret store. In particular, replace
Invitation:TargetFingerprintKey, the SQL credentials, and OIDC client secret.
Integration
- Add
ResearchCave.Invitation.Clientto a calling service and callAddResearchCaveInvitationClient(configuration). Its typed result reportsUnavailablefor outages, timeouts, invalid configuration, 5xx responses, and malformed responses so Invitation never becomes a core-service availability dependency. - Publish purposes as extensible lowercase strings such as
messaging.contactororganization.member; do not add a purpose enum or foreign key. - Consume
InvitationAcceptedfromResearchCave.Contractsidempotently using the stableInvitationId. Notifications consumes creation and delivery-request events. - Set a unique, random
Invitation:TargetFingerprintKeyof at least 32 characters. Rotating it affects duplicate/rate-limit fingerprints but does not invalidate issued token links.
Apply the SQL Server migration in ResearchCave.Invitation.Data/Migrations through the normal
deployment pipeline. The web host also follows the existing ResearchCave convention of applying
pending migrations during startup.
Invitation form and delivery
The home-page form accepts interactive human users. It uses the shared Cloudflare middleware
for the client IP, the invitation-create rate limits (5/minute, 25/hour, 50/day), and the
adaptive ResearchCave CAPTCHA widget for invitation:send. CAPTCHA verification fails closed;
low-risk traffic can pass invisibly, while repeated attempts can require an interactive challenge.
Link the researchcave-invitation AuthServer application in CAPTCHA administration. AuthServer's
seeder grants this existing application captcha.verify for urn:rc:api:captcha; deployments
using an older AuthServer must apply that grant through application management.
No separate CAPTCHA secret is used.
An accepted submission queues delivery; it does not confirm SMTP or inbox delivery. Creation and
redelivery events use the durable SQL outbox and acknowledged NATS JetStream publishing.
Nats:Enabled must be true, and Invitation and Notifications must use the same broker and stream.
Set Invitation:PublicBaseUrl to https://invite.researchcave.com so emailed tokens open this service.
Repeat submissions within Invitation:DuplicateInvitationCooldownSeconds (24 hours by default)
do not request another delivery. Responses and the home-page confirmation use the full contact.
For a missing email, check Notifications' effective Notifications:Email:Enabled (the checked-in
default is false), SMTP host/port/authentication, and default sender address in the production
configuration. Then inspect the notifications-invitations-created / -requested and
notifications-email-delivery consumers, Wolverine error queue, and the
EmailNotificationDeliveries rows using the invitation ID as CorrelationId.
The Invitation /health result alone does not verify the downstream SMTP configuration.