@gscdump/contracts 3.1.0 → 3.2.0

package/dist/v1/operations.mjs

@@ -3,6 +3,7 @@ import "./version.mjs";
 import { HTTP_V1_ERROR_CODES, defineHttpOperation, defineHttpSurface, defineResponseObject, defineSuccessResponse } from "./http-core.mjs";
 import { GSCDUMP_REALTIME_ACK_POLICY, GSCDUMP_REALTIME_CLOSE_CODES, GSCDUMP_REALTIME_CONNECTION_POLICY, GSCDUMP_REALTIME_LIMITS, GSCDUMP_REALTIME_PING, GSCDUMP_REALTIME_PONG, GSCDUMP_REALTIME_REPLAY_POLICY, GSCDUMP_REALTIME_SUBPROTOCOL, GSCDUMP_REALTIME_TICKET_AUDIENCE, GSCDUMP_REALTIME_TICKET_ISSUER, GSCDUMP_REALTIME_TICKET_POLICY, GSCDUMP_REALTIME_TICKET_PREFIX, REALTIME_V1_EVENT_SEMANTICS, createRealtimeV1Schemas } from "./realtime.mjs";
 import { GSCDUMP_V1_ANALYTICS_DIMENSIONS, createGscdumpV1BrowserSchemas } from "./browser.mjs";
