Clarify UGC query limits

Author: raub

README.md

@@ -314,14 +314,17 @@ UGC promises resolve from Steam call results. Continue pumping callbacks with
 reports completion through the `download-item-result` callback event:
 
 `getItems()`, `getUserItems()`, and `getItemsByIds()` query options map to Steam's query setter
-methods. Tag filters, required key-value tags, return toggles, playtime stats,
-text search, trend windows, language, and cache age are applied before
-`SendQueryUGCRequest()`. `userId` is used only by `getUserItems()`.
+methods. `getItemsByIds()` accepts from one to 50 known published file IDs and
+throws if given more. Tag filters, required key-value tags, return toggles,
+playtime stats, text search, trend windows, language, and cache age are applied
+before `SendQueryUGCRequest()`. `userId` is used only by `getUserItems()`.
 `matchAnyTag`, `searchText`, and `rankedByTrendDays` are only valid for
 `getItems()`; `cloudFileNameFilter` is only valid for `getUserItems()`.
 `getItems()` also accepts a deep-pagination `cursor`, which cannot be combined
 with `page`. Pass the prior result's non-empty `nextCursor` to obtain the next
-page; cursor pagination is not available for user or ID-detail queries.
+page. Steam returns `nextCursor: ''` on the final page; do not pass that empty
+terminal value as `cursor`, because the binding throws. Cursor pagination is not
+available for user or ID-detail queries.
 
 ```ts
 import {

docs/api/ugc.md

@@ -22,8 +22,9 @@ flags, language, cache age, and the query-specific options documented below.
   deep-pagination `cursor`. Do not combine `cursor` with `page`.
 - `getUserItems()` supports `userId` for another public user and
   `cloudFileNameFilter`; without `userId`, it selects the current user.
-- `getItemsByIds()` accepts known published file IDs and return-field options;
-  it does not support user or cursor options.
+- `getItemsByIds()` accepts one to 50 known published file IDs and return-field
+  options; it does not support user or cursor options. Passing more than 50 IDs
+  throws before Steam creates a query.
 
 The result includes `items`, `totalMatchingResults`, `cachedData`, and
 `nextCursor`. Optional fields such as metadata, children, previews, key-value
@@ -51,7 +52,9 @@ const items = await waitForSteamCall(
 ```
 
 For deep pagination, pass a non-empty `nextCursor` from one all-item result to
-the next `getItems()` call.
+the next `getItems()` call. Steam returns `nextCursor: ''` on the final page;
+that empty terminal value must not be passed as `cursor` because the binding
+throws for an empty cursor. Use a truthiness check such as the one below.
 
 ```ts
 let result = await waitForSteamCall(

src/cpp/ugc.cpp

@@ -1907,6 +1907,10 @@ JS_METHOD(getUserItems) {
 JS_METHOD(getItemsByIds) {
 	NAPI_ENV;
 	REQ_ARRAY_ARG(1, publishedFileIds);
+	if (publishedFileIds.Length() > kNumUGCResultsPerPage) {
+		JS_THROW("publishedFileIds must contain no more than 50 item IDs.");
+		RET_UNDEFINED;
+	}
 
 	QueryOptions options = {};
 	if (!readQueryOptions(env, info[0], &options)) {

ts/index.test.ts

@@ -3,7 +3,12 @@ import assert from 'node:assert/strict';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { getBin } from '@node-3d/addon-tools';
-import type { TSteamId, TSteamUgcDetails, TSteamUgcQueryOptions } from './index.ts';
+import type {
+	TSteamId,
+	TSteamPublishedFileId,
+	TSteamUgcDetails,
+	TSteamUgcQueryOptions,
+} from './index.ts';
 
 const nativeBinaryPath = join(import.meta.dirname, '..', getBin(), 'steam-api.node');
 const nativeSkip = existsSync(nativeBinaryPath) ? false : 'native binary is not built';
@@ -276,5 +281,13 @@ test(
 			() => steamApi.friends.getFriendMessage(steamId, 0, 64 * 1024 + 1),
 			/maximumMessageSize exceeds the maximum Steam friend message size/u,
 		);
+		assert.throws(
+			() =>
+				steamApi.ugc.getItemsByIds(
+					{},
+					Array.from({ length: 51 }, () => '1' as TSteamPublishedFileId),
+				),
+			/publishedFileIds must contain no more than 50 item IDs/u,
+		);
 	},
 );

ts/native.ts

@@ -111,7 +111,10 @@ export type TSteamUgcQueryKeyValueTag = Readonly<{
 export type TSteamUgcQueryOptions = Readonly<{
 	appId?: number;
 	page?: number;
-	/** Deep-pagination cursor for getItems(); cannot be combined with page. */
+	/**
+	 * Deep-pagination cursor for getItems(); cannot be combined with page. Must
+	 * be a non-empty nextCursor from a previous result.
+	 */
 	cursor?: string;
 	/** Steam user ID for getUserItems(); defaults to the current user. */
 	userId?: TSteamId;
@@ -193,6 +196,7 @@ export type TSteamUgcQueryResult = Readonly<{
 	result: number;
 	totalMatchingResults: number;
 	cachedData: boolean;
+	/** Empty when there is no next page; do not pass an empty cursor to getItems(). */
 	nextCursor: string;
 	items: TSteamUgcDetails[];
 }>;
@@ -1022,6 +1026,7 @@ export type TSteamNativeUgcNamespace = Readonly<{
 	) => Promise<TSteamUgcQueryResult>;
 	getItemsByIds: (
 		options: TSteamUgcQueryOptions | null | undefined,
+		/** Accepts from one to 50 published file IDs. */
 		publishedFileIds: TSteamPublishedFileId[],
 	) => Promise<TSteamUgcQueryResult>;
 	createItem: (appId?: number, fileType?: number) => Promise<TSteamUgcCreateItemResult>;