@wp-typia/block-runtime 0.3.0 → 0.4.2

package/README.md

@@ -25,9 +25,8 @@ import { createNestedAttributeUpdater } from "@wp-typia/block-runtime/validation
 import { runSyncBlockMetadata } from "@wp-typia/block-runtime/metadata-core";
 ```
 
-`@wp-typia/create` remains the CLI/scaffolding package.
+`wp-typia` remains the CLI package.
 
-`@wp-typia/create/metadata-core` and `@wp-typia/create/runtime/*` remain
-available as backward-compatible facades, but newly generated projects should
-prefer `@wp-typia/block-runtime/*` and
-`@wp-typia/block-runtime/metadata-core`.
+`@wp-typia/project-tools` is the canonical programmatic project orchestration
+package, while newly generated projects should prefer `@wp-typia/block-runtime/*`
+and `@wp-typia/block-runtime/metadata-core`.

package/dist/identifiers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Generate a UUID v4-style id for block attributes.
+ */
+export declare function generateBlockId(): string;
+/**
+ * Generate a prefixed runtime id for client-side attributes such as uniqueId.
+ * @param prefix Prefix chosen by the scaffold/template.
+ */
+export declare function generateScopedClientId(prefix: string): string;
+/**
+ * Generate a prefixed persistence resource key.
+ * @param prefix Prefix chosen by the scaffold/template.
+ */
+export declare function generateResourceKey(prefix: string): string;
+/**
+ * Generate an opaque id for one public write attempt.
+ */
+export declare function generatePublicWriteRequestId(): string;

package/dist/identifiers.js

@@ -0,0 +1,84 @@
+const UUID_HEX_RADIX = 16;
+const SCOPED_SUFFIX_LENGTH = 9;
+/**
+ * Generate a UUID v4-style id for block attributes.
+ */
+export function generateBlockId() {
+    return generateUuidV4();
+}
+/**
+ * Generate a prefixed runtime id for client-side attributes such as uniqueId.
+ * @param prefix Prefix chosen by the scaffold/template.
+ */
+export function generateScopedClientId(prefix) {
+    return generatePrefixedScopedId(prefix);
+}
+/**
+ * Generate a prefixed persistence resource key.
+ * @param prefix Prefix chosen by the scaffold/template.
+ */
+export function generateResourceKey(prefix) {
+    return generatePrefixedScopedId(prefix);
+}
+/**
+ * Generate an opaque id for one public write attempt.
+ */
+export function generatePublicWriteRequestId() {
+    return generateUuidV4();
+}
+function generateUuidV4() {
+    const cryptoObject = getCryptoObject();
+    if (typeof cryptoObject?.randomUUID === 'function') {
+        return cryptoObject.randomUUID();
+    }
+    const bytes = fillRandomBytes(16);
+    if (bytes) {
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        return formatUuidBytes(bytes);
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (character) => {
+        const randomNibble = Math.floor(Math.random() * UUID_HEX_RADIX);
+        const value = character === 'x'
+            ? randomNibble
+            : (randomNibble & 0x03) | 0x08;
+        return value.toString(UUID_HEX_RADIX);
+    });
+}
+function generatePrefixedScopedId(prefix) {
+    return `${prefix}-${generateScopedSuffix()}`;
+}
+function generateScopedSuffix() {
+    const bytes = fillRandomBytes(SCOPED_SUFFIX_LENGTH);
+    if (bytes) {
+        return Array.from(bytes, (byte) => (byte % 36).toString(36)).join('');
+    }
+    return Math.random()
+        .toString(36)
+        .slice(2, 2 + SCOPED_SUFFIX_LENGTH)
+        .padEnd(SCOPED_SUFFIX_LENGTH, '0');
+}
+function formatUuidBytes(bytes) {
+    const hex = Array.from(bytes, (byte) => byte.toString(UUID_HEX_RADIX).padStart(2, '0')).join('');
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20),
+    ].join('-');
+}
+function fillRandomBytes(size) {
+    const cryptoObject = getCryptoObject();
+    if (typeof cryptoObject?.getRandomValues !== 'function') {
+        return null;
+    }
+    const bytes = new Uint8Array(size);
+    cryptoObject.getRandomValues(bytes);
+    return bytes;
+}
+function getCryptoObject() {
+    return typeof globalThis.crypto === 'object' && globalThis.crypto
+        ? globalThis.crypto
+        : undefined;
+}

