MMOLove Developer Docs

Official MMOLove SDKs for the Referral Kit (sign + send events) and reward callbacks (verify heart webhooks) — Node/JS, PHP, Python, and .NET, plus the raw HMAC spec.

Thin, signed-HTTP wrappers around the Referral API and the reward-callback webhook. Each pairs a sender (sign + POST referral events to MMOLove) with a verifier (validate inbound heart callbacks). They're convenience, not magic — the REST contract is always the source of truth.

These packages live in this repo under packages/. The Node and Python packages publish to npm / PyPI as @mmolove/… and mmolove-…; the .NET packages as MMOLove.* on NuGet; PHP is a vendored single-file drop-in (no Composer needed). Until a package is published to its registry, vendor the linked source — the API shown here is what ships.

Referral Kit — send signed events

The outbound side: your backend signs and POSTs registered / qualified events to MMOLove as your referred players progress.

Node / JS — @mmolove/referral

npm i @mmolove/referral · new ReferralClient(...).registered/qualified

PHP — mmolove-referral.php

Single-file drop-in · mmolove_referral_send(...)

Python — mmolove-referral

pip install mmolove-referral · ReferralClient(...).registered/qualified

.NET — MMOLove.Referral

dotnet add package MMOLove.Referral · new ReferralClient(...).RegisteredAsync/QualifiedAsync

Stack	Install	Entry point
Node / JS	`npm i @mmolove/referral`	`new ReferralClient({ serverId, secret })` → `.registered(...)` / `.qualified(...)`
PHP	drop in `mmolove-referral.php`	`mmolove_referral_send($secret, $serverId, $event, $token, $opts)`
Python	`pip install mmolove-referral`	`ReferralClient(server_id=…, secret=…)` → `.registered(...)` / `.qualified(...)`
.NET	`dotnet add package MMOLove.Referral`	`new ReferralClient(serverId, secret)` → `.RegisteredAsync(...)` / `.QualifiedAsync(...)`

Reward callbacks — verify heart webhooks

The inbound side: verify the signed heart.counted callback MMOLove POSTs when a player votes for you, then reward them.

Node / JS — @mmolove/callback

npm i @mmolove/callback · verifyHeartCallback({ rawBody, signatureHeader, secret })

PHP — mmolove-callback.php

Single-file drop-in · mmolove_verify($secret)

Python — mmolove-callback

pip install mmolove-callback · verify_heart_callback(raw_body, header, secret)

.NET — MMOLove.Callback

dotnet add package MMOLove.Callback · MmoLoveCallback.VerifyHeartCallback(...)

Stack	Install	Entry point
Node / JS	`npm i @mmolove/callback`	`verifyHeartCallback({ rawBody, signatureHeader, secret })` → `{ valid, event }`
PHP	drop in `mmolove-callback.php`	`mmolove_verify($secret)` (+ `mmolove_verify_legacy_get($secret)`)
Python	`pip install mmolove-callback`	`verify_heart_callback(raw_body, signature_header, secret)` → event `dict` \| `None`
.NET	`dotnet add package MMOLove.Callback`	`MmoLoveCallback.VerifyHeartCallback(rawBody, header, secret)` → `VerifyResult`

A different shape of SDK: no signing, no webhook. These wrap the hosted vote widget so players can vote for your server from your own site. The @mmolove/vote npm package opens the widget (popup or modal) from your browser JS and hands you the result; the MMOLove.Vote ASP.NET helper emits the embed snippet server-side. A one-line <script src=".../embed.js"> tag needs no package at all.

Node / JS — @mmolove/vote

npm i @mmolove/vote · openVote(...) / mountVoteButton(...) / <VoteButton> (React)

.NET — MMOLove.Vote

dotnet add package MMOLove.Vote · VoteEmbed.Script(...) + <mmolove-vote> TagHelper

Stack	Install	Entry point
Node / JS	`npm i @mmolove/vote`	`openVote({ serverId, mode, theme, onVote })` · `<VoteButton>` from `@mmolove/vote/react`
.NET	`dotnet add package MMOLove.Vote`	`VoteEmbed.Script(serverId, mode, theme)` · `<mmolove-vote server-id="…" />`
Any	`<script src="https://mmolove.gg/embed.js" data-mmolove-vote="…">`	the hosted loader — no package

See the Vote button guide for all three paths + the result payload.

One signing core, two header forms

Every SDK implements the same HMAC core — HMAC_SHA256(secret, "<t>.<rawBody>"), lower-case hex, signed over the raw body, with t in the X-MMOLove-Signature header. The only difference between the two integrations is the v1 encoding:

	Referral Kit (send)	Reward callback (verify)
Header	`t=<unix>,v1=sha256=<hex>[,kid=…]`	`t=<unix>,v1=<hex>`
`v1`	`sha256=` + hex	bare hex
Direction	you → MMOLove (we verify)	MMOLove → you (you verify)

Every SDK is cross-checked against the shared packages/signing-vectors.json fixtures, and the JS suite cross-checks those vectors against the real server verifier — so a signature any SDK produces is one MMOLove will accept.

No SDK? No problem

Any language that can compute an HMAC-SHA256 and speak HTTPS can integrate directly. The per-language Referral Kit guides and reward-callback handlers show the full copy-paste path, and the OpenAPI 3.1 spec drives client generators.

SDKs