ropegeo-common 1.1.2 → 1.1.4

package/dist/index.d.ts

@@ -7,6 +7,10 @@ export { RoutesGeojson } from './types/api/getRoutes/routeGeojson';
 export type { RopewikiImageView } from './types/api/getRopewikiPageView/ropewikiImageView';
 export type { RopewikiBetaSectionView } from './types/api/getRopewikiPageView/ropewikiBetaSectionView';
 export type { RopewikiPageView } from './types/api/getRopewikiPageView/ropewikiPageView';
-export type { RegionPreview } from './types/api/search/regionPreview';
-export type { SearchResults } from './types/api/search/searchResults';
+export { RegionPreview } from './types/api/search/regionPreview';
+export { SearchCursor } from './types/api/search/searchCursor';
+export type { SearchCursorType } from './types/api/search/searchCursor';
+export { SearchParams } from './types/api/search/searchParams';
+export type { SearchOrder } from './types/api/search/searchParams';
+export { SearchResults } from './types/api/search/searchResults';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACjG,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AAC3F,YAAY,EAAE,uBAAuB,EAAE,MAAM,yDAAyD,CAAC;AACvG,YAAY,EAAE,gBAAgB,EAAE,MAAM,kDAAkD,CAAC;AACzF,YAAY,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACjG,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mDAAmD,CAAC;AAC3F,YAAY,EAAE,uBAAuB,EAAE,MAAM,yDAAyD,CAAC;AACvG,YAAY,EAAE,gBAAgB,EAAE,MAAM,kDAAkD,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,YAAY,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RoutesGeojson = exports.RouteType = exports.Route = exports.PagePreview = exports.PermitStatus = exports.DifficultyWater = exports.DifficultyTime = exports.DifficultyTechnical = exports.DifficultyRisk = exports.Difficulty = exports.PageDataSource = void 0;
+exports.SearchResults = exports.SearchParams = exports.SearchCursor = exports.RegionPreview = exports.RoutesGeojson = exports.RouteType = exports.Route = exports.PagePreview = exports.PermitStatus = exports.DifficultyWater = exports.DifficultyTime = exports.DifficultyTechnical = exports.DifficultyRisk = exports.Difficulty = exports.PageDataSource = void 0;
 var pageDataSource_1 = require("./types/pageDataSource");
 Object.defineProperty(exports, "PageDataSource", { enumerable: true, get: function () { return pageDataSource_1.PageDataSource; } });
 var difficulty_1 = require("./types/difficulty");
@@ -18,3 +18,11 @@ Object.defineProperty(exports, "Route", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "RouteType", { enumerable: true, get: function () { return route_1.RouteType; } });
 var routeGeojson_1 = require("./types/api/getRoutes/routeGeojson");
 Object.defineProperty(exports, "RoutesGeojson", { enumerable: true, get: function () { return routeGeojson_1.RoutesGeojson; } });
+var regionPreview_1 = require("./types/api/search/regionPreview");
+Object.defineProperty(exports, "RegionPreview", { enumerable: true, get: function () { return regionPreview_1.RegionPreview; } });
+var searchCursor_1 = require("./types/api/search/searchCursor");
+Object.defineProperty(exports, "SearchCursor", { enumerable: true, get: function () { return searchCursor_1.SearchCursor; } });
+var searchParams_1 = require("./types/api/search/searchParams");
+Object.defineProperty(exports, "SearchParams", { enumerable: true, get: function () { return searchParams_1.SearchParams; } });
+var searchResults_1 = require("./types/api/search/searchResults");
+Object.defineProperty(exports, "SearchResults", { enumerable: true, get: function () { return searchResults_1.SearchResults; } });

package/dist/types/api/getRoutePreview/pagePreview.d.ts

