@pas7/nextjs-sitemap-hreflang 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,261 @@
+type ChangeFrequency = "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+type SitemapAlternates = {
+    languages?: Record<string, string>;
+};
+type SitemapEntryLike = {
+    url: string;
+    lastModified?: string | Date;
+    changeFrequency?: ChangeFrequency;
+    priority?: number;
+    alternates?: SitemapAlternates;
+    images?: string[];
+};
+type SitemapEntry = SitemapEntryLike;
+type XDefaultStrategy = {
+    type: "loc";
+} | {
+    type: "root";
+} | {
+    type: "locale";
+    locale: string;
+} | {
+    type: "custom";
+    url: string;
+} | {
+    type: "fn";
+    resolve: (entry: SitemapEntryLike) => string;
+};
+type HreflangIssueCode = "MISSING_LANGUAGES" | "MISSING_XDEFAULT" | "MISSING_SELF" | "NON_ABSOLUTE_URL" | "INVALID_LOCALE_KEY" | "DUPLICATE_HREFLANG_KEY" | "DUPLICATE_HREF" | "INVALID_HREFLANG_CASING" | "INCONSISTENT_ORIGIN";
+type HreflangIssue = {
+    code: HreflangIssueCode;
+    entryUrl: string;
+    message: string;
+};
+type HreflangReport = {
+    ok: boolean;
+    issues: HreflangIssue[];
+};
+/**
+ * Routing strategy for generating hreflang URLs.
+ * This makes the package routing-agnostic.
+ */
+type RoutingStrategy = {
+    /** Supported locales */
+    readonly locales: readonly string[];
+    /** Default/canonical locale */
+    readonly canonicalLocale: string;
+    /** Generate URL for a given pathname and locale */
+    readonly hrefFor: (args: {
+        pathname: string;
+        locale: string;
+    }) => string;
+    /** x-default strategy (optional) */
+    readonly xDefault?: XDefaultStrategy;
+};
+/**
+ * Options for prefix-as-needed routing (like next-intl)
+ */
+type RoutingPrefixAsNeededOptions = {
+    readonly defaultLocale: string;
+    readonly locales: readonly string[];
+    readonly basePath?: string;
+};
+/**
+ * Options for prefix-always routing
+ */
+type RoutingPrefixAlwaysOptions = {
+    readonly defaultLocale: string;
+    readonly locales: readonly string[];
+    readonly basePath?: string;
+};
+/**
+ * Options for domain-based routing
+ */
+type RoutingDomainBasedOptions = {
+    readonly defaultLocale: string;
+    readonly locales: readonly string[];
+    readonly localeToDomain: Record<string, string>;
+};
+/**
+ * Options for suffix-locale routing (like /blog/uk)
+ */
+type RoutingSuffixLocaleOptions = {
+    readonly defaultLocale: string;
+    readonly locales: readonly string[];
+    readonly basePath?: string;
+};
+/**
+ * Options for PAS7 custom routing scheme
+ */
+type RoutingPAS7Options = {
+    readonly defaultLocale: string;
+    readonly locales: readonly string[];
+    readonly hubPaths?: readonly string[];
+    readonly detailPathPattern?: RegExp;
+};
+
+type ManifestRouteStyle = "prefix-as-needed" | "prefix-always" | "suffix-locale" | "locale-segment";
+type LocalizedManifestItem = {
+    slug: string;
+    locales: readonly string[];
+    updatedAt?: string | Date;
+    publishedAt?: string | Date;
+    lastModified?: string | Date;
+    date?: string | Date;
+    changeFrequency?: ChangeFrequency;
+    priority?: number;
+    images?: string[];
+};
+type CreateSitemapEntriesFromManifestOptions = {
+    baseUrl: string;
+    sectionPath: string;
+    defaultLocale: string;
+    canonicalLocale?: string;
+    routeStyle?: ManifestRouteStyle;
+    trailingSlash?: "preserve" | "always" | "never";
+    ensureXDefault?: boolean;
+    xDefaultStrategy?: XDefaultStrategy;
+    includeLocales?: readonly string[];
+    pathnameFor?: (args: {
+        slug: string;
+        locale: string;
+        defaultLocale: string;
+        sectionPath: string;
+        routeStyle: ManifestRouteStyle;
+    }) => string;
+};
+declare function createSitemapEntriesFromManifest<T extends LocalizedManifestItem>(items: readonly T[], options: CreateSitemapEntriesFromManifestOptions): SitemapEntry[];
+
+type BuildLanguagesMapInput = {
+    baseUrl: string;
+    locales: readonly string[];
+    canonicalLocale: string;
+    resolveHref: (locale: string) => string;
+    includeXDefault: boolean;
+    xDefaultStrategy?: XDefaultStrategy;
+    trailingSlash?: "preserve" | "always" | "never";
+};
+type BuildLanguagesMapOutput = {
+    canonical: string;
+    languages: Record<string, string>;
+};
+declare function buildLanguagesMap(input: BuildLanguagesMapInput): BuildLanguagesMapOutput;
+
+type TrailingSlashPolicy = "preserve" | "always" | "never";
+declare function normalizeUrl(url: string, trailingSlash: TrailingSlashPolicy): string;
+declare function resolveAbsoluteUrl(input: string, baseUrl: string): string;
+
+type WithHreflangOptions = {
+    baseUrl?: string;
+    trailingSlash?: "preserve" | "always" | "never";
+    ensureAbsolute?: boolean;
+    ensureXDefault?: boolean;
+    ensureSelf?: boolean;
+    canonicalLocale?: string;
+    xDefaultStrategy?: XDefaultStrategy;
+    shouldApply?: (entry: SitemapEntryLike) => boolean;
+};
+declare function withHreflang<T extends SitemapEntryLike>(entries: readonly T[], options: WithHreflangOptions): T[];
+type AssertHreflangOptions = {
+    requireAbsolute?: boolean;
+    requireXDefaultWhenMultiple?: boolean;
+    requireSelf?: boolean;
+    canonicalLocale?: string;
+};
+declare function assertHreflangExport(entries: readonly SitemapEntryLike[], options: AssertHreflangOptions): HreflangReport;
+/**
+ * Build hreflang entries using a routing strategy.
+ * This is the recommended way to use withHreflang with i18n routing.
+ */
+declare function withHreflangFromRouting<T extends SitemapEntryLike>(entries: readonly T[], strategy: RoutingStrategy, options: {
+    baseUrl: string;
+    trailingSlash?: "preserve" | "always" | "never";
+    ensureAbsolute?: boolean;
+    ensureXDefault?: boolean;
+    ensureSelf?: boolean;
+    shouldApply?: (entry: SitemapEntryLike) => boolean;
+}): T[];
+
+/**
+ * Prefix-as-needed routing: default locale has no prefix, others have /locale
+ * Example: /about (en), /uk/about (uk), /de/about (de)
+ *
+ * Compatible with next-intl's prefix-as-needed strategy.
+ */
+declare function routingPrefixAsNeeded(options: RoutingPrefixAsNeededOptions): RoutingStrategy;
+/**
+ * Prefix-always routing: all locales have /locale prefix
+ * Example: /en/about, /uk/about, /de/about
+ *
+ * Compatible with next-intl's prefix-always strategy.
+ */
+declare function routingPrefixAlways(options: RoutingPrefixAlwaysOptions): RoutingStrategy;
+/**
+ * Domain-based routing: each locale has its own domain
+ * Example: example.com (en), example.de (de), example.ua (uk)
+ *
+ * Compatible with next-intl's domain-based routing.
+ */
+declare function routingDomainBased(options: RoutingDomainBasedOptions): RoutingStrategy;
+/**
+ * Suffix-locale routing: locale added as suffix to path
+ * Example: /blog (en), /blog/uk (uk), /blog/de (de)
+ *
+ * Common for blogs and content sections.
+ */
+declare function routingSuffixLocale(options: RoutingSuffixLocaleOptions): RoutingStrategy;
+/**
+ * Custom routing with user-defined function
+ */
+declare function routingCustom(options: {
+    locales: readonly string[];
+    canonicalLocale: string;
+    hrefFor: (args: {
+        pathname: string;
+        locale: string;
+    }) => string;
+    xDefault?: RoutingStrategy["xDefault"];
+}): RoutingStrategy;
+/**
+ * PAS7 custom routing strategy:
+ * - Home: / (en), /uk, /de, /it, /hr
+ * - Hubs: /blog (en), /blog/uk, /blog/de
+ * - Details: /blog/en/<slug>, /blog/uk/<slug>
+ *
+ * This is a hybrid routing scheme where:
+ * - Home pages use prefix pattern for non-default locales
+ * - Hub pages (listing pages) use suffix pattern for non-default locales
+ * - Detail pages have locale as a segment after the section
+ */
+declare function routingPAS7(options: RoutingPAS7Options): RoutingStrategy;
+
+type ExpandLocalesOptions = {
+    mode: "cluster-only" | "expanded";
+    includeXDefault?: boolean;
+    locales?: readonly string[];
+};
+declare function expandLocaleEntries<T extends SitemapEntryLike>(entries: readonly T[], options: ExpandLocalesOptions): T[];
+
+type InjectOptions = {
+    baseUrl?: string;
+    xDefaultStrategy?: XDefaultStrategy;
+    ensureNamespace?: boolean;
+    canonicalLocale?: string;
+    order?: "canonical-first" | "preserve";
+    trailingSlash?: "preserve" | "always" | "never";
+};
+declare function injectXDefaultIntoSitemapXml(xml: string, options: InjectOptions): string;
+
+type CheckXmlOptions = {
+    requireNamespace?: boolean;
+    requireXDefaultWhenMultiple?: boolean;
+    requireAbsolute?: boolean;
+    checkDuplicateKeys?: boolean;
+    checkDuplicateHrefs?: boolean;
+    checkHreflangCasing?: boolean;
+    originPolicy?: "same" | "allowlist" | "off";
+    allowedOrigins?: string[];
+};
+declare function checkSitemapXmlHreflang(xml: string, options: CheckXmlOptions): HreflangReport;
+
+export { type ChangeFrequency, type CheckXmlOptions, type CreateSitemapEntriesFromManifestOptions, type ExpandLocalesOptions, type HreflangIssue, type HreflangIssueCode, type HreflangReport, type InjectOptions, type LocalizedManifestItem, type ManifestRouteStyle, type RoutingDomainBasedOptions, type RoutingPAS7Options, type RoutingPrefixAlwaysOptions, type RoutingPrefixAsNeededOptions, type RoutingStrategy, type RoutingSuffixLocaleOptions, type SitemapAlternates, type SitemapEntry, type SitemapEntryLike, type XDefaultStrategy, assertHreflangExport as assertHreflang, buildLanguagesMap, checkSitemapXmlHreflang, createSitemapEntriesFromManifest, expandLocaleEntries, injectXDefaultIntoSitemapXml, normalizeUrl, resolveAbsoluteUrl, routingCustom, routingDomainBased, routingPAS7, routingPrefixAlways, routingPrefixAsNeeded, routingSuffixLocale, withHreflang, withHreflangFromRouting };