Node SDK

Server-side companion for web backends: record the signup → attribution binding on your server, instead of (or in addition to) the browser. Pairs with any billing provider — see the Web SaaS guide for the full flow.

Integrate MyAppAffiliate into my project.

Documentation (read these first, they are the source of truth):
- Page: https://docs.myappaffiliate.com/sdk-node.md
- Full docs index: https://docs.myappaffiliate.com/llms.txt

Task: Add the MyAppAffiliate Node SDK to my backend: install it, set MAA_SDK_KEY in the environment, and call trackSignup from my signup handler passing the request URL.

Rules:
- Follow the documented API exactly — no invented method names, endpoints, parameters or field names.
- Match the conventions already used in my codebase.
- Ask me for my SDK key instead of guessing, and never hard-code it — read it from config/environment.
- Do NOT set an API base URL anywhere. Every SDK compiles the production host in; a staging or self-hosted host belongs in a build setting, not in code.
- Tell me afterwards which steps I still have to do by hand (dashboard settings, capabilities, webhook configuration).

Install

npm i @myappaffiliate/sdk-node

Node 18+ (global fetch), zero dependencies.

1. Set the key in the environment

MAA_SDK_KEY=pk_live_…

Server env only — never ship this key to the browser; that's what the Web SDK is for. There is no host to configure: the production API is compiled in, and MAA_API_BASE_URL overrides it for staging or self-hosted.

2. Track the signup

One call from your signup handler. Pass the request URL you already have and the SDK pulls the referral out of it — ?via=, ?ref=, ?code=, ?claim_token=, ?ct=:

import { myAppAffiliate } from "@myappaffiliate/sdk-node";
 
const result = await myAppAffiliate.trackSignup({
  userId: user.id,     // the id your billing provider will report back to us
  from: req.url,       // or the referer, or the landing URL you stashed at signup
});
// → { affiliateId } when attributed, null otherwise

null means "organic signup" — it is not an error. Under the hood this is POST /sdk/install + POST /sdk/identify in one call, keyed by a deterministic device id (srv_<userId>), so retrying it is safe.

Already parsed the referral yourself? Pass it directly instead of from:

await myAppAffiliate.trackSignup({ userId: user.id, code: form.referralCode });
await myAppAffiliate.trackSignup({ userId: user.id, claimToken: req.cookies.maa_ct });

3. Make sure the billing provider sends that same id back

Attribution joins on the user id. Whatever bills your customers, the id in the revenue event has to be the string you passed to trackSignup. The field per provider is in Billing & Webhooks — for Stripe it's metadata.customer_user_id, for Paddle it's custom data.

Optional

Your own client — two keys in one process, or a key from a secret manager rather than the environment:

import { createClient } from "@myappaffiliate/sdk-node";
 
const maa = createClient({
  apiKey: await secrets.get("maa"),
  apiBaseUrl: "https://staging.example.com",  // optional
  debug: true,                                // optional
});
if (!maa.configured) logger.warn("MyAppAffiliate is inactive — no key");

Stash the referral before signup — useful when the landing page and the signup request are different sessions:

import { referralFrom } from "@myappaffiliate/sdk-node";
 
const referral = referralFrom(req.url);  // { code } | { claimToken } | {}
session.referral = referral;

Raw endpoints, when you manage device identity yourself:

await maa.install({ deviceId, claimToken });
await maa.identify({ deviceId, customerUserId });

API

Network failures resolve to null — a flaky attribution call must never fail your signup path.