create-next-style-guide 0.0.0-stage → 0.1.2

package/addons/endpoints/src/endpoints/Types.ts

@@ -0,0 +1,105 @@
+/* -------------------------------------------------------------------------- */
+/*                                   Request                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Query params + JSON body wrapper used by every endpoint call. */
+export type ApiRequestData<TParams = undefined, TBody = undefined> = {
+  params?: TParams;
+  body?: TBody;
+};
+
+/** Standard argument shape for endpoint functions. */
+export type ApiRequest<TParams = undefined, TBody = undefined> = {
+  request?: ApiRequestData<TParams, TBody>;
+};
+
+export type ApiListParams = {
+  all?: string;
+  order?: string;
+  search?: string;
+};
+
+export type ApiPaginatedParams = {
+  page_size?: string | number;
+  p?: string | number;
+  order?: string;
+  search?: string;
+};
+
+export type ApiRequestAll<TParams = undefined, TBody = undefined> = ApiRequest<
+  ApiListParams & TParams,
+  TBody
+>;
+
+export type ApiRequestPaginated<TParams = undefined, TBody = undefined> =
+  ApiRequest<ApiPaginatedParams & TParams, TBody>;
+
+/* -------------------------------------------------------------------------- */
+/*                                  Response                                  */
+/* -------------------------------------------------------------------------- */
+
+/** API envelope for a single object `result`. */
+export type ApiObjectResponse<T> = {
+  result: T;
+  status: number;
+  success: boolean;
+  messages: Record<string, unknown>;
+};
+
+/** API envelope for an unpaginated list `result`. */
+export type ApiListResponse<T> = {
+  result: T[];
+  status: number;
+  success: boolean;
+  messages: Record<string, unknown>;
+};
+
+/** API envelope for page-number paginated `result`. */
+export type ApiPaginatedResponse<T> = {
+  result: {
+    count: number;
+    next: string | null;
+    previous: string | null;
+    page_size: number;
+    results: T[];
+  };
+  status: number;
+  success: boolean;
+  messages: Record<string, unknown>;
+};
+
+/** Limit/offset page payload (often the unwrapped `result` of list endpoints). */
+export type ApiLimitOffsetPage<T> = {
+  limit: number;
+  offset: number;
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: T[];
+};
+
+/** API envelope for limit/offset paginated `result`. */
+export type ApiLimitOffsetResponse<T> = {
+  result: ApiLimitOffsetPage<T>;
+  status: number;
+  success: boolean;
+  messages: Record<string, unknown>;
+};
+
+/* -------------------------------------------------------------------------- */
+/*                                   Errors                                   */
+/* -------------------------------------------------------------------------- */
+
+/** Single message item from standard API error payload. */
+export type ApiMessageItem = {
+  message: string;
+  code?: string;
+};
+
+/** API error response envelope (HTTP 400). */
+export type ApiErrorEnvelope = {
+  success: boolean;
+  status: number;
+  result: unknown[];
+  messages: Record<string, ApiMessageItem[] | string[] | string>;
+};

package/addons/endpoints/src/endpoints/index.ts

@@ -0,0 +1,2 @@
+/** Hand-written stubs until you run `pnpm endpoints:generate`. */
+export * from "./Types";

package/addons/endpoints/src/utils/api-error.ts

