@docyrus/docyrus 0.0.19 → 0.0.21

package/resources/pi-agent/skills/docyrus-app-dev/SKILL.md

@@ -1,159 +0,0 @@
----
-name: docyrus-app-dev
-description: Build React TypeScript web applications using Docyrus as a backend. Use when creating or modifying apps that authenticate with Docyrus OAuth2, fetch/mutate data via the @docyrus/api-client library, use auto-generated collections for CRUD operations, or build queries with filters, aggregations, formulas, pivots, and child queries against Docyrus data sources. Triggers on tasks involving @docyrus/api-client, @docyrus/signin, Docyrus collections, data source queries, or Docyrus-backed React app development.
----
-
-# Docyrus App Developer
-
-Build React TypeScript web apps with Docyrus as the backend. Authenticate via OAuth2 PKCE, query data sources with powerful filtering/aggregation, and follow established patterns.
-
-## Tech Stack
-
-- React 19 + TypeScript + Vite
-- TanStack Router (code-based), TanStack Query (server state)
-- Tailwind CSS v4, shadcn/ui components
-- `@docyrus/api-client` (REST client) + `@docyrus/signin` (auth provider)
-- Auto-generated collections from OpenAPI spec
-
-## Quick Start: New App Setup
-
-1. Wrap root with `DocyrusAuthProvider`:
-
-```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"
->
-  <QueryClientProvider client={queryClient}>
-    <RouterProvider router={router} />
-  </QueryClientProvider>
-</DocyrusAuthProvider>
-```
-
-2. In App.tsx, check auth and use collection hooks:
-
-```tsx
-const { status } = useDocyrusAuth()
-const { getMyInfo } = useUsersCollection()
-
-if (status === 'loading') return <Spinner />
-if (status === 'unauthenticated') return <SignInButton />
-```
-
-3. Use collection hooks in components:
-
-```tsx
-const { list } = useBaseProjectCollection()
-
-const { data: projects } = useQuery({
-  queryKey: ['projects'],
-  queryFn: () => list({
-    columns: ['name', 'status', 'record_owner(firstname,lastname)'],
-    filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
-    orderBy: 'created_on DESC',
-    limit: 50,
-  }),
-})
-```
-
-## Critical Rules
-
-1. **Always send `columns`** in `.list()` and `.get()` calls. Without it, only `id` is returned.
-2. **Collections are React hooks** — call `useBaseProjectCollection()`, `useUsersCollection()`, etc. inside React components. They use `useDocyrusClient()` internally for authenticated API access.
-3. **Data source endpoints are dynamic** — they only exist if the data source is defined in the tenant's OpenAPI spec.
-4. **Use `id` field** for `count` calculations. Use the actual field slug for `sum`, `avg`, `min`, `max`.
-5. **Child query keys must appear in `columns`** — e.g., if childQuery key is `orders`, include `'orders'` in the columns array.
-6. **Formula keys must appear in `columns`** — e.g., if formula key is `total`, include `'total'` in the columns array.
-7. **Use `useUsersCollection().getMyInfo()`** for current user profile, not a direct API call.
-
-## Regenerating Collections After Schema Changes
-
-When data sources or fields are created, updated, or deleted via the `docyrus-architect` MCP tools, the app's auto-generated collections become stale. To resync:
-
-1. Call `regenerate_openapi_spec` (architect MCP) to rebuild and upload the tenant's OpenAPI spec
-2. Download the new spec into the repo, overwriting the existing file:
-   ```bash
-   curl -o openapi.json "<publicUrl returned from step 1>"
-   ```
-3. Regenerate collections:
-   ```bash
-   pnpx @docyrus/tanstack-db-generator openapi.json
-   ```
-
-Always run all three steps together — a stale `openapi.json` or outdated collections will cause missing or incorrect endpoints at runtime.
-
-## Collection CRUD Methods
-
-Every generated collection is a React hook that returns CRUD methods:
-
-```typescript
-const { list, get, create, update, delete: deleteOne, deleteMany } = useBaseProjectCollection()
-
-list(params?: ICollectionListParams)   // Query with filters, sort, pagination
-get(id, { columns })                    // Single record
-create(data)                            // Create
-update(id, data)                        // Partial update
-deleteOne(id)                           // Delete one
-deleteMany({ recordIds })               // Delete many
-```
-
-API endpoint pattern: `/v1/apps/{appSlug}/data-sources/{slug}/items`
-
-## Query Capabilities Summary
-
-The `.list()` method supports:
-
-| Feature | Purpose |
-|---------|---------|
-| `columns` | Select fields, expand relations `field(subfields)`, alias `alias:field`, spread `...field()` |
-| `filters` | Nested AND/OR groups with 50+ operators (comparison, date shortcuts, user-related) |
-| `filterKeyword` | Full-text search |
-| `orderBy` | Sort by fields with direction, including related fields |
-| `limit`/`offset` | Pagination (default 100) |
-| `fullCount` | Return total count alongside results |
-| `calculations` | Aggregations: count, sum, avg, min, max with grouping |
-| `formulas` | Computed virtual columns (simple functions, block AST, correlated subqueries) |
-| `childQueries` | Fetch related child records as nested JSON arrays |
-| `pivot` | Cross-tab matrix queries with date range series |
-| `expand` | Return full objects for relation/user/enum fields instead of IDs |
-
-**For query/formula details, read**:
-- `references/data-source-query-guide.md`
-- `references/formula-design-guide-llm.md`
-
-## TanStack Query Pattern
-
-```typescript
-// Query hook — call collection hook inside the component, pass methods to TanStack Query
-function useProjects(params?: ICollectionListParams) {
-  const { list } = useBaseProjectCollection()
-  return useQuery({
-    queryKey: ['projects', 'list', params],
-    queryFn: () => list({ columns: PROJECT_COLUMNS, ...params }),
-  })
-}
-
-// Mutation hook
-function useCreateProject() {
-  const { create } = useBaseProjectCollection()
-  const qc = useQueryClient()
-  return useMutation({
-    mutationFn: (data: Record<string, unknown>) => create(data),
-    onSuccess: () => { void qc.invalidateQueries({ queryKey: ['projects'] }) },
-  })
-}
-```
-
-## References
-
-Read these files when you need detailed information:
-
-- **`references/api-client-and-auth.md`** — RestApiClient API, @docyrus/signin hooks, auth provider config, interceptors, error handling, SSE/streaming, file upload/download
-- **`references/data-source-query-guide.md`** — Up-to-date query payload guide: columns, filters, orderBy, pagination, calculations, formulas, child queries, pivots, and operator reference
-- **`references/formula-design-guide-llm.md`** — Up-to-date formula design guide for building and validating `formulas` payloads
-- **`references/collections-and-patterns.md`** — Generated collection hooks, useUsersCollection, TanStack Query/mutation hook patterns, query key factories, app bootstrap flow, routing setup, API endpoints

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

@@ -1,275 +0,0 @@
-# @docyrus/api-client & @docyrus/signin Reference
-
-## Table of Contents
-
-1. [RestApiClient](#restapiclient)
-2. [Authentication with @docyrus/signin](#authentication-with-docyrussignin)
-3. [API Client Access Pattern](#api-client-access-pattern)
-4. [Interceptors](#interceptors)
-5. [Error Handling](#error-handling)
-6. [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
-  signIn,   // () => void — redirects to Docyrus login
-  signOut,  // () => void — logout and clear tokens
-  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
-```
-
----
-
-## 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,
-})
-```