ropegeo-common 1.2.5 → 1.2.7

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { RopewikiImageView } from './types/api/getRopewikiPageView/ropewiki
 export type { RopewikiBetaSectionView } from './types/api/getRopewikiPageView/ropewikiBetaSectionView';
 export type { RopewikiPageView } from './types/api/getRopewikiPageView/ropewikiPageView';
 export { Cursor, CursorType } from './types/cursors/cursor';
+export { CursorPaginationParams } from './types/params/cursorPaginationParams';
+export { CursorPaginationResults, type CursorPaginationResponseParsed, ResultType, } from './types/results/cursorPaginationResults';
 export { SearchCursor } from './types/cursors/searchCursor';
 export type { SearchCursorType } from './types/cursors/searchCursor';
 export { SearchParams } from './types/api/search/searchParams';

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,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,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,MAAM,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sDAAsD,CAAC;AAC1F,YAAY,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,4BAA4B,EAAE,MAAM,oEAAoE,CAAC;AAClH,OAAO,EAAE,4BAA4B,EAAE,MAAM,oEAAoE,CAAC;AAClH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,6DAA6D,CAAC;AACtG,YAAY,EAAE,0BAA0B,EAAE,MAAM,6DAA6D,CAAC;AAC9G,OAAO,EAAE,0BAA0B,EAAE,MAAM,gEAAgE,CAAC;AAC5G,OAAO,EAAE,0BAA0B,EAAE,MAAM,gEAAgE,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,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,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,MAAM,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EACH,uBAAuB,EACvB,KAAK,8BAA8B,EACnC,UAAU,GACb,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sDAAsD,CAAC;AAC1F,YAAY,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,4BAA4B,EAAE,MAAM,oEAAoE,CAAC;AAClH,OAAO,EAAE,4BAA4B,EAAE,MAAM,oEAAoE,CAAC;AAClH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,6DAA6D,CAAC;AACtG,YAAY,EAAE,0BAA0B,EAAE,MAAM,6DAA6D,CAAC;AAC9G,OAAO,EAAE,0BAA0B,EAAE,MAAM,gEAAgE,CAAC;AAC5G,OAAO,EAAE,0BAA0B,EAAE,MAAM,gEAAgE,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RopewikiRegionImagesResult = exports.RopewikiRegionImagesParams = exports.RopewikiRegionImageView = exports.RegionImagesCursor = exports.RopewikiRegionPreviewsResult = exports.RopewikiRegionPreviewsParams = exports.RegionPreviewsCursor = exports.RopewikiRegionView = exports.SearchResults = exports.SearchParams = exports.SearchCursor = exports.CursorType = exports.Cursor = exports.RoutesParams = exports.RoutesGeojson = exports.RouteType = exports.Route = exports.RegionPreview = exports.PagePreview = exports.PreviewType = exports.Preview = exports.PermitStatus = exports.DifficultyWater = exports.DifficultyTime = exports.DifficultyTechnical = exports.DifficultyRisk = exports.Difficulty = exports.PageDataSource = void 0;
+exports.RopewikiRegionImagesResult = exports.RopewikiRegionImagesParams = exports.RopewikiRegionImageView = exports.RegionImagesCursor = exports.RopewikiRegionPreviewsResult = exports.RopewikiRegionPreviewsParams = exports.RegionPreviewsCursor = exports.RopewikiRegionView = exports.SearchResults = exports.SearchParams = exports.SearchCursor = exports.ResultType = exports.CursorPaginationResults = exports.CursorPaginationParams = exports.CursorType = exports.Cursor = exports.RoutesParams = exports.RoutesGeojson = exports.RouteType = exports.Route = exports.RegionPreview = exports.PagePreview = exports.PreviewType = exports.Preview = 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");
@@ -28,6 +28,11 @@ Object.defineProperty(exports, "RoutesParams", { enumerable: true, get: function
 var cursor_1 = require("./types/cursors/cursor");
 Object.defineProperty(exports, "Cursor", { enumerable: true, get: function () { return cursor_1.Cursor; } });
 Object.defineProperty(exports, "CursorType", { enumerable: true, get: function () { return cursor_1.CursorType; } });
+var cursorPaginationParams_1 = require("./types/params/cursorPaginationParams");
+Object.defineProperty(exports, "CursorPaginationParams", { enumerable: true, get: function () { return cursorPaginationParams_1.CursorPaginationParams; } });
+var cursorPaginationResults_1 = require("./types/results/cursorPaginationResults");
+Object.defineProperty(exports, "CursorPaginationResults", { enumerable: true, get: function () { return cursorPaginationResults_1.CursorPaginationResults; } });
+Object.defineProperty(exports, "ResultType", { enumerable: true, get: function () { return cursorPaginationResults_1.ResultType; } });
 var searchCursor_1 = require("./types/cursors/searchCursor");
 Object.defineProperty(exports, "SearchCursor", { enumerable: true, get: function () { return searchCursor_1.SearchCursor; } });
 var searchParams_1 = require("./types/api/search/searchParams");

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImageView.d.ts

@@ -21,5 +21,11 @@ export declare class RopewikiRegionImageView {
     externalLink: string;
     caption: string | undefined;
     constructor(row: RopewikiRegionImageViewRow);
+    /**
+     * Validates result has image view fields and applies RopewikiRegionImageView.prototype.
+     */
+    static fromResult(result: unknown): RopewikiRegionImageView;
+    private static assertString;
+    private static assertOptionalString;
 }
 //# sourceMappingURL=ropewikiRegionImageView.d.ts.map

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImageView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ropewikiRegionImageView.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionImages/ropewikiRegionImageView.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEhB,GAAG,EAAE,0BAA0B;CAQ9C"}
+{"version":3,"file":"ropewikiRegionImageView.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionImages/ropewikiRegionImageView.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEhB,GAAG,EAAE,0BAA0B;IAS3C;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,uBAAuB;IAe3D,OAAO,CAAC,MAAM,CAAC,YAAY;IAS3B,OAAO,CAAC,MAAM,CAAC,oBAAoB;CAYtC"}

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImageView.js

@@ -13,5 +13,36 @@ class RopewikiRegionImageView {
         this.externalLink = row.linkUrl;
         this.caption = row.caption ?? undefined;
     }
+    /**
+     * Validates result has image view fields and applies RopewikiRegionImageView.prototype.
+     */
+    static fromResult(result) {
+        if (result == null || typeof result !== 'object') {
+            throw new Error('RopewikiRegionImageView result must be an object');
+        }
+        const r = result;
+        RopewikiRegionImageView.assertString(r, 'id');
+        RopewikiRegionImageView.assertString(r, 'pageId');
+        RopewikiRegionImageView.assertString(r, 'pageName');
+        RopewikiRegionImageView.assertString(r, 'url');
+        RopewikiRegionImageView.assertString(r, 'externalLink');
+        RopewikiRegionImageView.assertOptionalString(r, 'caption');
+        Object.setPrototypeOf(r, RopewikiRegionImageView.prototype);
+        return r;
+    }
+    static assertString(obj, key) {
+        const v = obj[key];
+        if (typeof v !== 'string') {
+            throw new Error(`RopewikiRegionImageView.${key} must be a string, got: ${typeof v}`);
+        }
+    }
+    static assertOptionalString(obj, key) {
+        const v = obj[key];
+        if (v !== null &&
+            v !== undefined &&
+            typeof v !== 'string') {
+            throw new Error(`RopewikiRegionImageView.${key} must be string or undefined, got: ${typeof v}`);
+        }
+    }
 }
 exports.RopewikiRegionImageView = RopewikiRegionImageView;

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImagesParams.d.ts

@@ -1,18 +1,13 @@
+import { CursorPaginationParams } from '../../params/cursorPaginationParams';
 import { RegionImagesCursor } from '../../cursors/regionImagesCursor';
 /**
  * Validated params for getRopewikiRegionImages (GET /ropewiki/region/{id}/images).
  * Cursor is stored decoded (RegionImagesCursor | null).
  * The constructor accepts an encoded cursor string and decodes it.
  */
-export declare class RopewikiRegionImagesParams {
-    readonly limit: number;
-    readonly cursor: RegionImagesCursor | null;
-    constructor(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>;
+export declare class RopewikiRegionImagesParams extends CursorPaginationParams<RegionImagesCursor> {
+    constructor(limit: number, cursorEncoded?: string);
+    withCursor(cursorEncoded: string | null): RopewikiRegionImagesParams;
     /**
      * Parses query string parameters and returns validated params.
      * Validation is performed by the constructor.

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImagesParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ropewikiRegionImagesParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionImages/ropewikiRegionImagesParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAItE;;;;GAIG;AACH,qBAAa,0BAA0B;IACnC,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;gBAEtC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IA0BvD;;;OAGG;IACH,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAU7C;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,0BAA0B;CAOhC"}
+{"version":3,"file":"ropewikiRegionImagesParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionImages/ropewikiRegionImagesParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAItE;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,sBAAsB,CAAC,kBAAkB,CAAC;gBAC1E,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM;IAsBjD,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,0BAA0B;IAOpE;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,0BAA0B;CAOhC"}

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImagesParams.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RopewikiRegionImagesParams = void 0;
+const cursorPaginationParams_1 = require("../../params/cursorPaginationParams");
 const regionImagesCursor_1 = require("../../cursors/regionImagesCursor");
 const DEFAULT_LIMIT = 20;
 /**
@@ -8,7 +9,7 @@ const DEFAULT_LIMIT = 20;
  * Cursor is stored decoded (RegionImagesCursor | null).
  * The constructor accepts an encoded cursor string and decodes it.
  */
-class RopewikiRegionImagesParams {
+class RopewikiRegionImagesParams extends cursorPaginationParams_1.CursorPaginationParams {
     constructor(limit, cursorEncoded) {
         const limitNum = Number(limit);
         if (Number.isNaN(limitNum) ||
@@ -16,31 +17,17 @@ class RopewikiRegionImagesParams {
             limitNum < 1) {
             throw new Error('Query parameter "limit" must be a whole number greater than 0');
         }
-        this.limit = limit;
-        if (cursorEncoded === null || cursorEncoded === '') {
-            this.cursor = null;
-        }
-        else {
-            try {
-                this.cursor = regionImagesCursor_1.RegionImagesCursor.decodeBase64(cursorEncoded);
-            }
-            catch {
-                throw new Error('Invalid or malformed query parameter: cursor');
-            }
+        const cursorNorm = cursorEncoded === undefined || cursorEncoded === null || cursorEncoded === ''
+            ? null
+            : cursorEncoded;
+        let cursor = null;
+        if (cursorNorm !== null) {
+            cursor = regionImagesCursor_1.RegionImagesCursor.decodeBase64(cursorNorm);
         }
+        super(limitNum, cursor);
     }
-    /**
-     * Returns an object suitable for use as query string parameters.
-     * Cursor is encoded for the query string.
-     */
-    toQueryStringParams() {
-        const params = {
-            limit: String(this.limit),
-        };
-        if (this.cursor !== null) {
-            params.cursor = this.cursor.encodeBase64();
-        }
-        return params;
+    withCursor(cursorEncoded) {
+        return new RopewikiRegionImagesParams(this.limit, cursorEncoded === null || cursorEncoded === '' ? undefined : cursorEncoded);
     }
     /**
      * Parses query string parameters and returns validated params.
@@ -50,7 +37,7 @@ class RopewikiRegionImagesParams {
         const limitParam = q.limit ?? q.Limit ?? '';
         const limit = limitParam === '' ? DEFAULT_LIMIT : Number(limitParam);
         const cursorRaw = (q.cursor ?? q.Cursor ?? '').trim();
-        const cursorEncoded = cursorRaw === '' ? null : cursorRaw;
+        const cursorEncoded = cursorRaw === '' ? undefined : cursorRaw;
         return new RopewikiRegionImagesParams(limit, cursorEncoded);
     }
 }

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImagesResult.d.ts

@@ -1,11 +1,15 @@
-import type { RopewikiRegionImageView } from './ropewikiRegionImageView';
+import { RopewikiRegionImageView } from './ropewikiRegionImageView';
 import { RegionImagesCursor } from '../../cursors/regionImagesCursor';
+import { CursorPaginationResults, type CursorPaginationResponseParsed } from '../../results/cursorPaginationResults';
 /**
  * Result of getRopewikiRegionImages (GET /ropewiki/region/{id}/images).
  */
-export declare class RopewikiRegionImagesResult {
-    results: RopewikiRegionImageView[];
-    nextCursor: string | null;
-    constructor(results: RopewikiRegionImageView[], nextCursor: RegionImagesCursor | null);
+export declare class RopewikiRegionImagesResult extends CursorPaginationResults<RopewikiRegionImageView> {
+    constructor(results: RopewikiRegionImageView[], nextCursor: RegionImagesCursor | string | null);
+    /**
+     * Build from validated { results, nextCursor }. Decodes nextCursor to ensure valid.
+     * Each result is validated via RopewikiRegionImageView.fromResult.
+     */
+    static fromResponseBody(body: CursorPaginationResponseParsed): RopewikiRegionImagesResult;
 }
 //# sourceMappingURL=ropewikiRegionImagesResult.d.ts.map

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImagesResult.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ropewikiRegionImagesResult.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionImages/ropewikiRegionImagesResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE;;GAEG;AACH,qBAAa,0BAA0B;IACnC,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;gBAGtB,OAAO,EAAE,uBAAuB,EAAE,EAClC,UAAU,EAAE,kBAAkB,GAAG,IAAI;CAK5C"}
+{"version":3,"file":"ropewikiRegionImagesResult.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionImages/ropewikiRegionImagesResult.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EACH,uBAAuB,EACvB,KAAK,8BAA8B,EAEtC,MAAM,uCAAuC,CAAC;AAE/C;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,uBAAuB,CAAC,uBAAuB,CAAC;gBAExF,OAAO,EAAE,uBAAuB,EAAE,EAClC,UAAU,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI;IAWlD;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CACnB,IAAI,EAAE,8BAA8B,GACrC,0BAA0B;CAQhC"}

package/dist/types/api/getRopewikiRegionImages/ropewikiRegionImagesResult.js

@@ -1,13 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RopewikiRegionImagesResult = void 0;
+const ropewikiRegionImageView_1 = require("./ropewikiRegionImageView");
+const regionImagesCursor_1 = require("../../cursors/regionImagesCursor");
+const cursorPaginationResults_1 = require("../../results/cursorPaginationResults");
 /**
  * Result of getRopewikiRegionImages (GET /ropewiki/region/{id}/images).
  */
-class RopewikiRegionImagesResult {
+class RopewikiRegionImagesResult extends cursorPaginationResults_1.CursorPaginationResults {
     constructor(results, nextCursor) {
-        this.results = results;
-        this.nextCursor = nextCursor !== null ? nextCursor.encodeBase64() : null;
+        const nextCursorStr = nextCursor === null
+            ? null
+            : typeof nextCursor === 'string'
+                ? nextCursor
+                : nextCursor.encodeBase64();
+        super(results, nextCursorStr, cursorPaginationResults_1.ResultType.RopewikiRegionImages);
+    }
+    /**
+     * Build from validated { results, nextCursor }. Decodes nextCursor to ensure valid.
+     * Each result is validated via RopewikiRegionImageView.fromResult.
+     */
+    static fromResponseBody(body) {
+        const { results: resultsRaw, nextCursor } = body;
+        if (nextCursor != null) {
+            regionImagesCursor_1.RegionImagesCursor.decodeBase64(nextCursor);
+        }
+        const results = resultsRaw.map((r) => ropewikiRegionImageView_1.RopewikiRegionImageView.fromResult(r));
+        return new RopewikiRegionImagesResult(results, nextCursor);
     }
 }
 exports.RopewikiRegionImagesResult = RopewikiRegionImagesResult;

package/dist/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsParams.d.ts

@@ -1,18 +1,13 @@
+import { CursorPaginationParams } from '../../params/cursorPaginationParams';
 import { RegionPreviewsCursor } from '../../cursors/regionPreviewsCursor';
 /**
  * Validated params for getRopewikiRegionPreviews (GET /ropewiki/region/{id}/previews).
  * Cursor is stored decoded (RegionPreviewsCursor | null).
  * The constructor accepts an encoded cursor string and decodes it.
  */
-export declare class RopewikiRegionPreviewsParams {
-    readonly limit: number;
-    readonly cursor: RegionPreviewsCursor | null;
-    constructor(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>;
+export declare class RopewikiRegionPreviewsParams extends CursorPaginationParams<RegionPreviewsCursor> {
+    constructor(limit: number, cursorEncoded?: string);
+    withCursor(cursorEncoded: string | null): RopewikiRegionPreviewsParams;
     /**
      * Parses query string parameters and returns validated params.
      * Validation is performed by the constructor.

package/dist/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ropewikiRegionPreviewsParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAI1E;;;;GAIG;AACH,qBAAa,4BAA4B;IACrC,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;gBAExC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IA0BvD;;;OAGG;IACH,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAU7C;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,4BAA4B;CAOlC"}
+{"version":3,"file":"ropewikiRegionPreviewsParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAI1E;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,sBAAsB,CAAC,oBAAoB,CAAC;gBAC9E,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM;IAsBjD,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,4BAA4B;IAOtE;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,4BAA4B;CAOlC"}

package/dist/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsParams.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RopewikiRegionPreviewsParams = void 0;
+const cursorPaginationParams_1 = require("../../params/cursorPaginationParams");
 const regionPreviewsCursor_1 = require("../../cursors/regionPreviewsCursor");
 const DEFAULT_LIMIT = 20;
 /**
@@ -8,7 +9,7 @@ const DEFAULT_LIMIT = 20;
  * Cursor is stored decoded (RegionPreviewsCursor | null).
  * The constructor accepts an encoded cursor string and decodes it.
  */
-class RopewikiRegionPreviewsParams {
+class RopewikiRegionPreviewsParams extends cursorPaginationParams_1.CursorPaginationParams {
     constructor(limit, cursorEncoded) {
         const limitNum = Number(limit);
         if (Number.isNaN(limitNum) ||
@@ -16,31 +17,17 @@ class RopewikiRegionPreviewsParams {
             limitNum < 1) {
             throw new Error('Query parameter "limit" must be a whole number greater than 0');
         }
-        this.limit = limit;
-        if (cursorEncoded === null || cursorEncoded === '') {
-            this.cursor = null;
-        }
-        else {
-            try {
-                this.cursor = regionPreviewsCursor_1.RegionPreviewsCursor.decodeBase64(cursorEncoded);
-            }
-            catch {
-                throw new Error('Invalid or malformed query parameter: cursor');
-            }
+        const cursorNorm = cursorEncoded === undefined || cursorEncoded === null || cursorEncoded === ''
+            ? null
+            : cursorEncoded;
+        let cursor = null;
+        if (cursorNorm !== null) {
+            cursor = regionPreviewsCursor_1.RegionPreviewsCursor.decodeBase64(cursorNorm);
         }
+        super(limitNum, cursor);
     }
-    /**
-     * Returns an object suitable for use as query string parameters.
-     * Cursor is encoded for the query string.
-     */
-    toQueryStringParams() {
-        const params = {
-            limit: String(this.limit),
-        };
-        if (this.cursor !== null) {
-            params.cursor = this.cursor.encodeBase64();
-        }
-        return params;
+    withCursor(cursorEncoded) {
+        return new RopewikiRegionPreviewsParams(this.limit, cursorEncoded === null || cursorEncoded === '' ? undefined : cursorEncoded);
     }
     /**
      * Parses query string parameters and returns validated params.
@@ -50,7 +37,7 @@ class RopewikiRegionPreviewsParams {
         const limitParam = q.limit ?? q.Limit ?? '';
         const limit = limitParam === '' ? DEFAULT_LIMIT : Number(limitParam);
         const cursorRaw = (q.cursor ?? q.Cursor ?? '').trim();
-        const cursorEncoded = cursorRaw === '' ? null : cursorRaw;
+        const cursorEncoded = cursorRaw === '' ? undefined : cursorRaw;
         return new RopewikiRegionPreviewsParams(limit, cursorEncoded);
     }
 }

package/dist/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsResult.d.ts

@@ -1,11 +1,15 @@
 import { Preview } from '../../previews/preview';
 import { RegionPreviewsCursor } from '../../cursors/regionPreviewsCursor';
+import { CursorPaginationResults, type CursorPaginationResponseParsed } from '../../results/cursorPaginationResults';
 /**
  * Result of getRopewikiRegionPreviews (GET /ropewiki/region/{id}/previews).
  */
-export declare class RopewikiRegionPreviewsResult {
-    results: Preview[];
-    nextCursor: string | null;
-    constructor(results: Preview[], nextCursor: RegionPreviewsCursor | null);
+export declare class RopewikiRegionPreviewsResult extends CursorPaginationResults<Preview> {
+    constructor(results: Preview[], nextCursor: RegionPreviewsCursor | string | null);
+    /**
+     * Build from validated { results, nextCursor }. Decodes nextCursor to ensure valid.
+     * Each result is validated via Preview.fromResult.
+     */
+    static fromResponseBody(body: CursorPaginationResponseParsed): RopewikiRegionPreviewsResult;
 }
 //# sourceMappingURL=ropewikiRegionPreviewsResult.d.ts.map

package/dist/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsResult.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ropewikiRegionPreviewsResult.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsResult.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAE1E;;GAEG;AACH,qBAAa,4BAA4B;IACrC,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;gBAGtB,OAAO,EAAE,OAAO,EAAE,EAClB,UAAU,EAAE,oBAAoB,GAAG,IAAI;CAK9C"}
+{"version":3,"file":"ropewikiRegionPreviewsResult.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsResult.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EACH,uBAAuB,EACvB,KAAK,8BAA8B,EAEtC,MAAM,uCAAuC,CAAC;AAE/C;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,uBAAuB,CAAC,OAAO,CAAC;gBAE1E,OAAO,EAAE,OAAO,EAAE,EAClB,UAAU,EAAE,oBAAoB,GAAG,MAAM,GAAG,IAAI;IAWpD;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CACnB,IAAI,EAAE,8BAA8B,GACrC,4BAA4B;CAQlC"}

package/dist/types/api/getRopewikiRegionPreviews/ropewikiRegionPreviewsResult.js

@@ -1,13 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RopewikiRegionPreviewsResult = void 0;
+const preview_1 = require("../../previews/preview");
+const regionPreviewsCursor_1 = require("../../cursors/regionPreviewsCursor");
+const cursorPaginationResults_1 = require("../../results/cursorPaginationResults");
 /**
  * Result of getRopewikiRegionPreviews (GET /ropewiki/region/{id}/previews).
  */
-class RopewikiRegionPreviewsResult {
+class RopewikiRegionPreviewsResult extends cursorPaginationResults_1.CursorPaginationResults {
     constructor(results, nextCursor) {
-        this.results = results;
-        this.nextCursor = nextCursor !== null ? nextCursor.encodeBase64() : null;
+        const nextCursorStr = nextCursor === null
+            ? null
+            : typeof nextCursor === 'string'
+                ? nextCursor
+                : nextCursor.encodeBase64();
+        super(results, nextCursorStr, cursorPaginationResults_1.ResultType.RopewikiRegionPreviews);
+    }
+    /**
+     * Build from validated { results, nextCursor }. Decodes nextCursor to ensure valid.
+     * Each result is validated via Preview.fromResult.
+     */
+    static fromResponseBody(body) {
+        const { results: resultsRaw, nextCursor } = body;
+        if (nextCursor != null) {
+            regionPreviewsCursor_1.RegionPreviewsCursor.decodeBase64(nextCursor);
+        }
+        const results = resultsRaw.map((r) => preview_1.Preview.fromResult(r));
+        return new RopewikiRegionPreviewsResult(results, nextCursor);
     }
 }
 exports.RopewikiRegionPreviewsResult = RopewikiRegionPreviewsResult;

package/dist/types/api/getRoutes/routesParams.d.ts

@@ -11,9 +11,9 @@ export declare class RoutesParams {
     } | null;
     constructor(source: PageDataSource | undefined, regionId: string | undefined);
     /**
-     * Returns an object suitable for use as query string parameters.
+     * Returns a URL-encoded query string.
      */
-    toQueryStringParams(): Record<string, string>;
+    toQueryString(): string;
     /**
      * Parses query string parameters and returns validated params.
      * Validation is performed by the constructor.

package/dist/types/api/getRoutes/routesParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routesParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRoutes/routesParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;GAGG;AACH,qBAAa,YAAY;IACrB,sEAAsE;IACtE,SAAgB,MAAM,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;gBAE1D,MAAM,EAAE,cAAc,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS;IAiB5E;;OAEG;IACH,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAU7C;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,YAAY;IAWf,OAAO,CAAC,MAAM,CAAC,WAAW;CAQ7B"}
+{"version":3,"file":"routesParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/getRoutes/routesParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;GAGG;AACH,qBAAa,YAAY;IACrB,sEAAsE;IACtE,SAAgB,MAAM,EAAE;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;gBAE1D,MAAM,EAAE,cAAc,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS;IAiB5E;;OAEG;IACH,aAAa,IAAI,MAAM;IAUvB;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,YAAY;IAWf,OAAO,CAAC,MAAM,CAAC,WAAW;CAQ7B"}

package/dist/types/api/getRoutes/routesParams.js

@@ -21,16 +21,16 @@ class RoutesParams {
                 : null;
     }
     /**
-     * Returns an object suitable for use as query string parameters.
+     * Returns a URL-encoded query string.
      */
-    toQueryStringParams() {
+    toQueryString() {
         if (this.region === null) {
-            return {};
+            return '';
         }
-        return {
+        return new URLSearchParams({
             source: this.region.source,
             region: this.region.id,
-        };
+        }).toString();
     }
     /**
      * Parses query string parameters and returns validated params.

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

@@ -1,10 +1,11 @@
+import { CursorPaginationParams } from '../../params/cursorPaginationParams';
 import { SearchCursor } from '../../cursors/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 {
+export declare class SearchParams extends CursorPaginationParams<SearchCursor> {
     readonly name: string;
     readonly similarityThreshold: number;
     readonly includePages: boolean;
@@ -12,14 +13,12 @@ export declare class SearchParams {
     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);
+    constructor(name: string, similarityThreshold: number, includePages: boolean, includeRegions: boolean, includeAka: boolean, regionId: string | null, order: SearchOrder, limit: number, cursorEncoded?: string);
     /**
-     * Returns an object suitable for use as query string parameters.
-     * Cursor is encoded for the query string.
+     * Returns a URL-encoded query string. Cursor is encoded for the query string.
      */
-    toQueryStringParams(): Record<string, string>;
+    toQueryString(): string;
+    withCursor(cursorEncoded: string | null): SearchParams;
     /**
      * Parses query string parameters and returns validated params.
      * Validation is performed by the constructor.

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

@@ -1 +1 @@
-{"version":3,"file":"searchParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/searchParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,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;IA2Cf;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAY9B"}
+{"version":3,"file":"searchParams.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/searchParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,SAAS,CAAC;AAOnD;;;GAGG;AACH,qBAAa,YAAa,SAAQ,sBAAsB,CAAC,YAAY,CAAC;IAClE,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;gBAG/B,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,CAAC,EAAE,MAAM;IAkE1B;;OAEG;IACH,aAAa,IAAI,MAAM;IAmBvB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY;IActD;;;OAGG;IACH,MAAM,CAAC,qBAAqB,CACxB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,YAAY;IA2Cf;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAY9B"}

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchParams = void 0;
+const cursorPaginationParams_1 = require("../../params/cursorPaginationParams");
 const searchCursor_1 = require("../../cursors/searchCursor");
 const DEFAULT_LIMIT = 20;
 /** UUID v4 format: 8-4-4-4-12 hex digits */
@@ -9,7 +10,7 @@ const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12
  * Validated search parameters. Cursor is stored decoded (SearchCursor | null).
  * The constructor accepts an encoded cursor string and decodes it.
  */
-class SearchParams {
+class SearchParams extends cursorPaginationParams_1.CursorPaginationParams {
     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');
@@ -39,6 +40,14 @@ class SearchParams {
         if (trimmedRegionId !== null && !UUID_REGEX.test(trimmedRegionId)) {
             throw new Error('Query parameter "region" must be a valid UUID');
         }
+        const cursorNorm = cursorEncoded === undefined || cursorEncoded === null || cursorEncoded === ''
+            ? null
+            : cursorEncoded;
+        let cursor = null;
+        if (cursorNorm !== null) {
+            cursor = searchCursor_1.SearchCursor.decodeBase64(cursorNorm);
+        }
+        super(limitNum, cursor);
         this.name = name;
         this.similarityThreshold = similarityThreshold;
         this.includePages = includePages;
@@ -46,24 +55,11 @@ class SearchParams {
         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.
+     * Returns a URL-encoded query string. Cursor is encoded for the query string.
      */
-    toQueryStringParams() {
+    toQueryString() {
         const params = {
             name: this.name,
             similarity: String(this.similarityThreshold),
@@ -79,7 +75,10 @@ class SearchParams {
         if (this.cursor !== null) {
             params.cursor = this.cursor.encodeBase64();
         }
-        return params;
+        return new URLSearchParams(params).toString();
+    }
+    withCursor(cursorEncoded) {
+        return new SearchParams(this.name, this.similarityThreshold, this.includePages, this.includeRegions, this.includeAka, this.regionId, this.order, this.limit, cursorEncoded === null || cursorEncoded === '' ? undefined : cursorEncoded);
     }
     /**
      * Parses query string parameters and returns validated params.
@@ -90,7 +89,7 @@ class SearchParams {
         const limitParam = q.limit ?? q.Limit ?? '';
         const limit = limitParam === '' ? DEFAULT_LIMIT : Number(limitParam);
         const cursorRaw = (q.cursor ?? q.Cursor ?? '').trim();
-        const cursorEncoded = cursorRaw === '' ? null : cursorRaw;
+        const cursorEncoded = cursorRaw === '' ? undefined : cursorRaw;
         const similarityParam = q.similarity ?? q.Similarity ?? '';
         const similarity = similarityParam === '' ? 0.5 : Number(similarityParam);
         const orderParam = (q.order ?? q.Order ?? '').trim().toLowerCase();

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

@@ -1,8 +1,12 @@
 import { Preview } from '../../previews/preview';
 import { SearchCursor } from '../../cursors/searchCursor';
-export declare class SearchResults {
-    results: Preview[];
-    nextCursor: string | null;
-    constructor(results: Preview[], nextCursor: SearchCursor | null);
+import { CursorPaginationResults, type CursorPaginationResponseParsed } from '../../results/cursorPaginationResults';
+export declare class SearchResults extends CursorPaginationResults<Preview> {
+    constructor(results: Preview[], nextCursor: SearchCursor | string | null);
+    /**
+     * Build from validated { results, nextCursor }. Decodes nextCursor to ensure valid.
+     * Each result is validated via Preview.fromResult.
+     */
+    static fromResponseBody(body: CursorPaginationResponseParsed): SearchResults;
 }
 //# 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,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,qBAAa,aAAa;IACtB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEd,OAAO,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,GAAG,IAAI;CAIlE"}
+{"version":3,"file":"searchResults.d.ts","sourceRoot":"","sources":["../../../../src/types/api/search/searchResults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EACH,uBAAuB,EACvB,KAAK,8BAA8B,EAEtC,MAAM,uCAAuC,CAAC;AAE/C,qBAAa,aAAc,SAAQ,uBAAuB,CAAC,OAAO,CAAC;gBACnD,OAAO,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI;IAQxE;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,8BAA8B,GAAG,aAAa;CAQ/E"}

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

@@ -1,10 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchResults = void 0;
-class SearchResults {
+const preview_1 = require("../../previews/preview");
+const searchCursor_1 = require("../../cursors/searchCursor");
+const cursorPaginationResults_1 = require("../../results/cursorPaginationResults");
+class SearchResults extends cursorPaginationResults_1.CursorPaginationResults {
     constructor(results, nextCursor) {
-        this.results = results;
-        this.nextCursor = nextCursor !== null ? nextCursor.encodeBase64() : null;
+        const nextCursorStr = nextCursor === null || typeof nextCursor === 'string'
+            ? nextCursor
+            : nextCursor.encodeBase64();
+        super(results, nextCursorStr, cursorPaginationResults_1.ResultType.Search);
+    }
+    /**
+     * Build from validated { results, nextCursor }. Decodes nextCursor to ensure valid.
+     * Each result is validated via Preview.fromResult.
+     */
+    static fromResponseBody(body) {
+        const { results: resultsRaw, nextCursor } = body;
+        if (nextCursor != null) {
+            searchCursor_1.SearchCursor.decodeBase64(nextCursor);
+        }
+        const results = resultsRaw.map((r) => preview_1.Preview.fromResult(r));
+        return new SearchResults(results, nextCursor);
     }
 }
 exports.SearchResults = SearchResults;

package/dist/types/params/cursorPaginationParams.d.ts

@@ -0,0 +1,21 @@
+import { Cursor } from '../cursors/cursor';
+/**
+ * Abstract base for params that paginate with a limit and an optional cursor.
+ * Subclasses specify their own cursor type via the generic.
+ */
+export declare abstract class CursorPaginationParams<C extends Cursor = Cursor> {
+    readonly limit: number;
+    readonly cursor: C | null;
+    constructor(limit: number, cursor: C | null);
+    /**
+     * Returns a URL-encoded query string (e.g. "limit=10" or "limit=10&cursor=...").
+     * Default implementation uses limit and cursor; subclasses with extra params override.
+     */
+    toQueryString(): string;
+    /**
+     * Returns a new params instance with the given cursor (for the next page).
+     * Each subclass implements this.
+     */
+    abstract withCursor(cursorEncoded: string | null): CursorPaginationParams;
+}
+//# sourceMappingURL=cursorPaginationParams.d.ts.map

package/dist/types/params/cursorPaginationParams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursorPaginationParams.d.ts","sourceRoot":"","sources":["../../../src/types/params/cursorPaginationParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;GAGG;AACH,8BAAsB,sBAAsB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;aAE9C,KAAK,EAAE,MAAM;aACb,MAAM,EAAE,CAAC,GAAG,IAAI;gBADhB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,GAAG,IAAI;IAGpC;;;OAGG;IACH,aAAa,IAAI,MAAM;IAUvB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,sBAAsB;CAC5E"}

package/dist/types/params/cursorPaginationParams.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CursorPaginationParams = void 0;
+/**
+ * Abstract base for params that paginate with a limit and an optional cursor.
+ * Subclasses specify their own cursor type via the generic.
+ */
+class CursorPaginationParams {
+    constructor(limit, cursor) {
+        this.limit = limit;
+        this.cursor = cursor;
+    }
+    /**
+     * Returns a URL-encoded query string (e.g. "limit=10" or "limit=10&cursor=...").
+     * Default implementation uses limit and cursor; subclasses with extra params override.
+     */
+    toQueryString() {
+        const params = {
+            limit: String(this.limit),
+        };
+        if (this.cursor != null) {
+            params.cursor = this.cursor.encodeBase64();
+        }
+        return new URLSearchParams(params).toString();
+    }
+}
+exports.CursorPaginationParams = CursorPaginationParams;

package/dist/types/previews/pagePreview.d.ts

@@ -57,6 +57,18 @@ export declare class PagePreview extends Preview {
      * Builds a PagePreview from a getRopewikiPagePreview query row.
      */
     static fromDbRow(row: GetRopewikiPagePreviewRow, mapData: string | null, regions?: string[], aka?: string[]): PagePreview;
+    /**
+     * Validates result has page preview fields and applies PagePreview.prototype.
+     * Expects difficulty as plain object with technical, water, time, risk (optional).
+     */
+    static fromResult(result: unknown): PagePreview;
+    private static assertString;
+    private static assertNullableString;
+    private static assertNullableNumber;
+    private static assertSource;
+    private static assertStringArray;
+    private static assertDifficulty;
+    private static assertPermit;
     private static parsePermit;
 }
 //# sourceMappingURL=pagePreview.d.ts.map

package/dist/types/previews/pagePreview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagePreview.d.ts","sourceRoot":"","sources":["../../../src/types/previews/pagePreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEjD;;;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,WAAY,SAAQ,OAAO;IACpC,sDAAsD;IACtD,QAAQ,CAAC,WAAW,oBAAoB;IACxC,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,gCAAgC;IAChC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,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,GAAG,EAAE,MAAM,EAAE,EACb,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,MAAM,EAAE,YAAY,GAAG,IAAI;IAiB/B;;OAEG;IACH,MAAM,CAAC,SAAS,CACZ,GAAG,EAAE,yBAAyB,EAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,GAAG,CAAC,EAAE,MAAM,EAAE,GACf,WAAW;IAuBd,OAAO,CAAC,MAAM,CAAC,WAAW;CAK7B"}
+{"version":3,"file":"pagePreview.d.ts","sourceRoot":"","sources":["../../../src/types/previews/pagePreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEjD;;;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,WAAY,SAAQ,OAAO;IACpC,sDAAsD;IACtD,QAAQ,CAAC,WAAW,oBAAoB;IACxC,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,gCAAgC;IAChC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,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,GAAG,EAAE,MAAM,EAAE,EACb,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,MAAM,EAAE,YAAY,GAAG,IAAI;IAiB/B;;OAEG;IACH,MAAM,CAAC,SAAS,CACZ,GAAG,EAAE,yBAAyB,EAC9B,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,GAAG,CAAC,EAAE,MAAM,EAAE,GACf,WAAW;IAuBd;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW;IA4B/C,OAAO,CAAC,MAAM,CAAC,YAAY;IAO3B,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAOnC,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAOnC,OAAO,CAAC,MAAM,CAAC,YAAY;IAS3B,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAYhC,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAoC/B,OAAO,CAAC,MAAM,CAAC,YAAY;IAU3B,OAAO,CAAC,MAAM,CAAC,WAAW;CAK7B"}

package/dist/types/previews/pagePreview.js

@@ -34,6 +34,103 @@ class PagePreview extends preview_1.Preview {
         const difficulty = new difficulty_1.Difficulty(row.technicalRating, row.waterRating, row.timeRating, row.riskRating);
         return new PagePreview(row.pageId, pageDataSource_1.PageDataSource.Ropewiki, row.bannerFileUrl ?? null, row.quality != null ? Number(row.quality) : null, row.userVotes ?? null, row.title, regions ?? [row.regionName], aka ?? [], difficulty, mapData, row.url ?? null, PagePreview.parsePermit(row.permits));
     }
+    /**
+     * Validates result has page preview fields and applies PagePreview.prototype.
+     * Expects difficulty as plain object with technical, water, time, risk (optional).
+     */
+    static fromResult(result) {
+        if (result == null || typeof result !== 'object') {
+            throw new Error('PagePreview result must be an object');
+        }
+        const r = result;
+        PagePreview.assertString(r, 'id');
+        PagePreview.assertString(r, 'title');
+        PagePreview.assertSource(r, 'source');
+        PagePreview.assertStringArray(r, 'regions');
+        PagePreview.assertStringArray(r, 'aka');
+        PagePreview.assertDifficulty(r, 'difficulty');
+        PagePreview.assertNullableString(r, 'mapData');
+        PagePreview.assertNullableString(r, 'externalLink');
+        PagePreview.assertNullableString(r, 'imageUrl');
+        PagePreview.assertNullableNumber(r, 'rating');
+        PagePreview.assertNullableNumber(r, 'ratingCount');
+        PagePreview.assertPermit(r, 'permit');
+        const diff = r.difficulty;
+        r.difficulty = new difficulty_1.Difficulty(diff.technical, diff.water, diff.time, diff.risk);
+        Object.setPrototypeOf(r, PagePreview.prototype);
+        return r;
+    }
+    static assertString(obj, key) {
+        const v = obj[key];
+        if (typeof v !== 'string') {
+            throw new Error(`PagePreview.${key} must be a string, got: ${typeof v}`);
+        }
+    }
+    static assertNullableString(obj, key) {
+        const v = obj[key];
+        if (v !== null && v !== undefined && typeof v !== 'string') {
+            throw new Error(`PagePreview.${key} must be string or null, got: ${typeof v}`);
+        }
+    }
+    static assertNullableNumber(obj, key) {
+        const v = obj[key];
+        if (v !== null && v !== undefined && (typeof v !== 'number' || Number.isNaN(v))) {
+            throw new Error(`PagePreview.${key} must be number or null, got: ${typeof v}`);
+        }
+    }
+    static assertSource(obj, key) {
+        const v = obj[key];
+        if (v !== pageDataSource_1.PageDataSource.Ropewiki) {
+            throw new Error(`PagePreview.${key} must be PageDataSource, got: ${JSON.stringify(v)}`);
+        }
+    }
+    static assertStringArray(obj, key) {
+        const v = obj[key];
+        if (!Array.isArray(v)) {
+            throw new Error(`PagePreview.${key} must be an array, got: ${typeof v}`);
+        }
+        for (let i = 0; i < v.length; i++) {
+            if (typeof v[i] !== 'string') {
+                throw new Error(`PagePreview.${key}[${i}] must be a string`);
+            }
+        }
+    }
+    static assertDifficulty(obj, key) {
+        const v = obj[key];
+        if (v == null || typeof v !== 'object') {
+            throw new Error(`PagePreview.${key} must be an object`);
+        }
+        const d = v;
+        if (d.technical !== undefined &&
+            d.technical !== null &&
+            typeof d.technical !== 'string') {
+            throw new Error('PagePreview.difficulty.technical must be string or null');
+        }
+        if (d.water !== undefined &&
+            d.water !== null &&
+            typeof d.water !== 'string') {
+            throw new Error('PagePreview.difficulty.water must be string or null');
+        }
+        if (d.time !== undefined &&
+            d.time !== null &&
+            typeof d.time !== 'string') {
+            throw new Error('PagePreview.difficulty.time must be string or null');
+        }
+        if (d.risk !== undefined &&
+            d.risk !== null &&
+            typeof d.risk !== 'string') {
+            throw new Error('PagePreview.difficulty.risk must be string or null');
+        }
+    }
+    static assertPermit(obj, key) {
+        const v = obj[key];
+        if (v !== null && v !== undefined && typeof v !== 'string') {
+            throw new Error(`PagePreview.${key} must be string or null, got: ${typeof v}`);
+        }
+        if (v != null && !Object.values(permitStatus_1.PermitStatus).includes(v)) {
+            throw new Error(`PagePreview.${key} must be PermitStatus or null, got: ${JSON.stringify(v)}`);
+        }
+    }
     static parsePermit(value) {
         if (value == null || value === '')
             return null;

package/dist/types/previews/preview.d.ts

@@ -1,5 +1,5 @@
-import { PagePreview } from './pagePreview';
-import { RegionPreview } from './regionPreview';
+import type { PagePreview } from './pagePreview';
+import type { RegionPreview } from './regionPreview';
 export declare enum PreviewType {
     Page = "page",
     Region = "region"
@@ -13,5 +13,10 @@ export declare abstract class Preview {
     isPagePreview(): this is PagePreview;
     /** Type guard: narrows this to RegionPreview. */
     isRegionPreview(): this is RegionPreview;
+    /**
+     * Validates result has previewType and delegates to PagePreview.fromResult or
+     * RegionPreview.fromResult. Returns the same object with the appropriate prototype.
+     */
+    static fromResult(result: unknown): Preview;
 }
 //# sourceMappingURL=preview.d.ts.map

package/dist/types/previews/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/types/previews/preview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,oBAAY,WAAW;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CACpB;AAED;;GAEG;AACH,8BAAsB,OAAO;IACzB,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAE3C,+CAA+C;IAC/C,aAAa,IAAI,IAAI,IAAI,WAAW;IAIpC,iDAAiD;IACjD,eAAe,IAAI,IAAI,IAAI,aAAa;CAG3C"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/types/previews/preview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,oBAAY,WAAW;IACnB,IAAI,SAAS;IACb,MAAM,WAAW;CACpB;AAED;;GAEG;AACH,8BAAsB,OAAO;IACzB,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAE3C,+CAA+C;IAC/C,aAAa,IAAI,IAAI,IAAI,WAAW;IAIpC,iDAAiD;IACjD,eAAe,IAAI,IAAI,IAAI,aAAa;IAIxC;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;CAkB9C"}

package/dist/types/previews/preview.js

@@ -18,5 +18,25 @@ class Preview {
     isRegionPreview() {
         return this.previewType === PreviewType.Region;
     }
+    /**
+     * Validates result has previewType and delegates to PagePreview.fromResult or
+     * RegionPreview.fromResult. Returns the same object with the appropriate prototype.
+     */
+    static fromResult(result) {
+        if (result == null || typeof result !== 'object') {
+            throw new Error('Preview result must be an object');
+        }
+        const obj = result;
+        const previewType = obj.previewType;
+        if (previewType !== PreviewType.Page && previewType !== PreviewType.Region) {
+            throw new Error(`Preview result must have previewType "page" or "region", got: ${JSON.stringify(previewType)}`);
+        }
+        if (previewType === PreviewType.Page) {
+            const { PagePreview: PagePreviewClass } = require('./pagePreview');
+            return PagePreviewClass.fromResult(result);
+        }
+        const { RegionPreview: RegionPreviewClass } = require('./regionPreview');
+        return RegionPreviewClass.fromResult(result);
+    }
 }
 exports.Preview = Preview;

package/dist/types/previews/regionPreview.d.ts

@@ -10,5 +10,14 @@ export declare class RegionPreview extends Preview {
     imageUrl: string | null;
     source: PageDataSource;
     constructor(id: string, name: string, parents: string[], pageCount: number, regionCount: number, imageUrl: string | null, source: PageDataSource);
+    /**
+     * Validates result has region preview fields and applies RegionPreview.prototype.
+     */
+    static fromResult(result: unknown): RegionPreview;
+    private static assertString;
+    private static assertNullableString;
+    private static assertNumber;
+    private static assertStringArray;
+    private static assertSource;
 }
 //# sourceMappingURL=regionPreview.d.ts.map

package/dist/types/previews/regionPreview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regionPreview.d.ts","sourceRoot":"","sources":["../../../src/types/previews/regionPreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEjD,qBAAa,aAAc,SAAQ,OAAO;IACtC,QAAQ,CAAC,WAAW,sBAAsB;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,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,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,cAAc;CAW7B"}
+{"version":3,"file":"regionPreview.d.ts","sourceRoot":"","sources":["../../../src/types/previews/regionPreview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEjD,qBAAa,aAAc,SAAQ,OAAO;IACtC,QAAQ,CAAC,WAAW,sBAAsB;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,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,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,cAAc;IAY1B;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa;IAgBjD,OAAO,CAAC,MAAM,CAAC,YAAY;IAO3B,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAOnC,OAAO,CAAC,MAAM,CAAC,YAAY;IAO3B,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAYhC,OAAO,CAAC,MAAM,CAAC,YAAY;CAQ9B"}

package/dist/types/previews/regionPreview.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RegionPreview = void 0;
+const pageDataSource_1 = require("../pageDataSource");
 const preview_1 = require("./preview");
 class RegionPreview extends preview_1.Preview {
     constructor(id, name, parents, pageCount, regionCount, imageUrl, source) {
@@ -14,5 +15,58 @@ class RegionPreview extends preview_1.Preview {
         this.imageUrl = imageUrl;
         this.source = source;
     }
+    /**
+     * Validates result has region preview fields and applies RegionPreview.prototype.
+     */
+    static fromResult(result) {
+        if (result == null || typeof result !== 'object') {
+            throw new Error('RegionPreview result must be an object');
+        }
+        const r = result;
+        RegionPreview.assertString(r, 'id');
+        RegionPreview.assertString(r, 'name');
+        RegionPreview.assertStringArray(r, 'parents');
+        RegionPreview.assertNumber(r, 'pageCount');
+        RegionPreview.assertNumber(r, 'regionCount');
+        RegionPreview.assertNullableString(r, 'imageUrl');
+        RegionPreview.assertSource(r, 'source');
+        Object.setPrototypeOf(r, RegionPreview.prototype);
+        return r;
+    }
+    static assertString(obj, key) {
+        const v = obj[key];
+        if (typeof v !== 'string') {
+            throw new Error(`RegionPreview.${key} must be a string, got: ${typeof v}`);
+        }
+    }
+    static assertNullableString(obj, key) {
+        const v = obj[key];
+        if (v !== null && v !== undefined && typeof v !== 'string') {
+            throw new Error(`RegionPreview.${key} must be string or null, got: ${typeof v}`);
+        }
+    }
+    static assertNumber(obj, key) {
+        const v = obj[key];
+        if (typeof v !== 'number' || Number.isNaN(v)) {
+            throw new Error(`RegionPreview.${key} must be a number, got: ${typeof v}`);
+        }
+    }
+    static assertStringArray(obj, key) {
+        const v = obj[key];
+        if (!Array.isArray(v)) {
+            throw new Error(`RegionPreview.${key} must be an array, got: ${typeof v}`);
+        }
+        for (let i = 0; i < v.length; i++) {
+            if (typeof v[i] !== 'string') {
+                throw new Error(`RegionPreview.${key}[${i}] must be a string`);
+            }
+        }
+    }
+    static assertSource(obj, key) {
+        const v = obj[key];
+        if (v !== pageDataSource_1.PageDataSource.Ropewiki) {
+            throw new Error(`RegionPreview.${key} must be PageDataSource, got: ${JSON.stringify(v)}`);
+        }
+    }
 }
 exports.RegionPreview = RegionPreview;

package/dist/types/results/cursorPaginationResults.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Discriminator for cursor-paginated result types. Used in response body so
+ * CursorPaginationResults.fromResponseBody can route to the correct parser.
+ */
+export declare enum ResultType {
+    Search = "search",
+    RopewikiRegionImages = "ropewikiRegionImages",
+    RopewikiRegionPreviews = "ropewikiRegionPreviews"
+}
+/**
+ * Validated shape (results + nextCursor) passed to specific Result class's fromResponseBody
+ * after CursorPaginationResults.fromResponseBody has validated the full body.
+ */
+export type CursorPaginationResponseParsed = {
+    results: unknown[];
+    nextCursor: string | null;
+};
+/**
+ * Base type for cursor-paginated API results (results array + nextCursor + resultType).
+ * fromResponseBody validates body (resultType, results, nextCursor) then delegates to
+ * the corresponding Result class's fromResponseBody with the validated shape.
+ */
+export declare abstract class CursorPaginationResults<R = unknown> {
+    readonly results: R[];
+    readonly nextCursor: string | null;
+    readonly resultType: ResultType;
+    constructor(results: R[], nextCursor: string | null, resultType: ResultType);
+    /**
+     * Validates body (object, resultType, results array, nextCursor), then delegates to
+     * the corresponding Result class's fromResponseBody with { results, nextCursor }.
+     */
+    static fromResponseBody(body: unknown): CursorPaginationResults;
+}
+//# sourceMappingURL=cursorPaginationResults.d.ts.map

package/dist/types/results/cursorPaginationResults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursorPaginationResults.d.ts","sourceRoot":"","sources":["../../../src/types/results/cursorPaginationResults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,UAAU;IAClB,MAAM,WAAW;IACjB,oBAAoB,yBAAyB;IAC7C,sBAAsB,2BAA2B;CACpD;AAED;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG;IACzC,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF;;;;GAIG;AACH,8BAAsB,uBAAuB,CAAC,CAAC,GAAG,OAAO;aAEjC,OAAO,EAAE,CAAC,EAAE;aACZ,UAAU,EAAE,MAAM,GAAG,IAAI;aACzB,UAAU,EAAE,UAAU;gBAFtB,OAAO,EAAE,CAAC,EAAE,EACZ,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,UAAU;IAG1C;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,uBAAuB;CAgDlE"}

package/dist/types/results/cursorPaginationResults.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CursorPaginationResults = exports.ResultType = void 0;
+/**
+ * Discriminator for cursor-paginated result types. Used in response body so
+ * CursorPaginationResults.fromResponseBody can route to the correct parser.
+ */
+var ResultType;
+(function (ResultType) {
+    ResultType["Search"] = "search";
+    ResultType["RopewikiRegionImages"] = "ropewikiRegionImages";
+    ResultType["RopewikiRegionPreviews"] = "ropewikiRegionPreviews";
+})(ResultType || (exports.ResultType = ResultType = {}));
+/**
+ * Base type for cursor-paginated API results (results array + nextCursor + resultType).
+ * fromResponseBody validates body (resultType, results, nextCursor) then delegates to
+ * the corresponding Result class's fromResponseBody with the validated shape.
+ */
+class CursorPaginationResults {
+    constructor(results, nextCursor, resultType) {
+        this.results = results;
+        this.nextCursor = nextCursor;
+        this.resultType = resultType;
+    }
+    /**
+     * Validates body (object, resultType, results array, nextCursor), then delegates to
+     * the corresponding Result class's fromResponseBody with { results, nextCursor }.
+     */
+    static fromResponseBody(body) {
+        if (body == null || typeof body !== 'object') {
+            throw new Error('Response body must be an object');
+        }
+        const b = body;
+        if (!('resultType' in b)) {
+            throw new Error('Response body must have resultType');
+        }
+        const resultType = b.resultType;
+        const valid = Object.values(ResultType);
+        if (typeof resultType !== 'string' || !valid.includes(resultType)) {
+            throw new Error(`Response body.resultType must be one of [${valid.join(', ')}], got: ${JSON.stringify(resultType)}`);
+        }
+        if (!('results' in b)) {
+            throw new Error('Response body must have results');
+        }
+        const resultsRaw = b.results;
+        if (!Array.isArray(resultsRaw)) {
+            throw new Error('Response body.results must be an array');
+        }
+        let nextCursor = null;
+        if ('nextCursor' in b && b.nextCursor != null) {
+            if (typeof b.nextCursor !== 'string') {
+                throw new Error('Response body.nextCursor must be a string or null');
+            }
+            nextCursor = b.nextCursor;
+        }
+        const validated = {
+            results: resultsRaw,
+            nextCursor,
+        };
+        switch (resultType) {
+            case ResultType.Search: {
+                const { SearchResults } = require('../api/search/searchResults');
+                return SearchResults.fromResponseBody(validated);
+            }
+            case ResultType.RopewikiRegionPreviews: {
+                const { RopewikiRegionPreviewsResult } = require('../api/getRopewikiRegionPreviews/ropewikiRegionPreviewsResult');
+                return RopewikiRegionPreviewsResult.fromResponseBody(validated);
+            }
+            case ResultType.RopewikiRegionImages: {
+                const { RopewikiRegionImagesResult } = require('../api/getRopewikiRegionImages/ropewikiRegionImagesResult');
+                return RopewikiRegionImagesResult.fromResponseBody(validated);
+            }
+        }
+    }
+}
+exports.CursorPaginationResults = CursorPaginationResults;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ropegeo-common",
-    "version": "1.2.5",
+    "version": "1.2.7",
     "description": "Shared types and utilities for RopeGeo and WebScraper",
     "license": "ISC",
     "repository": {