@wp-typia/project-tools 0.22.9 → 0.23.0

package/dist/runtime/cli-add-workspace-rest-source-emitters.js

@@ -1,5 +1,5 @@
 import { quoteTsString, } from "./cli-add-shared.js";
-import { buildRestResourceEndpointManifest } from "./rest-resource-artifacts.js";
+import { buildManualRestContractEndpointManifest, buildRestResourceEndpointManifest, } from "./rest-resource-artifacts.js";
 import { toPascalCase, toTitleCase } from "./string-case.js";
 function indentMultiline(source, prefix) {
     return source
@@ -7,33 +7,287 @@ function indentMultiline(source, prefix) {
         .map((line) => `${prefix}${line}`)
         .join("\n");
 }
-export function buildRestResourceConfigEntry(restResourceSlug, namespace, methods) {
-    const pascalCase = toPascalCase(restResourceSlug);
-    const title = toTitleCase(restResourceSlug);
+/**
+ * Build a generated REST resource config entry for `scripts/block-config.ts`.
+ *
+ * @param options REST resource metadata. `restResourceSlug`, `namespace`, and
+ * `methods` are required; `controllerClass`, `controllerExtends`,
+ * `permissionCallback`, and `routePattern` opt into generated controller,
+ * permission, and item-route escape hatches.
+ * @returns TypeScript object literal source for one generated REST resource entry.
+ */
+export function buildRestResourceConfigEntry(options) {
+    const pascalCase = toPascalCase(options.restResourceSlug);
+    const title = toTitleCase(options.restResourceSlug);
     const manifest = buildRestResourceEndpointManifest({
-        namespace,
+        namespace: options.namespace,
+        pascalCase,
+        ...(options.routePattern ? { routePattern: options.routePattern } : {}),
+        slugKebabCase: options.restResourceSlug,
+        title,
+    }, options.methods);
+    return [
+        "\t{",
+        `\t\tapiFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api.ts`)},`,
+        ...(options.controllerClass
+            ? [`\t\tcontrollerClass: ${quoteTsString(options.controllerClass)},`]
+            : []),
+        ...(options.controllerExtends
+            ? [`\t\tcontrollerExtends: ${quoteTsString(options.controllerExtends)},`]
+            : []),
+        `\t\tclientFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api-client.ts`)},`,
+        `\t\tdataFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/data.ts`)},`,
+        `\t\tmethods: [ ${options.methods.map((method) => quoteTsString(method)).join(", ")} ],`,
+        `\t\tnamespace: ${quoteTsString(options.namespace)},`,
+        `\t\topenApiFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api.openapi.json`)},`,
+        ...(options.permissionCallback
+            ? [`\t\tpermissionCallback: ${quoteTsString(options.permissionCallback)},`]
+            : []),
+        `\t\tphpFile: ${quoteTsString(`inc/rest/${options.restResourceSlug}.php`)},`,
+        "\t\trestManifest: defineEndpointManifest(",
+        indentMultiline(JSON.stringify(manifest, null, "\t"), "\t\t\t"),
+        "\t\t),",
+        ...(options.routePattern
+            ? [`\t\troutePattern: ${quoteTsString(options.routePattern)},`]
+            : []),
+        `\t\tslug: ${quoteTsString(options.restResourceSlug)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api-types.ts`)},`,
+        `\t\tvalidatorsFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api-validators.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+/**
+ * Build the `REST_RESOURCES` config entry appended for a manual REST contract.
+ *
+ * @param options Manual contract file, route, type, and auth metadata.
+ * @param options.auth Auth intent stored in the endpoint manifest.
+ * @param options.bodyTypeName Optional exported body type name.
+ * @param options.method Uppercase HTTP method for the external route.
+ * @param options.namespace REST namespace such as `vendor/v1`.
+ * @param options.pathPattern Route pattern relative to the namespace.
+ * @param options.queryTypeName Exported query type name.
+ * @param options.responseTypeName Exported response type name.
+ * @param options.restResourceSlug Normalized workspace REST contract slug.
+ * @returns A TypeScript object literal string for `scripts/block-config.ts`.
+ */
+export function buildManualRestContractConfigEntry(options) {
+    const pascalCase = toPascalCase(options.restResourceSlug);
+    const title = toTitleCase(options.restResourceSlug);
+    const manifest = buildManualRestContractEndpointManifest({
+        auth: options.auth,
+        ...(options.bodyTypeName ? { bodyTypeName: options.bodyTypeName } : {}),
+        method: options.method,
+        namespace: options.namespace,
         pascalCase,
-        slugKebabCase: restResourceSlug,
+        pathPattern: options.pathPattern,
+        queryTypeName: options.queryTypeName,
+        responseTypeName: options.responseTypeName,
+        slugKebabCase: options.restResourceSlug,
         title,
-    }, methods);
+    });
     return [
         "\t{",
-        `\t\tapiFile: ${quoteTsString(`src/rest/${restResourceSlug}/api.ts`)},`,
-        `\t\tclientFile: ${quoteTsString(`src/rest/${restResourceSlug}/api-client.ts`)},`,
-        `\t\tdataFile: ${quoteTsString(`src/rest/${restResourceSlug}/data.ts`)},`,
-        `\t\tmethods: [ ${methods.map((method) => quoteTsString(method)).join(", ")} ],`,
-        `\t\tnamespace: ${quoteTsString(namespace)},`,
-        `\t\topenApiFile: ${quoteTsString(`src/rest/${restResourceSlug}/api.openapi.json`)},`,
-        `\t\tphpFile: ${quoteTsString(`inc/rest/${restResourceSlug}.php`)},`,
+        `\t\tapiFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api.ts`)},`,
+        `\t\tauth: ${quoteTsString(options.auth)},`,
+        ...(options.bodyTypeName
+            ? [`\t\tbodyTypeName: ${quoteTsString(options.bodyTypeName)},`]
+            : []),
+        `\t\tclientFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api-client.ts`)},`,
+        `\t\tmethod: ${quoteTsString(options.method)},`,
+        "\t\tmethods: [],",
+        "\t\tmode: 'manual',",
+        `\t\tnamespace: ${quoteTsString(options.namespace)},`,
+        `\t\topenApiFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api.openapi.json`)},`,
+        `\t\tpathPattern: ${quoteTsString(options.pathPattern)},`,
+        `\t\tqueryTypeName: ${quoteTsString(options.queryTypeName)},`,
         "\t\trestManifest: defineEndpointManifest(",
         indentMultiline(JSON.stringify(manifest, null, "\t"), "\t\t\t"),
         "\t\t),",
-        `\t\tslug: ${quoteTsString(restResourceSlug)},`,
-        `\t\ttypesFile: ${quoteTsString(`src/rest/${restResourceSlug}/api-types.ts`)},`,
-        `\t\tvalidatorsFile: ${quoteTsString(`src/rest/${restResourceSlug}/api-validators.ts`)},`,
+        `\t\tresponseTypeName: ${quoteTsString(options.responseTypeName)},`,
+        ...(options.secretFieldName
+            ? [`\t\tsecretFieldName: ${quoteTsString(options.secretFieldName)},`]
+            : []),
+        ...(options.secretStateFieldName
+            ? [`\t\tsecretStateFieldName: ${quoteTsString(options.secretStateFieldName)},`]
+            : []),
+        `\t\tslug: ${quoteTsString(options.restResourceSlug)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api-types.ts`)},`,
+        `\t\tvalidatorsFile: ${quoteTsString(`src/rest/${options.restResourceSlug}/api-validators.ts`)},`,
         "\t},",
     ].join("\n");
 }
