export type CanonicalUrlMode = "host-aware"; export type ApiVersion = "v1"; export type PathInput = string | undefined; export interface CanonicalPathOptions { mode?: CanonicalUrlMode; } export interface AppPathOptions extends CanonicalPathOptions { tenantSlug: string; path?: PathInput; } export interface AdminPathOptions extends CanonicalPathOptions { path?: PathInput; } export interface ApiPathOptions extends CanonicalPathOptions { path?: PathInput; version?: ApiVersion; } export interface AbsoluteUrlOptions extends CanonicalPathOptions { rootDomain: string; protocol?: "http" | "https"; } export interface AppUrlOptions extends AbsoluteUrlOptions { tenantSlug: string; path?: PathInput; appSubdomain?: string; } export interface AdminUrlOptions extends AbsoluteUrlOptions { path?: PathInput; adminSubdomain?: string; } export interface ApiUrlOptions extends AbsoluteUrlOptions { path?: PathInput; apiSubdomain?: string; version?: ApiVersion; } const DEFAULT_PROTOCOL: AbsoluteUrlOptions["protocol"] = "https"; const DEFAULT_API_VERSION: ApiVersion = "v1"; function encodeTenantSlug(tenantSlug: string) { const trimmed = tenantSlug.trim(); if (!trimmed) { throw new Error("tenantSlug is required"); } return encodeURIComponent(trimmed); } function trimSlashes(value: string) { return value.replace(/^\/+|\/+$/g, ""); } function splitPathSuffix(path: string) { const queryIndex = path.indexOf("?"); const hashIndex = path.indexOf("#"); const indexes = [queryIndex, hashIndex].filter((index) => index >= 0); const suffixIndex = indexes.length > 0 ? Math.min(...indexes) : -1; if (suffixIndex < 0) { return { pathname: path, suffix: "" }; } return { pathname: path.slice(0, suffixIndex), suffix: path.slice(suffixIndex), }; } function normalizeRelativePath(path: PathInput) { if (!path) { return ""; } const { pathname, suffix } = splitPathSuffix(path.trim()); const normalizedPathname = trimSlashes(pathname).split("/").filter(Boolean).join("/"); return `${normalizedPathname}${suffix}`; } function stripApiVersionPrefix(path: string) { const { pathname, suffix } = splitPathSuffix(path); const normalizedPathname = pathname.replace(/^api\/v1(?=\/|$)/, "").replace(/^v1(?=\/|$)/, ""); return `${normalizedPathname}${suffix}`; } function joinPath(...segments: Array) { const nonEmptySegments = segments.filter((segment): segment is string => Boolean(segment)); const lastSegment = nonEmptySegments.at(-1); let suffix = ""; if (lastSegment) { const split = splitPathSuffix(lastSegment); suffix = split.suffix; nonEmptySegments[nonEmptySegments.length - 1] = split.pathname; } const joined = nonEmptySegments .map((segment) => trimSlashes(segment)) .filter(Boolean) .join("/"); return `/${joined}${suffix}`; } function normalizeHostLabel(label: string | undefined) { if (!label) { return undefined; } const normalized = trimSlashes(label.trim()).replace(/\.+$/g, ""); return normalized || undefined; } function parseRootDomain(rootDomain: string, protocol: AbsoluteUrlOptions["protocol"] | undefined) { const trimmed = rootDomain.trim(); if (!trimmed) { throw new Error("rootDomain is required"); } const withProtocol = /^[a-z][a-z\d+\-.]*:\/\//i.test(trimmed) ? trimmed : `${protocol ?? DEFAULT_PROTOCOL}://${trimmed}`; const url = new URL(withProtocol); return { protocol: url.protocol.replace(":", ""), host: url.host.replace(/\/+$/g, ""), }; } function withSubdomain(host: string, subdomain: string | undefined) { const normalizedSubdomain = normalizeHostLabel(subdomain); if (!normalizedSubdomain) { return host; } return `${normalizedSubdomain}.${host}`; } function absoluteUrl(rootDomain: string, path: string, subdomain: string | undefined, protocol?: AbsoluteUrlOptions["protocol"]) { const root = parseRootDomain(rootDomain, protocol); return `${root.protocol}://${withSubdomain(root.host, subdomain)}${path}`; } export function appPath({ tenantSlug, path }: AppPathOptions) { const normalizedPath = normalizeRelativePath(path); const tenantSegment = encodeTenantSlug(tenantSlug); return joinPath(tenantSegment, normalizedPath); } export function adminPath(pathOrOptions?: PathInput | AdminPathOptions, _options?: CanonicalPathOptions) { void _options; const path = typeof pathOrOptions === "object" && pathOrOptions !== null ? pathOrOptions.path : pathOrOptions; const normalizedPath = normalizeRelativePath(path); return joinPath(normalizedPath); } export function apiPath(pathOrOptions?: PathInput | ApiPathOptions, options?: ApiPathOptions) { const path = typeof pathOrOptions === "object" && pathOrOptions !== null ? pathOrOptions.path : pathOrOptions; const version = typeof pathOrOptions === "object" && pathOrOptions !== null ? pathOrOptions.version : options?.version; const normalizedPath = stripApiVersionPrefix(normalizeRelativePath(path)); return joinPath(version ?? DEFAULT_API_VERSION, normalizedPath); } export function appUrl({ rootDomain, protocol, appSubdomain, ...pathOptions }: AppUrlOptions) { return absoluteUrl(rootDomain, appPath(pathOptions), appSubdomain, protocol); } export function adminUrl({ rootDomain, protocol, adminSubdomain, path }: AdminUrlOptions) { return absoluteUrl(rootDomain, adminPath({ path }), adminSubdomain, protocol); } export function apiUrl({ rootDomain, protocol, apiSubdomain, path, version }: ApiUrlOptions) { return absoluteUrl(rootDomain, apiPath({ path, version }), apiSubdomain, protocol); } const canonicalUrlUtils = { appPath, adminPath, apiPath, appUrl, adminUrl, apiUrl, }; export default canonicalUrlUtils;