pasika 0.10.55 → 0.10.57

package/dist/helpers/api-contract.d.ts

@@ -0,0 +1,20 @@
+import { ZodType, z } from 'zod';
+import { HttpMethod } from './http-method.js';
+
+declare const apiErrorResponseSchema: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>;
+interface ApiContract<TResponseSchema extends ZodType = ZodType, TRequestSchema extends ZodType | undefined = undefined> {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly responseSchema: TResponseSchema;
+    readonly requestSchema?: TRequestSchema;
+}
+/**
+ * Declares one schema-validated JSON endpoint. Route, client, and mock import
+ * this same value so method, path, request validation, and response validation
+ * have one source.
+ */
+declare function defineApiContract<TResponseSchema extends ZodType, TRequestSchema extends ZodType | undefined = undefined>(contract: ApiContract<TResponseSchema, TRequestSchema>): Readonly<ApiContract<TResponseSchema, TRequestSchema>>;
+
+export { type ApiContract, apiErrorResponseSchema, defineApiContract };

package/dist/helpers/api-contract.js

@@ -0,0 +1,8 @@
+import {
+  apiErrorResponseSchema,
+  defineApiContract
+} from "../chunk-Z3C5YVO4.js";
+export {
+  apiErrorResponseSchema,
+  defineApiContract
+};

package/dist/helpers/with-response.d.ts

@@ -1,7 +1,8 @@
 import { NextResponse } from 'next/server';
 import { z } from 'zod';
+import { ApiContract } from './api-contract.js';
+import './http-method.js';
 
