Script

Script एक घोषणात्मक बैकएंड एंडपॉइंट है, जिसे फ्रंटएंड HTTP के ज़रिए कॉल करता है. सर्वर कोड लिखे बिना आप "क्या करना है" को JSON में घोषित करते हैं, और WEEGLOO इंजन उसे आपकी जगह चला देता है. प्रमाणीकरण, कंडीशन जाँच (guard), चेन किया गया CRUD, बाहरी API कॉल और मानों को आकार देने जैसी, फ्रंटएंड को सहारा देने वाली सामान्य बैकएंड प्लंबिंग (BFF, Backend-for-Frontend) को एक ही Script से बदल देना ही इसका लक्ष्य है.

यह दस्तावेज़ समूह Script सिंटैक्स का आधिकारिक संदर्भ (reference) है. अलग-अलग सिंटैक्स का विवरण नीचे इस समूह के दस्तावेज़ में बाँटकर दिया गया है.

Script को CMA पर लिखा और चलाया जाता है (Weegloo User पहचान के साथ). उत्पाद में साइन अप कर चुके सदस्य (ServiceUser) की पहचान से इसे ACMA पर भी इसी तरह इस्तेमाल किया जा सकता है. Script API सिर्फ़ इन दो प्रबंधन API (CMA, ACMA) पर मौजूद है; केवल-पढ़ने वाली डिलीवरी API (CDA, ACDA) पर नहीं है.

मेंटल मॉडल

• एक Script एक HTTP एंडपॉइंट होता है. कॉल मेथड (method) से यह मैच किया जाता है कि कौन-सा Script चलेगा.
• बॉडी एक statements ऐरे है. ये ऊपर से नीचे क्रम से चलते हैं. यह सामान्य प्रोग्रामिंग में किसी फ़ंक्शन की बॉडी जैसा ही है.
• यह कोड नहीं, घोषणा है. आप कोई भी मनमाना कोड (FaaS) नहीं डालते, बल्कि पहले से तय statement प्रकारों को जोड़ते हैं. इसे किसी व्यक्ति द्वारा हाथ से लिखने के बजाय AI एजेंट द्वारा MCP के ज़रिए जेनरेट किए जाने के हिसाब से डिज़ाइन किया गया है.
• मान JSON Pointer टेम्पलेट के ज़रिए बहते हैं. पिछले चरण का परिणाम, इनपुट payload या वेरिएबल को { /pointer } से रेफ़र करके अगले चरण में भेजा जाता है. जब कोई कंडीशन या गणना चाहिए, तब JsonLogic ऑपरेटर इस्तेमाल किए जाते हैं. विस्तृत नियम मान एक्सप्रेशन में दिए गए हैं.

शीर्ष-स्तरीय संरचना (ScriptDefinition)

एक Script को निम्नलिखित ScriptDefinition संरचना से परिभाषित किया जाता है.

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. कॉल के समय मैच होने वाली HTTP मेथड (आवश्यक)
  "payloadSchema": { /* ... */ }, // (वैकल्पिक) JSON Schema. मौजूद होने पर, एक्ज़ीक्यूशन से पहले रिक्वेस्ट payload को वैलिडेट करता है
  "executionMode": "Sync",        // "Sync" | "Async" (आवश्यक)
  "statements": [ /* Statement[]. ऊपर से नीचे एक्ज़ीक्यूट (आवश्यक, कम से कम 1) */ ]
}

payload सिर्फ़ JSON स्वीकार करता है. कॉल body को /payload कॉन्टेक्स्ट रूट के ज़रिए एक्सेस किया जाता है ({ /payload/... }). कॉल के रिक्वेस्ट HTTP हेडर को /headers रूट से रेफ़र किया जाता है ({ /headers/... }, keys लोअरकेस में). पूरे कॉन्टेक्स्ट रूट सेट के बारे में मान एक्सप्रेशन में बताया गया है.

रिक्वेस्ट और रिस्पॉन्स

अंततः Script अपने Return स्टेटमेंट का मान कॉलर को लौटाता है. रिस्पॉन्स (या Async पोलिंग परिणाम) का स्वरूप इस प्रकार है.

{
  "requestId": "…",     // एक्ज़ीक्यूशन पहचानकर्ता (Async के लिए, इस id से परिणाम पोल करें)
  "durationMs": 1234,   // एक्ज़ीक्यूशन समय (ms)
  "statusCode": 200,    // पहुँचे गए Return का statusCode (डिफ़ॉल्ट 200)
  "return": <value>     // सिर्फ़ तब जब Return.isError false हो. मान null होने पर ""
  // "error": <value>   // सिर्फ़ तब जब Return.isError true हो (इस स्थिति में "return" नहीं होता). मान null होने पर ""
}

