@wp-typia/rest 0.3.6 → 0.3.7

package/README.md

@@ -15,26 +15,40 @@ It does not include any WordPress PHP bridge logic. Generated PHP route code sta
 If you need a backend-neutral consumer instead of WordPress-specific route
 resolution, use `@wp-typia/api-client`.
 
+## Export contract
+
+- `@wp-typia/rest`
+  Canonical convenience surface for transport helpers plus HTTP decoder helpers.
+- `@wp-typia/rest/client`
+  Backward-compatible alias of the root surface. It is not a distinct semantic
+  contract and may be removed in a future major once downstream imports settle.
+- `@wp-typia/rest/http`
+  Backward-compatible alias of the root surface. It remains publishable for
+  existing imports, but it is not a distinct decoder-only contract in the
+  current major line.
+- `@wp-typia/rest/react`
+  React-only cache and hook layer.
+
 The root `@wp-typia/rest` entry stays transport-oriented. If you want query and
 mutation hooks on top of those WordPress helpers, use the React-only subpath:
 
 ```ts
-import { useEndpointMutation, useEndpointQuery } from "@wp-typia/rest/react";
+import { useEndpointMutation, useEndpointQuery } from '@wp-typia/rest/react';
 ```
 
 Typical usage:
 
 ```ts
-import { callEndpoint, createEndpoint } from "@wp-typia/rest";
+import { callEndpoint, createEndpoint } from '@wp-typia/rest';
 
 const endpoint = createEndpoint<MyRequest, MyResponse>({
-  method: "POST",
-  path: "/my-namespace/v1/demo",
+  method: 'POST',
+  path: '/my-namespace/v1/demo',
   validateRequest: validators.request,
   validateResponse: validators.response,
 });
 
-const result = await callEndpoint(endpoint, { title: "Hello" });
+const result = await callEndpoint(endpoint, { title: 'Hello' });
 ```
 
 `callEndpoint(...)` returns `EndpointValidationResult<Req, Res>`. If request
@@ -42,22 +56,32 @@ validation fails before transport execution, the result keeps
 `validationTarget: "request"`. Response validation runs after transport and uses
 `validationTarget: "response"`.
 
+Invalid request/response payloads stay in that result union. Thrown exceptions
+are reserved for public runtime misconfiguration or assertion APIs:
+
+- `RestConfigurationError`
+- `RestRootResolutionError`
+- `RestQueryHookUsageError`
+- `RestValidationAssertionError`
+- shared base classes re-exported from `@wp-typia/api-client`:
+  `WpTypiaContractError` and `WpTypiaValidationAssertionError`
+
 If you need a canonical REST URL for a route path, use:
 
 ```ts
-import { resolveRestRouteUrl } from "@wp-typia/rest";
+import { resolveRestRouteUrl } from '@wp-typia/rest';
 
-const url = resolveRestRouteUrl("/my-namespace/v1/demo");
+const url = resolveRestRouteUrl('/my-namespace/v1/demo');
 ```
 
 If you want Typia-powered HTTP decoding, compile the decoder in the consumer project and pass it in:
 
 ```ts
-import typia from "typia";
-import { createQueryDecoder } from "@wp-typia/rest";
+import typia from 'typia';
+import { createQueryDecoder } from '@wp-typia/rest';
 
 const decodeQuery = createQueryDecoder(
-  typia.http.createValidateQuery<MyQuery>()
+  typia.http.createValidateQuery<MyQuery>(),
 );
 ```
 