@@ -0,0 +1,181 @@
+import { isAxiosError } from "axios";
+
+import type { ApiErrorEnvelope, ApiMessageItem } from "@/endpoints/Types";
+
+export type { ApiErrorEnvelope, ApiMessageItem };
+
+function codeFromValue(value: unknown): string | null {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const code = codeFromValue(item);
+      if (code) return code;
+    }
+    return null;
+  }
+
+  if (value && typeof value === "object" && "code" in value) {
+    const code = (value as ApiMessageItem).code;
+    if (typeof code === "string" && code.trim()) return code.trim();
+  }
+
+  return null;
+}
+
+function envelopeMessages(error: unknown): Record<string, unknown> | null {
+  if (!isAxiosError(error)) return null;
+
+  const messages = (error.response?.data as { messages?: unknown } | undefined)
+    ?.messages;
+  if (!messages || typeof messages !== "object") return null;
+
+  if (!Array.isArray(messages)) {
+    return messages as Record<string, unknown>;
+  }
+
+  const mapped: Record<string, unknown> = {};
+  for (let i = 0; i < messages.length; i += 1) {
+    const item = messages[i];
+    if (item && typeof item === "object") {
+      const field = (item as { field?: unknown }).field;
+      if (typeof field === "string" && field.trim()) {
+        mapped[field.trim()] = item;
+      } else {
+        mapped[`_${i}`] = item;
+      }
+    }
+  }
+  return mapped;
+}
+
+function messageFromValue(value: unknown): string | null {
+  if (typeof value === "string" && value.trim()) return value;
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item === "string" && item.trim()) return item;
+      if (item && typeof item === "object" && "message" in item) {
+        const text = (item as ApiMessageItem).message;
+        if (typeof text === "string" && text.trim()) return text;
+      }
+    }
+  }
+
+  if (value && typeof value === "object" && "message" in value) {
+    const text = (value as ApiMessageItem).message;
+    if (typeof text === "string" && text.trim()) return text;
+  }
+
+  return null;
+}
+
+export const NETWORK_ERROR_MESSAGE =
+  "Could not reach the API. Check the network or that the server is running.";
+
+export const SERVER_ERROR_MESSAGE =
+  "The API returned a server error. Try again later.";
+
+export function isNetworkError(error: unknown): boolean {
+  if (!isAxiosError(error)) return false;
+  return (
+    !error.response ||
+    error.code === "ERR_NETWORK" ||
+    error.code === "ECONNREFUSED" ||
+    error.code === "ETIMEDOUT" ||
+    error.message === "Network Error"
+  );
+}
+
+export function isServerError(error: unknown): boolean {
+  if (!isAxiosError(error)) return false;
+  const status = error.response?.status;
+  return typeof status === "number" && status >= 500;
+}
+
+export function getApiErrorMessage(
+  error: unknown,
+  fallback = "Something went wrong. Please try again.",
+): string {
+  if (isNetworkError(error)) return NETWORK_ERROR_MESSAGE;
+  if (isServerError(error)) return SERVER_ERROR_MESSAGE;
+
+  if (!isAxiosError(error)) {
+    if (error instanceof Error && error.message.trim()) return error.message;
+    return fallback;
+  }
+
+  const data = error.response?.data as
+    | { messages?: Record<string, unknown>; detail?: unknown }
+    | undefined;
+
+  const messages = envelopeMessages(error);
+  if (messages) {
+    for (const value of Object.values(messages)) {
+      const message = messageFromValue(value);
+      if (message) return message;
+    }
+  }
+
+  const detail = messageFromValue(data?.detail);
+  if (detail) return detail;
+
+  return fallback;
+}
+
+export function getApiErrorCode(error: unknown): string | null {
+  if (!isAxiosError(error)) return null;
+
+  const data = error.response?.data as
+    | { messages?: Record<string, unknown>; detail?: unknown; code?: unknown }
+    | undefined;
+
+  if (typeof data?.code === "string" && data.code.trim()) {
+    return data.code.trim();
+  }
+
+  const messages = envelopeMessages(error);
+  if (messages) {
+    for (const value of Object.values(messages)) {
+      const code = codeFromValue(value);
+      if (code) return code;
+    }
+  }
+
+  return codeFromValue(data?.detail);
+}
+
+export function getApiHttpStatus(error: unknown): number | undefined {
+  if (!isAxiosError(error)) return undefined;
+  return error.response?.status;
+}
+
+export function getApiErrorFieldCode(
+  error: unknown,
+  field: string,
+): string | null {
+  const messages = envelopeMessages(error);
+  if (!messages || !(field in messages)) return null;
+  return codeFromValue(messages[field]);
+}
+
+export function getApiErrorFieldMessage(
+  error: unknown,
+  field: string,
+): string | null {
+  const messages = envelopeMessages(error);
+  if (!messages || !(field in messages)) return null;
+  return messageFromValue(messages[field]);
+}
+
+export function extractApiFieldErrors(
+  error: unknown,
+): Record<string, string> {
+  const messages = envelopeMessages(error);
+  if (!messages) return {};
+
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(messages)) {
+    const msg = messageFromValue(value);
+    if (msg) result[key] = msg;
+  }
+  return result;
+}