+/**
+ * Build the editable TypeScript type source for a manual REST contract.
+ *
+ * @param options Manual contract type naming metadata.
+ * @param options.bodyTypeName Optional exported body type name.
+ * @param options.queryTypeName Exported query type name.
+ * @param options.responseTypeName Exported response type name.
+ * @param options.restResourceSlug Normalized workspace REST contract slug.
+ * @param options.secretFieldName Optional raw secret field included only in the request body.
+ * @param options.secretStateFieldName Optional masked response boolean field.
+ * @returns TypeScript source for `api-types.ts`.
+ */
+export function buildManualRestContractTypesSource(options) {
+    const title = toTitleCase(options.restResourceSlug);
+    const lines = [
+        "import type { tags } from '@wp-typia/block-runtime/typia-tags';",
+        "",
+        `export interface ${options.queryTypeName} {`,
+        "\tid?: string & tags.MinLength< 1 >;",
+        "\tpreview?: boolean;",
+        "}",
+    ];
+    if (options.bodyTypeName) {
+        const secretLines = options.secretFieldName && options.secretStateFieldName
+            ? [
+                `\t${options.secretFieldName}?: string & tags.MinLength< 1 > & tags.MaxLength< 4096 > & tags.Secret< ${quoteTsString(options.secretStateFieldName)} >;`,
+                `\t// ${options.secretFieldName} is write-only: persist it server-side and expose ${options.secretStateFieldName} in responses instead of returning the raw value.`,
+            ]
+            : [];
+        lines.push("", `export interface ${options.bodyTypeName} {`, ...secretLines, "\tpayload: string & tags.MinLength< 1 >;", "\tcomment?: string & tags.MaxLength< 500 >;", "}");
+    }
+    lines.push("", `export interface ${options.responseTypeName} {`, ...(options.secretStateFieldName
+        ? [
+            `\t${options.secretStateFieldName}: boolean;`,
+            `\t// Raw secret fields such as ${options.secretFieldName ?? "the request secret"} must never be returned in this response.`,
+        ]
+        : []), "\tid: string & tags.MinLength< 1 >;", "\tstatus: 'ok' | 'error';", "\tmessage?: string;", "\tupdatedAt?: string;", "}", "", `// ${title} is a manual REST contract: edit these types to match the external route owner.`);
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Build Typia validator source for a manual REST contract.
+ *
+ * @param options Manual contract type names to validate.
+ * @param options.bodyTypeName Optional exported body type name.
+ * @param options.queryTypeName Exported query type name.
+ * @param options.responseTypeName Exported response type name.
+ * @returns TypeScript source for `api-validators.ts`.
+ */
+export function buildManualRestContractValidatorsSource(options) {
+    const importedTypes = [
+        options.queryTypeName,
+        ...(options.bodyTypeName ? [options.bodyTypeName] : []),
+        options.responseTypeName,
+    ].sort();
+    const validatorDeclarations = [
+        `const validateQuery = typia.createValidate< ${options.queryTypeName} >();`,
+        ...(options.bodyTypeName
+            ? [`const validateRequest = typia.createValidate< ${options.bodyTypeName} >();`]
+            : []),
+        `const validateResponse = typia.createValidate< ${options.responseTypeName} >();`,
+    ];
+    const validatorEntries = [
+        `\tquery: ( input: unknown ) => toValidationResult< ${options.queryTypeName} >( validateQuery( input ) ),`,
+        ...(options.bodyTypeName
+            ? [
+                `\trequest: ( input: unknown ) => toValidationResult< ${options.bodyTypeName} >( validateRequest( input ) ),`,
+            ]
+            : []),
+        `\tresponse: ( input: unknown ) => toValidationResult< ${options.responseTypeName} >( validateResponse( input ) ),`,
+    ];
+    return `import typia from 'typia';
+
+import { toValidationResult } from '@wp-typia/rest';
+import type {
+\t${importedTypes.join(",\n\t")},
+} from './api-types';
+
+${validatorDeclarations.join("\n")}
+
+export const apiValidators = {
+${validatorEntries.join("\n")}
+};
+`;
+}
+/**
+ * Build the public API shim for a manual REST contract.
+ *
+ * @param options Manual REST contract operation and request type metadata.
+ * @returns TypeScript source that re-exports the generated endpoint client.
+ */
+export function buildManualRestContractApiSource(options) {
+    const pascalCase = toPascalCase(options.restResourceSlug);
+    const operationId = `call${pascalCase}ManualRestContract`;
+    const requestTypeName = options.bodyTypeName
+        ? `${pascalCase}ManualRestContractRequest`
+        : options.queryTypeName;
+    const requestTypeSource = options.bodyTypeName
+        ? `export interface ${requestTypeName} {
+\tbody: ${options.bodyTypeName};
+\tquery: ${options.queryTypeName};
+}
+
+`
+        : "";
+    const typeImports = options.bodyTypeName
+        ? [options.bodyTypeName, options.queryTypeName]
+        : [options.queryTypeName];
+    return `import {
+\tcallEndpoint,
+\tresolveRestRouteUrl,
+} from '@wp-typia/rest';
+
+import type {
+\t${typeImports.sort().join(",\n\t")},
+} from './api-types';
+import { ${operationId}Endpoint } from './api-client';
+
+export * from './api-client';
+
+${requestTypeSource}function resolveRestNonce(fallback?: string): string | undefined {
+\tif (typeof fallback === 'string' && fallback.length > 0) {
+\t\treturn fallback;
+\t}
+
+\tif (typeof window === 'undefined') {
+\t\treturn undefined;
+\t}
+
+\tconst wpApiSettings = (
+\t\twindow as typeof window & {
+\t\t\twpApiSettings?: { nonce?: string };
+\t\t}
+\t).wpApiSettings;
+
+\treturn typeof wpApiSettings?.nonce === 'string' &&
+\t\twpApiSettings.nonce.length > 0
+\t\t? wpApiSettings.nonce
+\t\t: undefined;
+}
+
+function resolveEndpointRouteOptions(request: ${requestTypeName}) {
+\tconst requestOptions = ${operationId}Endpoint.buildRequestOptions?.(request) ?? {};
+\tconst nonce = resolveRestNonce();
+\tconst requestHeaders = (
+\t\trequestOptions as { headers?: Record<string, string> }
+\t).headers;
+
+\treturn {
+\t\t...requestOptions,
+\t\theaders: nonce
+\t\t\t? {
+\t\t\t\t\t...(requestHeaders ?? {}),
+\t\t\t\t\t'X-WP-Nonce': nonce,
+\t\t\t\t}
+\t\t\t: requestHeaders,
+\t\tpath: undefined,
+\t\turl:
+\t\t\trequestOptions.url ??
+\t\t\tresolveRestRouteUrl(requestOptions.path ?? ${operationId}Endpoint.path),
+\t};
+}
+
+export const manualRestContractEndpoint = {
+\t...${operationId}Endpoint,
+\tbuildRequestOptions: resolveEndpointRouteOptions,
+};
+
+export function callManualRestContract(request: ${requestTypeName}) {
+\treturn callEndpoint(manualRestContractEndpoint, request);
+}
+`;
+}
 export function buildRestResourceTypesSource(restResourceSlug, methods) {
     const pascalCase = toPascalCase(restResourceSlug);
     const lines = [
@@ -122,9 +376,8 @@ export function buildRestResourceApiSource(restResourceSlug, methods) {
         clientEndpointImports.push(`list${pascalCase}ResourcesEndpoint`);
         exportedBindings.push(`export const restResourceListEndpoint = {
 \t...list${pascalCase}ResourcesEndpoint,
-\tbuildRequestOptions: () => ( {
-\t\turl: resolveRestRouteUrl( list${pascalCase}ResourcesEndpoint.path ),
-\t} ),
+\tbuildRequestOptions: ( request: ${pascalCase}ListQuery ) =>
+\t\tresolveEndpointRouteOptions( list${pascalCase}ResourcesEndpoint, request ),
 };
 
 export function listResource( request: ${pascalCase}ListQuery ) {
@@ -136,9 +389,8 @@ export function listResource( request: ${pascalCase}ListQuery ) {
         clientEndpointImports.push(`read${pascalCase}ResourceEndpoint`);
         exportedBindings.push(`export const restResourceReadEndpoint = {
 \t...read${pascalCase}ResourceEndpoint,
-\tbuildRequestOptions: () => ( {
-\t\turl: resolveRestRouteUrl( read${pascalCase}ResourceEndpoint.path ),
-\t} ),
+\tbuildRequestOptions: ( request: ${pascalCase}ReadQuery ) =>
+\t\tresolveEndpointRouteOptions( read${pascalCase}ResourceEndpoint, request ),
 };
 
 export function readResource( request: ${pascalCase}ReadQuery ) {
@@ -150,15 +402,15 @@ export function readResource( request: ${pascalCase}ReadQuery ) {
         clientEndpointImports.push(`create${pascalCase}ResourceEndpoint`);
         exportedBindings.push(`export const restResourceCreateEndpoint = {
 \t...create${pascalCase}ResourceEndpoint,
-\tbuildRequestOptions: () => {
+\tbuildRequestOptions: ( request: ${pascalCase}CreateRequest ) => {
 \t\tconst nonce = resolveRestNonce();
 \t\treturn {
+\t\t\t...resolveEndpointRouteOptions( create${pascalCase}ResourceEndpoint, request ),
 \t\t\theaders: nonce
 \t\t\t\t? {
 \t\t\t\t\t'X-WP-Nonce': nonce,
 \t\t\t\t}
 \t\t\t\t: undefined,
-\t\t\turl: resolveRestRouteUrl( create${pascalCase}ResourceEndpoint.path ),
 \t\t};
 \t},
 };
@@ -173,15 +425,18 @@ export function createResource( request: ${pascalCase}CreateRequest ) {
         clientEndpointImports.push(`update${pascalCase}ResourceEndpoint`);
         exportedBindings.push(`export const restResourceUpdateEndpoint = {
 \t...update${pascalCase}ResourceEndpoint,
-\tbuildRequestOptions: () => {
+\tbuildRequestOptions: ( request: {
+\t\tbody: ${pascalCase}UpdateRequest;
+\t\tquery: ${pascalCase}UpdateQuery;
+\t} ) => {
 \t\tconst nonce = resolveRestNonce();
 \t\treturn {
+\t\t\t...resolveEndpointRouteOptions( update${pascalCase}ResourceEndpoint, request ),
 \t\t\theaders: nonce
 \t\t\t\t? {
 \t\t\t\t\t'X-WP-Nonce': nonce,
 \t\t\t\t}
 \t\t\t\t: undefined,
-\t\t\turl: resolveRestRouteUrl( update${pascalCase}ResourceEndpoint.path ),
 \t\t};
 \t},
 };
@@ -198,15 +453,15 @@ export function updateResource( request: {
         clientEndpointImports.push(`delete${pascalCase}ResourceEndpoint`);
         exportedBindings.push(`export const restResourceDeleteEndpoint = {
 \t...delete${pascalCase}ResourceEndpoint,
-\tbuildRequestOptions: () => {
+\tbuildRequestOptions: ( request: ${pascalCase}DeleteQuery ) => {
 \t\tconst nonce = resolveRestNonce();
 \t\treturn {
+\t\t\t...resolveEndpointRouteOptions( delete${pascalCase}ResourceEndpoint, request ),
 \t\t\theaders: nonce
 \t\t\t\t? {
 \t\t\t\t\t'X-WP-Nonce': nonce,
 \t\t\t\t}
 \t\t\t\t: undefined,
-\t\t\turl: resolveRestRouteUrl( delete${pascalCase}ResourceEndpoint.path ),
 \t\t};
 \t},
 };
@@ -251,6 +506,24 @@ import {
 \t${clientEndpointImports.sort().join(",\n\t")},
 } from './api-client';
 ${resolveRestNonceSource}
+function resolveEndpointRouteOptions<TRequest>(
+\tendpoint: {
+\t\tbuildRequestOptions?: ( request: TRequest ) => {
+\t\t\tpath?: string;
+\t\t\turl?: string;
+\t\t};
+\t\tpath: string;
+\t},
+\trequest: TRequest
+) {
+\tconst requestOptions = endpoint.buildRequestOptions?.( request ) ?? {};
+\treturn {
+\t\t...requestOptions,
+\t\tpath: undefined,
+\t\turl: requestOptions.url ?? resolveRestRouteUrl( requestOptions.path ?? endpoint.path ),
+\t};
+}
+
 ${exportedBindings.join("\n\n")}
 `;
 }

package/dist/runtime/cli-add-workspace-rest.d.ts

@@ -1,4 +1,4 @@
-import { type RestResourceMethodId, type RunAddRestResourceCommandOptions } from "./cli-add-shared.js";
+import { type ManualRestContractAuthId, type ManualRestContractHttpMethodId, type RestResourceMethodId, type RunAddRestResourceCommandOptions } from "./cli-add-shared.js";
 /**
  * Scaffold a workspace-level REST resource and synchronize its generated
  * TypeScript and PHP artifacts.
@@ -6,9 +6,22 @@ import { type RestResourceMethodId, type RunAddRestResourceCommandOptions } from
  * @param options Command options for the REST resource scaffold workflow.
  * @returns Resolved scaffold metadata for the created REST resource.
  */
-export declare function runAddRestResourceCommand({ cwd, methods, namespace, restResourceName, }: RunAddRestResourceCommandOptions): Promise<{
+export declare function runAddRestResourceCommand({ auth, bodyTypeName, controllerClass, controllerExtends, cwd, manual, method, methods, namespace, permissionCallback, pathPattern, queryTypeName, restResourceName, responseTypeName, routePattern, secretFieldName, secretStateFieldName, }: RunAddRestResourceCommandOptions): Promise<{
+    auth?: ManualRestContractAuthId;
+    bodyTypeName?: string;
+    controllerClass?: string;
+    controllerExtends?: string;
+    method?: ManualRestContractHttpMethodId;
     methods: RestResourceMethodId[];
+    mode: "generated" | "manual";
     namespace: string;
+    permissionCallback?: string;
+    pathPattern?: string;
     projectDir: string;
+    queryTypeName?: string;
     restResourceSlug: string;
+    responseTypeName?: string;
+    routePattern?: string;
+    secretFieldName?: string;
+    secretStateFieldName?: string;
 }>;