@famgia/omnify-react-sso 2.2.0 → 2.2.2

package/README.md

@@ -14,12 +14,12 @@ pnpm add @famgia/omnify-react-sso
 
 - **React Hooks**: `useSso()`, `useAuth()`, `useOrganization()` for SSO state management
 - **React Components**: `SsoProvider`, `SsoCallback`, `OrganizationSwitcher`, `ProtectedRoute`
-- **SSO Service**: `createSsoService()` for API communication
-- **User Management**: User schema with Zod validation and i18n support
-- **Role-Based Access Control (RBAC)**: Role, Permission, and RolePermission schemas
-- **Team Management**: Team and TeamPermission schemas
+- **SSO Services**: Individual services for auth, roles, permissions, branches, teams
+- **SSO Schemas**: User, Role, Permission, Branch, Team with Zod validation and i18n
+- **Bundled Types**: `@omnify-base` types included - no extra setup needed
 - **Multi-locale Support**: Japanese and English labels/messages
 - **Query Keys**: Pre-defined TanStack Query keys for SSO data
+- **Test Utilities**: Mock factories and helpers for testing
 
 ## Quick Start
 
@@ -55,114 +55,342 @@ function Dashboard() {
     </div>
   );
 }
+
+// 3. Import types directly from package
+import type { Role, Permission, Branch, User } from '@famgia/omnify-react-sso';
 ```
 
 ---
 
 ## 🔧 Development & Build Workflow
 
-### Prerequisites
-
-This package depends on schemas from `omnifyjp/omnify-client-laravel-sso`. The build process will:
+> ⛔ **CRITICAL: DO NOT MODIFY THIS BUILD PROCESS**
+> 
+> Quy trình build này đã được thiết kế và test kỹ lưỡng. **TUYỆT ĐỐI KHÔNG ĐƯỢC THAY ĐỔI** các bước sau:
+> 1. `build:schemas` - Fetch và generate TypeScript từ YAML
+> 2. `build:lib` - Bundle với tsup
+> 3. `build:copy-base` - Copy @omnify-base vào dist (QUAN TRỌNG cho TypeScript consumers)
+> 4. `postinstall` - Tự động tạo @omnify-base cho consumers
+>
+> Nếu thay đổi, TypeScript consumers sẽ không resolve được types!
 
-1. **Try local**: Copy from `../omnify-client-laravel-sso/database/schemas/Sso`
-2. **Fallback to git**: Clone via SSH from GitHub (requires access to omnifyjp org)
+### Overview
 
-**SSH Access Required**: Developers must have SSH access to `git@github.com:omnifyjp/omnify-client-laravel-sso.git`
+This package bundles SSO schemas from the Laravel backend (`omnify-client-laravel-sso`) into a self-contained npm package. Consumers don't need to generate schemas - everything is included.
 
-### Build Commands
-
-```bash
-# Full build (schemas + library)
-pnpm build
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Source: omnify-client-laravel-sso                              │
+│  database/schemas/Sso/*.yaml                                    │
+│  (Branch, Permission, Role, Team, User, etc.)                   │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+                            ▼  pnpm build
+┌─────────────────────────────────────────────────────────────────┐
+│  Package: @famgia/omnify-react-sso                              │
+│                                                                  │
+│  dist/                                                           │
+│  ├── index.js          (hooks, components, services)            │
+│  ├── index.d.ts        (type definitions)                       │
+│  ├── schemas/          (bundled SSO schemas)                    │
+│  ├── testing/          (test utilities)                         │
+│  └── @omnify-base/     (bundled for TypeScript consumers)       │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+                            ▼  npm install
+┌─────────────────────────────────────────────────────────────────┐
+│  Consumer App (Boilerplate, etc.)                               │
+│                                                                  │
+│  import { useSso, Role, Permission } from '@famgia/...'         │
+│  // Everything just works - no schema generation needed!        │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-# Build only schemas (fetch + generate types)
-pnpm build:schemas
+### Prerequisites
 
-# Build only library (requires schemas to exist)
-pnpm build:lib
+1. **Node.js 18+** and **pnpm**
+2. **SSH Access** to `git@github.com:omnifyjp/omnify-client-laravel-sso.git`
+3. Test SSH: `ssh -T git@github.com`
 
-# Run tests
-pnpm test
+### Build Commands
 
-# Type check
-pnpm typecheck
-```
+| Command                | Description                                  |
+| ---------------------- | -------------------------------------------- |
+| `pnpm build`           | Full build (schemas → types → bundle → copy) |
+| `pnpm build:schemas`   | Fetch schemas and generate TypeScript types  |
+| `pnpm build:lib`       | Bundle with tsup (requires schemas)          |
+| `pnpm build:copy-base` | Copy @omnify-base to dist for consumers      |
+| `pnpm test`            | Run all tests                                |
+| `pnpm typecheck`       | Type check without emitting                  |
 
-### Build Process Detail
+### Build Process (Detailed)
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │                         pnpm build                               │
+│  "pnpm build:schemas && pnpm build:lib && pnpm build:copy-base" │
 └───────────────────────────┬─────────────────────────────────────┘
                             │
+        ┌───────────────────┼───────────────────┐
+        ▼                   ▼                   ▼
+┌───────────────┐  ┌───────────────┐  ┌───────────────────────┐
+│ build:schemas │  │   build:lib   │  │   build:copy-base     │
+│               │  │               │  │                       │
+│ 1. Clean      │  │ 1. tsup       │  │ cp -r node_modules/   │
+│    - schemas/ │  │    bundle     │  │   @omnify-base dist/  │
+│    - src/     │  │               │  │                       │
+│      schemas/ │  │ 2. Generate   │  │ ⚠️ CRITICAL STEP!     │
+│               │  │    .d.ts      │  │ Without this, TS      │
+│ 2. Get YAML   │  │               │  │ consumers can't       │
+│    schemas    │  │ 3. Output:    │  │ resolve types         │
+│    (local or  │  │    dist/*.js  │  │                       │
+│    git clone) │  │    dist/*.d.ts│  │                       │
+│               │  │               │  │                       │
+│ 3. omnify     │  │               │  │                       │
+│    generate   │  │               │  │                       │
+│    --types-   │  │               │  │                       │
+│    only       │  │               │  │                       │
+└───────────────┘  └───────────────┘  └───────────────────────┘
+        │                   │                   │
+        └───────────────────┼───────────────────┘
                             ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ Step 1: pnpm build:schemas                                       │
-│                                                                  │
-│  1. Clean previous builds (schemas/, src/schemas/, src/enum/)   │
-│  2. Obtain SSO schemas:                                         │
-│     - Try: ../omnify-client-laravel-sso/database/schemas/Sso    │
-│     - Fallback: git clone from GitHub (sparse checkout)          │
-│  3. Run: npx omnify generate --types-only                        │
-│     → Creates @omnify-base in node_modules                       │
-│     → Generates src/schemas/*.ts                                │
-└───────────────────────────┬─────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────────┐
-│ Step 2: pnpm build:lib (tsup)                                    │
-│                                                                  │
-│  - Bundle src/index.ts → dist/index.js                          │
-│  - Bundle src/schemas/index.ts → dist/schemas/index.js          │
-│  - Generate .d.ts type definitions                               │
-│  - External: zod, @omnify-base/*                                │
-└─────────────────────────────────────────────────────────────────┘
+                    dist/ (complete)
+                    ├── index.js
+                    ├── index.d.ts
+                    ├── schemas/
+                    ├── testing/
+                    └── @omnify-base/  ← TypeScript types
+```
+
+### Step-by-Step Build Details
+
+#### Step 1: `pnpm build:schemas` (scripts/build-schemas.ts)
+
+```typescript
+// 1. Clean previous builds
+rm -rf schemas/ src/schemas/ src/enum/
+
+// 2. Obtain SSO schema YAML files
+if (exists('../omnify-client-laravel-sso/database/schemas/Sso')) {
+  // Local copy (fastest)
+  cp -r ../omnify-client-laravel-sso/database/schemas/Sso → schemas/
+} else {
+  // Git clone (fallback)
+  git clone --sparse git@github.com:omnifyjp/omnify-client-laravel-sso.git
+  git sparse-checkout set database/schemas/Sso
+  cp schemas...
+}
+
+// 3. Generate TypeScript from YAML
+npx omnify generate --types-only
+// Creates:
+//   - node_modules/@omnify-base/schemas/*.ts
+//   - src/schemas/*.ts
+```
+
+#### Step 2: `pnpm build:lib` (tsup)
+
+```typescript
+// tsup.config.ts
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    'schemas/index': 'src/schemas/index.ts',
+    'testing/index': 'src/testing/index.ts',
+  },
+  format: ['esm', 'cjs'],
+  dts: true,                              // Generate .d.ts
+  clean: true,                            // Clean dist/ first
+  external: ['zod', 'react', ...],        // Don't bundle these
+  noExternal: [/@omnify-base\/.*/],       // Bundle @omnify-base JS
+});
+```
+
+**Important**: `noExternal: [/@omnify-base\/.*/]` bundles the JavaScript, but `.d.ts` files still reference `@omnify-base` externally.
+
+#### Step 3: `pnpm build:copy-base`
+
+```bash
+cp -r node_modules/@omnify-base dist/
+```
+
+**Why this is critical:**
+- The generated `.d.ts` files contain: `export { User } from '@omnify-base/schemas/User'`
+- TypeScript in consumer apps needs to resolve `@omnify-base`
+- Without this step, consumers get: `Cannot find module '@omnify-base/...'`
+
+#### Postinstall Script (scripts/postinstall.cjs)
+
+When consumers install the package, this script copies `@omnify-base` to their `node_modules`:
+
+```javascript
+// Runs automatically after npm install
+// Copies dist/@omnify-base → node_modules/@omnify-base
+// This allows TypeScript to resolve the types
 ```
 
 ### First Time Setup
 
 ```bash