package/addons/endpoints/src/utils/api-result.ts

@@ -0,0 +1,13 @@
+/**
+ * Many APIs return `{ result, status, success, messages }`.
+ * Some auth responses may be the bare payload.
+ */
+export function unwrapApiResult<T>(data: unknown): T {
+  if (data && typeof data === "object" && "result" in data) {
+    const result = (data as { result: unknown }).result;
+    if (result !== undefined && result !== null) {
+      return result as T;
+    }
+  }
+  return data as T;
+}

package/addons/endpoints/src/utils/axios-instance.ts

@@ -0,0 +1,23 @@
+import axios from "axios";
+
+const baseURL = process.env.NEXT_PUBLIC_API_URL ?? "";
+
+/**
+ * Shared Axios client for `src/endpoints/*`.
+ * Do not call from UI components directly — go through generated endpoint modules.
+ */
+export const api = axios.create({
+  baseURL,
+  headers: {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  },
+});
+
+api.interceptors.request.use((config) => {
+  // Let the browser set multipart boundary; default JSON Content-Type breaks FormData.
+  if (typeof FormData !== "undefined" && config.data instanceof FormData) {
+    config.headers.delete("Content-Type");
+  }
+  return config;
+});

package/addons/endpoints/src/utils/form-data.ts

@@ -0,0 +1,37 @@
+/**
+ * JSON body as-is, or multipart FormData when any value is a File/Blob.
+ * Used by OpenAPI codegen for upload endpoints.
+ */
+export function toApiBody(
+  body: Record<string, unknown> | undefined,
+): FormData | Record<string, unknown> | undefined {
+  if (!body) {
+    return undefined;
+  }
+
+  const hasFile = Object.values(body).some(
+    (value) =>
+      (typeof File !== "undefined" && value instanceof File) ||
+      (typeof Blob !== "undefined" && value instanceof Blob),
+  );
+
+  if (!hasFile) {
+    return body;
+  }
+
+  const form = new FormData();
+  for (const [key, value] of Object.entries(body)) {
+    if (value === undefined || value === null) continue;
+    if (
+      (typeof File !== "undefined" && value instanceof File) ||
+      (typeof Blob !== "undefined" && value instanceof Blob)
+    ) {
+      form.append(key, value);
+    } else if (typeof value === "object") {
+      form.append(key, JSON.stringify(value));
+    } else {
+      form.append(key, String(value));
+    }
+  }
+  return form;
+}

package/addons/endpoints/src/utils/search-params.ts

@@ -0,0 +1,21 @@
+/** Build `?a=1&b=2` from a params object (skips empty values). */
+export function toSearchParams(
+  params:
+    | Record<string, string | number | boolean | null | undefined>
+    | undefined,
+): string {
+  if (!params) {
+    return "";
+  }
+
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === "") {
+      continue;
+    }
+    search.set(key, String(value));
+  }
+
+  const query = search.toString();
+  return query ? `?${query}` : "";
+}

package/addons/eslint/.cursor/rules/eslint.mdc

@@ -0,0 +1,12 @@
+---
+description: Enhanced ESLint conventions (import order, func-style)
+globs: eslint.config.mjs,src/**/*.{ts,tsx}
+alwaysApply: false
+---
+
+# ESLint
+
+- Import order (simple-import-sort): react/next → packages → `@/app` → `@/providers` → `@/endpoints` → `@/components` → `@/hooks` → `@/lib` → `@/utils` → other `@/` → relative → css.
+- `function Name()` declarations (not `const Name = () =>` for components/helpers that ESLint `func-style` covers).
+- JSX props: shorthand first, callbacks last (`react/jsx-sort-props`).
+- Scripts: `pnpm lint` · `pnpm lint:fix`. Prefer `required_permissions: ["all"]` for shell lint in agents.

package/addons/eslint/docs/style-guide/tooling/eslint.md

