@docyrus/docyrus 0.0.19 → 0.0.21

package/resources/pi-agent/skills/docyrus-platform/references/core-building-blocks.md

@@ -0,0 +1,53 @@
+# Core Building Blocks
+
+## Data Sources
+
+Data sources are the fundamental building block. Each data source represents a structured collection of records with a defined schema. Every data source — whether backed by an internal database table or a connected external REST API — is exposed through a single, unified CRUD endpoint. This means consumers interact with all data sources the same way regardless of where the data lives.
+
+**Types:**
+
+- **Simple** — Schema-flexible records. Quick to set up, ideal for lightweight or rapidly evolving data.
+- **Advanced** — Fully structured data sources with dedicated columns per field. Supports base data sources (shared field inheritance across variants) and high-performance querying.
+- **External** — Connected external REST API resources or databases mapped as data sources. External resources are accessed through the same unified API as internal data sources, abstracting away the underlying connection.
+- **System** — Pre-built templates for common entities: documents, threads, messages, contacts, organizations, activities, tasks, events, calendars, time entries, projects, and sections.
+
+**Ownership models:** App-scoped, tenant-custom, product-provided, system-built-in, or user-specific.
+
+## Fields
+
+Every data source is composed of fields. 45+ field types cover all data modeling needs:
+
+| Category | Field Types |
+|---|---|
+| **Text** | text, textarea, email, phone, URL, color, icon, display |
+| **Rich content** | document editor, HTML editor, email editor, code editor |
+| **Numeric** | number, money, currency, duration, rating, autonumber, identity |
+| **Date & time** | date, dateTime, time, dateRange |
+| **Boolean** | checkbox, switch |
+| **Selection** | select, multiSelect, tagSelect, status, radioGroup |
+| **Users** | userSelect, userMultiSelect |
+| **Relations** | relation (lookup to another data source), list (virtual related records) |
+| **Nested data** | inlineData (nested JSON arrays), inlineForm (nested objects) |
+| **Files** | file, image, fileStorageFolder |
+| **Computed** | formula (JSONata expressions), display (read-only computed) |
+| **Workflow** | approvalStatus, taskList, todo |
+| **Advanced** | json, queryBuilder, dynamic, schema, schemaRepeater, locationSelect |
+| **System** | systemEnum, systemBuffer, systemVector, systemTextArray, systemUuidArray |
+
+## Enumerations
+
+Multi-option fields (select, multiSelect, status, tagSelect) support enumerations with color, icon, and ordering. Enum sets allow sharing option lists across multiple fields.
+
+## Apps
+
+Apps are the top-level container that groups data sources, views, forms, pages, navigation, and configurations into a deployable unit.
+
+**Supported app types:** web, mobile, AI agent, integration, inline (embedded), client portal (web & mobile), Chrome extension, MS Office add-in, MS Outlook add-in, external (white-label), website, and website widget.
+
+**App lifecycle:** draft → design → development → active → inactive, with archiving and permanent deletion.
+
+**Customization layers:** Apps support per-tenant overrides for pages, views, menus, fields, and enums — allowing product apps to be tailored without forking.
+
+## Custom Queries
+
+SQL-based analytics templates with variable interpolation. Support dynamic runtime filters, pagination, and multiple database targets. Built-in variables include tenant context, user identity, and custom filter expressions.

package/resources/pi-agent/skills/{docyrus-api-dev → docyrus-platform}/references/data-source-query-guide.md

