Skip to content

Commit 05bd86e

Browse files
committed
fix(Pages)!: postPageCopied and postPageMove methods and params
BREAKING CHANGE: corrects and renames putPageMove to postPageMove. Adds type fixes and runtime checks for required parameters to both postPageCopied and postPageMove.
1 parent cc6ebc3 commit 05bd86e

4 files changed

Lines changed: 194 additions & 30 deletions

File tree

‎src/modules/base.ts‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { BaseArgs, ExpertGlobalOptions } from "../types";
2-
import { getTld, getAuth, getHeaders, createDebugLogger, parsePageId, parseFileName, parseKey, parseUserId, parseGroupId, parseFileId } from "../utils";
2+
import { getTld, getAuth, getHeaders, createDebugLogger, parsePageId, parseFileName, parseKey, parsePathParam, parseUserId, parseGroupId, parseFileId, parseNumericId } from "../utils";
33
import Requests from "./requests";
44
import type { Debugger } from "debug";
55

@@ -63,6 +63,16 @@ export default abstract class BaseModule {
6363
return parseKey(key);
6464
}
6565

66+
/**
67+
* Encodes a page path for use in a query-string value. Delegates to the
68+
* shared {@link parsePathParam} helper.
69+
* @param path - The page path to encode.
70+
* @returns The single URL-encoded path; axios adds the second encoding layer.
71+
*/
72+
protected parsePathParam(path: string): string {
73+
return parsePathParam(path);
74+
}
75+
6676
/**
6777
* Formats a user identifier for use in an endpoint path. Delegates to the
6878
* shared {@link parseUserId} helper.
@@ -92,4 +102,16 @@ export default abstract class BaseModule {
92102
protected parseFileId(id: string | number): string {
93103
return parseFileId(id);
94104
}
105+
106+
/**
107+
* Resolves a numeric identifier used as a query-param value (rather than a
108+
* path segment). Delegates to the shared {@link parseNumericId} helper, so
109+
* digit strings are accepted and coerced the same way page IDs are.
110+
* @param id - A positive integer ID, or a string of digits.
111+
* @param resource - Resource name used in the error message, e.g. `"parent page"`.
112+
* @returns The ID as a number.
113+
*/
114+
protected parseNumericId(id: string | number, resource: string): number {
115+
return parseNumericId(id, resource);
116+
}
95117
}

‎src/modules/pages.ts‎