+import { gscdumpV1OperationRoute, gscdumpV1Surface } from "./route-catalog.mjs";
 import { z } from "zod";
 function errorEnvelopeSchemas(codes, publicRequestId) {
 	const errorDetails = z.record(z.string(), z.json());
@@ -696,14 +697,10 @@ function createGscdumpV1Protocol() {
 		"contract_violation"
 	];
 	const partner = defineHttpSurface({
-		name: "partner",
-		prefix: "/api/partner/v1",
-		version: "1.0",
+		...gscdumpV1Surface("partner"),
 		operations: {
 			getUserLifecycle: defineHttpOperation({
-				id: "partner.users.lifecycle.get",
-				method: "GET",
-				path: "/users/{userId}/lifecycle",
+				...gscdumpV1OperationRoute("partner.users.lifecycle.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -772,9 +769,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			listAvailableSites: defineHttpOperation({
-				id: "partner.users.sites.available.list",
-				method: "GET",
-				path: "/users/{userId}/available-sites",
+				...gscdumpV1OperationRoute("partner.users.sites.available.list"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -835,9 +830,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			createSite: defineHttpOperation({
-				id: "partner.users.sites.create",
-				method: "POST",
-				path: "/users/{userId}/sites",
+				...gscdumpV1OperationRoute("partner.users.sites.create"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -901,9 +894,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			createUser: defineHttpOperation({
-				id: "partner.users.create",
-				method: "POST",
-				path: "/users",
+				...gscdumpV1OperationRoute("partner.users.create"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -963,9 +954,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			updateUserTokens: defineHttpOperation({
-				id: "partner.users.tokens.update",
-				method: "PATCH",
-				path: "/users/{userId}/tokens",
+				...gscdumpV1OperationRoute("partner.users.tokens.update"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -1030,9 +1019,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getSiteIndexing: defineHttpOperation({
-				id: "partner.sites.indexing.get",
-				method: "GET",
-				path: "/sites/{siteId}/indexing",
+				...gscdumpV1OperationRoute("partner.sites.indexing.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1123,9 +1110,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			listSiteIndexingUrls: defineHttpOperation({
-				id: "partner.sites.indexing.urls.list",
-				method: "GET",
-				path: "/sites/{siteId}/indexing/urls",
+				...gscdumpV1OperationRoute("partner.sites.indexing.urls.list"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1199,9 +1184,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			listSiteBingIndexingEvidence: defineHttpOperation({
-				id: "partner.sites.indexing.bing.evidence.list",
-				method: "GET",
-				path: "/sites/{siteId}/indexing/bing/evidence",
+				...gscdumpV1OperationRoute("partner.sites.indexing.bing.evidence.list"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1272,9 +1255,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			listSiteIndexingTransitions: defineHttpOperation({
-				id: "partner.sites.indexing.transitions.list",
-				method: "GET",
-				path: "/sites/{siteId}/indexing/transitions",
+				...gscdumpV1OperationRoute("partner.sites.indexing.transitions.list"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1355,9 +1336,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getSiteIndexingDiagnostics: defineHttpOperation({
-				id: "partner.sites.indexing.diagnostics.get",
-				method: "GET",
-				path: "/sites/{siteId}/indexing/diagnostics",
+				...gscdumpV1OperationRoute("partner.sites.indexing.diagnostics.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1423,9 +1402,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getSiteSitemaps: defineHttpOperation({
-				id: "partner.sites.sitemaps.get",
-				method: "GET",
-				path: "/sites/{siteId}/sitemaps",
+				...gscdumpV1OperationRoute("partner.sites.sitemaps.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1494,9 +1471,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getSiteSitemapChanges: defineHttpOperation({
-				id: "partner.sites.sitemaps.changes.get",
-				method: "GET",
-				path: "/sites/{siteId}/sitemaps/changes",
+				...gscdumpV1OperationRoute("partner.sites.sitemaps.changes.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1569,9 +1544,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getSiteAnalysis: defineHttpOperation({
-				id: "partner.sites.analysis.get",
-				method: "GET",
-				path: "/sites/{siteId}/analysis",
+				...gscdumpV1OperationRoute("partner.sites.analysis.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1644,9 +1617,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getSiteAnalysisBundle: defineHttpOperation({
-				id: "partner.sites.analysis.bundle.get",
-				method: "GET",
-				path: "/sites/{siteId}/analysis/bundle",
+				...gscdumpV1OperationRoute("partner.sites.analysis.bundle.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1717,9 +1688,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			deleteSite: defineHttpOperation({
-				id: "partner.sites.delete",
-				method: "DELETE",
-				path: "/sites/{siteId}",
+				...gscdumpV1OperationRoute("partner.sites.delete"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -1784,9 +1753,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getCanonicalMismatches: defineHttpOperation({
-				id: "partner.sites.canonical.mismatches.get",
-				method: "GET",
-				path: "/sites/{siteId}/canonical-mismatches",
+				...gscdumpV1OperationRoute("partner.sites.canonical.mismatches.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -1850,9 +1817,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			inspectSiteUrls: defineHttpOperation({
-				id: "partner.sites.indexing.inspect.create",
-				method: "POST",
-				path: "/sites/{siteId}/indexing/inspect",
+				...gscdumpV1OperationRoute("partner.sites.indexing.inspect.create"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -1923,9 +1888,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			recoverSitePermission: defineHttpOperation({
-				id: "partner.sites.permission.recover",
-				method: "POST",
-				path: "/sites/{siteId}/permission/recover",
+				...gscdumpV1OperationRoute("partner.sites.permission.recover"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -1991,9 +1954,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			queryKeywordSparklines: defineHttpOperation({
-				id: "partner.sites.keyword.sparklines.query",
-				method: "POST",
-				path: "/sites/{siteId}/keyword-sparklines",
+				...gscdumpV1OperationRoute("partner.sites.keyword.sparklines.query"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2059,9 +2020,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getQueryTrend: defineHttpOperation({
-				id: "partner.sites.query.trend.get",
-				method: "GET",
-				path: "/sites/{siteId}/query-trend",
+				...gscdumpV1OperationRoute("partner.sites.query.trend.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2129,9 +2088,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getPageTrend: defineHttpOperation({
-				id: "partner.sites.page.trend.get",
-				method: "GET",
-				path: "/sites/{siteId}/page-trend",
+				...gscdumpV1OperationRoute("partner.sites.page.trend.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2199,9 +2156,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getContentVelocity: defineHttpOperation({
-				id: "partner.sites.content.velocity.get",
-				method: "GET",
-				path: "/sites/{siteId}/content-velocity",
+				...gscdumpV1OperationRoute("partner.sites.content.velocity.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2270,9 +2225,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getCtrCurve: defineHttpOperation({
-				id: "partner.sites.ctr.curve.get",
-				method: "GET",
-				path: "/sites/{siteId}/ctr-curve",
+				...gscdumpV1OperationRoute("partner.sites.ctr.curve.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2341,9 +2294,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getDarkTraffic: defineHttpOperation({
-				id: "partner.sites.dark.traffic.get",
-				method: "GET",
-				path: "/sites/{siteId}/dark-traffic",
+				...gscdumpV1OperationRoute("partner.sites.dark.traffic.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2418,9 +2369,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getDeviceGap: defineHttpOperation({
-				id: "partner.sites.device.gap.get",
-				method: "GET",
-				path: "/sites/{siteId}/device-gap",
+				...gscdumpV1OperationRoute("partner.sites.device.gap.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2488,9 +2437,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getKeywordBreadth: defineHttpOperation({
-				id: "partner.sites.keyword.breadth.get",
-				method: "GET",
-				path: "/sites/{siteId}/keyword-breadth",
+				...gscdumpV1OperationRoute("partner.sites.keyword.breadth.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2565,9 +2512,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getPositionDistribution: defineHttpOperation({
-				id: "partner.sites.position.distribution.get",
-				method: "GET",
-				path: "/sites/{siteId}/position-distribution",
+				...gscdumpV1OperationRoute("partner.sites.position.distribution.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2634,9 +2579,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getTopAssociation: defineHttpOperation({
-				id: "partner.sites.top.association.get",
-				method: "GET",
-				path: "/sites/{siteId}/top-association",
+				...gscdumpV1OperationRoute("partner.sites.top.association.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2699,9 +2642,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getIndexPercent: defineHttpOperation({
-				id: "partner.sites.index.percent.get",
-				method: "GET",
-				path: "/sites/{siteId}/index-percent",
+				...gscdumpV1OperationRoute("partner.sites.index.percent.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2782,9 +2723,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			createSitemapAction: defineHttpOperation({
-				id: "partner.sites.sitemaps.action.create",
-				method: "POST",
-				path: "/sites/{siteId}/sitemaps/actions",
+				...gscdumpV1OperationRoute("partner.sites.sitemaps.action.create"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -2850,9 +2789,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			querySitemapMembership: defineHttpOperation({
-				id: "partner.sites.sitemaps.membership.query",
-				method: "POST",
-				path: "/sites/{siteId}/sitemaps/membership",
+				...gscdumpV1OperationRoute("partner.sites.sitemaps.membership.query"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2922,9 +2859,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			listSitemapUrls: defineHttpOperation({
-				id: "partner.sites.sitemaps.urls.get",
-				method: "GET",
-				path: "/sites/{siteId}/sitemaps/urls",
+				...gscdumpV1OperationRoute("partner.sites.sitemaps.urls.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -2996,9 +2931,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getSitemapExport: defineHttpOperation({
-				id: "partner.sites.sitemaps.export.get",
-				method: "GET",
-				path: "/sites/{siteId}/sitemaps/export",
+				...gscdumpV1OperationRoute("partner.sites.sitemaps.export.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -3066,9 +2999,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			createTeam: defineHttpOperation({
-				id: "partner.teams.create",
-				method: "POST",
-				path: "/teams",
+				...gscdumpV1OperationRoute("partner.teams.create"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3130,9 +3061,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			renameTeam: defineHttpOperation({
-				id: "partner.teams.rename",
-				method: "PATCH",
-				path: "/teams/{teamId}",
+				...gscdumpV1OperationRoute("partner.teams.rename"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3193,9 +3122,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			deleteTeam: defineHttpOperation({
-				id: "partner.teams.delete",
-				method: "DELETE",
-				path: "/teams/{teamId}",
+				...gscdumpV1OperationRoute("partner.teams.delete"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3250,9 +3177,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			listTeamMembers: defineHttpOperation({
-				id: "partner.teams.members.list",
-				method: "GET",
-				path: "/teams/{teamId}/members",
+				...gscdumpV1OperationRoute("partner.teams.members.list"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -3304,9 +3229,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			addTeamMember: defineHttpOperation({
-				id: "partner.teams.members.add",
-				method: "POST",
-				path: "/teams/{teamId}/members",
+				...gscdumpV1OperationRoute("partner.teams.members.add"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3370,9 +3293,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			updateTeamMemberRole: defineHttpOperation({
-				id: "partner.teams.members.role.update",
-				method: "PATCH",
-				path: "/teams/{teamId}/members/{userId}",
+				...gscdumpV1OperationRoute("partner.teams.members.role.update"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3445,9 +3366,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			removeTeamMember: defineHttpOperation({
-				id: "partner.teams.members.remove",
-				method: "DELETE",
-				path: "/teams/{teamId}/members/{userId}",
+				...gscdumpV1OperationRoute("partner.teams.members.remove"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3514,9 +3433,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			updateSiteTeam: defineHttpOperation({
-				id: "partner.sites.team.update",
-				method: "PATCH",
-				path: "/sites/{siteId}/team",
+				...gscdumpV1OperationRoute("partner.sites.team.update"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3577,9 +3494,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getTeamCatalog: defineHttpOperation({
-				id: "partner.teams.catalog.get",
-				method: "GET",
-				path: "/teams/{teamId}/catalog",
+				...gscdumpV1OperationRoute("partner.teams.catalog.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -3641,9 +3556,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			bindTeamCatalog: defineHttpOperation({
-				id: "partner.teams.catalog.bind",
-				method: "POST",
-				path: "/teams/{teamId}/catalog",
+				...gscdumpV1OperationRoute("partner.teams.catalog.bind"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3713,9 +3626,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			getSiteIntIdCrosswalk: defineHttpOperation({
-				id: "partner.users.sites.crosswalk.get",
-				method: "GET",
-				path: "/users/{userId}/sites/crosswalk",
+				...gscdumpV1OperationRoute("partner.users.sites.crosswalk.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -3776,9 +3687,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			deleteUser: defineHttpOperation({
-				id: "partner.users.delete",
-				method: "DELETE",
-				path: "/users/{userId}",
+				...gscdumpV1OperationRoute("partner.users.delete"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3841,9 +3750,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			createVerificationToken: defineHttpOperation({
-				id: "partner.users.verification.token.create",
-				method: "POST",
-				path: "/users/{userId}/verification-token",
+				...gscdumpV1OperationRoute("partner.users.verification.token.create"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -3921,9 +3828,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			addAndVerifySite: defineHttpOperation({
-				id: "partner.users.sites.verify.create",
-				method: "POST",
-				path: "/users/{userId}/sites/verify",
+				...gscdumpV1OperationRoute("partner.users.sites.verify.create"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",
@@ -3998,14 +3903,10 @@ function createGscdumpV1Protocol() {
 		}
 	});
 	const analytics = defineHttpSurface({
-		name: "analytics",
-		prefix: "/api/analytics/v1",
-		version: "1.0",
+		...gscdumpV1Surface("analytics"),
 		operations: {
 			queryRows: defineHttpOperation({
-				id: "analytics.rows.query",
-				method: "POST",
-				path: "/sites/{siteId}/rows",
+				...gscdumpV1OperationRoute("analytics.rows.query"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -4070,9 +3971,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			queryReport: defineHttpOperation({
-				id: "analytics.reports.query",
-				method: "POST",
-				path: "/sites/{siteId}/reports",
+				...gscdumpV1OperationRoute("analytics.reports.query"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -4152,9 +4051,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			queryReportDetail: defineHttpOperation({
-				id: "analytics.reports.detail.query",
-				method: "POST",
-				path: "/sites/{siteId}/reports/detail",
+				...gscdumpV1OperationRoute("analytics.reports.detail.query"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -4235,14 +4132,10 @@ function createGscdumpV1Protocol() {
 		}
 	});
 	const realtime = defineHttpSurface({
-		name: "realtime",
-		prefix: "/api/realtime/v1",
-		version: "1.0",
+		...gscdumpV1Surface("realtime"),
 		operations: {
 			getStreamHead: defineHttpOperation({
-				id: "realtime.stream.head.get",
-				method: "GET",
-				path: "/stream/head",
+				...gscdumpV1OperationRoute("realtime.stream.head.get"),
 				visibility: "public",
 				semantics: {
 					kind: "query",
@@ -4297,9 +4190,7 @@ function createGscdumpV1Protocol() {
 				}
 			}),
 			createTicket: defineHttpOperation({
-				id: "realtime.tickets.create",
-				method: "POST",
-				path: "/tickets",
+				...gscdumpV1OperationRoute("realtime.tickets.create"),
 				visibility: "public",
 				semantics: {
 					kind: "mutation",

package/dist/v1/path-segment.mjs

@@ -0,0 +1,7 @@
+function serializeHttpV1PathSegment(operationId, name, value) {
+	if (typeof value !== "string" && typeof value !== "number") throw new TypeError(`${operationId}: path parameter ${name} must serialize as a string or number`);
+	const serialized = String(value);
+	if (serialized.length === 0 || serialized === "." || serialized === "..") throw new TypeError(`${operationId}: path parameter ${name} cannot serialize as an empty or dot segment`);
+	return encodeURIComponent(serialized);
+}
+export { serializeHttpV1PathSegment };

package/dist/v1/paths.d.mts

@@ -0,0 +1,19 @@
+import { UnknownHttpV1OperationError, isUnknownHttpV1OperationError } from "./http-operation-error.mjs";
+import { HttpV1RouteSurfaceName } from "./route-surfaces.mjs";
+import { GSCDUMP_V1_ROUTE_CATALOG, GscdumpV1Route, GscdumpV1RouteOperationId, HttpV1RouteMethod } from "./route-catalog.mjs";
+type PathParameterNames<TTemplate extends string> = TTemplate extends `${string}{${infer TName}}${infer TRest}` ? TName | PathParameterNames<TRest> : never;
+type GscdumpV1PathParams<TId extends GscdumpV1RouteOperationId> = [PathParameterNames<GscdumpV1Route<TId>['template']>] extends [never] ? undefined : { [TName in PathParameterNames<GscdumpV1Route<TId>['template']>]: string | number; };
+type GscdumpV1PathArguments<TId extends GscdumpV1RouteOperationId> = GscdumpV1PathParams<TId> extends undefined ? [params?: undefined] : [params: GscdumpV1PathParams<TId>];
+interface GscdumpV1PathsOptions {
+  /** Root replacing the contract's `/api` segment. */
+  apiRoot?: string;
+}
+type GscdumpV1PathOperation<TId extends GscdumpV1RouteOperationId = GscdumpV1RouteOperationId> = GscdumpV1Route<TId> & {
+  prefix: typeof GSCDUMP_V1_ROUTE_CATALOG.surfaces[GscdumpV1Route<TId>['surface']]['prefix'];
+};
+interface GscdumpV1Paths {
+  operation: <const TId extends GscdumpV1RouteOperationId>(id: TId) => GscdumpV1PathOperation<TId>;
+  path: <const TId extends GscdumpV1RouteOperationId>(id: TId, ...args: GscdumpV1PathArguments<TId>) => string;
+}
+declare function createGscdumpV1Paths(options?: GscdumpV1PathsOptions): GscdumpV1Paths;
+export { GscdumpV1PathArguments, GscdumpV1PathOperation, GscdumpV1PathParams, GscdumpV1Paths, GscdumpV1PathsOptions, type GscdumpV1Route, type GscdumpV1RouteOperationId, type HttpV1RouteMethod, type HttpV1RouteSurfaceName, type UnknownHttpV1OperationError, createGscdumpV1Paths, isUnknownHttpV1OperationError };

package/dist/v1/paths.mjs

@@ -0,0 +1,39 @@
+import { isUnknownHttpV1OperationError } from "./http-operation-error.mjs";
+import { serializeHttpV1PathSegment } from "./path-segment.mjs";
+import { GSCDUMP_V1_ROUTE_CATALOG, getGscdumpV1Route } from "./route-catalog.mjs";
+function normalizeApiRoot(apiRoot) {
+	const root = apiRoot ?? "/api";
+	if (!root.startsWith("/") || root.startsWith("//") || root.includes("?") || root.includes("#")) throw new TypeError("HTTP v1 apiRoot must be an absolute path without a query string or fragment");
+	return root === "/" ? "" : root.replace(/\/+$/, "");
+}
+function createGscdumpV1Paths(options = {}) {
+	const apiRoot = normalizeApiRoot(options.apiRoot);
+	function operation(id) {
+		const route = getGscdumpV1Route(id);
+		return {
+			...route,
+			prefix: GSCDUMP_V1_ROUTE_CATALOG.surfaces[route.surface].prefix
+		};
+	}
+	return {
+		operation,
+		path: (id, ...args) => {
+			const route = operation(id);
+			const names = [...route.template.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1]);
+			const params = args[0];
+			if (names.length === 0) {
+				if (params !== void 0) throw new TypeError(`${id}: this operation has no path parameters`);
+				return `${apiRoot}${route.prefix.slice(4)}${route.template}`;
+			}
+			if (params === void 0 || params === null || typeof params !== "object" || Array.isArray(params)) throw new TypeError(`${id}: path parameters are required`);
+			const unknownName = Object.keys(params).find((name) => !names.includes(name));
+			if (unknownName) throw new TypeError(`${id}: unknown path parameter ${unknownName}`);
+			const relativePath = route.template.replace(/\{([^{}]+)\}/g, (_match, name) => {
+				if (!Object.hasOwn(params, name)) throw new TypeError(`${id}: path parameter ${name} is required`);
+				return serializeHttpV1PathSegment(id, name, params[name]);
+			});
+			return `${apiRoot}${route.prefix.slice(4)}${relativePath}`;
+		}
+	};
+}
+export { createGscdumpV1Paths, isUnknownHttpV1OperationError };