@short.io/statistics-merger

Fetches Short.io statistics from both the US and EU regions in parallel and merges the responses into a single result. Used by services that need a unified view of click-level analytics across regions.

Install

pnpm add @short.io/statistics-merger
# or
npm install @short.io/statistics-merger

Requires Node.js 18+ (uses the built-in fetch and Response globals).

Usage

Every exported function takes an API token and a payload, fans the request out to the US and EU stats hosts, and returns a Lambda-style envelope: { headers, statusCode, body } on success, or { headers, statusCode, error } on 4xx upstream failures. 5xx and network errors are re-thrown.

import { fetchDomainOverview } from "@short.io/statistics-merger";

const result = await fetchDomainOverview(
    "YOUR_API_TOKEN",
    "/statistics",
    {
        domainId: "123",
        payloadData: { startDate: "2026-01-01", endDate: "2026-01-31" },
    },
    "POST",
);

if (result.statusCode === 200) {
    console.log(result.body.clicks, result.body.country);
} else {
    console.error(result.error);
}

API

All fetch* functions accept an optional trailing endpoints?: StatsEndpoints parameter to override the default US/EU hosts (https://stats-internal.short.io and https://stats-eu.short.io):

await fetchDomainOverview(token, "/statistics", payload, "POST", {
    us: "https://stats-us.internal.example",
    eu: "https://stats-eu.internal.example",
});

Either region can be overridden independently; the other falls back to the default host.

fetchDomainOverview(token, statisticsUrl, payload, method, endpoints?)

Calls /domain/:domainId. Sums clicks / humanClicks, recomputes clicksPerLink, and merges the clickStatistics time series plus the top-N lists for browser, os, city, country, social, device, and utm.

fetchLinkOverview(token, statisticsUrl, payload, method, endpoints?)

Calls /link/:linkId. Sums totalClicks / humanClicks and merges clickStatistics plus the top-N lists for browser, os, city, country, social, referer, and device.

fetchTopColumn(token, statisticsUrl, payload, endpoints?)

Calls /domain/:domainId/top. Returns a single merged, descending-by-score list of ColumnScore entries, summing matching columns across regions.

fetchTopColumnByInterval(token, statisticsUrl, payload, endpoints?)

Calls /domain/:domainId/top_by_interval. Merges per-date top-column statistics across regions.

fetchTopColumnByLink(token, statisticsUrl, payload, endpoints?)

Calls /link/:linkId/top. Same merge behavior as fetchTopColumn but scoped to one link.

fetchLastClicks(token, statisticsUrl, payload, endpoints?)

Calls /domain/:domainId/last_clicks. Concatenates both regions' click lists and sorts descending by dt.

fetchLinkClicks(token, statisticsUrl, payload, endpoints?)

Calls /domain/:domainId/link_clicks. Returns a { [path]: count } map with per-path counts summed across regions.

fetchDomainLinkClicks(token, payload, endpoints?)

Calls /domain/:domainId/domain_clicks as a CSV stream, parses both regions (csv-parse), and returns the merged { [path]: count } map. Unlike the other helpers, this one does not take a statisticsUrl argument.

statsRequest(path, options, endpoints?)

Low-level primitive exported for advanced use. Issues the same request to both regions in parallel and returns [usResponse, euResponse]. Supports responseType: "json" | "text" | "stream" with overloaded return types.

Error handling

On a 4xx from either region, each fetch* function catches the internal FetchError and returns:

{
    headers: { "content-type": "application/json" },
    statusCode: 4xx,
    error: createError(status, { name, message, status, statusText }),
}

5xx responses and non-HTTP failures propagate as thrown FetchErrors (or the original error for network-level failures). FetchError is exported from the package entry point via statsRequest's module and carries { response: { status, statusText } }.

Scripts

• pnpm compile — TypeScript build to dist/ with declarations in dist/types/.
• pnpm format — Biome check + write over ./src.
• pnpm test — compiles to dist-test/ with tsconfig.test.json and runs node --test.

License

ISC