@docyrus/docyrus 0.0.30 → 0.0.32

package/resources/pi-agent/skills/docyrus-app-dev-react/references/api-client-and-auth.md

@@ -0,0 +1,326 @@
+# @docyrus/api-client & @docyrus/signin Reference
+
+## Table of Contents
+
+1. [RestApiClient](#restapiclient)
+2. [Authentication with @docyrus/signin](#authentication-with-docyrussignin)
+3. [Authorization (Roles & Permissions)](#authorization-roles--permissions)
+4. [API Client Access Pattern](#api-client-access-pattern)
+5. [Interceptors](#interceptors)
+6. [Error Handling](#error-handling)
+7. [Advanced Features](#advanced-features)
+
+---
+
+## RestApiClient
+
+Type-safe REST API client from `@docyrus/api-client`.
+
+### HTTP Methods
+
+```typescript
+import { RestApiClient } from '@docyrus/api-client'
+
+client.get<T>(endpoint, params?)    // GET
+client.post<T>(endpoint, data)      // POST
+client.patch<T>(endpoint, data)     // PATCH
+client.put(endpoint, data)          // PUT
+client.delete(endpoint, data?)      // DELETE
+```
+
+### Typed Responses
+
+```typescript
+interface User { id: string; name: string; email: string }
+const response = await client.get<User[]>('/v1/users')
+```
+
+### Config Options
+
+```typescript
+interface ApiClientConfig {
+  baseURL?: string
+  tokenManager?: TokenManager
+  headers?: Record<string, string>
+  timeout?: number
+  fetch?: typeof fetch
+  FormData?: typeof FormData
+  AbortController?: typeof AbortController
+  storage?: Storage
+}
+```
+
+---
+
+## Authentication with @docyrus/signin
+
+Package: `@docyrus/signin` (peer dep: `@docyrus/api-client >= 0.0.10`, `react >= 18`)
+
+### DocyrusAuthProvider Setup
+
+Wrap application root:
+
+```tsx
+import { DocyrusAuthProvider } from '@docyrus/signin'
+
+<DocyrusAuthProvider
+  apiUrl={import.meta.env.VITE_API_BASE_URL}
+  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
+  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
+  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
+  callbackPath="/auth/callback"
+>
+  <App />
+</DocyrusAuthProvider>
+```
+
+### Provider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | `https://alpha-api.docyrus.com` | API base URL |
+| `clientId` | `string` | Built-in default | OAuth2 client ID |
+| `redirectUri` | `string` | `origin + callbackPath` | OAuth2 redirect URI |
+| `scopes` | `string[]` | `['offline_access', 'Read.All', ...]` | OAuth2 scopes |
+| `callbackPath` | `string` | `/auth/callback` | OAuth callback route |
+| `forceMode` | `'standalone' \| 'iframe'` | Auto-detected | Force auth mode |
+| `storageKeyPrefix` | `string` | `docyrus_oauth2_` | localStorage prefix |
+| `allowedHostOrigins` | `string[]` | `undefined` | Extra trusted iframe origins |
+
+### Auth Modes
+
+- **Standalone**: OAuth2 Authorization Code + PKCE via page redirect. Tokens stored in localStorage, auto-refreshed.
+- **Iframe**: Receives tokens via `window.postMessage` from `*.docyrus.app` hosts. Requests refresh from host when expired.
+
+### useDocyrusAuth() Hook
+
+```typescript
+const {
+  status,        // 'loading' | 'authenticated' | 'unauthenticated'
+  mode,          // 'standalone' | 'iframe'
+  client,        // RestApiClient | null
+  tokens,        // { accessToken, refreshToken, ... } | null
+  user,          // DocyrusUser | null — auto-fetched from /v1/users/me
+  signIn,        // () => void — redirects to Docyrus login
+  signOut,       // () => void — logout and clear tokens
+  hasRole,       // (role: string | string[]) => boolean — check role by slug or uid
+  hasPermission, // (operation: string, dataSourceId?: string) => boolean — check ACL permission
+  refreshUser,   // () => Promise<void> — re-fetch user from API
+  error,         // Error | null
+} = useDocyrusAuth()
+```
+
+### useDocyrusClient() Hook
+
+```typescript
+const client = useDocyrusClient() // RestApiClient | null
+```
+
+### SignInButton Component
+
+```tsx
+// Basic
+<SignInButton />
+
+// Styled
+<SignInButton className="btn" label="Log in with Docyrus" />
+
+// Render prop
+<SignInButton>
+  {({ signIn, isLoading }) => (
+    <button onClick={signIn} disabled={isLoading}>
+      {isLoading ? 'Redirecting...' : 'Sign in'}
+    </button>
+  )}
+</SignInButton>
+```
+
+### Environment Variables (.env)
+
+```bash
+VITE_API_BASE_URL=https://localhost:3366
+VITE_OAUTH2_CLIENT_ID=your-client-id
+VITE_OAUTH2_REDIRECT_URI=http://localhost:3000/auth/callback
+VITE_OAUTH2_SCOPES=openid profile offline_access Users.Read DS.ReadWrite.All
+```
+
+---
+
+## Authorization (Roles & Permissions)
+
+The provider auto-fetches the current user from `/v1/users/me` after authentication. The `user`, `hasRole`, and `hasPermission` are available on the `useDocyrusAuth()` hook.
+
+### Role-Based UI Gating
+
+```tsx
+function Dashboard({ dataSourceId }: { dataSourceId: string }) {
+  const { user, hasRole, hasPermission } = useDocyrusAuth()
+
+  if (!user) return <Spinner />
+
+  const canEdit = hasPermission('edit', dataSourceId)
+  const canDelete = hasPermission('delete', dataSourceId)
+  const isAdmin = hasRole('super_admin')
+
+  return (
+    <div>
+      {canEdit && <Button>Edit</Button>}
+      {canDelete && <Button variant="destructive">Delete</Button>}
+      {isAdmin && <AdminPanel />}
+    </div>
+  )
+}
+```
+
+### Permission Resolution Order
+
+1. `super_admin` role → always granted
+2. `global_editor` role → granted for: view, create, edit, delete, create_bulk, export, import, print
+3. `global_viewer` role → granted only for: view
+4. Always-permitted system data sources (reports, todos, notes, etc.)
+5. User's `aclRules` array (merged from all roles by the server)
+
+### Pure Functions (No React)
+
+```typescript
+import { hasRole, hasPermission } from '@docyrus/signin/core'
+import type { DocyrusUser } from '@docyrus/signin/core'
+
+hasRole(user, 'super_admin')
+hasPermission(user, 'edit', 'some-ds-id')
+```
+
+---
+
+## API Client Access Pattern
+
+Generated collections are React hooks that use `useDocyrusClient()` internally to get the authenticated `RestApiClient` from `DocyrusAuthProvider`. No manual client syncing is needed.
+
+```typescript
+// Collections get the client automatically via useDocyrusClient()
+function useBaseProjectCollection() {
+  const client = useDocyrusClient()
+  return {
+    list: (params?) => client!.get('/v1/apps/base/data-sources/project/items', params),
+    // ... other CRUD methods
+  }
+}
+
+// In your component — just call the collection hook
+function ProjectList() {
+  const { list } = useBaseProjectCollection()
+  const { data } = useQuery({
+    queryKey: ['projects'],
+    queryFn: () => list({ columns: ['name', 'status'] }),
+  })
+}
+```
+
+For direct API access outside collections, use the `useDocyrusClient()` hook:
+
+```typescript
+const client = useDocyrusClient()
+const data = await client!.get<MyType>('/v1/custom-endpoint')
+```
+
+---
+
+## Interceptors
+
+Add request/response interceptors via `client.use()`:
+
+```typescript
+client.use({
+  request: (config) => {
+    // Transform columns array to comma-separated string
+    if (config.params?.columns && Array.isArray(config.params.columns)) {
+      config.params.columns = config.params.columns.join(',')
+    }
+    return config
+  },
+  response: (response) => {
+    // Unwrap nested .data property
+    if (response.data?.data && !Array.isArray(response.data)) {
+      response.data = response.data.data
+    }
+    return response
+  },
+  error: (error, request, response) => {
+    if (error.status === 401) { /* handle auth error */ }
+    return { error, request, response }
+  },
+})
+```
+
+---
+
+## Error Handling
+
+```typescript
+import {
+  ApiError, NetworkError, TimeoutError,
+  AuthenticationError, AuthorizationError,
+  NotFoundError, RateLimitError, ValidationError,
+  OAuth2Error, InvalidGrantError,
+} from '@docyrus/api-client'
+
+try {
+  await client.get('/resource')
+} catch (error) {
+  if (error instanceof AuthenticationError) { /* 401 */ }
+  else if (error instanceof AuthorizationError) { /* 403 */ }
+  else if (error instanceof NotFoundError) { /* 404 */ }
+  else if (error instanceof RateLimitError) { /* 429 - error.retryAfter */ }
+  else if (error instanceof NetworkError) { /* network issue */ }
+  else if (error instanceof TimeoutError) { /* timeout */ }
+}
+```
+
+---
+
+## Advanced Features
+
+### SSE (Server-Sent Events)
+
+```typescript
+const eventSource = client.sse('/events', {
+  onMessage(data) { console.log(data) },
+  onError(error) { console.error(error) },
+  onComplete() { console.log('done') },
+})
+eventSource.close()
+```
+
+### File Upload
+
+```typescript
+const formData = new FormData()
+formData.append('file', fileInput.files[0])
+await client.post('/upload', formData)
+```
+
+### File Download
+
+```typescript
+const response = await client.get('/download/file.pdf', { responseType: 'blob' })
+const url = URL.createObjectURL(response.data)
+```
+
+### HTML to PDF
+
+```typescript
+await client.html2pdf({
+  html: '<html><body>Content</body></html>',
+  options: { format: 'A4', margin: { top: 10, bottom: 10 } },
+})
+```
+
+### Retry Logic
+
+```typescript
+import { withRetry } from '@docyrus/api-client'
+const response = await withRetry(() => client.get('/endpoint'), {
+  retries: 3, retryDelay: 1000,
+  retryCondition: (error) => error.status >= 500,
+})
+```

package/resources/pi-agent/skills/docyrus-app-dev-react/references/collections-and-patterns.md

@@ -0,0 +1,353 @@
+# Collections & App Patterns Reference
+
+## Table of Contents
+
+1. [Collection Architecture](#collection-architecture)
+2. [Generated Collection Structure](#generated-collection-structure)
+3. [Collection Types](#collection-types)
+4. [useUsersCollection](#useuserscollection)
+5. [TanStack Query Hooks Pattern](#tanstack-query-hooks-pattern)
+6. [Query Key Factory Pattern](#query-key-factory-pattern)
+7. [Mutation Pattern](#mutation-pattern)
+8. [App Bootstrap Flow](#app-bootstrap-flow)
+9. [Routing Setup](#routing-setup)
+10. [API Endpoints](#api-endpoints)
+
+---
+
+## Collection Architecture
+
+Collections are auto-generated from `openapi.json` using `@docyrus/tanstack-db-generator`. They provide type-safe CRUD operations for each data source.
+
+**Generate command**: `pnpm generate-orm` (runs `@docyrus/tanstack-db-generator openapi.json`)
+
+**Key files:**
+- `src/collections/<app>-<entity>.collection.ts` — generated React hooks with CRUD methods + entity types
+- `src/collections/types.ts` — shared query types (filters, calculations, formulas, etc.)
+- `src/collections/users.collection.ts` — special system users collection hook
+
+---
+
+## Generated Collection Structure
+
+Each collection exports an entity interface and a React hook that returns CRUD methods:
+
+```typescript
+// Generated collection for base/project
+import { useDocyrusClient } from '@docyrus/signin'
+import type { ICollectionListParams } from './types'
+
+export interface BaseProjectEntity {
+  id?: string
+  record_owner?: string
+  created_on?: string
+  created_by?: string
+  last_modified_on?: string
+  last_modified_by?: string
+  name: string
+  description?: Record<string, any>
+  status?: { id: string; name: string } | any
+  organization?: { id: string; name: string } | string
+}
+
+export function useBaseProjectCollection() {
+  const client = useDocyrusClient()
+
+  return {
+    list: (params?: ICollectionListParams): Promise<Array<BaseProjectEntity>> =>
+      client!.get('/v1/apps/base/data-sources/project/items', params as any),
+
+    get: (recordId: string, params?: { columns?: Array<string> }): Promise<BaseProjectEntity> =>
+      client!.get(`/v1/apps/base/data-sources/project/items/${recordId}`, params),
+
+    create: (data: Record<string, any>): Promise<BaseProjectEntity> =>
+      client!.post('/v1/apps/base/data-sources/project/items', data),
+
+    update: (recordId: string, data: Record<string, any>): Promise<BaseProjectEntity> =>
+      client!.patch(`/v1/apps/base/data-sources/project/items/${recordId}`, data),
+
+    delete: (recordId: string): Promise<void> =>
+      client!.delete(`/v1/apps/base/data-sources/project/items/${recordId}`),
+
+    deleteMany: (data: { recordIds: Array<string> }): Promise<void> =>
+      client!.delete('/v1/apps/base/data-sources/project/items', data),
+  }
+}
+```
+
+Collections are hooks because they use `useDocyrusClient()` internally, which provides the authenticated `RestApiClient` from `DocyrusAuthProvider`. This means collections must be called inside React components.
+
+### Default Fields (always present)
+Every data source entity includes: `id`, `record_owner`, `created_on`, `created_by`, `last_modified_on`, `last_modified_by`, `name`
+
+---
+
+## Collection Types
+
+Shared query parameter types in `src/collections/types.ts`:
+
+- `ICollectionListParams` — full query payload with columns, filters, calculations, formulas, childQueries, pivot, orderBy, limit, offset, fullCount, expand
+- `ICollectionFilterRule` — single filter rule
+- `ICollectionFilterGroup` — nested filter group
+- `ICollectionCalculation` — aggregation rule
+- `ICollectionFormula` — simple formula
+- `ICollectionBlockFormula` — block/subquery formula
+- `ICollectionChildQuery` — child query definition
+- `ICollectionPivot` / `ICollectionPivotMatrix` — pivot configuration
+- `ICollectionOrderBy` — sort specification
+
+---
+
+## useUsersCollection
+
+System users collection hook with special methods:
+
+```typescript
+export function useUsersCollection() {
+  const client = useDocyrusClient()
+
+  return {
+    getUsers: (): Promise<Array<UserEntity>> =>
+      client!.get('/v1/users'),
+
+    getMyInfo: (): Promise<UserEntity> =>
+      client!.get('/v1/users/me'),
+
+    createUser: (data: UserCreateParams): Promise<UserEntity> =>
+      client!.post('/v1/users', data),
+
+    updateMe: (data: UserUpdateParams): Promise<UserEntity> =>
+      client!.patch('/v1/users/me', data),
+
+    updateUser: (userId: string, data: UserUpdateParams): Promise<UserEntity> =>
+      client!.patch(`/v1/users/${userId}`, data),
+
+    changeUserStatus: (userId: string, status: number) =>
+      client!.put(`/v1/users/${userId}/status/${status}`),
+
+    saveUserDevice: (data: UserDeviceDto) =>
+      client!.post('/v1/users/device', data),
+
+    getMyTenants: () =>
+      client!.get('/v1/users/me/tenants'),
+  }
+}
+```
+
+Use `useUsersCollection().getMyInfo()` for current user profile.
+
+---
+
+## TanStack Query Hooks Pattern
+
+Wrap collection hook methods in TanStack Query hooks. Since collections are themselves hooks, call them inside the component/hook, then pass the returned methods to TanStack Query:
+
+```typescript
+import { useQuery } from '@tanstack/react-query'
+import { useBaseProjectCollection } from '@/collections/base-project.collection'
+import { queryKeys } from '@/lib/query-keys'
+
+const PROJECT_COLUMNS = ['name', 'status', 'description', 'record_owner(id,firstname,lastname)']
+
+export function useProjects(params?: ICollectionListParams) {
+  const { list } = useBaseProjectCollection()
+  return useQuery({
+    queryKey: queryKeys.projects.list(params ?? {}),
+    queryFn: () =>
+      list({
+        columns: PROJECT_COLUMNS,  // ALWAYS specify columns
+        ...params,
+      }),
+  })
+}
+
+export function useProject(projectId: string) {
+  const { get } = useBaseProjectCollection()
+  return useQuery({
+    queryKey: queryKeys.projects.detail(projectId),
+    queryFn: () =>
+      get(projectId, {
+        columns: PROJECT_COLUMNS,
+      }),
+    enabled: !!projectId,
+  })
+}
+```
+
+---
+
+## Query Key Factory Pattern
+
+```typescript
+export const queryKeys = {
+  projects: {
+    all: ['projects'] as const,
+    lists: () => [...queryKeys.projects.all, 'list'] as const,
+    list: (params: object) => [...queryKeys.projects.lists(), params] as const,
+    detail: (id: string) => [...queryKeys.projects.all, 'detail', id] as const,
+  },
+  tasks: {
+    all: ['tasks'] as const,
+    lists: () => [...queryKeys.tasks.all, 'list'] as const,
+    list: (params: object) => [...queryKeys.tasks.lists(), params] as const,
+    detail: (id: string) => [...queryKeys.tasks.all, 'detail', id] as const,
+  },
+}
+```
+
+---
+
+## Mutation Pattern
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { useBaseProjectCollection } from '@/collections/base-project.collection'
+
+export function useCreateProject() {
+  const { create } = useBaseProjectCollection()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (data: Record<string, unknown>) => create(data),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({
+        queryKey: queryKeys.projects.all,
+      })
+    },
+  })
+}
+
+export function useUpdateProject() {
+  const { update } = useBaseProjectCollection()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: Record<string, unknown> }) =>
+      update(id, data),
+    onSuccess: (_data, { id }) => {
+      void queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(id) })
+      void queryClient.invalidateQueries({ queryKey: queryKeys.projects.lists() })
+    },
+  })
+}
+
+export function useDeleteProject() {
+  const { delete: deleteProject } = useBaseProjectCollection()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: (id: string) => deleteProject(id),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: queryKeys.projects.all })
+    },
+  })
+}
+```
+
+---
+
+## App Bootstrap Flow
+
+1. `main.tsx`: Mount `DocyrusAuthProvider` → `QueryClientProvider` → `RouterProvider`
+2. `App.tsx`: Check `useDocyrusAuth()` status — `user` is auto-fetched from `/v1/users/me`
+3. Use `hasRole()` / `hasPermission()` from `useDocyrusAuth()` for authorization checks
+4. Use collection hooks (e.g., `useUsersCollection()`) for data access — they get the authenticated client via `useDocyrusClient()` internally
+5. Render protected routes
+
+```typescript
+// App.tsx
+function App() {
+  const { status, user, hasRole, hasPermission } = useDocyrusAuth()
+
+  if (status === 'loading') return <LoadingSpinner />
+  if (status === 'unauthenticated') return <LoginPage />
+
+  // user auto-fetched, hasRole/hasPermission ready
+  return <AppLayout />
+}
+```
+
+---
+
+## Routing Setup
+
+TanStack Router with code-based routes:
+
+```typescript
+import { createRouter, createRoute, createRootRoute } from '@tanstack/react-router'
+
+const rootRoute = createRootRoute({ component: () => <Outlet /> })
+
+const layoutRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  id: 'layout',
+  component: AppLayout,
+})
+
+const indexRoute = createRoute({
+  getParentRoute: () => layoutRoute,
+  path: '/',
+  component: DashboardPage,
+})
+
+const projectsRoute = createRoute({
+  getParentRoute: () => layoutRoute,
+  path: '/projects',
+  component: ProjectsPage,
+})
+
+const projectDetailRoute = createRoute({
+  getParentRoute: () => layoutRoute,
+  path: '/projects/$projectId',
+  component: ProjectDetailPage,
+})
+
+// Auth routes (public)
+const authCallbackRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/auth/callback',
+  component: () => <div>Processing login...</div>,
+})
+
+const routeTree = rootRoute.addChildren([
+  layoutRoute.addChildren([indexRoute, projectsRoute, projectDetailRoute]),
+  authCallbackRoute,
+])
+
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',
+  scrollRestoration: true,
+})
+```
+
+---
+
+## API Endpoints
+
+### Data Source Items (Dynamic)
+```
+GET    /v1/apps/{appSlug}/data-sources/{slug}/items          — List (with query payload)
+GET    /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Get one
+POST   /v1/apps/{appSlug}/data-sources/{slug}/items          — Create
+PATCH  /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Update
+DELETE /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Delete one
+DELETE /v1/apps/{appSlug}/data-sources/{slug}/items          — Delete many
+```
+
+Endpoints are **dynamic** — they exist only if a data source is defined in the tenant. The `openapi.json` spec enumerates all available data sources.
+
+### System Endpoints (Always Available)
+```
+GET    /v1/users                    — List users
+POST   /v1/users                    — Create user
+GET    /v1/users/me                 — Current user profile
+PATCH  /v1/users/me                 — Update current user
+PATCH  /v1/users/{userId}           — Update user
+PUT    /v1/users/{userId}/status/{s} — Change user status
+POST   /v1/users/device             — Save push notification device
+```
+
+### Other Standard Endpoints
+```
+GET  /v1/api/openapi.json           — Generate OpenAPI spec
+HEAD /v1/oauth2                     — Check rate limits
+PUT  reports/runCustomQuery/{id}    — Run custom query/report
+```