@wanasapps/deluge-core 1.0.0 → 1.2.0

package/assets/DELUGE_GUIDE.md

@@ -0,0 +1,312 @@
+# Zoho Deluge — how to write it correctly
+
+Deluge is Zoho's scripting language. It runs inside Zoho products (CRM, Creator, Books, Desk, Recruit, People, Projects, Bigin, Inventory, Analytics, Cliq, Mail, Sheet, Writer, WorkDrive, Bookings, Subscriptions/Billing, SalesIQ, Calendar) and nowhere else. It looks like JavaScript or Java and **is not**: no classes, no closures, no `while`, no `switch`, a different standard library, and a runtime that validates far less than you expect. Most mistakes come from writing JavaScript with Deluge punctuation.
+
+This document has two parts. **Part 1** is guidance: how to think, the contracts, and the traps — every trap marked **(verified)** was confirmed against a live Zoho CRM org, not taken from documentation. **Part 2** is the complete reference — every statement, data type, built-in function and integration task — generated from Zoho's own Deluge documentation (source and date at the top of Part 2). When the two disagree on a detail, Part 2 is what Zoho documents; Part 1 is what actually happened.
+
+## 1. Shape of a script
+
+```deluge
+// Standalone function in Zoho CRM. The FIRST meaningful line is the signature:
+//   <returnType> standalone.<api_name>(<Type> <param>, ...)
+string standalone.NormalizeLead(String leadId, Int retries)
+{
+	lead = zoho.crm.getRecordById("Leads", leadId.toLong());
+	if(lead == null || lead.isEmpty())
+	{
+		return "not found";
+	}
+	info "normalizing " + leadId;
+	return "ok";
+}
+```
+
+- Every statement ends with `;`. Blocks use `{ }`. Indentation is tabs by convention (Zoho's editor writes tabs).
+- No `var`/`let`/`const` and no type declarations: `x = 5;` creates `x`. Variables are function-scoped, dynamically typed, and can change type.
+- Comments: `//` and `/* ... */`.
+- Signature types: `String`, `Int`, `Long`, `Decimal`, `Boolean`, `Date`, `Map`, `List`. Return types: `string`, `int`, `decimal`, `boolean`, `map`, `list`, `void`.
+- Reserved words you cannot use as variable names: `bool collection date false for each else else if float from if ifnull in int is list map null permissions portal reload return string thisapp true void zoho`.
+- **Do not put a `//` comment block above the signature when uploading raw code (verified).** Zoho's raw code endpoint reads everything before the first `(` as the package declaration and rejects a leading comment with a misleading `COMPILATION_ERROR`. Comments inside the body are fine. Tooling built on `@wanasapps/deluge-core` (the `zone` CLI, the VS Code extension) strips a leading header for you.
+- **Function names are case-insensitive (verified).** `standalone.SyncRecentCommissions(...)` and `standalone.syncrecentcommissions(...)` are the same function. A case-sensitive search for "is this function used anywhere" will report live code as dead.
+
+## 2. Control flow — what exists and what does not
+
+```deluge
+if(a > 1 && b != null)
+{
+	// ...
+}
+else if(c == "x")
+{
+	// ...
+}
+else
+{
+	// ...
+}
+
+label = if(score > 80, "high", "low");        // conditional-if EXPRESSION
+name  = ifNull(input.Name, "unknown");       // first value when not null, else the second
+
+for each item in someList
+{
+	if(item == null) { continue; }
+	if(item == "stop") { break; }
+}
+
+for each index i in someList          // i is the position, 0-based
+{
+	value = someList.get(i);
+}
+
+for each key in someMap.keys()
+{
+	value = someMap.get(key);
+}
+```
+
+- Operators: `==`, `!=`, `<`, `<=`, `>`, `>=`, `&&`, `||`, `!`. String equality with `==` works and is case-sensitive; use `.equalsIgnoreCase()` otherwise.
+- **There is no `while` loop.** Iterate a list, or a literal range such as `{1,2,3,4,5}`; if you need "until", loop a generous fixed range and `break`.
+- **There is no `switch`.** Chain `else if`, or look the value up in a Map.
+- **`throw` exists.** `throw "message";` or `throw {"message": "...", "data": {...}};` raises an exception that the nearest `catch` receives; inside a `catch(e)`, `throw e;` re-throws. There is no `finally`.
+- `return;` is valid in a `void` function; every other function must return a value on every path.
+- Criteria are written as `(<condition>) and/or (<condition>)` — parentheses around each condition, `and`/`or`/`&&`/`||` between them.
+
+## 3. Types, literals and the brace trap
+
+| Type | Create | Notes |
+|---|---|---|
+| Map (key-value) | `m = Map();` or `m = {"a": 1, "b": "x"};` | keys unique; a repeated key overwrites |
+| List | `l = List();` or `l = {1, 2, 3};` | 0-based; `List:String()` / `List:Int()` / `List:Float()` / `List:date()` / `List:Bool()` restrict the element type |
+| Collection | `c = Collection();` | index-value or key-value, chosen by how you insert |
+| Text | `"double"` (backslash escapes a quote inside) | concatenate with `+`; numbers auto-convert on `+` with text |
+| Number | `5`, `1234567890123` | integer; -9,223,372,036,854,775,808 to 9,223,372,036,854,775,808 |
+| Decimal | `5.25` | a Number in an operation with a Decimal yields a Decimal |
+| Boolean | `true` / `false` | no quotes; case-insensitive |
+| Date-time | `'15-Aug-1947'`, `'2026-09-01 14:30:00'` | **single quotes**; no time → 00:00:00; many formats accepted (see Part 2) |
+| Time | `'19:00:00'`, `'06:00:00 PM'` | Creator only; all three components required |
+| null | `null` | |
+
+**Curly braces mean both Map and List.** `{"a": 1}` is a Map; `{1, 2}` is a List; `{}` is ambiguous. Use `Map()` and `List()` for empties.
+
+**Record ids are Longs, not Strings.** They arrive as strings from JSON and as `Long` from `zoho.crm.*`. Compare and pass them carefully: `id.toLong()` when a Zoho call expects an id, `id.toString()` when building a string.
+
+### Map
+```deluge
+m = Map();
+m.put("k", "v");            // put replaces
+m.get("k");                 // null when missing — no exception
+m.containKey("k");          // note the spelling: containKey, not containsKey
+m.containValue("v");
+m.keys();                   // List of keys
+m.remove("k");
+m.putAll(otherMap);         // merge
+m.size();  m.isEmpty();
+```
+
+### List
+```deluge
+l = List();
+l.add("x");  l.addAll(otherList);     // addAll: at most 25,000 elements per call
+l.get(0);                             // out-of-range throws
+l.size();  l.isEmpty();  l.contains("x");  l.indexOf("x");  l.lastIndexOf("x");
+l.removeElement("x");                 // by value
+l.remove(0);                          // by index
+l.sort();  l.distinct();  l.intersect(other);
+l.toString();                         // "x,y" — comma-joined
+```
+
+### Detecting Map vs List in a value you did not build
+**`getJSONType()` does not exist in this runtime (verified — COMPILATION_ERROR).** Look at the text:
+```deluge
+text = value.toString();
+if(text.startsWith("["))      { list = value.toJSONList(); }
+else if(text.startsWith("{")) { map = value.toMap(); }
+```
+
+## 4. Strings — the methods you will actually use
+
+```deluge
+s.length();  s.trim();  s.toUpperCase();  s.toLowerCase();  s.isEmpty();
+s.contains("x");  s.startsWith("x");  s.endsWith("x");  s.indexOf("x");
+s.subString(0, 3);                    // start inclusive, end exclusive (also subText, mid, left, right)
+s.equalsIgnoreCase("X");
+s.matches("^[0-9]+$");                // regex
+s.toList(",");                        // split → List
+s.getPrefix("@");  s.getSuffix("@");  s.getSuffixIgnoreCase("<body>");
+s.removeFirstOccurence("00");         // Zoho's spelling — one 'r'
+s.leftPad(10, "0");  s.rightPad(10, " ");
+s.toNumber();  s.toLong();  s.toDecimal();  s.toDate();  s.toDateTime();  s.toTime();
+s.toMap();  s.toJSONList();           // parse JSON text
+```
+
+**`replaceAll` — the third argument changes the meaning (verified).**
+```deluge
+s.replaceAll("[^0-9]", "");           // 2 args: pattern is a REGEX
+s.replaceAll("+", "", true);          // 3rd arg true: pattern is LITERAL text
+```
+Passing `true` "to be safe" silently turns a character class into a literal search for the characters `[^0-9]`, and nothing is replaced. If the pattern is a regex, use the 2-argument form. Zoho documents the third parameter as "escape the regular expression".
+
+Regex flavour is Java-like: `\d`, `\s`, `[^...]`, `(?i)`. Escape backslashes in the Deluge string literal as normal.
+
+## 5. Calling Zoho — `zoho.crm.*` and friends
+
+```deluge
+rec   = zoho.crm.getRecordById("Deals", dealId);
+recs  = zoho.crm.getRecords("Leads", 1, 200);                  // page 1, up to 200 per call
+found = zoho.crm.searchRecords("Contacts", "(Email:equals:" + email + ")");
+                                                              // criteria: (Field:operator:value), joined with and/or in outer parens
+kids  = zoho.crm.getRelatedRecords("Notes", "Leads", leadId);
+resp  = zoho.crm.createRecord("Leads", leadMap);
+resp  = zoho.crm.updateRecord("Leads", leadId, changesMap);
+resp  = zoho.crm.upsert("License_Transactions", txnMap);       // matches on the module's unique field(s)
+value = zoho.crm.getOrgVariable("StoreBaseURL");               // org variables = config, not hard-coded secrets
+```
+
+Zoho now documents a versioned form for CRM — `zoho.crm.v8.getRecordById(...)`, `zoho.crm.v8.upsert(...)`, `zoho.crm.v8.bulkCreate(...)` etc. (Part 2 lists them with full signatures). The unversioned names above still work on existing orgs; prefer the `v8` form in new code.
+
+**Write calls do not throw when Zoho rejects the record (verified).** They return a Map and carry the failure inside it. Always check:
+```deluge
+resp = zoho.crm.upsert("Leads", data);
+if(resp == null || resp.get("status") == "error")
+{
+	info "upsert rejected: " + resp;
+	result.put("error", "upsert rejected: " + resp);
+	return result;
+}
+newId = resp.get("id");
+```
+Treating a non-null response as success is the single most common way a Deluge job reports "0 failures" while writing nothing.
+
+Search results are a List of Maps; an empty search returns an empty List (check `.size() > 0`, then `.get(0)`). Lookup fields inside a record are Maps: `rec.get("Account_Name").get("id")`.
+
+**Field API names, not labels.** Use the exact `api_name` (`Last_Name`, `Deal_Name`, `Closing_Date`), and picklist values exactly as configured. A wrong field name is not an error on write — it is silently dropped. Get the real names from the org, never from memory: `zone crm pull` writes `metadata/.zcrm/.store/field_map.json` (`{ Module: { Field: type } }`).
+
+**Every integration task and every `invokeurl` counts against a daily external-call limit** (2,000 per user per day for each), and each execution inside a loop counts once per iteration.
+
+## 6. HTTP — `invokeurl`
+
+```deluge
+payload = Map();
+payload.put("query", "acme");
+
+response = invokeurl
+[
+	url        : "https://api.example.com/search"
+	type       : POST
+	parameters : payload.toString()                 // JSON body: send the Map as text
+	headers    : {"Content-Type": "application/json", "Authorization": "Bearer " + token}
+	connection : "my_connection"                    // OR a saved OAuth connection instead of headers
+	detailed   : true
+];
+```
+
+- `type` is `GET`, `POST`, `PUT`, `DELETE` or `PATCH` — bare, no quotes.
+- `parameters` as a **Map** sends a form body; as a **String** sends the text as-is (use `map.toString()` for JSON). `body` sends a raw body; `files` uploads a file object.
+- Without `detailed`, the result is the parsed body: a Map or List when the response is JSON, otherwise a String. With `detailed:true` you get `responseCode`, `responseText`, `responseHeaders`.
+- `response-format` and `response-decoding` control how the body is parsed; the response is capped at **5 MB**.
+- **Check the result before merging it into anything.** An error page or a null merged with `putAll` corrupts the record and surfaces later as a confusing write failure:
+  ```deluge
+  if(response == null || !response.toString().startsWith("{")) { return errorMap("detail fetch failed"); }
+  ```
+- `connection:` (a connection created under Setup → Connections) is the right way to authenticate to Zoho's own APIs and to third parties. **Never paste an API key or secret into a script** — it ends up in every revision and every export. Use a connection or `zoho.crm.getOrgVariable("...")`.
+
+## 7. Dates
+
+```deluge
+d = zoho.currentdate;                                // today
+t = zoho.currenttime;                                // now
+s = t.toString("yyyy-MM-dd'T'HH:mm:ss");             // Java-style patterns; quote literals with ' '
+d2 = '2026-09-01'.toDate();
+dt = '2026-09-01 14:30:00'.toDateTime();
+d.addDay(7);  d.subDay(30);  d.addMonth(1);  d.addYear(1);  d.addBusinessDay(3);
+d.getDay();  d.getMonth();  d.getYear();  d.getDayOfWeek();
+d.daysBetween(d2);  d.monthsBetween(d2);
+d.toString("dd-MMM-yyyy", "Asia/Dubai");             // time zone as the second argument
+```
+Parsing user-supplied dates fails often; wrap `toDate()`/`toDateTime()` in `try`/`catch` and skip the field rather than abort the run.
+
+## 8. Errors, logging, and what "success" means
+
+```deluge
+try
+{
+	risky = something.toMap();
+}
+catch (e)
+{
+	info "parse failed: " + e;         // e carries the message (and data, for a thrown Map)
+}
+```
+
+- `info <value>;` is the only logging. It shows in the function's execution log. Log outcomes and identifiers; **do not log phone numbers, emails or tokens** — logs are retained and readable by every admin.
+- A `try`/`catch` catches runtime exceptions (bad `.get(9)`, failed parse) and anything you `throw`. It does **not** catch a rejected write — see §5.
+- **Calling another standalone function** returns whatever that function returned, but if its declared return type is `string`, a Map comes back as a **string** and must be `.toMap()`'d; declare `map` as the return type when you mean a Map, or parse defensively:
+  ```deluge
+  raw = standalone.TransactionUpsert(txnJson);
+  resultMap = Map();
+  try { resultMap = raw.toMap(); } catch (e) { }
+  if(resultMap.get("error") != null) { failed = failed + 1; }
+  ```
+- Design a return contract and keep it. The convention that works: success → Map with the useful ids; failure → Map with `"error"`; something-worth-knowing → `"warning"`. Callers check `error` explicitly.
+- **Execution limits (documented):** 5,000 statements executed per function (a loop body counts once per iteration), 75 function calls per function, 500 `sendmail` per user per day (15 MB attachments), 2,000 webhook and 2,000 integration tasks per user per day.
+
+## 9. Functions exposed over REST
+
+A standalone function can be invoked over HTTP once REST access is enabled in the console (Setup → Functions → REST API — it cannot be enabled through the API). Such a function takes one parameter, `crmAPIRequest`, a Map of the whole request:
+
+```deluge
+string standalone.Lookup(String crmAPIRequest)
+{
+	req    = crmAPIRequest.toMap();
+	body   = req.get("body");             // POST body (Map when JSON)
+	params = req.get("params");           // query string
+	q      = body.get("query");
+
+	resp = Map();
+	resp.put("status_code", 200);
+	resp.put("body", {"ok": true, "query": q});
+	return {"crmAPIResponse": resp};
+}
+```
+Return `{"crmAPIResponse": {...}}` with `status_code` and `body`. Anything else is wrapped as text.
+
+## 10. Known runtime traps (each cost real time)
+
+| You wrote | What happens | Do instead |
+|---|---|---|
+| `getJSONType(x)` | COMPILATION_ERROR — function does not exist **(verified)** | `x.toString().startsWith("[")` / `"{"` |
+| `s.replaceAll("[^0-9]", "", true)` | pattern treated as literal; nothing replaced **(verified)** | 2-argument form for regex |
+| `if(resp != null) { ...success... }` after `upsert` | rejected writes counted as success **(verified)** | check `resp.get("status") == "error"` |
+| `// header` above the signature, pushed via API | rejected as a bad package declaration **(verified)** | comments inside the body only |
+| grep -i missing for function usage | live callers reported dead **(verified)** | names are case-insensitive |
+| `zoho.ai.parsePhoneNumber(n, country)` result used as-is | returns a populated object flagged `"invalid"` for a bad number **(verified)** | reject when `international_format` is `"invalid"` |
+| `m.containsKey("k")` | no such method | `m.containKey("k")` |
+| `l.get(l.size())` | index out of range (0-based) | `l.get(l.size() - 1)` |
+| `{}` for an empty collection | ambiguous | `Map()` or `List()` |
+| `id == "123"` with a Long id | false | `id.toString() == "123"` or `id == 123.toLong()` |
+| `"2026-09-01".toDate()` | date literals want single quotes | `'2026-09-01'.toDate()` |
+| Secrets in string literals | leaked in every revision/export | `zoho.crm.getOrgVariable`, or a Connection |
+| `while(...)` / `switch` | do not exist | list loops, `else if` |
+
+## 11. Workflow with the `zone` CLI
+
+```bash
+zone crm pull -o ./metadata                 # real field API names, picklists, layouts, every function
+zone crm fn pull my_function -o ./functions # fetch a .ds
+zone crm fmt ./functions/my_function.ds -w  # canonical formatting
+zone crm fn push ./functions/my_function.ds # save (strips a leading // header, surfaces COMPILATION_ERROR line numbers that match your file)
+zone crm fn test my_function --args '{"leadId":"123"}'   # run a script on the live org
+zone crm fn rest-api my_function            # is it REST-exposed? invoke URL
+zone crm fn invoke my_function --args '{"id":"1"}'       # call the SAVED function over REST
+```
+
+**Before pushing:**
+1. Every code path returns a value (non-`void`) and every statement ends with `;`.
+2. No `while`, `switch`, `getJSONType`, `containsKey`.
+3. Every `zoho.crm.*` write checks `status == "error"`.
+4. Every `invokeurl` result is checked before use.
+5. No secrets or PII in literals or `info` lines.
+6. Field names came from the org's metadata, not from memory.
+7. Stays inside the limits: 5,000 executed statements, 75 calls, 2,000 external calls/day.
+8. Test with `zone crm fn test` on one record before wiring it to a workflow or schedule.