@@ -25,6 +25,8 @@ export interface GetRopewikiPagePreviewRow {
  * Used by GET /route/{routeId}/preview.
  */
 export declare class PagePreview {
+    /** Discriminator for search results: always 'page' */
+    readonly previewType: "page";
     /** Page identifier (e.g. RopewikiPage id) */
     id: string;
     /** Source of the page (e.g. ropewiki) */

package/dist/types/api/getRoutePreview/pagePreview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagePreview.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRoutePreview/pagePreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,WAAW;IACpB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,MAAM,EAAE,cAAc,CAAC;IACvB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iDAAiD;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oDAAoD;IACpD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2IAA2I;IAC3I,UAAU,EAAE,UAAU,CAAC;IACvB,sDAAsD;IACtD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yDAAyD;IACzD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0DAA0D;IAC1D,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;gBAGxB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,MAAM,EAAE,YAAY,GAAG,IAAI;IAe/B;;OAEG;IACH,MAAM,CAAC,SAAS,CACZ,GAAG,EAAE,yBAAyB,EAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,OAAO,CAAC,EAAE,MAAM,EAAE,GACnB,WAAW;IAsBd,OAAO,CAAC,MAAM,CAAC,WAAW;CAK7B"}
+{"version":3,"file":"pagePreview.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRoutePreview/pagePreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,WAAW;IACpB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAG,MAAM,CAAU;IACvC,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,MAAM,EAAE,cAAc,CAAC;IACvB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iDAAiD;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oDAAoD;IACpD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2IAA2I;IAC3I,UAAU,EAAE,UAAU,CAAC;IACvB,sDAAsD;IACtD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yDAAyD;IACzD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0DAA0D;IAC1D,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;gBAGxB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,MAAM,EAAE,YAAY,GAAG,IAAI;IAe/B;;OAEG;IACH,MAAM,CAAC,SAAS,CACZ,GAAG,EAAE,yBAAyB,EAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,OAAO,CAAC,EAAE,MAAM,EAAE,GACnB,WAAW;IAsBd,OAAO,CAAC,MAAM,CAAC,WAAW;CAK7B"}

package/dist/types/api/getRoutePreview/pagePreview.js

@@ -10,6 +10,8 @@ const pageDataSource_1 = require("../../pageDataSource");
  */
 class PagePreview {
     constructor(id, source, imageUrl, rating, ratingCount, title, regions, difficulty, mapData, externalLink, permit) {
+        /** Discriminator for search results: always 'page' */
+        this.previewType = 'page';
         this.id = id;
         this.source = source;
         this.imageUrl = imageUrl;

package/dist/types/api/search/regionPreview.d.ts

@@ -1,10 +1,12 @@
 import { PageDataSource } from '../../pageDataSource';
-export interface RegionPreview {
+export declare class RegionPreview {
+    readonly previewType: "region";
     id: string;
     name: string;
     parents: string[];
     pageCount: number;
     imageUrl: string | null;
     source: PageDataSource;
+    constructor(id: string, name: string, parents: string[], pageCount: number, imageUrl: string | null, source: PageDataSource);
 }
 //# sourceMappingURL=regionPreview.d.ts.map

package/dist/types/api/search/regionPreview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regionPreview.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/regionPreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,cAAc,CAAC;CAC1B"}
+{"version":3,"file":"regionPreview.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/regionPreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,qBAAa,aAAa;IACtB,QAAQ,CAAC,WAAW,EAAG,QAAQ,CAAU;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,cAAc,CAAC;gBAGnB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,cAAc;CAS7B"}

package/dist/types/api/search/regionPreview.js

@@ -1,2 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegionPreview = void 0;
+class RegionPreview {
+    constructor(id, name, parents, pageCount, imageUrl, source) {
+        this.previewType = 'region';
+        this.id = id;
+        this.name = name;
+        this.parents = parents;
+        this.pageCount = pageCount;
+        this.imageUrl = imageUrl;
+        this.source = source;
+    }
+}
+exports.RegionPreview = RegionPreview;

package/dist/types/api/search/searchCursor.d.ts

@@ -0,0 +1,17 @@
+export type SearchCursorType = 'page' | 'region';
+/**
+ * Cursor for search API pagination. Encodes to base64url for the nextCursor string.
+ */
+export declare class SearchCursor {
+    readonly sortKey: number;
+    readonly type: SearchCursorType;
+    readonly id: string;
+    constructor(sortKey: number, type: SearchCursorType, id: string);
+    encodeBase64(): string;
+    /**
+     * Decodes a base64url-encoded cursor string. Throws if the string is invalid
+     * or does not represent a valid SearchCursor.
+     */
+    static decodeBase64(encoded: string): SearchCursor;
+}
+//# sourceMappingURL=searchCursor.d.ts.map

package/dist/types/api/search/searchCursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchCursor.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/searchCursor.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEjD;;GAEG;AACH,qBAAa,YAAY;aAED,OAAO,EAAE,MAAM;aACf,IAAI,EAAE,gBAAgB;aACtB,EAAE,EAAE,MAAM;gBAFV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,MAAM;IAG9B,YAAY,IAAI,MAAM;IAMtB;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;CAmCrD"}

package/dist/types/api/search/searchCursor.js

@@ -0,0 +1,58 @@
+"use strict";
+/// <reference types="node" />
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchCursor = void 0;
+const ENCODING = 'utf8';
+const BASE64URL = 'base64url';
+/**
+ * Cursor for search API pagination. Encodes to base64url for the nextCursor string.
+ */
+class SearchCursor {
+    constructor(sortKey, type, id) {
+        this.sortKey = sortKey;
+        this.type = type;
+        this.id = id;
+    }
+    encodeBase64() {
+        return Buffer.from(JSON.stringify({ sortKey: this.sortKey, type: this.type, id: this.id }), ENCODING).toString(BASE64URL);
+    }
+    /**
+     * Decodes a base64url-encoded cursor string. Throws if the string is invalid
+     * or does not represent a valid SearchCursor.
+     */
+    static decodeBase64(encoded) {
+        if (typeof encoded !== 'string' || encoded === '') {
+            throw new Error('Search cursor must be a non-empty string');
+        }
+        let decoded;
+        try {
+            const json = Buffer.from(encoded, BASE64URL).toString(ENCODING);
+            decoded = JSON.parse(json);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Invalid search cursor encoding: ${message}`);
+        }
+        if (decoded == null ||
+            typeof decoded !== 'object' ||
+            !('sortKey' in decoded) ||
+            !('type' in decoded) ||
+            !('id' in decoded)) {
+            throw new Error('Search cursor must be an object with sortKey, type, and id');
+        }
+        const obj = decoded;
+        const type = obj.type;
+        if (type !== 'page' && type !== 'region') {
+            throw new Error(`Search cursor type must be "page" or "region", got: ${JSON.stringify(type)}`);
+        }
+        if (typeof obj.id !== 'string') {
+            throw new Error(`Search cursor id must be a string, got: ${typeof obj.id}`);
+        }
+        const sortKey = Number(obj.sortKey);
+        if (Number.isNaN(sortKey)) {
+            throw new Error(`Search cursor sortKey must be a number, got: ${JSON.stringify(obj.sortKey)}`);
+        }
+        return new SearchCursor(sortKey, type, obj.id);
+    }
+}
+exports.SearchCursor = SearchCursor;

package/dist/types/api/search/searchParams.d.ts

@@ -0,0 +1,34 @@
+import { SearchCursor } from './searchCursor';
+export type SearchOrder = 'similarity' | 'quality';
+/**
+ * Validated search parameters. Cursor is stored decoded (SearchCursor | null).
+ * The constructor accepts an encoded cursor string and decodes it.
+ */
+export declare class SearchParams {
+    readonly name: string;
+    readonly similarityThreshold: number;
+    readonly includePages: boolean;
+    readonly includeRegions: boolean;
+    readonly includeAka: boolean;
+    readonly regionId: string | null;
+    readonly order: SearchOrder;
+    readonly limit: number;
+    readonly cursor: SearchCursor | null;
+    constructor(name: string, similarityThreshold: number, includePages: boolean, includeRegions: boolean, includeAka: boolean, regionId: string | null, order: SearchOrder, limit: number, cursorEncoded: string | null);
+    /**
+     * Returns an object suitable for use as query string parameters.
+     * Cursor is encoded for the query string.
+     */
+    toQueryStringParams(): Record<string, string>;
+    /**
+     * Parses and validates query string parameters. Throws with a descriptive
+     * error message if any value is invalid.
+     */
+    static fromQueryStringParams(q: Record<string, string | undefined>): SearchParams;
+    /**
+     * Parses a boolean from a query string value. Returns defaultValue when value is undefined or empty.
+     * Throws when value is a non-empty string that is not "true", "false", "1", or "0" (case-insensitive).
+     */
+    private static parseBoolean;
+}
+//# sourceMappingURL=searchParams.d.ts.map

package/dist/types/api/search/searchParams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/searchParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,SAAS,CAAC;AAOnD;;;GAGG;AACH,qBAAa,YAAY;IACrB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,mBAAmB,EAAE,MAAM,CAAC;IAC5C,SAAgB,YAAY,EAAE,OAAO,CAAC;IACtC,SAAgB,cAAc,EAAE,OAAO,CAAC;IACxC,SAAgB,UAAU,EAAE,OAAO,CAAC;IACpC,SAAgB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,SAAgB,KAAK,EAAE,WAAW,CAAC;IACnC,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;gBAGxC,IAAI,EAAE,MAAM,EACZ,mBAAmB,EAAE,MAAM,EAC3B,YAAY,EAAE,OAAO,EACrB,cAAc,EAAE,OAAO,EACvB,UAAU,EAAE,OAAO,EACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GAAG,IAAI;IAqEhC;;;OAGG;IACH,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAmB7C;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,YAAY;IA2Ff;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAY9B"}

package/dist/types/api/search/searchParams.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchParams = void 0;
+const searchCursor_1 = require("./searchCursor");
+const DEFAULT_LIMIT = 20;
+/** UUID v4 format: 8-4-4-4-12 hex digits */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Validated search parameters. Cursor is stored decoded (SearchCursor | null).
+ * The constructor accepts an encoded cursor string and decodes it.
+ */
+class SearchParams {
+    constructor(name, similarityThreshold, includePages, includeRegions, includeAka, regionId, order, limit, cursorEncoded) {
+        if (typeof name !== 'string' || name.trim() === '') {
+            throw new Error('Missing or empty required query parameter: name');
+        }
+        if (typeof similarityThreshold !== 'number' ||
+            Number.isNaN(similarityThreshold) ||
+            similarityThreshold < 0 ||
+            similarityThreshold > 1) {
+            throw new Error('Query parameter "similarity" must be a number between 0 and 1');
+        }
+        if (!includePages && !includeRegions) {
+            throw new Error('At least one of include-pages or include-regions must be true');
+        }
+        if (includeAka && !includePages) {
+            throw new Error('include-aka cannot be true when include-pages is false');
+        }
+        if (order !== 'similarity' && order !== 'quality') {
+            throw new Error('Query parameter "order" must be one of: similarity, quality');
+        }
+        const limitNum = Number(limit);
+        if (Number.isNaN(limitNum) ||
+            !Number.isInteger(limitNum) ||
+            limitNum < 1) {
+            throw new Error('Query parameter "limit" must be a whole number greater than 0');
+        }
+        const trimmedRegionId = (regionId !== null && regionId !== '' ? regionId.trim() : null) || null;
+        if (trimmedRegionId !== null && !UUID_REGEX.test(trimmedRegionId)) {
+            throw new Error('Query parameter "region" must be a valid UUID');
+        }
+        this.name = name;
+        this.similarityThreshold = similarityThreshold;
+        this.includePages = includePages;
+        this.includeRegions = includeRegions;
+        this.includeAka = includeAka;
+        this.regionId = trimmedRegionId;
+        this.order = order;
+        this.limit = limit;
+        if (cursorEncoded === null || cursorEncoded === '') {
+            this.cursor = null;
+        }
+        else {
+            try {
+                this.cursor = searchCursor_1.SearchCursor.decodeBase64(cursorEncoded);
+            }
+            catch {
+                throw new Error('Invalid or malformed query parameter: cursor');
+            }
+        }
+    }
+    /**
+     * Returns an object suitable for use as query string parameters.
+     * Cursor is encoded for the query string.
+     */
+    toQueryStringParams() {
+        const params = {
+            name: this.name,
+            similarity: String(this.similarityThreshold),
+            'include-pages': String(this.includePages),
+            'include-regions': String(this.includeRegions),
+            'include-aka': String(this.includeAka),
+            order: this.order,
+            limit: String(this.limit),
+        };
+        if (this.regionId !== null && this.regionId !== '') {
+            params.region = this.regionId;
+        }
+        if (this.cursor !== null) {
+            params.cursor = this.cursor.encodeBase64();
+        }
+        return params;
+    }
+    /**
+     * Parses and validates query string parameters. Throws with a descriptive
+     * error message if any value is invalid.
+     */
+    static fromQueryStringParams(q) {
+        const name = (q.name ?? q.Name ?? '').trim();
+        if (!name) {
+            throw new Error('Missing or empty required query parameter: name');
+        }
+        const limitParam = q.limit ?? q.Limit ?? '';
+        let limit;
+        if (limitParam === '') {
+            limit = DEFAULT_LIMIT;
+        }
+        else {
+            const limitNum = Number(limitParam);
+            if (Number.isNaN(limitNum) ||
+                !Number.isInteger(limitNum) ||
+                limitNum < 1) {
+                throw new Error('Query parameter "limit" must be a whole number greater than 0');
+            }
+            limit = limitNum;
+        }
+        const cursorRaw = (q.cursor ?? q.Cursor ?? '').trim();
+        const cursorEncoded = cursorRaw === '' ? null : cursorRaw;
+        const similarityParam = q.similarity ?? q.Similarity ?? '';
+        const similarity = similarityParam === '' ? 0.5 : Number(similarityParam);
+        const orderParam = (q.order ?? q.Order ?? '').trim().toLowerCase();
+        if (orderParam !== '' &&
+            orderParam !== 'similarity' &&
+            orderParam !== 'quality') {
+            throw new Error('Query parameter "order" must be one of: similarity, quality');
+        }
+        const order = orderParam === 'quality' ? 'quality' : 'similarity';
+        const includePages = SearchParams.parseBoolean(q['include-pages'] ?? q['Include-Pages'], true);
+        const includeRegions = SearchParams.parseBoolean(q['include-regions'] ?? q['Include-Regions'], true);
+        if (!includePages && !includeRegions) {
+            throw new Error('At least one of include-pages or include-regions must be true');
+        }
+        const includeAkaParam = q['include-aka'] ?? q['Include-Aka'];
+        const includeAkaExplicit = (includeAkaParam ?? '').trim() !== '';
+        let includeAka = SearchParams.parseBoolean(includeAkaParam, true);
+        if (!includeAkaExplicit && !includePages) {
+            includeAka = false;
+        }
+        if (includeAkaExplicit && includeAka && !includePages) {
+            throw new Error('include-aka cannot be true when include-pages is false');
+        }
+        const region = (q.region ?? q.Region ?? '').trim() || null;
+        if (region !== null && !UUID_REGEX.test(region)) {
+            throw new Error('Query parameter "region" must be a valid UUID');
+        }
+        return new SearchParams(name, similarity, includePages, includeRegions, includeAka, region, order, limit, cursorEncoded);
+    }
+    /**
+     * Parses a boolean from a query string value. Returns defaultValue when value is undefined or empty.
+     * Throws when value is a non-empty string that is not "true", "false", "1", or "0" (case-insensitive).
+     */
+    static parseBoolean(value, defaultValue) {
+        if (value === undefined || value === '')
+            return defaultValue;
+        const lower = value.toLowerCase().trim();
+        if (lower === 'true' || lower === '1')
+            return true;
+        if (lower === 'false' || lower === '0')
+            return false;
+        throw new Error(`Query parameter value must be true, false, 1, or 0 (case-insensitive), got: ${JSON.stringify(value)}`);
+    }
+}
+exports.SearchParams = SearchParams;

package/dist/types/api/search/searchResults.d.ts

@@ -1,7 +1,9 @@
 import { PagePreview } from '../getRoutePreview/pagePreview';
 import { RegionPreview } from './regionPreview';
-export interface SearchResults {
+import { SearchCursor } from './searchCursor';
+export declare class SearchResults {
     results: (PagePreview | RegionPreview)[];
     nextCursor: string;
+    constructor(results: (PagePreview | RegionPreview)[], nextCursorCursor: SearchCursor | null);
 }
 //# sourceMappingURL=searchResults.d.ts.map

package/dist/types/api/search/searchResults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"searchResults.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/searchResults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,CAAC,WAAW,GAAG,aAAa,CAAC,EAAE,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;CACtB"}
+{"version":3,"file":"searchResults.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/searchResults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,qBAAa,aAAa;IACtB,OAAO,EAAE,CAAC,WAAW,GAAG,aAAa,CAAC,EAAE,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;gBAEP,OAAO,EAAE,CAAC,WAAW,GAAG,aAAa,CAAC,EAAE,EAAE,gBAAgB,EAAE,YAAY,GAAG,IAAI;CAI9F"}

package/dist/types/api/search/searchResults.js

@@ -1,2 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchResults = void 0;
+class SearchResults {
+    constructor(results, nextCursorCursor) {
+        this.results = results;
+        this.nextCursor = nextCursorCursor !== null ? nextCursorCursor.encodeBase64() : '';
+    }
+}
+exports.SearchResults = SearchResults;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ropegeo-common",
-    "version": "1.1.2",
+    "version": "1.1.4",
     "description": "Shared types and utilities for RopeGeo and WebScraper",
     "license": "ISC",
     "repository": {
@@ -16,6 +16,7 @@
     },
     "devDependencies": {
         "@types/jest": "^29.5.14",
+        "@types/node": "^22.10.0",
         "jest": "^30.2.0",
         "ts-jest": "^29.2.5",
         "typescript": "^5.9.3"