-# Option A: Just run build (auto-fetches via SSH)
+# Option A: Build with auto-fetch (requires SSH access)
 pnpm install
-pnpm build  # Will clone schemas from git automatically
+pnpm build
 
-# Option B: Clone laravel-sso as sibling (for frequent schema changes)
-cd packages
+# Option B: Clone Laravel package as sibling (for development)
+cd /path/to/omnify/packages
 git clone git@github.com:omnifyjp/omnify-client-laravel-sso.git
 cd omnify-client-react-sso
 pnpm install
 pnpm build
 ```
 
-> **Note**: Build script uses SSH (`git@github.com:omnifyjp/...`). Ensure your SSH key is added to GitHub.
-
 ### When to Rebuild
 
-You need to run `pnpm build` when:
+| Scenario                         | Action                                      |
+| -------------------------------- | ------------------------------------------- |
+| First time setup                 | `pnpm build`                                |
+| Schema YAML changed in Laravel   | `pnpm build`                                |
+| Added new hook/component/service | `pnpm build:lib`                            |
+| Before publishing to npm         | `pnpm build && pnpm test`                   |
+| After `pnpm install`             | Usually not needed (postinstall handles it) |
+
+### Publishing Checklist
 
-- ✅ First time setup
-- ✅ Schema changes in `omnify-client-laravel-sso`
-- ✅ After pulling updates from laravel-sso
-- ✅ Before publishing to npm
+```bash
+# 1. Ensure you're on main branch
+git checkout main && git pull
+
+# 2. Full build
+pnpm build
+
+# 3. Run tests
+pnpm test
+
+# 4. Type check
+pnpm typecheck
+
+# 5. Bump version
+npm version patch  # or minor/major
+
+# 6. Publish
+npm publish --access public
+
+# 7. Verify on npm
+npm view @famgia/omnify-react-sso
+```
+
+---
+
+## 📦 Package Contents
+
+After build, `dist/` contains:
+
+```
+dist/
+├── index.js              # Main entry (ESM)
+├── index.cjs             # Main entry (CJS)
+├── index.d.ts            # Type definitions
+├── schemas/
+│   ├── index.js          # SSO schemas bundle
+│   └── index.d.ts
+├── testing/
+│   ├── index.js          # Test utilities
+│   └── index.d.ts
+├── @omnify-base/         # Bundled types for TS resolution
+│   ├── package.json
+│   └── schemas/
+│       ├── User.ts
+│       ├── Role.ts
+│       ├── Permission.ts
+│       ├── Branch.ts
+│       ├── Team.ts
+│       └── ...
+└── types-*.d.ts          # Internal type chunks
+```
 
 ---
 
 ## Local Development with Boilerplate
 
-### Linking Package to Boilerplate
+### Option 1: Use Published Package (Recommended)
+
+```bash
+# In boilerplate/frontend
+pnpm add @famgia/omnify-react-sso@latest
+```
+
+The postinstall script automatically sets up `@omnify-base` for TypeScript.
 
-Instead of using npm registry or tarballs, link the package directly:
+### Option 2: Link Local Package (Development)
 
 ```bash
 # In boilerplate/frontend