@@ -74,7 +74,7 @@ interface ISelectQueryParams {
 
   // --- Aggregation ---
   calculations?: ISelectQueryCalculationRule[] | null;
-  showGroupSummaries?: boolean;
+  groupSummaries?: boolean;
 
   // --- Sorting ---
   orderBy?: string | ISelectQueryOrderBy | ISelectQueryOrderBy[];
@@ -94,7 +94,7 @@ interface ISelectQueryParams {
   cursorDateEnd?: string | null;
 
   // --- Advanced ---
-  childQueries?: Record<string, IQueryChildQueryParams> | null;
+  childQueries?: ISelectQueryChildQueryParams[] | null;
   pivot?: {
     matrix: ISelectPivotMatrixQuery[];
     hideEmptyRows?: boolean;
@@ -700,7 +700,7 @@ Count unique emails:
 }
 ```
 
-### `showGroupSummaries`
+### `groupSummaries`
 
 **Type:** `boolean`
 **Default:** `false`
@@ -837,16 +837,14 @@ Block subquery formulas can also be wrapped under an `expression` key:
 {
   "formulas": {
     "children_count": {
-      "expression": {
-        "from": "app_child_table",
-        "with": "parent_field",
-        "inputs": [{
-          "kind": "aggregate",
-          "name": "count",
-          "distinct": true,
-          "inputs": [{ "kind": "column", "name": "id" }]
-        }]
-      }
+      "from": "app_child_table",
+      "with": "parent_field",
+      "inputs": [{
+        "kind": "aggregate",
+        "name": "count",
+        "distinct": true,
+        "inputs": [{ "kind": "column", "name": "id" }]
+      }]
     }
   }
 }
@@ -1294,14 +1292,15 @@ interface ISelectPivotMatrixQuery {
 
 ## Child Queries
 
-**Parameter:** `childQueries` — `Record<string, IQueryChildQueryParams> | null`
+**Parameter:** `childQueries` — `ISelectQueryChildQueryParams[] | null`
 
 Use `childQueries` to fetch related records from a child data source as a nested JSON array for each parent record. This is similar to a `LEFT JOIN` but returns results as an aggregated JSON array in a single column.
 
 ### Child Query Structure
 
 ```typescript
-interface IQueryChildQueryParams {
+interface ISelectQueryChildQueryParams {
+  alias: string;                    // alias for the child query
   from: string;                    // child data source slug in "appSlug_slug" format
   using: string;                   // field in the child DS that references the parent record
   columns?: string | null;         // comma-separated columns to select from child
@@ -1317,8 +1316,9 @@ interface IQueryChildQueryParams {
 ```json
 {
   "columns": "id, name, matters",
-  "childQueries": {
-    "matters": {
+  "childQueries": [
+    {
+      "alias": "matters",
       "from": "attornaid_matter",
       "using": "client",
       "columns": "name",
@@ -1328,7 +1328,7 @@ interface IQueryChildQueryParams {
         ]
       }
     }
-  }
+  ]
 }
 ```
 
@@ -1359,8 +1359,9 @@ interface IQueryChildQueryParams {
 ```json
 {
   "columns": "id, product_name, recent_orders",
-  "childQueries": {
-    "recent_orders": {
+  "childQueries": [
+    {
+      "alias": "recent_orders",
       "from": "shop_order_item",
       "using": "product",
       "columns": "order_date, quantity, total_price",
@@ -1372,7 +1373,7 @@ interface IQueryChildQueryParams {
         ]
       }
     }
-  }
+  ]
 }
 ```
 
@@ -1381,8 +1382,9 @@ interface IQueryChildQueryParams {
 ```json
 {
   "columns": "id, name, order_stats",
-  "childQueries": {
-    "order_stats": {
+  "childQueries": [
+    {
+      "alias": "order_stats",
       "from": "shop_order",
       "using": "customer",
       "calculations": [
@@ -1390,7 +1392,7 @@ interface IQueryChildQueryParams {
         { "field": "amount", "func": "sum", "name": "total_spent" }
       ]
     }
-  }
+  ]
 }
 ```
 
@@ -1769,8 +1771,9 @@ Monthly sales report grouped by category:
 {
   "dataSourceFullSlug": "crm_customer",
   "columns": "id, name, email, recent_orders, open_tickets",
-  "childQueries": {
-    "recent_orders": {
+  "childQueries": [
+    {
+      "alias": "recent_orders",
       "from": "shop_order",
       "using": "customer",
       "columns": "id, order_date, total_amount, ...status(status_label:name)",
@@ -1782,7 +1785,8 @@ Monthly sales report grouped by category:
         ]
       }
     },
-    "open_tickets": {
+    {
+      "alias": "open_tickets",
       "from": "support_ticket",
       "using": "customer",
       "columns": "id, subject, priority, created_on",
@@ -1794,7 +1798,7 @@ Monthly sales report grouped by category:
         ]
       }
     }
-  },
+  ],
   "filters": {
     "rules": [
       { "field": "status", "operator": "=", "value": "active" }

package/resources/pi-agent/skills/docyrus-platform/references/developer-tools.md

@@ -0,0 +1,28 @@
+# Developer Tools
+
+## OpenAPI Specification
+
+- Auto-generated, tenant-specific OpenAPI specs reflecting all configured data sources and fields
+- Regeneratable on-demand after schema changes
+- Powers client SDK generation and API discovery
+
+## MCP Server (Model Context Protocol)
+
+- Built-in MCP server exposing platform capabilities as AI-consumable tools
+- Discovery, CRUD, querying, enum management, custom query execution, and JSONata evaluation — all accessible via MCP transport
+
+## CLI
+
+- Full-featured CLI (`@docyrus/docyrus`) for terminal and AI agent use
+- Commands: environment management, authentication, data operations, schema management (studio), app management, API discovery, AI chat, and direct API requests
+- Multi-account, multi-tenant session management
+- OpenAPI discovery with caching and fallback generation
+- Interactive TUI mode
+
+For full CLI command reference, see [docyrus-cli-usage.md](docyrus-cli-usage.md).
+
+## Client Libraries
+
+- REST API client (`@docyrus/api-client`) with OAuth2 support, interceptors, streaming, and file operations
+- React authentication provider (`@docyrus/signin`) with standalone OAuth2 PKCE and iframe postMessage modes
+- Auto-generated collection hooks from OpenAPI specs for data fetching integration