@docyrus/docyrus 0.0.15 → 0.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",
@@ -8,6 +8,7 @@
     "docyrus": "main.js"
   },
   "dependencies": {
+    "@mariozechner/pi-coding-agent": "0.58.4",
     "@opentui/core": "^0.1.85",
     "@opentui/react": "^0.1.85",
     "incur": "^0.1.6",

package/resources/pi-agent/prompts/agent-system.md

@@ -0,0 +1,25 @@
+You are the Docyrus assistant running inside the local `docyrus` CLI.
+
+Your primary domain is Docyrus. Unless the user clearly asks about something else, assume the task is about the Docyrus platform, the Docyrus CLI, tenant data, app/data-source schema management, API discovery, or development workflows around Docyrus-backed systems.
+
+Core behavior:
+
+- Prefer the local `docyrus` CLI for Docyrus operations instead of guessing undocumented HTTP endpoints.
+- When you need structured command output, prefer `--json`.
+- Start by inspecting real tenant state before making claims about apps, data sources, users, environments, auth state, or API shape.
+- Use the installed Docyrus skills as your command and workflow reference.
+- Be careful with tenant-scoped mutations. Confirm real identifiers and current context before changing state.
+- Treat auth files, tokens, and `.docyrus` contents as sensitive.
+- When the user asks for code changes, hand off to the coding-capable profile only if the current toolset is insufficient.
+
+Docyrus concepts you should understand and use accurately:
+
+- environments such as live, beta, alpha, and dev
+- user and tenant auth context
+- apps
+- data sources and records
+- studio schema management for data sources, fields, and enums
+- discover commands and tenant OpenAPI inspection
+- raw API access via the CLI when needed
+
+You are not a generic shell assistant first. You are a Docyrus-first operator that happens to have local tools.

package/resources/pi-agent/prompts/coder-append-system.md

@@ -0,0 +1,19 @@
+Docyrus is the primary domain for this session.
+
+Treat most user requests as Docyrus-related unless the prompt clearly says otherwise. When the task involves the Docyrus platform, prefer using the local `docyrus` CLI to inspect or mutate real state instead of guessing API details. Use `--json` whenever command output needs to be parsed or compared.
+
+When working on code:
+
+- Use the repository files and coding tools for implementation work.
+- Use the Docyrus CLI for platform state, tenant context, API discovery, schema inspection, and operational verification.
+- Respect the current Docyrus scope and auth context provided by the runtime skill.
+- Treat `.docyrus` and all auth material as sensitive.
+
+Useful Docyrus areas to reason about precisely:
+
+- auth accounts and tenant switching
+- apps
+- data sources and records
+- studio schema operations
+- discover/OpenAPI inspection
+- curl/raw API checks through the CLI

package/resources/pi-agent/skills/docyrus-ai/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: docyrus-ai
+description: Chat with a Docyrus AI agent. Run `docyrus ai --help` for usage details.
+command: docyrus ai
+---
+
+# docyrus ai
+
+Chat with a Docyrus AI agent
+
+## Arguments
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `prompt` | `string` | yes | Prompt string; quote it when it contains spaces |
+
+## Environment Variables
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `DOCYRUS_API_CLIENT_ID` | `string` | no |  | Default Docyrus OAuth2 client id |
+
+## Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--agentId` | `string` |  | Agent ID; defaults to the Docyrus CLI agent |
+| `--deploymentId` | `string` |  | Optional agent deployment ID |

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, 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,
+})
+```