@docyrus/docyrus 0.0.30 → 0.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",
@@ -10,8 +10,8 @@
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "@hono/node-server": "^1.14.1",
-    "@mariozechner/pi-ai": "0.63.1",
-    "@mariozechner/pi-coding-agent": "0.63.1",
+    "@mariozechner/pi-ai": "0.63.2",
+    "@mariozechner/pi-coding-agent": "0.63.2",
     "@modelcontextprotocol/ext-apps": "^1.2.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@mozilla/readability": "^0.6.0",

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

@@ -0,0 +1,161 @@
+---
+name: docyrus-api-dev
+description: Develop applications using the Docyrus API with @docyrus/api-client and @docyrus/signin libraries. Use when building apps that authenticate with Docyrus OAuth2 (PKCE, iframe, client credentials, device code), make REST API calls to Docyrus data source endpoints, or construct query payloads with filters, aggregations, formulas, pivots, and child queries. Triggers on tasks involving Docyrus API integration, @docyrus/api-client usage, @docyrus/signin authentication, data source query building, or Docyrus REST endpoint consumption.
+---
+
+# Docyrus API Developer
+
+Integrate with the Docyrus API using `@docyrus/api-client` (REST client) and `@docyrus/signin` (React auth provider). Authenticate via OAuth2 PKCE, query data sources with powerful filtering/aggregation, and consume REST endpoints.
+
+## Authentication Quick Start
+
+### React Apps — Use @docyrus/signin
+
+```tsx
+import { DocyrusAuthProvider, useDocyrusAuth, useDocyrusClient, SignInButton } from '@docyrus/signin'
+
+// 1. Wrap root
+<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>
+
+// 2. Use hooks
+function App() {
+  const { status, signOut } = useDocyrusAuth()
+  const client = useDocyrusClient()  // RestApiClient | null
+
+  if (status === 'loading') return <Spinner />
+  if (status === 'unauthenticated') return <SignInButton />
+
+  // client is ready — make API calls
+  const user = await client!.get('/v1/users/me')
+}
+```
+
+### Non-React / Server — Use OAuth2Client Directly
+
+```typescript
+import { RestApiClient, OAuth2Client, OAuth2TokenManagerAdapter, BrowserOAuth2TokenStorage } from '@docyrus/api-client'
+
+const tokenStorage = new BrowserOAuth2TokenStorage(localStorage)
+const oauth2 = new OAuth2Client({
+  baseURL: 'https://api.docyrus.com',
+  clientId: 'your-client-id',
+  redirectUri: 'http://localhost:3000/callback',
+  usePKCE: true,
+  tokenStorage,
+})
+
+// Auth Code flow
+const { url } = await oauth2.getAuthorizationUrl({ scope: 'openid offline_access Users.Read' })
+window.location.href = url
+// After redirect:
+const tokens = await oauth2.handleCallback(window.location.href)
+
+// Create API client with auto-refresh
+const client = new RestApiClient({
+  baseURL: 'https://api.docyrus.com',
+  tokenManager: new OAuth2TokenManagerAdapter(tokenStorage, async () => {
+    return (await oauth2.refreshAccessToken()).accessToken
+  }),
+})
+```
+
+## API Endpoints
+
+### Data Source Items (Dynamic per tenant)
+```
+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 (body: { recordIds })
+```
+
+Endpoints exist only if the data source is defined in the tenant. Check the tenant's OpenAPI spec at `GET /v1/api/openapi.json`.
+
+### 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
+```
+
+### Making API Calls
+
+```typescript
+// List items with query payload
+const items = await client.get('/v1/apps/base/data-sources/project/items', {
+  columns: 'name, status, record_owner(firstname,lastname)',
+  filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
+  orderBy: 'created_on DESC',
+  limit: 50,
+})
+
+// Get single item
+const item = await client.get('/v1/apps/base/data-sources/project/items/uuid-here', {
+  columns: 'name, description, status',
+})
+
+// Create
+const newItem = await client.post('/v1/apps/base/data-sources/project/items', {
+  name: 'New Project',
+  status: 'status-enum-id',
+})
+
+// Update
+await client.patch('/v1/apps/base/data-sources/project/items/uuid-here', {
+  name: 'Updated Name',
+})
+
+// Delete
+await client.delete('/v1/apps/base/data-sources/project/items/uuid-here')
+```
+
+## Query Payload Summary
+
+The GET items endpoint accepts a powerful query payload:
+
+| 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 across all searchable fields |
+| `orderBy` | Sort by fields with direction, including related fields |
+| `limit`/`offset` | Pagination (default limit: 100) |
+| `fullCount` | Return total matching 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 full query and formula references, read**:
+- `references/data-source-query-guide.md`
+- `references/formula-design-guide-llm.md`
+
+## Critical Rules
+
+1. **Always send `columns`** in list/get calls. Without it, only `id` is returned.
+2. **Data source endpoints are dynamic** — they exist only for data sources defined in the tenant.
+3. **Use `id` field** for `count` calculations. Use the actual field slug for `sum`, `avg`, `min`, `max`.
+4. **Child query keys must appear in `columns`** — if childQuery key is `orders`, include `orders` in columns.
+5. **Formula keys must appear in `columns`** — if formula key is `total`, include `total` in columns.
+6. **Filter by related field** using `rel_{{relation_field}}/{{field}}` syntax.
+
+## References
+
+Read these files when you need detailed information:
+
+- **`references/api-client.md`** — Full RestApiClient API, OAuth2Client (all flows: PKCE, client credentials, device code), token managers, interceptors, error classes, SSE/streaming, file upload/download, HTML to PDF, retry logic
+- **`references/authentication.md`** — @docyrus/signin React provider, useDocyrusAuth/useDocyrusClient hooks, hasRole/hasPermission authorization helpers, SignInButton, standalone vs iframe auth modes, env vars, API client access pattern
+- **`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

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

