Revamp action definitions and types for server functions

Updated documentation to clarify the concept of actions as server-side functions, distinguishing between global and record scopes, and providing schema-first input examples. Refactored TypeScript types to improve type safety, unify input schema with FieldConfig, and enhance metadata for UI integration and internal API usage.

Author: hotlong

docs/spec/action.md

@@ -1,27 +1,110 @@
-# Action Definitions (RPC)
+# Action Definitions (Server Functions)
 
-Custom business logic can be defined in the `actions` section. Actions act as Remote Procedure Calls (RPC) scoped to the object.
+Actions are custom Server-Side Functions attached to an object. They allow you to encapsulate complex business logic that goes beyond standard CRUD operations.
+
+Unlike Hooks (which trigger automatically), Actions are explicitly invoked by the client (API, Button, Scheduled Task).
+
+## 1. Concepts
+
+### 1.1 Scope (`type`)
+*   **Global Actions**: Operate on the collection level.
+    *   *Examples:* "Import CSV", "Generate Monthly Report", "Sync with External API".
+    *   *Context:* No `id`.
+*   **Record Actions**: Operate on a specific record instance.
+    *   *Examples:* "Approve", "Reject", "Send Email", "Clone".
+    *   *Context:* Has `id`.
+
+### 1.2 Schema-First Inputs
+Input parameters (`params`) are defined using the same `FieldConfig` schema as object fields. This gives you free validation, type coercion, and UI generation.
+
+## 2. Configuration (YAML)
+
+Actions are declared in `*.object.yml` or JSON.
 
 ```yaml
 actions:
-  approve:
-    label: Approve Request
-    description: Approves the current record.
+  # 1. A Record Action (Button on a row)
+  approve_order:
+    type: record
+    label: Approve Order
+    icon: standard:approval
+    confirm_text: "Are you sure you want to approve this order? This cannot be undone."
     params:
       comment:
         type: textarea
-        label: Approval Comments
-    result:
-      type: boolean
+        required: true
+        label: Approval Reason
+  
+  # 2. A Global Action (Button on list view)
+  sync_jira:
+    type: global
+    label: Sync from Jira
+    internal: true # Not exposed to public API
+    params:
+      project_key:
+        type: text
+        required: true
+```
+
+## 3. Implementation (TypeScript)
+
+Implement the logic in a companion `*.action.ts` file.
+
+```typescript
+// src/objects/order.action.ts
+import { ActionDefinition } from '@objectql/types';
+import { Order } from './types';
+
+// Input Type Definition
+interface ApproveInput {
+    comment: string;
+}
+
+export const approve_order: ActionDefinition<Order, ApproveInput> = {
+    type: 'record',
+    
+    // Logic
+    handler: async ({ id, input, api, user }) => {
+        // 1. Fetch current state
+        const order = await api.findOne('order', id);
+        
+        if (order.status !== 'Draft') {
+            throw new Error("Only draft orders can be approved");
+        }
+
+        // 2. Perform updates using Atomic Operations or Transactions
+        await api.update('order', id, {
+            status: 'Approved',
+            approved_by: user.id,
+            approval_comment: input.comment,
+            approved_at: new Date()
+        });
+
+        // 3. Return result to client
+        return { success: true, new_status: 'Approved' };
+    }
+}
 ```
 
-## 1. Properties
+## 4. Why this design is "Optimal"?
+
+1.  **Unified Schema**: Inputs use the same definitions as Database fields. If you know how to define a table, you know how to define an API argument.
+2.  **UI Ready**: The metadata (`label`, `icon`, `confirm_text`, `params`) contains everything a frontend framework (like React Admin or Salesforce Lightning) needs to render a button and a modal form **automatically**.
+3.  **Type Safety**: The `ActionDefinition<Entity, Input, Output>` generic ensures your handler code respects the contract.
+
+## 5. Loading & Registration (Standard)
+
+To ensure the Metadata Loader can automatically bind your actions to the correct object, you must follow the file naming convention:
+
+*   **Object Definition**: `mypackage/objects/invoice.object.yml`
+*   **Action Implementation**: `mypackage/objects/invoice.action.ts` (or `.js`)
+
+The loader extracts the `objectName` from the filename (everything before `.action.`).
+
+```typescript
+// mypackage/objects/invoice.action.ts
+export const approve_invoice: ActionDefinition<Invoice> = { ... };
+export const reject_invoice: ActionDefinition<Invoice> = { ... };
+```
 