• return और error एक साथ कभी नहीं आते. Return स्टेटमेंट का isError तय करता है कि यह कौन-सा है.
• अगर Script किसी Return स्टेटमेंट तक पहुँचे बिना समाप्त हो जाए, तो return और error दोनों ही नहीं होते और statusCode डिफ़ॉल्ट (200) रहता है.
• अगर कोई मान null हो, तो वह फ़ील्ड खाली स्ट्रिंग "" के रूप में निकलता है.

Return के value, isError और statusCode से आप रिस्पॉन्स बॉडी और स्टेटस कोड को नियंत्रित करते हैं. विस्तार के लिए Statement कैटलॉग में Return देखें.

एक्ज़ीक्यूशन मोड: Sync और Async

• बाहरी I/O होने पर सिर्फ़ Async की अनुमति है. अगर कोई भी statement Http बाहरी कॉल (ExternalIo) या Media फ़ाइल इनजेस्ट (MediaIngest, url या base64 से) जैसा कोई नेटवर्क ऑपरेशन करता है, तो executionMode अनिवार्य रूप से Async होना चाहिए, और उसे Sync के रूप में सहेजने की कोशिश सहेजते समय अस्वीकार कर दी जाती है. यह इसलिए है ताकि रिक्वेस्ट थ्रेड बाहरी देरी से ब्लॉक न हो.
• यह सिर्फ़ इस बात का फ़र्क है कि एक्ज़ीक्यूशन कहाँ होता है; किसी भी स्थिति में परिणाम Return मान ही होता है.

किसी क्षमता के आधार पर मोड तय होने के नियम और उनकी सीमाएँ एक्ज़ीक्यूशन सिमैंटिक्स, प्रतिबंध और सुरक्षा में दी गई हैं.

न्यूनतम उदाहरण

यह रिक्वेस्ट payload के शीर्षक और बॉडी से एक पोस्ट Content बनाता है, उसे तुरंत publish करता है, और फिर बनाई गई sys.id लौटाता है.

{
  "method": "Post",
  "executionMode": "Sync",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

• ResourceCreate Content बनाता है और परिणाम को post नाम से बाइंड करता है.
• Return { "id": <नई Content id> } को 201 के साथ लौटाता है.
• Content के fields मान locale map ({ "en-US": ... }) क्यों होते हैं, यह मान एक्सप्रेशन में Locale map में बताया गया है.

और भी विविध परिदृश्य कुकबुक में मिलेंगे.

इस समूह के दस्तावेज़

• मान एक्सप्रेशन: { /pointer } रेफ़रेंस, लिटरल, JsonLogic ऑपरेशन और कंडीशन, कॉन्टेक्स्ट रूट, और Locale map को कवर करता है. यह सिंटैक्स का केंद्र है.
• Statement कैटलॉग: 17 प्रकार के statements (रिसोर्स CRUD और रीड, Http, SetVar, If, Loop, Parallel, Try, Return) के फ़ील्ड और परिणाम को कवर करता है.
• एक्ज़ीक्यूशन सिमैंटिक्स, प्रतिबंध और सुरक्षा: एक्ज़ीक्यूशन क्रम, guard, कॉम्पेंसेशन, ऑप्टिमिस्टिक लॉकिंग, एरर, स्टैटिक प्रतिबंध और प्लान सीमाएँ, तथा सुरक्षा मॉडल को कवर करता है.
• कुकबुक: upsert, क्रेडिट guard, LLM प्रॉक्सी, पेजिनेशन, समानांतर एक्ज़ीक्यूशन, भुगतान सागा जैसे पूर्ण उदाहरणों को कवर करता है.
• Script रिसोर्स और एंडपॉइंट: Script रिसोर्स की sys संरचना और लेखन तथा एक्ज़ीक्यूशन (/execute) के HTTP एंडपॉइंट के स्पेसिफ़िकेशन को कवर करता है.

अगर यह आपकी पहली बार है, तो इस पेज से शुरू करके मान एक्सप्रेशन, फिर Statement कैटलॉग के क्रम में पढ़ने की सलाह है. कुकबुक को पूरा एक बार सरसरी तौर पर देखना भी अच्छा रहेगा.