@@ -0,0 +1,13 @@
+# ESLint
+
+Enhanced flat config: `eslint.config.mjs`.
+
+- Next core-web-vitals + TypeScript
+- `eslint-plugin-simple-import-sort` + `eslint-plugin-import`
+- `func-style: declaration`, `react/jsx-sort-props`
+- `eslint-config-prettier` (turns off formatting rules that clash with Prettier)
+
+```bash
+pnpm lint
+pnpm lint:fix
+```

package/addons/eslint/eslint.config.mjs

@@ -0,0 +1,85 @@
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import eslintConfigPrettier from "eslint-config-prettier";
+import importPlugin from "eslint-plugin-import";
+import simpleImportSort from "eslint-plugin-simple-import-sort";
+
+/**
+ * Enhanced flat config (import sort, func-style, jsx-sort-props).
+ * Prettier disable-conflicts block is always included; harmless without Prettier.
+ */
+const eslintConfig = [
+  ...nextVitals,
+  ...nextTs,
+  eslintConfigPrettier,
+  {
+    settings: {
+      react: {
+        version: "19",
+      },
+    },
+    plugins: {
+      import: importPlugin,
+      "simple-import-sort": simpleImportSort,
+    },
+    rules: {
+      "simple-import-sort/imports": [
+        "error",
+        {
+          groups: [
+            ["^react\\u0000?$", "^react/", "^next", "^next/"],
+            ["^@?\\w"],
+            ["^@/app"],
+            ["^@/providers"],
+            ["^@/endpoints"],
+            ["^@/components"],
+            ["^@/hooks"],
+            ["^@/lib"],
+            ["^@/utils"],
+            ["^@/"],
+            ["^~"],
+            ["^\\.\\.(?!/?$)", "^\\.\\./?$"],
+            ["^\\./(?=.*/)(?!/?$)", "^\\.(?!/?$)", "^\\./?$"],
+            ["^.+\\.s?css$"],
+            ["^\\u0000"],
+          ],
+        },
+      ],
+      "simple-import-sort/exports": "error",
+      "import/first": "error",
+      "import/newline-after-import": "error",
+      "import/no-duplicates": "error",
+
+      "react/react-in-jsx-scope": "off",
+      "react/jsx-sort-props": [
+        "error",
+        {
+          callbacksLast: true,
+          shorthandFirst: true,
+          multiline: "last",
+        },
+      ],
+
+      "func-style": ["error", "declaration", { allowArrowFunctions: false }],
+
+      "@typescript-eslint/no-unused-expressions": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-empty-object-type": "off",
+      "no-unused-vars": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+          ignoreRestSiblings: true,
+        },
+      ],
+    },
+  },
+  {
+    ignores: [".next/**", "out/**", "build/**", "next-env.d.ts", "node_modules/**"],
+  },
+];
+
+export default eslintConfig;

package/addons/husky/.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+npx lint-staged

package/addons/husky/docs/style-guide/tooling/husky.md

@@ -0,0 +1,10 @@
+# Husky + lint-staged
+
+Pre-commit runs `npx lint-staged` (Prettier and/or ESLint — whatever was enabled at scaffold).
+
+| Path | Role |
+|------|------|
+| `.husky/pre-commit` | Hook entry |
+| `package.json` → `lint-staged` | Globs |
+
+`prepare`: `husky` — runs after install.

package/addons/prettier/.cursor/rules/prettier.mdc

@@ -0,0 +1,11 @@
+---
+description: Prettier formatting
+globs: .prettierrc,**/*.{ts,tsx,js,jsx,json,css,md,yml,yaml}
+alwaysApply: false
+---
+
+# Prettier
+
+- Config: `.prettierrc` (printWidth 100, double quotes, trailing commas).
+- Do not hand-fight formatting — run `pnpm format`.
+- With Husky: lint-staged runs Prettier before ESLint on commit.

package/addons/prettier/.prettierrc

@@ -0,0 +1,14 @@
+{
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "htmlWhitespaceSensitivity": "css",
+  "printWidth": 100,
+  "proseWrap": "preserve",
+  "quoteProps": "as-needed",
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "useTabs": false
+}

package/addons/prettier/docs/style-guide/tooling/prettier.md

@@ -0,0 +1,9 @@
+# Prettier
+
+Config: `.prettierrc`.
+
+```bash
+pnpm format
+```
+
+When Husky is enabled, pre-commit runs Prettier via lint-staged.