Script

Script adalah endpoint backend deklaratif yang dipanggil frontend melalui HTTP. Alih-alih menulis kode server, Anda mendeklarasikan "apa yang harus dilakukan" sebagai JSON, dan mesin WEEGLOO menjalankannya untuk Anda. Tujuannya adalah menggantikan pipa backend khas yang menopang frontend (sebuah BFF, Backend-for-Frontend) hanya dengan satu Script saja: autentikasi, pemeriksaan kondisi (guard), CRUD berantai, panggilan API eksternal, dan pengolahan nilai.

Kumpulan dokumen ini adalah acuan (reference) untuk sintaks Script. Rincian tiap bagian sintaks dibahas terpisah di Dokumen dalam grup ini di bawah.

Script disusun dan dijalankan di CMA (dengan identitas Weegloo User). Dengan identitas anggota yang telah mendaftar ke produk (ServiceUser), Anda juga dapat menggunakannya dengan cara yang sama di ACMA. Script API hanya ada pada kedua API manajemen ini (CMA, ACMA), dan tidak ada pada API pengiriman baca-saja (CDA, ACDA).

Model mental

• Satu Script adalah satu endpoint HTTP. Metode panggilan (method) menentukan Script mana yang dijalankan.
• Body-nya adalah array statements. Elemen-elemennya dijalankan secara berurutan, dari atas ke bawah. Ini sama seperti body fungsi dalam pemrograman biasa.
• Ini deklarasi, bukan kode. Anda tidak menyisipkan kode sembarang (FaaS), melainkan menyusun tipe statement yang sudah ditentukan. Ini dirancang lebih untuk dihasilkan oleh agen AI melalui MCP daripada untuk ditulis dengan tangan oleh manusia.
• Nilai mengalir melalui templat JSON Pointer. Anda mereferensikan hasil langkah sebelumnya, payload masukan, atau variabel dengan { /pointer } lalu meneruskannya ke langkah berikutnya. Bila butuh kondisi atau perhitungan, gunakan operator JsonLogic. Aturan lengkapnya dibahas di Ekspresi nilai.

Struktur tingkat atas (ScriptDefinition)

Satu Script didefinisikan dengan struktur ScriptDefinition berikut.

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. Metode HTTP yang dicocokkan saat pemanggilan (wajib)
  "payloadSchema": { /* ... */ }, // (opsional) JSON Schema. Jika ada, memvalidasi payload permintaan sebelum eksekusi
  "executionMode": "Sync",        // "Sync" | "Async" (wajib)
  "statements": [ /* Statement[]. Dijalankan dari atas ke bawah (wajib, minimal 1) */ ]
}

payload hanya menerima JSON. Body panggilan diakses melalui context root /payload ({ /payload/... }). Header HTTP permintaan panggilan direferensikan melalui root /headers ({ /headers/... }, dengan kunci huruf kecil). Seluruh context root dibahas di Ekspresi nilai.

Permintaan dan respons

Pada akhirnya, Script mengembalikan nilai statement Return kepada pemanggil. Bentuk respons (atau hasil polling Async) adalah sebagai berikut.

{
  "requestId": "…",     // Pengenal eksekusi (untuk Async, polling hasil dengan id ini)
  "durationMs": 1234,   // Durasi eksekusi (ms)
  "statusCode": 200,    // statusCode dari Return yang tercapai (default 200)
  "return": <value>     // Hanya saat Return.isError bernilai false. Jika nilainya null, ""
  // "error": <value>   // Hanya saat Return.isError bernilai true (dalam hal ini "return" tidak ada). Jika nilainya null, ""
}

• return dan error tidak pernah muncul bersamaan. isError dari statement Return menentukan yang mana.
• Jika Script berakhir tanpa mencapai statement Return, return dan error sama-sama tidak ada, dan statusCode bernilai default (200).
• Jika sebuah nilai adalah null, field tersebut ditampilkan sebagai string kosong "".

Anda mengendalikan body respons dan kode status dengan value, isError, dan statusCode milik Return. Selengkapnya dibahas di Return pada Katalog Statement.

Mode eksekusi: Sync dan Async

• Jika ada I/O eksternal, hanya Async yang diizinkan. Jika ada satu saja statement yang melakukan operasi jaringan seperti panggilan eksternal Http (ExternalIo) atau ingest file Media (MediaIngest, dari url atau base64), maka executionMode wajib Async, dan mencoba menyimpannya sebagai Sync akan ditolak saat penyimpanan. Ini agar thread permintaan tidak terhambat oleh latensi eksternal.
• Ini hanya perbedaan tempat eksekusi berlangsung; apa pun pilihannya, hasilnya adalah nilai Return.

Aturan tentang bagaimana suatu kemampuan menentukan mode, beserta batasan yang berlaku, dibahas di Semantik eksekusi, batasan, dan keamanan.

Contoh minimal

Membuat sebuah Content postingan dari judul dan isi pada payload permintaan, langsung mempublikasikannya, lalu mengembalikan sys.id yang dibuat.

{
  "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 membuat Content dan mengikat hasilnya ke nama post.
• Return mengembalikan { "id": <id Content baru> } dengan 201.
• Alasan nilai fields sebuah Content berupa peta locale ({ "en-US": ... }) dibahas di Peta locale pada Ekspresi nilai.

Skenario yang lebih beragam bisa Anda temukan di Cookbook.

Dokumen dalam grup ini

• Ekspresi nilai: Membahas referensi { /pointer }, literal, operasi dan kondisi JsonLogic, context root, serta peta locale. Ini adalah inti dari sintaks.
• Katalog Statement: Membahas field dan hasil dari 17 jenis statement (CRUD dan pembacaan resource, Http, SetVar, If, Loop, Parallel, Try, Return).
• Semantik eksekusi, batasan, dan keamanan: Membahas urutan eksekusi, guard, kompensasi, penguncian optimistik, error, batasan statis dan batas paket, serta model keamanan.
• Cookbook: Membahas contoh-contoh lengkap seperti upsert, guard kredit, proxy LLM, paginasi, eksekusi paralel, dan saga pembayaran.
• Resource dan endpoint Script: Membahas struktur sys dari resource Script serta spesifikasi endpoint HTTP untuk penyusunan dan eksekusi (/execute).

Jika ini pertama kalinya, kami menyarankan membaca dari halaman ini dengan urutan Ekspresi nilai, lalu Katalog Statement. Cookbook juga layak Anda telusuri secara menyeluruh.