-pnpm add /path/to/omnify/packages/omnify-client-react-sso
+pnpm add link:/path/to/omnify/packages/omnify-client-react-sso
 ```
 
-This creates a symlink in `package.json`:
+**After linking, manually run postinstall:**
+```bash
+node node_modules/@famgia/omnify-react-sso/scripts/postinstall.cjs
+```
+
+### Consumer App Configuration
 
-```json
-"@famgia/omnify-react-sso": "link:/path/to/omnify/packages/omnify-client-react-sso"
+#### 1. Exclude SSO Schemas from Local Generation
+
+In `omnify.config.ts`:
+
+```typescript
+typescriptPlugin({
+  modelsPath: "./frontend/src/omnify/schemas",
+  exclude: [
+    // SSO types come from @famgia/omnify-react-sso
+    "Branch",
+    "Permission", 
+    "Role",
+    "RolePermission",
+    "Team",
+    "TeamPermission",
+    "User",  // Important!
+  ],
+})
+```
+
+#### 2. Import Patterns
+
+```typescript
+// ✅ CORRECT: SSO types from package
+import type { User, Role, Permission, Branch } from '@famgia/omnify-react-sso';
+import { useSso, useAuth } from '@famgia/omnify-react-sso';
+import { roleService, permissionService } from '@/lib/ssoService';  // configured instances
+
+// ✅ CORRECT: App-specific types from local
+import type { Product, Order } from '@/omnify/schemas';
+import { getProductFieldLabel } from '@/omnify/schemas';
+
+// ❌ WRONG: Don't import SSO types from local schemas
+import type { Role } from '@/omnify/schemas';  // Error or duplicate!
+```
+
+#### 3. Service Configuration
+
+Create `lib/ssoService.ts` to configure services with your API URL:
+
+```typescript
+import {
+  createAuthService,
+  createRoleService,
+  createPermissionService,
+  createBranchService,
+  createUserRoleService,
+} from '@famgia/omnify-react-sso';
+
+const apiUrl = process.env.NEXT_PUBLIC_API_URL!;
+
+export const authService = createAuthService({ apiUrl });
+export const roleService = createRoleService({ apiUrl });
+export const permissionService = createPermissionService({ apiUrl });
+export const branchService = createBranchService({ apiUrl });
+export const userRoleService = createUserRoleService({ apiUrl });
 ```
 
 ### Development Workflow