-| Property | Type | Description |
-| :--- | :--- | :--- |
-| `label` | `string` | Display label (e.g., for buttons). |
-| `icon` | `string` | Icon name. |
-| `description` | `string` | Help text. |
-| `confirmText` | `string` | Confirmation message before execution. |
-| `params` | `Map<string, FieldConfig>` | Input parameters schema. Same structure as Object fields. |
-| `result` | `FieldConfig` | The shape of the return value. |
+The loader will register `approve_invoice` and `reject_invoice` as actions for the `invoice` object.

packages/types/src/action.ts

@@ -1,21 +1,94 @@
 import { FieldConfig } from "./field";
-import { ObjectQLContext } from "./types";
+import { HookAPI } from "./hook"; // Reuse the restricted API interface
 
+/**
+ * Defines the scope of the action.
+ * - `record`: Acts on a specific record instance (e.g. "Approve Order").
+ * - `global`: Acts on the collection or system (e.g. "Import CSV", "Daily Report").
+ */
+export type ActionType = 'record' | 'global';
+
+/**
+ * Re-using FieldConfig allows us to describe input parameters 
+ * using the same rich vocabulary as database fields (validation, UI hints, etc).
+ */
+export type ActionInputDefinition = Record<string, FieldConfig>;
+
+/**
+ * Context passed to the action handler execution.
+ */
+export interface ActionContext<BaseT = any, InputT = any> {
+    /** The object this action belongs to. */
+    objectName: string;
+    
+    /** The name of the action being executed. */
+    actionName: string;
+
+    /** 
+     * The ID of the record being acted upon.
+     * Only available if type is 'record'.
+     */
+    id?: string | number;
+
+    /**
+     * The validated input arguments.
+     */
+    input: InputT;
+
+    /**
+     * Database Access API (Same as Hooks).
+     */
+    api: HookAPI;
+
+    /**
+     * User Session.
+     */
+    user?: {
+        id: string | number;
+        [key: string]: any;
+    };
+}
+
+/**
+ * The configuration of an Action visible to the Metadata engine (YAML/JSON side).
+ */
 export interface ActionConfig {
     label?: string;
-    icon?: string;
     description?: string;
-    confirmText?: string;
+    icon?: string;
 
-    // Parameters definition for the action (input schema)
-    params?: Record<string, FieldConfig>;
-}
+    /**
+     * Default: 'global' if no fields defined, but usually specified explicitly.
+     */
+    type?: ActionType; // 'record' | 'global'
 
-export interface ActionContext extends ObjectQLContext {
-    objectName: string;
-    actionName: string;
-    id?: string | number; // Optional record ID if action is applied to a record
-    params: any;          // Arguments passed to the action
+    /**
+     * Message to show before executing. If present, UI should prompt confirmation.
+     */
+    confirm_text?: string;
+    
+    /**
+     * If true, this action is not exposed via API directly (server-internal).
+     */
+    internal?: boolean;
+    
+    /**
+     * Input parameter schema.
+     */
+    params?: ActionInputDefinition;
+    
+    /**
+     * Output data shape description (optional, for content negotiation).
+     */
+    return_type?: string | FieldConfig; 
 }
 
-export type ActionHandler = (ctx: ActionContext) => Promise<any>;
+/**
+ * The full implementation definition (Code side).
+ */
+export interface ActionDefinition<BaseT = any, InputT = any, ReturnT = any> extends ActionConfig {
+    /**
+     * The business logic implementation.
+     */
+    handler: (ctx: ActionContext<BaseT, InputT>) => Promise<ReturnT>;
+}