@onemrr/node
v0.2.0
Published
Server-side client for OneMRR: identify accounts and track key events for Churn Signals, and record free trials for trial conversion.
Maintainers
Readme
@onemrr/node
Server-side client for OneMRR:
- Churn Signals: tell OneMRR which of your customer accounts are using your product, so it can spot paying customers whose usage drops before they cancel.
- Trial conversion: record the free trials your app starts, so OneMRR counts every trial, including the ones your billing provider never sees, and how many convert.
No dependencies. Node 20 or later.
npm install @onemrr/nodeUse
import { OneMRR } from "@onemrr/node";
const onemrr = new OneMRR({ apiKey: process.env.ONEMRR_API_KEY! });
// Once per account (and whenever its billing changes): link your account ID to the
// customer in your billing source.
await onemrr.identify({
accountId: "merchant_123",
email: "[email protected]", // optional
source: "shopify",
externalCustomerId: "merchant-123.myshopify.com",
});
// Whenever something meaningful happens. Queued and sent in batches.
onemrr.track({ accountId: "merchant_123", event: "event_published" });
// In serverless functions, before returning:
await onemrr.flush();Trials
If your app starts free trials itself (before anyone picks a plan in Stripe or Shopify), send each one when it starts. It converts when the same customer's first payment arrives in billing.
await onemrr.trial({
externalId: `shop_${shop.id}:${startedAt.toISOString()}`, // a restarted trial gets a new ID
unitKey: String(shop.id), // what you count by in OneMRR, or the billing customer's ID
name: shop.name,
startedAt,
endsAt, // optional: defaults to the trial length in Settings → Trials
links: { shopifyDomain: shop.domain }, // optional: for shops billed through your Shopify app
attributes: { channel: "etsy" }, // optional: to split trials by
});
// Past trials, 500 a request. Sending the same externalId again is safe.
await onemrr.trialMany(pastTrials);Set Settings → Trials in OneMRR to say your trials start In our app. See Trial conversion.
Keys
Create a secret key in OneMRR under Settings → API keys. A key limited to tracking can only identify accounts and track events; recording trials needs a full secret key. Keep it on your server: the SDK refuses to run in a browser, and OneMRR refuses secret keys sent from one.
What is sent
For tracking, only your account ID, the event name and its time. No properties, page URLs, IP addresses or user details. Each event carries a generated ID, so retries are counted once. Trials send only the fields you pass to trial().
API
identify({ accountId, name?, email?, links?, source?, sourceId?, externalCustomerId? }): creates or updates the account and its billing links. Resolves the result, including each link's status (linked,pending_customer,conflict), ornullif it couldn't be sent.identifyMany(inputs): the same for up to 500 accounts per request.track({ accountId, event, timestamp?, id? }): queues an event. Never throws.flush(): sends the queue now.verify(): checks the key and reports the last event OneMRR received.shutdown(): flushes before your process exits.trial({ externalId, unitKey?, name?, startedAt, endsAt?, links?, attributes? }): records a free trial. NeedsunitKeyor one oflinks.shopifyDomain,links.stripeCustomer,links.customerExternalId. Resolves{ external_id, status, matched }, ornullif it couldn't be sent. Never throws.trialMany(inputs): the same for any number of trials, 500 per request. Resolves the counts and each result, by its index ininputs.
Options: baseUrl, flushAt (default 50), flushInterval (default 5000 ms), timeout (default 10000 ms), maxRetries (default 3), onError, disabled.
The REST API is documented at https://app.onemrr.dev/api/v1/openapi.json.