Lines changed: 106 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@ import {
7272
PutPageFileNamePropertiesByKeyParams,
7373
PutPageFileNamePropertiesByKeyResponse,
7474
PutPageImportParams,
75-
PutPageMoveParams,
76-
PutPageMoveResponse,
75+
PostPageMoveParams,
76+
PostPageMoveResponse,
7777
PutPageOrderParams,
7878
PostPagePropertiesParams,
7979
PostPagePropertiesResponse,
@@ -95,6 +95,7 @@ import {
9595
PutPageTagsResponse
9696
} from "../types";
9797
import BaseModule from "./base";
98+
import { ExpertError } from "../errors";
9899
import { Buffer } from 'buffer';
99100

100101
export default class Pages extends BaseModule {
@@ -819,23 +820,44 @@ export default class Pages extends BaseModule {
819820
return res.data;
820821
}
821822

823+
/**
824+
* Copies a page to a new location. `to` is required by the endpoint and takes
825+
* a plain path - the double encoding Deki requires is applied here.
826+
* @param id - A page ID, page path, or the literal `"home"`.
827+
* @param reqArgs - Copy destination and options.
828+
* @param funcArgs - Optional per-call auth/tld/headers overrides.
829+
* @returns The copied pages.
830+
* @throws {ExpertError} With `kind: 'config'` when `to` is missing or blank.
831+
*/
822832
public async postPageCopied(
823833
id: string | number,
824-
reqArgs?: PostCopyPageParams,
834+
reqArgs: PostCopyPageParams,
825835
funcArgs?: BaseArgs
826836
) {
827-
this.debug('postPageCopied called for page:', id);
837+
this.debug('postPageCopied called for page:', id, 'to:', reqArgs?.to);
838+
839+
// `to` is the only required param, and JavaScript callers can skip
840+
// `reqArgs` entirely, so check it before anything dereferences it.
841+
if (typeof reqArgs?.to !== 'string' || reqArgs.to.trim() === '') {
842+
throw ExpertError.config(
843+
'Invalid copy request: `to` must be a non-empty destination path.'
844+
);
845+
}
846+
828847
const pageId = this.parsePageId(id);
829848
const requests = this.prepare(funcArgs);
830849

850+
// Deki wants the destination path double-encoded; axios supplies the
851+
// second layer when it serializes the query string.
852+
const params = {
853+
...reqArgs,
854+
to: this.parsePathParam(reqArgs.to),
855+
};
856+
831857
const res = await requests.post<PostCopyPageResponse>(
832858
`/pages/${pageId}/copy`,
833859
"",
834-
{
835-
params: {
836-
...reqArgs,
837-
},
838-
}
860+
{ params }
839861
);
840862

841863
this.debug('postPageCopied successfully copied page:', id);
@@ -1044,29 +1066,94 @@ export default class Pages extends BaseModule {
10441066
return res.data;
10451067
}
10461068

1047-
public async putPageMove(
1069+
/**
1070+
* Moves a page, and every page beneath it, to a new location. Deki leaves a
1071+
* redirect alias behind at the old path.
1072+
*
1073+
* Pass `to` for a full relocation, or `parentid`/`name`/`title` to reparent
1074+
* or rename the page where it sits. `to` takes a plain path - the double
1075+
* encoding Deki requires is applied here.
1076+
* @param id - A page ID, page path, or the literal `"home"`.
1077+
* @param reqArgs - Move target and options. At least one of `to`, `parentid`,
1078+
* `name`, or `title` must be supplied. `parentid` accepts a number or a
1079+
* string of digits.
1080+
* @param funcArgs - Optional per-call auth/tld/headers overrides.
1081+
* @returns The moved pages.
1082+
* @throws {ExpertError} With `kind: 'config'` when no move target is supplied,
1083+
* when `to`/`name`/`title` are blank, or when `parentid` is not a positive
1084+
* integer page ID.
1085+
*/
1086+
public async postPageMove(
10481087
id: string | number,
1049-
reqArgs?: PutPageMoveParams,
1088+
reqArgs?: PostPageMoveParams,
10501089
funcArgs?: BaseArgs
10511090
) {
1052-
this.debug('putPageMove called for page:', id, 'to:', reqArgs?.to);
1091+
this.debug('postPageMove called for page:', id, 'to:', reqArgs?.to);
1092+
1093+
// Every move target is individually optional, but a move with none of them
1094+
// is a no-op the API rejects, so catch it before the request goes out.
1095+
// A supplied-but-junk target (empty string, zero, a fractional id) is the
1096+
// same rejection, so validate the values rather than their presence.
1097+
const isNonBlankString = (value: unknown) =>
1098+
typeof value === 'string' && value.trim() !== '';
1099+
1100+
for (const key of ['to', 'name', 'title'] as const) {
1101+
if (reqArgs?.[key] !== undefined && !isNonBlankString(reqArgs[key])) {
1102+
throw ExpertError.config(
1103+
`Invalid move request: \`${key}\` must be a non-empty string.`
1104+
);
1105+
}
1106+
}
1107+
1108+
// `parentid` follows the same rules as any other page ID: digit strings
1109+
// are accepted and coerced, everything else throws.
1110+
const parentid =
1111+
reqArgs?.parentid !== undefined
1112+
? this.parseNumericId(reqArgs.parentid, 'parent page')
1113+
: undefined;
1114+
1115+
const hasTarget = (['to', 'parentid', 'name', 'title'] as const).some(
1116+
(key) => reqArgs?.[key] !== undefined
1117+
);
1118+
if (!hasTarget) {
1119+
throw ExpertError.config(
1120+
'Invalid move request: supply at least one of `to`, `parentid`, `name`, or `title`.'
1121+
);
1122+
}
1123+
10531124
const pageId = this.parsePageId(id);
10541125
const requests = this.prepare(funcArgs);
10551126

1056-
const res = await requests.put<PutPageMoveResponse>(
1127+
// Deki wants the destination path double-encoded; axios supplies the
1128+
// second layer when it serializes the query string.
1129+
const params = {
1130+
...reqArgs,
1131+
...(reqArgs?.to !== undefined && { to: this.parsePathParam(reqArgs.to) }),
1132+
...(parentid !== undefined && { parentid }),
1133+
};
1134+
1135+
const res = await requests.post<PostPageMoveResponse>(
10571136
`/pages/${pageId}/move`,
10581137
"",
1059-
{
1060-
params: {
1061-
...reqArgs,
1062-
},
1063-
}
1138+
{ params }
10641139
);
10651140

1066-
this.debug('putPageMove successfully moved page:', id);
1141+
this.debug('postPageMove successfully moved page:', id);
10671142
return res.data;
10681143
}
10691144

1145+
/**
1146+
* @deprecated Use {@link Pages.postPageMove}. The move endpoint is a POST,
1147+
* not a PUT; this alias forwards to the corrected implementation.
1148+
*/
1149+
public async putPageMove(
1150+
id: string | number,
1151+
reqArgs?: PostPageMoveParams,
1152+
funcArgs?: BaseArgs
1153+
) {
1154+
return this.postPageMove(id, reqArgs, funcArgs);
1155+
}
1156+
10701157
public async putPageOrder(
10711158
id: string | number,
10721159
reqArgs?: PutPageOrderParams,

‎src/types/pages.ts‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -371,8 +371,12 @@ export type PostPageAllowedResponse = {
371371
}
372372
}
373373

374+
/**
375+
* Query parameters for `POST /pages/{pageid}/copy`. `to` is required and takes
376+
* a plain path such as `Category/Floating rocks` - it is encoded for you.
377+
*/
374378
export type PostCopyPageParams = {
375-
to: string;
379+
to: string;
376380
title?: string;
377381
abort?: 'never' | 'exists';
378382
recursive?: boolean;
@@ -441,20 +445,33 @@ export type PutPageImportParams = {
441445
pageid?: number;
442446
}
443447

444-
export type PutPageMoveParams = {
445-
parentid?: number;
448+
/**
449+
* Query parameters for `POST /pages/{pageid}/move`. Supply `to` for a full
450+
* relocation, or `parentid`/`name`/`title` to reparent or rename in place.
451+
* The `to` value is encoded for you - pass a plain path such as
452+
* `Category/Floating rocks`.
453+
*/
454+
export type PostPageMoveParams = {
455+
/** Parent page ID. A string of digits is accepted and coerced to a number. */
456+
parentid?: number | string;
446457
name?: string;
447458
title?: string;
448459
to?: string;
449460
} & BaseQueryParams;
450461

451-
export type PutPageMoveResponse = {
452-
"page.moved"?: Maybe<{
462+
export type PostPageMoveResponse = {
463+
"pages.moved"?: Maybe<{
453464
"@count"?: string;
454465
page?: OneOrMany<Partial<PageBase>>;
455466
}>;
456467
};
457468

469+
/** @deprecated Use {@link PostPageMoveParams}. The move endpoint is a POST. */
470+
export type PutPageMoveParams = PostPageMoveParams;
471+
472+
/** @deprecated Use {@link PostPageMoveResponse}. The move endpoint is a POST. */
473+
export type PutPageMoveResponse = PostPageMoveResponse;
474+
458475
export type PutPageOrderParams = {
459476
afterid?: number;
460477
};

‎src/utils.ts‎

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -132,23 +132,38 @@ export function parseGroupId(id: string | number): string {
132132
* @throws {ExpertError} With `kind: 'config'` when `id` is not a positive integer.
133133
*/
134134
export function parseFileId(id: string | number): string {
135+
return String(parseNumericId(id, "file"));
136+
}
137+
138+
/**
139+
* Resolves a numeric identifier the way {@link parsePageId} resolves the
140+
* numeric half of its input: numbers pass through when they are positive safe
141+
* integers, digit-only strings are converted, and anything Number() would
142+
* coerce loosely (decimals, hex, exponents, signs, whitespace-padded junk) is
143+
* rejected.
144+
* @param id - A positive integer ID, or a string of digits.
145+
* @param resource - Resource name used in the error message, e.g. `"file"`.
146+
* @returns The ID as a number.
147+
* @throws {ExpertError} With `kind: 'config'` when `id` is not a positive integer.
148+
*/
149+
export function parseNumericId(id: string | number, resource: string): number {
135150
if (typeof id === "number") {
136151
if (!Number.isSafeInteger(id) || id <= 0) {
137152
throw ExpertError.config(
138-
`Invalid file id: expected a positive integer, received ${id}.`
153+
`Invalid ${resource} id: expected a positive integer, received ${id}.`
139154
);
140155
}
141-
return String(id);
156+
return id;
142157
}
143158

144-
const trimmed = id?.trim() ?? "";
159+
const trimmed = typeof id === "string" ? id.trim() : "";
145160
const asNumber = /^\d+$/.test(trimmed) ? Number(trimmed) : Number.NaN;
146161
if (!Number.isSafeInteger(asNumber) || asNumber <= 0) {
147162
throw ExpertError.config(
148-
`Invalid file id: expected a positive integer, received "${id}".`
163+
`Invalid ${resource} id: expected a positive integer, received ${JSON.stringify(id)}.`
149164
);
150165
}
151-
return String(asNumber);
166+
return asNumber;
152167
}
153168

154169
export function joinPaths(...parts: string[]): string {
@@ -191,3 +206,26 @@ export function parseKey(key: string): string {
191206
return encodeURIComponent(encodeURIComponent(key));
192207
}
193208

209+
210+
/**
211+
* Encodes a page path for use in a **query string** value, such as the `to`
212+
* parameter on `POST /pages/{pageid}/move`. Deki expects that value to arrive
213+
* double URL-encoded (a space reaches the server as `%2520`, a slash as
214+
* `%252f`), so this applies exactly one layer of encoding: axios serializes
215+
* query params and applies the second layer on the way out.
216+
*
217+
* Do not use this for path segments — those never pass through the query
218+
* serializer, so they need both layers up front (see {@link parsePageId}).
219+
* @param path - The page path, for example `Category/Floating rocks`.
220+
* @returns The single URL-encoded path.
221+
* @throws {ExpertError} With `kind: 'config'` when `path` is empty or whitespace-only.
222+
*/
223+
export function parsePathParam(path: string): string {
224+
const trimmed = path?.trim() ?? "";
225+
if (trimmed.length === 0) {
226+
throw ExpertError.config(
227+
"Invalid page path: expected a path, received an empty string."
228+
);
229+
}
230+
return encodeURIComponent(trimmed);
231+
}

0 commit comments

Comments
 (0)