@docyrus/docyrus 0.0.30 → 0.0.32

package/resources/pi-agent/skills/docyrus-api-dev/references/acl-endpoints-frontend.md

@@ -0,0 +1,295 @@
+# ACL Endpoints for Frontend Developers
+
+Base path: `/api/v1/users/acl`
+
+All ACL endpoints require the normal authenticated API session.
+
+These endpoints may be hidden from generated Swagger/OpenAPI output because the backend currently marks them with `@ApiExcludeEndpoint()`. Treat this document as the frontend integration source of truth and call these routes directly with `RestApiClient` or `useDocyrusClient()`.
+
+## Important identifier rules
+
+- Role assignments and ACL role relations are stored using `tenant_role.uid`.
+- Returned nested role objects expose both `id` and `uid`, and both values map to the role UID.
+- For role operations, backend can resolve incoming `roleId` values against both `tenant_role.uid` and `tenant_role.id`, but frontend apps should prefer role `uid` values from API responses.
+- For user-role writes and role-query `roleIds`, send role UUIDs and prefer UID values.
+- `tenant_role_query.query` is a JSON object matching the app's filter-query structure. Send raw JSON, not stringified JSON.
+
+## Enum values
+
+### Role ownership
+
+- `APP`
+- `CUSTOM`
+- `PRODUCT`
+- `SYSTEM`
+- `USER`
+
+### Role query restriction level
+
+- `hidden`
+- `read-only`
+- `not-deletable`
+
+## Endpoint groups
+
+### 1) Record ACL endpoints
+
+These manage record-level shares, not role CRUD.
+
+| Method | Path | Purpose |
+| :----- | :--- | :------ |
+| `GET` | `/v1/users/acl?dataSourceId={uuid}&recordId={uuid}` | Fetch direct and effective ACL rows for a record |
+| `POST` | `/v1/users/acl/share` | Upsert record share rows |
+| `DELETE` | `/v1/users/acl/share` | Revoke matching share rows |
+| `PUT` | `/v1/users/acl/owner` | Transfer record ownership |
+
+#### Share payload notes
+
+- `principalType` must be one of: `user`, `team`, `role`, `tenant`, `public`.
+- `permissions` is the backend ACL bitmask value.
+- `expiresAt` is optional and must be a valid ISO date if provided.
+
+#### Record ACL response shapes
+
+`GET /v1/users/acl` returns:
+
+```json
+{
+  "direct": [
+    {
+      "id": "uuid",
+      "principal_type": "user",
+      "principal_id": "uuid",
+      "permissions": 7,
+      "expires_at": null,
+      "created_by": "uuid-or-null",
+      "created_on": "2026-03-29T20:10:00.000Z"
+    }
+  ],
+  "effective": [
+    {
+      "id": "uuid",
+      "user_id": "uuid",
+      "permissions": 7,
+      "source_principal_type": "role",
+      "source_principal_id": "uuid"
+    }
+  ]
+}
+```
+
+### 2) Role endpoints
+
+| Method | Path | Purpose |
+| :----- | :--- | :------ |
+| `GET` | `/v1/users/acl/roles` | List tenant roles |
+| `GET` | `/v1/users/acl/roles/:roleId` | Get one role |
+| `POST` | `/v1/users/acl/roles` | Create role |
+| `PATCH` | `/v1/users/acl/roles/:roleId` | Partial update role |
+| `DELETE` | `/v1/users/acl/roles/:roleId` | Hard delete role |
+
+#### Role create/update rules
+
+- `slug` is required on create and must be unique within the tenant.
+- Create defaults:
+  - `ownership = "CUSTOM"`
+  - `privileges = ""`
+  - `status = 1`
+- Role responses include both `id` and `uid`, both pointing to the role UID.
+
+#### Role delete side effects
+
+Deleting a role also cleans up dependent ACL state:
+
+- removes `tenant_user_role` assignments for that role
+- sets `tenant_user.primary_role` to `null` where applicable
+- removes linked `tenant_acl_rule` rows
+- removes linked `tenant_acl_field_rule` rows
+- removes the role from `tenant_role_query` role arrays
+- hard deletes role-query rows that become empty after role removal
+
+Frontend implication: after role deletion, refresh role lists, user-role lists, role-query lists, and any UI showing primary-role labels.
+
+### 3) User-role endpoints
+
+| Method | Path | Purpose |
+| :----- | :--- | :------ |
+| `GET` | `/v1/users/acl/user-roles` | List assignments across the tenant |
+| `GET` | `/v1/users/acl/users/:userId/roles` | List assignments for one user |
+| `POST` | `/v1/users/acl/users/:userId/roles` | Add roles to a user |
+| `PUT` | `/v1/users/acl/users/:userId/roles` | Replace the full role set for a user |
+| `DELETE` | `/v1/users/acl/users/:userId/roles/:roleId` | Remove one role assignment |
+
+#### User-role behavior
+
+- `GET /v1/users/acl/user-roles` accepts optional `userId` and `roleId` filters.
+- If `roleId` is supplied, backend resolves it to the canonical role UID first.
+- `POST /users/:userId/roles` is additive.
+- `POST /users/:userId/roles` safely ignores duplicate assignments.
+- `PUT /users/:userId/roles` is a full replacement operation.
+- Sending `roleIds: []` to `PUT /users/:userId/roles` clears all additional roles for that user.
+
+### 4) Role-query endpoints
+
+Role queries are role-based filtering rules attached to roles and optionally scoped to a specific data source.
+
+| Method | Path | Purpose |
+| :----- | :--- | :------ |
+| `GET` | `/v1/users/acl/role-queries` | List role queries |
+| `GET` | `/v1/users/acl/role-queries/:roleQueryId` | Get one role query |
+| `POST` | `/v1/users/acl/role-queries` | Create role query |
+| `PATCH` | `/v1/users/acl/role-queries/:roleQueryId` | Partial update role query |
+| `DELETE` | `/v1/users/acl/role-queries/:roleQueryId` | Hard delete role query |
+
+#### Role-query rules
+
+- `roleIds` is required on create and must contain at least one UUID.
+- Stored role IDs are normalized to role UIDs.
+- `query` is required on create and must be a JSON object.
+- `filterChildRelations` defaults to `false`.
+- `restrictionLevel` defaults to `hidden`.
+- If `dataSourceId` is provided, backend derives `tenantAppId` automatically.
+- If `dataSourceId` changes during update, backend recalculates `tenantAppId`.
+
+## Common request examples
+
+### Sync a user's complete role set
+
+```json
+{
+  "roleIds": ["role-uid-uuid-1", "role-uid-uuid-2"]
+}
+```
+
+### Create a role query
+
+```json
+{
+  "name": "Hide archived records",
+  "dataSourceId": "data-source-uuid",
+  "roleIds": ["role-uid-uuid"],
+  "query": {
+    "condition": "and",
+    "filters": []
+  },
+  "filterChildRelations": false,
+  "restrictionLevel": "hidden"
+}
+```
+
+### Share a record
+
+```json
+{
+  "dataSourceId": "uuid",
+  "recordId": "uuid",
+  "items": [
+    {
+      "principalType": "user",
+      "principalId": "uuid",
+      "permissions": 7,
+      "expiresAt": "2026-12-31T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+## Error expectations
+
+Common backend error patterns:
+
+- `400 Bad Request`
+  - malformed UUID in path, query, or body
+  - missing required DTO fields
+  - invalid enum values
+  - invalid boolean or date format in share payloads
+- `404 Not Found`
+  - role not found
+  - role query not found
+  - tenant user not found
+  - tenant data source not found
+  - one or more submitted role IDs could not be resolved
+- `409 Conflict`
+  - role slug already exists in the tenant
+- `500 Internal Server Error`
+  - unexpected persistence failure
+
+## Frontend integration recommendations
+
+- Use direct `RestApiClient` calls or `useDocyrusClient()` for ACL work; these routes may not be present in generated OpenAPI or collection layers.
+- Prefer role `uid` values from API responses for future writes and filters.
+- Treat `PUT /users/:userId/roles` as the canonical full-sync endpoint.
+- Treat `POST /users/:userId/roles` as an additive convenience endpoint.
+- Send role-query `query` values as raw JSON objects.
+- Omit `tenantAppId` when sending a role query scoped by `dataSourceId`; backend derives it.
+- After deleting a role, invalidate and refetch role lists, user-role lists, role-query lists, and any dependent role-label UI.
+
+## Suggested TypeScript interfaces
+
+```ts
+export interface IAclRole {
+  activitySummaryReportQueryId: string | null;
+  createdBy: string | null;
+  createdOn: string | null;
+  databaseId: string | null;
+  disableLogin: number | null;
+  id: string;
+  lastModifiedBy: string | null;
+  lastModifiedOn: string | null;
+  name: string;
+  ownership: "APP" | "CUSTOM" | "PRODUCT" | "SYSTEM" | "USER";
+  privileges: string;
+  slug: string;
+  status: number | null;
+  tenantAppId: string | null;
+  uid: string;
+}
+
+export interface IAclUserRoleAssignment {
+  createdOn: string | null;
+  id: string;
+  role: {
+    databaseId: string | null;
+    id: string;
+    name: string;
+    slug: string;
+    uid: string;
+  };
+  roleId: string;
+  status: number | null;
+  userId: string;
+}
+
+export interface IAclRoleQuery {
+  createdBy: string | null;
+  createdOn: string | null;
+  dataSourceId: string | null;
+  filterChildRelations: boolean;
+  id: string;
+  lastModifiedBy: string | null;
+  lastModifiedOn: string | null;
+  name: string | null;
+  query: Record<string, unknown> | null;
+  restrictionLevel: "hidden" | "read-only" | "not-deletable";
+  roleIds: string[];
+  tenantAppId: string | null;
+}
+
+export interface IAclRecordShare {
+  id: string;
+  principal_type: "user" | "team" | "role" | "tenant" | "public";
+  principal_id: string;
+  permissions: number;
+  expires_at: string | null;
+  created_by: string | null;
+  created_on: string | null;
+}
+
+export interface IAclEffectiveUserAccess {
+  id: string;
+  user_id: string;
+  permissions: number;
+  source_principal_type: "user" | "team" | "role" | "tenant" | "public";
+  source_principal_id: string;
+}
+```

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