@@ -0,0 +1,349 @@
+# @docyrus/api-client Reference
+
+## Table of Contents
+
+1. [RestApiClient](#restapiclient)
+2. [HTTP Methods](#http-methods)
+3. [Configuration](#configuration)
+4. [Token Management](#token-management)
+5. [OAuth2Client](#oauth2client)
+6. [Interceptors](#interceptors)
+7. [Error Handling](#error-handling)
+8. [Streaming](#streaming)
+9. [File Operations](#file-operations)
+10. [Utilities](#utilities)
+
+---
+
+## RestApiClient
+
+```typescript
+import { RestApiClient, MemoryTokenManager } from '@docyrus/api-client'
+
+const client = new RestApiClient({
+  baseURL: 'https://api.docyrus.com',
+  tokenManager: new MemoryTokenManager(),
+  timeout: 5000,
+  headers: { 'X-API-Version': '1.0' },
+})
+```
+
+---
+
+## HTTP Methods
+
+```typescript
+// GET with query params
+const users = await client.get<User[]>('/v1/users', { params: { page: 1, limit: 10 } })
+
+// POST with body
+const newUser = await client.post<User>('/v1/users', { name: 'John', email: 'john@example.com' })
+
+// PATCH (partial update)
+const updated = await client.patch<User>('/v1/users/123', { name: 'Jane' })
+
+// PUT (full replace)
+await client.put('/v1/users/123', { name: 'Jane', email: 'jane@example.com' })
+
+// DELETE
+await client.delete('/v1/users/123')
+
+// DELETE with body
+await client.delete('/v1/items', { recordIds: ['id1', 'id2'] })
+```
+
+### Typed Responses
+
+```typescript
+interface ApiResponse<T> { data: T; meta: { page: number; total: number } }
+const response = await client.get<ApiResponse<User[]>>('/v1/users')
+const users: User[] = response.data.data
+```
+
+---
+
+## Configuration
+
+```typescript
+interface ApiClientConfig {
+  baseURL?: string                      // Base URL for all requests
+  tokenManager?: TokenManager           // Token manager instance
+  headers?: Record<string, string>      // Default headers
+  timeout?: number                      // Request timeout in ms
+  fetch?: typeof fetch                  // Custom fetch implementation
+  FormData?: typeof FormData            // Custom FormData
+  AbortController?: typeof AbortController
+  storage?: Storage                     // Browser storage for persistence
+}
+```
+
+---
+
+## Token Management
+
+### MemoryTokenManager (default)
+```typescript
+import { MemoryTokenManager } from '@docyrus/api-client'
+const tokenManager = new MemoryTokenManager()
+```
+
+### StorageTokenManager (persistent)
+```typescript
+import { StorageTokenManager } from '@docyrus/api-client'
+const tokenManager = new StorageTokenManager(localStorage, 'auth_token')
+```
+
+### AsyncTokenManager (custom)
+```typescript
+import { AsyncTokenManager } from '@docyrus/api-client'
+const tokenManager = new AsyncTokenManager({
+  async getToken() { return await secureStorage.get('token') },
+  async setToken(token) { await secureStorage.set('token', token) },
+  async clearToken() { await secureStorage.remove('token') },
+})
+```
+
+### Set Token Directly
+```typescript
+await client.setAccessToken('your-auth-token')
+```
+
+---
+
+## OAuth2Client
+
+Full OAuth2 support with PKCE, Device Code, and Client Credentials flows.
+
+### Setup
+```typescript
+import { OAuth2Client, BrowserOAuth2TokenStorage } from '@docyrus/api-client'
+
+const oauth2 = new OAuth2Client({
+  baseURL: 'https://api.docyrus.com',
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',    // optional for public clients
+  redirectUri: 'http://localhost:3000/callback',
+  defaultScopes: ['openid', 'offline_access'],
+  usePKCE: true,                          // default: true
+  tokenStorage: new BrowserOAuth2TokenStorage(localStorage),
+})
+```
+
+### Authorization Code Flow (PKCE)
+```typescript
+// Step 1: Generate auth URL
+const { url, state, codeVerifier } = await oauth2.getAuthorizationUrl({
+  scope: 'openid offline_access Users.Read',
+})
+
+// Step 2: Redirect user
+window.location.href = url
+
+// Step 3: Handle callback
+const tokens = await oauth2.handleCallback(window.location.href)
+// tokens: { accessToken, refreshToken, ... }
+```
+
+### Client Credentials Flow (server-to-server)
+```typescript
+const tokens = await oauth2.getClientCredentialsToken({
+  scope: 'Read.All',
+  delegatedUserId: 'user-id-to-impersonate',
+})
+```
+
+### Device Code Flow (CLI/headless)
+```typescript
+const deviceAuth = await oauth2.startDeviceAuthorization('openid offline_access')
+console.log(`Go to: ${deviceAuth.verification_uri}`)
+console.log(`Enter code: ${deviceAuth.user_code}`)
+
+const tokens = await oauth2.pollDeviceAuthorization(
+  deviceAuth.device_code, deviceAuth.interval, deviceAuth.expires_in,
+  { onExpired: () => console.log('Code expired'), signal: abortController.signal },
+)
+```
+
+### Token Operations
+```typescript
+const tokens = await oauth2.getTokens()
+const isExpired = await oauth2.isTokenExpired()
+const accessToken = await oauth2.getValidAccessToken()  // auto-refreshes
+const newTokens = await oauth2.refreshAccessToken()
+await oauth2.revokeToken(tokens.refreshToken)
+const tokenInfo = await oauth2.introspectToken(tokens.accessToken)
+await oauth2.logout()
+```
+
+### Integrate OAuth2 with RestApiClient
+```typescript
+import { RestApiClient, OAuth2Client, OAuth2TokenManagerAdapter, BrowserOAuth2TokenStorage } from '@docyrus/api-client'
+
+const tokenStorage = new BrowserOAuth2TokenStorage(localStorage)
+const oauth2 = new OAuth2Client({ baseURL: 'https://api.docyrus.com', clientId: 'id', tokenStorage })
+
+const tokenManager = new OAuth2TokenManagerAdapter(tokenStorage, async () => {
+  const tokens = await oauth2.refreshAccessToken()
+  return tokens.accessToken
+})
+
+const apiClient = new RestApiClient({ baseURL: 'https://api.docyrus.com', tokenManager })
+```
+
+### Rate Limit Check
+```typescript
+const rateLimit = await oauth2.checkRateLimit()
+// { remaining, limit, reset }
+```
+
+### PKCE Utilities
+```typescript
+import { generatePKCEChallenge, generateCodeVerifier, generateCodeChallenge, generateState, generateNonce } from '@docyrus/api-client'
+
+const pkce = await generatePKCEChallenge()
+// { codeVerifier, codeChallenge, codeChallengeMethod: 'S256' }
+```
+
+---
+
+## Interceptors
+
+```typescript
+client.use({
+  // Transform outgoing requests
+  async request(config) {
+    config.headers = { ...config.headers, 'X-Request-Time': new Date().toISOString() }
+    return config
+  },
+  // Transform incoming responses
+  async response(response, request) {
+    console.log(`${request.url} took ${Date.now() - request.timestamp}ms`)
+    return response
+  },
+  // Handle errors globally
+  async error(error, request, response) {
+    if (error.status === 401) { await refreshToken() }
+    return { error, request, response }
+  },
+})
+```
+
+### Common Interceptor: Unwrap Response Data
+```typescript
+client.use({
+  response: (response) => {
+    if (response.data?.data && typeof response.data === 'object' && !Array.isArray(response.data)) {
+      response.data = response.data.data
+    }
+    return response
+  },
+})
+```
+
+---
+
+## Error Handling
+
+```typescript
+import {
+  ApiError, NetworkError, TimeoutError,
+  AuthenticationError,   // 401
+  AuthorizationError,    // 403
+  NotFoundError,         // 404
+  RateLimitError,        // 429 — has error.retryAfter
+  ValidationError,
+  // OAuth2-specific
+  OAuth2Error, InvalidGrantError, InvalidClientError,
+  AccessDeniedError, ExpiredTokenError, AuthorizationPendingError,
+} from '@docyrus/api-client'
+
+try {
+  await client.get('/resource')
+} catch (error) {
+  if (error instanceof AuthenticationError) { /* re-login */ }
+  else if (error instanceof AuthorizationError) { /* forbidden */ }
+  else if (error instanceof NotFoundError) { /* 404 */ }
+  else if (error instanceof RateLimitError) { /* retry after error.retryAfter */ }
+  else if (error instanceof NetworkError) { /* offline */ }
+  else if (error instanceof TimeoutError) { /* timed out */ }
+}
+```
+
+---
+
+## Streaming
+
+### Server-Sent Events (SSE)
+```typescript
+const eventSource = client.sse('/events', {
+  onMessage(data) { console.log('Received:', data) },
+  onError(error) { console.error(error) },
+  onComplete() { console.log('Stream completed') },
+})
+eventSource.close()
+```
+
+### Chunked Streaming
+```typescript
+for await (const chunk of client.stream('/stream', {
+  method: 'POST',
+  body: { query: 'stream data' },
+})) {
+  console.log('Chunk:', chunk)
+}
+```
+
+---
+
+## File Operations
+
+### Upload
+```typescript
+const formData = new FormData()
+formData.append('file', fileInput.files[0])
+formData.append('description', 'My file')
+await client.post('/upload', formData)
+```
+
+### Download
+```typescript
+const response = await client.get('/download/file.pdf', { responseType: 'blob' })
+const url = URL.createObjectURL(response.data)
+const link = document.createElement('a')
+link.href = url
+link.download = 'file.pdf'
+link.click()
+```
+
+### HTML to PDF
+```typescript
+await client.html2pdf({
+  html: '<html><body>Content</body></html>',
+  // or: url: 'https://example.com',
+  options: { format: 'A4', margin: { top: 10, bottom: 10, left: 10, right: 10 }, landscape: false },
+})
+```
+
+### Custom Query/Report
+```typescript
+const results = await client.runCustomQuery(customQueryId, options)
+// PUT reports/runCustomQuery/:customQueryId
+```
+
+---
+
+## Utilities
+
+```typescript
+import { buildUrl, isAbortError, parseContentDisposition, createAbortSignal, jsonToQueryString, withRetry } from '@docyrus/api-client'
+
+const url = buildUrl('/api/users', { page: 1, limit: 10 })
+// '/api/users?page=1&limit=10'
+
+const signal = createAbortSignal(5000) // 5s timeout
+
+const response = await withRetry(() => client.get('/flaky'), {
+  retries: 3, retryDelay: 1000,
+  retryCondition: (error) => error.status >= 500,
+})
+```