@@ -76,17 +100,14 @@ The `./react` subpath adds a small cache client and React hook layer on top of
 non-query calls go through `useEndpointMutation(...)`.
 
 ```tsx
-import {
-  useEndpointMutation,
-  useEndpointQuery,
-} from "@wp-typia/rest/react";
+import { useEndpointMutation, useEndpointQuery } from '@wp-typia/rest/react';
 
 const query = useEndpointQuery(stateEndpoint, request, {
   staleTime: 30_000,
   resolveCallOptions: () => ({
     requestOptions: {
       headers: {
-        "X-WP-Nonce": resolveRestNonce(),
+        'X-WP-Nonce': resolveRestNonce(),
       },
     },
   }),
@@ -97,7 +118,7 @@ const mutation = useEndpointMutation(writeStateEndpoint, {
   resolveCallOptions: () => ({
     requestOptions: {
       headers: {
-        "X-WP-Nonce": resolveRestNonce(),
+        'X-WP-Nonce': resolveRestNonce(),
       },
     },
   }),

package/dist/client.js

@@ -1,5 +1,6 @@
 import { encodeGetLikeRequest, joinPathWithQuery, joinUrlWithQuery, mergeHeaderInputs, parseResponsePayload, } from "@wp-typia/api-client/client-utils";
 import { isFormDataLike, toValidationResult, } from "./internal/runtime-primitives.js";
+import { RestConfigurationError, RestRootResolutionError, RestValidationAssertionError, } from "./errors.js";
 export { isValidationResult, normalizeValidationError, toValidationResult } from "./internal/runtime-primitives.js";
 function getDefaultRestRoot() {
     if (typeof window !== "undefined") {
@@ -15,7 +16,7 @@ function getDefaultRestRoot() {
             }
         }
     }
-    throw new Error("Unable to resolve the WordPress REST root automatically. Provide wpApiSettings.root, an api.w.org discovery link, or an explicit url.");
+    throw new RestRootResolutionError("Unable to resolve the WordPress REST root automatically. Provide wpApiSettings.root, an api.w.org discovery link, or an explicit url.");
 }
 export function resolveRestRouteUrl(routePath, root = getDefaultRestRoot()) {
     const [pathWithQuery, hash = ""] = routePath.split("#", 2);
@@ -50,7 +51,7 @@ function resolveFetchUrl(options) {
     if (typeof options.path === "string" && options.path.length > 0) {
         return resolveRestRouteUrl(options.path);
     }
-    throw new Error("API fetch options must include either a path or a url.");
+    throw new RestConfigurationError("API fetch options must include either a path or a url.");
 }
 async function defaultFetch(options) {
     const response = await fetch(resolveFetchUrl(options), {
@@ -154,7 +155,7 @@ export function createValidatedFetch(validator, fetchFn = defaultFetch) {
         async assertFetch(options) {
             const result = await this.fetch(options);
             if (!result.isValid) {
-                throw new Error(result.errors[0]
+                throw new RestValidationAssertionError(result, result.errors[0]
                     ? `${result.errors[0].path}: ${result.errors[0].expected}`
                     : "REST response validation failed.");
             }

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+import { WpTypiaContractError, WpTypiaValidationAssertionError, type ValidationResult } from "@wp-typia/api-client";
+export { ApiClientConfigurationError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "@wp-typia/api-client";
+export declare class RestConfigurationError extends WpTypiaContractError {
+    constructor(message: string);
+}
+export declare class RestRootResolutionError extends RestConfigurationError {
+    constructor(message: string);
+}
+export declare class RestQueryHookUsageError extends RestConfigurationError {
+    constructor(message: string);
+}
+export declare class RestValidationAssertionError<T = unknown> extends WpTypiaValidationAssertionError<T> {
+    constructor(validation: ValidationResult<T>, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+import { WpTypiaContractError, WpTypiaValidationAssertionError, } from "@wp-typia/api-client";
+export { ApiClientConfigurationError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "@wp-typia/api-client";
+export class RestConfigurationError extends WpTypiaContractError {
+    constructor(message) {
+        super(message, "REST_CONFIGURATION_ERROR");
+    }
+}
+export class RestRootResolutionError extends RestConfigurationError {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class RestQueryHookUsageError extends RestConfigurationError {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class RestValidationAssertionError extends WpTypiaValidationAssertionError {
+    constructor(validation, message) {
+        super(validation, message);
+        this.name = new.target.name;
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { createEndpoint, createValidatedFetch, callEndpoint, isValidationResult, normalizeValidationError, resolveRestRouteUrl, toValidationResult, type ApiEndpoint, type EndpointCallOptions, type EndpointRequestValidationResult, type EndpointResponseValidationResult, type EndpointValidationResult, type EndpointValidationTarget, type ValidatedFetch, type ValidationResult, type ValidationError, type ValidationLike, } from "./client.js";
+export { ApiClientConfigurationError, RestConfigurationError, RestQueryHookUsageError, RestRootResolutionError, RestValidationAssertionError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "./errors.js";
 export { createHeadersDecoder, createParameterDecoder, createQueryDecoder, } from "./http.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createEndpoint, createValidatedFetch, callEndpoint, isValidationResult, normalizeValidationError, resolveRestRouteUrl, toValidationResult, } from "./client.js";
+export { ApiClientConfigurationError, RestConfigurationError, RestQueryHookUsageError, RestRootResolutionError, RestValidationAssertionError, WpTypiaContractError, WpTypiaValidationAssertionError, } from "./errors.js";
 export { createHeadersDecoder, createParameterDecoder, createQueryDecoder, } from "./http.js";

package/dist/react.js

@@ -1,5 +1,6 @@
 import { createContext, createElement, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "@wordpress/element";
 import { callEndpoint, } from "./client.js";
+import { RestQueryHookUsageError } from "./errors.js";
 import { isPlainObject } from "./internal/runtime-primitives.js";
 const EMPTY_SNAPSHOT = {
     data: undefined,
@@ -325,7 +326,7 @@ export function useEndpointDataClient() {
 }
 export function useEndpointQuery(endpoint, request, options = {}) {
     if (endpoint.method !== "GET") {
-        throw new Error("useEndpointQuery only supports GET endpoints in v1.");
+        throw new RestQueryHookUsageError("useEndpointQuery only supports GET endpoints in v1.");
     }
     const defaultClient = useEndpointDataClient();
     const client = asInternalClient(options.client ?? defaultClient);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/rest",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Typed WordPress REST helpers powered by Typia validation",
   "type": "module",
   "main": "dist/index.js",
@@ -62,7 +62,7 @@
     "bun": ">=1.3.11"
   },
   "dependencies": {
-    "@wp-typia/api-client": "^0.4.3",
+    "@wp-typia/api-client": "^0.4.4",
     "@typia/interface": "^12.0.1",
     "@wordpress/api-fetch": "^7.42.0"
   },