@stechquick/studio-cli 4.2.0-2 → 4.2.0-3

package/dist/studio-cli/kits/miniapp-app-kit/.ai-kit/miniapp-kit/reference/host-functions.json

@@ -0,0 +1,109 @@
+{
+  "$comment": "Functions the SuperApp shell exposes to a MiniApp, and the rules for each. Grep one block by funcName; do not read this file whole. Full return shapes and default mocks are NOT repeated here — they live in host-functions.container, the template for the app's container file. Every function is available to every MiniApp — isSuccess !== true is a runtime error, not a missing permission.",
+  "version": 2,
+  "api": {
+    "signature": "(<any>quick.container).<funcName>(): Promise<{ isSuccess: boolean, retVal: any }>",
+    "cast": "Always call through (<any>quick.container). studio buildQjson cannot see the container file and types quick.container as {}, so a bare quick.container.<funcName>() fails validation with \"Property '<funcName>' does not exist on type '{}'\". The cast changes only the type check.",
+    "declaration": "Every function a page calls must be declared in the app's single *.container file. If the workspace has none, create it from host-functions.container — see guides/host-functions.md.",
+    "resultPath": "res.retVal.funcRetVal.<Field>",
+    "resultPathNote": "Every function that returns data wraps its payload in retVal.funcRetVal. stopMiniApp and OpenMap return nothing worth reading.",
+    "errors": "A call can reject, or resolve with isSuccess !== true. Handle both — try/catch plus an isSuccess check — and show the user an error.",
+    "handlerLanguage": "Event handlers are always TypeScript — set \"HL\":\"TS\". The cast is TypeScript syntax.",
+    "multipleCalls": "Await each call before starting the next. Never fire them in parallel.",
+    "environment": "In Studio, a quick.container call returns the mockBody declared for that function in the app's container file. The user owns those mocks and edits them in Studio.",
+    "legacy": "quick.Quick.host.trigger(functionName, params) is the deprecated form of the same calls, with the same payload shape. Existing pages and the platform payment component still use it — leave them unless the user asks to migrate. It does not respond in Studio."
+  },
+  "functions": [
+    {
+      "funcName": "GetIdentity",
+      "purpose": "Name, surname and national identification number of the signed-in user.",
+      "result": "Read res.retVal.funcRetVal.Name, .Surname and .TCKN (all strings)."
+    },
+    {
+      "funcName": "GetMailAddress",
+      "purpose": "E-mail address of the signed-in user.",
+      "result": "Read res.retVal.funcRetVal.Email (string)."
+    },
+    {
+      "funcName": "GetPhoneNumber",
+      "purpose": "Phone number of the signed-in user.",
+      "result": "Read res.retVal.funcRetVal.PhoneNumber (string)."
+    },
+    {
+      "funcName": "GetCustomerNumber",
+      "purpose": "Retail customer number of the signed-in user.",
+      "result": "Read res.retVal.funcRetVal.CustomerNumber (string)."
+    },
+    {
+      "funcName": "GetCommercialCustomerNumber",
+      "purpose": "Commercial customer number of the signed-in user.",
+      "result": "Read res.retVal.funcRetVal.CommercialCustomerNumber (string)."
+    },
+    {
+      "funcName": "GetToken",
+      "purpose": "Access token for İşPay MiniApps.",
+      "result": "Read res.retVal.funcRetVal.AccessToken (string).",
+      "notes": "A credential. Never log it (quick.EM.trace included), render it, or keep it in the store beyond the call that needs it."
+    },
+    {
+      "funcName": "GetQRData",
+      "purpose": "QR data provided by the host.",
+      "result": "Read res.retVal.funcRetVal.qrData (string)."
+    },
+    {
+      "funcName": "GetClientIp",
+      "purpose": "IP address of the client device.",
+      "result": "Read res.retVal.funcRetVal.ClientIp (string)."
+    },
+    {
+      "funcName": "GetCardList",
+      "purpose": "Credit cards available to the signed-in user — the same CreditCardList payload GetCards returns.",
+      "result": "The payment component reads res.retVal.funcRetVal.CreditCardList (array of card objects) and .RandNo (string).",
+      "calledBy": "platform payment component",
+      "notes": "Declared in the container file so its mock exists. Do not call it by hand — card selection and payment belong to the platform payment component. See guides/platform-payments.md."
+    },
+    {
+      "funcName": "stopMiniApp",
+      "purpose": "Closes the MiniApp and returns the user to the host app. Wire it to the appbar's exit button and to any control that leaves the MiniApp.",
+      "usage": "(<any>quick.container).stopMiniApp();",
+      "notes": "Fire-and-forget — the MiniApp is torn down, so there is no result worth reading and nothing after the call runs. Fire analytics events and store writes before it. Do not use quick.Quick.back() to leave the MiniApp; back navigates within it."
+    },
+    {
+      "funcName": "OpenMap",
+      "purpose": "Opens the device's map application at a location.",
+      "notes": "Takes latitude and longitude, both numbers. Legacy form: quick.Quick.host.trigger(\"OpenMap\", { latitude: lat, longitude: lng }). How quick.container passes parameters is not confirmed yet — ask before wiring it. Fire-and-forget; there is no payload to read back."
+    },
+    {
+      "funcName": "GetCards",
+      "purpose": "Credit cards available to the signed-in user.",
+      "calledBy": "platform payment component",
+      "inContainerFile": false,
+      "parameters": [],
+      "returnValue": {
+        "objectContent": "{ isSuccess: boolean, retVal: { funcRetVal: { CreditCardList: object[] } } }",
+        "returnValueType": "object"
+      },
+      "notes": "The platform payment component calls this itself through quick.Quick.host.trigger(\"GetCards\", {}) and raises cardsCreated / noAvailableCard to your page. Do not call it by hand — see guides/platform-payments.md."
+    },
+    {
+      "funcName": "makeSecurePayment",
+      "purpose": "Executes a card payment through the host.",
+      "calledBy": "platform payment component",
+      "inContainerFile": false,
+      "parameters": [
+        { "name": "miniAppId", "type": "string" },
+        { "name": "cardNumber", "type": "string" },
+        { "name": "total", "type": "number" },
+        { "name": "expMonth", "type": "string" },
+        { "name": "expYear", "type": "string" },
+        { "name": "cv2", "type": "string" },
+        { "name": "orderId", "type": "string" }
+      ],
+      "returnValue": {
+        "objectContent": "{ isSuccess: boolean, retVal: { succeeded: boolean, errors: any, data: { request: { orderId: string } } } }",
+        "returnValueType": "object"
+      },
+      "notes": "BREAKS THE PATTERN — no funcRetVal wrapper; read retVal.succeeded, retVal.errors, retVal.data.request.orderId directly. The platform payment component calls this itself through quick.Quick.host.trigger and raises callParent / paymentFail to your page. Do not call it by hand — see guides/platform-payments.md."
+    }
+  ]
+}