@@ -170,74 +398,49 @@ This creates a symlink in `package.json`:
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │  omnify-client-laravel-sso (Laravel Package)                    │
-│  - SSO schema YAML files (source of truth)                      │
-│  - Backend models, migrations, controllers                      │
+│  database/schemas/Sso/*.yaml  (Source of truth)                 │
 └───────────────────────────┬─────────────────────────────────────┘
-                            │ schemas copied during build
+                            │ pnpm build (copies + generates)
                             ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  @famgia/omnify-react-sso (This Package)                        │
-│                                                                  │
-│  pnpm build                                                      │
-│  ├── 1. Copy schemas from laravel-sso                           │
-│  ├── 2. omnify generate --types-only                            │
-│  └── 3. tsup bundle → dist/                                     │
-│                                                                  │
-│  Exports:                                                        │
-│  - React hooks (useSso, useAuth, useOrganization)               │
-│  - React components (SsoProvider, ProtectedRoute, etc.)         │
-│  - Services (createAuthService, createRoleService, etc.)        │
-│  - SSO Schemas (Role, Permission, Branch, Team, User)           │
-│  - Query Keys (ssoQueryKeys)                                    │
+│  dist/                                                           │
+│  ├── index.js     (hooks, components, services)                 │
+│  ├── schemas/     (SSO types: User, Role, Permission...)        │
+│  └── @omnify-base/(TypeScript resolution)                       │
 └───────────────────────────┬─────────────────────────────────────┘
-                            │ linked via pnpm
+                            │ npm install / pnpm link
                             ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  Boilerplate / Your App                                         │
 │                                                                  │
-│  package.json:                                                   │
-│  "@famgia/omnify-react-sso": "link:/path/to/package"            │
-│                                                                  │
-│  omnify.config.ts:                                               │
-│  typescriptPlugin({                                              │
-│    exclude: ["Branch", "Role", "Permission", ...]  // SSO types │
-│  })                                                              │
+│  Import from package:                                            │
+│  - useSso, useAuth, useOrganization                             │
+│  - User, Role, Permission, Branch, Team                         │
+│  - createRoleService, ssoQueryKeys, etc.                        │
 │                                                                  │
-│  Imports:                                                        │
-│  - SSO types → from "@famgia/omnify-react-sso"                  │
-│  - App types → from "@/omnify/schemas" (local generate)         │
+│  Generate locally (via omnify.config.ts):                       │
+│  - App-specific schemas only                                     │
+│  - Product, Order, Invoice, etc.                                │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
 ### After Changing SSO Schemas
 
-1. **Update Laravel package** (if schema YAML changed)
-2. **Rebuild this package:**
+1. **Edit YAML** in `omnify-client-laravel-sso/database/schemas/Sso/`
+2. **Rebuild package:**
    ```bash
    cd packages/omnify-client-react-sso
    pnpm build
    ```
-3. **Boilerplate automatically uses new dist** (linked)
-
-### Boilerplate Configuration
-
-In the boilerplate's `omnify.config.ts`, exclude SSO schemas:
-
-```typescript
-typescriptPlugin({
-  modelsPath: "./frontend/src/omnify/schemas",
-  exclude: [
-    "Branch",
-    "Permission",
-    "Role",
-    "RolePermission",
-    "Team",
-    "TeamPermission",
-  ],
-})
-```
-
-This prevents duplicate schema generation - SSO types come from this package.
+3. **If using npm (not link):** Publish and update
+   ```bash
+   npm version patch
+   npm publish --access public
+   # In boilerplate:
+   pnpm update @famgia/omnify-react-sso
+   ```
+4. **If using link:** Rebuild triggers automatic update
 
 ---
 
@@ -491,7 +694,95 @@ vi.mock('@famgia/omnify-react-sso', async () => {
 });
 ```
 
-> **Note**: Subpath exports (`/testing`) require the package to be installed from npm, not linked locally.
+> **Note**: Subpath exports (`/testing`) may not work with linked packages in Vite/Vitest. Use direct imports or install from npm.
+
+---
+
+## Troubleshooting
+
+### ❌ Cannot find module '@omnify-base/schemas/...'
+
+**Cause:** TypeScript can't resolve the bundled types.
+
+**Solutions:**
+
+1. **If installed from npm:** Run postinstall manually
+   ```bash
+   node node_modules/@famgia/omnify-react-sso/scripts/postinstall.cjs
+   ```
+
+2. **If using pnpm link:** Same as above
+   ```bash
+   cd your-app/frontend
+   node node_modules/@famgia/omnify-react-sso/scripts/postinstall.cjs
+   ```
+
+3. **Verify @omnify-base exists:**
+   ```bash
+   ls node_modules/@omnify-base/schemas/
+   # Should show: User.ts, Role.ts, Permission.ts, etc.
+   ```
+
+### ❌ Module has no exported member 'Role' (from @/omnify/schemas)
+
+**Cause:** You're importing SSO types from local schemas instead of the package.
+
+**Fix:** Change imports:
+```typescript
+// ❌ Wrong
+import type { Role } from '@/omnify/schemas';
+
+// ✅ Correct  
+import type { Role } from '@famgia/omnify-react-sso';
+```
+
+### ❌ Duplicate identifier 'User'
+
+**Cause:** SSO schemas generated locally AND imported from package.
+
+**Fix:** Add to `omnify.config.ts`:
+```typescript
+typescriptPlugin({
+  exclude: ["User", "Role", "Permission", "Branch", "Team", "RolePermission", "TeamPermission"],
+})
+```
+
+### ❌ Build fails: Cannot clone git repository
+
+**Cause:** No SSH access to omnifyjp/omnify-client-laravel-sso.
+
+**Fix:**
+```bash
+# Test SSH access
+ssh -T git@github.com
+
+# If needed, add SSH key to GitHub
+# Or clone manually as sibling:
+git clone git@github.com:omnifyjp/omnify-client-laravel-sso.git ../omnify-client-laravel-sso
+```
+
+### ❌ Tests fail with "Cannot find module '@famgia/omnify-react-sso/testing'"
+
+**Cause:** Subpath exports don't work well with linked packages in Vite.
+
+**Fix:** Create local mock file instead:
+```typescript
+// src/test/mocks/sso.ts
+export function createMockUser(overrides = {}) {
+  return { id: '1', name: 'Test User', email: 'test@example.com', ...overrides };
+}
+```
+
+---
+
+## Version History
+
+| Version | Changes                                                  |
+| ------- | -------------------------------------------------------- |
+| 2.2.1   | Bundled @omnify-base for TS consumers, added postinstall |
+| 2.2.0   | Added testing utilities subpath export                   |
+| 2.1.0   | Split services into individual factories                 |
+| 2.0.0   | Initial stable release                                   |
 
 ---
 

package/dist/@omnify-base/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@omnify-base",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./enum/*": {
+      "types": "./enum/*.ts",
+      "default": "./enum/*.ts"
+    },
+    "./schemas/*": {
+      "types": "./schemas/*.ts",
+      "default": "./schemas/*.ts"
+    }
+  }
+}