first commit

Author: acominotto

.github/workflows/deploy-docs.yml

@@ -0,0 +1,59 @@
+name: Deploy Docs Website to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build library
+        run: pnpm build
+
+      - name: Build docs website
+        run: pnpm docs:build
+
+      - name: Upload docs website artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -0,0 +1,104 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'package.json'
+  workflow_dispatch:
+    inputs:
+      force_publish:
+        description: 'Force publish without version check'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version_changed: ${{ steps.check.outputs.changed }}
+      new_version: ${{ steps.check.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check if version changed
+        id: check
+        run: |
+          # Get current version
+          CURRENT_VERSION=$(jq -r '.version' package.json)
+          echo "Current version: $CURRENT_VERSION"
+          
+          # Check if this is a manual trigger with force
+          if [ "${{ inputs.force_publish }}" == "true" ]; then
+            echo "Force publish requested"
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+          
+          # Check if tag already exists
+          if git rev-parse "v$CURRENT_VERSION" >/dev/null 2>&1; then
+            echo "Tag v$CURRENT_VERSION already exists, skipping"
+            echo "changed=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+          
+          # Get previous version from last commit
+          PREVIOUS_VERSION=$(git show HEAD~1:package.json 2>/dev/null | jq -r '.version' 2>/dev/null || echo "0.0.0")
+          echo "Previous version: $PREVIOUS_VERSION"
+          
+          if [ "$CURRENT_VERSION" != "$PREVIOUS_VERSION" ]; then
+            echo "Version changed from $PREVIOUS_VERSION to $CURRENT_VERSION"
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+          else
+            echo "Version unchanged"
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+
+  publish:
+    needs: check-version
+    if: needs.check-version.outputs.version_changed == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish to npm
+        run: pnpm publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create Git tag
+        run: |
+          VERSION=${{ needs.check-version.outputs.new_version }}
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "v$VERSION" -m "Release v$VERSION"
+          git push origin "v$VERSION"

.gitignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+.DS_Store

README.md

@@ -0,0 +1,202 @@
+# @ideative/next-handler
+
+Typed helpers for Next.js route handlers with:
+
+- request context access (`getRequest()`),
+- Zod payload validation (`payload()`),
+- serializable errors that round-trip from backend to frontend.
+
+## Install
+
+```bash
+pnpm add @ideative/next-handler
+```
+
+Peer dependencies:
+
+- `next` >= 15
+- `zod` >= 4.3.6
+- `react` >= 19.2.4 (for intl context utilities)
+- `next-intl` >= 4.8.2 (for intl utilities)
+
+## Backend usage
+
+### Wrap handlers
+
+```ts
+import { NextResponse } from "next/server";
+import { withApiHandler, payload, getRequest } from "@ideative/next-handler";
+import { z } from "zod";
+
+const schema = z.object({ name: z.string(), email: z.string().email() });
+
+export const POST = withApiHandler(async () => {
+  const body = await payload(schema);
+  const req = getRequest();
+  return NextResponse.json({ from: req.url, ...body });
+});
+```
+
+### Throw typed API errors
+
+```ts
+import {
+  withApiHandler,
+  BadRequestError,
+  NotFoundError,
+  UnauthorizedError,
+} from "@ideative/next-handler";
+
+export const GET = withApiHandler(async (req) => {
+  if (!req.headers.get("authorization")) throw new UnauthorizedError("Missing token");
+  throw new NotFoundError("User");
+});
+```
+
+Built-ins:
+
+- `BadRequestError` (400)
+- `UnauthorizedError` (401)
+- `ForbiddenError` (403)
+- `NotFoundError` (404)
+- `ConflictError` (409)
+- `InternalServerError` (500)
+
+## Wire format contract
+
+Known API errors are returned as a serialized object:
+
+```ts
+type SerializedApiError = {
+  name: string;
+  uid: string;
+  message: string;
+  status?: number;
+  details?: unknown;
+  isSerializableError: true;
+  [key: string]: unknown;
+};
+```
+
+Unhandled non-library errors return:
+
+```json
+{ "error": "An error occurred" }
+```
+
+## Frontend integration with ky (`afterResponse`)
+
+```ts
+import ky from "ky";
+import {
+  scanResponseAndThrowErrors,
+  BadRequestError,
+  NotFoundError,
+} from "@ideative/next-handler";
+
+const api = ky.create({
+  prefixUrl: "/api",
+  hooks: {
+    afterResponse: [
+      async (_req, _opts, response) => {
+        await scanResponseAndThrowErrors(response);
+        if (!response.ok) throw new Error(response.statusText);
+        return response;
+      },
+    ],
+  },
+});
+
+try {
+  await api.get("users/123").json();
+} catch (e) {
+  if (e instanceof NotFoundError) console.log(e.resource);
+  if (e instanceof BadRequestError) console.log(e.details);
+}
+```
+
+If you already have a `Response`, you can also call:
+
+```ts
+import { scanResponseAndThrowErrors } from "@ideative/next-handler";
+
+await scanResponseAndThrowErrors(response);
+```
+
+## Frontend integration with axios (response interceptor)
+
+```ts
+import axios from "axios";
+import { deserializeApiError } from "@ideative/next-handler";
+
+const api = axios.create({ baseURL: "/api" });
+
+api.interceptors.response.use(
+  (res) => res,
+  (err) => {
+    if (!axios.isAxiosError(err) || !err.response) return Promise.reject(err);
+    const data = err.response.data;
+    const candidate =
+      typeof data === "object" && data !== null && "error" in data
+        ? (data as { error: unknown }).error
+        : data;
+    const apiError = deserializeApiError(candidate);
+    return Promise.reject(apiError ?? err);
+  }
+);
+```
+
+## Custom error types
+
+`EndpointError` is abstract and expects `(name, status, message, details?)`.
+
+```ts
+import {
+  apiErrorFactory,
+  EndpointError,
+  type ErrorDeserializer,
+} from "@ideative/next-handler";
+
+class PaymentRequiredError extends EndpointError {
+  static ErrorName() {
+    return "PaymentRequiredError";
+  }
+  constructor(message = "Payment required") {
+    super(PaymentRequiredError.ErrorName(), 402, message);
+  }
+}
+
+const deserialize: ErrorDeserializer<PaymentRequiredError> = (d) =>
+  new PaymentRequiredError(d.message);
+
+apiErrorFactory.register(PaymentRequiredError, deserialize);
+```
+
+Register custom errors in both server and client runtime initialization so deserialization works everywhere.
+
+## Intl exports
+
+Import intl helpers from:
+
+- `@ideative/next-handler/intl`
+- `@ideative/next-handler/intl/intl-context`
+
+## API summary
+
+| Export | Description |
+| --- | --- |
+| `withApiHandler(handler)` | Wraps route handlers and converts thrown `EndpointError` values to JSON responses. |
+| `payload(schema)` | Reads and validates request JSON with Zod, throws `BadRequestError` on invalid input. |
+| `getRequest()` | Gets current `NextRequest` from AsyncLocalStorage context. |
+| `serializeApiError(error)` | Converts `SerializableError` to transport-safe payload. |
+| `deserializeApiError(data)` | Converts payload back to typed error, or `null` if payload is not recognized. |
+| `isSerializedApiError(data)` | Runtime type-guard for serialized payload shape. |
+| `scanResponseAndThrowErrors(response)` | Scans non-OK responses and rethrows serialized API errors if present. |
+| `apiErrorFactory.register(ctor, deserialize)` | Register custom error classes for round-trip behavior. |
+
+## v0.1.0 release checklist
+
+- `pnpm run build` emits all exported entry points.
+- `pnpm test` passes.
+- README examples match current runtime contracts.
+- `package.json` exports resolve to emitted `dist/` files.