@wp-typia/project-tools 0.13.4 → 0.14.0

package/dist/runtime/scaffold-onboarding.js

@@ -37,12 +37,12 @@ export function getTemplateSourceOfTruthNote(templateId, { compoundPersistenceEn
     if (templateId === "compound") {
         const compoundBase = "`src/blocks/*/types.ts` files remain the source of truth for each block's `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include starter `typia.manifest.json` files so editor imports resolve before the first sync.";
         if (compoundPersistenceEnabled) {
-            return `${compoundBase} For persistence-enabled parents, \`src/blocks/*/api-types.ts\` files remain the source of truth for \`src/blocks/*/api-schemas/*\` when you run \`sync-rest\`.`;
+            return `${compoundBase} For persistence-enabled parents, \`src/blocks/*/api-types.ts\` files remain the source of truth for \`src/blocks/*/api-schemas/*\` when you run \`sync-rest\`, while \`src/blocks/*/transport.ts\` is the first-class transport seam for editor and frontend requests.`;
         }
         return compoundBase;
     }
     if (templateId === "persistence") {
-        return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. `src/api-types.ts` remains the source of truth for `src/api-schemas/*` when you run `sync-rest`. This scaffold is intentionally server-rendered: `src/render.php` is the canonical frontend entry, and `src/save.tsx` returns `null` so PHP can inject post context, storage-backed state, and write-policy bootstrap data before hydration.";
+        return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. `src/api-types.ts` remains the source of truth for `src/api-schemas/*` when you run `sync-rest`, while `src/transport.ts` is the first-class transport seam for editor and frontend requests. This scaffold is intentionally server-rendered: `src/render.php` is the canonical frontend entry, and `src/save.tsx` returns `null` so PHP can inject post context, storage-backed state, and write-policy bootstrap data before hydration.";
     }
     return "`src/types.ts` remains the source of truth for `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include a starter `typia.manifest.json` so editor imports resolve before the first sync. The basic scaffold stays static by design: `src/render.php` is only an opt-in server placeholder, `src/save.tsx` remains the canonical frontend output, and the generated webpack config keeps the current `@wordpress/scripts` CommonJS baseline unless you intentionally add `render` to `block.json`.";
 }
@@ -61,13 +61,14 @@ ${formatRunScript(packageManager, "add-child", '--slug faq-item --title "FAQ Ite
 
 This scaffolds a new hidden child block type, updates \`scripts/block-config.ts\` and \`src/blocks/*/children.ts\`, and leaves the default seeded child template unchanged.`;
 }
-function formatPhpRestExtensionPointsSection({ apiTypesPath, extraNote, mainPhpPath, mainPhpScope, }) {
+function formatPhpRestExtensionPointsSection({ apiTypesPath, extraNote, mainPhpPath, mainPhpScope, transportPath, }) {
     const schemaJsonGlob = apiTypesPath.replace(/api-types\.ts$/u, "api-schemas/*.schema.json");
     const perContractOpenApiGlob = apiTypesPath.replace(/api-types\.ts$/u, "api-schemas/*.openapi.json");
     const aggregateOpenApiPath = apiTypesPath.replace(/api-types\.ts$/u, "api.openapi.json");
     const lines = [
         `- Edit \`${mainPhpPath}\` when you need to ${mainPhpScope}.`,
         "- Edit `inc/rest-auth.php` or `inc/rest-public.php` when you need to customize write permissions or token/request-id/nonce checks for the selected policy.",
+        `- Edit \`${transportPath}\` when you need to switch between direct WordPress REST and a contract-compatible proxy or BFF without changing the endpoint contracts.`,
         `- Keep \`${apiTypesPath}\` as the source of truth for request and response contracts, then regenerate \`${schemaJsonGlob}\`, per-contract \`${perContractOpenApiGlob}\`, and \`${aggregateOpenApiPath}\` with \`sync-rest\`.`,
         "- Avoid hand-editing generated schema and OpenAPI artifacts unless you are debugging generated output; they are meant to be regenerated from TypeScript contracts.",
     ];
@@ -85,6 +86,7 @@ export function getPhpRestExtensionPointsSection(templateId, { compoundPersisten
             apiTypesPath: "src/api-types.ts",
             mainPhpPath: `${slug}.php`,
             mainPhpScope: "change storage helpers, route handlers, response shaping, or route registration",
+            transportPath: "src/transport.ts",
         });
     }
     if (templateId === "compound" && compoundPersistenceEnabled) {
@@ -93,6 +95,7 @@ export function getPhpRestExtensionPointsSection(templateId, { compoundPersisten
             extraNote: "The hidden child block does not own REST routes or storage.",
             mainPhpPath: `${slug}.php`,
             mainPhpScope: "change parent-block storage helpers, route handlers, response shaping, or route registration",
+            transportPath: `src/blocks/${slug}/transport.ts`,
         });
     }
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.13.4",
+  "version": "0.14.0",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/api.ts.mustache

@@ -1,6 +1,5 @@
 import {
 	callEndpoint,
-	resolveRestRouteUrl,
 } from '@wp-typia/rest';
 
 import {
@@ -11,58 +10,49 @@ import {
 	get{{pascalCase}}StateEndpoint,
 	write{{pascalCase}}StateEndpoint,
 } from './api-client';
-
-export function resolveRestNonce( fallback?: string ): string | undefined {
-	if ( typeof fallback === 'string' && fallback.length > 0 ) {
-		return fallback;
-	}
-
-	if ( typeof window === 'undefined' ) {
-		return undefined;
-	}
-
-	const wpApiSettings = ( window as typeof window & {
-		wpApiSettings?: { nonce?: string };
-	} ).wpApiSettings;
-
-	return typeof wpApiSettings?.nonce === 'string' && wpApiSettings.nonce.length > 0
-		? wpApiSettings.nonce
-		: undefined;
-}
+import {
+	resolveTransportCallOptions,
+	type PersistenceTransportOptions,
+} from './transport';
 
 export const stateEndpoint = {
 	...get{{pascalCase}}StateEndpoint,
-	buildRequestOptions: () => ( {
-		url: resolveRestRouteUrl( get{{pascalCase}}StateEndpoint.path ),
-	} ),
 };
 
 export const writeStateEndpoint = {
 	...write{{pascalCase}}StateEndpoint,
-	buildRequestOptions: () => ( {
-		url: resolveRestRouteUrl( write{{pascalCase}}StateEndpoint.path ),
-	} ),
 };
 
 export function fetchState(
-	request: {{pascalCase}}StateQuery
+	request: {{pascalCase}}StateQuery,
+	options: PersistenceTransportOptions = {}
 ) {
-	return callEndpoint( stateEndpoint, request );
+	return callEndpoint(
+		stateEndpoint,
+		request,
+		resolveTransportCallOptions(
+			options.transportTarget ?? 'frontend',
+			'read',
+			stateEndpoint,
+			request,
+			options
+		)
+	);
 }
 
 export function writeState(
 	request: {{pascalCase}}WriteStateRequest,
-	restNonce?: string
+	options: PersistenceTransportOptions = {}
 ) {
-	const nonce = resolveRestNonce( restNonce );
-
-	return callEndpoint( writeStateEndpoint, request, {
-		requestOptions: nonce
-			? {
-					headers: {
-						'X-WP-Nonce': nonce,
-					},
-				}
-			: undefined,
-	} );
+	return callEndpoint(
+		writeStateEndpoint,
+		request,
+		resolveTransportCallOptions(
+			options.transportTarget ?? 'frontend',
+			'write',
+			writeStateEndpoint,
+			request,
+			options
+		)
+	);
 }

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/data.ts.mustache

@@ -11,26 +11,13 @@ import type {
 	{{pascalCase}}WriteStateRequest,
 } from './api-types';
 import {
-	resolveRestNonce,
 	stateEndpoint,
 	writeStateEndpoint,
 } from './api';
-
-{{#isAuthenticatedPersistencePolicy}}
-function buildWriteCallOptions( restNonce?: string ) {
-	const nonce = resolveRestNonce( restNonce );
-
-	return nonce
-		? {
-				requestOptions: {
-					headers: {
-						'X-WP-Nonce': nonce,
-					},
-				},
-			}
-		: undefined;
-}
-{{/isAuthenticatedPersistencePolicy}}
+import {
+	resolveTransportCallOptions,
+	type PersistenceTransportTarget,
+} from './transport';
 
 interface WriteStateMutationContext< Context > {
 	previous:
@@ -49,9 +36,8 @@ export interface Use{{pascalCase}}StateQueryOptions<
 	>,
 	'resolveCallOptions'
 > {
-	{{#isAuthenticatedPersistencePolicy}}
 	restNonce?: string;
-	{{/isAuthenticatedPersistencePolicy}}
+	transportTarget?: PersistenceTransportTarget;
 }
 
 export interface UseWrite{{pascalCase}}StateMutationOptions<
@@ -62,7 +48,7 @@ export interface UseWrite{{pascalCase}}StateMutationOptions<
 		{{pascalCase}}StateResponse,
 		WriteStateMutationContext< Context >
 	>,
-	'invalidate' | 'onError' | 'onMutate'{{#isAuthenticatedPersistencePolicy}} | 'resolveCallOptions'{{/isAuthenticatedPersistencePolicy}}
+	'invalidate' | 'onError' | 'onMutate' | 'resolveCallOptions'
 > {
 	onError?: (
 		error: unknown,
@@ -74,9 +60,8 @@ export interface UseWrite{{pascalCase}}StateMutationOptions<
 		request: {{pascalCase}}WriteStateRequest,
 		client: import('@wp-typia/rest/react').EndpointDataClient
 	) => Context | Promise<Context>;
-	{{#isAuthenticatedPersistencePolicy}}
 	restNonce?: string;
-	{{/isAuthenticatedPersistencePolicy}}
+	transportTarget?: PersistenceTransportTarget;
 }
 
 export function use{{pascalCase}}StateQuery<
@@ -85,20 +70,26 @@ export function use{{pascalCase}}StateQuery<
 	request: {{pascalCase}}StateQuery,
 	options: Use{{pascalCase}}StateQueryOptions< Selected > = {}
 ) {
-	{{#isAuthenticatedPersistencePolicy}}
 	const {
 		restNonce,
+		transportTarget = 'editor',
 		...queryOptions
 	} = options;
 
 	return useEndpointQuery( stateEndpoint, request, {
 		...queryOptions,
-		resolveCallOptions: () => buildWriteCallOptions( restNonce ),
+		resolveCallOptions: () =>
+			resolveTransportCallOptions(
+				transportTarget,
+				'read',
+				stateEndpoint,
+				request,
+				{
+					restNonce,
+					transportTarget,
+				}
+			),
 	} );
-	{{/isAuthenticatedPersistencePolicy}}
-	{{^isAuthenticatedPersistencePolicy}}
-	return useEndpointQuery( stateEndpoint, request, options );
-	{{/isAuthenticatedPersistencePolicy}}
 }
 
 export function useWrite{{pascalCase}}StateMutation<
@@ -109,9 +100,8 @@ export function useWrite{{pascalCase}}StateMutation<
 	const {
 		onError,
 		onMutate,
-		{{#isAuthenticatedPersistencePolicy}}
 		restNonce,
-		{{/isAuthenticatedPersistencePolicy}}
+		transportTarget = 'editor',
 		...mutationOptions
 	} = options;
 
@@ -185,8 +175,16 @@ export function useWrite{{pascalCase}}StateMutation<
 				userContext,
 			};
 		},
-		{{#isAuthenticatedPersistencePolicy}}
-		resolveCallOptions: () => buildWriteCallOptions( restNonce ),
-		{{/isAuthenticatedPersistencePolicy}}
+		resolveCallOptions: ( request ) =>
+			resolveTransportCallOptions(
+				transportTarget,
+				'write',
+				writeStateEndpoint,
+				request,
+				{
+					restNonce,
+					transportTarget,
+				}
+			),
 	} );
 }

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/interactivity.ts.mustache

@@ -47,6 +47,9 @@ const { actions, state } = store( '{{slugKebabCase}}', {
 				const result = await fetchState( {
 					postId: context.postId,
 					resourceKey: context.resourceKey,
+				}, {
+					restNonce: context.restNonce,
+					transportTarget: 'frontend',
 				} );
 				if ( ! result.isValid || ! result.data ) {
 					state.error = result.errors[ 0 ]?.expected ?? 'Unable to load counter';
@@ -96,7 +99,10 @@ const { actions, state } = store( '{{slugKebabCase}}', {
 							? context.publicWriteToken
 							: undefined,
 					resourceKey: context.resourceKey,
-				}, context.restNonce );
+				}, {
+					restNonce: context.restNonce,
+					transportTarget: 'frontend',
+				} );
 				if ( ! result.isValid || ! result.data ) {
 					state.error = result.errors[ 0 ]?.expected ?? 'Unable to update counter';
 					return;

package/templates/_shared/compound/persistence/src/blocks/{{slugKebabCase}}/transport.ts.mustache

@@ -0,0 +1,254 @@
+import {
+	type EndpointCallOptions,
+	resolveRestRouteUrl,
+} from '@wp-typia/rest';
+
+export type PersistenceTransportTarget = 'editor' | 'frontend';
+export type PersistenceTransportOperation = 'read' | 'write';
+
+export interface PersistenceTransportOptions {
+	restNonce?: string;
+	transportTarget?: PersistenceTransportTarget;
+}
+
+interface EndpointWithPath {
+	path: string;
+}
+
+type PersistenceTransportResolver = (
+	endpoint: EndpointWithPath,
+	request?: unknown,
+	options?: PersistenceTransportOptions
+) => EndpointCallOptions;
+
+interface PersistenceTransportTargetResolvers {
+	read: PersistenceTransportResolver;
+	write: PersistenceTransportResolver;
+}
+
+// Replace any of these base URLs to route a given target through a contract-compatible proxy or BFF.
+const EDITOR_READ_BASE_URL: string | undefined = undefined;
+const EDITOR_WRITE_BASE_URL: string | undefined = undefined;
+const FRONTEND_READ_BASE_URL: string | undefined = undefined;
+const FRONTEND_WRITE_BASE_URL: string | undefined = undefined;
+
+function resolveEndpointUrl(
+	endpointPath: string,
+	baseUrl?: string
+): string {
+	if ( typeof baseUrl === 'string' && baseUrl.trim().length > 0 ) {
+		const origin =
+			typeof window !== 'undefined' ? window.location.origin : 'http://localhost';
+		const resolvedBaseUrl = new URL( baseUrl.trim(), origin );
+		const [ pathWithQuery, hash = '' ] = endpointPath.split( '#', 2 );
+		const [ rawPath, rawQuery = '' ] = pathWithQuery.split( '?', 2 );
+		const normalizedEndpointPath = rawPath.replace( /^\/+/, '' );
+
+		if ( resolvedBaseUrl.searchParams.has( 'rest_route' ) ) {
+			const restRouteBase = resolvedBaseUrl.searchParams.get( 'rest_route' ) ?? '/';
+			const normalizedRestRouteBase = restRouteBase
+				.replace( /^\/+/, '' )
+				.replace( /\/+$/, '' );
+			const nextRestRoute = normalizedRestRouteBase.length > 0
+				? `/${ normalizedRestRouteBase }/${ normalizedEndpointPath }`
+				: `/${ normalizedEndpointPath }`;
+			resolvedBaseUrl.searchParams.set( 'rest_route', nextRestRoute );
+		} else {
+			const basePath = resolvedBaseUrl.pathname.endsWith( '/' )
+				? resolvedBaseUrl.pathname
+				: `${ resolvedBaseUrl.pathname }/`;
+			resolvedBaseUrl.pathname = `${ basePath }${ normalizedEndpointPath }`;
+		}
+
+		for ( const [ key, value ] of new URLSearchParams( rawQuery ) ) {
+			resolvedBaseUrl.searchParams.append( key, value );
+		}
+
+		if ( hash ) {
+			resolvedBaseUrl.hash = hash;
+		}
+
+		return resolvedBaseUrl.toString();
+	}
+
+	return resolveRestRouteUrl( endpointPath );
+}
+
+function isPlainObject(
+	value: unknown
+): value is Record< string, unknown > {
+	if ( Object.prototype.toString.call( value ) !== '[object Object]' ) {
+		return false;
+	}
+
+	const prototype = Object.getPrototypeOf( value );
+	return prototype === null || prototype === Object.prototype;
+}
+
+function encodeRequestQuery( request: unknown ): string {
+	if ( request === undefined || request === null ) {
+		return '';
+	}
+
+	if ( request instanceof URLSearchParams ) {
+		return request.toString();
+	}
+
+	if ( ! isPlainObject( request ) ) {
+		throw new Error(
+			'Persistence transport read requests must be plain objects or URLSearchParams.'
+		);
+	}
+
+	const params = new URLSearchParams();
+
+	for ( const [ key, value ] of Object.entries( request ) ) {
+		if ( value === undefined || value === null ) {
+			continue;
+		}
+
+		if ( Array.isArray( value ) ) {
+			for ( const item of value ) {
+				params.append( key, String( item ) );
+			}
+			continue;
+		}
+
+		params.set( key, String( value ) );
+	}
+
+	return params.toString();
+}
+
+function joinUrlWithQuery(
+	url: string,
+	query: string
+): string {
+	if ( ! query ) {
+		return url;
+	}
+
+	const nextUrl = new URL(
+		url,
+		typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
+	);
+
+	for ( const [ key, value ] of new URLSearchParams( query ) ) {
+		nextUrl.searchParams.append( key, value );
+	}
+
+	return nextUrl.toString();
+}
+
+export function resolveRestNonce( fallback?: string ): string | undefined {
+	if ( typeof fallback === 'string' && fallback.length > 0 ) {
+		return fallback;
+	}
+
+	if ( typeof window === 'undefined' ) {
+		return undefined;
+	}
+
+	const wpApiSettings = ( window as typeof window & {
+		wpApiSettings?: { nonce?: string };
+	} ).wpApiSettings;
+
+	return typeof wpApiSettings?.nonce === 'string' && wpApiSettings.nonce.length > 0
+		? wpApiSettings.nonce
+		: undefined;
+}
+
+function buildCallOptions( {
+	baseUrl,
+	endpoint,
+	includeRestNonce,
+	operation,
+	options,
+	request,
+}: {
+	baseUrl?: string;
+	endpoint: EndpointWithPath;
+	includeRestNonce: boolean;
+	operation: PersistenceTransportOperation;
+	options?: PersistenceTransportOptions;
+	request?: unknown;
+} ): EndpointCallOptions {
+	const nonce = includeRestNonce ? resolveRestNonce( options?.restNonce ) : undefined;
+	const requestOptions: EndpointCallOptions['requestOptions'] = {};
+
+	if ( nonce ) {
+		requestOptions.headers = {
+			'X-WP-Nonce': nonce,
+		};
+	}
+
+	if ( typeof baseUrl === 'string' && baseUrl.trim().length > 0 ) {
+		const endpointUrl = resolveEndpointUrl( endpoint.path, baseUrl );
+		requestOptions.url =
+			operation === 'read'
+				? joinUrlWithQuery( endpointUrl, encodeRequestQuery( request ) )
+				: endpointUrl;
+	}
+
+	return Object.keys( requestOptions ).length > 0
+		? {
+				requestOptions,
+			}
+		: {};
+}
+
+export const persistenceTransportTargets: Record<
+	PersistenceTransportTarget,
+	PersistenceTransportTargetResolvers
+> = {
+	editor: {
+		read: ( endpoint, request, options ) =>
+			buildCallOptions( {
+				baseUrl: EDITOR_READ_BASE_URL,
+				endpoint,
+				includeRestNonce: {{isAuthenticatedPersistencePolicy}},
+				operation: 'read',
+				options,
+				request,
+			} ),
+		write: ( endpoint, request, options ) =>
+			buildCallOptions( {
+				baseUrl: EDITOR_WRITE_BASE_URL,
+				endpoint,
+				includeRestNonce: {{isAuthenticatedPersistencePolicy}},
+				operation: 'write',
+				options,
+				request,
+			} ),
+	},
+	frontend: {
+		read: ( endpoint, request, options ) =>
+			buildCallOptions( {
+				baseUrl: FRONTEND_READ_BASE_URL,
+				endpoint,
+				includeRestNonce: false,
+				operation: 'read',
+				options,
+				request,
+			} ),
+		write: ( endpoint, request, options ) =>
+			buildCallOptions( {
+				baseUrl: FRONTEND_WRITE_BASE_URL,
+				endpoint,
+				includeRestNonce: {{isAuthenticatedPersistencePolicy}},
+				operation: 'write',
+				options,
+				request,
+			} ),
+	},
+};
+
+export function resolveTransportCallOptions(
+	target: PersistenceTransportTarget,
+	operation: PersistenceTransportOperation,
+	endpoint: EndpointWithPath,
+	request?: unknown,
+	options?: PersistenceTransportOptions
+): EndpointCallOptions {
+	return persistenceTransportTargets[ target ][ operation ]( endpoint, request, options );
+}

package/templates/_shared/persistence/core/src/api.ts.mustache

@@ -1,6 +1,5 @@
 import {
 	callEndpoint,
-	resolveRestRouteUrl,
 } from '@wp-typia/rest';
 
 import {
@@ -11,58 +10,49 @@ import {
 	get{{pascalCase}}StateEndpoint,
 	write{{pascalCase}}StateEndpoint,
 } from './api-client';
-
-export function resolveRestNonce( fallback?: string ): string | undefined {
-	if ( typeof fallback === 'string' && fallback.length > 0 ) {
-		return fallback;
-	}
-
-	if ( typeof window === 'undefined' ) {
-		return undefined;
-	}
-
-	const wpApiSettings = ( window as typeof window & {
-		wpApiSettings?: { nonce?: string };
-	} ).wpApiSettings;
-
-	return typeof wpApiSettings?.nonce === 'string' && wpApiSettings.nonce.length > 0
-		? wpApiSettings.nonce
-		: undefined;
-}
+import {
+	resolveTransportCallOptions,
+	type PersistenceTransportOptions,
+} from './transport';
 
 export const stateEndpoint = {
 	...get{{pascalCase}}StateEndpoint,
-	buildRequestOptions: () => ( {
-		url: resolveRestRouteUrl( get{{pascalCase}}StateEndpoint.path ),
-	} ),
 };
 
 export const writeStateEndpoint = {
 	...write{{pascalCase}}StateEndpoint,
-	buildRequestOptions: () => ( {
-		url: resolveRestRouteUrl( write{{pascalCase}}StateEndpoint.path ),
-	} ),
 };
 
 export function fetchState(
-	request: {{pascalCase}}StateQuery
+	request: {{pascalCase}}StateQuery,
+	options: PersistenceTransportOptions = {}
 ) {
-	return callEndpoint( stateEndpoint, request );
+	return callEndpoint(
+		stateEndpoint,
+		request,
+		resolveTransportCallOptions(
+			options.transportTarget ?? 'frontend',
+			'read',
+			stateEndpoint,
+			request,
+			options
+		)
+	);
 }
 
 export function writeState(
 	request: {{pascalCase}}WriteStateRequest,
-	restNonce?: string
+	options: PersistenceTransportOptions = {}
 ) {
-	const nonce = resolveRestNonce( restNonce );
-
-	return callEndpoint( writeStateEndpoint, request, {
-		requestOptions: nonce
-			? {
-					headers: {
-						'X-WP-Nonce': nonce,
-					},
-				}
-			: undefined,
-	} );
+	return callEndpoint(
+		writeStateEndpoint,
+		request,
+		resolveTransportCallOptions(
+			options.transportTarget ?? 'frontend',
+			'write',
+			writeStateEndpoint,
+			request,
+			options
+		)
+	);
 }

package/templates/_shared/persistence/core/src/data.ts.mustache

@@ -11,26 +11,13 @@ import type {
 	{{pascalCase}}WriteStateRequest,
 } from './api-types';
 import {
-	resolveRestNonce,
 	stateEndpoint,
 	writeStateEndpoint,
 } from './api';
-
-{{#isAuthenticatedPersistencePolicy}}
-function buildWriteCallOptions( restNonce?: string ) {
-	const nonce = resolveRestNonce( restNonce );
-
-	return nonce
-		? {
-				requestOptions: {
-					headers: {
-						'X-WP-Nonce': nonce,
-					},
-				},
-			}
-		: undefined;
-}
-{{/isAuthenticatedPersistencePolicy}}
+import {
+	resolveTransportCallOptions,
+	type PersistenceTransportTarget,
+} from './transport';
 
 interface WriteStateMutationContext< Context > {
 	previous:
@@ -49,9 +36,8 @@ export interface Use{{pascalCase}}StateQueryOptions<
 	>,
 	'resolveCallOptions'
 > {
-	{{#isAuthenticatedPersistencePolicy}}
 	restNonce?: string;
-	{{/isAuthenticatedPersistencePolicy}}
+	transportTarget?: PersistenceTransportTarget;
 }
 
 export interface UseWrite{{pascalCase}}StateMutationOptions<
@@ -62,7 +48,7 @@ export interface UseWrite{{pascalCase}}StateMutationOptions<
 		{{pascalCase}}StateResponse,
 		WriteStateMutationContext< Context >
 	>,
-	'invalidate' | 'onError' | 'onMutate'{{#isAuthenticatedPersistencePolicy}} | 'resolveCallOptions'{{/isAuthenticatedPersistencePolicy}}
+	'invalidate' | 'onError' | 'onMutate' | 'resolveCallOptions'
 > {
 	onError?: (
 		error: unknown,
@@ -74,9 +60,8 @@ export interface UseWrite{{pascalCase}}StateMutationOptions<
 		request: {{pascalCase}}WriteStateRequest,
 		client: import('@wp-typia/rest/react').EndpointDataClient
 	) => Context | Promise<Context>;
-	{{#isAuthenticatedPersistencePolicy}}
 	restNonce?: string;
-	{{/isAuthenticatedPersistencePolicy}}
+	transportTarget?: PersistenceTransportTarget;
 }
 
 export function use{{pascalCase}}StateQuery<
@@ -85,20 +70,26 @@ export function use{{pascalCase}}StateQuery<
 	request: {{pascalCase}}StateQuery,
 	options: Use{{pascalCase}}StateQueryOptions< Selected > = {}
 ) {
-	{{#isAuthenticatedPersistencePolicy}}
 	const {
 		restNonce,
+		transportTarget = 'editor',
 		...queryOptions
 	} = options;
 
 	return useEndpointQuery( stateEndpoint, request, {
 		...queryOptions,
-		resolveCallOptions: () => buildWriteCallOptions( restNonce ),
+		resolveCallOptions: () =>
+			resolveTransportCallOptions(
+				transportTarget,
+				'read',
+				stateEndpoint,
+				request,
+				{
+					restNonce,
+					transportTarget,
+				}
+			),
 	} );
-	{{/isAuthenticatedPersistencePolicy}}
-	{{^isAuthenticatedPersistencePolicy}}
-	return useEndpointQuery( stateEndpoint, request, options );
-	{{/isAuthenticatedPersistencePolicy}}
 }
 
 export function useWrite{{pascalCase}}StateMutation<
@@ -109,9 +100,8 @@ export function useWrite{{pascalCase}}StateMutation<
 	const {
 		onError,
 		onMutate,
-		{{#isAuthenticatedPersistencePolicy}}
 		restNonce,
-		{{/isAuthenticatedPersistencePolicy}}
+		transportTarget = 'editor',
 		...mutationOptions
 	} = options;
 
@@ -185,8 +175,16 @@ export function useWrite{{pascalCase}}StateMutation<
 				userContext,
 			};
 		},
-		{{#isAuthenticatedPersistencePolicy}}
-		resolveCallOptions: () => buildWriteCallOptions( restNonce ),
-		{{/isAuthenticatedPersistencePolicy}}
+		resolveCallOptions: ( request ) =>
+			resolveTransportCallOptions(
+				transportTarget,
+				'write',
+				writeStateEndpoint,
+				request,
+				{
+					restNonce,
+					transportTarget,
+				}
+			),
 	} );
 }

package/templates/_shared/persistence/core/src/interactivity.ts.mustache

@@ -48,6 +48,9 @@ const { actions, state } = store( '{{slugKebabCase}}', {
 				const result = await fetchState( {
 					postId: context.postId,
 					resourceKey: context.resourceKey,
+				}, {
+					restNonce: context.restNonce,
+					transportTarget: 'frontend',
 				} );
 				if ( ! result.isValid || ! result.data ) {
 					state.error = result.errors[ 0 ]?.expected ?? 'Unable to load counter';
@@ -97,7 +100,10 @@ const { actions, state } = store( '{{slugKebabCase}}', {
 							? context.publicWriteToken
 							: undefined,
 					resourceKey: context.resourceKey,
-				}, context.restNonce );
+				}, {
+					restNonce: context.restNonce,
+					transportTarget: 'frontend',
+				} );
 				if ( ! result.isValid || ! result.data ) {
 					state.error = result.errors[ 0 ]?.expected ?? 'Unable to update counter';
 					return;

package/templates/_shared/persistence/core/src/transport.ts.mustache

@@ -0,0 +1,254 @@
+import {
+	type EndpointCallOptions,
+	resolveRestRouteUrl,
+} from '@wp-typia/rest';
+
+export type PersistenceTransportTarget = 'editor' | 'frontend';
+export type PersistenceTransportOperation = 'read' | 'write';
+
+export interface PersistenceTransportOptions {
+	restNonce?: string;
+	transportTarget?: PersistenceTransportTarget;
+}
+
+interface EndpointWithPath {
+	path: string;
+}
+
+type PersistenceTransportResolver = (
+	endpoint: EndpointWithPath,
+	request?: unknown,
+	options?: PersistenceTransportOptions
+) => EndpointCallOptions;
+
+interface PersistenceTransportTargetResolvers {
+	read: PersistenceTransportResolver;
+	write: PersistenceTransportResolver;
+}
+
+// Replace any of these base URLs to route a given target through a contract-compatible proxy or BFF.
+const EDITOR_READ_BASE_URL: string | undefined = undefined;
+const EDITOR_WRITE_BASE_URL: string | undefined = undefined;
+const FRONTEND_READ_BASE_URL: string | undefined = undefined;
+const FRONTEND_WRITE_BASE_URL: string | undefined = undefined;
+
+function resolveEndpointUrl(
+	endpointPath: string,
+	baseUrl?: string
+): string {
+	if ( typeof baseUrl === 'string' && baseUrl.trim().length > 0 ) {
+		const origin =
+			typeof window !== 'undefined' ? window.location.origin : 'http://localhost';
+		const resolvedBaseUrl = new URL( baseUrl.trim(), origin );
+		const [ pathWithQuery, hash = '' ] = endpointPath.split( '#', 2 );
+		const [ rawPath, rawQuery = '' ] = pathWithQuery.split( '?', 2 );
+		const normalizedEndpointPath = rawPath.replace( /^\/+/, '' );
+
+		if ( resolvedBaseUrl.searchParams.has( 'rest_route' ) ) {
+			const restRouteBase = resolvedBaseUrl.searchParams.get( 'rest_route' ) ?? '/';
+			const normalizedRestRouteBase = restRouteBase
+				.replace( /^\/+/, '' )
+				.replace( /\/+$/, '' );
+			const nextRestRoute = normalizedRestRouteBase.length > 0
+				? `/${ normalizedRestRouteBase }/${ normalizedEndpointPath }`
+				: `/${ normalizedEndpointPath }`;
+			resolvedBaseUrl.searchParams.set( 'rest_route', nextRestRoute );
+		} else {
+			const basePath = resolvedBaseUrl.pathname.endsWith( '/' )
+				? resolvedBaseUrl.pathname
+				: `${ resolvedBaseUrl.pathname }/`;
+			resolvedBaseUrl.pathname = `${ basePath }${ normalizedEndpointPath }`;
+		}
+
+		for ( const [ key, value ] of new URLSearchParams( rawQuery ) ) {
+			resolvedBaseUrl.searchParams.append( key, value );
+		}
+
+		if ( hash ) {
+			resolvedBaseUrl.hash = hash;
+		}
+
+		return resolvedBaseUrl.toString();
+	}
+
+	return resolveRestRouteUrl( endpointPath );
+}
+
+function isPlainObject(
+	value: unknown
+): value is Record< string, unknown > {
+	if ( Object.prototype.toString.call( value ) !== '[object Object]' ) {
+		return false;
+	}
+
+	const prototype = Object.getPrototypeOf( value );
+	return prototype === null || prototype === Object.prototype;
+}
+
+function encodeRequestQuery( request: unknown ): string {
+	if ( request === undefined || request === null ) {
+		return '';
+	}
+
+	if ( request instanceof URLSearchParams ) {
+		return request.toString();
+	}
+
+	if ( ! isPlainObject( request ) ) {
+		throw new Error(
+			'Persistence transport read requests must be plain objects or URLSearchParams.'
+		);
+	}
+
+	const params = new URLSearchParams();
+
+	for ( const [ key, value ] of Object.entries( request ) ) {
+		if ( value === undefined || value === null ) {
+			continue;
+		}
+
+		if ( Array.isArray( value ) ) {
+			for ( const item of value ) {
+				params.append( key, String( item ) );
+			}
+			continue;
+		}
+
+		params.set( key, String( value ) );
+	}
+
+	return params.toString();
+}
+
+function joinUrlWithQuery(
+	url: string,
+	query: string
+): string {
+	if ( ! query ) {
+		return url;
+	}
+
+	const nextUrl = new URL(
+		url,
+		typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
+	);
+
+	for ( const [ key, value ] of new URLSearchParams( query ) ) {
+		nextUrl.searchParams.append( key, value );
+	}
+
+	return nextUrl.toString();
+}
+
+export function resolveRestNonce( fallback?: string ): string | undefined {
+	if ( typeof fallback === 'string' && fallback.length > 0 ) {
+		return fallback;
+	}
+
+	if ( typeof window === 'undefined' ) {
+		return undefined;
+	}
+
+	const wpApiSettings = ( window as typeof window & {
+		wpApiSettings?: { nonce?: string };
+	} ).wpApiSettings;
+
+	return typeof wpApiSettings?.nonce === 'string' && wpApiSettings.nonce.length > 0
+		? wpApiSettings.nonce
+		: undefined;
+}
+
+function buildCallOptions( {
+	baseUrl,
+	endpoint,
+	includeRestNonce,
+	operation,
+	options,
+	request,
+}: {
+	baseUrl?: string;
+	endpoint: EndpointWithPath;
+	includeRestNonce: boolean;
+	operation: PersistenceTransportOperation;
+	options?: PersistenceTransportOptions;
+	request?: unknown;
+} ): EndpointCallOptions {
+	const nonce = includeRestNonce ? resolveRestNonce( options?.restNonce ) : undefined;
+	const requestOptions: EndpointCallOptions['requestOptions'] = {};
+
+	if ( nonce ) {
+		requestOptions.headers = {
+			'X-WP-Nonce': nonce,
+		};
+	}
+
+	if ( typeof baseUrl === 'string' && baseUrl.trim().length > 0 ) {
+		const endpointUrl = resolveEndpointUrl( endpoint.path, baseUrl );
+		requestOptions.url =
+			operation === 'read'
+				? joinUrlWithQuery( endpointUrl, encodeRequestQuery( request ) )
+				: endpointUrl;
+	}
+
+	return Object.keys( requestOptions ).length > 0
+		? {
+				requestOptions,
+			}
+		: {};
+}
+
+export const persistenceTransportTargets: Record<
+	PersistenceTransportTarget,
+	PersistenceTransportTargetResolvers
+> = {
+	editor: {
+		read: ( endpoint, request, options ) =>
+			buildCallOptions( {
+				baseUrl: EDITOR_READ_BASE_URL,
+				endpoint,
+				includeRestNonce: {{isAuthenticatedPersistencePolicy}},
+				operation: 'read',
+				options,
+				request,
+			} ),
+		write: ( endpoint, request, options ) =>
+			buildCallOptions( {
+				baseUrl: EDITOR_WRITE_BASE_URL,
+				endpoint,
+				includeRestNonce: {{isAuthenticatedPersistencePolicy}},
+				operation: 'write',
+				options,
+				request,
+			} ),
+	},
+	frontend: {
+		read: ( endpoint, request, options ) =>
+			buildCallOptions( {
+				baseUrl: FRONTEND_READ_BASE_URL,
+				endpoint,
+				includeRestNonce: false,
+				operation: 'read',
+				options,
+				request,
+			} ),
+		write: ( endpoint, request, options ) =>
+			buildCallOptions( {
+				baseUrl: FRONTEND_WRITE_BASE_URL,
+				endpoint,
+				includeRestNonce: {{isAuthenticatedPersistencePolicy}},
+				operation: 'write',
+				options,
+				request,
+			} ),
+	},
+};
+
+export function resolveTransportCallOptions(
+	target: PersistenceTransportTarget,
+	operation: PersistenceTransportOperation,
+	endpoint: EndpointWithPath,
+	request?: unknown,
+	options?: PersistenceTransportOptions
+): EndpointCallOptions {
+	return persistenceTransportTargets[ target ][ operation ]( endpoint, request, options );
+}