@wp-typia/project-tools 0.13.4 → 0.15.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, `src/save.tsx` returns `null`, and session-only write data now refreshes through the dedicated `/bootstrap` endpoint after hydration instead of being frozen into markup.";
     }
     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,14 +86,17 @@ 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",
+            extraNote: "Keep durable state on the `/state` endpoints and treat the dedicated `/bootstrap` endpoint as the place to return fresh session-only write access data such as nonces or public write tokens.",
         });
     }
     if (templateId === "compound" && compoundPersistenceEnabled) {
         return formatPhpRestExtensionPointsSection({
             apiTypesPath: `src/blocks/${slug}/api-types.ts`,
-            extraNote: "The hidden child block does not own REST routes or storage.",
+            extraNote: "The hidden child block does not own REST routes or storage. Keep durable parent-block state on the `/state` endpoints and return fresh session-only write access data from the dedicated `/bootstrap` endpoint.",
             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/dist/runtime/scaffold.d.ts

@@ -56,6 +56,7 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     phpPrefixUpper: string;
     isAuthenticatedPersistencePolicy: "false" | "true";
     isPublicPersistencePolicy: "false" | "true";
+    bootstrapCredentialDeclarations: string;
     publicWriteRequestIdDeclaration: string;
     restPackageVersion: string;
     restWriteAuthIntent: "authenticated" | "public-write-protected";

package/dist/runtime/scaffold.js

@@ -262,6 +262,9 @@ export function getTemplateVariables(templateId, answers) {
         frontendCssClassName: buildFrontendCssClassName(cssClassName),
         isAuthenticatedPersistencePolicy: persistencePolicy === "authenticated" ? "true" : "false",
         isPublicPersistencePolicy: persistencePolicy === "public" ? "true" : "false",
+        bootstrapCredentialDeclarations: persistencePolicy === "public"
+            ? "publicWriteExpiresAt?: number & tags.Type< 'uint32' >;\n\tpublicWriteToken?: string & tags.MinLength< 1 > & tags.MaxLength< 512 >;"
+            : "restNonce?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
         keyword: slug.replace(/-/g, " "),
         namespace,
         needsMigration: "{{needsMigration}}",

package/dist/runtime/schema-core.d.ts

@@ -59,6 +59,7 @@ export interface OpenApiResponse extends JsonSchemaObject {
         "application/json": OpenApiMediaType;
     };
     description: string;
+    headers?: Record<string, JsonSchemaObject>;
 }
 /**
  * Header-based security scheme used by authenticated WordPress REST routes.

package/dist/runtime/schema-core.js

@@ -149,15 +149,35 @@ function applyProjectedTypeTag(schema, typeTag, path) {
             throw new Error(`Unsupported wp-typia schema type tag "${typeTag}" at "${path}".`);
     }
 }
+function canProjectTypeTag(typeTag) {
+    switch (typeTag) {
+        case "uint32":
+        case "int32":
+        case "float":
+        case "double":
+            return true;
+        default:
+            return false;
+    }
+}
 function projectSchemaArrayItemsForAiStructuredOutput(items, path) {
     return items.map((item, index) => projectSchemaObjectForAiStructuredOutput(item, `${path}/${index}`));
 }
+function projectSchemaArrayItemsForRest(items, path) {
+    return items.map((item, index) => projectSchemaObjectForRest(item, `${path}/${index}`));
+}
 function projectSchemaPropertyMapForAiStructuredOutput(properties, path) {
     return Object.fromEntries(Object.entries(properties).map(([key, value]) => [
         key,
         projectSchemaObjectForAiStructuredOutput(value, `${path}/${key}`),
     ]));
 }
+function projectSchemaPropertyMapForRest(properties, path) {
+    return Object.fromEntries(Object.entries(properties).map(([key, value]) => [
+        key,
+        projectSchemaObjectForRest(value, `${path}/${key}`),
+    ]));
+}
 function projectSchemaObjectForAiStructuredOutput(node, path) {
     const projectedNode = cloneJsonSchemaNode(node);
     const rawTypeTag = projectedNode[WP_TYPIA_OPENAPI_EXTENSION_KEYS.TYPE_TAG];
@@ -188,6 +208,126 @@ function projectSchemaObjectForAiStructuredOutput(node, path) {
     }
     return projectedNode;
 }
+function projectSchemaObjectForRest(node, path) {
+    const projectedNode = cloneJsonSchemaNode(node);
+    const rawTypeTag = projectedNode[WP_TYPIA_OPENAPI_EXTENSION_KEYS.TYPE_TAG];
+    if (typeof rawTypeTag === "string" && canProjectTypeTag(rawTypeTag)) {
+        applyProjectedTypeTag(projectedNode, rawTypeTag, path);
+    }
+    for (const key of Object.keys(projectedNode)) {
+        const child = projectedNode[key];
+        if (Array.isArray(child)) {
+            projectedNode[key] = child.every(isJsonSchemaObject)
+                ? projectSchemaArrayItemsForRest(child, `${path}/${key}`)
+                : child;
+            continue;
+        }
+        if (!isJsonSchemaObject(child)) {
+            continue;
+        }
+        if (key === "properties") {
+            projectedNode[key] = projectSchemaPropertyMapForRest(child, `${path}/${key}`);
+            continue;
+        }
+        projectedNode[key] = projectSchemaObjectForRest(child, `${path}/${key}`);
+    }
+    applyProjectedBootstrapContract(projectedNode);
+    return projectedNode;
+}
+function applyProjectedBootstrapContract(schema) {
+    if (schema.type !== "object" || !isJsonSchemaObject(schema.properties)) {
+        return;
+    }
+    const properties = schema.properties;
+    const buildRequiredPropertyObject = (requiredKeys) => Object.fromEntries(requiredKeys.map((requiredKey) => [requiredKey, properties[requiredKey] ?? {}]));
+    if (properties.canWrite?.type !== "boolean") {
+        return;
+    }
+    const allOf = Array.isArray(schema.allOf)
+        ? [...schema.allOf]
+        : [];
+    const canWriteIsTrue = {
+        properties: {
+            canWrite: {
+                const: true,
+            },
+        },
+        required: ["canWrite"],
+    };
+    const hasRestNonce = properties.restNonce?.type === "string";
+    const hasPublicWriteCredential = properties.publicWriteToken?.type === "string" &&
+        isJsonSchemaObject(properties.publicWriteExpiresAt);
+    if (hasRestNonce && hasPublicWriteCredential) {
+        allOf.push({
+            if: canWriteIsTrue,
+            then: {
+                anyOf: [
+                    {
+                        properties: buildRequiredPropertyObject(["restNonce"]),
+                        required: ["restNonce"],
+                    },
+                    {
+                        properties: buildRequiredPropertyObject([
+                            "publicWriteExpiresAt",
+                            "publicWriteToken",
+                        ]),
+                        required: ["publicWriteExpiresAt", "publicWriteToken"],
+                    },
+                ],
+            },
+            else: {
+                not: {
+                    anyOf: [
+                        {
+                            properties: buildRequiredPropertyObject(["restNonce"]),
+                            required: ["restNonce"],
+                        },
+                        {
+                            properties: buildRequiredPropertyObject(["publicWriteToken"]),
+                            required: ["publicWriteToken"],
+                        },
+                    ],
+                },
+            },
+        });
+    }
+    if (hasRestNonce && !hasPublicWriteCredential) {
+        allOf.push({
+            if: canWriteIsTrue,
+            then: {
+                properties: buildRequiredPropertyObject(["restNonce"]),
+                required: ["restNonce"],
+            },
+            else: {
+                not: {
+                    properties: buildRequiredPropertyObject(["restNonce"]),
+                    required: ["restNonce"],
+                },
+            },
+        });
+    }
+    if (hasPublicWriteCredential && !hasRestNonce) {
+        allOf.push({
+            if: canWriteIsTrue,
+            then: {
+                properties: buildRequiredPropertyObject([
+                    "publicWriteExpiresAt",
+                    "publicWriteToken",
+                ]),
+                required: ["publicWriteExpiresAt", "publicWriteToken"],
+            },
+            else: {
+                not: {
+                    properties: buildRequiredPropertyObject(["publicWriteToken"]),
+                    required: ["publicWriteToken"],
+                },
+            },
+        });
+    }
+    if (allOf.length > 0) {
+        schema.allOf = allOf;
+    }
+}
 function manifestUnionToJsonSchema(union) {
     const oneOf = Object.entries(union.branches).map(([branchKey, branch]) => {
         if (branch.ts.kind !== "object") {
@@ -305,7 +445,7 @@ export function manifestToJsonSchema(doc) {
  */
 export function projectJsonSchemaDocument(schema, options) {
     if (options.profile === "rest") {
-        return cloneJsonSchemaNode(schema);
+        return projectSchemaObjectForRest(schema, "#");
     }
     if (options.profile === "ai-structured-output") {
         return projectSchemaObjectForAiStructuredOutput(schema, "#");
@@ -321,10 +461,14 @@ export function projectJsonSchemaDocument(schema, options) {
  */
 export function manifestToOpenApi(doc, info = {}) {
     const schemaName = doc.sourceType ?? "TypiaDocument";
+    const projectedSchema = projectJsonSchemaDocument(manifestToJsonSchema(doc), {
+        profile: "rest",
+    });
+    delete projectedSchema.$schema;
     return {
         components: {
             schemas: {
-                [schemaName]: manifestToJsonSchema(doc),
+                [schemaName]: projectedSchema,
             },
         },
         info: {
@@ -486,7 +630,36 @@ function buildQueryParameters(contract) {
         schema: manifestAttributeToJsonSchema(attribute),
     }));
 }
-function createSuccessResponse(schemaName) {
+function createBootstrapResponseHeaders(normalizedAuth) {
+    const headers = {
+        "Cache-Control": {
+            description: "Must be non-cacheable for fresh bootstrap write/session state.",
+            schema: {
+                type: "string",
+                example: "private, no-store, no-cache, must-revalidate",
+            },
+        },
+        Pragma: {
+            description: "Legacy non-cacheable bootstrap response directive.",
+            schema: {
+                type: "string",
+                example: "no-cache",
+            },
+        },
+    };
+    if (normalizedAuth.wordpressAuth?.mechanism ===
+        WP_TYPIA_OPENAPI_LITERALS.WORDPRESS_REST_NONCE_MECHANISM) {
+        headers.Vary = {
+            description: "Viewer-aware bootstrap responses should vary on cookie-backed auth state.",
+            schema: {
+                type: "string",
+                example: "Cookie",
+            },
+        };
+    }
+    return headers;
+}
+function createSuccessResponse(schemaName, headers) {
     return {
         content: {
             [WP_TYPIA_OPENAPI_LITERALS.JSON_CONTENT_TYPE]: {
@@ -494,14 +667,18 @@ function createSuccessResponse(schemaName) {
             },
         },
         description: WP_TYPIA_OPENAPI_LITERALS.SUCCESS_RESPONSE_DESCRIPTION,
+        ...(headers ? { headers } : {}),
     };
 }
 function buildEndpointOpenApiOperation(endpoint, contracts) {
     const normalizedAuth = normalizeEndpointAuthDefinition(endpoint);
+    const isBootstrapEndpoint = endpoint.path.endsWith("/bootstrap");
     const operation = {
         operationId: endpoint.operationId,
         responses: {
-            "200": createSuccessResponse(getContractSchemaName(endpoint.responseContract, contracts[endpoint.responseContract], endpoint, "response")),
+            "200": createSuccessResponse(getContractSchemaName(endpoint.responseContract, contracts[endpoint.responseContract], endpoint, "response"), isBootstrapEndpoint
+                ? createBootstrapResponseHeaders(normalizedAuth)
+                : undefined),
         },
         tags: [...endpoint.tags],
         [WP_TYPIA_OPENAPI_EXTENSION_KEYS.AUTH_INTENT]: normalizedAuth.auth,
@@ -554,10 +731,13 @@ function buildEndpointOpenApiOperation(endpoint, contracts) {
  */
 export function buildEndpointOpenApiDocument(options) {
     const contractEntries = Object.entries(options.contracts);
-    const schemas = Object.fromEntries(contractEntries.map(([contractKey, contract]) => [
-        getContractSchemaName(contractKey, contract),
-        manifestToJsonSchema(contract.document),
-    ]));
+    const schemas = Object.fromEntries(contractEntries.map(([contractKey, contract]) => {
+        const projectedSchema = projectJsonSchemaDocument(manifestToJsonSchema(contract.document), {
+            profile: "rest",
+        });
+        delete projectedSchema.$schema;
+        return [getContractSchemaName(contractKey, contract), projectedSchema];
+    }));
     const paths = {};
     const topLevelTags = [...new Set(options.endpoints.flatMap((endpoint) => endpoint.tags))]
         .filter((tag) => typeof tag === "string" && tag.length > 0)

package/package.json

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

package/templates/_shared/compound/persistence/scripts/block-config.ts.mustache

@@ -9,9 +9,15 @@ export const BLOCKS = [
 				'state-query': {
 					sourceTypeName: '{{pascalCase}}StateQuery',
 				},
+				'bootstrap-query': {
+					sourceTypeName: '{{pascalCase}}BootstrapQuery',
+				},
 				'write-state-request': {
 					sourceTypeName: '{{pascalCase}}WriteStateRequest',
 				},
+				'bootstrap-response': {
+					sourceTypeName: '{{pascalCase}}BootstrapResponse',
+				},
 				'state-response': {
 					sourceTypeName: '{{pascalCase}}StateResponse',
 				},
@@ -40,6 +46,16 @@ export const BLOCKS = [
 						mechanism: '{{restWriteAuthMechanism}}',
 					},
 				},
+				{
+					auth: 'public',
+					method: 'GET',
+					operationId: 'get{{pascalCase}}Bootstrap',
+					path: '/{{namespace}}/v1/{{slugKebabCase}}/bootstrap',
+					queryContract: 'bootstrap-query',
+					responseContract: 'bootstrap-response',
+					summary: 'Read fresh session bootstrap state for the current viewer.',
+					tags: [ '{{title}}' ],
+				},
 			],
 			info: {
 				title: '{{title}} REST API',

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

@@ -5,6 +5,11 @@ export interface {{pascalCase}}StateQuery {
 	resourceKey: string & tags.MinLength< 1 > & tags.MaxLength< 100 >;
 }
 
+export interface {{pascalCase}}BootstrapQuery {
+	postId: number & tags.Type< 'uint32' >;
+	resourceKey: string & tags.MinLength< 1 > & tags.MaxLength< 100 >;
+}
+
 export interface {{pascalCase}}WriteStateRequest {
 	postId: number & tags.Type< 'uint32' >;
 	{{publicWriteRequestIdDeclaration}}
@@ -13,6 +18,11 @@ export interface {{pascalCase}}WriteStateRequest {
 	delta?: number & tags.Minimum< 1 > & tags.Type< 'uint32' > & tags.Default< 1 >;
 }
 
+export interface {{pascalCase}}BootstrapResponse {
+	canWrite: boolean;
+	{{bootstrapCredentialDeclarations}}
+}
+
 export interface {{pascalCase}}StateResponse {
 	postId: number & tags.Type< 'uint32' >;
 	resourceKey: string & tags.MinLength< 1 > & tags.MaxLength< 100 >;

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

@@ -1,68 +1,81 @@
 import {
 	callEndpoint,
-	resolveRestRouteUrl,
 } from '@wp-typia/rest';
 
 import {
+	type {{pascalCase}}BootstrapQuery,
 	type {{pascalCase}}StateQuery,
 	type {{pascalCase}}WriteStateRequest,
 } from './api-types';
 import {
+	get{{pascalCase}}BootstrapEndpoint,
 	get{{pascalCase}}StateEndpoint,
 	write{{pascalCase}}StateEndpoint,
 } from './api-client';
+import {
+	resolveTransportCallOptions,
+	type PersistenceTransportOptions,
+} from './transport';
 
-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;
-}
+export const bootstrapEndpoint = {
+	...get{{pascalCase}}BootstrapEndpoint,
+};
 
 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 fetchBootstrap(
+	request: {{pascalCase}}BootstrapQuery,
+	options: PersistenceTransportOptions = {}
+) {
+	return callEndpoint(
+		bootstrapEndpoint,
+		request,
+		resolveTransportCallOptions(
+			options.transportTarget ?? 'frontend',
+			'read',
+			bootstrapEndpoint,
+			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
+		)
+	);
 }