-/** Whatever a handler's own response needs to carry; a failure never inherits it. */
 type ResponseHeaders = Headers | Record<string, string>;
 type HandlerResult<TData> = {
     data: TData;
@@ -13,14 +14,12 @@ type HandlerResult<TData> = {
     headers?: ResponseHeaders;
 };
 /**
- * Turns a handler's result, or a failure thrown under it, into a response: the data
- * goes through the response schema, an `HttpError` becomes `{ success: false, data: null, message }`
- * at its own status and is never cached, and anything else stays an error.
- *
- * A handler whose own response is not JSON calls it with the handler alone and returns
- * `{ body, status, headers }`, so a relayed body passes through unread.
+ * Turns a handler result into the raw HTTP response described by one API contract.
+ * Successful JSON data is validated and returned as the body directly. An HttpError
+ * becomes the standard { message } error body at its own status and is never cached.
+ * Anything else remains an error.
  */
-declare function withResponse<TSchema extends z.ZodType, Args extends unknown[]>(responseSchema: TSchema, handler?: (...args: Args) => Promise<HandlerResult<z.input<TSchema>>>): (...args: Args) => Promise<NextResponse>;
+declare function withResponse<TSchema extends z.ZodType, Args extends unknown[]>(contract: ApiContract<TSchema, z.ZodType | undefined>, handler?: (...args: Args) => Promise<HandlerResult<z.input<TSchema>>>): (...args: Args) => Promise<NextResponse>;
 declare function withResponse<Args extends unknown[]>(handler: (...args: Args) => Promise<HandlerResult<ReadableStream<Uint8Array>>>): (...args: Args) => Promise<NextResponse>;
 
 export { type HandlerResult, type ResponseHeaders, withResponse };

package/dist/helpers/with-response.js

@@ -1,3 +1,6 @@
+import {
+  apiErrorResponseSchema
+} from "../chunk-Z3C5YVO4.js";
 import {
   HttpError
 } from "../chunk-7JI2V3HF.js";
@@ -7,9 +10,9 @@ import { NextResponse } from "next/server";
 import { z } from "zod";
 var streamBody = z.custom((value) => value instanceof ReadableStream);
 function missingHandler() {
-  throw new HttpError("withResponse requires a response schema and a handler.", 500);
+  throw new HttpError("withResponse requires an API contract and a handler.", 500);
 }
-function withResponse(responseSchemaOrHandler, handler) {
+function withResponse(contractOrHandler, handler) {
   const respond = (schema, wrapped = missingHandler) => async (...requestArgs) => {
     try {
       const result = await wrapped(...requestArgs);
@@ -18,18 +21,18 @@ function withResponse(responseSchemaOrHandler, handler) {
         return new NextResponse(streamBody.parse(body), { status: status2, headers: headers2 });
       }
       const { data, status, headers } = result;
-      return NextResponse.json({ success: true, data: schema.parse(data) }, { status, headers });
+      return NextResponse.json(schema.parse(data), { status, headers });
     } catch (error) {
       if (error instanceof HttpError) {
-        return NextResponse.json(
-          { success: false, data: null, message: error.message },
-          { status: error.status, headers: { "Cache-Control": "no-store" } }
-        );
+        return NextResponse.json(apiErrorResponseSchema.parse({ message: error.message }), {
+          status: error.status,
+          headers: { "Cache-Control": "no-store" }
+        });
       }
       throw error;
     }
   };
-  return typeof responseSchemaOrHandler === "function" ? respond(streamBody, responseSchemaOrHandler) : respond(responseSchemaOrHandler, handler);
+  return typeof contractOrHandler === "function" ? respond(streamBody, contractOrHandler) : respond(contractOrHandler.responseSchema, handler);
 }
 export {
   withResponse

package/dist/helpers/zod-fetch.d.ts

@@ -1,30 +1,28 @@
 import { ZodType, z } from 'zod';
+import { ApiContract } from './api-contract.js';
+import './http-method.js';
 
-interface ZodFetchOptions<TSchema extends ZodType = never, TRequestSchema extends ZodType = ZodType> {
+interface ApiContractFetchOptions<TResponseSchema extends ZodType, TRequestSchema extends ZodType | undefined = undefined> {
+    contract: ApiContract<TResponseSchema, TRequestSchema>;
+    url?: string | URL;
+    init?: Omit<RequestInit, "method">;
+}
+interface ZodFetchRelayedOptions {
     url: string | URL;
     init?: RequestInit;
-    requestSchema?: TRequestSchema;
-    responseSchema?: TSchema;
 }
-/** The response itself, for a caller whose own response relays a body nothing has read. */
 interface ZodFetchRelayedResponse {
     body: ReadableStream<Uint8Array>;
     status: number;
     headers: Headers;
 }
 /**
- * The only module in a repository that calls `fetch`. It hands a JSON body back as
- * data the response schema accepted, and a failure back as an `HttpError` carrying
- * the status the upstream reported, the message for a client, and what the upstream
- * answered with. A call that names no response schema gets the response itself.
- *
- * A success that carries no body is the schema's call: one that allows its data to
- * be absent, such as `z.undefined()` for an endpoint answering `204`, accepts it, and
- * one that does not makes it a failure of this gateway's own, a 502.
+ * Makes one schema-validated JSON request through an API contract, or relays a
+ * response body when no contract is supplied. Contract calls reuse the endpoint's
+ * method, request schema, and response schema; url only overrides the concrete
+ * address for dynamic or external endpoints.
  */
-declare function zodFetch<TSchema extends ZodType>(options: ZodFetchOptions<TSchema> & {
-    responseSchema: TSchema;
-}): Promise<z.output<TSchema>>;
-declare function zodFetch(options: ZodFetchOptions): Promise<ZodFetchRelayedResponse>;
+declare function zodFetch<TResponseSchema extends ZodType, TRequestSchema extends ZodType | undefined>(options: ApiContractFetchOptions<TResponseSchema, TRequestSchema>): Promise<z.output<TResponseSchema>>;
+declare function zodFetch(options: ZodFetchRelayedOptions): Promise<ZodFetchRelayedResponse>;
 
-export { type ZodFetchOptions, type ZodFetchRelayedResponse, zodFetch };
+export { type ApiContractFetchOptions, type ZodFetchRelayedOptions, type ZodFetchRelayedResponse, zodFetch };

package/dist/helpers/zod-fetch.js

@@ -1,3 +1,6 @@
+import {
+  apiErrorResponseSchema
+} from "../chunk-Z3C5YVO4.js";
 import {
   HttpError
 } from "../chunk-7JI2V3HF.js";
@@ -14,23 +17,28 @@ function decodeFailureBody(body) {
     return body;
   }
 }
+function failureMessage(status, statusText, body) {
+  const parsed = apiErrorResponseSchema.safeParse(body);
+  if (parsed.success) return parsed.data.message;
+  const suffix = statusText === "" ? "" : ` ${statusText}`;
+  return `Request failed with status ${String(status)}${suffix}`;
+}
+function parseRequestBody(schema, body) {
+  if (schema === void 0) return;
+  const decoded = typeof body === "string" ? JSON.parse(body) : body;
+  schema.parse(decoded);
+}
 async function zodFetch(options) {
-  if (options.requestSchema !== void 0) {
-    const rawBody = options.init?.body;
-    const body2 = typeof rawBody === "string" ? JSON.parse(rawBody) : rawBody;
-    options.requestSchema.parse(body2);
-  }
-  const response = await fetch(options.url, options.init);
+  const contract = "contract" in options ? options.contract : void 0;
+  const url = "contract" in options ? options.url ?? options.contract.path : options.url;
+  const init = contract ? { ...options.init, method: contract.method } : options.init;
+  if (contract) parseRequestBody(contract.requestSchema, init?.body);
+  const response = await fetch(url, init);
   if (!response.ok) {
-    const body2 = await response.text();
-    const statusText = response.statusText === "" ? "" : ` ${response.statusText}`;
-    throw new HttpError(
-      `Request failed with status ${String(response.status)}${statusText}`,
-      response.status,
-      decodeFailureBody(body2)
-    );
+    const body2 = decodeFailureBody(await response.text());
+    throw new HttpError(failureMessage(response.status, response.statusText, body2), response.status, body2);
   }
-  if (options.responseSchema === void 0) {
+  if (!contract) {
     const streamed = streamBody.safeParse(response.body);
     if (!streamed.success) {
       throw new HttpError("The upstream answered without a body to relay.", BAD_GATEWAY);
@@ -39,12 +47,12 @@ async function zodFetch(options) {
   }
   const body = await response.text();
   if (body === "") {
-    const absent = options.responseSchema.safeParse(void 0);
+    const absent = contract.responseSchema.safeParse(void 0);
     if (absent.success) return absent.data;
     throw new HttpError("The upstream answered without a body to decode.", BAD_GATEWAY);
   }
   const decoded = JSON.parse(body);
-  return options.responseSchema.parse(decoded);
+  return contract.responseSchema.parse(decoded);
 }
 export {
   zodFetch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pasika",
-  "version": "0.10.55",
+  "version": "0.10.57",
   "description": "Reusable agent setup package",
   "repository": {
     "type": "git",
@@ -13,6 +13,10 @@
       "types": "./dist/eslint/pasika/index.d.ts",
       "import": "./dist/eslint/pasika/index.js"
     },
+    "./api-contract": {
+      "types": "./dist/helpers/api-contract.d.ts",
+      "import": "./dist/helpers/api-contract.js"
+    },
     "./cn": {
       "types": "./dist/helpers/cn.d.ts",
       "import": "./dist/helpers/cn.js"
@@ -25,10 +29,6 @@
       "types": "./dist/helpers/http-method.d.ts",
       "import": "./dist/helpers/http-method.js"
     },
-    "./response-envelope": {
-      "types": "./dist/helpers/response-envelope.d.ts",
-      "import": "./dist/helpers/response-envelope.js"
-    },
     "./zod-fetch": {
       "types": "./dist/helpers/zod-fetch.d.ts",
       "import": "./dist/helpers/zod-fetch.js"

package/dist/helpers/response-envelope.d.ts

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-
-declare function responseEnvelope<TSchema extends z.ZodType>(dataSchema: TSchema): z.ZodType<{
-    success: true;
-    data: z.output<TSchema>;
-} | {
-    success: false;
-    data: null;
-    message: string;
-}, {
-    success: true;
-    data: z.input<TSchema>;
-} | {
-    success: false;
-    data: null;
-    message: string;
-}>;
-declare function responseEnvelope(dataSchema: z.ZodType): z.ZodType;
-
-export { responseEnvelope };

package/dist/helpers/response-envelope.js

@@ -1,18 +0,0 @@
-// helpers/response-envelope.ts
-import { z } from "zod";
-function responseEnvelope(dataSchema) {
-  return z.discriminatedUnion("success", [
-    z.object({
-      success: z.literal(true),
-      data: dataSchema
-    }),
-    z.object({
-      success: z.literal(false),
-      data: z.null(),
-      message: z.string()
-    })
-  ]);
-}
-export {
-  responseEnvelope
-};