package/dist/inspector-runtime.d.ts

@@ -125,5 +125,5 @@ export interface InspectorFromManifestProps<T extends UnknownRecord> {
 }
 export declare function useEditorFields(manifest: ManifestDocument, options?: EditorModelOptions): UseEditorFieldsResult;
 export declare function useTypedAttributeUpdater<T extends object>(attributes: T, setAttributes: (attrs: Partial<T>) => void, validate?: (value: T) => ValidationResult<T>): TypedAttributeUpdater<T>;
-export declare function FieldControl({ components, field, help, label, max, min, onChange, options, render, renderUnsupported, step, value, }: FieldControlProps): import("react/jsx-runtime.js").JSX.Element | null;
-export declare function InspectorFromManifest<T extends UnknownRecord>({ attributes, children, components, fieldLookup, fieldOverrides, initialOpen, onChange, paths, title, }: InspectorFromManifestProps<T>): import("react/jsx-runtime.js").JSX.Element;
+export declare function FieldControl({ components, field, help, label, max, min, onChange, options, render, renderUnsupported, step, value, }: FieldControlProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function InspectorFromManifest<T extends UnknownRecord>({ attributes, children, components, fieldLookup, fieldOverrides, initialOpen, onChange, paths, title, }: InspectorFromManifestProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/metadata-core.js

@@ -4,7 +4,7 @@ import { getTaggedSyncBlockMetadataFailureCode } from './metadata-analysis.js';
 import { renderPhpValidator } from './metadata-php-render.js';
 import { analyzeSourceType, analyzeSourceTypes } from './metadata-parser.js';
 import { createBlockJsonAttribute, createExampleValue, createManifestDocument, validateWordPressExtractionAttributes, } from './metadata-projection.js';
-import { buildEndpointOpenApiDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from './schema-core.js';
+import { buildEndpointOpenApiDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, projectJsonSchemaDocument, } from './schema-core.js';
 /**
  * Preserve literal TypeScript inference for backend-neutral endpoint manifests.
  *
@@ -251,7 +251,9 @@ export async function syncTypeSchemas(options, executionOptions = {}) {
         : undefined;
     reconcileGeneratedArtifacts([
         {
-            content: JSON.stringify(manifestToJsonSchema(manifest), null, '\t'),
+            content: JSON.stringify(projectJsonSchemaDocument(manifestToJsonSchema(manifest), {
+                profile: 'rest',
+            }), null, '\t'),
             path: jsonSchemaPath,
         },
         ...(openApiPath

package/dist/object-utils.js

@@ -1,7 +1,4 @@
+import { isPlainObject as isSharedPlainObject } from "@wp-typia/api-client/runtime-primitives";
 export function isPlainObject(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
+    return isSharedPlainObject(value);
 }

package/dist/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/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;
+    if (properties.canWrite?.type !== "boolean") {
+        return;
+    }
+    const allOf = Array.isArray(schema.allOf)
+        ? [...schema.allOf]
+        : [];
+    const canWriteIsTrue = {
+        properties: {
+            canWrite: {
+                const: true,
+            },
+        },
+        required: ["canWrite"],
+    };
+    const buildRequiredPropertyObject = (requiredKeys) => Object.fromEntries(requiredKeys.map((requiredKey) => [requiredKey, properties[requiredKey] ?? {}]));
+    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/dist/validation.d.ts

@@ -1,15 +1,7 @@
 import type { ManifestDefaultsDocument } from "./defaults.js";
-export interface TypiaValidationError {
-    description?: string;
-    expected: string;
-    path: string;
-    value: unknown;
-}
-export interface ValidationResult<T> {
-    data?: T;
-    errors: TypiaValidationError[];
-    isValid: boolean;
-}
+import { type ValidationError as SharedValidationError, type ValidationResult as SharedValidationResult } from "@wp-typia/api-client/runtime-primitives";
+export type TypiaValidationError = SharedValidationError;
+export type ValidationResult<T> = SharedValidationResult<T>;
 export interface ValidationState<T> extends ValidationResult<T> {
     errorMessages: string[];
 }

package/dist/validation.js

@@ -1,5 +1,5 @@
 import { applyTemplateDefaultsFromManifest } from "./defaults.js";
-import { isPlainObject as isRecord } from "./object-utils.js";
+import { isPlainObject as isRecord, normalizeValidationError as normalizeSharedValidationError, toValidationResult as toSharedValidationResult, } from "@wp-typia/api-client/runtime-primitives";
 const UNSAFE_PATH_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
 function getValueType(value) {
     if (value === null) {
@@ -18,33 +18,10 @@ function redactValidationErrors(errors) {
     }));
 }
 export function normalizeValidationError(error) {
-    const raw = error !== null && typeof error === "object"
-        ? error
-        : {};
-    return {
-        description: typeof raw.description === "string" ? raw.description : undefined,
-        expected: typeof raw.expected === "string" ? raw.expected : "unknown",
-        path: typeof raw.path === "string" && raw.path.length > 0 ? raw.path : "(root)",
-        value: Object.prototype.hasOwnProperty.call(raw, "value") ? raw.value : undefined,
-    };
+    return normalizeSharedValidationError(error);
 }
 export function toValidationResult(result) {
-    const raw = result !== null && typeof result === "object"
-        ? result
-        : undefined;
-    if (raw?.success === true) {
-        return {
-            data: raw.data,
-            errors: [],
-            isValid: true,
-        };
-    }
-    const rawErrors = Array.isArray(raw?.errors) ? raw.errors : [];
-    return {
-        data: undefined,
-        errors: rawErrors.map(normalizeValidationError),
-        isValid: false,
-    };
+    return toSharedValidationResult(result);
 }
 export function formatValidationError(error) {
     return `${error.path}: ${error.expected} expected, got ${getValueType(error.value)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/block-runtime",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "Generated-project runtime and metadata sync helpers for wp-typia",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,31 @@
       "import": "./dist/metadata-core.js",
       "default": "./dist/metadata-core.js"
     },
+    "./metadata-analysis": {
+      "types": "./dist/metadata-analysis.d.ts",
+      "import": "./dist/metadata-analysis.js",
+      "default": "./dist/metadata-analysis.js"
+    },
+    "./metadata-model": {
+      "types": "./dist/metadata-model.d.ts",
+      "import": "./dist/metadata-model.js",
+      "default": "./dist/metadata-model.js"
+    },
+    "./metadata-parser": {
+      "types": "./dist/metadata-parser.d.ts",
+      "import": "./dist/metadata-parser.js",
+      "default": "./dist/metadata-parser.js"
+    },
+    "./metadata-php-render": {
+      "types": "./dist/metadata-php-render.d.ts",
+      "import": "./dist/metadata-php-render.js",
+      "default": "./dist/metadata-php-render.js"
+    },
+    "./metadata-projection": {
+      "types": "./dist/metadata-projection.d.ts",
+      "import": "./dist/metadata-projection.js",
+      "default": "./dist/metadata-projection.js"
+    },
     "./defaults": {
       "types": "./dist/defaults.d.ts",
       "import": "./dist/defaults.js",
@@ -31,6 +56,11 @@
       "import": "./dist/editor.js",
       "default": "./dist/editor.js"
     },
+    "./identifiers": {
+      "types": "./dist/identifiers.d.ts",
+      "import": "./dist/identifiers.js",
+      "default": "./dist/identifiers.js"
+    },
     "./inspector": {
       "types": "./dist/inspector.d.ts",
       "import": "./dist/inspector.js",
@@ -41,6 +71,11 @@
       "import": "./dist/validation.js",
       "default": "./dist/validation.js"
     },
+    "./json-utils": {
+      "types": "./dist/json-utils.d.ts",
+      "import": "./dist/json-utils.js",
+      "default": "./dist/json-utils.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -49,7 +84,7 @@
     "package.json"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "bun run --filter @wp-typia/api-client build && rm -rf dist && tsc -p tsconfig.build.json",
     "clean": "rm -rf dist",
     "test:prepare": "bun run build",
     "test": "bun run test:prepare && bun test tests",
@@ -73,7 +108,7 @@
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0",
-    "bun": ">=1.3.10"
+    "bun": ">=1.3.11"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
@@ -84,6 +119,7 @@
     }
   },
   "dependencies": {
+    "@wp-typia/api-client": "^0.4.2",
     "typescript": "^5.9.2"
   },
   "devDependencies": {