@famgia/omnify-react-sso 2.1.0 → 2.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @famgia/omnify-react-sso
 
-SSO (Single Sign-On) schemas, types, and utilities for Omnify Console integration.
+SSO (Single Sign-On) schemas, types, React hooks, components, and utilities for Omnify Console integration.
 
 ## Installation
 
@@ -12,11 +12,234 @@ pnpm add @famgia/omnify-react-sso
 
 ## Features
 
+- **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
 - **Multi-locale Support**: Japanese and English labels/messages
-- **ServiceInstance Compatible**: Works with Console's multi-instance architecture
+- **Query Keys**: Pre-defined TanStack Query keys for SSO data
+
+## Quick Start
+
+```tsx
+// 1. Wrap your app with SsoProvider
+import { SsoProvider } from '@famgia/omnify-react-sso';
+
+function App() {
+  return (
+    <SsoProvider config={{
+      apiUrl: process.env.NEXT_PUBLIC_API_URL,
+      consoleUrl: process.env.NEXT_PUBLIC_SSO_URL,
+      loginPath: '/login',
+      callbackPath: '/sso/callback',
+    }}>
+      <YourApp />
+    </SsoProvider>
+  );
+}
+
+// 2. Use hooks in your components
+import { useSso } from '@famgia/omnify-react-sso';
+
+function Dashboard() {
+  const { user, isAuthenticated, currentOrg, logout } = useSso();
+  
+  if (!isAuthenticated) return <Login />;
+  
+  return (
+    <div>
+      Welcome, {user.name}!
+      Current org: {currentOrg?.name}
+    </div>
+  );
+}
+```
+
+---
+
+## 🔧 Development & Build Workflow
+
+### Prerequisites
+
+This package depends on schemas from `omnifyjp/omnify-client-laravel-sso`. The build process will:
+
+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)
+
+**SSH Access Required**: Developers must have SSH access to `git@github.com:omnifyjp/omnify-client-laravel-sso.git`
+
+### Build Commands
+
+```bash
+# Full build (schemas + library)
+pnpm build
+
+# Build only schemas (fetch + generate types)
+pnpm build:schemas
+
+# Build only library (requires schemas to exist)
+pnpm build:lib
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm typecheck
+```
+
+### Build Process Detail
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         pnpm build                               │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 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/*                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### First Time Setup
+
+```bash
+# Option A: Just run build (auto-fetches via SSH)
+pnpm install
+pnpm build  # Will clone schemas from git automatically
+
+# Option B: Clone laravel-sso as sibling (for frequent schema changes)
+cd 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:
+
+- ✅ First time setup
+- ✅ Schema changes in `omnify-client-laravel-sso`
+- ✅ After pulling updates from laravel-sso
+- ✅ Before publishing to npm
+
+---
+
+## Local Development with Boilerplate
+
+### Linking Package to Boilerplate
+
+Instead of using npm registry or tarballs, link the package directly:
+
+```bash
+# In boilerplate/frontend
+pnpm add /path/to/omnify/packages/omnify-client-react-sso
+```
+
+This creates a symlink in `package.json`:
+
+```json
+"@famgia/omnify-react-sso": "link:/path/to/omnify/packages/omnify-client-react-sso"
+```
+
+### Development Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  omnify-client-laravel-sso (Laravel Package)                    │
+│  - SSO schema YAML files (source of truth)                      │
+│  - Backend models, migrations, controllers                      │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │ schemas copied during build
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  @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)                                    │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │ linked via pnpm
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Boilerplate / Your App                                         │
+│                                                                  │
+│  package.json:                                                   │
+│  "@famgia/omnify-react-sso": "link:/path/to/package"            │
+│                                                                  │
+│  omnify.config.ts:                                               │
+│  typescriptPlugin({                                              │
+│    exclude: ["Branch", "Role", "Permission", ...]  // SSO types │
+│  })                                                              │
+│                                                                  │
+│  Imports:                                                        │
+│  - SSO types → from "@famgia/omnify-react-sso"                  │
+│  - App types → from "@/omnify/schemas" (local generate)         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### After Changing SSO Schemas
+
+1. **Update Laravel package** (if schema YAML changed)
+2. **Rebuild this 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.
+
+---
 
 ## Architecture Note
 
@@ -35,7 +258,123 @@ Console (SSO Provider)                    Your React App (SSO Client)
 
 > **Note:** Your app only needs the `service_slug`. Console manages credentials per-organization through ServiceInstance.
 
-## Usage
+---
+
+## API Reference
+
+### Hooks
+
+```typescript
+import { useSso, useAuth, useOrganization } from '@famgia/omnify-react-sso';
+
+// Main hook - all SSO functionality
+const {
+  user,              // Current user
+  isAuthenticated,   // Auth status
+  isLoading,         // Loading state
+  organizations,     // User's organizations
+  currentOrg,        // Current organization
+  hasMultipleOrgs,   // Has more than one org?
+  login,             // Redirect to login
+  logout,            // Logout current session
+  globalLogout,      // Logout from all sessions
+  switchOrg,         // Switch organization
+  getHeaders,        // Get auth headers
+  config,            // SSO config
+} = useSso();
+
+// Auth-focused hook
+const { user, isAuthenticated, login, logout } = useAuth();
+
+// Organization-focused hook
+const { organizations, currentOrg, switchOrg, hasMultipleOrgs } = useOrganization();
+```
+
+### Components
+
+```tsx
+import {
+  SsoProvider,
+  SsoCallback,
+  OrganizationSwitcher,
+  ProtectedRoute,
+} from '@famgia/omnify-react-sso';
+
+// Provider - wrap your app
+<SsoProvider config={ssoConfig}>
+  <App />
+</SsoProvider>
+
+// Callback page - handle OAuth redirect
+<SsoCallback
+  onSuccess={(user) => router.push('/dashboard')}
+  onError={(error) => console.error(error)}
+/>
+
+// Organization switcher dropdown
+<OrganizationSwitcher />
+
+// Protected route wrapper
+<ProtectedRoute fallback={<Login />}>
+  <Dashboard />
+</ProtectedRoute>
+```
+
+### Services (Recommended)
+
+Use individual services for better tree-shaking and type safety:
+
+```typescript
+import {
+  createAuthService,
+  createRoleService,
+  createPermissionService,
+  createBranchService,
+  createUserRoleService,
+} from '@famgia/omnify-react-sso';
+
+const config = { apiUrl: 'https://api.example.com' };
+
+// Auth Service
+const authService = createAuthService(config);
+await authService.callback({ code: 'oauth-code' });
+await authService.getUser();
+await authService.logout();
+
+// Role Service
+const roleService = createRoleService(config);
+await roleService.list();
+await roleService.get(roleId);
+await roleService.create({ name: 'Editor', slug: 'editor' });
+await roleService.syncPermissions(roleId, { permissions: ['read', 'write'] });
+
+// Permission Service
+const permissionService = createPermissionService(config);
+await permissionService.list();
+await permissionService.getMatrix();
+
+// Branch Service
+const branchService = createBranchService(config);
+await branchService.list();
+await branchService.getPrimary();
+
+// User Role Service (Scoped Assignments)
+const userRoleService = createUserRoleService(config);
+await userRoleService.listForUser(userId);
+await userRoleService.assign({ user_id, role_id, scope: 'branch', branch_id });
+```
+
+### Legacy Service (Deprecated)
+
+```typescript
+// @deprecated - Use individual services instead
+import { createSsoService } from '@famgia/omnify-react-sso';
+
+const ssoService = createSsoService({ apiUrl: 'https://api.example.com' });
+await ssoService.getRoles();  // Use roleService.list() instead
+```
+
+### Schemas
 
 ```typescript
 import {
@@ -64,16 +403,24 @@ import {
 } from '@famgia/omnify-react-sso';
 ```
 
-## Schemas
+### Query Keys
+
+```typescript
+import { ssoQueryKeys } from '@famgia/omnify-react-sso';
 
-| Schema         | Description                             |
-| -------------- | --------------------------------------- |
-| User           | User account with authentication fields |
-| Role           | User roles for RBAC                     |
-| Permission     | Individual permissions                  |
-| RolePermission | Role-Permission mapping (pivot)         |
-| Team           | Team/Organization grouping              |
-| TeamPermission | Team-Permission mapping                 |
+// Use with TanStack Query
+useQuery({
+  queryKey: ssoQueryKeys.auth.user(),
+  queryFn: () => ssoService.getUser(),
+});
+
+useQuery({
+  queryKey: ssoQueryKeys.roles.list(),
+  queryFn: () => ssoService.getRoles(),
+});
+```
+
+---
 
 ## i18n Support
 
@@ -89,6 +436,65 @@ const label = getUserLabel('ja'); // 'ユーザー'
 const emailLabel = getUserFieldLabel('email', 'ja'); // 'メールアドレス'
 ```
 
+---
+
+## Testing
+
+### Run Tests
+
+```bash
+pnpm test           # Run once
+pnpm test:watch     # Watch mode
+pnpm typecheck      # Type check
+```
+
+### Test Utilities (for App Tests)
+
+The package provides official test mocks:
+
+```typescript
+import {
+  createMockUser,
+  createMockOrganization,
+  setMockSsoData,
+  resetMockSsoData,
+  mockUseSso,
+} from '@famgia/omnify-react-sso/testing';
+
+// Create mock data
+const user = createMockUser({ name: 'Custom User' });
+const org = createMockOrganization({ slug: 'my-org' });
+
+// Setup mock for tests
+beforeEach(() => {
+  setMockSsoData({
+    user,
+    organizations: [org],
+    currentOrg: org,
+    isAuthenticated: true,
+  });
+});
+
+afterEach(() => {
+  resetMockSsoData();
+});
+
+// Mock the hooks in vitest
+vi.mock('@famgia/omnify-react-sso', async () => {
+  const testing = await import('@famgia/omnify-react-sso/testing');
+  return {
+    useSso: testing.mockUseSso,
+    useAuth: testing.mockUseAuth,
+    useOrganization: testing.mockUseOrganization,
+    SsoProvider: ({ children }) => children,
+  };
+});
+```
+
+> **Note**: Subpath exports (`/testing`) require the package to be installed from npm, not linked locally.
+
+---
+
 ## License
 
 MIT