npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@blotout/qinto-sdk-browser

v0.1.22

Published

Qinto browser SDK: the cookie-backed WebSocket client for the identity graph, and the source of the /q.js tag. Zero runtime dependencies.

Readme

@blotout/qinto-sdk-browser

The Qinto browser client. It sends events, identity, and consent from your page to your own Qinto host over one WebSocket connection, and gives you a promise per call that settles when the edge accepted it. Zero runtime dependencies.

Why we built it

A page normally carries one script per vendor: one for the ad platform, one for analytics, one for the CRM. Each is a separate connection to a separate company, a separate copy of your tracking code, and a separate thing to keep working.

Qinto turns that around. Your site sends each action once, to a Qinto host on your own domain. The edge resolves who the visitor is, applies the consent that visitor gave, and fans the action out server-side to every app the site has installed. Adding or removing a destination is a change in the Qinto platform — not a change in your page.

This package is the client for that connection:

  • First-party. The socket goes to your own hostname, and the visitor id is a first-party cookie your Qinto host sets. No vendor origin, no third-party pixel.
  • One integration, not one per vendor. Destinations are installed on the site; your page never learns their names.
  • Acknowledged. Every method returns a promise that settles when the edge accepted the action, so you can await a Purchase before you navigate away from the page.
  • Typed, and dependency-free. The types ship with the package, and installing it pulls in nothing else.

If you would rather paste a <script> tag than bundle a client, you do not need this package: the Qinto platform gives you a snippet built from this same source. Install the package when you build your site — an SPA, a framework, a TypeScript app — and want the client in your bundle. The tag lists what differs.

Install

npm i @blotout/qinto-sdk-browser

Connect

Call init once, where your app starts. Nothing to await, nothing to keep:

import { init } from '@blotout/qinto-sdk-browser'

init({ destination: 'https://q.example.com' })

Then import the calls you need from any file:

import { track } from '@blotout/qinto-sdk-browser'

await track('PageView')

destination is your site's Qinto host — the same origin the platform's snippet loads /q.js from. The Qinto platform shows it on the site's snippet page: your own mapped hostname (q.example.com), or the site's development URL while DNS is still pending.

| Option | Default | What it does | | --- | --- | --- | | destination | — | Required. The origin of your Qinto host. | | globalName | qinto | The window property this instance lives on. Change it when the page already has a window.qinto, or to run a second host. | | onError | — | Receives connection errors that belong to no single call — a dropped socket, an unreadable frame. | | requestTimeoutMs | 10000 | How long one call waits for its acknowledgement before it rejects with QintoTimeoutError. | | pageContext | — | A function that names the real page when the client runs in a sandboxed frame. See Sandboxed pages. |

The instance lives on window[globalName], and every call goes through it. A call made before init has connected waits there and is sent, in order, once the connection is open — so a component can track on mount without knowing whether init has finished. If that first connection fails, init rejects and so does every call that was waiting.

init does two things, in order. It loads the browser code of the apps the site installed from <destination>/q.js?tag=0 — the same script the snippet loads, minus the client this package already is — and then opens the connection. It resolves, to the same handle client(globalName) returns, once both are done, so the first call you make already runs through every app. A page with a Content Security Policy must allow the destination in script-src (for /q.js) and wss://<destination host> in connect-src (for /open): an https: source never matches a wss: URL, and a blocked socket leaves init pending with every queued call.

That wait is capped at three seconds, because your events matter more than the apps. A script that is still loading at that point no longer holds init: the client connects, your calls go out, a line in the console says so, and the apps activate the moment the script lands. A script that fails to load is logged the same way and leaves the site's browser apps off for this page. After the first connection the client reconnects on its own with an exponential backoff up to 30 seconds; a call made while the socket is down waits in a queue and is sent on the next open, up to its timeout.

Call init once per page. A second init on a name that is already running rejects with QintoError rather than run every app twice. If the page pasted the snippet as well, init takes over its global: the calls the snippet buffered are sent by this client, and the tag skips its own boot.

init runs in a browser only. On a server it throws QintoEnvironmentError — every reconnect there would mint a new anonymous visitor. Use @blotout/qinto-sdk-server instead.

