SDK Reference
The full client surface, typed event names, and payload structure for the @reclaimsh/sdk package.
Configuration
Initialize the client
Create one client instance per project. All events sent through it are scoped to that project's dashboard and API key.
baseUrlstringrequiredYour API origin. In Next.js this is usually NEXT_PUBLIC_API_URL.
projectIdstringrequiredThe project UUID from your dashboard. Keep it stable across the integration.
apiKeystringrequiredThe project API key from Settings. Sent as x-api-key header on every request.
Initialize
const client = new ReclaimClient({
baseUrl: process.env.NEXT_PUBLIC_API_URL,
projectId: "<project-id>",
apiKey: process.env.RECLAIM_API_KEY,
});client.track(payload)
Send an event
Send one typed event per call with consistent user identity. The SDK validates the payload before sending.
projectIdstringrequiredThe project this event belongs to.
userobjectrequiredIdentity fields so Reclaim can stitch signup, onboarding, and checkout activity to the same person. See User object below.
eventEventNamerequiredOne of the typed event names listed below. Determines which recovery scenario can trigger.
propertiesRecord<string, unknown>optionalLightweight metadata like plan, step, source, or revenue amount. Stored as JSON — no schema enforced.
timestampstringoptionalISO 8601 datetime. Defaults to now if omitted. Use this when ingesting historical events.
User object
emailstringrequiredPrimary identity key. Must be a valid email. This is how Reclaim identifies users across events.
namestringoptionalDisplay name. Used in {{name}} template variable in recovery emails.
externalIdstringoptionalYour system's user ID. Recommended for stable identity stitching if email can change.
idstringoptionalInternal UUID. Usually omitted — Reclaim assigns one automatically.
Track event
client.track({
projectId: "<project-id>",
user: {
externalId: "u_456",
email: "owner@acme.com",
name: "Taylor",
},
event: "onboarding_finished",
properties: {
completedChecklist: ["import-data", "invite-team"],
source: "checklist-finished",
},
}).catch(() => {});Track with revenue
await client.track({
projectId: "<project-id>",
user: {
email: "buyer@acme.com",
name: "Taylor",
},
event: "payment_success",
properties: {
revenue: 49.99,
plan: "pro",
billingInterval: "monthly",
},
});Event names
Typed events Reclaim understands
These names are defined in the shared contract. The SDK validates them at send time. Each event maps to a product moment in the user journey.
user_signed_upMarks the first moment a new account exists.
When: Right after account creation, invite acceptance, or the first completed signup step.
onboarding_startedConfirms the user actually entered the setup flow.
When: When the user opens onboarding, starts guided setup, or begins the first workspace configuration step.
onboarding_finishedMarks the end of onboarding and a strong activation milestone.
When: When the user completes setup, reaches the final onboarding step, or lands on the post-setup success state.
key_actionRepresents the product action that proves real value was reached.
When: When the user completes the core action your product is built around.
visited_pricingSignals explicit commercial or upgrade intent.
When: When pricing, billing, or upgrade screens are viewed.
started_checkoutCaptures the strongest near-term buying signal.
When: When checkout starts, billing begins, or payment details are submitted.
payment_successConfirms the user converted successfully.
When: As soon as a subscription or one-time payment completes.
trial_startedMarks the start of a free trial period.
When: When a user begins a trial, activates a trial plan, or receives trial access.
user_activeShows an existing user came back and did something meaningful.
When: When a returning user uses an important feature or resumes normal product activity.
Minimum viable integration
Start with user_signed_up, started_checkout, and payment_success. These three events cover the checkout drop scenario. Add onboarding and activity events to unlock activation and inactivity recovery.
Revenue tracking
Include { revenue: 49.99 } in payment_success properties to see recovered revenue in your dashboard.
Properties
Recommended properties per event
All properties are optional. They add context for debugging and future scenario tuning.
user_signed_upsignup sourceplan selectedcampaign or referralonboarding_startedworkspace identry stepsignup sourceonboarding_finishedcompleted checklistworkspace idtime to completekey_actionaction nameworkspace or project idfeature contextvisited_pricingpricing page URLplan viewedentry sourcestarted_checkoutplancheckout stepbilling intervalpayment_successplan purchasedamountbilling intervaltrial_startedplantrialDaysentry sourceuser_activepage or screenfeature usedsession sourceRecovery engine
How intents are created
When you send events, Reclaim scores user behavior and detects recovery scenarios automatically. Each detected scenario creates an intent — a pending recovery action that triggers a personalized email.
Scoring model
Every user's event history is scored to measure buying or activation intent. An intent is created when the score reaches the threshold and the scenario timing condition is met.
user_signed_up+2onboarding_started+5onboarding_finished+2visited_pricing (first time)+3visited_pricing (repeat)+2started_checkout+5trial_started+3Returned after 24h+ gap+2Recovery scenarios
Each scenario has its own trigger condition, timing window, and threshold. When all conditions are met and no anti-spam rule blocks it, an intent is created.
checkout_dropTrigger: User started checkout but didn’t complete payment
Timing: 10+ minutes after started_checkout
Threshold: Score ≥ 7
Stops when: payment_success after the checkout event
Key events: started_checkout + payment_success
activation_dropTrigger: User signed up but didn’t activate
Timing: 24+ hours after user_signed_up
Threshold: \u2265 7 or onboarding_started sent
Stops when: key_action or onboarding_finished after signup
Key events: user_signed_up + onboarding_started + onboarding_finished / key_action
inactive_userTrigger: Active user went silent
Timing: 3+ days since last event
Threshold: Score ≥ 7
Stops when: Any new event resets the inactivity clock
Key events: Any events that build score to ≥ 7
trial_expiringTrigger: Trial started but no payment yet
Timing: 70% of trial duration elapsed (reads trialDays from properties, defaults to 7)
Threshold: No minimum (trial_started required)
Stops when: payment_success after trial start
Key events: trial_started with { trialDays: number } + payment_success
pricing_hesitationTrigger: Visited pricing 3+ times without starting checkout
Timing: 48+ hours after first visited_pricing
Threshold: Score ≥ 7
Stops when: started_checkout breaks the pattern
Key events: visited_pricing (3+) + started_checkout
Intent lifecycle
Every intent moves through a state machine. The current state is shown in the dashboard log.
Scenario matched, intent created. In auto mode, proceeds to scheduling immediately.
Manual send mode — waiting for you to approve or dismiss from the dashboard.
Recovery email is queued and about to be sent.
Email delivered. Reclaim watches for conversion events for the next 7 days.
User completed payment_success or key_action within 7 days of the email. Revenue is attributed if provided.
You dismissed this intent manually from the dashboard (no email sent).
Email delivery failed after 3 retries.
Anti-spam safeguards
- 48-hour cooldown — same user + same scenario won't be emailed twice within 48 hours.
- Max 3 retries — if delivery fails 3 times, the message is marked as failed.
- Unsubscribe check — users marked as unsubscribed are never emailed.
- Conversion block — if the user already converted (paid or activated), no intent is created.
- Deduplication — only one open intent per user per scenario at any time.
Types
TypeScript definitions
The SDK validates payloads against these types at runtime using Zod. Your editor will surface type errors before you ship.
Returns
client.track() returns a promise that resolves with the created event, the resolved user, and the number of intents created. Throws on validation or network errors.
TrackPayload
type TrackPayload = {
projectId: string; // required
user: User; // required
event: EventName; // required
properties?: Record<string, unknown>; // optional metadata
timestamp?: string; // optional ISO 8601
};User
type User = {
id?: string; // internal UUID
externalId?: string; // your system's user ID
email: string; // required — primary identity key
name?: string; // used in recovery email templates
};EventName
type EventName =
| "user_active"
| "user_signed_up"
| "onboarding_started"
| "onboarding_finished"
| "visited_pricing"
| "started_checkout"
| "payment_success"
| "key_action"
| "trial_started";