cushin-monorepo 3.0.1

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [],
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  }
+}

package/.claude/settings.local.json

@@ -0,0 +1,44 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm install:*)",
+      "Bash(pnpm build:*)",
+      "Bash(node /home/hash/work/node/api-codegen/packages/api-codegen/dist/cli.js:*)",
+      "Bash(tree:*)",
+      "Bash(mkdir:*)",
+      "Bash(node /home/hash/work/node/codegen/test-import.mjs:*)",
+      "Bash(node /home/hash/work/node/codegen/packages/test-package/test.mjs:*)",
+      "Bash(cat:*)",
+      "Bash(pnpm changeset:*)",
+      "Bash(pnpm version-packages:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(npx tsc:*)",
+      "Bash(pnpm typecheck:*)",
+      "Bash(node test.mjs:*)",
+      "Bash(git --git-dir=/home/hash/work/node/codegen/.git --work-tree=/home/hash/work/node/codegen status:*)",
+      "Bash(bash -c \"cd /home/hash/work/node/codegen && git status\")",
+      "Bash(bash -c 'cd /home/hash/work/node/codegen && pnpm changeset')",
+      "Bash(bash -c 'export HOME=/home/hash && cd /home/hash/work/node/codegen && /home/hash/work/node/codegen/node_modules/.bin/changeset version':*)",
+      "Bash(export HOME=/home/hash:*)",
+      "Bash(/usr/bin/bash:*)",
+      "Bash(node /home/hash/work/node/codegen/test-runtime-params.mjs:*)",
+      "Bash(node /home/hash/work/node/codegen/test-full-integration.mjs:*)",
+      "Bash(node /home/hash/work/node/codegen/test-internal-calls.mjs:*)",
+      "Bash(pnpm publish:*)",
+      "Bash(node test-full-integration.mjs:*)",
+      "Bash(node /home/hash/work/node/codegen/packages/api-codegen/dist/cli.js generate:*)",
+      "Bash(node test-headers-formdata.mjs:*)",
+      "Bash(node test-headers.mjs:*)",
+      "Bash(node test-headers-runtime.mjs:*)",
+      "Bash(node test-formdata-runtime.mjs:*)",
+      "Bash(pnpm -F @cushin/api-runtime build:*)",
+      "Bash(node test-ky-formdata.mjs:*)",
+      "Bash(pnpm add:*)",
+      "Bash(node test-content-type-handling.mjs:*)",
+      "Bash(node test-formdata-content-type-protection.mjs:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+## <small>4.0.5 (2025-12-19)</small>
+
+* feat: add custom headers support for endpoints - allows per-endpoint header configuration for API keys, tracking, and metadata
+* feat: add automatic FormData detection and handling - runtime client now detects FormData bodies and handles Content-Type correctly
+* docs: add comprehensive CUSTOM_HEADERS.md documentation with examples for file uploads, React hooks, and Next.js server actions
+* docs: update README with custom headers and FormData usage examples
+
+## <small>2.0.6 (2025-12-18)</small>
+
+* fix: handle undefined params in server-client and client type definitions - endpoints without params, query, or body no longer require passing undefined
+
+## <small>1.0.5 (2025-11-24)</small>
+
+* fix: add jiti loader to support TypeScript endpoint files ([eac2867](https://github.com/cushin-org/api-codegen/commit/eac2867))
+* fix: remove unused imports ([7c46e10](https://github.com/cushin-org/api-codegen/commit/7c46e10))
+* fix: resolve build and npm deployment errors ([cef18d7](https://github.com/cushin-org/api-codegen/commit/cef18d7))
+* chore: bump version to 1.0.1 - fix build and npm deployment errors ([6bda5b4](https://github.com/cushin-org/api-codegen/commit/6bda5b4))
+* chore: bump version to 1.0.2 ([5d3a6cd](https://github.com/cushin-org/api-codegen/commit/5d3a6cd))
+* chore: bump version to 1.0.3 ([d7f2489](https://github.com/cushin-org/api-codegen/commit/d7f2489))
+* chore: bump version to 1.0.4 ([7aa777e](https://github.com/cushin-org/api-codegen/commit/7aa777e))
+* chore: bump version to 1.0.4 ([a94bed3](https://github.com/cushin-org/api-codegen/commit/a94bed3))
+* chore: remove unused packed file ([694d3a8](https://github.com/cushin-org/api-codegen/commit/694d3a8))
+* docs: update CHANGELOG ([01b2c9c](https://github.com/cushin-org/api-codegen/commit/01b2c9c))
+* docs: update document for cli ([e27c4fa](https://github.com/cushin-org/api-codegen/commit/e27c4fa))
+* docs: update github username ([98b86f0](https://github.com/cushin-org/api-codegen/commit/98b86f0))
+* Add GitHub Actions workflow for npm publish ([0298a75](https://github.com/cushin-org/api-codegen/commit/0298a75))
+* init project ([d0847c2](https://github.com/cushin-org/api-codegen/commit/d0847c2))
+* update README ([65b6962](https://github.com/cushin-org/api-codegen/commit/65b6962))
+* update README ([e1866ed](https://github.com/cushin-org/api-codegen/commit/e1866ed))
+
+
+
+## <small>1.0.4 (2025-11-24)</small>
+
+* fix: add jiti loader to support TypeScript endpoint files ([eac2867](https://github.com/cushin-org/api-codegen/commit/eac2867))
+* fix: remove unused imports ([7c46e10](https://github.com/cushin-org/api-codegen/commit/7c46e10))
+* fix: resolve build and npm deployment errors ([cef18d7](https://github.com/cushin-org/api-codegen/commit/cef18d7))
+* chore: bump version to 1.0.1 - fix build and npm deployment errors ([6bda5b4](https://github.com/cushin-org/api-codegen/commit/6bda5b4))
+* chore: bump version to 1.0.2 ([5d3a6cd](https://github.com/cushin-org/api-codegen/commit/5d3a6cd))
+* chore: bump version to 1.0.3 ([d7f2489](https://github.com/cushin-org/api-codegen/commit/d7f2489))
+* chore: bump version to 1.0.4 ([7aa777e](https://github.com/cushin-org/api-codegen/commit/7aa777e))
+* chore: bump version to 1.0.4 ([a94bed3](https://github.com/cushin-org/api-codegen/commit/a94bed3))
+* chore: remove unused packed file ([694d3a8](https://github.com/cushin-org/api-codegen/commit/694d3a8))
+* docs: update CHANGELOG ([01b2c9c](https://github.com/cushin-org/api-codegen/commit/01b2c9c))
+* docs: update document for cli ([e27c4fa](https://github.com/cushin-org/api-codegen/commit/e27c4fa))
+* docs: update github username ([98b86f0](https://github.com/cushin-org/api-codegen/commit/98b86f0))
+* Add GitHub Actions workflow for npm publish ([0298a75](https://github.com/cushin-org/api-codegen/commit/0298a75))
+* init project ([d0847c2](https://github.com/cushin-org/api-codegen/commit/d0847c2))
+* update README ([65b6962](https://github.com/cushin-org/api-codegen/commit/65b6962))
+* update README ([e1866ed](https://github.com/cushin-org/api-codegen/commit/e1866ed))
+
+
+
+## <small>1.0.4 (2025-11-24)</small>
+
+* chore: bump version to 1.0.1 - fix build and npm deployment errors ([6bda5b4](https://github.com/cushin-org/api-codegen/commit/6bda5b4))
+* chore: bump version to 1.0.2 ([5d3a6cd](https://github.com/cushin-org/api-codegen/commit/5d3a6cd))
+* chore: bump version to 1.0.3 ([d7f2489](https://github.com/cushin-org/api-codegen/commit/d7f2489))
+* chore: bump version to 1.0.4 ([a94bed3](https://github.com/cushin-org/api-codegen/commit/a94bed3))
+* chore: remove unused packed file ([694d3a8](https://github.com/cushin-org/api-codegen/commit/694d3a8))
+* fix: add jiti loader to support TypeScript endpoint files ([eac2867](https://github.com/cushin-org/api-codegen/commit/eac2867))
+* fix: resolve build and npm deployment errors ([cef18d7](https://github.com/cushin-org/api-codegen/commit/cef18d7))
+* docs: update CHANGELOG ([01b2c9c](https://github.com/cushin-org/api-codegen/commit/01b2c9c))
+* docs: update document for cli ([e27c4fa](https://github.com/cushin-org/api-codegen/commit/e27c4fa))
+* docs: update github username ([98b86f0](https://github.com/cushin-org/api-codegen/commit/98b86f0))
+* Add GitHub Actions workflow for npm publish ([0298a75](https://github.com/cushin-org/api-codegen/commit/0298a75))
+* init project ([d0847c2](https://github.com/cushin-org/api-codegen/commit/d0847c2))
+* update README ([65b6962](https://github.com/cushin-org/api-codegen/commit/65b6962))
+* update README ([e1866ed](https://github.com/cushin-org/api-codegen/commit/e1866ed))
+
+
+
+## <small>1.0.2 (2025-11-22)</small>
+
+* docs: update document for cli ([e27c4fa](https://github.com/cushin-org/api-codegen/commit/e27c4fa))
+* docs: update github username ([98b86f0](https://github.com/cushin-org/api-codegen/commit/98b86f0))
+* Add GitHub Actions workflow for npm publish ([0298a75](https://github.com/cushin-org/api-codegen/commit/0298a75))
+* init project ([d0847c2](https://github.com/cushin-org/api-codegen/commit/d0847c2))
+* update README ([65b6962](https://github.com/cushin-org/api-codegen/commit/65b6962))
+* update README ([e1866ed](https://github.com/cushin-org/api-codegen/commit/e1866ed))
+* fix: resolve build and npm deployment errors ([cef18d7](https://github.com/cushin-org/api-codegen/commit/cef18d7))
+
+
+
+# 1.0.0 (2025-11-22)
+
+
+### Bug Fixes
+
+* resolve build and npm deployment errors ([cef18d7](https://github.com/hashdotlee/api-codegen/commit/cef18d795e2ac83818b3a06b7bb38bdecc46295b))
+
+
+

package/README.md

@@ -0,0 +1,482 @@
+# @cushin/api-codegen
+
+Type-safe API client generator for React/Next.js applications with automatic hooks and server actions generation.
+
+## Features
+
+- 🎯 **Type-Safe**: Full TypeScript support with Zod schema validation
+- 🔄 **Auto-Generated**: Generate React Query hooks, Server Actions, and Server Queries
+- 🚀 **Framework Agnostic**: Works with Vite, Next.js, and more
+- 🔐 **Auth Built-in**: Token refresh, automatic retry with customizable callbacks
+- 📦 **Zero Config**: Simple configuration with sensible defaults
+- 🎨 **Customizable**: Custom templates and generation options
+- 📤 **File Uploads**: Automatic FormData detection and handling
+- 🔧 **Custom Headers**: Per-endpoint header configuration for API keys and metadata
+
+## Installation
+
+```bash
+npm install @cushin/api-codegen ky zod
+# or
+pnpm add @cushin/api-codegen ky zod
+# or
+yarn add @cushin/api-codegen ky zod
+```
+
+For React Query support (client-side):
+```bash
+npm install @tanstack/react-query
+```
+
+## Quick Start
+
+### 1. Initialize Configuration
+
+```bash
+npx @cushin/api-codegen init --provider vite
+# or for Next.js
+npx @cushin/api-codegen init --provider nextjs
+```
+
+This creates `api-codegen.config.js`:
+
+```js
+/** @type {import('@cushin/api-codegen').UserConfig} */
+export default {
+  provider: 'vite',
+  endpoints: './lib/api/config/endpoints.ts',
+  output: './lib/api/generated',
+  baseUrl: process.env.VITE_API_URL,
+  generateHooks: true,
+  generateClient: true,
+};
+```
+
+### 2. Define Your API Endpoints
+
+Create your endpoints configuration file:
+
+```typescript
+// lib/api/config/endpoints.ts
+import { z } from 'zod';
+import { defineConfig, defineEndpoint } from '@cushin/api-codegen';
+
+// Define your schemas
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const CreateUserSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+});
+
+// Define your endpoints
+export const apiConfig = defineConfig({
+  baseUrl: 'https://api.example.com',
+  endpoints: {
+    // GET request
+    getUser: defineEndpoint({
+      path: '/users/:id',
+      method: 'GET',
+      params: z.object({ id: z.string() }),
+      response: UserSchema,
+      tags: ['users', 'query'],
+      description: 'Get user by ID',
+    }),
+
+    // GET with query params
+    listUsers: defineEndpoint({
+      path: '/users',
+      method: 'GET',
+      query: z.object({
+        page: z.number().optional(),
+        limit: z.number().optional(),
+      }),
+      response: z.array(UserSchema),
+      tags: ['users', 'query'],
+    }),
+
+    // POST request
+    createUser: defineEndpoint({
+      path: '/users',
+      method: 'POST',
+      body: CreateUserSchema,
+      response: UserSchema,
+      tags: ['users', 'mutation'],
+    }),
+
+    // PUT request with params
+    updateUser: defineEndpoint({
+      path: '/users/:id',
+      method: 'PUT',
+      params: z.object({ id: z.string() }),
+      body: CreateUserSchema,
+      response: UserSchema,
+      tags: ['users', 'mutation'],
+    }),
+
+    // DELETE request
+    deleteUser: defineEndpoint({
+      path: '/users/:id',
+      method: 'DELETE',
+      params: z.object({ id: z.string() }),
+      response: z.object({ success: z.boolean() }),
+      tags: ['users', 'mutation'],
+    }),
+  },
+});
+```
+
+### 3. Generate Code
+
+```bash
+npx @cushin/api-codegen generate
+```
+
+This generates:
+- `generated/types.ts` - Type definitions
+- `generated/client.ts` - API client
+- `generated/hooks.ts` - React Query hooks
+- `generated/actions.ts` - Server Actions (Next.js only)
+- `generated/queries.ts` - Server Queries (Next.js only)
+
+### 4. Initialize Client (Vite)
+
+```typescript
+// lib/auth/provider.tsx
+import { initializeAPIClient } from '@/lib/api/generated/client';
+
+export function AuthProvider({ children }) {
+  useEffect(() => {
+    initializeAPIClient({
+      getTokens: () => {
+        const token = localStorage.getItem('access_token');
+        return token ? { accessToken: token } : null;
+      },
+      setTokens: (tokens) => {
+        localStorage.setItem('access_token', tokens.accessToken);
+      },
+      clearTokens: () => {
+        localStorage.removeItem('access_token');
+      },
+      onAuthError: () => {
+        router.push('/login');
+      },
+      onRefreshToken: async () => {
+        const response = await fetch('/api/auth/refresh', {
+          method: 'POST',
+          credentials: 'include',
+        });
+        const data = await response.json();
+        return data.accessToken;
+      },
+    });
+  }, []);
+
+  return <>{children}</>;
+}
+```
+
+### 5. Use Generated Hooks
+
+```typescript
+// components/UserList.tsx
+import { useListUsers, useCreateUser, useDeleteUser } from '@/lib/api/generated/hooks';
+
+export function UserList() {
+  // Query hook
+  const { data: users, isLoading } = useListUsers({
+    page: 1,
+    limit: 10,
+  });
+
+  // Mutation hooks
+  const createUser = useCreateUser({
+    onSuccess: () => {
+      console.log('User created!');
+    },
+  });
+
+  const deleteUser = useDeleteUser();
+
+  const handleCreate = () => {
+    createUser.mutate({
+      name: 'John Doe',
+      email: 'john@example.com',
+    });
+  };
+
+  const handleDelete = (id: string) => {
+    deleteUser.mutate({ id });
+  };
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <button onClick={handleCreate}>Create User</button>
+      {users?.map((user) => (
+        <div key={user.id}>
+          {user.name}
+          <button onClick={() => handleDelete(user.id)}>Delete</button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Next.js Usage
+
+### Server Components
+
+```typescript
+// app/users/page.tsx
+import { listUsersQuery } from '@/lib/api/generated/queries';
+
+export default async function UsersPage() {
+  const users = await listUsersQuery({ page: 1, limit: 10 });
+
+  return (
+    <div>
+      {users.map((user) => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Server Actions
+
+```typescript
+// app/users/actions.ts
+'use client';
+
+import { createUserAction, deleteUserAction } from '@/lib/api/generated/actions';
+import { useTransition } from 'react';
+
+export function UserForm() {
+  const [isPending, startTransition] = useTransition();
+
+  const handleSubmit = async (formData: FormData) => {
+    startTransition(async () => {
+      const result = await createUserAction({
+        name: formData.get('name') as string,
+        email: formData.get('email') as string,
+      });
+
+      if (result.success) {
+        console.log('User created:', result.data);
+      } else {
+        console.error('Error:', result.error);
+      }
+    });
+  };
+
+  return <form action={handleSubmit}>...</form>;
+}
+```
+
+## Configuration
+
+### Full Configuration Options
+
+```typescript
+/** @type {import('@cushin/api-codegen').UserConfig} */
+export default {
+  // Required: Provider type
+  provider: 'vite' | 'nextjs',
+
+  // Required: Path to endpoints configuration
+  endpoints: './lib/api/config/endpoints.ts',
+
+  // Required: Output directory
+  output: './lib/api/generated',
+
+  // Optional: Base URL (can also be set at runtime)
+  baseUrl: process.env.VITE_API_URL,
+
+  // Optional: Generation flags
+  generateHooks: true, // Generate React Query hooks
+  generateClient: true, // Generate API client
+  generateServerActions: true, // Next.js only
+  generateServerQueries: true, // Next.js only
+
+  // Optional: Advanced options
+  options: {
+    useClientDirective: true, // Add 'use client' to generated files
+    hookPrefix: 'use', // Prefix for hook names (e.g., useGetUser)
+    actionSuffix: 'Action', // Suffix for action names (e.g., createUserAction)
+    customImports: {
+      // Add custom imports to generated files
+      hooks: ['import { customHook } from "./custom"'],
+    },
+  },
+};
+```
+
+## CLI Commands
+
+```bash
+# Generate code from config
+npx @cushin/api-codegen generate
+
+# Generate with specific config file
+npx @cushin/api-codegen generate --config ./custom.config.js
+
+# Initialize new config
+npx @cushin/api-codegen init --provider nextjs
+
+# Validate configuration
+npx @cushin/api-codegen validate
+```
+
+## Advanced Usage
+
+### Custom Headers
+
+Add custom headers to specific endpoints for API keys, tracking, or other metadata:
+
+```typescript
+defineEndpoint({
+  path: '/api/data',
+  method: 'POST',
+  body: z.object({ name: z.string() }),
+  response: z.object({ id: z.string() }),
+  headers: {
+    'X-API-Key': process.env.THIRD_PARTY_API_KEY,
+    'X-Custom-Header': 'custom-value',
+  },
+});
+```
+
+### FormData Support
+
+The client automatically detects and handles FormData for file uploads:
+
+```typescript
+// Define endpoint (no body schema needed for FormData)
+const uploadAvatar = defineEndpoint({
+  path: '/users/:userId/avatar',
+  method: 'POST',
+  params: z.object({ userId: z.string() }),
+  response: z.object({ avatarUrl: z.string() }),
+  headers: {
+    'X-Upload-Source': 'web-app', // Optional custom headers
+  },
+});
+
+// Usage
+const formData = new FormData();
+formData.append('avatar', fileBlob, 'avatar.jpg');
+
+const result = await apiClient.uploadAvatar(
+  { userId: '123' },
+  formData
+);
+```
+
+See [CUSTOM_HEADERS.md](./CUSTOM_HEADERS.md) for detailed documentation and examples.
+
+### Custom Base URL per Endpoint
+
+```typescript
+defineEndpoint({
+  path: '/auth/login',
+  method: 'POST',
+  baseUrl: 'https://auth.example.com', // Override base URL
+  body: LoginSchema,
+  response: TokenSchema,
+});
+```
+
+### Multiple Endpoints Files
+
+```typescript
+// lib/api/config/modules/users.ts
+export const userEndpoints = {
+  getUser: defineEndpoint({ ... }),
+  createUser: defineEndpoint({ ... }),
+};
+
+// lib/api/config/endpoints.ts
+import { userEndpoints } from './modules/users';
+import { productEndpoints } from './modules/products';
+
+export const apiConfig = defineConfig({
+  baseUrl: 'https://api.example.com',
+  endpoints: {
+    ...userEndpoints,
+    ...productEndpoints,
+  },
+});
+```
+
+### Custom Auth Logic
+
+```typescript
+initializeAPIClient({
+  getTokens: () => {
+    // Custom token retrieval
+    return yourAuthStore.getTokens();
+  },
+  setTokens: (tokens) => {
+    // Custom token storage
+    yourAuthStore.setTokens(tokens);
+  },
+  clearTokens: () => {
+    // Custom cleanup
+    yourAuthStore.clearTokens();
+  },
+  onRefreshToken: async () => {
+    // Custom refresh logic
+    const newToken = await yourRefreshFunction();
+    return newToken;
+  },
+  onAuthError: () => {
+    // Custom error handling
+    yourRouter.push('/login');
+  },
+});
+```
+
+## Type Safety
+
+All generated code is fully typed:
+
+```typescript
+// IntelliSense knows the exact shape
+const { data } = useGetUser({ id: '123' });
+//     ^? { id: string; name: string; email: string; }
+
+// TypeScript will error on invalid params
+const { data } = useGetUser({ id: 123 }); // ❌ Type error
+const { data } = useGetUser({ wrongParam: '123' }); // ❌ Type error
+
+// Mutation inputs are also typed
+createUser.mutate({
+  name: 'John',
+  email: 'invalid', // ❌ Type error: invalid email format
+});
+```
+
+## Best Practices
+
+1. **Organize endpoints by feature/module**
+2. **Use descriptive endpoint names**
+3. **Add descriptions to endpoints for better documentation**
+4. **Use tags for query invalidation**
+5. **Define reusable schemas**
+6. **Keep baseUrl in environment variables**
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guide.
+
+## License
+
+MIT © Le Viet Hoang

package/biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.5/schema.json",
+  "vcs": {
+    "enabled": false,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node