A second host

A page that sends to two Qinto hosts starts each under its own name, and addresses the second by that name:

init({ destination: 'https://q.example.com' })
init({ destination: 'https://q.partner.com', globalName: 'partner' })

import { client, track } from '@blotout/qinto-sdk-browser'

await track('AddToCart', { value: 10.5 })
await client('partner').track('AddToCart', { value: 10.5 })

client(name) looks the instance up on window[name]; it creates nothing and holds only the name, so it can be written at every call site. The module-level functions are client('qinto').

Sandboxed pages

In a sandboxed frame, such as a Shopify custom pixel, window.location and document.referrer name the frame, not the page the visitor sees, and the site's cookies do not reach the connection. Give the client a pageContext function that returns the real page and the visitor the server reported on an earlier connect:

init({
  destination: 'https://q.example.com',
  pageContext: () => ({
    url: shopPage.url,
    referrer: shopPage.referrer,
    visitor: stored === undefined ? undefined : { id: stored.anonId, session: stored.session }
  })
})

The tag reads the same function from its global. Set it on the snippet's holder before the tag loads:

var t = { _q: 1, q: [], pageContext: function () { return { url: shopPage.url } } }

The client calls it on every connect, reconnect and call, so it must return at once. url is the page's absolute URL. url and referrer name the page for the connection, the calls, the apps and query-parameter capture. visitor goes to the connection only: id continues that visitor, and session (<session id>.<startedAt>) continues that visit. Leave id and session off until the server has reported them in a qinto:connect event; the server mints both. If the function throws, or returns a url that is not an absolute URL, the client uses the frame's own location and referrer.

visitor.fallbackId takes the place of the site's recovery cookie, which a sandboxed frame cannot send. Return the value that cookie would hold, such as the Shopify customer event's clientId. When the connection has no valid id, the server looks the value up under the cookie name set in Settings → Capturing data and continues the visitor it recovers, or binds the new visitor to the value. With no cookie name set, the server ignores it.

For a Shopify store, the Qinto team sets this up with the Shopify custom pixel guide (docs/shopify-pixel/README.md in the Qinto repo).

Send

import { alias, identify, track } from '@blotout/qinto-sdk-browser'

await track('AddToCart', { currency: 'USD', value: 10.5 })

await identify({ email: '[email protected]', plan: 'pro' })
await identify({ plan: 'pro' }, 'crm-user-8412')

await alias('crm-user-8412')

| Method | What it does | | --- | --- | | track(event, properties?, options?) | Records something the visitor did. Resolves to { eventId }. | | identify(traits?, id?) | Merges identity traits into the visitor's profile, and links id — an identifier of your own — to them. | | alias(alias) | Links an identifier of your own to the visitor without touching traits. | | consent(input) | Records the visitor's consent choices. See Consent. |

Details worth knowing:

  • Event names are free-form, but the eleven standard events are the vocabulary apps recognize without per-site configuration. An app that does not know your own name does nothing with it.
  • track returns the event id. A payload carrying a non-empty orderId uses that as the event id, so a purchase you also send from your backend deduplicates across the two. Otherwise one is minted. Pass your own with track(event, properties, { eventId }); a supplied id always wins.
  • options.installs picks the app installs that receive a track. { mode: 'except', installIds } reaches every install but the listed ones, and { mode: 'only', installIds } reaches the listed ones alone. An unknown id is ignored. An empty only list reaches no install, but the event is still sent and stored as usual. On the page, an install the rule leaves out does not see the event in its onEvent; on the server, it does not receive it, though its transform still runs.
  • options.apps picks the apps that receive a track, by slug. { mode: 'only', slugs: ['facebook'] } reaches every install of the listed apps, an install added later included, and except reaches every app but the listed ones. It follows the same rules as installs, and when you pass both, an install receives the event only if both allow it.
  • Traits merge. Only the traits you send change. A trait sent as null clears the stored one, so identify({ plan: null }) is an unset, not a no-op.
  • A trait never links an identifier. An email or phone trait is stored as a standard trait, nothing more; call alias with the value so a later call from your server can address the same person by it.
  • A link is permanent. Repeating alias is safe, and an identifier that already belongs to someone else does not move.

