codymaster 4.1.4 → 4.4.1

package/skills/cm-frappe-agent/skills/frappe-api/SKILL.md

@@ -0,0 +1,740 @@
+---
+name: frappe-api
+description: Frappe Python and JavaScript API reference including document operations, database queries, utilities, and REST API patterns. Use when working with frappe.get_doc, frappe.db, frappe.call, or any Frappe API methods.
+---
+
+# Frappe API Reference
+
+Complete reference for Frappe's Python and JavaScript APIs for document operations, database queries, utilities, and server communication.
+
+## When to Use This Skill
+
+- Working with Document API (get_doc, new_doc, save)
+- Database operations (frappe.db.*)
+- Making API calls from client to server
+- Using Frappe utilities (date, number formatting)
+- Creating whitelisted API endpoints
+- Working with REST API
+
+## Python API
+
+### Document Operations
+
+#### Get Document
+```python
+# Get existing document
+doc = frappe.get_doc("Customer", "CUST-001")
+
+# Get document with filters
+doc = frappe.get_doc("Customer", {"customer_name": "John"})
+
+# Get last document
+doc = frappe.get_last_doc("Customer", filters={"status": "Active"})
+
+# Get cached document (read-only, faster)
+doc = frappe.get_cached_doc("Customer", "CUST-001")
+
+# Check if document exists
+if frappe.db.exists("Customer", "CUST-001"):
+    doc = frappe.get_doc("Customer", "CUST-001")
+```
+
+#### Create Document
+```python
+# Create new document
+doc = frappe.new_doc("Customer")
+doc.customer_name = "New Customer"
+doc.customer_type = "Company"
+doc.insert()
+
+# Create with dict
+doc = frappe.get_doc({
+    "doctype": "Customer",
+    "customer_name": "New Customer",
+    "customer_type": "Company"
+})
+doc.insert()
+
+# Create and insert in one step
+doc = frappe.get_doc({
+    "doctype": "Customer",
+    "customer_name": "New Customer"
+}).insert()
+
+# Insert ignoring permissions
+doc.insert(ignore_permissions=True)
+
+# Insert ignoring mandatory fields
+doc.insert(ignore_mandatory=True)
+```
+
+#### Update Document
+```python
+# Update and save
+doc = frappe.get_doc("Customer", "CUST-001")
+doc.customer_name = "Updated Name"
+doc.save()
+
+# Save ignoring permissions
+doc.save(ignore_permissions=True)
+
+# Update single value
+frappe.db.set_value("Customer", "CUST-001", "customer_name", "New Name")
+
+# Update multiple values
+frappe.db.set_value("Customer", "CUST-001", {
+    "customer_name": "New Name",
+    "status": "Active"
+})
+
+# Bulk update
+frappe.db.set_value("Customer", {"status": "Inactive"}, "status", "Active")
+```
+
+#### Delete Document
+```python
+# Delete document
+frappe.delete_doc("Customer", "CUST-001")
+
+# Delete ignoring permissions
+frappe.delete_doc("Customer", "CUST-001", ignore_permissions=True)
+
+# Delete with linked documents
+frappe.delete_doc("Customer", "CUST-001", force=True)
+
+# Delete from controller
+doc.delete()
+```
+
+### Database API (frappe.db)
+
+#### Select Queries
+```python
+# Get single value
+value = frappe.db.get_value("Customer", "CUST-001", "customer_name")
+
+# Get multiple fields
+values = frappe.db.get_value("Customer", "CUST-001",
+    ["customer_name", "status"], as_dict=True)
+
+# Get with filters
+value = frappe.db.get_value("Customer",
+    {"customer_type": "Company"}, "customer_name")
+
+# Get list of values
+names = frappe.db.get_all("Customer",
+    filters={"status": "Active"},
+    fields=["name", "customer_name"],
+    order_by="creation desc",
+    limit=10
+)
+
+# Get list with pluck (single field as list)
+names = frappe.db.get_all("Customer",
+    filters={"status": "Active"},
+    pluck="name"
+)
+
+# Complex filters
+docs = frappe.db.get_all("Sales Invoice",
+    filters={
+        "status": ["in", ["Paid", "Unpaid"]],
+        "grand_total": [">", 1000],
+        "posting_date": ["between", ["2024-01-01", "2024-12-31"]],
+        "customer": ["like", "%Corp%"]
+    },
+    fields=["name", "customer", "grand_total"]
+)
+
+# Filter operators
+# =, !=, <, >, <=, >=
+# in, not in
+# like, not like
+# between
+# is, is not (for None)
+# descendants of, ancestors of (for tree doctypes)
+
+# Get count
+count = frappe.db.count("Customer", {"status": "Active"})
+
+# Check existence
+exists = frappe.db.exists("Customer", "CUST-001")
+exists = frappe.db.exists("Customer", {"customer_name": "John"})
+```
+
+#### Raw SQL
+```python
+# Execute SQL query
+result = frappe.db.sql("""
+    SELECT name, customer_name, grand_total
+    FROM `tabSales Invoice`
+    WHERE status = %s AND grand_total > %s
+    ORDER BY creation DESC
+    LIMIT 10
+""", ("Paid", 1000), as_dict=True)
+
+# Single value
+total = frappe.db.sql("""
+    SELECT SUM(grand_total) FROM `tabSales Invoice`
+    WHERE status = 'Paid'
+""")[0][0]
+
+# With named parameters
+result = frappe.db.sql("""
+    SELECT * FROM `tabCustomer`
+    WHERE name = %(name)s
+""", {"name": "CUST-001"}, as_dict=True)
+```
+
+#### Insert/Update
+```python
+# Insert raw
+frappe.db.sql("""
+    INSERT INTO `tabCustomer` (name, customer_name)
+    VALUES (%s, %s)
+""", ("CUST-002", "New Customer"))
+
+# Commit transaction
+frappe.db.commit()
+
+# Rollback
+frappe.db.rollback()
+```
+
+### Whitelisted API
+
+```python
+# Create API endpoint
+@frappe.whitelist()
+def get_customer_details(customer):
+    """Get customer details
+
+    Args:
+        customer: Customer ID
+
+    Returns:
+        dict: Customer details
+    """
+    doc = frappe.get_doc("Customer", customer)
+    return {
+        "name": doc.name,
+        "customer_name": doc.customer_name,
+        "outstanding_amount": get_outstanding(customer)
+    }
+
+# Allow guest access (no login required)
+@frappe.whitelist(allow_guest=True)
+def public_api():
+    return {"status": "ok"}
+
+# With specific methods
+@frappe.whitelist(methods=["POST"])
+def create_record(data):
+    doc = frappe.get_doc(data)
+    doc.insert()
+    return doc.name
+```
+
+### Utilities
+
+#### Date/Time
+```python
+from frappe.utils import (
+    now, nowdate, nowtime, now_datetime,
+    today, getdate, get_datetime,
+    add_days, add_months, add_years,
+    date_diff, time_diff, time_diff_in_seconds,
+    get_first_day, get_last_day,
+    formatdate, format_datetime
+)
+
+# Current date/time
+current = nowdate()  # "2024-01-15"
+current_dt = now_datetime()  # datetime object
+timestamp = now()  # "2024-01-15 10:30:00"
+
+# Date arithmetic
+next_week = add_days(nowdate(), 7)
+next_month = add_months(nowdate(), 1)
+last_year = add_years(nowdate(), -1)
+
+# Date difference
+days = date_diff(end_date, start_date)
+seconds = time_diff_in_seconds(end_time, start_time)
+
+# First/last day of month
+first = get_first_day(nowdate())
+last = get_last_day(nowdate())
+
+# Parse dates
+date_obj = getdate("2024-01-15")
+dt_obj = get_datetime("2024-01-15 10:30:00")
+
+# Format dates
+formatted = formatdate("2024-01-15", "dd-MM-yyyy")
+```
+
+#### Numbers
+```python
+from frappe.utils import (
+    flt, cint, cstr,
+    fmt_money, rounded,
+    money_in_words
+)
+
+# Type conversion with defaults
+num = flt(value)  # float, None -> 0.0
+num = flt(value, 2)  # with precision
+integer = cint(value)  # int, None -> 0
+string = cstr(value)  # string, None -> ""
+
+# Formatting
+formatted = fmt_money(1234.56, currency="USD")  # "$1,234.56"
+rounded_val = rounded(1234.567, 2)  # 1234.57
+words = money_in_words(1234.56, "USD")  # "One Thousand..."
+```
+
+#### Strings
+```python
+from frappe.utils import (
+    strip_html, strip_html_tags,
+    escape_html, sanitize_html,
+    scrub, unscrub
+)
+
+# HTML handling
+plain = strip_html("<p>Hello</p>")  # "Hello"
+safe = escape_html("<script>bad</script>")
+
+# Field name conversion
+field = scrub("My Field Name")  # "my_field_name"
+label = unscrub("my_field_name")  # "My Field Name"
+```
+
+### Messaging & Notifications
+
+```python
+# Show message (appears as toast)
+frappe.msgprint("Document saved successfully")
+
+# With indicator
+frappe.msgprint("Error occurred", indicator="red", title="Error")
+
+# Throw error (stops execution)
+frappe.throw("Invalid data provided")
+
+# With exception type
+from frappe.exceptions import ValidationError
+frappe.throw("Validation failed", exc=ValidationError)
+
+# Send email
+frappe.sendmail(
+    recipients=["user@example.com"],
+    subject="Hello",
+    message="Email body",
+    template="email_template",
+    args={"name": "John"}
+)
+
+# Create system notification
+frappe.publish_realtime(
+    "msgprint",
+    {"message": "Task completed"},
+    user="user@example.com"
+)
+```
+
+### Background Jobs
+
+```python
+# Enqueue background job
+frappe.enqueue(
+    "myapp.tasks.heavy_task",
+    queue="long",
+    timeout=600,
+    job_name="Heavy Task",
+    customer="CUST-001"
+)
+
+# In tasks.py
+def heavy_task(customer):
+    # Long running task
+    process_customer(customer)
+
+# Enqueue with callback
+frappe.enqueue(
+    method=process_data,
+    queue="default",
+    on_success=on_complete,
+    on_failure=on_error
+)
+
+# Scheduled jobs (in hooks.py)
+scheduler_events = {
+    "daily": [
+        "myapp.tasks.daily_task"
+    ],
+    "hourly": [
+        "myapp.tasks.hourly_task"
+    ],
+    "cron": {
+        "0 0 * * *": [  # Midnight
+            "myapp.tasks.midnight_task"
+        ]
+    }
+}
+```
+
+### Session & User
+
+```python
+# Current user
+user = frappe.session.user
+
+# Check if logged in
+if frappe.session.user != "Guest":
+    pass
+
+# Check permissions
+if frappe.has_permission("Customer", "write"):
+    pass
+
+# Get user info
+user_doc = frappe.get_doc("User", frappe.session.user)
+full_name = frappe.utils.get_fullname(frappe.session.user)
+
+# Check roles
+if "System Manager" in frappe.get_roles():
+    pass
+
+# Run as different user
+frappe.set_user("Administrator")
+# ... do operations
+frappe.set_user(original_user)
+```
+
+## JavaScript API
+
+### Document Operations
+
+```javascript
+// Get document
+frappe.call({
+    method: 'frappe.client.get',
+    args: {
+        doctype: 'Customer',
+        name: 'CUST-001'
+    },
+    callback: function(r) {
+        console.log(r.message);
+    }
+});
+
+// Create document
+frappe.call({
+    method: 'frappe.client.insert',
+    args: {
+        doc: {
+            doctype: 'Customer',
+            customer_name: 'New Customer'
+        }
+    },
+    callback: function(r) {
+        console.log('Created:', r.message.name);
+    }
+});
+
+// Save document
+frappe.call({
+    method: 'frappe.client.save',
+    args: {
+        doc: cur_frm.doc
+    }
+});
+
+// Delete document
+frappe.call({
+    method: 'frappe.client.delete',
+    args: {
+        doctype: 'Customer',
+        name: 'CUST-001'
+    }
+});
+```
+
+### frappe.call (API Calls)
+
+```javascript
+// Call whitelisted method
+frappe.call({
+    method: 'myapp.api.get_customer_details',
+    args: {
+        customer: 'CUST-001'
+    },
+    freeze: true,
+    freeze_message: 'Loading...',
+    callback: function(r) {
+        if (r.message) {
+            console.log(r.message);
+        }
+    },
+    error: function(r) {
+        frappe.msgprint('Error occurred');
+    }
+});
+
+// Async/await pattern
+async function getCustomer(name) {
+    const response = await frappe.call({
+        method: 'myapp.api.get_customer',
+        args: { name }
+    });
+    return response.message;
+}
+
+// Call with promise
+frappe.call({
+    method: 'myapp.api.process',
+    args: { data: 'test' }
+}).then(r => {
+    console.log(r.message);
+});
+```
+
+### Form API (cur_frm)
+
+```javascript
+frappe.ui.form.on('Sales Invoice', {
+    refresh: function(frm) {
+        // Add custom button
+        frm.add_custom_button('Process', function() {
+            // Button action
+        }, 'Actions');
+
+        // Set field properties
+        frm.set_df_property('field_name', 'read_only', 1);
+        frm.set_df_property('field_name', 'hidden', 1);
+        frm.set_df_property('field_name', 'reqd', 1);
+
+        // Set query for link field
+        frm.set_query('customer', function() {
+            return {
+                filters: {
+                    status: 'Active'
+                }
+            };
+        });
+
+        // Toggle fields
+        frm.toggle_display('field_name', frm.doc.show_field);
+        frm.toggle_reqd('field_name', frm.doc.is_required);
+    },
+
+    customer: function(frm) {
+        // Field change handler
+        if (frm.doc.customer) {
+            frappe.call({
+                method: 'myapp.api.get_customer_details',
+                args: { customer: frm.doc.customer },
+                callback: function(r) {
+                    frm.set_value('customer_name', r.message.name);
+                }
+            });
+        }
+    },
+
+    validate: function(frm) {
+        // Validate before save
+        if (!frm.doc.customer) {
+            frappe.throw('Customer is required');
+            return false;
+        }
+    },
+
+    before_save: function(frm) {
+        // Before save actions
+        frm.doc.modified_by_script = 1;
+    },
+
+    after_save: function(frm) {
+        // After save actions
+        frappe.show_alert('Document saved!');
+    }
+});
+
+// Child table events
+frappe.ui.form.on('Sales Invoice Item', {
+    qty: function(frm, cdt, cdn) {
+        let row = locals[cdt][cdn];
+        row.amount = row.qty * row.rate;
+        frm.refresh_field('items');
+    },
+
+    items_add: function(frm, cdt, cdn) {
+        // New row added
+        let row = locals[cdt][cdn];
+        row.warehouse = frm.doc.default_warehouse;
+    },
+
+    items_remove: function(frm) {
+        // Row removed - recalculate totals
+        calculate_totals(frm);
+    }
+});
+```
+
+### Dialogs
+
+```javascript
+// Simple prompt
+frappe.prompt(
+    {fieldname: 'name', fieldtype: 'Data', label: 'Name', reqd: 1},
+    function(values) {
+        console.log(values.name);
+    },
+    'Enter Name'
+);
+
+// Multiple fields
+frappe.prompt([
+    {fieldname: 'name', fieldtype: 'Data', label: 'Name', reqd: 1},
+    {fieldname: 'email', fieldtype: 'Data', label: 'Email', options: 'Email'},
+    {fieldname: 'date', fieldtype: 'Date', label: 'Date', default: frappe.datetime.nowdate()}
+], function(values) {
+    console.log(values);
+}, 'Enter Details', 'Submit');
+
+// Custom dialog
+let dialog = new frappe.ui.Dialog({
+    title: 'My Dialog',
+    fields: [
+        {fieldname: 'customer', fieldtype: 'Link', options: 'Customer', label: 'Customer'},
+        {fieldname: 'amount', fieldtype: 'Currency', label: 'Amount'}
+    ],
+    primary_action_label: 'Submit',
+    primary_action: function(values) {
+        console.log(values);
+        dialog.hide();
+    }
+});
+dialog.show();
+
+// Confirmation
+frappe.confirm(
+    'Are you sure you want to proceed?',
+    function() {
+        // Yes
+        process_action();
+    },
+    function() {
+        // No
+    }
+);
+```
+
+### Utilities
+
+```javascript
+// Messages
+frappe.msgprint('Hello World');
+frappe.msgprint({
+    title: 'Success',
+    message: 'Operation completed',
+    indicator: 'green'
+});
+
+frappe.throw('Error message');  // Stops execution
+
+frappe.show_alert('Quick notification', 5);  // 5 seconds
+
+// Date/time
+frappe.datetime.nowdate();  // "2024-01-15"
+frappe.datetime.now_datetime();  // "2024-01-15 10:30:00"
+frappe.datetime.add_days('2024-01-15', 7);
+frappe.datetime.str_to_obj('2024-01-15');
+
+// Format
+frappe.format(1234.56, {fieldtype: 'Currency'});
+frappe.format('2024-01-15', {fieldtype: 'Date'});
+
+// Routing
+frappe.set_route('Form', 'Customer', 'CUST-001');
+frappe.set_route('List', 'Customer');
+frappe.set_route('query-report', 'Sales Report');
+
+// Current route
+let route = frappe.get_route();
+```
+
+## REST API
+
+### Authentication
+
+```bash
+# Token-based
+curl -X GET "https://site.com/api/resource/Customer" \
+  -H "Authorization: token api_key:api_secret"
+
+# Session-based (login first)
+curl -X POST "https://site.com/api/method/login" \
+  -d "usr=user&pwd=password"
+```
+
+### CRUD Operations
+
+```bash
+# List
+GET /api/resource/Customer?filters=[["status","=","Active"]]&fields=["name","customer_name"]&limit_page_length=10
+
+# Get single
+GET /api/resource/Customer/CUST-001
+
+# Create
+POST /api/resource/Customer
+Content-Type: application/json
+{"customer_name": "New Customer", "customer_type": "Company"}
+
+# Update
+PUT /api/resource/Customer/CUST-001
+Content-Type: application/json
+{"customer_name": "Updated Name"}
+
+# Delete
+DELETE /api/resource/Customer/CUST-001
+```
+
+### Call Methods
+
+```bash
+# Call whitelisted method
+POST /api/method/myapp.api.get_customer_details
+Content-Type: application/json
+{"customer": "CUST-001"}
+```
+
+### JavaScript Fetch
+
+```javascript
+// Using fetch API
+async function getCustomers() {
+    const response = await fetch('/api/resource/Customer?limit_page_length=10', {
+        headers: {
+            'Content-Type': 'application/json'
+        }
+    });
+    const data = await response.json();
+    return data.data;
+}
+
+// POST request
+async function createCustomer(customerData) {
+    const response = await fetch('/api/resource/Customer', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(customerData)
+    });
+    return response.json();
+}
+```