Standard traits

Eight trait keys are the visitor's identity fields. Qinto stores them as such, and apps read them by these names; any other key is a custom trait, kept as sent.

| Key | Meaning | Handling | | --- | --- | --- | | email | Email address | Trimmed and lowercased. Must look like [email protected], or the trait is dropped. | | phone | Phone number | Trimmed; spaces, (), . and - removed; a leading + kept. Needs at least 7 digits and no other characters, or the trait is dropped. | | first_name | Given name | Stored as sent. | | last_name | Family name | Stored as sent. | | country | Country | Stored as sent. | | state | State or region | Stored as sent. | | city | City | Stored as sent. | | postal_code | Postal or ZIP code | Stored as sent. |

await identify({ firstName: 'Ada', email: ' [email protected] ', phone: '+1 (415) 555-0142' })
// stored: first_name 'Ada', email '[email protected]', phone '+14155550142'
  • camelCase keys fold to these names. firstName and first_name are the same field, as are postalCode and postal_code.
  • A dropped value changes nothing. An invalid email or phone leaves the stored one in place; the other traits in the same call still apply.
  • Values are not hashed. The SDK sends what you pass, over HTTPS. A non-string value on a standard key other than email or phone is stored as its JSON.

Read

import { getVisitor } from '@blotout/qinto-sdk-browser'

const { anonId, globalId, ip, geo } = await getVisitor()

| Method | What it returns | | --- | --- | | getVisitor() | { anonId, globalId, ip, geo } — visitor identity plus the server-observed IP and narrow Cloudflare location. geo contains country, EdgeTag-compatible subdivision code region, full subdivision name state, and isEU; unavailable values are null. It asks the server each time, so globalId reflects an identify that just linked the visitor. | | getAnonId() | The anon_… id alone, from the socket's connect. It sends nothing. | | getConsent() | The consent state stored for this visitor, as the server last sent it. It sends nothing. |

The server sends the consent state when the socket connects, answers each consent() call with the state it stored, and pushes every later change, including one the visitor made in another tab or on another device.

The qinto:connect event

The client dispatches a qinto:connect event on window each time the socket connects, reconnects included. Both the tag and init() dispatch it; there is no option to set.

window.addEventListener('qinto:connect', (event) => {
  const { name, anonId, session, reconnect } = (event as CustomEvent).detail
})

| Field | Value | | --- | --- | | name | The global that connected: 'qinto', or the name a second instance uses. | | anonId | The visitor's id: an anon_… id, or the EdgeTag id Qinto adopted for a visitor EdgeTag saw first. | | session | { id, isNew, startedAt }: the visit the server put this connection in, the same session apps get on actions and in onConnect. startedAt is in epoch milliseconds. Absent when the site's worker is older than this client. | | reconnect | false on the first connect of this instance, true on every later one. It does not tell a new visit from a continued one; session.isNew does. |

The event leaves out ip, geo and globalId, because every script on the page can read it. Use getVisitor() for those. A sandboxed page stores anonId and session from this event and returns them from pageContext on the next page.

Consent

import { consent } from '@blotout/qinto-sdk-browser'

await consent({ categories: { analytics: true, marketing: false } })
await consent({ apps: { 'facebook-capi': false } })

Choices merge, so a banner can send one toggle at a time. The five categories are exported as CONSENT_CATEGORIES: necessary, functional, analytics, marketing, salesOfData. necessary is always granted and accepts only true.

Consent decides which apps receive an action: an app is delivered to only when the visitor granted the category its manifest declares, and the per-app map overrides that for one app. It is not a switch on whether Qinto accepts the action. A site that collects no consent at all turns enforcement off in the platform instead.

Geo filters

An install can have a geo filter: the visitor locations where it runs. You set it in the Qinto platform, on the install's card under Site → Apps, or through the API or the MCP tool qinto_set_install_geo_filter. Your page code does not change.

A geo filter has a list of locations to include ("Run only in"), a list to exclude ("Never run in"), or both. Each entry is one of these:

| Entry | Example | Matches | | --- | --- | --- | | Country code (ISO 3166-1 alpha-2) | SI | A visitor in that country | | EU | EU | A visitor in a European Union country | | US state code (ISO 3166-2) | US-CA | A US visitor in that state. The 50 states and DC; US territories use their own country codes |

An install with a geo filter runs for a visitor only when the location is known, the include list is empty or one of its entries matches, and no exclude entry matches. The exclude list wins: include US with exclude US-CA runs everywhere in the US except California. The location is where the visitor is on this page load, not where they first visited the site.

An unknown location turns the install off, because a geo filter is a compliance control. The location is unknown when:

  • the visitor's country is not known (no country, XX, or T1 for Tor);
  • a list names a US state, and a US visitor's state is not known;
  • a list holds EU, and the request does not say whether the country is in the EU.

What it covers. The visitor's browser session: the app's browser code, the connect call, the events and transforms from the page, pushes to the page, stored click ids and cookies, and calls to the app's visitor endpoints. It does not limit events sent with the server SDK or the HTTP API, the app's schedules, its webhooks and API endpoints, MCP tools, or calls from other apps.

A new install runs in all locations. You cannot give an install a geo filter when you create it, and a new install is on and deploys at once, so it runs until you turn it off or save its geo filter. To add an install that must never run in the wrong location, turn the whole app off on the site first, add the install, save its geo filter, then turn the app on. The app's other installs are off for that time too.

When a change takes effect. Saving a geo filter redeploys an active site. The server applies it as soon as the deploy is done; on a site that shares another site's identity graph, pushes, stored click ids and cookies, and the browser's answer can take up to 60 seconds more. A page loaded after that gets a changed list at once; after you add or remove a geo filter, it can take about 10 minutes, because q.js is cached. A page that is already open keeps the installs it started with until it reloads.

What it costs the page. On a site with a geo-filtered install, the client asks once, when it connects, which of those installs it may run, and holds the page's first calls until the answer arrives. If the request fails, those installs stay off for the page and the console says so; all other tracking continues. A site with no geo filter sends no extra request. Every app's browser code still downloads in q.js, as it does for an app the visitor has not consented to; it does not run.

Close

import { close } from '@blotout/qinto-sdk-browser'

await close()

Stops reconnecting and rejects every call still in flight. A page that lives for its whole session rarely needs it.

Errors

Every error the client throws extends QintoError.

| Class | When | | --- | --- | | QintoEnvironmentError | init or a call was made outside a browser. | | QintoError | window[globalName] belongs to something else on the page, or init was called on a name that is already running. | | QintoTimeoutError | The call waited requestTimeoutMs with no acknowledgement. | | QintoProtocolError | The edge refused the frame, or the socket closed with the call in flight. Its message is the edge's own. |

import { QintoTimeoutError } from '@blotout/qinto-sdk-browser'

try {
  await track('Purchase', { currency: 'USD', value: 20.5, orderId: '190315' })
} catch (error) {
  if (error instanceof QintoTimeoutError) {
    // queue it and retry: the order id keeps the retry from double-counting
  }
}

The tag

The Qinto platform also gives you a <script> snippet, built from this same source, that binds a global (window.qinto by default) and queues calls made before it finishes loading. Both talk to the same edge and mint the same ids, so a site can move from one to the other without losing a visitor.

The apps the site installed run in both, init fetches their browser bundles from the same /q.js, consent gates them the same way, and both queue a call made before the connection is open. Two things differ in this package:

  • You choose when it loads. The snippet loads the tag as soon as the page parses it; here, init runs when your code calls it, and the calls are typed imports rather than window.qinto.
  • The page load is yours. The tag can record it for you; here, track('PageView') is yours to call.

Types

QintoBrowserClient (what client(name) and init return), QintoInitOptions, ConsentCategory, ConsentInput, ConsentState, InstallRule, Properties, VisitorInfo, TrackOptions, and Traits are all exported.

Documentation

The standard events, the identity model, and the platform itself are documented at docs.blotout.io.