@xano/sdk 1.0.15 → 1.0.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +33 -37
- package/dist/.build-fingerprint +1 -1
- package/dist/{agent-file-refresh-ZRGNOA6Q.js → agent-file-refresh-DBHTEFYM.js} +12 -12
- package/dist/{agent-skill-command-DV26SDA2.js → agent-skill-command-LHNTU7MH.js} +74 -73
- package/dist/{answer-shape-AVZSKBR6.js → answer-shape-ZRQS7ZC4.js} +5 -5
- package/dist/{backend-dir-NTMXWE5R.js → backend-dir-AXR43HNV.js} +11 -11
- package/dist/{backend-slot-DZAUHLTS.js → backend-slot-7BATLL3X.js} +4 -4
- package/dist/bin.js +64 -63
- package/dist/{branch-IJTBZZFO.js → branch-SJKKUCMZ.js} +9 -9
- package/dist/branch-commands-KGR52SZU.js +80 -0
- package/dist/bundle.d.ts +2 -2
- package/dist/bundle.js +15 -69
- package/dist/{capture-GW5KNKMB.js → capture-RYBJE25P.js} +5 -5
- package/dist/{chunk-66ZU2CD5.js → chunk-23GEFHRX.js} +236 -17
- package/dist/{chunk-3H7R4ISR.js → chunk-2DUYJR5N.js} +2 -2
- package/dist/{chunk-MFWF2NZJ.js → chunk-2H5BQRHF.js} +2 -2
- package/dist/{chunk-O44MJTLR.js → chunk-35SI4GBM.js} +3 -3
- package/dist/{chunk-ZYECXDVV.js → chunk-3ZV23FVR.js} +5 -5
- package/dist/{chunk-N72XNQNJ.js → chunk-47XIVDJ6.js} +14 -14
- package/dist/{chunk-ICK36EGF.js → chunk-4EVDCSEY.js} +2 -2
- package/dist/{chunk-AXMUYBWQ.js → chunk-4XGZ325S.js} +3 -3
- package/dist/{chunk-P7GKTV7N.js → chunk-4XYXUK5H.js} +75 -32
- package/dist/{chunk-AE5CRAKS.js → chunk-4ZBXS7YN.js} +8 -8
- package/dist/{chunk-JWASCOHO.js → chunk-52QAENY6.js} +14 -14
- package/dist/{chunk-2LF734YB.js → chunk-54CJ74BH.js} +4 -4
- package/dist/{chunk-TT6LN55R.js → chunk-57PGTPT3.js} +8 -8
- package/dist/{chunk-IKXXTRMN.js → chunk-64UVVLDT.js} +4 -4
- package/dist/{chunk-EQXHUWUO.js → chunk-6FCAFWD5.js} +2 -2
- package/dist/{chunk-4MX5LMPQ.js → chunk-6ODQ5GDZ.js} +2 -2
- package/dist/{chunk-G4WRZU5T.js → chunk-74YCPI4G.js} +7 -7
- package/dist/{chunk-Y5XAPLZS.js → chunk-7UQZ7C4W.js} +4 -4
- package/dist/{chunk-CJDPSCMX.js → chunk-7ZVQIKNL.js} +3 -3
- package/dist/{chunk-RVAEPPRH.js → chunk-AICWDCLJ.js} +2 -2
- package/dist/{chunk-WS4BA75E.js → chunk-AJBOGO5U.js} +4 -4
- package/dist/{chunk-FOBVJ2UR.js → chunk-AJQFUJEQ.js} +8 -8
- package/dist/{chunk-DH6O5NQU.js → chunk-C7AYP4H6.js} +29 -20
- package/dist/{chunk-SXMZNSQ6.js → chunk-DJMGDCVX.js} +8 -8
- package/dist/{chunk-K6SWZ6H4.js → chunk-DLD4FVRP.js} +54 -54
- package/dist/{chunk-Q7DGTQ5G.js → chunk-E34VGSCI.js} +2 -1
- package/dist/{chunk-YR3MNGWZ.js → chunk-E5M5P23K.js} +8 -8
- package/dist/{chunk-HJZUI2ZU.js → chunk-EAZTRU75.js} +2 -2
- package/dist/{chunk-V7WCTXEH.js → chunk-EINZSVEU.js} +5 -5
- package/dist/{chunk-KMKUH2IO.js → chunk-EPB6FAR5.js} +5 -5
- package/dist/chunk-EUAU4QKI.js +67 -0
- package/dist/{chunk-IDOVZLPK.js → chunk-EXJ4Q5F6.js} +2 -2
- package/dist/{chunk-FKQX6KU7.js → chunk-F3JK5RIY.js} +2 -2
- package/dist/{chunk-W2QFR3ZJ.js → chunk-FIOC7RSU.js} +2 -2
- package/dist/{chunk-YEH5OIPF.js → chunk-FMXPV5JI.js} +39 -11
- package/dist/{chunk-GVHWIDEJ.js → chunk-FRJB3NTE.js} +10 -5
- package/dist/{chunk-VIRFG3WG.js → chunk-FTFAPKCW.js} +23 -7
- package/dist/{chunk-LL6ED5IB.js → chunk-FTS42N37.js} +2 -2
- package/dist/{chunk-MIS6F4HM.js → chunk-G2XSDIYS.js} +4 -4
- package/dist/{chunk-ZY55DO5P.js → chunk-G6BEJ3NA.js} +2 -2
- package/dist/{chunk-RYWNNJK5.js → chunk-GA6HTO3O.js} +2 -2
- package/dist/{chunk-JIKGT7DO.js → chunk-GE3JV5SI.js} +1 -1
- package/dist/{chunk-GCINMMFL.js → chunk-GJZMKMWO.js} +2 -2
- package/dist/{chunk-VXHXSGPU.js → chunk-GRZ62LLU.js} +8 -8
- package/dist/{chunk-6X73VFCX.js → chunk-GT7PZCTK.js} +2 -2
- package/dist/{chunk-SH4RY6QX.js → chunk-HXPQXCOZ.js} +1536 -413
- package/dist/{chunk-ECQXASG3.js → chunk-IFHFJR5O.js} +2 -2
- package/dist/{chunk-7ZQ73AHJ.js → chunk-IOWNQEMW.js} +31 -31
- package/dist/{chunk-YCKKL5PD.js → chunk-ISIZFK5Q.js} +53 -47
- package/dist/{chunk-HCNIB3EC.js → chunk-IUJDUFT7.js} +4 -4
- package/dist/{chunk-74OPNM2Z.js → chunk-JHAZK4RY.js} +3 -3
- package/dist/{chunk-OZWAITII.js → chunk-KGHJ74HF.js} +6 -6
- package/dist/{chunk-XLP4CNSF.js → chunk-L2O5KG5Q.js} +6 -6
- package/dist/{chunk-NNI5R6V6.js → chunk-L3Q2QYIQ.js} +72 -72
- package/dist/{chunk-UNFQN3TT.js → chunk-LLBEPJBO.js} +3 -3
- package/dist/{chunk-VUWR5YLE.js → chunk-LWBGPPI5.js} +13 -13
- package/dist/{chunk-RBTZEHXF.js → chunk-MBSHONP3.js} +3 -3
- package/dist/{chunk-GKQTXUOW.js → chunk-MOVRSULZ.js} +2 -2
- package/dist/{chunk-QAEBBTYR.js → chunk-MSYMEP7Y.js} +7 -7
- package/dist/{chunk-Y453TW6J.js → chunk-NCERS5QH.js} +2 -2
- package/dist/{chunk-HXFLHA5K.js → chunk-NH5Z2NOD.js} +2 -2
- package/dist/{chunk-T3HNISBN.js → chunk-NJVY3GAX.js} +3 -3
- package/dist/{chunk-ZF2CBXT5.js → chunk-NQPPUNWP.js} +3 -3
- package/dist/{chunk-5SKWGCAJ.js → chunk-O7Z3LF44.js} +5 -5
- package/dist/{chunk-ASQX477B.js → chunk-OLXYZQR7.js} +7 -7
- package/dist/{chunk-5SJQAJLF.js → chunk-OQNYZ2OM.js} +3 -3
- package/dist/{chunk-DBDTQR23.js → chunk-OTQF4B37.js} +4 -4
- package/dist/{chunk-GBSHHNSD.js → chunk-PRSNMSVG.js} +3 -3
- package/dist/{chunk-DGYXCIBV.js → chunk-Q6AKSLD2.js} +2 -2
- package/dist/{chunk-WXKSB2N3.js → chunk-Q7KXMIR3.js} +3 -3
- package/dist/{chunk-B6AFJVG4.js → chunk-QCVH32T2.js} +5 -5
- package/dist/{chunk-7FIMUFBP.js → chunk-QDPY7RN3.js} +3 -3
- package/dist/{chunk-MGG4CHO4.js → chunk-QIT2GGNB.js} +3 -3
- package/dist/{chunk-QW7NGUYW.js → chunk-QSJH5AFU.js} +244 -173
- package/dist/{chunk-3GZMP7II.js → chunk-R7DS2TRZ.js} +38 -22
- package/dist/{chunk-BEKEOXNG.js → chunk-RGPHFHJU.js} +2 -2
- package/dist/{chunk-5FJ4M4HB.js → chunk-RHH6SCB4.js} +17 -32
- package/dist/{chunk-M7O3T7IM.js → chunk-RIT3WBBX.js} +4 -4
- package/dist/{chunk-45K2QZBR.js → chunk-RKNCISPM.js} +3 -3
- package/dist/{chunk-NPYYDTXS.js → chunk-RKTVXFBV.js} +5 -5
- package/dist/{chunk-AXNX4NWN.js → chunk-RLQX6LHW.js} +37 -37
- package/dist/{chunk-FIERONKM.js → chunk-ROWYW3JF.js} +2 -2
- package/dist/{chunk-LSJ3SQEU.js → chunk-RVWWNNZQ.js} +4 -4
- package/dist/{chunk-A2N2C2WD.js → chunk-S7MVI4W7.js} +7 -7
- package/dist/{chunk-4MIV244X.js → chunk-SGEOXJIH.js} +9 -2
- package/dist/{chunk-QRMKQYCB.js → chunk-SINL5WMI.js} +2 -2
- package/dist/{chunk-Z6N5N4MN.js → chunk-SIW2HT2H.js} +21 -5
- package/dist/{chunk-IEDQT4Z3.js → chunk-SOAZIMWL.js} +12 -12
- package/dist/{chunk-R3GPRNBT.js → chunk-SVQMDVND.js} +87 -16
- package/dist/{chunk-45ZUMF4E.js → chunk-TPUAXIPR.js} +2 -2
- package/dist/{chunk-SL55XKVL.js → chunk-TXU34ELY.js} +25 -25
- package/dist/{chunk-GDJCWQIK.js → chunk-U4UAWGIT.js} +12 -8
- package/dist/{chunk-76SBT7KS.js → chunk-U56HK2RG.js} +7 -5
- package/dist/{chunk-RXNMZM6H.js → chunk-UDW2KAVF.js} +6 -6
- package/dist/{chunk-NDV6CBR7.js → chunk-UH5VQGNR.js} +2 -2
- package/dist/{chunk-75QC66XI.js → chunk-V2MIBJZU.js} +2 -2
- package/dist/{chunk-ZDVVIJPU.js → chunk-VAQPQXOI.js} +4 -4
- package/dist/{chunk-XPSDDTUZ.js → chunk-VCFRALU7.js} +3 -3
- package/dist/{chunk-5KJBWIDZ.js → chunk-VQDVEHDB.js} +2 -2
- package/dist/{chunk-6EFXPTHT.js → chunk-WAP5362D.js} +5 -5
- package/dist/{chunk-XY4OBD26.js → chunk-WGKKDGSA.js} +4 -4
- package/dist/{chunk-TXFOQZUQ.js → chunk-WVVUE7LU.js} +14 -7
- package/dist/{chunk-JAYHFXWH.js → chunk-WXQ7BHVQ.js} +7 -7
- package/dist/{chunk-7REDHC4N.js → chunk-X5NF3ZXW.js} +69 -14
- package/dist/{chunk-5W7S2SCA.js → chunk-XAE4NIZ2.js} +4 -4
- package/dist/{chunk-SPLRKCFV.js → chunk-XDGLYIB2.js} +2 -2
- package/dist/{chunk-7AKH4QDJ.js → chunk-XKMZYU5B.js} +96 -65
- package/dist/{chunk-UVHSMANV.js → chunk-Y3RH35KM.js} +47 -47
- package/dist/{chunk-GIQIMWTK.js → chunk-YHT7TDSH.js} +14 -14
- package/dist/{chunk-FXZEZAV2.js → chunk-YJXJOMXW.js} +3 -3
- package/dist/{chunk-ZPJXWMHK.js → chunk-YPLHVRMS.js} +4 -4
- package/dist/{chunk-WS2X5BB2.js → chunk-YYBBJPCL.js} +5 -5
- package/dist/{chunk-ZOHEHIFS.js → chunk-YYDM4DNP.js} +2 -2
- package/dist/{chunk-ZC6H2ERE.js → chunk-ZF4LCHCT.js} +5 -5
- package/dist/{chunk-GRXX2TOJ.js → chunk-ZHFSIQ6E.js} +2 -2
- package/dist/{chunk-SHHXLI2K.js → chunk-ZJQFKBX7.js} +7 -7
- package/dist/{chunk-ZRXDPCMN.js → chunk-ZYZ7GRX3.js} +2 -2
- package/dist/{chunk-CJGLAQRD.js → chunk-ZZC5VSLP.js} +4 -4
- package/dist/cli.d.ts +3 -3
- package/dist/cli.js +62 -61
- package/dist/codegen-command-NAY6YAOD.js +183 -0
- package/dist/codegen.d.ts +3 -3
- package/dist/codegen.js +5 -5
- package/dist/{commands-5ILSWDSV.js → commands-Z2QZOORB.js} +3 -3
- package/dist/{completion-UNKBVVDT.js → completion-LFXXNQGR.js} +3 -3
- package/dist/{config-NTOASFCA.js → config-7GGINOFY.js} +4 -4
- package/dist/{deploy-command-BYAZZF37.js → deploy-command-PBM3S4ZL.js} +69 -68
- package/dist/{deploy-source-QCPZWNJO.js → deploy-source-JW7DAN75.js} +32 -32
- package/dist/{dev-env-sync-6MHK3UHC.js → dev-env-sync-FHJTFH3V.js} +63 -62
- package/dist/{diagnostics-FNVNRYMB.js → diagnostics-T3RN3372.js} +2 -2
- package/dist/{display-name-hint-MYXCCAOP.js → display-name-hint-5GLJGPQ6.js} +11 -11
- package/dist/{emit-YLt3GfsZ.d.ts → emit-t-gDE1BL.d.ts} +181 -93
- package/dist/env-example-refresh-HHEGMFNH.js +136 -0
- package/dist/{env-pull-command-KUIEKBTM.js → env-pull-command-FFPNRVWD.js} +52 -52
- package/dist/{env-target-Y77RLRS5.js → env-target-XHVRZXHX.js} +14 -14
- package/dist/{env-var-command-BZWJD75C.js → env-var-command-DJS62YRR.js} +41 -41
- package/dist/{ephemeral-VLPRDNEJ.js → ephemeral-2DXWP3VK.js} +9 -9
- package/dist/{ephemeral-command-SYKDPALW.js → ephemeral-command-VLQIQ5TS.js} +52 -52
- package/dist/{ephemeral-state-RUOU2GFS.js → ephemeral-state-56XEDUJW.js} +12 -12
- package/dist/{generate-command-CSQDQZSW.js → generate-command-PSDIIOTU.js} +89 -88
- package/dist/{gitignore-OQGYM7DO.js → gitignore-PMJ6MFNA.js} +15 -15
- package/dist/{guards-JUYBDLZY.js → guards-YICHJKX3.js} +51 -15
- package/dist/{impersonate-command-HSFCZBV6.js → impersonate-command-IKV4KUYA.js} +37 -37
- package/dist/{import-T4ZTOTBT.js → import-VJQGIS33.js} +5 -5
- package/dist/index.d.ts +552 -117
- package/dist/index.js +29 -28
- package/dist/init-command-LEQIE6GC.js +143 -0
- package/dist/{init-modules-BL2SR5RK.js → init-modules-G47Q7ABV.js} +8 -8
- package/dist/{init-web-DYE2FEXL.js → init-web-25QJ4JWB.js} +3 -3
- package/dist/internal.d.ts +55 -8
- package/dist/internal.js +692 -503
- package/dist/{io-PGTCBSIQ.js → io-47TFRYDB.js} +6 -6
- package/dist/{keep-data-merge-SHF75FC7.js → keep-data-merge-XCPCX7BZ.js} +38 -38
- package/dist/{lambda-config-reconcile-VOBVZPWS.js → lambda-config-reconcile-CC5QIP6E.js} +3 -3
- package/dist/{landed-F7PCHGCK.js → landed-VIUFHLCJ.js} +5 -5
- package/dist/{landing-record-7EOLEKH3.js → landing-record-JQ7HZDGI.js} +22 -22
- package/dist/{live-diff-M2OLXKM6.js → live-diff-KJ2TWWWT.js} +14 -14
- package/dist/{local-engine-choice-TOC3UYZZ.js → local-engine-choice-DFAMYOIF.js} +35 -35
- package/dist/{local-engine-command-6KSRDZBR.js → local-engine-command-5RP2J5QZ.js} +40 -40
- package/dist/{local-engine-deploy-4N4NFZ4T.js → local-engine-deploy-XAEDT55W.js} +12 -12
- package/dist/{local-engine-lookup-AQTUGSBT.js → local-engine-lookup-WBYTY2JE.js} +2 -2
- package/dist/{local-engine-mcp-bridge-AMYRH4SY.js → local-engine-mcp-bridge-3H5OXBWQ.js} +5 -5
- package/dist/{local-engine-mcp-command-XTP3EATV.js → local-engine-mcp-command-JSYVVZKK.js} +42 -42
- package/dist/{local-engine-process-OD5OSWDG.js → local-engine-process-35B2KQED.js} +7 -7
- package/dist/{local-engine-update-check-G3YCBXRE.js → local-engine-update-check-VXJZSIJU.js} +5 -5
- package/dist/{lock-HDCHD2ON.js → lock-JBKTDEDO.js} +4 -4
- package/dist/{lock-commands-437P6BHY.js → lock-commands-7VO6YWOV.js} +67 -66
- package/dist/{login-command-BNRDAVFV.js → login-command-WTZUBCW6.js} +27 -27
- package/dist/{logout-command-FCGCHB7Y.js → logout-command-5BJUNK3C.js} +17 -17
- package/dist/{loop-WOAEXMTC.js → loop-HILLODVH.js} +15 -15
- package/dist/{marketplace-command-SUBJZPJV.js → marketplace-command-NMOH4XOV.js} +30 -30
- package/dist/{marketplace-resolve-JR4BBJ6K.js → marketplace-resolve-63QWMQZU.js} +6 -6
- package/dist/{meta-client-AYJS3RQ3.js → meta-client-MRAMWUKV.js} +15 -15
- package/dist/{module-manifest-63I5GRK4.js → module-manifest-NWJWAQLQ.js} +4 -4
- package/dist/node.d.ts +8 -8
- package/dist/node.js +71 -70
- package/dist/{operation-outcome-ORQPVJKB.js → operation-outcome-WK7UW6PJ.js} +24 -24
- package/dist/{output-target-KNHHNDM3.js → output-target-5PYRCCK4.js} +16 -16
- package/dist/{plan-disclosure-4DUFRGCP.js → plan-disclosure-6MG4YYJV.js} +28 -28
- package/dist/{plugin-contributions-YYEP7IWH.js → plugin-contributions-DD6R6RL6.js} +5 -5
- package/dist/{plugin-prompt-GKCQKNYI.js → plugin-prompt-UX2TT5NS.js} +5 -5
- package/dist/{plugin-questions-P7MA3TYI.js → plugin-questions-WE2F4ZC4.js} +4 -4
- package/dist/{preflight-command-32GFVKSN.js → preflight-command-3BX2WW3S.js} +75 -74
- package/dist/{profile-command-U2XTKOMF.js → profile-command-GSUX3UMB.js} +28 -28
- package/dist/{profile-pointer-JJ7K5O2R.js → profile-pointer-RCPHVTJV.js} +4 -4
- package/dist/{project-dependency-X3KCWBK5.js → project-dependency-TPVV3YIX.js} +7 -7
- package/dist/{project-sdk-YHJZRCNB.js → project-sdk-DKZBK5H5.js} +4 -4
- package/dist/promote-command-3LQTXWCD.js +149 -0
- package/dist/{prompt-QNMJIWNI.js → prompt-OYQHQWKI.js} +4 -4
- package/dist/{publish-command-5ZVZ6IYT.js → publish-command-3BQCV4NE.js} +72 -71
- package/dist/pull-command-B7OVWTZD.js +171 -0
- package/dist/{pull-superseded-6HADGGC5.js → pull-superseded-3SSM3JFT.js} +4 -4
- package/dist/{raw-where-gWGr-E4t.d.ts → raw-where-CinW0keO.d.ts} +32 -4
- package/dist/release-command-XSDICMJE.js +153 -0
- package/dist/{release-ns-command-LDN5DOKQ.js → release-ns-command-EVAHK4CU.js} +96 -95
- package/dist/{retry-command-LFZYEVRU.js → retry-command-WP4ZI6CJ.js} +8 -8
- package/dist/{routes-manifest-BMAOL6WN.js → routes-manifest-N73THJB3.js} +16 -16
- package/dist/routes-manifest-file-LDUDIVFJ.js +41 -0
- package/dist/scaffold.js +2 -2
- package/dist/{secrets-file-7QM3ORGX.js → secrets-file-7XWR7HW3.js} +15 -15
- package/dist/{secrets-fill-command-OZ537VOD.js → secrets-fill-command-NKCGC75L.js} +66 -65
- package/dist/{seed-ATGBOEJP.js → seed-YKTZDS2Q.js} +13 -13
- package/dist/{source-resolve-QYSWA3QR.js → source-resolve-CQGDFQQC.js} +22 -22
- package/dist/{static-host-MO4VDHL7.js → static-host-3HPZKVKK.js} +5 -5
- package/dist/{status-command-IEB4K7ME.js → status-command-TBMQ3GJP.js} +38 -38
- package/dist/{store-AJX4MC7Y.js → store-B63BQV6R.js} +6 -6
- package/dist/{store-DspGMsFY.d.ts → store-in7gSpMS.d.ts} +185 -11
- package/dist/sync-baseline-GRS33AB5.js +38 -0
- package/dist/{sync-contributions-DLV5JZUK.js → sync-contributions-RKPLZPPO.js} +9 -9
- package/dist/{sync-record-NE62ERA3.js → sync-record-AWFCSS4D.js} +15 -15
- package/dist/{table-TFD4ZQXA.js → table-ONGT3JGE.js} +12 -12
- package/dist/{tables-command-IMCVPUFY.js → tables-command-UYQ277TJ.js} +41 -41
- package/dist/{tenant-IIYECNWO.js → tenant-IXIW3FOI.js} +10 -10
- package/dist/{tenant-command-77KG76MU.js → tenant-command-7LWZUK2V.js} +104 -103
- package/dist/{test-command-NSPU4RUO.js → test-command-7KTT5EAF.js} +56 -45
- package/dist/{tests-JWQRHFCT.js → tests-N4MMBABH.js} +6 -6
- package/dist/{token-BDHD7GU3.js → token-3TCMW2AP.js} +13 -13
- package/dist/{toolchain-hooks-QHJRDCRW.js → toolchain-hooks-IJWV3ZQS.js} +18 -18
- package/dist/{toolchain-modules-LY7BMYG6.js → toolchain-modules-PBVBCPQJ.js} +5 -5
- package/dist/{toolchain-peers-FQJBTKEB.js → toolchain-peers-EMOYN4U7.js} +8 -8
- package/dist/{tracked-backend-BIR7YJCE.js → tracked-backend-YDUUQZQF.js} +34 -34
- package/dist/update-check-C6KDFGMT.js +141 -0
- package/dist/{upgrade-command-YCADQCIA.js → upgrade-command-ZSBTSMBR.js} +68 -67
- package/dist/{whoami-command-IZCTUPM4.js → whoami-command-L6ERHR5K.js} +16 -16
- package/dist/{workspace-TK52V7WO.js → workspace-5DPSDM4A.js} +5 -5
- package/dist/{workspace-binding-3UT6PP4B.js → workspace-binding-MVOWGNYW.js} +15 -15
- package/dist/{workspace-command-46OCB6XT.js → workspace-command-PKQ5TDR7.js} +100 -99
- package/dist/{workspace-env-PVPOWFNZ.js → workspace-env-UZJZUIYV.js} +18 -12
- package/dist/{workspace-export-PUEXKZNS.js → workspace-export-3KMWNZDD.js} +5 -5
- package/dist/{writable-LMMG4AFZ.js → writable-X7BCN7XE.js} +4 -4
- package/dist/xano-YB6Y2IJS.js +44 -0
- package/dist/{xanosdk-import-XXJT365U.js → xanosdk-import-HHMQDK2I.js} +10 -10
- package/dist/{xanosdk-project-CJKRLQ6U.js → xanosdk-project-CKEUNJU4.js} +13 -13
- package/dist/{xdo-D4OwfF2J.d.ts → xdo-DNGZGO1j.d.ts} +50 -12
- package/guides/authoring.md +1 -0
- package/guides/codes.md +33 -3
- package/guides/coverage.md +2 -2
- package/guides/object-kinds.md +1 -1
- package/guides/typed-frontend.md +9 -0
- package/llms/client.md +54 -36
- package/llms/errors.md +26 -6
- package/llms/fields.md +53 -30
- package/llms/filters.md +55 -46
- package/llms/kinds-agent-mcp.md +10 -9
- package/llms/kinds-core.md +19 -15
- package/llms/kinds-knowledge.md +4 -4
- package/llms/kinds-realtime.md +25 -23
- package/llms/lambda.md +42 -30
- package/llms/legacy.md +6 -7
- package/llms/lock.md +21 -17
- package/llms/object-kinds.md +9 -11
- package/llms/statements-calls.md +41 -20
- package/llms/statements-catalog.md +32 -25
- package/llms/statements-data.md +35 -25
- package/llms/statements-runtime.md +28 -18
- package/llms/tests.md +20 -7
- package/llms/toolchain.md +12 -9
- package/llms/triggers.md +14 -18
- package/llms/values.md +16 -9
- package/llms-full.txt +643 -503
- package/llms.txt +120 -137
- package/manifest.json +147 -95
- package/package.json +1 -1
- package/skills/xano-backend/SKILL.md +10 -12
- package/types/lambda-globals.d.ts +6 -1
- package/dist/branch-commands-4PJEBNRK.js +0 -80
- package/dist/codegen-command-RDD4GL35.js +0 -182
- package/dist/env-example-refresh-MQWHY7ZS.js +0 -135
- package/dist/init-command-6Z7QNVDY.js +0 -142
- package/dist/promote-command-OO56IZBT.js +0 -148
- package/dist/pull-command-LT5PCEIW.js +0 -170
- package/dist/release-command-RBUOXIH7.js +0 -152
- package/dist/routes-manifest-file-MPOVKD6N.js +0 -41
- package/dist/sync-baseline-IB7MABZO.js +0 -38
- package/dist/update-check-JDARCXAX.js +0 -140
- package/dist/xano-EOUVXNQX.js +0 -43
package/dist/internal.js
CHANGED
|
@@ -7,8 +7,9 @@ import {
|
|
|
7
7
|
import {
|
|
8
8
|
CAPABILITIES,
|
|
9
9
|
STATEMENT_CAPABILITIES,
|
|
10
|
-
bundleCapabilities
|
|
11
|
-
|
|
10
|
+
bundleCapabilities,
|
|
11
|
+
capabilityReport
|
|
12
|
+
} from "./chunk-X5NF3ZXW.js";
|
|
12
13
|
import {
|
|
13
14
|
AGENT_SIGNUP_URL
|
|
14
15
|
} from "./chunk-VYJYDMY6.js";
|
|
@@ -22,8 +23,8 @@ import {
|
|
|
22
23
|
selectorValues,
|
|
23
24
|
sourceSpellings,
|
|
24
25
|
visibleFlags
|
|
25
|
-
} from "./chunk-
|
|
26
|
-
import "./chunk-
|
|
26
|
+
} from "./chunk-ZHFSIQ6E.js";
|
|
27
|
+
import "./chunk-Q7KXMIR3.js";
|
|
27
28
|
import {
|
|
28
29
|
GENERATED_STATEMENT_NAMES,
|
|
29
30
|
HEADER_DUPLICATES,
|
|
@@ -67,27 +68,26 @@ import {
|
|
|
67
68
|
toolKind,
|
|
68
69
|
triggerKind,
|
|
69
70
|
workflowTestKind
|
|
70
|
-
} from "./chunk-
|
|
71
|
+
} from "./chunk-4XYXUK5H.js";
|
|
71
72
|
import {
|
|
72
73
|
encodeQuery,
|
|
73
74
|
encodeResponse,
|
|
74
75
|
queryKind
|
|
75
|
-
} from "./chunk-
|
|
76
|
+
} from "./chunk-52QAENY6.js";
|
|
76
77
|
import {
|
|
77
78
|
encodeWorkspaceConfig,
|
|
78
79
|
workspaceKind
|
|
79
|
-
} from "./chunk-
|
|
80
|
-
import "./chunk-
|
|
80
|
+
} from "./chunk-RKTVXFBV.js";
|
|
81
|
+
import "./chunk-23GEFHRX.js";
|
|
81
82
|
import {
|
|
82
83
|
resolveAuthRef
|
|
83
|
-
} from "./chunk-
|
|
84
|
-
import "./chunk-76SBT7KS.js";
|
|
84
|
+
} from "./chunk-TPUAXIPR.js";
|
|
85
85
|
import {
|
|
86
86
|
PAYLOAD_ARRAY_KEYS,
|
|
87
87
|
buildBundle,
|
|
88
88
|
calcSignatureJson,
|
|
89
89
|
phpJsonEncode
|
|
90
|
-
} from "./chunk-
|
|
90
|
+
} from "./chunk-QDPY7RN3.js";
|
|
91
91
|
import {
|
|
92
92
|
DECODE_ONLY_STATEMENTS,
|
|
93
93
|
GENERATED_SPECS,
|
|
@@ -104,12 +104,13 @@ import {
|
|
|
104
104
|
isQueryExpressionFilter,
|
|
105
105
|
microserviceKind,
|
|
106
106
|
registerSpec
|
|
107
|
-
} from "./chunk-
|
|
108
|
-
import "./chunk-
|
|
107
|
+
} from "./chunk-HXPQXCOZ.js";
|
|
108
|
+
import "./chunk-4EVDCSEY.js";
|
|
109
109
|
import {
|
|
110
110
|
FILTER_NAMES,
|
|
111
111
|
FILTER_SPECS
|
|
112
|
-
} from "./chunk-
|
|
112
|
+
} from "./chunk-RLQX6LHW.js";
|
|
113
|
+
import "./chunk-U56HK2RG.js";
|
|
113
114
|
import {
|
|
114
115
|
buildMiddlewareBlock,
|
|
115
116
|
buildWorkspaceHistory,
|
|
@@ -117,7 +118,7 @@ import {
|
|
|
117
118
|
encodeHistory,
|
|
118
119
|
encodeMiddlewareEntry,
|
|
119
120
|
encodeMiddlewareList
|
|
120
|
-
} from "./chunk-
|
|
121
|
+
} from "./chunk-WAP5362D.js";
|
|
121
122
|
import "./chunk-GSGDWJB5.js";
|
|
122
123
|
import {
|
|
123
124
|
encodeColumn,
|
|
@@ -125,7 +126,7 @@ import {
|
|
|
125
126
|
encodeTable,
|
|
126
127
|
encodeView,
|
|
127
128
|
tableKind
|
|
128
|
-
} from "./chunk-
|
|
129
|
+
} from "./chunk-WVVUE7LU.js";
|
|
129
130
|
import "./chunk-ERVIASGL.js";
|
|
130
131
|
import {
|
|
131
132
|
encodeObject,
|
|
@@ -133,11 +134,11 @@ import {
|
|
|
133
134
|
isRegisteredKind,
|
|
134
135
|
registerKind,
|
|
135
136
|
registeredKinds
|
|
136
|
-
} from "./chunk-
|
|
137
|
+
} from "./chunk-JHAZK4RY.js";
|
|
137
138
|
import "./chunk-H2V3N23D.js";
|
|
138
139
|
import "./chunk-3JDU4VRL.js";
|
|
139
140
|
import "./chunk-WTPZRR4I.js";
|
|
140
|
-
import "./chunk-
|
|
141
|
+
import "./chunk-FMXPV5JI.js";
|
|
141
142
|
import "./chunk-UTI5G6OJ.js";
|
|
142
143
|
import {
|
|
143
144
|
LOCK_PAYLOAD_KEYS,
|
|
@@ -155,46 +156,47 @@ import {
|
|
|
155
156
|
resolvePayloadKey,
|
|
156
157
|
serializeLock,
|
|
157
158
|
validateLockModel
|
|
158
|
-
} from "./chunk-
|
|
159
|
+
} from "./chunk-VQDVEHDB.js";
|
|
159
160
|
import "./chunk-5ZSO4T2G.js";
|
|
160
161
|
import "./chunk-VQPDATQT.js";
|
|
161
162
|
import "./chunk-UDZX2ZL4.js";
|
|
162
|
-
import "./chunk-
|
|
163
|
+
import "./chunk-G6BEJ3NA.js";
|
|
163
164
|
import {
|
|
164
165
|
encodeStatement,
|
|
165
166
|
getStatementFactory,
|
|
166
167
|
isRegisteredStatement
|
|
167
|
-
} from "./chunk-
|
|
168
|
+
} from "./chunk-F3JK5RIY.js";
|
|
168
169
|
import "./chunk-TFFGOFVZ.js";
|
|
169
170
|
import {
|
|
170
171
|
IMPLEMENTED_STATEMENTS,
|
|
171
172
|
STATEMENT_SURFACES,
|
|
172
173
|
TOTAL_STATEMENTS,
|
|
173
174
|
sPathOf
|
|
174
|
-
} from "./chunk-
|
|
175
|
-
import "./chunk-
|
|
175
|
+
} from "./chunk-E34VGSCI.js";
|
|
176
|
+
import "./chunk-EAZTRU75.js";
|
|
176
177
|
import {
|
|
177
178
|
toNestedFields
|
|
178
|
-
} from "./chunk-
|
|
179
|
+
} from "./chunk-FTFAPKCW.js";
|
|
180
|
+
import "./chunk-EUAU4QKI.js";
|
|
179
181
|
import {
|
|
180
182
|
LAMBDA_BINDINGS,
|
|
181
183
|
LAMBDA_GLOBALS,
|
|
182
184
|
LAMBDA_MODULE_GLOBALS,
|
|
183
185
|
TAGS
|
|
184
|
-
} from "./chunk-
|
|
186
|
+
} from "./chunk-SIW2HT2H.js";
|
|
185
187
|
import "./chunk-VAX3UZOY.js";
|
|
186
188
|
import {
|
|
187
189
|
REFERENCEABLE_KINDS,
|
|
188
190
|
deriveGuid,
|
|
189
191
|
resolveRef
|
|
190
|
-
} from "./chunk-
|
|
192
|
+
} from "./chunk-FTS42N37.js";
|
|
191
193
|
import {
|
|
192
194
|
getLockedCanonical,
|
|
193
195
|
getLockedGuid,
|
|
194
196
|
isLockSeeded
|
|
195
197
|
} from "./chunk-4BW2SG2N.js";
|
|
196
|
-
import "./chunk-
|
|
197
|
-
import "./chunk-
|
|
198
|
+
import "./chunk-GE3JV5SI.js";
|
|
199
|
+
import "./chunk-SGEOXJIH.js";
|
|
198
200
|
import "./chunk-OHX6MIUZ.js";
|
|
199
201
|
import "./chunk-36JUQZVQ.js";
|
|
200
202
|
import "./chunk-PZ5AY32C.js";
|
|
@@ -280,7 +282,7 @@ var KIND_DESCRIPTORS = [
|
|
|
280
282
|
registerMethod: "registerTriggers",
|
|
281
283
|
subKinds: [
|
|
282
284
|
{ authorFactory: "tableTrigger", objType: "database", description: 'Fires when rows change on a bound table (insert/update/delete/truncate). The changed row is exposed as `t.new`/`t.old`, typed to the table when a `table()` handle is bound. Config-only (no response). `search` filters rows in the DATABASE, so it uses `col("NEW.x")`/`col("OLD.x")`, not `t`; invalid with `truncate`, and insert/delete cannot read the absent side.' },
|
|
283
|
-
{ authorFactory: "realtimeTrigger", objType: "workspace_realtime_channel", legacy: true, description: "the SUPERSEDED realtime trigger, against the workspace-global realtime layer \u2014 a different object from the current `channel`, despite the similar name. For a join hook use `realtimeChannelTrigger({ actions: { join: true } })`; for message handling use a `realtimeMessage()` handler, which is the
|
|
285
|
+
{ authorFactory: "realtimeTrigger", objType: "workspace_realtime_channel", legacy: true, description: "the SUPERSEDED realtime trigger, against the workspace-global realtime layer \u2014 a different object from the current `channel`, despite the similar name. For a join hook use `realtimeChannelTrigger({ actions: { join: true } })`; for message handling use a `realtimeMessage()` handler, which is the equivalent of its `message` action (a message is its own object, not a trigger action)." },
|
|
284
286
|
{ authorFactory: "realtimeServerTrigger", objType: "realtime_server", description: "Fires when a client connects to or disconnects from a realtime server; inspect the connecting client and its permissions via `t`. Bind with `realtimeServer`. Response-bearing." },
|
|
285
287
|
{ authorFactory: "realtimeChannelTrigger", objType: "channel", description: "Fires when a client joins or leaves a channel; inspect the addressed channel path and the client via `t`. Bind with a `realtimeChannel()` handle (a bare path is ambiguous across servers). Response-bearing." },
|
|
286
288
|
{ authorFactory: "mcpServerTrigger", objType: "toolset", description: "Fires when an MCP client connects to a bound MCP server; filter its tools/prompts/resources via `t`. Response-bearing." },
|
|
@@ -294,9 +296,9 @@ var KIND_DESCRIPTORS = [
|
|
|
294
296
|
{ kind: "resource", payloadKey: "resource", authorFactory: "resource", description: "An MCP resource: contents an MCP client reads by URI (a literal or a `{variable}` template), produced by a stack. Exposed by an `mcpServer`.", registerMethod: "registerResources" },
|
|
295
297
|
{ kind: "mcp_server", payloadKey: "toolset", authorFactory: "mcpServer", description: "An MCP server exposing tools, prompts and resources to external MCP clients.", registerMethod: "registerMcpServers" },
|
|
296
298
|
{ kind: "agent", payloadKey: "toolset", authorFactory: "agent", description: "An AI agent: an LLM configuration plus the tools it can call. Invoke it from any stack (query/function/task/tool/trigger) with `s.ai.agent.run` \u2014 no public endpoint; the result is a rich envelope whose completion text is at `.result`.", registerMethod: "registerAgents" },
|
|
297
|
-
{ kind: "task", payloadKey: "task", authorFactory: "task", description: "A scheduled background job
|
|
298
|
-
{ kind: "workflow_test", payloadKey: "workflow_test", authorFactory: "workflowTest", description:
|
|
299
|
-
{ kind: "middleware", payloadKey: "middleware", authorFactory: "middleware", description: "A reusable pre/post stack attached to a query
|
|
299
|
+
{ kind: "task", payloadKey: "task", authorFactory: "task", description: "A scheduled background job that runs a stack on a fixed interval (no cron).", registerMethod: "registerTasks" },
|
|
300
|
+
{ kind: "workflow_test", payloadKey: "workflow_test", authorFactory: "workflowTest", description: "An end-to-end test: a named stack with NO input and NO response that invokes other objects (`s.function.call`, `s.task.call`, `s.api.call`) and asserts on what they bind with `s.expect.*`. `datasource`: `llms/kinds-core.md`.", registerMethod: "registerWorkflowTests" },
|
|
301
|
+
{ kind: "middleware", payloadKey: "middleware", authorFactory: "middleware", description: "A reusable pre/post stack attached to a host (query, function, task, tool, API group, prompt, resource, realtime server/channel/message) to run before or after its own logic.", registerMethod: "registerMiddleware" },
|
|
300
302
|
{ kind: "addon", payloadKey: "addon", authorFactory: "addon", description: "A reusable read fragment that enriches a query result by joining related table data.", registerMethod: "registerAddons" },
|
|
301
303
|
{ kind: "realtime_server", payloadKey: "realtime_server", authorFactory: "realtimeServer", description: "A realtime (websocket) server: the canonical-addressed container that owns realtime channels. Off until `enabled: true`. Returns a handle with `getUrl(baseUrl)`/`getPath()` for the client's socket URL (`wss://<host>/ws/<canonical>`).", registerMethod: "registerRealtimeServers" },
|
|
302
304
|
{ kind: "channel", payloadKey: "channel", authorFactory: "realtimeChannel", description: "A realtime channel: a joinable path on a realtime server (`rooms/{room_id}`) with typed path params, join/publish policy, a client-visible conversation transcript, and delivery semantics. Owns message handlers. Returns a handle with `getChannel(params)` for the path a client joins.", registerMethod: "registerRealtimeChannels" },
|
|
@@ -306,7 +308,7 @@ var KIND_DESCRIPTORS = [
|
|
|
306
308
|
kind: "knowledge",
|
|
307
309
|
payloadKey: "knowledge",
|
|
308
310
|
authorFactory: "knowledge",
|
|
309
|
-
description: 'Markdown
|
|
311
|
+
description: 'Markdown for the AIs that build the backend (never an `agent()` run): an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a markdown FILE via `knowledgeFile("./x.md", import.meta.url)`; readers and `mode`: `llms/kinds-knowledge.md`.',
|
|
310
312
|
registerMethod: "registerKnowledge"
|
|
311
313
|
},
|
|
312
314
|
{ kind: "workspace", payloadKey: "workspace", authorFactory: "workspaceConfig", description: "Workspace-level configuration such as default middleware chains and request-history defaults per host kind.", registerMethod: "registerWorkspace" }
|
|
@@ -370,10 +372,12 @@ var NAMESPACE_NOTES = {
|
|
|
370
372
|
// lines down says it and a call omitting one does not compile. A warning that
|
|
371
373
|
// restates the type costs every reader of this section and changes nothing an
|
|
372
374
|
// agent writes.
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
375
|
+
array: '`by` is a `$this` expression, NOT a column name: `by: ref("$this.id")` (warns `stack.array-key-constant`). A predicate\'s `if` binds `$this` only; `$index` only in `partition` (warns `stack.array-index-unbound`).',
|
|
376
|
+
debug: '`s.debug.stop` is a REAL terminator: it ends the request with HTTP 200 `{ payload, statement: "Stop & Debug" }` (use `s.precondition` for an error status). Also exported flat as `die()`; there is no `s.die`.',
|
|
377
|
+
"(top-level)": '`s.throw` raises a named error `s.try_catch` catches; uncaught, it answers HTTP 200 `{ payload, statement: "Throw Error" }`, or its `status` (100\u2013599) when it sets one. Inside `s.db.transaction` a throw or failed precondition rolls it back.',
|
|
378
|
+
expect: 'Assertions. Use only in a `workflowTest({...})` stack, asserting on what a `.call` bound with `as`; elsewhere a failure aborts the request with HTTP 500 and the assertion\'s message (`to_equal failed - expected value 2 does not equal 1`). `to_throw` sees only an error carrying a MESSAGE, so an empty-message failure (`ERROR_CODE_ACCESS_DENIED`) reports "response is ok", and `to_be_within` EXCLUDES both bounds \u2014 `min < expr < max`.',
|
|
379
|
+
util: '`s.util.sleep`\'s `value` is in SECONDS; a decimal is allowed (`c.decimal(0.5)` = 500 ms); a negative value returns at once. `s.util.set_header`\'s `value` is a WHOLE `"Name: value"` line (there is no `name` field) \u2014 `c.text("X-Thing: on")`; a line with no colon sends an empty header, and a `Content-Type` line is IGNORED when the response is an object/JSON (it applies to a `c.text()` response). `s.util.template_engine`\'s `value` is a Twig template with `$var`/`$input` in scope (`"Hello {{ $var.who }}"`); output is NOT HTML-escaped, a missing var renders `""`, and a syntax error 500s.',
|
|
380
|
+
text: '`name` is an EXISTING variable the statement acts on. `trim`/`ltrim`/`rtrim`/`append`/`prepend` rewrite it IN PLACE and take no `as` (a non-text var is coerced, a null reads as `""`); on the trims `value` is a SET OF CHARACTERS to strip, not a substring (`"abcHIcba"` trimmed by `"abc"` \u2192 `"HI"`). The predicates (`contains`/`icontains`/`starts_with`/`istarts_with`/`ends_with`/`iends_with`) leave `name` unchanged and bind a boolean to `as` \u2014 without `as` they compute nothing (warns `stack.predicate-unbound`); an empty or omitted needle is `true`. An undeclared `name` 500s `Missing var entry`.',
|
|
377
381
|
workflow_test: "Run another workflow test from inside one. Pass the `workflowTest()` def handle, not a name."
|
|
378
382
|
};
|
|
379
383
|
var PUBLISHED_AUTHOR_FACTORIES = new Set(
|
|
@@ -397,28 +401,28 @@ function unmodeledObjectKinds() {
|
|
|
397
401
|
}
|
|
398
402
|
var VALUE_CONSTRUCTORS = [
|
|
399
403
|
{ name: "c.text", signature: "(s: string) => Value", description: 'String constant \u2192 tag "const".' },
|
|
400
|
-
{ name: "c.int", signature: "(n: number | bigint | string) => Value", description: 'Integer constant \u2192 tag "const:int". The engine stores integers as STRINGS and has no 53-bit limit, so pass a string or bigint for anything past Number.MAX_SAFE_INTEGER \u2014 c.int("9223372036854775807") is exact where the number literal for it is already \u2026808. A number that is not a safe integer THROWS rather than encoding the rounded value.
|
|
404
|
+
{ name: "c.int", signature: "(n: number | bigint | string) => Value", description: 'Integer constant \u2192 tag "const:int". The engine stores integers as STRINGS and has no 53-bit limit, so pass a string or bigint for anything past Number.MAX_SAFE_INTEGER \u2014 c.int("9223372036854775807") is exact where the number literal for it is already \u2026808. A number that is not a safe integer THROWS rather than encoding the rounded value. For the int64 clamp of an `f.int` column see `llms/fields.md`.' },
|
|
401
405
|
{ name: "c.decimal", signature: "(n: number | string) => Value", description: 'Decimal constant \u2192 tag "const:decimal". Pass a string only to keep a stored spelling a number cannot reproduce (c.decimal("10.00") keeps its trailing zeros).' },
|
|
402
|
-
{ name: "c.blank", signature: '(tag: "const:<type>") => Value', description:
|
|
406
|
+
{ name: "c.blank", signature: '(tag: "const:<type>") => Value', description: 'The editor\'s UNCONFIGURED value box (stored value ""), emitted by codegen for a pulled workspace \u2014 do not author it. NOT a zero or an empty collection: the engine reads "" and "0" differently, so c.blank("const:int") \u2260 c.int(0) and neither canonicalizes into the other. Valid for every constant tag except `const` and `const:obj`; their blanks are `c.text("")` and `c.obj(null)`.' },
|
|
403
407
|
{ name: "c.bool", signature: "(b: boolean) => Value", description: 'Boolean constant \u2192 tag "const:bool".' },
|
|
404
408
|
{ name: "c.null", signature: '(tag?: "const:null" | "const:obj") => Value', description: `Null constant, stored value "null". Bare c.null() is tag "const:null". c.null("const:obj") is the OBJECT-TYPED null the engine writes into a db.* statement's @meta slot \u2014 different stored bytes from c.obj(null), which is the blank object (value ""), though both evaluate to null. Codegen emits whichever spelling the workspace stored; do not swap one for the other.` },
|
|
405
|
-
{ name: "c.obj", signature: "(o?: Json | null) => Value", description: 'Object constant \u2192 tag "const:obj". A populated one stores an empty {} carrying one `set` filter per key
|
|
409
|
+
{ name: "c.obj", signature: "(o?: Json | null) => Value", description: 'Object constant \u2192 tag "const:obj". A populated one stores an empty {} carrying one `set` filter per key (a populated JSON string fails the request with ERROR_FATAL "Unable to decode."). \u26A0 A ZERO-BASED numeric key is an INDEX: c.obj({"0":"a"}) evaluates to the list ["a"] ({"2":\u2026} stays a key) \u2014 write c.array([...]) for a list, or prefix the keys ("k0") for an object; `export()` warns. c.obj() is the empty object {}. c.obj(null) is a pulled-workspace blank that evaluates to null; do not author it. Plain JSON literals only \u2014 a nested tagged value (inp/ref/auth/c.*) is rejected; for a computed object use a record of values.' },
|
|
406
410
|
{ name: "c.array", signature: "(a: Json[]) => Value", description: 'Array constant (JSON string) \u2192 tag "const:array". Plain JSON literals only \u2014 a nested tagged value is rejected, same as c.obj.' },
|
|
407
|
-
{ name: "c.expression", signature: "(source: string) => Value", description:
|
|
411
|
+
{ name: "c.expression", signature: "(source: string) => Value", description: 'Xano Expression Engine source, passed through VERBATIM \u2192 tag "const:expr2". The string IS the expression: c.expression(\'"Hi, " ~ $input.name\'), c.expression("$var.price * $var.qty"). \u26A0 Unvalidated: not parsed, typed (invisible to InferResponse), or renamed with refs; a typo surfaces at runtime. Use only for syntax typed surfaces lack (`~`, inline arithmetic, conditionals); otherwise prefer ref/inp/col, withFilters+fl.*, and obj() (which builds a checked expression). Not the expr() condition builder.' },
|
|
408
412
|
{ name: "c.expressionLegacy", signature: "(source: string) => Value", legacy: true, description: "the older `const:expr` expression form, emitted by codegen for workspaces that still hold one \u2014 author `c.expression` instead." },
|
|
409
|
-
{ name: "c.now", signature: "() => Value", description: "Current time as epoch-ms \u2014 the engine-native const:epochms constant
|
|
410
|
-
{ name: "obj", signature: "(fields: Record<string, Value | nested>) => ObjValue<typeof fields>", description: 'Dynamic object value \u2192 tag "const:expr2" (an object-literal expression string)
|
|
413
|
+
{ name: "c.now", signature: "() => Value", description: "Current time as epoch-ms \u2014 the engine-native const:epochms constant. Valid inline as a where/cmp operand." },
|
|
414
|
+
{ name: "obj", signature: "(fields: Record<string, Value | nested>) => ObjValue<typeof fields>", description: 'Dynamic object value \u2192 tag "const:expr2" (an object-literal expression string); the dynamic sibling of c.obj.\n - Members: inp/ref/auth values, env()/setting()/sys.*, c.now(), c.* constants, nested records, or arrays. Each may carry a FILTER CHAIN (withFilters + fl.*), rendered as the expression pipe `$var.row|get:"a.b"`. A null-safe ref(path, { safe: true }) works in a member directly. An inner obj() nests, same bytes as a raw record.\n - InferResponse (through a set_var too) resolves each member like a top-level response key: `response: { user: obj({ id: ref("row.id") }) }` derives `{ user: { id: Col } }`, and a raw nested object literal (`response: { user: { id: ref("row.id") } }`, auto-wrapped through this) derives the same.\n - A constant record or list has two spellings that both work and render identically: bare (`{ a: 1 }`, `[]`) or `c.obj(...)`/`c.array([...])` \u2014 prefer the bare form.\n - Rejected: the blank `c.obj(null)` is refused here (write c.null() or c.obj()); a filter ARGUMENT that carries its own chain or is a c.now(); a DISABLED filter; the output/response/trycatch/toolset/reg tags (a type error) \u2014 set_var those first and ref() them.' },
|
|
411
415
|
{ name: "ref", signature: "(name: string, opts?: { safe?: boolean }) => Value", description: 'Reference a stack variable \u2192 tag "var". Pass { safe: true } for null-safe nested access \u2014 a dotted ref("owner.user_id", { safe: true }) compiles through the get filter so it resolves to null instead of raising "Unable to locate var" when the base is null.' },
|
|
412
416
|
{
|
|
413
417
|
name: "inp",
|
|
414
418
|
signature: "(name: string) => Value",
|
|
415
|
-
description: 'Reference a function/endpoint input \u2192 tag "input". Resolves ONLY against the `input` block of the def it sits in \u2014 a value produced earlier in the stack is `ref("var.field")`, not `inp("field")`. A name that is not declared here deploys clean and fails at runtime with ERROR_FATAL "Unable to locate input: <name>" on every branch that reads it; `export()` warns, and `--strict` fails the build. Sending the name in the request does NOT rescue it
|
|
419
|
+
description: 'Reference a function/endpoint input \u2192 tag "input". Resolves ONLY against the `input` block of the def it sits in \u2014 a value produced earlier in the stack is `ref("var.field")`, not `inp("field")`. A name that is not declared here deploys clean and fails at runtime with ERROR_FATAL "Unable to locate input: <name>" on every branch that reads it; `export()` warns, and `--strict` fails the build. Sending the name in the request does NOT rescue it. A dotted path drills INTO a declared input (`inp("action.amount")` needs a declared `action`). \u26A0 An omitted/`null` optional input binds its EMPTY value (`""`/`0`/`false`/`[]`/`{}`; `""` for an enum), not null \u2014 only a type whose input defaults to `nullable: true` (vector, uuid, date, timestamp, file types; `llms/fields.md`) or one set `nullable: true` binds null. An omitted optional `input.geo.*` is not bound at all.'
|
|
416
420
|
},
|
|
417
421
|
{ name: "col", signature: "(name: string) => Value", description: 'Reference a table column \u2192 tag "col".' },
|
|
418
|
-
{ name: "auth", signature: "(path
|
|
422
|
+
{ name: "auth", signature: "(path: string) => Value", description: 'Reference the authenticated identity (auth("id") \u2192 $auth.id) \u2192 tag "auth". The PATH is required: the engine cannot read a bare auth, so auth("") throws. A token minted with extras exposes its claims at auth("extras.<key>") (auth("extras") is the whole map); a key absent from the token is a 500, not null.' },
|
|
419
423
|
{ name: "caught", signature: '(path?: "code" | "message" | "name" | "result") => Value', description: 'Read the caught error inside an s.try_catch CATCH arm \u2192 tag "trycatch". Valid ONLY there \u2014 it reads empty in the try/finally arms and outside the statement. Those four fields are all the engine binds; bare caught() is the whole error record. `code` is the error type: `ERROR_FATAL` for an engine error, a precondition\'s `error_type` (`ERROR_CODE_ACCESS_DENIED`, \u2026), `ERROR_CODE_THROWN_ERROR` for `s.throw`. `message` is the error text (a precondition\'s `error`, the engine\'s, an LLM provider\'s) EXCEPT for `s.throw`, where it is the fixed "Throw Error Statement" and your value is in `result`. `name` is `s.throw`\'s `name` (empty without one), else a label (`Exception`, `Access Denied`). \u26A0 An `s.ai.agent.run` provider failure binds `result: { name: "AI_APICallError", statusCode, isRetryable, data }`; branch a fallback on `withFilters(caught("result"), fl.get("statusCode"))` (401: the key was refused). The path takes only the four names; reach deeper with `fl.get`.' },
|
|
420
424
|
{ name: "toolset", signature: '(path: "token" | "params" | `params.${string}`) => Value', description: `Read a toolset-scoped binding inside a tool \u2192 tag "toolset". The engine binds two: token (the calling URL's token, null when absent) and params (its parameters, as an object); a dotted params.<key> reads one parameter out of that object. Bound only while a tool runs under its toolset \u2014 anywhere else it reads empty.` },
|
|
421
|
-
{ name: "env", signature: "(name: string) => Value", description: 'Read a WORKSPACE environment variable (set via workspaceConfig({ env }) or the dashboard) \u2192 `$env.NAME`. Compiles to tag "setting" with the plain name. env("remote_ip") reads a user var named remote_ip, not the caller IP \u2014 use sys.remoteIp()
|
|
425
|
+
{ name: "env", signature: "(name: string) => Value", description: 'Read a WORKSPACE environment variable (set via workspaceConfig({ env }) or the dashboard) \u2192 `$env.NAME`. Compiles to tag "setting" with the plain name.\n - Every value is TEXT (or null), edge whitespace trimmed on read: compare a flag against c.text("true"), not c.bool(true) (under loose `=`, FLAG=false equals c.bool(true)); a numeric use needs fl.to_int/fl.to_decimal.\n - env("remote_ip") reads a user var named remote_ip, not the caller IP \u2014 use sys.remoteIp().\n - A name that does not exist resolves to NULL rather than erroring, so a typo deploys clean: prefer typedEnv(config), which turns the names that config declares into properties (E.STRIPE_KEY). Once a config declares env, export() warns stack.env-undeclared on any env() or bare setting() outside the declared set.' },
|
|
422
426
|
{ name: "setting", signature: "(name: string) => Value", description: 'Reference a workspace setting \u2192 tag "setting". Built-in system vars are $-prefixed settings, e.g. setting("$remote_ip"); prefer the typed sys.* accessors.' },
|
|
423
427
|
{ name: "sys.*", signature: "() => Value", description: 'Built-in system / request-context variables \u2192 tag "setting" ($-prefixed). Accessors: remoteIp, requestMethod, requestUri, requestQueryString, httpHeaders, requestAuthToken, apiBaseUrl, datasource, branch, tenant, release, platform, isDebugger. In XanoScript these are $env.$remote_ip etc.; sys.remoteIp() is the public-endpoint rate-limit key (auth("id") is null there). sys.httpHeaders() keys arrive Title-Cased whatever the client sent: a client sending `x-sync-secret` is read as `X-Sync-Secret`, so `get:"x-sync-secret"` is null in production \u2014 read the Title-Cased name. s.api.call sends header names the same way, so a workflow test sees what a real request delivers.' },
|
|
424
428
|
{ name: "filter", signature: "(name: string, ...args: Value[]) => FilterXdo", description: "Build a filter-chain entry by raw name (escape hatch)." },
|
|
@@ -503,12 +507,44 @@ var STATEMENT_RESULTS = {
|
|
|
503
507
|
"security.check_password": {
|
|
504
508
|
name: "as",
|
|
505
509
|
type: "boolean",
|
|
506
|
-
note: "true when the plaintext matches the stored hash. \u26A0 input.password
|
|
510
|
+
note: "true when the plaintext matches the stored hash. \u26A0 not input.password \u2014 pass input.text() plaintext. \u26A0 THROWS 500 on a non-hash hash_password (Invalid password syntax.)"
|
|
511
|
+
},
|
|
512
|
+
// The decode/decrypt family THROWS on any failed verification rather than
|
|
513
|
+
// binding a falsy result — see the "Verifying a token" recipe in
|
|
514
|
+
// statements-calls.md. Doc-only notes (the decoded value's shape is unknown).
|
|
515
|
+
"security.jws_decode": {
|
|
516
|
+
name: "as",
|
|
517
|
+
type: "unknown",
|
|
518
|
+
note: "the decoded claims. \u26A0 THROWS 500 ERROR_FATAL on ANY failure (bad/garbage/expired/tampered token, wrong key/signature_algorithm, failed check_claims) \u2014 wrap in s.try_catch for a 401 (statements-calls.md)"
|
|
519
|
+
},
|
|
520
|
+
"security.jwe_decode": {
|
|
521
|
+
name: "as",
|
|
522
|
+
type: "unknown",
|
|
523
|
+
note: "the decoded claims. \u26A0 THROWS 500 ERROR_FATAL on ANY failure (bad/expired token, wrong key/algorithm, failed check_claims) \u2014 wrap in s.try_catch for a 401 (statements-calls.md)"
|
|
524
|
+
},
|
|
525
|
+
"security.decrypt": {
|
|
526
|
+
name: "as",
|
|
527
|
+
type: "unknown",
|
|
528
|
+
note: "the plaintext; takes encrypt's RAW bytes (fl.base64_decode() a stored base64 first). \u26A0 THROWS 500 on a wrong key/iv or non-ciphertext \u2014 wrap in s.try_catch"
|
|
529
|
+
},
|
|
530
|
+
// random_bytes/encrypt bind RAW BINARY: a JSON response or text column mangles
|
|
531
|
+
// it silently, and strlen counts characters not bytes. Encode before returning.
|
|
532
|
+
// (encrypt's raw-output note lives on `fl.encrypt` in filters.md — the catalog
|
|
533
|
+
// file is at its per-file token ceiling.)
|
|
534
|
+
"security.random_bytes": {
|
|
535
|
+
name: "as",
|
|
536
|
+
type: "string",
|
|
537
|
+
note: "RAW bytes (encrypt too) \u2014 fl.bin2hex()/fl.base64_encode() before returning or storing; raw binary mangles in a JSON/text response"
|
|
507
538
|
},
|
|
508
539
|
// redis/storage binds measured live: a get miss is `false`, not null.
|
|
509
540
|
"redis.get": { name: "as", type: "unknown", note: "FALSE (not null) on a miss" },
|
|
510
541
|
"redis.set": { name: "as", type: "boolean", note: "false when create_only meets an existing key (kept)" },
|
|
511
542
|
"storage.read_file_resource": { name: "as", type: "{ name; size; mime; data: <contents> }" },
|
|
543
|
+
"storage.create_attachment": {
|
|
544
|
+
name: "as",
|
|
545
|
+
type: "XanoFileRef",
|
|
546
|
+
note: "the stored file VALUE ({ access, path, name, type, size, mime, meta }) \u2014 write it into an f.attachment() cell. \u26A0 include_meta: true binds the file's internal RECORD instead (id, guid, sig, the storage BUCKET name): never store it as the file value or return it (warns storage.include-meta-returned). type (also optional) coerces the kind when it is image/video/audio"
|
|
547
|
+
},
|
|
512
548
|
// util.* — three whose UNITS, SHAPE or PHASE cost teams time, and none is
|
|
513
549
|
// guessable from the signature.
|
|
514
550
|
"util.geo_distance": {
|
|
@@ -519,22 +555,33 @@ var STATEMENT_RESULTS = {
|
|
|
519
555
|
"util.get_all_input": {
|
|
520
556
|
name: "as",
|
|
521
557
|
type: "unknown",
|
|
522
|
-
note:
|
|
558
|
+
note: 'inside an ATTACHED middleware it is a { type, vars } envelope whose vars DIFFERS BY PHASE: pre \u2192 the request inputs; post \u2192 { status, result }, NOT the request \u2014 read the request in post with s.util.get_raw_input. \u26A0 status is the STRING "ok" | "exception" (NOT an HTTP code), so store it in a text column, not f.int(); on "exception", result is the { code, message, payload } error and payload is set. See llms/kinds-core.md'
|
|
559
|
+
},
|
|
560
|
+
"util.get_env": {
|
|
561
|
+
name: "as",
|
|
562
|
+
type: "Record<string, string>",
|
|
563
|
+
note: "every workspace env var (declared AND dashboard) as one { NAME: value } object, each value TEXT \u2014 so this binds every SECRET; never return it to a client or write it to a row"
|
|
523
564
|
},
|
|
524
565
|
"util.ip_lookup": {
|
|
525
566
|
name: "as",
|
|
526
567
|
type: "IpLookupResult | null",
|
|
527
568
|
note: 'NESTED, not flat: { continent: {code,name}, country: {code,name}, region: {code,name}, city: {name}, postal: {code}, location: {latitude, longitude, tz, radius} } \u2014 ref("geo.location.latitude"), ref("geo.city.name"); radius is KILOMETRES. \u26A0 Every leaf is nullable (region/city/postal often null on a normal hit). `city` is an OBJECT: a bare ref("geo.city") into a text column fails and { safe: true } does NOT help; drill to city.name. The whole var is null for an unresolvable address'
|
|
528
569
|
},
|
|
570
|
+
// The s.text.* predicates bind a boolean to `as` (empty/omitted needle → true).
|
|
571
|
+
"text.contains": { name: "as", type: "boolean" },
|
|
572
|
+
"text.icontains": { name: "as", type: "boolean" },
|
|
573
|
+
"text.starts_with": { name: "as", type: "boolean" },
|
|
574
|
+
"text.istarts_with": { name: "as", type: "boolean" },
|
|
575
|
+
"text.ends_with": { name: "as", type: "boolean" },
|
|
576
|
+
"text.iends_with": { name: "as", type: "boolean" },
|
|
529
577
|
// Clearly-typed declarative ops.
|
|
530
578
|
"array.every": { name: "as", type: "boolean" },
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
"
|
|
535
|
-
"object.keys": { name: "as", type: "string[]" },
|
|
579
|
+
// The `s.math.*` family takes NO `as` — it MUTATES the variable named `name`
|
|
580
|
+
// in place (the engine's `output` flag on add/bitwise is an artifact; the
|
|
581
|
+
// factory has no `as` param). Semantics live in llms/statements-runtime.md.
|
|
582
|
+
"object.keys": { name: "as", type: "(string | number)[]", note: "an integer-like key comes back as a NUMBER (PHP coerces it), not a string" },
|
|
536
583
|
"object.values": { name: "as", type: "unknown[]" },
|
|
537
|
-
"object.entries": { name: "as", type: "
|
|
584
|
+
"object.entries": { name: "as", type: "{ key: string | number; value: unknown }[]", note: "each entry is a { key, value } OBJECT, NOT a [key, value] tuple; an integer-like key comes back as a number" }
|
|
538
585
|
};
|
|
539
586
|
var CONTEXT_FIELD_ENUMS = {
|
|
540
587
|
"mvp:precondition:error_type": PRECONDITION_ERROR_TYPES,
|
|
@@ -648,11 +695,12 @@ var FILTER_NOTES = {
|
|
|
648
695
|
array_find: "a MISS THROWS (`Unable to find element.`) rather than yielding null \u2014 use `array_has` to test first",
|
|
649
696
|
array_filter: "matches by EXAMPLE (an object of key/value pairs), not by code, and compares LOOSELY",
|
|
650
697
|
splice: "returns the REMOVED slice, not the remainder \u2014 [1,2,3,4] spliced at offset 1 length 2 yields [2,3]; with a `path` it removes in place and returns the whole value instead",
|
|
651
|
-
array_upmerge: "merges the node
|
|
698
|
+
array_upmerge: "merges the node into the FIRST matched element, and APPENDS it on a miss (an UPSERT, not update-all) \u2014 use `fl.map` to update every match; `array_replace` is first-match too but swaps the element whole and THROWS on a miss",
|
|
652
699
|
array_set: "sets a DOTTED path and returns the value; a non-object piped value is replaced by an empty one",
|
|
653
700
|
// A computed key is the grouping half of `index_by`: one pass over the rows,
|
|
654
701
|
// then a lookup per group, with no query per group.
|
|
655
|
-
get: '`path` may be a runtime value: after `fl.index_by("suite_id")`, `fl.get(ref("suite.id"))` returns that key\'s rows (null for a missing key)',
|
|
702
|
+
get: '`path` may be a runtime value: after `fl.index_by("suite_id")`, `fl.get(ref("suite.id"))` returns that key\'s rows (null for a missing key). \u26A0 the `default` applies only to a MISSING path \u2014 a key present with a `null` value stays `null`; chain `fl.first_notnull(default)` to cover both.',
|
|
703
|
+
has: "`false` for a missing key and for a key whose value is `null` (unlike `fl.get`'s default, which treats a present null as present)",
|
|
656
704
|
// "Direction" family — which operand is the subject is genuinely confusing.
|
|
657
705
|
contains: "piped value is the subject text; the arg is the substring searched for",
|
|
658
706
|
ends_with: "piped value is the subject text; the arg is the substring searched for",
|
|
@@ -662,25 +710,28 @@ var FILTER_NOTES = {
|
|
|
662
710
|
// its own note: the pattern is piped and the subject is the argument. Written
|
|
663
711
|
// the other way round it reads correctly, type-checks, and answers false for
|
|
664
712
|
// every input, so the note has to state the order and the symptom.
|
|
665
|
-
regex_test: 'piped value is the PATTERN (build it with `c.regex(...)`); the arg is the subject \u2014 the REVERSE of `contains`/`starts_with`. Swapped
|
|
713
|
+
regex_test: 'piped value is the PATTERN (build it with `c.regex(...)`); the arg is the subject \u2014 the REVERSE of `contains`/`starts_with`. Swapped args \u2192 always false, no error. Write `withFilters(c.regex("^a+$"), fl.regex_test(inp("s")))` (or name the arg: `fl.regex_test({ subject: inp("s") })`). A pattern found in the subject slot is refused at build time',
|
|
666
714
|
regex_match: "piped value is the PATTERN, the arg is the subject \u2014 see `regex_test`",
|
|
667
715
|
regex_match_all: "piped value is the PATTERN, the arg is the subject \u2014 see `regex_test`",
|
|
668
716
|
regex_replace: "piped value is the PATTERN, `subject` is the text searched \u2014 see `regex_test`. The replacement comes FIRST",
|
|
669
717
|
iends_with: "case-insensitive; piped value is the subject, the arg is the substring",
|
|
670
718
|
istarts_with: "case-insensitive; piped value is the subject, the arg is the substring",
|
|
671
719
|
// "empty" is a specific set of values, not just null.
|
|
672
|
-
filter_empty: 'keeps entries that are not empty ("", null, 0, "0", false, [], {})',
|
|
720
|
+
filter_empty: 'keeps entries that are not empty ("", null, 0, "0", false, [], {}) \u2014 the only one of the family that drops them all',
|
|
721
|
+
// The rest of the family each drop ONE strict value; the names read broader.
|
|
722
|
+
filter_empty_text: 'drops only `""`; null, 0, false, [] and {} stay',
|
|
723
|
+
filter_zero: 'drops only the integer `0` (strict), not `"0"` or `0.0`',
|
|
673
724
|
first_notempty: 'first value that is not empty ("", null, 0, "0", false, [], {})',
|
|
674
725
|
// The `code` arg is a JS FUNCTION BODY (it must `return`), not a column path,
|
|
675
726
|
// and which identifiers it can see depends on the filter — see **Lambda bodies**.
|
|
676
727
|
// Build it with `lam.fn`, which makes the bindings the function's parameters.
|
|
677
728
|
map: "`code` is a JS body run per element, over `$this`/`$index`/`$parent` \u2014 build it with `lam.fn`",
|
|
678
729
|
filter: "`code` is a JS body run per element (keep it? true/false), over `$this`/`$index`/`$parent`",
|
|
679
|
-
every: "`code` is a JS body run per element (true for all?), over `$this`/`$index`/`$parent`",
|
|
680
|
-
some: "`code` is a JS body run per element (true for any?), over `$this`/`$index`/`$parent`",
|
|
681
|
-
find: "`code` is a JS body run per element; returns the first
|
|
682
|
-
findIndex: "`code` is a JS body run per element; returns the first matching
|
|
683
|
-
reduce:
|
|
730
|
+
every: "`code` is a JS body run per element (true for all?), over `$this`/`$index`/`$parent` \u2014 returns a BOOL (`true` on an empty list)",
|
|
731
|
+
some: "`code` is a JS body run per element (true for any?), over `$this`/`$index`/`$parent` \u2014 returns a BOOL (`false` on an empty list)",
|
|
732
|
+
find: "`code` is a JS body run per element; returns the first ELEMENT it accepts (`null` when none)",
|
|
733
|
+
findIndex: "`code` is a JS body run per element; returns the first matching INDEX as an int (`-1` when none)",
|
|
734
|
+
reduce: '`code` is a JS body run per element; the ACCUMULATOR is `$result` (there is no `$acc`) and `initial_value` is REQUIRED. `initial_value` takes ANY value (an object/text accumulator, `c.obj({...})`/`c.text("")`, not just an int); the result is that accumulator',
|
|
684
735
|
lambda: "runs a JS body once over the piped value, which it binds as `$this` (NOT `$parent`)",
|
|
685
736
|
// The one filter next to `lambda` that is NOT a lambda. It reads as one, its
|
|
686
737
|
// upstream description names a `$this` that does not exist on its path, and
|
|
@@ -691,7 +742,7 @@ var FILTER_NOTES = {
|
|
|
691
742
|
// SILENT — every unrecognized spelling falls through to `itext`, so the array
|
|
692
743
|
// comes back sorted as case-insensitive text with no error anywhere. That is
|
|
693
744
|
// how "top N by score/distance/recency" comes out wrong.
|
|
694
|
-
fsort: '`type` is the comparator
|
|
745
|
+
fsort: '`type` is the comparator: "number" (the only numeric one), "text"/"itext" (strcmp/strcasecmp), "natural"/"inatural" ("a2 < a10"). Default "itext"; anything else sorts as text. The path arg drills into each element',
|
|
695
746
|
// The CSV pair reads as interchangeable and is not: only `csv_create` writes a
|
|
696
747
|
// header, and `csv_encode`'s per-row column order misaligns heterogeneous rows
|
|
697
748
|
// with no error at all.
|
|
@@ -700,9 +751,16 @@ var FILTER_NOTES = {
|
|
|
700
751
|
// A group-by whose name reads as a lookup table. The singular spelling
|
|
701
752
|
// `idx[key].name` is null at runtime rather than an error.
|
|
702
753
|
index_by: "a GROUP-BY: every value is an ARRAY of the items sharing that key, even when only one does, so a lookup reads `idx[key][0]`. Items whose path is missing or non-scalar are dropped",
|
|
754
|
+
unique: "with a `path`, dedupes a list of records by the value at that path and keeps the FIRST per key \u2014 but it DROPS every element whose path is missing or null (the same rule as `index_by`), so deduping by an optional key loses those rows",
|
|
703
755
|
// Non-obvious names.
|
|
704
|
-
epochms_transform: 'applies a relative shift (e.g. "+1 day") to the timestamp',
|
|
705
|
-
unpick: "returns the object without the named keys (inverse of a pick)"
|
|
756
|
+
epochms_transform: 'applies a relative shift (e.g. "+1 day") to the timestamp. \u26A0 a format `strtotime` cannot parse yields `0`, and a MISTYPED one (`"+1 dya"`) a PLAUSIBLE WRONG time, both with NO error \u2014 see date-filter failure modes in `llms/statements-runtime.md`',
|
|
757
|
+
unpick: "returns the object without the named keys (inverse of a pick)",
|
|
758
|
+
// Binary output: a JSON response or text column mangles raw bytes silently, and
|
|
759
|
+
// strlen counts CHARACTERS not bytes, so both under-count a raw-binary result.
|
|
760
|
+
encrypt: "binds RAW ciphertext bytes \u2014 fl.base64_encode() before returning or storing (fl.decrypt takes the raw bytes back)",
|
|
761
|
+
sha256: "the optional `raw` arg returns RAW binary, not the hex digest \u2014 fl.bin2hex()/fl.base64_encode() it before returning or storing (strlen then UNDER-COUNTS: it counts characters, not bytes); omit `raw` for hex",
|
|
762
|
+
secureid_encode: "the operand must be a NON-NEGATIVE integer \u2014 a negative or fractional one encodes without error but `secureid_decode` returns a DIFFERENT positive int (`-3` \u2192 `13`, `-42` \u2192 `214`, `1.5` \u2192 `1`), NOT a round-trip; validate the domain before encoding",
|
|
763
|
+
secureid_decode: "a wrong salt, or a garbage/empty id, is a 400 (`This signature is invalid.` / `Invalid input format for secureId.`), NOT null \u2014 wrap in s.try_catch to handle a miss; only the id from `secureid_encode` of a non-negative int round-trips back"
|
|
706
764
|
};
|
|
707
765
|
function wrapList(items, indent, width = 84) {
|
|
708
766
|
const lines = [];
|
|
@@ -722,19 +780,15 @@ function wrapList(items, indent, width = 84) {
|
|
|
722
780
|
function renderLambdaSection() {
|
|
723
781
|
const lines = ["## Lambda bodies (JavaScript)", ""];
|
|
724
782
|
lines.push(
|
|
725
|
-
"**A lambda is an escape hatch, not a default.**
|
|
726
|
-
"
|
|
727
|
-
"
|
|
728
|
-
"
|
|
729
|
-
"
|
|
730
|
-
"is per CALL, not per element \u2014 an iterating filter sends the body ONCE and loops on the",
|
|
731
|
-
"other side, so one body over a whole list beats one called from inside a stack loop.",
|
|
783
|
+
"**A lambda is an escape hatch, not a default.** Use one only when a native filter,",
|
|
784
|
+
"an `expr(...)`/`obj(...)` expression, or a statement can't do the work: each call crosses a",
|
|
785
|
+
"process boundary into a BOUNDED pool of lambda workers every lambda in the workspace shares.",
|
|
786
|
+
"The crossing is per CALL, not per element \u2014 an iterating filter sends the body ONCE and loops on the",
|
|
787
|
+
"other side, so one iterating filter over a list beats a lambda inside a stack loop.",
|
|
732
788
|
"",
|
|
733
789
|
"The lambda statement (`s.lambda({ as, code, timeout? })`) and eight filters run a",
|
|
734
|
-
"JavaScript body. **Write the body as a FUNCTION, not a `c.text` string**
|
|
735
|
-
"
|
|
736
|
-
"compile error instead of a wrong value at runtime. Write it inline and the surface",
|
|
737
|
-
"is implied by where it sits; nothing names one:",
|
|
790
|
+
"JavaScript body. **Write the body as a FUNCTION, not a `c.text` string** (bindings are",
|
|
791
|
+
"typed parameters; a wrong name is a compile error). Inline, the surface is implied by where it sits:",
|
|
738
792
|
"",
|
|
739
793
|
"```ts",
|
|
740
794
|
"fl.map(({ $this }) => $this * 2) // map's bindings, typed from the position",
|
|
@@ -742,19 +796,18 @@ function renderLambdaSection() {
|
|
|
742
796
|
's.lambda({ as: "total", code: ({ $var }) => $var.subtotal * 1.2 }) // ambient only \u2014 $this is a compile error',
|
|
743
797
|
"```",
|
|
744
798
|
"",
|
|
745
|
-
"
|
|
746
|
-
"
|
|
747
|
-
"`{ $this: x }`, nesting, a default or rest are undefined there (refused).",
|
|
799
|
+
"Destructure bindings by their exact names (`({ $this })`). Refused: `(b) => b.$this`,",
|
|
800
|
+
"renaming (`{ $this: x }`), nesting, defaults, rest.",
|
|
748
801
|
"",
|
|
749
802
|
"\u26A0 An inline `code:` arrow receives BINDINGS ONLY. `capture` is an option of",
|
|
750
803
|
"`lam.fn`, not a field of `s.lambda` or a filter, so `capture:` beside `code:` is a type",
|
|
751
|
-
"error \u2014
|
|
804
|
+
"error \u2014 move the body into `lam.fn(fn, { capture })` (below).",
|
|
752
805
|
"",
|
|
753
806
|
"For a body built away from its call site:",
|
|
754
807
|
"",
|
|
755
808
|
"- `lam.fn(({ $result, $this }) => $result + $this, { surface?, capture? })` \u2014 name a `surface` to check it here, or omit it and the call site checks it.",
|
|
756
809
|
'- `lam.raw("return 1", { surface })` \u2014 text, same validation.',
|
|
757
|
-
"- `lam.raw(code, { surface, unchecked: true })` \u2014 sends a body that does not parse or declares a top-level `import`/`export
|
|
810
|
+
"- `lam.raw(code, { surface, unchecked: true })` \u2014 sends a body that does not parse or declares a top-level `import`/`export`; skips those syntax checks only, here and at the `s.lambda` / `fl.*` site.",
|
|
758
811
|
'- `lam.file("./lambdas/total.ts")` \u2014 a default-exported function in its own module (path relative to the caller), read as text at build time. NODE ONLY: `import { lam } from "@xano/sdk/node"` (isomorphic `lam` has no `file`). Only the default export\'s BODY is sent, so a value import, a second export or a top-level helper is refused \u2014 move helpers inside; `import type` / `import { type X }` are free. `@xano/sdk/lambda-globals` types the globals below program-wide: keep modules in `xano/lambdas/` (its scaffold tsconfig loads it) or `import type {} from` it under their own tsconfig.',
|
|
759
812
|
"",
|
|
760
813
|
"Nothing from the enclosing scope crosses: the body is sent as TEXT, so a closed-over",
|
|
@@ -765,13 +818,12 @@ function renderLambdaSection() {
|
|
|
765
818
|
'lam.fn(({ $this }, { capturedRate }) => $this * capturedRate, { surface: "map", capture: { capturedRate: rate } })',
|
|
766
819
|
"```",
|
|
767
820
|
"",
|
|
768
|
-
"\u26A0 A capture key must NOT share
|
|
769
|
-
"
|
|
770
|
-
"declares `rate` (refused at build time). `capture: { capturedRate: rate }` is the safe form.",
|
|
821
|
+
"\u26A0 A capture key must NOT share a module-scope binding's name (a `.ts` loader renames one;",
|
|
822
|
+
"refused at build time) \u2014 `capture: { capturedRate: rate }`, not `{ rate }`.",
|
|
771
823
|
"",
|
|
772
824
|
"Capture JSON data only: a function, `NaN`, a sparse/typed array or class instance (`Date`, `Map`\u2026)",
|
|
773
825
|
"is refused at build time, at any depth. Capture the plain form and rebuild in",
|
|
774
|
-
"the body (`d.getTime()` \u2192 `new Date(d)`).
|
|
826
|
+
"the body (`d.getTime()` \u2192 `new Date(d)`).",
|
|
775
827
|
"",
|
|
776
828
|
"A body is a FUNCTION BODY: it must `return` its value. Bindings by surface \u2014 an",
|
|
777
829
|
"identifier outside its surface's set is undefined at runtime, and the SDK refuses",
|
|
@@ -802,12 +854,21 @@ function renderLambdaSection() {
|
|
|
802
854
|
"and exists only on the iterating filters. A stack variable is reached as",
|
|
803
855
|
"`$var.name` \u2014 it is NOT also injected as a bare `$name`.",
|
|
804
856
|
"",
|
|
805
|
-
"
|
|
806
|
-
"",
|
|
807
|
-
"
|
|
808
|
-
"
|
|
809
|
-
"
|
|
810
|
-
"
|
|
857
|
+
"`$auth` with no authenticated caller (a public surface, or an authed one reached without a",
|
|
858
|
+
'token) is `{ id: 0, dbo: "" }`, not null. Test `$auth.id > 0`, not truthiness.',
|
|
859
|
+
"",
|
|
860
|
+
"Hazards:",
|
|
861
|
+
"",
|
|
862
|
+
"- \u26A0 A body that THROWS or times out does not fail the request (nor reach `s.try_catch`): the",
|
|
863
|
+
' engine returns its diagnostic TEXT as the value with HTTP 200 (`"[Line 1:Char 7] boom"`,',
|
|
864
|
+
' `"Lambda timed out after 1 seconds"`; a thrown non-Error is `" Unknown error"` on the cloud).',
|
|
865
|
+
" Validate before consuming it. To FAIL the request: wrap the body in `try { return { ok: true,",
|
|
866
|
+
' v } } catch { return { ok: false } }`, then `s.precondition` `ref("r.ok", { safe: true })` = `true`.',
|
|
867
|
+
"- \u26A0 An `s.lambda` whose body returns a STRING that parses as a JSON object or array binds",
|
|
868
|
+
" the DECODED value, not the string (the statement's output is cast as `json`);",
|
|
869
|
+
' scalar-looking strings (`"123"`, `"true"`) stay text, and `fl.map`/`fl.lambda` keep',
|
|
870
|
+
" the string. A body that `JSON.stringify`s a payload to sign/hash/store gets an object",
|
|
871
|
+
" back. To keep text, return it WRAPPED (`{ text }`) and read `.text`.",
|
|
811
872
|
"- \u26A0 `timeout` is COOPERATIVE \u2014 observed only at an `await` \u2014 so it bounds WAITING (a slow",
|
|
812
873
|
" `fetch`), not compute: a 1s `timeout` over a 3s busy-loop runs all 3s and returns",
|
|
813
874
|
" normally. Bound a loop that could run away inside the body.",
|
|
@@ -815,16 +876,25 @@ function renderLambdaSection() {
|
|
|
815
876
|
' a dependency through the PRELOADED globals below. A dynamic `import("\u2026")`/`require("\u2026")`',
|
|
816
877
|
" with a LITERAL specifier is not portable: an instance that bundles the body first",
|
|
817
878
|
' returns the TEXT `Could not resolve "node:crypto"` with HTTP 200.',
|
|
818
|
-
"- Preloaded globals
|
|
879
|
+
"- Preloaded globals \u2014 no specifier, so these work everywhere:",
|
|
819
880
|
...wrapList(LAMBDA_MODULE_GLOBALS.map(tick), " "),
|
|
820
881
|
" \u2026plus `fetch`, `Buffer`, `TextEncoder`/`TextDecoder`, and the `crypto` above",
|
|
821
882
|
" (`randomUUID`, `createHmac`, `createHash`, `subtle`). `Object.keys(globalThis)`",
|
|
822
883
|
" inside a body lists whatever else a given instance carries.",
|
|
823
|
-
"-
|
|
824
|
-
|
|
825
|
-
"
|
|
884
|
+
"- An INLINE body in `xano/` that uses one of these globals does not type-check until that",
|
|
885
|
+
' file has `import type {} from "@xano/sdk/lambda-globals"` at the top (safe in the defs',
|
|
886
|
+
" program \u2014 it is not the frontend); or move the body to a `lam.file` module under",
|
|
887
|
+
" `xano/lambdas/`, whose scaffold tsconfig loads the types already.",
|
|
888
|
+
"- \u26A0 `console` output goes to the request LOG, not stdout. The logging methods (`log` \xB7",
|
|
889
|
+
" `error` \xB7 `warn` \xB7 `info` \xB7 `debug` \xB7 `trace`), plus `table` and `dir`, all route there;",
|
|
890
|
+
" `group`/`count`/`time`/`assert` are undefined, and CALLING one throws (error text as the",
|
|
891
|
+
" value, HTTP 200).",
|
|
826
892
|
"",
|
|
827
893
|
"TypeScript annotations survive in the body, and top-level `await` works.",
|
|
894
|
+
"",
|
|
895
|
+
"Inline and `lam.fn` bodies are stored WHITESPACE-MINIFIED on one line, so an error position",
|
|
896
|
+
"(`[Line 1:Char 59]`) always says Line 1. Use `lam.file` when you want the body readable or",
|
|
897
|
+
"line-accurate errors; its module text is stored as written.",
|
|
828
898
|
""
|
|
829
899
|
);
|
|
830
900
|
return lines;
|
|
@@ -841,9 +911,10 @@ function renderTestsSection() {
|
|
|
841
911
|
"- `name` is unique within the object and is the key a statement's `mock` resolves against; a duplicate throws.",
|
|
842
912
|
"- `id` defaults to a derivation from the owning object plus the name. A pulled test carries the id Xano minted, emitted explicitly.",
|
|
843
913
|
'- `datasource` defaults to `""` \u2014 an EMPTY datasource. Any other value names one the engine CLONES before the run; `"live"` warns `test.live-datasource` on the owning def.',
|
|
844
|
-
'-
|
|
914
|
+
'- That empty default means **no `table({ seed })` rows exist while a unit test runs**, as for a `workflowTest()`: every `db` read misses, so `resp("0.id")` fails though the deployed endpoint returns those rows. Create the rows INSIDE the run (a `defineFunction` fixture the stack calls first) or `mock` the read.',
|
|
915
|
+
'- **To read `table({ seed })` rows on an EPHEMERAL**, set `datasource: "live"`: there it holds only the seed fixtures (plus rows `--keep-data` kept); the run\'s writes are dropped. `diagnostics.allow` accepts its warning. \u26A0 `datasource` is STORED, not a per-run flag: a test left on `"live"` clones the REAL database once it runs against an instance, so clear it before you promote.',
|
|
845
916
|
"- `input` is `{ <input name>: Value }` \u2014 tagged values (`c.*`, `ref`, \u2026), never plain JS scalars.",
|
|
846
|
-
"- `token` runs the test as an authenticated caller. A pull does NOT bring it back: it is an expiring credential, reported as a deliberate omission.",
|
|
917
|
+
"- `token` runs the test as an authenticated caller. A pull does NOT bring it back: it is an expiring credential, reported as a deliberate omission. A token is signed per instance and expires: a literal one passes only on the backend that minted it, fails `Invalid token.` anywhere else, and commits a live credential to source. Keep `token` for a throwaway local check; for `query({ auth })` logic use the `defineFunction` route under **What a `workflowTest()` run actually sees**.",
|
|
847
918
|
"",
|
|
848
919
|
"### Assertions: `expect.*`, not `s.expect.*`",
|
|
849
920
|
"",
|
|
@@ -851,7 +922,10 @@ function renderTestsSection() {
|
|
|
851
922
|
"- Subject first \u2014 argument order is the assertion: `expect.to_equal(resp(), c.int(2))`.",
|
|
852
923
|
'- `resp()` is the response under test; `resp("id")` drills, `resp("a-b")` takes the bracket escape.',
|
|
853
924
|
"- Subject only: `to_be_defined`, `to_not_be_defined`, `to_be_empty`, `to_be_null`, `to_not_be_null`, `to_be_true`, `to_be_false`, `to_be_in_the_future`, `to_be_in_the_past`.",
|
|
925
|
+
'- \u26A0 `to_be_in_the_past`/`to_be_in_the_future` compare at WHOLE-SECOND resolution and treat the SAME second as neither \u2014 a timestamp taken during the request under test (`c.now()`, a `created_at` the endpoint just wrote) fails `to_be_in_the_past` nearly every run. Assert `expect.to_be_less_than(resp("ts"), c.now())` instead (or `to_be_defined` plus a range).',
|
|
854
926
|
"- Subject + operand: `to_equal`, `to_not_equal`, `to_be_greater_than`, `to_be_less_than`, `to_contain`, `to_start_with`, `to_end_with`, `to_match` (operand is a delimiter-wrapped pattern \u2014 build it with `c.regex`).",
|
|
927
|
+
'- `to_be_empty` passes ONLY for `""`, `[]` and `{}` \u2014 `0`, `null` and `false` FAIL it; use `to_be_null` for null and `to_equal(\u2026, c.int(0))` for zero.',
|
|
928
|
+
'- `to_equal`/`to_not_equal` compare LOOSELY: `"5"` equals `5`, and `5` equals `5.0`. To pin a value\'s TYPE, assert on a filter (`withFilters(resp("x"), fl.is_text())`), not `to_equal`.',
|
|
855
929
|
"- `expect.to_be_within(subject, min, max)` \u2014 both bounds EXCLUSIVE; a subject equal to either fails.",
|
|
856
930
|
'- `expect.to_throw(exception?)` takes NO subject. With an argument the error message must CONTAIN that text (case-insensitive substring); with none, any error passes. `exception` is a `Value` \u2014 `expect.to_throw(c.text("Wrong password"))`, not a bare string (a bare one fails to compile with TS2345).',
|
|
857
931
|
"",
|
|
@@ -870,14 +944,23 @@ function renderTestsSection() {
|
|
|
870
944
|
"",
|
|
871
945
|
"### What a `workflowTest()` run actually sees",
|
|
872
946
|
"",
|
|
873
|
-
"
|
|
947
|
+
"Isolation rules; each fails a correct test with a misleading message.",
|
|
948
|
+
"",
|
|
949
|
+
'- The run uses an EMPTY datasource by default (`datasource: ""`), so **no `table({ seed })` rows exist while it runs** (same as a unit test): a read of seeded row 1 fails with its own precondition message, not an empty-database error. Build fixtures INSIDE the test, or set `datasource: "live"` under the ephemeral-only rule in the first section.',
|
|
950
|
+
"- `s.api.call` reports a failing endpoint by WHERE it fails, so no single assertion covers every failure. `s.function.run` raises on every failure instead.",
|
|
874
951
|
"",
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
'
|
|
878
|
-
|
|
952
|
+
"| Failure | What `as` gets | Assert with |",
|
|
953
|
+
"|---|---|---|",
|
|
954
|
+
'| INPUT error (missing required input, wrong type) | nothing: the call RAISES and fails the test (`Missing param: msg`); later `s.expect.*` never run | `s.expect.to_throw({ body: [s.api.call({ api, input: {}, as: "r" })], exception: c.text("Missing param") })` |',
|
|
955
|
+
'| STACK error (`s.precondition`/`guard.*`) | the envelope `{ code, message, payload }`; the run carries on | `s.expect.to_contain({ expr: ref("r.code"), value: c.text("ERROR_CODE_ACCESS_DENIED") })` |',
|
|
956
|
+
'| `s.throw` | a codeless `{ payload, statement }`: `ref("r.code")` fails `Unable to locate var` | `ref("r.payload")` |',
|
|
957
|
+
"",
|
|
958
|
+
"- `s.expect.to_throw` catches a call only when the error carries a MESSAGE. `ERROR_CODE_ACCESS_DENIED` arrives with an empty one, so `to_throw` around an auth-refused call reports `to_throw failed - response is ok`.",
|
|
959
|
+
'- `s.expect.to_throw({ body, exception? })` runs `body` in an ISOLATED var stack, so a variable bound EARLIER in the test is not visible inside it \u2014 bind what the body needs inside the body. An outer one raises `Missing var entry: <name>` there, which the test reports as `to_throw` not matching (`export()` warns). `exception` is a `Value` (`c.text("already exists")`), matched as in `expect.to_throw`; omit it to accept any error.',
|
|
879
960
|
"- An endpoint's `auth` gate is NOT enforced on `s.api.call`. A `query({ auth: users })` runs anyway and fails only where its stack dereferences `auth(...)`. A stack that never touches `auth(...)` runs unauthenticated and passes.",
|
|
880
961
|
"- Neither `auth.token` nor an `Authorization` entry in `headers` authenticates the call \u2014 a token that answers 200 over real HTTP is refused here. To cover auth-gated logic, move the body into a `defineFunction` taking the user id and `s.function.call` that; the gate itself is not reachable from a workflow test.",
|
|
962
|
+
'- Table triggers do not fire on writes made during a test run (unit or workflow); a test asserting a trigger\'s side effect finds 0 rows. Triggers fire only on a deployed/ephemeral instance, async after commit (`llms/triggers.md`). Test the trigger\'s stack directly with `s.trigger.call({ trigger, input: { new: obj({\u2026}), old: obj({\u2026}), action: c.text("insert"), datasource: c.text("live") } })` \u2014 a synthetic `new`/`old`/`action`; `datasource` is REQUIRED \u2014 then assert on what it wrote.',
|
|
963
|
+
'- A failing RUN\'s `message` is the authored message: a `s.precondition`/`guard.*` that raised inside a `.call` reports its own text (`"Bookings must start in the future."`), an `s.throw` its `name`.',
|
|
881
964
|
"",
|
|
882
965
|
"### Running them",
|
|
883
966
|
"",
|
|
@@ -914,16 +997,13 @@ function renderSections(m) {
|
|
|
914
997
|
// The shortfall by name: an agent that cannot see WHICH kinds are missing
|
|
915
998
|
// will invent a factory for one. Reasons live in `manifest.json`.
|
|
916
999
|
`Authorable: statement surfaces ${m.coverage.statements.implemented}/${m.coverage.statements.total}, filters ${m.coverage.filters.total} (${m.coverage.filters.typed} typed).`,
|
|
917
|
-
`Not authorable here: ${m.coverage.objectKinds.unmodeled.map((k) => k.kind).join(", ")} \u2014 these cannot be authored and do not survive a pull; reasons in \`coverage.objectKinds.unmodeled\`.`,
|
|
918
|
-
"",
|
|
919
|
-
"
|
|
920
|
-
"
|
|
921
|
-
"
|
|
922
|
-
"
|
|
923
|
-
"
|
|
924
|
-
"lookup in the shipped `manifest.json` (a program imports it as",
|
|
925
|
-
'`@xano/sdk/manifest.json`, needing `with { type: "json" }` in Node ESM;',
|
|
926
|
-
"it is ~70k tokens, so never read it whole). Its top-level keys are `" + Object.keys(m).join("`, `") + "`. `statements` and `filters` are ARRAYS, not maps \u2014 SELECT, do not index:",
|
|
1000
|
+
`Not authorable here: ${m.coverage.objectKinds.unmodeled.map((k) => k.kind === "realtime_channel" ? "realtime_channel (legacy; author realtimeServer + realtimeChannel instead)" : k.kind).join(", ")} \u2014 these cannot be authored and do not survive a pull; reasons in \`coverage.objectKinds.unmodeled\`.`,
|
|
1001
|
+
"",
|
|
1002
|
+
"Per-surface detail is in the topic files below: open the one whose condition matches the task.",
|
|
1003
|
+
"Per-entry detail (a statement's field schema with engine defaults, a filter's full argument",
|
|
1004
|
+
"list, the `storedName` mapping) is in the shipped `manifest.json` \u2014 do a TARGETED lookup;",
|
|
1005
|
+
"it is ~70k tokens, so never read it whole. A program imports it as `@xano/sdk/manifest.json`",
|
|
1006
|
+
'(Node ESM needs `with { type: "json" }`). Its top-level keys are `' + Object.keys(m).join("`, `") + "`. `statements` and `filters` are ARRAYS, not maps \u2014 SELECT, do not index:",
|
|
927
1007
|
` jq '.statements[] | select(.sPath=="db.get")' manifest.json`,
|
|
928
1008
|
` jq '.filters[] | select(.name=="json_decode")' manifest.json`,
|
|
929
1009
|
`\u26A0 \`fields\` is null on the ${m.statements.filter((st) => st.declarative !== true).length} \`declarative: false\` statements (\`db.get\`, \u2026): typed wrappers whose arguments are the factory's \`.d.ts\` signature. Null \u2260 missing.`,
|
|
@@ -934,9 +1014,6 @@ function renderSections(m) {
|
|
|
934
1014
|
lines.push(
|
|
935
1015
|
"## Quickstart",
|
|
936
1016
|
"",
|
|
937
|
-
"Authoring is **declarative def-objects** passed to factories \u2014 there is no",
|
|
938
|
-
"callback/chaining builder.",
|
|
939
|
-
"",
|
|
940
1017
|
"```ts",
|
|
941
1018
|
'import { workspace, apiGroup, query, table, input, f, ref, inp, auth, s } from "@xano/sdk";',
|
|
942
1019
|
"",
|
|
@@ -945,13 +1022,13 @@ function renderSections(m) {
|
|
|
945
1022
|
" auth: true, // backs authentication",
|
|
946
1023
|
" // `id` (int PK) + `created_at` (epochms) are auto-injected \u2014 don't declare them.",
|
|
947
1024
|
" schema: {",
|
|
948
|
-
|
|
1025
|
+
' email: f.email({ required: true, methods: ["trim", "lower"] }), // a unique email index is CASE-SENSITIVE \u2014 lowercase it',
|
|
949
1026
|
" name: f.text(),",
|
|
950
1027
|
" },",
|
|
951
1028
|
' // Indexes: { type, fields: [{ name, op? }] }. `"unique"` is shorthand for `"btree|unique"`.',
|
|
952
1029
|
" // A DOTTED name indexes a key inside a column (`xdo.email`); only the part before the",
|
|
953
1030
|
" // first dot is checked against the schema.",
|
|
954
|
-
' index: [{ type: "unique", fields: [{ name: "email" }] }],
|
|
1031
|
+
' index: [{ type: "unique", fields: [{ name: "email" }] }],',
|
|
955
1032
|
"});",
|
|
956
1033
|
"",
|
|
957
1034
|
"const posts = table({",
|
|
@@ -992,30 +1069,26 @@ function renderSections(m) {
|
|
|
992
1069
|
'which fails with a "must be ES modules" error until you switch it to module.',
|
|
993
1070
|
"",
|
|
994
1071
|
"Set `canonical` on every `apiGroup`. The engine mints the URL token server-side, so",
|
|
995
|
-
"without one
|
|
996
|
-
"
|
|
997
|
-
"
|
|
998
|
-
"
|
|
999
|
-
"
|
|
1000
|
-
"
|
|
1001
|
-
"
|
|
1002
|
-
"
|
|
1003
|
-
"",
|
|
1004
|
-
"
|
|
1005
|
-
"
|
|
1006
|
-
"
|
|
1007
|
-
"but nothing fails on a message no one reads, so in CI and in unattended agent builds",
|
|
1008
|
-
"pass `--strict` (`emitBundle(app, { strict: true })` / `app.export({ strict: true })`):",
|
|
1009
|
-
"every warning becomes a hard failure. Same bundle bytes either way.",
|
|
1072
|
+
"without one `npx @xano/sdk routes` / `getPath()` cannot resolve the group's paths until a",
|
|
1073
|
+
"lock exists (the export itself succeeds).",
|
|
1074
|
+
"\u26A0 A canonical is unique across the whole INSTANCE, not per workspace; no flag shares one.",
|
|
1075
|
+
"A canonical set in code is a PIN: a merge refuses (exit 2) when another workspace holds it.",
|
|
1076
|
+
"One only the lock minted is not pinned: the instance may replace it with a random token,",
|
|
1077
|
+
"and `--static` is refused when it does.",
|
|
1078
|
+
"",
|
|
1079
|
+
"Build warnings: `export()` warns on shapes that deploy but misbehave (a `bulk.update`",
|
|
1080
|
+
"zero-filling omitted columns, an `ignoreEmpty` on an empty operand, a `ref()` nothing",
|
|
1081
|
+
"binds). In CI and agent builds pass `--strict` (`emitBundle(app, { strict: true })` /",
|
|
1082
|
+
"`app.export({ strict: true })`): every warning becomes a hard failure. Same bundle bytes",
|
|
1083
|
+
"either way.",
|
|
1010
1084
|
"Before calling the work done: `npm run typecheck`, `npx @xano/sdk export <entry> --strict`,",
|
|
1011
1085
|
"`deploy <entry>`, then `test run-all` against what deployed.",
|
|
1012
1086
|
"",
|
|
1013
|
-
"Identity: object guids derive from `(type, name)`
|
|
1014
|
-
"
|
|
1015
|
-
"
|
|
1016
|
-
"
|
|
1017
|
-
"
|
|
1018
|
-
"`--frozen-lock` fails instead of changing it).",
|
|
1087
|
+
"Identity: object guids derive from `(type, name)` (a query adds group + verb),",
|
|
1088
|
+
"so renames change identity.",
|
|
1089
|
+
"Every build freezes every guid + api-group/toolset canonical in a lock file beside the entry",
|
|
1090
|
+
"file (`xano/xano.lock` in the standard scaffold, not the project root). Commit it",
|
|
1091
|
+
"(`--no-lock` opts out; CI guard `--frozen-lock` fails instead of changing it).",
|
|
1019
1092
|
"To rename an object: rename in code, export (stderr prints the exact fix-up), run",
|
|
1020
1093
|
"`npx @xano/sdk lock rename <kind> <old> <new>`, export again \u2014 the original guid is emitted",
|
|
1021
1094
|
"under the new name, so the engine renames in place instead of delete+create. Taking",
|
|
@@ -1029,51 +1102,58 @@ function renderSections(m) {
|
|
|
1029
1102
|
"`export` (honoring `xano.lock`), imports the result, and prints the URL.",
|
|
1030
1103
|
"\u26A0 Every deploy is a FULL REPLACE of its destination \u2014 objects AND records.",
|
|
1031
1104
|
"",
|
|
1032
|
-
"**Backends** \u2014 one grammar
|
|
1033
|
-
"
|
|
1034
|
-
"
|
|
1035
|
-
"`
|
|
1036
|
-
"
|
|
1037
|
-
"
|
|
1038
|
-
"
|
|
1039
|
-
"
|
|
1040
|
-
"
|
|
1105
|
+
"**Backends** \u2014 one grammar for every command that names a backend:",
|
|
1106
|
+
"",
|
|
1107
|
+
"- Spellings: `workspace` | `ephemeral[:<name>]` | `local[:<name>]` (no credential) |",
|
|
1108
|
+
" `tenant:<name>` | `release:<name>` | a bundle path where a file fits.",
|
|
1109
|
+
"- Reads `--from`, writes `--to`, `test --on`; positional on `deploy`/`pull`/`generate`/`tables`/",
|
|
1110
|
+
" `impersonate`.",
|
|
1111
|
+
"- Omitted = the ephemeral or Xano Engine this project last deployed to, never",
|
|
1112
|
+
" workspace/tenant. Exceptions: bare `deploy` always targets the Xano Engine (`--ephemeral`: an",
|
|
1113
|
+
" ephemeral); `generate`/`init --from` need one.",
|
|
1114
|
+
"- A backend a command cannot serve is refused, typed or tracked, with the reason and the valid",
|
|
1115
|
+
" spellings (`release create` refuses a Xano Engine).",
|
|
1116
|
+
"- `release create --from` takes a run only: no bundle path, no `release:`, and a",
|
|
1117
|
+
" `tenant:` only if throwaway (`standard`/`run` refused).",
|
|
1041
1118
|
"",
|
|
1042
1119
|
"**Destinations** \u2014 the Xano Engine by default, real only when you say so:",
|
|
1043
1120
|
"",
|
|
1044
|
-
"- `deploy [source]` \u2192 the Xano Engine on this machine (no account).
|
|
1045
|
-
"
|
|
1046
|
-
"
|
|
1047
|
-
"
|
|
1048
|
-
"
|
|
1049
|
-
"
|
|
1050
|
-
"
|
|
1051
|
-
"
|
|
1052
|
-
"
|
|
1053
|
-
"
|
|
1054
|
-
"
|
|
1055
|
-
"
|
|
1056
|
-
"
|
|
1057
|
-
"
|
|
1058
|
-
"
|
|
1121
|
+
"- `deploy [source]` \u2192 the Xano Engine on this machine (no account).",
|
|
1122
|
+
" - `--ephemeral` \u2192 a NAMED, auto-expiring ephemeral (~1h; `--expires-hours` 1\u201324), tracked in",
|
|
1123
|
+
" `./.xano/ephemeral.json`, so deploying again REFRESHES it at the same URL; if it expired or",
|
|
1124
|
+
" was swept, a fresh one is created and the new URL printed.",
|
|
1125
|
+
" - \u26A0 Only the BACKEND URL survives a refresh: the replace clears static hosting, so",
|
|
1126
|
+
" `--static` publishes a NEW host every run and the previous URL stops serving.",
|
|
1127
|
+
" - Under `--keep-data`, which MERGES an env a deploy filled instead of replacing it, the static",
|
|
1128
|
+
" URL survives too: rows kept, no re-seed, removed objects deleted. \u26A0 Limits: a rename loses values,",
|
|
1129
|
+
" a RETYPE reads unfit ones as null, env VALUES are not applied, a table trigger refuses it.",
|
|
1130
|
+
" `--reset` replaces and re-seeds.",
|
|
1131
|
+
"- `release create <name>` cuts a release from a running source and LANDS it in your workspace.",
|
|
1132
|
+
" A release records that the source came up; it is the only thing `promote`/`tenant deploy` take.",
|
|
1133
|
+
" - Refused: a taken name, and one that addresses a LOCATION instead of naming (`/`, `\\`, `:`,",
|
|
1134
|
+
" or a leading `.`). Every export derives its FILENAME from the name it is given, so",
|
|
1135
|
+
" `release|ephemeral|workspace export` refuse those same shapes unless `--path` names the file.",
|
|
1136
|
+
" - Carries EVERY table's SCHEMA either way; `--seed[=<guids>]` adds ROWS. Guids come from",
|
|
1137
|
+
" `tables <backend>`; a redeploy KEEPS them.",
|
|
1059
1138
|
"- `release transfer <name> --to-profile <profile>` copies a release to another",
|
|
1060
1139
|
" workspace/instance by CONTENT (tar sha256): identical \u2192 reused; same name, other",
|
|
1061
1140
|
" bytes \u2192 exit 2.",
|
|
1062
1141
|
"- `promote <release>` / `tenant deploy <tenant> <release>` land it.",
|
|
1063
|
-
" `promote` adds a branch; \u26A0 its TABLE edits hit live",
|
|
1064
|
-
"
|
|
1065
|
-
"
|
|
1066
|
-
"
|
|
1067
|
-
"
|
|
1068
|
-
"
|
|
1069
|
-
"
|
|
1070
|
-
" `completed` yes|no|unknown; UNKNOWN exits 9 \u2014 run
|
|
1071
|
-
"
|
|
1072
|
-
"
|
|
1073
|
-
"
|
|
1074
|
-
"
|
|
1075
|
-
"
|
|
1076
|
-
"
|
|
1142
|
+
" - `promote` adds a branch; \u26A0 its TABLE edits hit live (`--allow-shared-schema-changes`).",
|
|
1143
|
+
" - `tenant deploy` REPLACES: DROPS tables it lacks, CONVERTS retypes (`--seed`: rows).",
|
|
1144
|
+
" - `promote` refuses a taken name/pinned slug (`SDK_IDENTITY_CONFLICT`), then EXITS NON-ZERO",
|
|
1145
|
+
" if a declared object did not arrive or a pinned slug is not served. `--set-live` switches",
|
|
1146
|
+
" only after that check passes; a failure leaves the previous branch serving. Extra objects",
|
|
1147
|
+
" are reported; a check missing an input reports `unverified`, exit 0.",
|
|
1148
|
+
" - `--expect-live <label>` (with `--set-live`) refuses if live moved; not atomic.",
|
|
1149
|
+
" - `--json` on every release write: `completed` yes|no|unknown; UNKNOWN exits 9 \u2014 run",
|
|
1150
|
+
" `resolveWith`, never retry blind.",
|
|
1151
|
+
" - Inspect a staged branch with `workspace export --branch <label>` or",
|
|
1152
|
+
" `workspace diff <entry> --branch <label>`.",
|
|
1153
|
+
"- \u26A0 The redis family, `s.lambda`, `s.db.direct_query`, `s.await`, async runs,",
|
|
1154
|
+
" `s.microservice.request`, `s.zip.*`, the raw-file readers, Datadog and Webflow need an",
|
|
1155
|
+
" INSTANCE CAPABILITY: they deploy clean and fail on the first request if the target lacks it.",
|
|
1156
|
+
" `export`/`deploy` list what the bundle needs \u2014 compare it to the target yourself.",
|
|
1077
1157
|
"- Backend SECRETS stay out of the repo: declare the NAME, value empty, in `workspaceConfig({ env })`",
|
|
1078
1158
|
" passed to `registerWorkspace()`; the VALUE lives in `xano/.env` \u2014 gitignored, kept across a",
|
|
1079
1159
|
" pull, read by every build. `--backend-env-file <path>` replaces that default (CI has",
|
|
@@ -1106,9 +1186,7 @@ function renderSections(m) {
|
|
|
1106
1186
|
"- `workspace reset-tables <entry> --table <guid>` puts NAMED tables back to their",
|
|
1107
1187
|
" compiled `table({ seed })` rows, touching no other table. Dry run unless `--write`.",
|
|
1108
1188
|
" \u26A0 ROWS BEFORE LOGIC: rows are workspace-shared like schema, so they reach production when",
|
|
1109
|
-
" applied even while the logic reading them is staged
|
|
1110
|
-
" atomic. Reset rows FIRST, then `promote`: new rows under old logic break only a feature",
|
|
1111
|
-
" being removed; new logic over old rows breaks the one you are shipping.",
|
|
1189
|
+
" applied, even while the logic reading them is staged. Reset rows FIRST, then `promote`.",
|
|
1112
1190
|
"- `pull` refreshes THIS project from a backend: rewrites decoded files,",
|
|
1113
1191
|
" keeps yours, lists and confirms (`--yes`).",
|
|
1114
1192
|
"- `generate <source>`: the decoded tree ONLY, no project.",
|
|
@@ -1140,11 +1218,9 @@ function renderSections(m) {
|
|
|
1140
1218
|
"- **No callback builder.** Flat def-objects + `register*`, not",
|
|
1141
1219
|
" `workspace(w => w.table(...))`. `workspace(name)` returns a named `new Xano()`;",
|
|
1142
1220
|
" tables are `table({ schema: { col: f.text() } })`.",
|
|
1143
|
-
"- **
|
|
1144
|
-
' `col` = table column (in `db.query` `where`), `auth("id")` = the caller,',
|
|
1145
|
-
" `c.*` = a constant.
|
|
1146
|
-
"- **Foreign key is `f.tableRef(table)`, not `ref`.** `ref(name)` references a",
|
|
1147
|
-
" stack variable (a value); `f.tableRef` is the column constructor.",
|
|
1221
|
+
"- **Foreign key is `f.tableRef(table)`, not `ref`.** `ref` = stack var (`as:` output),",
|
|
1222
|
+
' `inp` = input, `col` = table column (in `db.query` `where`), `auth("id")` = the caller,',
|
|
1223
|
+
" `c.*` = a constant; `f.tableRef` is the column constructor.",
|
|
1148
1224
|
"- **Tagged values are DATA \u2014 a JS template literal cannot compose them.** `${ref(...)}`",
|
|
1149
1225
|
' (or `"a" + ref(...)`) stringifies the tag object at BUILD time: ``c.text(`Hi ${ref("u.name")}`)``',
|
|
1150
1226
|
" type-checks and encodes the literal text `Hi [object Object]`, served verbatim.",
|
|
@@ -1158,11 +1234,11 @@ function renderSections(m) {
|
|
|
1158
1234
|
"- **`get_input`/`get_raw_input` read the whole payload**, not one named input",
|
|
1159
1235
|
" (args are `{ as?, encoding?, excludeMiddleware? }` \u2014 no `name`). For a single",
|
|
1160
1236
|
' input use `inp("name")`.',
|
|
1161
|
-
"- **
|
|
1162
|
-
'
|
|
1163
|
-
'
|
|
1164
|
-
|
|
1165
|
-
'
|
|
1237
|
+
"- **A `where` is a comparison, never a value.** To match every row, omit `where`. A value",
|
|
1238
|
+
' `where` \u2014 `c.bool(true)`, a text clause, or one built at run time (`inp("clause")`,',
|
|
1239
|
+
' `ref("built_where")`) \u2014 throws at build: the engine reads a filter only as a comparison',
|
|
1240
|
+
" tree and runs anything else over EVERY row. Bind run-time values as operands instead:",
|
|
1241
|
+
' `expr(col("status"), "=", inp("status"))`.',
|
|
1166
1242
|
"",
|
|
1167
1243
|
"### Tables and columns",
|
|
1168
1244
|
"",
|
|
@@ -1180,8 +1256,7 @@ function renderSections(m) {
|
|
|
1180
1256
|
" defaults or a 400. HTTP binds it fine. `--strict` fails on it.",
|
|
1181
1257
|
"- **Numeric columns lose money quietly.** A normalized table's `f.decimal` reads",
|
|
1182
1258
|
" `0.12345678` back as `0.12346`; `f.int` saturates at `9223372036854775807`",
|
|
1183
|
-
" instead of failing
|
|
1184
|
-
" arithmetic that stops reconciling. Hold money as a count of the smallest unit;",
|
|
1259
|
+
" instead of failing, both at HTTP 200. Hold money as a count of the smallest unit;",
|
|
1185
1260
|
" exact bounds: `llms/fields.md`.",
|
|
1186
1261
|
"- **Self-referencing tables** need the bare-name form: inside `tweets`'s own",
|
|
1187
1262
|
' schema, write `f.tableRef("tweets", { type: "int" })` \u2014 the `const tweets`',
|
|
@@ -1208,22 +1283,17 @@ function renderSections(m) {
|
|
|
1208
1283
|
"### Reading and writing rows",
|
|
1209
1284
|
"",
|
|
1210
1285
|
"- **DB reads are field-match, not `where`-expr.** `db.get`/`db.edit`/`db.del`/",
|
|
1211
|
-
" `db.has`/`db.patch` match
|
|
1212
|
-
" defaults to the PK `id`). Only `db.query` takes a
|
|
1213
|
-
" `expr(...)`; writes (`db.add`/`db.edit`/`db.add_or_edit`) take a
|
|
1214
|
-
"
|
|
1215
|
-
|
|
1216
|
-
"
|
|
1217
|
-
" predicate). For a `(a, b)` existence/fetch \u2014 e.g. dedupe a `(habit, date)`",
|
|
1218
|
-
' check-in \u2014 use `db.query({ where: [expr(col("habit"), "=", ...), expr(col("date"), "=", ...)], as })`',
|
|
1219
|
-
" (a `where` array is ANDed) and branch on the result, rather than pushing the",
|
|
1220
|
-
" check to the client.",
|
|
1286
|
+
" `db.has`/`db.patch` match exactly ONE field: `{ fieldName, fieldValue }` (`fieldName`",
|
|
1287
|
+
" defaults to the PK `id`); there is no composite match. Only `db.query` takes a",
|
|
1288
|
+
" `where`/`additionalWhere` `expr(...)`; writes (`db.add`/`db.edit`/`db.add_or_edit`) take a",
|
|
1289
|
+
" `row`/`data`. For an `(a, b)` existence/fetch (e.g. dedupe a `(habit, date)` check-in), use",
|
|
1290
|
+
' `db.query({ where: [expr(col("habit"), "=", ...), expr(col("date"), "=", ...)], as })`',
|
|
1291
|
+
" (a `where` array is ANDed) and branch on the result. Signatures: `llms/statements-data.md`.",
|
|
1221
1292
|
"- **Drilling into a maybe-null `db.get` result 500s \u2014 use `ref(path, { safe: true })`.**",
|
|
1222
1293
|
' `db.get` binds `null` on a no-match, but a nested `ref("owner.user_id")` raises a runtime',
|
|
1223
1294
|
' "Unable to locate var" (HTTP 500) when `owner` is null \u2014 an ownership guard throws instead',
|
|
1224
|
-
" of failing cleanly. Two correct shapes:",
|
|
1225
|
-
' - Guard existence first \u2014 `
|
|
1226
|
-
' error_type: "notfound", error: c.text("Not found.") })` \u2014 then drill WITHOUT `safe`.',
|
|
1295
|
+
" of failing cleanly (same for a `single` `db.query`; warns `stack.drill-maybe-null`). Two correct shapes:",
|
|
1296
|
+
' - Guard existence first \u2014 `guard.found("owner")` (a 404 precondition) \u2014 then drill WITHOUT `safe`.',
|
|
1227
1297
|
" - Or drill null-safe inside an EXPRESSION or `obj()` operand:",
|
|
1228
1298
|
' `expr(ref("owner.user_id", { safe: true }), "=", auth("id"))` yields `null` (the guard',
|
|
1229
1299
|
" reads `false`) instead of 500ing. Works inside `obj({...})` too \u2014 no `s.set_var` hoist needed.",
|
|
@@ -1254,12 +1324,12 @@ function renderSections(m) {
|
|
|
1254
1324
|
"- **`s.api.call` / `s.task.call` / `s.trigger.call` / `s.workflow_test.call` are",
|
|
1255
1325
|
" WORKFLOW-TEST ONLY.** Outside a `workflowTest({...})` stack the engine cannot reach",
|
|
1256
1326
|
" the target, so one in a query/function/task deploys clean and then answers the first",
|
|
1257
|
-
" real request with `ERROR_FATAL: <Type> does not exist: <type>:<n
|
|
1258
|
-
" host kind
|
|
1327
|
+
" real request with `ERROR_FATAL: <Type> does not exist: <type>:<n>`. The failure is not per",
|
|
1328
|
+
" host kind: the same call inside a function that a query runs fails the same way.",
|
|
1259
1329
|
" `export()` refuses them. `s.function.call`, `s.tool.call`, `s.middleware.call` and",
|
|
1260
|
-
" `s.addon.call` run anywhere, as does `s.function.run
|
|
1261
|
-
"
|
|
1262
|
-
"
|
|
1330
|
+
" `s.addon.call` run anywhere, as does `s.function.run`. To share logic, put it in a",
|
|
1331
|
+
" `defineFunction` and `s.function.run` it \u2014 NOT `s.function.call`, which binds a failing",
|
|
1332
|
+
" target's error envelope instead of raising.",
|
|
1263
1333
|
"- **`expect.*` is a unit-test assertion; `s.expect.*` is a workflow-test statement.**",
|
|
1264
1334
|
" A statement's `mock` is keyed by TEST NAME; an undeclared name throws. See `llms/tests.md`.",
|
|
1265
1335
|
"- **A helper returning `Statement[]` widens the stack and kills `InferResponse`.**",
|
|
@@ -1273,17 +1343,15 @@ function renderSections(m) {
|
|
|
1273
1343
|
" The regex filters (`regex_test`/`regex_match`/`regex_replace`/\u2026) are PHP `preg_*`: the",
|
|
1274
1344
|
" piped value is the PATTERN and must be delimiter-wrapped, and the ARGUMENT is the subject.",
|
|
1275
1345
|
' Correct: `withFilters(c.regex(/^[a-z-]+$/i), fl.regex_test(inp("slug")))`.',
|
|
1276
|
-
' - A bare `c.text("^\u2026$")` is an invalid pattern that matches *nothing* for every input,',
|
|
1277
|
-
'
|
|
1278
|
-
"
|
|
1279
|
-
" - Reversed \u2014 subject piped, pattern in the argument \u2014 reads correctly, type-checks, and",
|
|
1346
|
+
' - A bare `c.text("^\u2026$")` is an invalid pattern that matches *nothing* for every input, so',
|
|
1347
|
+
' a precondition on it rejects all values. `c.regex(body, "i")` (or a JS `RegExp`) wraps + escapes it.',
|
|
1348
|
+
" - Reversed (subject piped, pattern in the argument) type-checks and",
|
|
1280
1349
|
" answers false for EVERY input, so an `if (matches) reject` guard admits what it refuses.",
|
|
1281
|
-
" -
|
|
1282
|
-
"
|
|
1283
|
-
"
|
|
1284
|
-
"
|
|
1285
|
-
"
|
|
1286
|
-
" - Better still: a native typed input (`input.email`) over hand-rolled validation.",
|
|
1350
|
+
" - `withFilters` throws on both: a bare `c.text` pattern at ANY position in the chain (a",
|
|
1351
|
+
" normalizer in front does not add delimiters) and a pattern in the subject slot.",
|
|
1352
|
+
" `s.expect.to_match` is the same PATTERN slot, refused both ways. A `ref`/`inp` pattern is",
|
|
1353
|
+
" passed through untouched. `export()` warns on a reversed pair in stored bytes.",
|
|
1354
|
+
" - Prefer a native typed input (`input.email`) over hand-rolled validation.",
|
|
1287
1355
|
"- **An `auth()`-keyed limiter FAILS the request on any host with no caller identity \u2014**",
|
|
1288
1356
|
' **at every tier.** `s.redis.ratelimit({ key: withFilters(c.text("rl:"), fl.concat(auth("id"))), error: c.text("\u2026") })`',
|
|
1289
1357
|
" is the per-user form, and a public query, a task, or a function has no caller identity.",
|
|
@@ -1295,8 +1363,8 @@ function renderSections(m) {
|
|
|
1295
1363
|
"### Identity, build, and deploy",
|
|
1296
1364
|
"",
|
|
1297
1365
|
"- **Same-name siblings collide \u2014 queries excepted: their identity carries group + verb.**",
|
|
1298
|
-
"
|
|
1299
|
-
"
|
|
1366
|
+
" Two functions (or tables, toolsets, \u2026) sharing a name derive ONE guid and `export()`",
|
|
1367
|
+
" throws \u2014 give them DISTINCT names. A QUERY",
|
|
1300
1368
|
" derives from `(api group, verb, name)`, the engine's own uniqueness: `GET items` +",
|
|
1301
1369
|
" `POST items`, and `items` across two groups, coexist, and the lock keys the same",
|
|
1302
1370
|
" composed identity (`query:blog|GET|items`) \u2014 changing a query's verb or group",
|
|
@@ -1330,27 +1398,26 @@ function renderSections(m) {
|
|
|
1330
1398
|
" the runner has. An explicit `--profile` against it is a hard error too, not a displacement.",
|
|
1331
1399
|
" - On disk: `npx @xano/sdk profile add <name> --instance \u2026 --workspace-id <n>` reads the token",
|
|
1332
1400
|
" from piped stdin, else PROMPTS (a flag would reach the process list); the instance must accept it.",
|
|
1333
|
-
" `auth.json` holds a map of named profiles, selected by `--profile <name>`.
|
|
1334
|
-
" `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID`
|
|
1335
|
-
"- **Event-driven objects
|
|
1336
|
-
"
|
|
1337
|
-
"
|
|
1338
|
-
"
|
|
1401
|
+
" `auth.json` holds a map of named profiles, selected by `--profile <name>`.",
|
|
1402
|
+
" `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` also authenticate, but the refresh token is single-use (it ROTATES).",
|
|
1403
|
+
"- **Event-driven objects run once deployed.** A `task` (scheduled), an `mcpServer`, and",
|
|
1404
|
+
" every trigger \u2014 `tableTrigger` included \u2014 run on every deploy target, the Xano Engine and",
|
|
1405
|
+
" an ephemeral alike. Test an event-driven design (screen-on-insert, scheduled cleanup, MCP",
|
|
1406
|
+
" tool call) by deploying it and letting it run.",
|
|
1339
1407
|
""
|
|
1340
1408
|
);
|
|
1341
1409
|
const objectKinds = [];
|
|
1342
1410
|
objectKinds.push("## Object kinds", "");
|
|
1343
|
-
objectKinds.push("Author with the factory, register on the Xano instance, lands under the payload key. Each line ends with a one-liner on what the primitive is.", "");
|
|
1344
1411
|
objectKinds.push(
|
|
1345
1412
|
"### Choosing a kind",
|
|
1346
1413
|
"",
|
|
1347
|
-
"Choose by who or what starts the work.
|
|
1414
|
+
"Choose by who or what starts the work.",
|
|
1348
1415
|
"",
|
|
1349
1416
|
"- **Logic other code calls** \u2192 `defineFunction`, run with `s.function.run`. A `query` is the only kind an HTTP client reaches by verb + path; a `tool` is what an `agent()` or an MCP client calls. Logic serving two callers (an endpoint AND a tool) lives in one function both call.",
|
|
1350
|
-
|
|
1351
|
-
"- **The same steps before or after many objects** (an auth check, a rate limit, logging) \u2192 `middleware`, attached per host (`middleware: { pre, post }` on a query, function, task, tool or
|
|
1417
|
+
"- **Work on a timer** \u2192 `task` (fixed interval, no cron). **Work a request starts but does not wait for** \u2192 `s.function.run({ fn, runtime: { mode: \"async-shared\" } })`, which binds a job id, not the result (collect with `s.await`). **Work that follows a row change** \u2192 `tableTrigger`: it fires on every write to the table, whichever stack writes it (except a trigger's own), so the same side effect in one endpoint's stack misses every other write path. It runs after commit, async \u2014 validation belongs in the writing stack (`llms/triggers.md`).",
|
|
1418
|
+
"- **The same steps before or after many objects** (an auth check, a rate limit, logging) \u2192 `middleware`, attached per host (`middleware: { pre, post }` on a query, function, task, tool, API group, prompt, resource, or realtime server/channel/message) or to every host of a kind with `workspaceConfig({ middleware: { query, function, task, tool } })` \u2014 not a function call repeated at the top of each stack.",
|
|
1352
1419
|
"- **Related rows on returned rows** \u2192 an `addon` attached to the read through its `addon: [{ addon, as, input }]` option (`db.query`/`get`/`add`/`edit`/`patch`), merged onto each row under `as` and typed in `InferResponse` \u2014 not a second read plus a loop that stitches rows together.",
|
|
1353
|
-
"- **AI.** An LLM running inside the backend \u2192 `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend \u2192 `mcpServer()`. Standing instructions for Xano's own builder AI \u2192 `knowledge()` (
|
|
1420
|
+
"- **AI.** An LLM running inside the backend \u2192 `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend \u2192 `mcpServer()`. Standing instructions for Xano's own builder AI \u2192 `knowledge()` (who reads it: `llms/kinds-knowledge.md`). The actions either one calls \u2192 `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.",
|
|
1354
1421
|
"- **Pushing to connected clients** \u2192 `realtimeServer` \u2192 `realtimeChannel` \u2192 `realtimeMessage` (the handler for a frame a client sends \u2014 the realtime analogue of a query). A server-side push from any stack is `s.realtime.publish`; a client polling a `query` is the substitute this replaces.",
|
|
1355
1422
|
"- **Code the typed surface cannot express** \u2192 a lambda (`s.lambda`, `fl.lambda`) for a short JavaScript body, LAST, after native filters and expressions (`llms/lambda.md`); a `microservice` for a long-running container or another language; `s.api.request` for a service that already has an HTTP API.",
|
|
1356
1423
|
"- **Tests** \u2192 `tests` on a `query`/`defineFunction`/`middleware` for that one object's input \u2192 output; a `workflowTest` for a flow across objects (`s.function.call`, `s.api.call`, `s.task.call`) asserted with `s.expect.*`.",
|
|
@@ -1358,7 +1425,7 @@ function renderSections(m) {
|
|
|
1358
1425
|
""
|
|
1359
1426
|
);
|
|
1360
1427
|
objectKinds.push(
|
|
1361
|
-
"
|
|
1428
|
+
"Composing a workspace from modules: `registerTables(modules.flatMap((m) => m.tables))` does NOT typecheck \u2014 `flatMap` (and `.concat()`) binds its element type to the FIRST element, so later tables are checked against that one table's schema; the error names two unrelated columns, not the cause. Pass an array LITERAL (`registerTables([...a.tables, ...b.tables])`), or annotate the module array with the wide aliases `AnyTableDef` / `AnyQueryDef` / `AnyFunctionDef` / `AnyAddonDef`. Widening loses nothing: typing lives on the `table()`/`query()` handle passed to `s.db.*`.",
|
|
1362
1429
|
""
|
|
1363
1430
|
);
|
|
1364
1431
|
for (const k of m.objectKinds) {
|
|
@@ -1385,36 +1452,40 @@ function renderSections(m) {
|
|
|
1385
1452
|
"",
|
|
1386
1453
|
"- `defineFunction({ name, guid?, description?, docs?, workspace?, input?, stack?, response?, tests? })`",
|
|
1387
1454
|
"- `query({ name, verb, apiGroup?, guid?, auth?, input?, stack?, response?, responseType?, apiEnabled?, disabled?, cache?, description?, docs?, tests?, example? })` \u2014 a `cache` setting turns caching on unless `active: false`",
|
|
1388
|
-
' - `verb`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD"` (required), UPPERCASE. Anything else
|
|
1455
|
+
' - `verb`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD"` (required), UPPERCASE. Anything else (e.g. lowercase `"post"`) makes `query()` THROW \u2014 Xano would store NULL, a null verb serves as GET, and the verb you meant 404s `Unable to locate request.`',
|
|
1389
1456
|
" - `apiGroup`: an `apiGroup()` def handle (or its name) \u2014 binds by guid, stable across syncs. Raw numeric `apiGroupId?` is the escape hatch and wins if both given.",
|
|
1390
|
-
' - `auth`: `false` (no auth) or an auth-table id; `responseType`: `"standard" | "stream"` (default `standard`) \u2014 any other spelling THROWS
|
|
1457
|
+
' - `auth`: `false` (no auth) or an auth-table id; `responseType`: `"standard" | "stream"` (default `standard`) \u2014 any other spelling THROWS (Xano would store NULL and buffer it as `standard`). \u26A0 `s.api.stream` does nothing unless `responseType: "stream"`: in a `standard` query its chunk is SILENTLY DROPPED (no warning) and the normal `response` is served. Paired, each `s.api.stream({ value })` call emits ONE Server-Sent Event \u2014 the wire is `Content-Type: text/event-stream`, a `data: <json of value>` line per event, with an `id:` line that is a MILLISECOND TIMESTAMP and is NOT unique (ids repeat within a ms, so `Last-Event-ID` resume is unreliable). The query\'s own `response` is not sent in `stream` mode. Consumer recipe (`EventSource`/`fetch`): `llms/client.md`.',
|
|
1391
1458
|
" - `name` is the endpoint PATH within the group.",
|
|
1392
1459
|
' - A `{param}` segment is a URL PATH PARAM bound to the input of the same name, and segments chain: `name: "blog/{slug}/review/{review_id}"` + `input: { slug: input.text(), review_id: input.int() }`. Read it with `inp("slug")` like any other input.',
|
|
1393
|
-
" - Every `{param}` MUST have a matching input or `query()` THROWS \u2014 Xano
|
|
1394
|
-
' - A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded
|
|
1460
|
+
" - Every `{param}` MUST have a matching input or `query()` THROWS \u2014 Xano would treat an unbound marker as literal route text.",
|
|
1461
|
+
' - A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded.',
|
|
1395
1462
|
' - An input a `GET`/`DELETE`/`HEAD` looks ONE ROW up by (`s.db.get`/by-field edit/patch/delete; not `has` or an email/token/code) belongs in the path \u2014 `export()` warns `query.path-segment-candidate`: `getPath()` types STATIC. A segment is any value naming WHICH resource is wanted (`"shop/{country}"`); one that NARROWS A LIST (`s.db.query`) stays a query param. Intended? `diagnostics: { allow: [code] }` on the query (any def, for its own advisories) accepts it under `--strict`.',
|
|
1396
1463
|
' - Routes are matched FIRST-FIT in creation order, and a literal gets NO precedence over a `{param}`: `"runs/{id}"` (a text `id`) created before `"runs/trend"` answers `GET /runs/trend` itself. Two routes in one group and verb that one request path can match are REFUSED at `export()` (`query.route-shadowed`) \u2014 reordering `registerQueries` cannot fix it, since a release keeps an existing route first. Make the paths disjoint (`"runs/by-id/{id}"`), or declare a numeric param `input.int({ required: true })` (or `decimal`): only a REQUIRED int/decimal segment matches digits only \u2014 an OPTIONAL one matches any text, so `input.int()` still takes `trend`.',
|
|
1397
1464
|
" - Inputs absent from the path are ordinary query-string/body params.",
|
|
1398
|
-
' - Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`)
|
|
1465
|
+
' - Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`) THROWS \u2014 Xano would store an EMPTY name that deploys clean then 404s. Use `"export_zip"` and set the extension in the response headers.',
|
|
1399
1466
|
' - **Client recipe:** `q.getPath({ params: { slug: "hello" } })` \u2192 `/api:<canonical>/blog/hello` \u2014 never interpolate by hand.',
|
|
1400
1467
|
" - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a segment that becomes `.`/`..` as sent (a URL parser drops those before routing, addressing a different endpoint).",
|
|
1401
1468
|
" - The keys are typed from the literal `name`, so a typo is a compile error.",
|
|
1402
1469
|
" - `q.toSearchParams(input)` drops GET path params (free `query.toSearchParams` keeps them); lists send `k[]=a&k[]=b` (`k=a&k=b` binds only `b`).",
|
|
1403
1470
|
" - Browser bundle cost, the `routes.gen.ts` alternative (paths and request types), and spot-checking a def from Node: `llms/client.md`.",
|
|
1404
1471
|
"- `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors?, middleware? })` \u2014 a query container; queries bind to it via their `apiGroup`. `canonical` holds only letters, digits, `_` and `-` (it is the `<canonical>` of `/api:<canonical>`); anything else THROWS at build.",
|
|
1405
|
-
" - `documentation?`: `{ require_token? }` \u2014 the gate on this group's hosted docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid
|
|
1472
|
+
" - `documentation?`: `{ require_token? }` \u2014 the gate on this group's hosted docs; `swagger: true` publishes the docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid.",
|
|
1473
|
+
" - The block is ALWAYS emitted: an absent key is written as the engine default on import, so omitting it CLEARS an existing gate (the opposite of the `workspaceConfig` rule).",
|
|
1474
|
+
' - \u26A0 `require_token` gates them only alongside a non-empty token: `swagger: true` with no gate makes the whole group readable by anyone with the URL \u2014 export warns once per build and `--strict` fails; `diagnostics: { allow: ["api-group.docs-public"] }` accepts it.',
|
|
1475
|
+
" - A declared gate with NO token drops the block, clearing the gate: export FAILS under `swagger: true`, and with `swagger` off warns and completes.",
|
|
1476
|
+
" - A literal `token` FAILS the export.",
|
|
1406
1477
|
" - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.",
|
|
1407
|
-
' - `mode?`: `"default"` (the default) | `"custom"` | `"disabled"`, lowercase \u2014 a fourth value THROWS at export (`apiGroup()` itself does not check)
|
|
1478
|
+
' - `mode?`: `"default"` (the default) | `"custom"` | `"disabled"`, lowercase \u2014 a fourth value THROWS at export (`apiGroup()` itself does not check); otherwise Xano DROPS THE WHOLE API GROUP on import (deploy succeeds, every query 404s). \u26A0 Every OTHER field applies only under `"custom"`: `"default"` serves a FIXED permissive policy (any origin, `allow-headers: *`, `allow-credentials: true`, `max-age: 86400`) and ignores the block, so setting `maxAge`/`allowCredentials`/`allowHeaders` alone changes nothing. `"disabled"` sends no CORS headers at all, so every browser call fails.',
|
|
1408
1479
|
' - \u26A0 Under `"custom"`, `allowOrigins` is matched as EXACT strings (scheme+host+port, no wildcard or subdomain expansion) and `"*"` is compared as a literal origin \u2014 it matches NOTHING. An unmatched origin gets no `access-control-*` headers at all, so the browser call fails while export, deploy and the preflight look fine. Name each origin, or use `mode: "default"` for any-origin. `allowMethods` gates the REAL response too: a verb left off gets no CORS headers back even though its preflight passes. Export warns on an empty origin list, a `"*"` entry, and a policy with no method enabled; a non-origin entry (trailing `/`, path) is refused.',
|
|
1409
1480
|
"- Tasks, workflow tests, middleware and tools below (agents and MCP servers: `llms/kinds-agent-mcp.md`) share the envelope conventions (`guid?`, `description?`, `docs?`, `tags?`, `history?`) unless noted.",
|
|
1410
1481
|
"- `task({ name, guid?, description?, docs?, datasource?, active?, tags?, history?, schedule?, stack?, middleware? })` \u2014 a scheduled background job (function-like `stack`, no `input`/`response`). `active?` defaults `true`; `active: false` deploys it parked.",
|
|
1411
|
-
' - `schedule?`: a `ScheduleDef[]` (NOT a single object) \u2014 `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`. `startsOn`/`endsOn` are **timestamp strings** validated at encode time \u2014 `"2026-01-01T00:00:00Z"`, or the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries \u2014 never epoch numbers, and never zoneless; `freq` is the repeat interval **in SECONDS** (omitted \u21D2 runs ONCE) \u2014 spell it `every("15m")`, a compile-time duration-to-seconds helper (`s`/`m`/`h`/`d`/`w`, terms concatenate). No cron, no timezone \u2014 a fixed-offset `startsOn` drifts an hour at each DST change; for a local time run hourly, gated on the local hour `withFilters(c.now(), fl.epochms_date("G", "America/New_York"))`. `repeatEnabled?`/`endsEnabled?` follow whether `freq`/`endsOn` is set and are recovery-only \u2014 state one to reproduce a stored gate left OFF.
|
|
1412
|
-
'- `workflowTest({ name, guid?, description?, docs?, datasource?, active?, tags?, stack? })` \u2014 an end-to-end test. NO `input`/`response`: `.call` something with an `as`, then assert on that var \u2014 `s.function.call({ fn, input, as: "r" })`, `s.expect.to_equal({ expr: ref("r"), value: c.int(42) })`. `s.expect.*` belongs here \u2014 it is not inert elsewhere (a failure 500s the request), so treat one in a query/function/task as a mistake to remove. `active?` defaults `true`;
|
|
1413
|
-
' - `datasource?`: Default `""` is an EMPTY datasource (recommended), not "no datasource". Any non-empty name
|
|
1482
|
+
' - `schedule?`: a `ScheduleDef[]` (NOT a single object) \u2014 `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`. `startsOn`/`endsOn` are **timestamp strings** validated at encode time \u2014 `"2026-01-01T00:00:00Z"`, or the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries \u2014 never epoch numbers, and never zoneless; `freq` is the repeat interval **in SECONDS** (omitted \u21D2 runs ONCE) \u2014 spell it `every("15m")`, a compile-time duration-to-seconds helper (`s`/`m`/`h`/`d`/`w`, terms concatenate). No cron, no timezone \u2014 a fixed-offset `startsOn` drifts an hour at each DST change; for a local time run hourly, gated on the local hour `withFilters(c.now(), fl.epochms_date("G", "America/New_York"))`. `repeatEnabled?`/`endsEnabled?` follow whether `freq`/`endsOn` is set and are recovery-only \u2014 state one to reproduce a stored gate left OFF. Runs on every deploy target (`llms.txt` Gotchas).',
|
|
1483
|
+
'- `workflowTest({ name, guid?, description?, docs?, datasource?, active?, tags?, stack? })` \u2014 an end-to-end test. NO `input`/`response`: `.call` something with an `as`, then assert on that var \u2014 `s.function.call({ fn, input, as: "r" })`, `s.expect.to_equal({ expr: ref("r"), value: c.int(42) })`. `s.expect.*` belongs here \u2014 it is not inert elsewhere (a failure 500s the request), so treat one in a query/function/task as a mistake to remove. `active?` defaults `true`; `active: false` parks the test \u2014 `test run-all`/`deploy --test` SKIP it (reported `status: "skipped"`, never failing the suite), `test list` shows it `inactive`, and `test run "<name>"` still runs it. Chain tests with `s.workflow_test.call({ workflowTest: <def handle>, as: "child" })` then `s.expect.to_be_null({ expr: ref("child") })`, or a failing child passes the parent.',
|
|
1484
|
+
' - `datasource?`: Default `""` is an EMPTY datasource (recommended), not "no datasource". Any non-empty name is CLONED before EVERY run \u2014 against production-sized data, slow enough to fail the run; `"live"` warns at compile time. On an EPHEMERAL, `"live"` holds only the seed fixtures (plus rows a `--keep-data` deploy kept): the way to read `table({ seed })` rows \u2014 a small clone, dropped after the run. \u26A0 The value is STORED, so clear it before you promote or the same test clones the real database.',
|
|
1414
1485
|
"- `middleware({ name, guid?, description?, docs?, resultStrategy?, exceptionPolicy?, tags?, history?, input?, stack?, response?, responseShape?, tests? })` \u2014 a pre/post interceptor (function-like `stack`); attach it via a host's `middleware: { pre, post }`. \u26A0 `input` ENCODES but an ATTACHED middleware never has it bound \u2014 the host request binds its own inputs, so `inp()` inside pre/post fails at runtime with `Unable to locate input` and a declared default does not stand in (`export()` warns). Read the request body with `s.util.get_all_input` instead; it yields a `{ type, vars }` envelope whose `vars` DIFFERS BY PHASE: `pre` \u2192 the request inputs (`payload.vars.<field>`); `post` \u2192 `{ status, result }`, the host's outcome (`payload.vars.result.<field>`; plus `payload` on an error). A request field read in `post` 500s after the host already ran (`export()` warns); read the request there with `s.util.get_raw_input`. `s.middleware.call` is the one path that DOES bind the declared map.",
|
|
1415
|
-
' - `resultStrategy?`: `"merge" | "replace"` (default `merge`) \u2014 how the middleware `response` folds into
|
|
1416
|
-
' - `exceptionPolicy?`: `"silent" | "rethrow" | "critical"` (default `"rethrow"` \u2014 a throw ABORTS the request and surfaces the authored error/status
|
|
1417
|
-
"- `tool({ name, guid?, description?, instructions?, docs?, enabled?, title?, annotations?, icons?, output?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` \u2014 a function-like operation (`input`/`stack`/`response`) that a toolset (MCP server or agent) exposes. Register it, then reference it from a toolset's `tools`. `title`/`annotations`/`icons`/`output` are MCP metadata (`llms/kinds-agent-mcp.md`).",
|
|
1486
|
+
' - `resultStrategy?`: `"merge" | "replace"` (default `merge`) \u2014 how the middleware `response` folds into its phase\'s accumulator: in `post` the host\'s RESULT (changes what the CALLER receives), in `pre` the host\'s REQUEST INPUTS (changes what the HOST receives). `merge` folds key-by-key, `replace` substitutes wholesale; the next entry in the chain sees the updated value. `pre` + `replace` DISCARDS every caller input the middleware does not re-emit; reading a discarded input 500s, even one declared `required: false` (defaulting already ran).',
|
|
1487
|
+
' - `exceptionPolicy?`: `"silent" | "rethrow" | "critical"` (default `"rethrow"` \u2014 a throw ABORTS the request and surfaces the authored error/status). `"silent"` swallows the throw and admits the request; never use it on a guard. `"critical"` is `"rethrow"` plus skipping the `post` chain.',
|
|
1488
|
+
"- `tool({ name, guid?, description?, instructions?, docs?, enabled?, title?, annotations?, icons?, output?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` \u2014 a function-like operation (`input`/`stack`/`response`) that a toolset (MCP server or agent) exposes. Register it, then reference it from a toolset's `tools`. Name charset as a query's (`A-Za-z0-9_-/{}`, max 200). `instructions` is the description the MODEL/client sees (MCP `description`, agent-tool description) and what a connection trigger rewrites; it REPLACES `description`, which shows only when `instructions` is empty (both set warns `tool.description-shadowed`). `title`/`annotations`/`icons`/`output` are MCP metadata (`llms/kinds-agent-mcp.md`).",
|
|
1418
1489
|
'- An addon is a single table-bound db query, NOT a statement stack: `addon({ name, table, tableAlias?, where?, sort?, output: [cols], cardinality?: "single"|"list"|"count"|"exists"|"aggregate", group?, eval?, input?, context? })`, registered via `registerAddons([...])`.',
|
|
1419
1490
|
" - `table` auto-fills the `context.dbo` binding. \u26A0 Never author `table: null` \u2014 that is a BROKEN table-less addon returning nothing; `codegen` emits it only for an already-broken pulled object.",
|
|
1420
1491
|
' - `tableAlias` is its SQL alias (`context.dbo.as`), qualifying `where`/`sort` columns (`col("merchant.id")`).',
|
|
@@ -1442,7 +1513,7 @@ function renderSections(m) {
|
|
|
1442
1513
|
"surface \u2014 `s.conditional`/`s.while` `when` (incl. each `elif` branch), and",
|
|
1443
1514
|
"`db.query` `where`/`additionalWhere` (and the search triggers) \u2014 one shared tree.",
|
|
1444
1515
|
"",
|
|
1445
|
-
"- `op`:
|
|
1516
|
+
"- `op`: `=`/`==`/`!=` LOOSE (`null = 0` holds); `===`/`!==` STRICT; `>` `<` `>=` `<=`. Null check: `cond.isNull`.",
|
|
1446
1517
|
'- `left`/`right` are `Value`s \u2014 `col("x")` (a table column, `db.*` statements only), `ref`, `inp`, `auth(...)`, or `c.*`.',
|
|
1447
1518
|
"- For the full operator set (`in`/`like`/`ilike`/`between`/`contains`/`overlaps`/`@>`/`~`/`search`/\u2026)",
|
|
1448
1519
|
" use `cmp(left, op, right, { ignoreEmpty? })`; compose nested boolean logic with `and(...)`/`or(...)`.",
|
|
@@ -1456,7 +1527,7 @@ function renderSections(m) {
|
|
|
1456
1527
|
" `empty`/`notEmpty`, `isNull`/`notNull`, `between(v, lo, hi)`, `has(obj, path)`, `count(v, n)`.",
|
|
1457
1528
|
" Each returns a `Comparison`, usable anywhere `expr(...)` is.",
|
|
1458
1529
|
"- A condition/`where` accepts a single `expr(...)`/`cmp(...)`, an `and()`/`or()` group, an array of",
|
|
1459
|
-
" those (ANDed)
|
|
1530
|
+
" those (ANDed). `s.conditional`/`s.while`/`s.switch`, `db.query`,",
|
|
1460
1531
|
" `precondition`, and the `array.*` predicates all take the same TREE shape (operators per above).",
|
|
1461
1532
|
"- \u26A0 `mixed(a, { or: b }, { and: c })` reproduces a container whose terms do NOT all join the",
|
|
1462
1533
|
" same way \u2014 pulled workspaces contain it. **Do not author it** (export warns `condition.mixed`). The",
|
|
@@ -1476,8 +1547,8 @@ function renderSections(m) {
|
|
|
1476
1547
|
""
|
|
1477
1548
|
];
|
|
1478
1549
|
const kindsKnowledge = [
|
|
1479
|
-
"- `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` \u2014 markdown shared by every AI that builds the backend
|
|
1480
|
-
' - `body` (REQUIRED): `knowledgeFile("./runbook.md", import.meta.url)` \u2014 a path to a real markdown FILE. There is no inline-string form. The path resolves relative to the MODULE THAT DECLARES the item
|
|
1550
|
+
"- `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` \u2014 markdown shared by every AI that builds the backend. Xano's own AI reads it before it acts: the workspace's builder agent, and outside agents reading the workspace through the Meta API or MCP. A local coding agent reads the same `.md` files in the repo; deploy and `pull` keep the copies in sync. It does NOT reach an `agent()` run by `s.ai.agent.run`, whatever its `type` or `mode`: put what such an agent must know in its `llm.systemPrompt`. Takes `registerKnowledge`.",
|
|
1551
|
+
' - `body` (REQUIRED): `knowledgeFile("./runbook.md", import.meta.url)` \u2014 a path to a real markdown FILE. There is no inline-string form. The path resolves relative to the MODULE THAT DECLARES the item (not the working directory or the workspace entry), via the required `import.meta.url`.',
|
|
1481
1552
|
' - `refs?`: `knowledgeDir("./runbook", import.meta.url)` \u2014 a directory whose WHOLE tree ships, recursively, paths preserved: UTF-8 text only (else refused; binary `.DS_Store` skipped), symlinks not followed. Keep the body OUT of it, or it ships as a reference file.',
|
|
1482
1553
|
' - `type?`: `"skill"` (default) | `"doc"` | `"agents.md"`. `skill` and `doc` differ in how they are filed, not in what an agent receives.',
|
|
1483
1554
|
' - `mode?`: `"auto"` (default) | `"always"` | `"referenced"`.',
|
|
@@ -1490,28 +1561,31 @@ function renderSections(m) {
|
|
|
1490
1561
|
'- `mode: "referenced"` \u2014 full body only on turns whose message names the item (bare name or `@name`).',
|
|
1491
1562
|
'- `mode: "auto"` \u2014 name and `description` only; the agent loads the body when a request matches.',
|
|
1492
1563
|
'- Reference files are never injected wholesale \u2014 an agent searches them on demand. That is what makes a large `mode: "auto"` item cheap.',
|
|
1493
|
-
'- \u26A0 `mode: "always"`
|
|
1494
|
-
"- `name` takes letters, digits, and
|
|
1564
|
+
'- \u26A0 `mode: "always"` costs the full body on every request (nothing in the types flags it). For an `auto` item `description` is ALL the agent sees until it decides to load the body, so write it to be matched against a request rather than as a title.',
|
|
1565
|
+
"- `name` takes letters, digits, space, and `/` `_` `-` `{` `}` `.`; anything else is an export error."
|
|
1495
1566
|
];
|
|
1496
1567
|
const toolchain = [
|
|
1497
1568
|
"**Toolchain modules** extend the CLI, not the workspace \u2014 nothing to register in",
|
|
1498
1569
|
"`xano/index.ts`. An installed one runs on `export` and `deploy` (after the compile,",
|
|
1499
1570
|
"before the upload) and is verified, never rewritten, under `--frozen-lock`. Config",
|
|
1500
1571
|
'lives in this project\'s `package.json` `"xanosdk"` block, keyed by package name.',
|
|
1501
|
-
"
|
|
1502
|
-
"
|
|
1503
|
-
"
|
|
1504
|
-
"
|
|
1505
|
-
"
|
|
1506
|
-
"
|
|
1507
|
-
"
|
|
1508
|
-
"
|
|
1572
|
+
"",
|
|
1573
|
+
"- `marketplace install <pkg>` is not just `npm install`: it asks the module its questions",
|
|
1574
|
+
" and writes that block plus the `.gitattributes` lines it contributes. It also adds the",
|
|
1575
|
+
" module's non-SDK peers (e.g. `zod`) as direct dependencies.",
|
|
1576
|
+
"- A module that arrived any other way (a plain `npm install`, a merged PR) is configured by",
|
|
1577
|
+
" running that same command on it; until then `export`/`deploy` report it unconfigured and it runs on",
|
|
1578
|
+
" shipped defaults.",
|
|
1579
|
+
"- `marketplace reinstall <pkg>` re-asks with the current settings as the defaults and",
|
|
1580
|
+
" re-enables a disabled one.",
|
|
1581
|
+
"- `marketplace remove <pkg>` drops block, lines and dependency together. A plain",
|
|
1582
|
+
" `npm uninstall` leaves the block, and a package it names that is no longer installed",
|
|
1583
|
+
" fails every `--frozen-lock` run.",
|
|
1509
1584
|
"",
|
|
1510
1585
|
"**A module's section of `xano/routes.gen.ts`.** A module with a `routesManifest` hook (types:",
|
|
1511
1586
|
"`@xano/sdk/plugin`) writes a block between `// xanosdk:begin <pkg>` and `// xanosdk:end <pkg>`",
|
|
1512
1587
|
"after the core sections, on every write of the file (`routes --emit`, `xano:routes`, `pull`,",
|
|
1513
1588
|
"`generate`, `marketplace install|reinstall|remove`). Edits inside the block are overwritten.",
|
|
1514
|
-
"Install also adds the module's non-SDK peers (e.g. `zod`) as direct dependencies.",
|
|
1515
1589
|
"The hook is synchronous and pure: given",
|
|
1516
1590
|
"the request inputs under the manifest's keys and its config, it returns `{ imports?, source }`,",
|
|
1517
1591
|
"imports as bare package names (`@xano/sdk*`, relative and `node:` are refused). A module that",
|
|
@@ -1526,11 +1600,10 @@ function renderSections(m) {
|
|
|
1526
1600
|
" no Node built-ins, so a bundler drops unused SDK exports. But importing a **def** for its",
|
|
1527
1601
|
" `getPath()`/`verb`/`getUrl()`/`getChannel()` also pulls whatever its `stack` references:",
|
|
1528
1602
|
" the `s.*`/`c.*` factory CALLS run at module load to BUILD it. Types are free.",
|
|
1529
|
-
"
|
|
1530
|
-
"
|
|
1531
|
-
" adds ~2 kB, so trimming a def does not shrink it.",
|
|
1603
|
+
" The first def costs **~267 kB minified (~65 kB gzipped)**; the floor is the RUNTIME, not the def:",
|
|
1604
|
+
" each further def adds ~2 kB, so splitting or trimming defs does not help.",
|
|
1532
1605
|
" Fix: `npx @xano/sdk routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) \u2014 verbs, paths, and sockets as",
|
|
1533
|
-
' plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`',
|
|
1606
|
+
' plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`, `routeQuery("GET search", input)` (the GET query string, path params dropped),',
|
|
1534
1607
|
' `channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base',
|
|
1535
1608
|
' URLs lifted to `wss://h/ws/<tenant>:<canonical>`), `mcpUrl("notes_mcp", baseUrl)` (an MCP',
|
|
1536
1609
|
" server's address to show a user or hand a client; browser JS cannot call it). A rename is a type error, not a 404.",
|
|
@@ -1539,38 +1612,43 @@ function renderSections(m) {
|
|
|
1539
1612
|
' `"<channel key> <message name>"`: `type NewListing = RouteInputs["POST listings"]`. A',
|
|
1540
1613
|
" frontend types bodies, channel params and payloads from these, not `InferInput` on a def;",
|
|
1541
1614
|
" keep `InferInput` in code that already imports defs. They match `InferInput`, except a",
|
|
1542
|
-
" `dbLink` input
|
|
1615
|
+
" `dbLink` input is the linked table's columns, and an `input.file()` a `Blob`",
|
|
1616
|
+
" (multipart). Responses",
|
|
1543
1617
|
" are not in the file: `InferResponse` on an `import type` of the def.",
|
|
1544
1618
|
" Runtime validation: `npx @xano/sdk marketplace install zod` adds `@xano-sdk/zod`, which writes",
|
|
1545
1619
|
" `ROUTE_SCHEMAS`/`CHANNEL_SCHEMAS`/`MESSAGE_SCHEMAS` into the file under the same keys, each",
|
|
1546
1620
|
" checked against its type at typecheck; the file then imports `zod`, never `@xano/sdk`.",
|
|
1547
|
-
"- **Verifying a def outside a bundler.** Inside a bundler (Vite/webpack)
|
|
1548
|
-
"
|
|
1549
|
-
'
|
|
1550
|
-
"
|
|
1551
|
-
"
|
|
1552
|
-
"
|
|
1553
|
-
"
|
|
1554
|
-
"",
|
|
1555
|
-
"
|
|
1556
|
-
"
|
|
1557
|
-
"
|
|
1558
|
-
"
|
|
1621
|
+
"- **Verifying a def outside a bundler.** Inside a bundler (Vite/webpack), import the def and read",
|
|
1622
|
+
" `getPath()`/`verb` directly. From Node, run a REAL file with `tsx <file.ts>` **from inside the project root**.",
|
|
1623
|
+
' Not `tsx -e "import \u2026"` (mis-resolves the package `exports` map \u2192 ERR_PACKAGE_PATH_NOT_EXPORTED),',
|
|
1624
|
+
" not bare `node file.ts` (cannot resolve the `.js`-specifier intra-workspace imports), and not from",
|
|
1625
|
+
" outside the project root (the `@xano/sdk` specifier does not resolve).",
|
|
1626
|
+
"",
|
|
1627
|
+
"**Reading the injected backend URL.**",
|
|
1628
|
+
"",
|
|
1629
|
+
"- `npx @xano/sdk deploy <entry> --static <dir>` writes the deployed env's URL into every html",
|
|
1630
|
+
" document. A prerendered build serves a different one per route; a route without the global",
|
|
1631
|
+
" renders fine while every call goes to the wrong origin.",
|
|
1632
|
+
"- Read it at runtime with a build-time fallback:",
|
|
1559
1633
|
" const HOST = (typeof window !== 'undefined' && window.XANO_HOST) || import.meta.env.VITE_XANO_HOST;",
|
|
1560
|
-
"The scaffold's `lib/api.ts` types it (`interface Window { XANO_HOST?: string }` \u2014 `undefined` in dev)",
|
|
1561
|
-
"and exports this as a `string`, `XANO_HOST`; outside a scaffold declare the global yourself.",
|
|
1562
|
-
"In LOCAL DEV there is no injected global, so the fallback
|
|
1563
|
-
"
|
|
1564
|
-
"
|
|
1565
|
-
"
|
|
1566
|
-
|
|
1567
|
-
|
|
1568
|
-
"
|
|
1569
|
-
"bare `XANO_HOST` token.",
|
|
1634
|
+
"- The scaffold's `lib/api.ts` types it (`interface Window { XANO_HOST?: string }` \u2014 `undefined` in dev)",
|
|
1635
|
+
" and exports this as a `string`, `XANO_HOST`; outside a scaffold declare the global yourself.",
|
|
1636
|
+
"- In LOCAL DEV there is no injected global, so the fallback answers: set `VITE_XANO_HOST` in a",
|
|
1637
|
+
" `.env.local` beside `.env.example` at the PROJECT ROOT. The scaffold's vite config sets `envDir`",
|
|
1638
|
+
" there (its `root` is `frontend/`, and Vite resolves `.env` files against `root`); without it the",
|
|
1639
|
+
" var reads as undefined, the host falls back to '', and every call 404s off the dev server.",
|
|
1640
|
+
'- It is injected in bracket form \u2014 `window["XANO_HOST"]="\u2026"` \u2014 so grepping a deploy for',
|
|
1641
|
+
" `window.XANO_HOST` matches nothing. Grep the bare `XANO_HOST` token.",
|
|
1642
|
+
"",
|
|
1570
1643
|
"**Frontend without the backend.** `npx @xano/sdk publish <dir> [--to <backend>]` uploads an",
|
|
1571
1644
|
"already-built directory and nothing else \u2014 no compile, no import (scaffold script",
|
|
1572
1645
|
"`npm run xano:deploy:frontend`). A Xano Engine (`--to local`, or bare after a local",
|
|
1573
1646
|
"deploy) serves it, server half included, at `http://<prefix>.localhost:<port>`.",
|
|
1647
|
+
"The injected `XANO_HOST` is the DESTINATION's URL, so one build published to two",
|
|
1648
|
+
"destinations serves two different documents. `--release <name>` checks only that the",
|
|
1649
|
+
"release exists; `--branch <label>` (workspace only) refuses unless that label is LIVE \u2014",
|
|
1650
|
+
"a label match, not a content comparison. `--json` reports `published` and `verified` separately.",
|
|
1651
|
+
"",
|
|
1574
1652
|
"**Server-rendered SvelteKit.** `adapter()` from `@xano/sdk/sveltekit` (needs `esbuild`) writes",
|
|
1575
1653
|
"the static half at the build's root plus a server half in `.xano-ssr/`. A Xano Engine renders every",
|
|
1576
1654
|
"path that is not a file through it (`load` reads the engine's own URL as `XANO_HOST` from",
|
|
@@ -1579,16 +1657,30 @@ function renderSections(m) {
|
|
|
1579
1657
|
"shell, where a route with a server `load` fails (no `__data.json`). A scaffolded project configures",
|
|
1580
1658
|
"SvelteKit in `vite.config.ts`'s `sveltekit({ adapter })`, where `svelte.config.js` is ignored.",
|
|
1581
1659
|
"\u26A0 `.xano-ssr/server.js` inlines `$env/static/private` values; it is never served (`/.xano-ssr/` answers 404).",
|
|
1582
|
-
"
|
|
1583
|
-
"
|
|
1584
|
-
"
|
|
1585
|
-
"
|
|
1586
|
-
"
|
|
1587
|
-
"
|
|
1588
|
-
"
|
|
1589
|
-
"
|
|
1590
|
-
|
|
1591
|
-
"
|
|
1660
|
+
"",
|
|
1661
|
+
"**Displaying a stored file.** A file column comes back as `{ path, name, type, size, mime,",
|
|
1662
|
+
"meta, access, url }` \u2014 `mime` is the exact media type (`image/png`), `type` only the coarse",
|
|
1663
|
+
"kind (`image`). Do not use its `url`: on a tenant-scoped environment it addresses the",
|
|
1664
|
+
"instance host without the `/tenant/<name>` segment and 404s (a broken `<img>`; API",
|
|
1665
|
+
"assertions still pass). Build the URL from `path`: `fileUrl(row.avatar, HOST)` returns `null`",
|
|
1666
|
+
"for an absent file and is correct on an ephemeral and an instance workspace alike.",
|
|
1667
|
+
"",
|
|
1668
|
+
'**Consuming a streaming response.** A `responseType: "stream"` query emits Server-Sent Events \u2014',
|
|
1669
|
+
"`Content-Type: text/event-stream`, one `data: <json>` frame per `s.api.stream({ value })` call,",
|
|
1670
|
+
"each with an `id:` line that is a millisecond timestamp (ids REPEAT within a ms, so do not rely on",
|
|
1671
|
+
"`Last-Event-ID` for exactly-once resume). The query's own `response` is not sent. Read it with",
|
|
1672
|
+
"`EventSource`:",
|
|
1673
|
+
" const es = new EventSource(`${HOST}/api:<canonical>/stream/basic`);",
|
|
1674
|
+
" es.onmessage = (e) => { const chunk = JSON.parse(e.data); /* \u2026 */ };",
|
|
1675
|
+
" es.onerror = () => es.close(); // EventSource is GET-only and reconnects on its own",
|
|
1676
|
+
"For POST or auth headers, a `fetch` + `response.body.getReader()` loop instead, splitting the text",
|
|
1677
|
+
"on the blank-line (`\\n\\n`) frame delimiter and stripping the `data: ` prefix. There is no typed",
|
|
1678
|
+
"client helper for the stream body, and `InferResponse` does not describe it.",
|
|
1679
|
+
"**Error responses.** A failed request answers a JSON envelope `{ code, message, payload }`:",
|
|
1680
|
+
"`if (!res.ok) { const { code, message, payload } = await res.json(); \u2026 }`. `code` is an",
|
|
1681
|
+
"`ERROR_CODE_*` string (`ERROR_FATAL` for an engine error), `message` the human text (\u26A0 EMPTY",
|
|
1682
|
+
'on a `db` NotFound), `payload` a precondition\'s structured detail (`""`/absent otherwise).',
|
|
1683
|
+
"The `error_type` \u2192 HTTP status and `code` mapping is in `llms/fields.md`."
|
|
1592
1684
|
];
|
|
1593
1685
|
const errors = [
|
|
1594
1686
|
"### Request-time (deployed) failures",
|
|
@@ -1600,34 +1692,54 @@ function renderSections(m) {
|
|
|
1600
1692
|
"- `Value is less than the minimum value of 1` (HTTP 400) \u2014 a `db.get` given `0` in an editor-authored workspace (SDK field-match `db.get` answers 200 + null). `llms/statements-data.md`.",
|
|
1601
1693
|
"- `Invalid op: <op>` \u2014 a `cmp` operator (`in`, `like`, \u2026) in a RUNTIME condition, which takes the `expr` set only; write `or(expr(...), expr(...))`. `llms/kinds-core.md`.",
|
|
1602
1694
|
"- `Unsupported param format` / `Unsupported parameter reference` \u2014 an aggregate or `eval` `name` that is not a bare column, or a bare `eval` name for a joined column. `llms/statements-data.md`.",
|
|
1603
|
-
"- `ParseError: Invalid value for param` (HTTP 400) \u2014 `contains`/`@>`/`overlaps` on a text column (use `includes
|
|
1695
|
+
"- `ParseError: Invalid value for param` (HTTP 400) \u2014 `contains`/`@>`/`overlaps` on a text column (use `includes`, for scalar text only: a list column 500s), or a joined column qualified without `tableAlias`. `llms/statements-data.md`.",
|
|
1604
1696
|
"- `ERROR_FATAL: <Type> does not exist: <type>:<n>` \u2014 `s.api.call`/`s.task.call`/`s.trigger.call`/`s.workflow_test.call` outside a workflow test; share logic via `defineFunction` + `s.function.run`. `llms.txt`.",
|
|
1605
1697
|
'- `ERROR_FATAL "Unable to decode."` \u2014 a populated JSON string where the engine expects `c.obj`\'s form; write `c.obj({...})` or `obj({...})`. `llms/values.md`.',
|
|
1698
|
+
'- `ERROR_FATAL "Invalid zip"` on `s.zip.view_contents`/`extract` of an uploaded `input.file` \u2014 the CLIENT-supplied Content-Type was not `application/zip` (the bytes are not checked; curl\'s `-F` default is `application/octet-stream`). Send `new File([\u2026], "x.zip", { type: "application/zip" })`. A wrong password (`Extraction failed (wrong password?)`) and a non-zip both 500 \u2014 wrap the call in `s.try_catch`. `llms/statements-runtime.md`.',
|
|
1699
|
+
'- `ERROR_FATAL "Infinite recursion detected. Please fix."` \u2014 `s.function.run`/`.call` nested past ~25 deep in one request (the engine\'s variable-stack limit), even for correct bounded recursion. Recurse iteratively (`s.while` over an explicit list) or batch. `llms/statements-calls.md`.',
|
|
1606
1700
|
'- `Precondition failed.` in place of your message \u2014 `error` was a bare string; pass `c.text("\u2026")`. `llms/fields.md`.',
|
|
1607
1701
|
"- `Param: token - Text filter requires an integer, float, string or boolean value` \u2014 `s.api.call` `auth.token` given a tagged `Value`; it must be a bare string. `llms/statements-calls.md`.",
|
|
1608
1702
|
"- Every `s.db.add` into one table 400s naming a column while complaining about its VALUE \u2014 the column is named `run`. `llms.txt`.",
|
|
1609
|
-
'- HTTP 200 with an EMPTY body where `0` was expected \u2014 a bare `returnType: "count"` of zero; wrap it as `{ count: ref("n") }`. `llms/statements-data.md`.',
|
|
1703
|
+
'- HTTP 200 with an EMPTY body where `0` was expected \u2014 a bare `returnType: "count"` of zero can answer either; wrap it as `{ count: ref("n") }`. `llms/statements-data.md`.',
|
|
1610
1704
|
"- HTTP 200 with `[]` from a `db.query` that matches rows \u2014 a paged query (`metadata: true`, the default) whose `output` names bare columns; the selection applies to the ENVELOPE, so prefix them (`items.<column>`) or set `metadata: false` inside `paging`. `llms.txt`; `llms/statements-data.md`.",
|
|
1611
1705
|
"- Every field mapped off an `s.api.request` result reads `null` \u2014 the upstream answered an error (a 403 for a missing `User-Agent` is the common one) and its body arrived as ordinary `response.result`; send a `User-Agent` and gate on `response.status`. `llms/statements-calls.md`.",
|
|
1612
1706
|
'- A lambda returns error TEXT with HTTP 200 (`Could not resolve "node:crypto"`, an undefined-binding message) \u2014 the body threw; use the preloaded globals, the surface\'s bindings, and `capture`. `llms/lambda.md`.',
|
|
1613
1707
|
"- `Unable to locate request.` (404) on an endpoint that deployed \u2014 a lowercase verb, a `.` in the name, or a CORS `mode` typo that dropped the whole API group. `llms/kinds-core.md`.",
|
|
1614
1708
|
'- A browser call fails on a missing `access-control-allow-origin` while deploy looks fine \u2014 CORS `mode: "custom"` with `"*"` or an unmatched origin. `llms/kinds-core.md`.',
|
|
1615
|
-
"-
|
|
1616
|
-
"- `
|
|
1709
|
+
"- `ERROR_FATAL` `The free model is not available in this process.` \u2014 an `xano-free` agent run on a Xano Engine; it runs only on Xano's cloud. `llms/kinds-agent-mcp.md`.",
|
|
1710
|
+
"- `Not supported. Please upgrade your Xano instance.` (HTTP 403) \u2014 a capability the instance lacks; on the Xano Engine on this machine, every `s.storage.sign_private_url` answers it. Test it with `deploy --ephemeral`. `llms/fields.md`.",
|
|
1711
|
+
"- An MCP `tools/call` answers `isError: true` with `Unable to get successful response from executing tool` \u2014 the tool's run failed without a usable `{code, message}`, and the authored message is dropped. Common cause: a tool reading `auth()` behind an entry naming no auth table (`export()` warns `toolset.tool-reads-auth-ungated`); wrap it `{ tool: <handle>, auth: <auth table> }`. `llms/kinds-agent-mcp.md`.",
|
|
1617
1712
|
"- A websocket is closed right after the handshake \u2014 a refused `connect` gate: an empty/falsy return, a crash, or a gating trigger with no `response`. `llms/triggers.md`.",
|
|
1618
1713
|
"- `to_throw failed - response is ok` around an auth-refused call \u2014 `ERROR_CODE_ACCESS_DENIED` carries no message; the auth gate is not reachable from a workflow test. `llms/tests.md`.",
|
|
1619
1714
|
"- Output reads `Hi [object Object]` \u2014 a tagged value inside a JS template literal; compose at runtime with `withFilters` + `fl.concat`. `llms.txt`.",
|
|
1620
1715
|
"",
|
|
1621
1716
|
"### Build-time and tooling failures",
|
|
1622
1717
|
"",
|
|
1623
|
-
'- `export --strict` fails on a warning whose shape is meant (a fixture pinning a hazard) \u2014 accept it on ITS def only
|
|
1718
|
+
'- `export --strict` fails on a warning whose shape is meant (a fixture pinning a hazard) \u2014 accept it on ITS def only: add `diagnostics: { allow: ["<code>"] }`, which takes any warning code that def raised, on any def kind (warnings only, never an error). Accepted warnings are still listed: `export({ accepted: [] })`, `--json` `accepted[]`. An allowed code the def no longer raises warns `diagnostics.allow-unused`.',
|
|
1624
1719
|
'- `must be ES modules` \u2014 package.json says `"type": "commonjs"`; set `"type": "module"`. `llms.txt` Quickstart.',
|
|
1625
1720
|
"- A response types as `StackTupleWidened` \u2014 a `Statement[]` helper was spread into the stack; return `statements(...)`. `llms.txt`; `llms/statements-runtime.md`.",
|
|
1626
1721
|
'- `ERR_PACKAGE_PATH_NOT_EXPORTED` \u2014 `tsx -e "import \u2026"`, or running from outside the project root; run a real file with `tsx <file.ts>` from the root. `llms/client.md`.',
|
|
1627
1722
|
"- `Missing statement: mvp:placeholder` on import \u2014 an unconfigured slot in a pulled tree; replace it with the statement it stands in for. `llms/legacy.md`.",
|
|
1628
|
-
'- A CLI command fails under `--json` or piped (unless stdout carries data): stdout is `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }`, as does a failed release write. Codes: `SDK_SEED_IN_STATIC` (`details.leaks[]` \u2192 `publicSeed`), `SDK_EXPORT_INVALID` (`details.diagnostics[]`, `--strict` too), `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_LIVE_BRANCH_MISMATCH` (`details.conflictsWith`), `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_CREDENTIAL_REJECTED` (`details`: `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh), `SDK_WORKSPACE_CHANGED` (deploy over objects edited in Xano since the last sync; `details.objects`; pull first or `--overwrite`), `SDK_USAGE` (`details.reason: "needs-confirmation"`: run its `Re-run as`), `SDK_ERROR`. Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope. `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def\'s `{ kind, name }`). Backend documents add `selector` and `workspaceId`.',
|
|
1629
1723
|
"- A CLI command reports `could not reach <url>: fetch failed (<code>)` \u2014 blocked egress, not a bad credential; fix it before `npx @xano/sdk login`, which rotates a single-use refresh token.",
|
|
1630
1724
|
"",
|
|
1725
|
+
"### CLI failure documents",
|
|
1726
|
+
"",
|
|
1727
|
+
"A CLI command that fails under `--json` or piped (unless stdout carries data) writes `{ ok: false, error: { code, message, exitCode, details?, suggestion? } }` to stdout, as does a failed release write. Codes:",
|
|
1728
|
+
"",
|
|
1729
|
+
"| `code` | `details` |",
|
|
1730
|
+
"|---|---|",
|
|
1731
|
+
"| `SDK_SEED_IN_STATIC` | `details.leaks[]` \u2192 `publicSeed` |",
|
|
1732
|
+
"| `SDK_EXPORT_INVALID` | `details.diagnostics[]`, `--strict` too |",
|
|
1733
|
+
"| `SDK_LIVE_BRANCH_MISMATCH` | `details.conflictsWith` |",
|
|
1734
|
+
"| `SDK_CREDENTIAL_REJECTED` | `{ profile, credentialType, instance, workspaceId, signIn }`; ids null on a refused env refresh |",
|
|
1735
|
+
"| `SDK_WORKSPACE_CHANGED` | `details.objects`: objects edited in Xano since the last sync. Pull first or deploy `--overwrite`. |",
|
|
1736
|
+
'| `SDK_USAGE` | `details.reason: "needs-confirmation"`: run its `Re-run as` |',
|
|
1737
|
+
"| `SDK_DRIFT`, `SDK_BRANCH_TAKEN`, `SDK_BRANCH_LIVE`, `SDK_RELEASE_NAME_TAKEN`, `SDK_RELEASE_FILES_NOT_CARRIED`, `SDK_IDENTITY_CONFLICT`, `SDK_KIND_CONFLICT`, `SDK_PRUNE_OUT_OF_SCOPE`, `SDK_IMPORT_REFUSED`, `SDK_SHARED_SCHEMA_CHANGE`, `SDK_CONSTRAINT_VIOLATION`, `SDK_ERROR` | \u2014 |",
|
|
1738
|
+
"",
|
|
1739
|
+
"- Landing refusal `details.refused`: identityConflict, renamePending, kindConflict, uniqueViolation, tableTrigger, importInProgress, importRefused, pruneOutOfScope.",
|
|
1740
|
+
"- `warnings[]` / `details.warnings` / `accepted[]` entries: `{ code, message, subject? }` (`subject`: the def's `{ kind, name }`).",
|
|
1741
|
+
"- Backend documents add `selector` and `workspaceId`.",
|
|
1742
|
+
"",
|
|
1631
1743
|
"### CLI exit codes",
|
|
1632
1744
|
"",
|
|
1633
1745
|
"A failure document's `exitCode` matches.",
|
|
@@ -1648,32 +1760,33 @@ function renderSections(m) {
|
|
|
1648
1760
|
];
|
|
1649
1761
|
const kindsAgentMcp = [
|
|
1650
1762
|
"- An MCP server serves THREE primitives, and each reaches the client differently: a `tool()` is an action the MODEL calls (it may write); a `resource()` is read-only context the client APPLICATION lists and attaches by `uri` (reference docs, a schema, one record through a `{variable}` template); a `prompt()` is a message template with arguments the USER picks by name. Context a session opens with is a `resource()`; a workflow a user starts by name is a `prompt()`; data the model must fetch on its own mid-task stays a `tool()`, since a client shows the model only the resources attached to the conversation. Register each kind (`registerTools`/`registerPrompts`/`registerResources`) and list it on the server.",
|
|
1651
|
-
"- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, prompts?, resources?, oauth?, llm?, output? })` \u2014 an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent
|
|
1652
|
-
" - \u26A0
|
|
1653
|
-
' - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`); use the `{ tool, enabled?, auth?, type?, resourceUri?, toolMeta? }` wrapper when an entry needs more. `type: "resource"` (+ a required `resourceUri`)
|
|
1763
|
+
"- `mcpServer({ name, guid?, description?, instructions?, docs?, enabled?, canonical?, spec?, tags?, history?, tools?, prompts?, resources?, oauth?, llm?, output? })` \u2014 an MCP toolset. `llm?`/`output?` are the same blocks `agent()` takes and are usually absent. Returns a handle with `getPath()`/`getUrl(baseUrl)` for the Streamable-HTTP endpoint \u2014 `getUrl` is NOT idempotent, a `baseUrl` already carrying an `/x2/mcp/<\u2026>/stream` path THROWS, so resolve ONCE from the instance base URL. Fires on an ephemeral. A TENANT rides AFTER the prefix (`/x2/mcp/tenant/<tenant>/<canonical>/<token>/stream`), not as a base-URL segment: `getUrl` LIFTS a `/tenant/<name>` out of the base and re-places it there, so `getUrl(window.XANO_HOST)` is correct as-is; concatenating them by hand builds an unregistered route that 404s. Pass `{ tenant }` when the base URL cannot name it (a tenant on its own domain).",
|
|
1764
|
+
" - \u26A0 The endpoint is CORS-open (serves every browser `Origin`; preflight `204`, `access-control-allow-origin: *`); per-tool `auth`/`oauth` is the only gate.",
|
|
1765
|
+
' - `tools?`: a `ToolsetToolEntry[]`. Pass the `tool()` HANDLES directly (`tools: [saveNote]`); use the `{ tool, enabled?, auth?, type?, resourceUri?, toolMeta? }` wrapper when an entry needs more. `type: "resource"` (+ a required `resourceUri`) publishes a tool as an MCP resource \u2014 prefer a `resource()` listed in `resources`; `toolMeta` is extra metadata on a tool entry. `resourceUri` only with `type: "resource"`, `toolMeta` only with `type: "tool"`; the wrong one is refused. `auth` names an auth **table** (a `table({ auth: true })` handle or its name) \u2014 per-tool, and the only gate there is. \u26A0 It is also what gives the tool a CALLER, on an `agent()` and an MCP server alike. `auth()` inside a tool whose entry names no table does NOT return null: the run binds `{"code":"ERROR_FATAL","message":""}`. On an `agent()` the model reads that as a successful tool result and reports success while nothing is written; over an MCP server\'s `tools/call` the client instead gets an `isError: true` tool error with the generic text `Unable to get successful response from executing tool`. Either way the write never happens and a caller token does not rescue it \u2014 the ENTRY supplies identity. Spell it `{ tool: saveNote, auth: users }`; `export()` warns. An entry naming no tool THROWS at export; a deliberate raw `id: 0` warns and carries through.',
|
|
1654
1766
|
' - `prompts?` / `resources?`: `prompt()` / `resource()` HANDLES (or names), or a `{ prompt, enabled?, auth? }` / `{ resource, enabled?, auth? }` wrapper. `auth` names the auth table and is what gives the stack a caller: a prompt/resource reading `auth()` behind an entry with none answers every `prompts/get` / `resources/read` with `-32603 "Access Denied"` (`export()` warns `toolset.primitive-reads-auth-ungated`). Listing one target twice THROWS; two resources with one `uri` on one server fail `export()` (`mcp.resource-uri-duplicate`). MCP-server only \u2014 `agent()` takes tools only.',
|
|
1655
1767
|
" - `history?` is the server tier for its tools, prompts AND resources alike; an object's own `history` wins. The workspace tier (`workspaceConfig({ history })`) has `prompt` and `resource` keys, both default on.",
|
|
1656
1768
|
' - `oauth?`: per-server sign-in; omit and nothing changes. Union on `mode`; `authTable` (REQUIRED, auth `table()` handle or name) is whose row the signed-in user is \u2014 `auth()` on the whole server, `t.auth` in its trigger. Hosted (the platform is the authorization server): `{ mode: "hosted", authTable, loginUrl }` \u2014 clients are sent to `loginUrl` (YOUR page, which is also the consent screen) with `mcp_request`; show `s.mcp.oauth.request`, sign the user in, then your endpoint calls `s.mcp.oauth.complete` with their `decision` and the page redirects to the URL it binds. External (your IdP issues tokens): `{ mode: "external", authTable, issuer, column, audience?, audienceAck?, claim?, claimAck?, preset?, allowedClientIds? }` \u2014 token `claim` (default `sub`) matched against `column`; `preset` is `auth0|clerk|workos|entra|okta|cognito|generic`. `loginUrl`/`issuer`/`audience` take `env("NAME")` (resolved per environment).',
|
|
1657
|
-
' - `export()` FAILS: hosted without `loginUrl` (`mcp.oauth-hosted-incomplete`); external without `issuer`/`column` (`mcp.oauth-external-incomplete`); `preset: "clerk"` without `allowedClientIds` (`mcp.oauth-preset-client-ids`); `claim` other than `sub`/`oid`/`email` without `claimAck` (`mcp.oauth-claim-unacked` \u2014 users can edit it at most providers). Unknown `mode`/`preset` THROWS
|
|
1769
|
+
' - `export()` FAILS: hosted without `loginUrl` (`mcp.oauth-hosted-incomplete`); external without `issuer`/`column` (`mcp.oauth-external-incomplete`); `preset: "clerk"` without `allowedClientIds` (`mcp.oauth-preset-client-ids`); `claim` other than `sub`/`oid`/`email` without `claimAck` (`mcp.oauth-claim-unacked` \u2014 users can edit it at most providers). Unknown `mode`/`preset` THROWS, as do `consent`/`branding`/`trustedClients` (not options).',
|
|
1658
1770
|
'- `prompt({ name, guid?, description?, docs?, title?, icons?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` \u2014 an MCP prompt; takes `registerPrompts`. `input` is the prompt\'s arguments (each field\'s `description`/`required`/enum `values` reach the client; enum values also answer completion requests). `response`: a text value is ONE user message; a list of `{ role: "user" | "assistant", content }` is sent in order, `content` a string or an MCP content block: `s.set_var("m", obj({ list: [obj({ role: c.text("user"), content: ref("body") })] }))`, `response: ref("m.list")`. Without `response` or a top-level `s.return`, `prompts/get` fails.',
|
|
1659
1771
|
"- `resource({ name, uri, guid?, description?, docs?, mimeType?, title?, icons?, annotations?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` \u2014 an MCP resource; takes `registerResources`. Clients address it by `uri`, never `name`.",
|
|
1660
1772
|
' - `uri`: a literal (`"docs://readme"`, no `input`) or an RFC 6570 LEVEL-1 template (`"orders://{region}/{order_id}"`). It must start with a scheme; each `{variable}` is letters/digits/`_`, one per brace pair, never two adjacent. `input` must be EXACTLY the template\'s variables, each a single `text`/`int`/`decimal`/`bool`/`enum`/`email`/`uuid` \u2014 anything else THROWS. A value that does not convert is refused before the stack runs.',
|
|
1661
1773
|
" - `response`: a string is returned as text; non-UTF-8 content (a file, binary) as a base64 blob. `mimeType?` omitted \u2192 derived from what the stack returns.",
|
|
1774
|
+
' - Not found: a resource has no built-in miss path. Returning a `db.get` result straight through on a miss is an EMPTY SUCCESS \u2014 the client attaches an empty document (`text: ""`, `mimeType: "text/plain"`), not an error. Gate it: `s.precondition({ expr: expr(ref("note"), "!=", c.null()), error_type: "notfound", error: c.text("no such note") })` gives a real `resources/read` error (JSON-RPC `-32602`), but \u26A0 the AUTHORED message is dropped \u2014 the client sees only the generic `Not Found` (unlike a `tool()` precondition).',
|
|
1662
1775
|
' - `annotations?`: `{ audience?: ("user" | "assistant")[], priority?: 0..1, lastModified?: ISO 8601 string }`.',
|
|
1663
1776
|
'- MCP metadata, on `tool`/`prompt`/`resource`: `title?` (display name clients show instead of `name`); `icons?: { src, mimeType?, sizes?, theme? }[]` \u2014 `src` is `https:` (\u2264 2048 chars), a base64 `data:` URI of PNG/JPEG/WebP (\u2264 64 KiB), or `hostedFile("./icon.png", import.meta.url)`, a repo file served at each backend\'s own absolute URL (a pull keeps the `/vault/\u2026` path); SVG, `http:` and every other scheme THROW; `mimeType` is `image/png|jpeg|webp`, `sizes` a list (`["48x48"]`, `["any"]`), `theme` `light|dark`. Tool only: `annotations?: { readOnlyHint?, destructiveHint?, idempotentHint?, openWorldHint? }` \u2014 hints; an unset one is derived by the platform \u2014 and `output?`, a structured-output schema in the `input` grammar: a returned plain object then reaches the client as `structuredContent` plus a text copy, and a result that does not match is a tool error naming the field.',
|
|
1664
1777
|
'- `s.mcp.elicit({ key, message, input?, as? })` \u2014 ask the MCP client\'s user mid-call; binds `{ action: "accept" | "decline" | "cancel", content? }` (`content` only on accept, keyed by the `input` field names). `key`: a stable name unique in the stack; `message`: string or value. `input` is the form: a FLAT set of `text`/`email`/`date`/`int`/`decimal`/`bool`/`enum` fields (an enum may be a list); nested objects, files, JSON, timestamps, `password` and `sensitive` fields THROW. Works in tool, prompt and resource stacks.',
|
|
1665
1778
|
' - \u26A0 The WHOLE stack re-runs from the top when the user answers \u2014 everything BEFORE an elicit runs once per round trip, so ASK FIRST, then act. A write before an elicit (`s.db.*` writes, raw SQL, a non-GET `s.api.request`, `s.util.send_email`, `s.function.run`/`.call`, `s.tool.call`) makes `export()` warn `mcp.write-before-elicit`; accept a deliberate one per def with `diagnostics: { allow: ["mcp.write-before-elicit"] }`. An elicit inside `s.db.transaction` commits the transaction\'s earlier writes on every round trip.',
|
|
1666
|
-
' - Input is collected only from clients on MCP `2026-07-28` or later that declare form elicitation. Every other caller \u2014 an older client, a debug run, an agent, a workflow test \u2014 gets `{ action: "cancel" }` and the stack carries on, so ALWAYS handle `cancel`.
|
|
1779
|
+
' - Input is collected only from clients on MCP `2026-07-28` or later that declare form elicitation. Every other caller \u2014 an older client, a debug run, an agent, a workflow test \u2014 gets `{ action: "cancel" }` and the stack carries on, so ALWAYS handle `cancel`. Inside an async function run, `s.mcp.elicit` is a runtime error.',
|
|
1667
1780
|
"- `s.mcp.progress({ progress, total?, message? })` \u2014 report progress to a client that asked for it (a no-op otherwise); values never go backwards (a lower `progress` is sent as the last one).",
|
|
1668
1781
|
'- `s.mcp.oauth.complete({ request, decision, unsafe_user_id?, as? })` \u2014 run by the endpoint your `loginUrl` page calls after sign-in; `request` is the page\'s `mcp_request`. Signs in the CALLER (`auth()`, an `authTable` row whose session token is under 10 minutes old) and binds the single-use URL (text) to redirect to. `decision` (`"approve" | "deny"`, REQUIRED) is what the user chose on your page. \u26A0 `unsafe_user_id` names the row directly, skipping the caller checks \u2014 anyone reaching that endpoint signs in as that user.',
|
|
1669
1782
|
"- `s.mcp.oauth.request({ request, as? })` \u2014 a pending sign-in's verified details for your `loginUrl` page to show before the user approves: `{ client_name, client_logo, callback_host, client_verified, server_name }`. Does not consume it.",
|
|
1670
1783
|
"- `s.mcp.oauth.revoke({ mcp_server, user_id? | grant_id? | all?, as? })` \u2014 end hosted sign-ins on a server: EXACTLY ONE of `user_id`, `grant_id`, `all: c.bool(true)`, else `export()` fails (`mcp.oauth-revoke-target`). Binds `{ revoked }`.",
|
|
1671
1784
|
"- `agent({ name, guid?, description?, docs?, enabled?, canonical?, tags?, history?, llm, tools?, output? })` \u2014 an LLM orchestrator. No top-level `instructions`/`prompt`/`spec` \u2014 the prompt lives under `llm`. Invoke from a stack with `s.ai.agent.run({ agent, args })`.",
|
|
1672
|
-
' - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (
|
|
1785
|
+
' - `llm` (REQUIRED): typed provider settings, a discriminated union on `type` (`"xano-free" | "anthropic" | "openai" | "google-genai"`). Shared fields: `systemPrompt?`, `maxSteps?` (default `5`), and `prompt?` XOR `messages?` (mutually exclusive; both is a type error and throws); plus provider fields (`apiKey?`, `model?`, `temperature?`, `reasoningEffort?`, \u2026). String fields accept Twig placeholders \u2014 `{{ $args.x }}` for run inputs (the `args` of `s.ai.agent.run`), `{{ $env.NAME }}` for env vars.',
|
|
1673
1786
|
" - `xano-free` runs only on Xano's cloud: on the Xano Engine on this machine a run fails `ERROR_FATAL` `The free model is not available in this process.` \u2014 use a keyed provider there.",
|
|
1674
|
-
" - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` \u2014 bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()`
|
|
1675
|
-
' - `output?`: `{ schema: Record<string, input.*>, enabled? }` \u2014 structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map
|
|
1676
|
-
' - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args,
|
|
1787
|
+
" - `tools?`: same `ToolsetToolEntry[]` as `mcpServer` \u2014 bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()` needs the wrapper naming its auth table (see `mcpServer`'s `tools?`).",
|
|
1788
|
+
' - `output?`: `{ schema: Record<string, input.*>, enabled? }` \u2014 structured-output schema. With `tools`, the run executes them first, then shapes its answer into the schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map. e.g. `output: { schema: { priority: input.enum(["low","high"]), summary: input.text() } }`. When you pass the agent *handle* to `s.ai.agent.run({ agent })`, `.result` is typed from this schema; `resultShape` only overrides that, or types an agent referenced by bare name.',
|
|
1789
|
+
' - **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, as: "run" })`) \u2014 it produces a rich envelope, and the completion is at **`.result`**. Read one structured field with a dotted ref (`response: ref("run.result.priority")`) or the whole completion (`ref("run.result")`, typed from `output.schema`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` \u2014 raw literals are fine, e.g. `{ max_steps: 3 }`) surfaced to the agent as `{{ $args.topic }}`. `.toolCalls` is the FINAL step\'s calls only (often `[]`); every call is a `.steps[].content[]` entry of `type: "tool-call"`. `allowToolExecution` defaults to true. \u26A0 `c.bool(false)` does not hide the tools: the model still emits a call, the call never executes, and the run ends with an empty `result` (warns `stack.agent-tools-off`).',
|
|
1677
1790
|
" - **Marketplace:** for chat history, use `@xano-sdk/chatbot`; for vector RAG, use `@xano-sdk/vector` (`tools: [vector.searchTool]`). Find add-ons with `npx @xano/sdk marketplace search <q>`.",
|
|
1678
1791
|
"- Both kinds persist under the `toolset` payload key, so a same-name `agent` + `mcpServer` pair derives ONE guid and `export()` throws \u2014 give them distinct names."
|
|
1679
1792
|
];
|
|
@@ -1683,13 +1796,13 @@ function renderSections(m) {
|
|
|
1683
1796
|
" - `enabled` defaults to **false** \u2014 the one `enabled` in the SDK that does.",
|
|
1684
1797
|
" - An enabled server with no active channel still refuses the handshake.",
|
|
1685
1798
|
" - `realtimeChannel({ name, server, guid?, description?, active?, input?, anonymousClients?, presence?, publish?, conversation?, delivery?, rateLimit?, tags?, history?, middleware? })`",
|
|
1686
|
-
' - `name` is a PATH (`"lobby"`, `"rooms/{room_id}"`); `input` types its `{param}` segments, NOT the payload. Every `{param}` MUST have a matching input, and that input must be a SCALAR and not a list (`json`/`object`/`array: true` have no URL form), or `realtimeChannel()` THROWS. `required: true` is NOT checked and
|
|
1799
|
+
' - `name` is a PATH (`"lobby"`, `"rooms/{room_id}"`); `input` types its `{param}` segments, NOT the payload. Every `{param}` MUST have a matching input, and that input must be a SCALAR and not a list (`json`/`object`/`array: true` have no URL form), or `realtimeChannel()` THROWS. `required: true` is NOT checked and not needed (segment counts must match, so the segment is always present at join). Name charset as query (`A-Za-z0-9_-/{}`, max 200); `realtimeMessage` is narrower \u2014 no `/` or `{}`.',
|
|
1687
1800
|
" - Matching is STRICT: a literal segment beats a param (`rooms/lobby` and `rooms/{room_id}` coexist); segment counts must be EQUAL (`rooms/{room_id}` does NOT match `rooms/42/edit`); literals are CASE-SENSITIVE; an empty segment is REJECTED, not collapsed (a leading/trailing/doubled `/` matches nothing). `realtimeChannel()` refuses it and a partial-segment `{param}`; `getChannel()` a value outside `[A-Za-z0-9_-]`.",
|
|
1688
1801
|
" - An INACTIVE channel reports the same error as a nonexistent one \u2014 deactivating leaks nothing.",
|
|
1689
|
-
" - `middleware?: { pre?, post? }` is the CONTAINER tier, on the channel and on the server alike \u2014 the default chain every message inherits, the same shape an api group has. Full chain: message -> channel -> server -> branch/workspace, mirroring `history`.
|
|
1802
|
+
" - `middleware?: { pre?, post? }` is the CONTAINER tier, on the channel and on the server alike \u2014 the default chain every message inherits, the same shape an api group has. Full chain: message -> channel -> server -> branch/workspace, mirroring `history`. \u26A0 It cannot GUARD: a middleware that throws fails open (below).",
|
|
1690
1803
|
" - `anonymousClients` also gates CONNECT: a tokenless socket connects only if an active channel of its server sets it (no server flag); each channel admits its own join.",
|
|
1691
1804
|
' - `publish?: { who?: "nobody"|"anyone"|"authenticated", direct? }` \u2014 `who` defaults to `nobody`: nobody can publish until you set it. `direct` (default false) allows DIRECT messages \u2014 a frame whose `options.to = { dbo_id, row_id }` addresses one USER (`dbo_id` = the auth table\'s id as `s.realtime.get_session` reports it, `row_id` = the user\'s row id) and reaches every socket of theirs on the channel, no one else; the sender gets a receipt `{ delivered_local, direct: true }`. `direct` REPLACES `who` for such a frame rather than adding to it (`direct: true` with `who: "nobody"` delivers direct messages and refuses broadcasts); an anonymous sender is refused. A direct message is never stored in the transcript or the `at_least_once` stream, so an offline user never gets it. \u26A0 An `options.to` naming no usable identity is sent as an ordinary broadcast to the whole channel where `who` admits the sender.',
|
|
1692
|
-
" - `conversation?: { enabled?, limit?, ttl? }` \u2014 the client-visible TRANSCRIPT replayed to a joiner (distinct from `history`, which is execution history). \u26A0 `limit` DEFAULTS TO 0 AND 0 MEANS OFF: `{ enabled: true }` alone records nothing and replays nothing, silently
|
|
1805
|
+
" - `conversation?: { enabled?, limit?, ttl? }` \u2014 the client-visible TRANSCRIPT replayed to a joiner (distinct from `history`, which is execution history). \u26A0 `limit` DEFAULTS TO 0 AND 0 MEANS OFF: `{ enabled: true }` alone records nothing and replays nothing, silently \u2014 always pass `limit`. `ttl` is an IDLE expiry of the WHOLE transcript, refreshed by every write (an active channel never ages out; a silent one loses all of it at once) \u2014 NOT a per-message age cap.",
|
|
1693
1806
|
' - `delivery?: { guarantee?: "at_most_once"|"at_least_once", perRecipient? }` \u2014 `perRecipient` is independent of the guarantee, is a NO-OP unless the channel declares a `deliver` trigger, and costs a stack PER RECIPIENT PER MESSAGE. Per-viewer redaction needs BOTH HALVES \u2014 this flag AND an active `deliver` trigger bound to the channel \u2014 and with either missing the payload is delivered UNCHANGED to everyone; `export()` warns on each half alone.',
|
|
1694
1807
|
" - `rateLimit?: { messagesPerMinute? }` \u2014 0 = unlimited, checked BEFORE the handler runs. A COST guardrail, not a security control: an anonymous client is bucketed per CONNECTION (reconnecting resets it), and it fails OPEN when its store is down.",
|
|
1695
1808
|
" - `realtimeMessage({ name, channel, server?, guid?, description?, active?, auth?, deliverTo?, input?, middleware?, stack?, response?, responseShape?, history?, disabled?, tags? })` \u2014 the invocable unit (the realtime analogue of a query).",
|
|
@@ -1699,92 +1812,90 @@ function renderSections(m) {
|
|
|
1699
1812
|
' - **Both input surfaces read as ordinary inputs:** `inp("body")` for a payload field, `inp("room_id")` for the channel\'s `{room_id}`. No session lookup, no frame parsing.',
|
|
1700
1813
|
" - A path param is bound ONCE at join and read from the connection thereafter, never from the frame \u2014 a sender cannot claim a room it did not join.",
|
|
1701
1814
|
" - `s.realtime.get_session({ as })` \u2014 the CALLER's realtime session for the current frame. FLAT shape:",
|
|
1702
|
-
' - `authenticated` bool \xB7 `client_id` text (the AUTHED ROW ID as text, `""` anonymous) \xB7 `dbo_id` int (the auth TABLE\'s id
|
|
1815
|
+
' - `authenticated` bool \xB7 `client_id` text (the AUTHED ROW ID as text, `""` anonymous) \xB7 `dbo_id` int (the auth TABLE\'s id, `0` anonymous) \xB7 `socket_id` int (transport id) \xB7 `channel` text (resolved path, `""` in a server trigger) \xB7 `params` object (bound path params, `{}` when none \u2014 `ref("session.params.room_id")`) \xB7 `extras` object \xB7 `opened_at` decimal \xB7 `token_error` text|null (`"expired"`/`"invalid"` when the client SENT a token that did not authenticate \u2014 it connected anonymously; `null` otherwise).',
|
|
1816
|
+
" - `dbo_id` is NOT the user's row id \u2014 look the caller up by `client_id`. A gate keyed on `dbo_id` typechecks, finds no user, and refuses EVERYONE.",
|
|
1703
1817
|
" - Works in a realtime MESSAGE stack and in CHANNEL and SERVER trigger stacks; off that path it degrades to an anonymous session.",
|
|
1704
1818
|
' - For a path param prefer `inp("room_id")` in a MESSAGE; a lifecycle TRIGGER has only the session. Reach for the session when you need the CONNECTION (identity/extras) \u2014 "who is this sender" on an anonymous-client channel.',
|
|
1705
|
-
" -
|
|
1819
|
+
" - Three unrelated things are called a client id: `session.client_id` (app-facing identity), `session.socket_id` (transport), and a frame's `options.client_id` (the at_least_once cursor handle). Conflating the first and last breaks at_least_once for anonymous clients.",
|
|
1706
1820
|
" - `s.realtime.publish({ server, channel, data, message?, authTable?, authId? })` \u2014 the PUSH direction: originate a server-authored event onto a channel from ANY stack, no client frame first.",
|
|
1707
1821
|
" - `server` is the handle or its NAME (resolved by name, not guid); `channel` is the FILLED-IN path (`channel.getChannel({ room_id: 42 })`), never the template \u2014 a constant still carrying `{param}` THROWS at author time, and a constant `server`/`channel` naming nothing this workspace registers WARNS at export.",
|
|
1708
1822
|
' - A PER-ROW path whose id is only known at runtime is built as a value, not with `getChannel()` (which needs the id at author time): `withFilters(c.text("rooms/"), fl.concat(ref("room.id")))`, or `s.set_var` + `s.text.prepend`. A computed `channel`/`server` \u2014 a `ref`/`inp`, or a constant carrying a filter chain \u2014 is left alone by the export check.',
|
|
1709
1823
|
" - DELIVERY-ONLY \u2014 fanned out as-is; does NOT invoke a `realtimeMessage()` handler even when `message` names one (a channel `deliver` trigger still runs).",
|
|
1710
1824
|
" - SERVER-AUTHORITATIVE \u2014 bypasses `publish.who`, which governs CLIENTS. Authorize in your own stack.",
|
|
1711
1825
|
" - \u26A0 FAIL-SOFT \u2014 a missing/disabled server or dead bus is swallowed engine-side, so a mis-targeted publish is SILENT with no result to check.",
|
|
1712
|
-
" - `authTable`/`authId` are ASSERTED attribution on the frame \u2014 not a credential, nothing validates them.",
|
|
1826
|
+
" - `authTable`/`authId` are ASSERTED attribution on the frame \u2014 not a credential, nothing validates them. They land in `_meta.as`, NOT in `payload`.",
|
|
1827
|
+
' - `s.realtime.kick({ server, channel, authTable, authId, reason? })` \u2014 remove one user from one channel: every socket of `authTable`/`authId` (the identity is REQUIRED) leaves the FILLED-IN `channel` path, on every node, through the same steps as a client `leave` (the `leave` trigger, a `presence_leave`), and receives `{ action: "leave", channel, payload: { left: true, kicked: true, reason } }`. The socket stays CONNECTED and keeps its other channels. Call it wherever you revoke a membership the `join` gate admitted.',
|
|
1828
|
+
" - NOT fail-soft (unlike `publish`): an unknown server, a missing identity, or a dead bus FAILS the stack \u2014 a kick that silently did nothing would leave the member subscribed.",
|
|
1713
1829
|
" - **Client recipe (derive, never hardcode):**",
|
|
1714
1830
|
' - `server.getUrl(baseUrl)` \u2192 `wss://<host>/ws/<canonical>` \u2014 accepts the `https://\u2026` instance base URL and normalizes the scheme. `channel.getChannel({ room_id: 42 })` \u2192 `"rooms/42"`, the path that goes in a frame\'s `channel` field. Both throw rather than guess. A canonical is minted by `npx @xano/sdk export <entry> --lock`.',
|
|
1715
|
-
|
|
1831
|
+
' - Auth is a bearer token passed as the websocket SUBPROTOCOL: `new WebSocket(url, token)`. No token = an anonymous client, admitted only where `anonymousClients: true`. \u26A0 An INVALID, tampered, or EXPIRED token still connects \u2014 ANONYMOUSLY, with no error and no close (presence lists it `authenticated: false`) \u2014 and says why: `session.token_error` is `"expired"` or `"invalid"`, and a refusal the socket meets for being anonymous names the token: `{ message: "Your token has expired. Reconnect with a fresh token.", token_error: "expired", reason: "Anonymous clients cannot join this channel" }`. On an error frame carrying `token_error`, refresh the token and reconnect. For a hard refusal at connect, gate with a `realtimeServerTrigger` `connect` (`allowed: session.token_error == null`, or `session.authenticated` \u2192 a 4401 close).',
|
|
1716
1832
|
' - Frames are JSON `{ action: "join"|"leave"|"broadcast"|"ack"|"ping"|"presence", channel, type?, payload?, options?, id? }`. `broadcast` REQUIRES `type`: a `realtimeMessage` of that channel, else refused `Unknown message type`. You must `join` before you may `broadcast`, and the server\'s context is ready only a moment after `open` \u2014 an immediate first frame is refused.',
|
|
1717
1833
|
" - `options` is `{ to?, client_id?, channel? }` \u2014 `to: { dbo_id, row_id }` makes the frame a direct message (needs `publish.direct`), `client_id` is the at-least-once cursor handle, and `options.channel` WINS over a top-level `channel`.",
|
|
1718
1834
|
' - \u26A0 KEEP THE SOCKET ALIVE: an idle connection is REAPED after ~10 minutes. A LISTEN-ONLY client (a feed or dashboard that joins and rarely publishes) MUST send `{ action: "ping" }` (answered `pong`) or any frame periodically or it silently drops.',
|
|
1719
|
-
" - Server frames: `join` (ack `{ joined: true, params }`, + `cursor`/`resumed` on at_least_once) \xB7 `message` \xB7 `replay` \xB7 `broadcast` \xB7 `presence_full`|`presence_join`|`presence_leave` \xB7 `conversation_start`|`conversation_end` (replayed frames flagged `conversation: true`) \xB7 `pong` \xB7 `ack` \xB7 `error`.",
|
|
1720
|
-
" -
|
|
1721
|
-
" - `error` carries `payload.message`, plus `code`/`limit`/`retry_after` when rate limited. `rate_limited` is the
|
|
1835
|
+
" - Server frames: `join` (ack `{ joined: true, params }`, + `cursor`/`resumed` on at_least_once) \xB7 `message` \xB7 `replay` \xB7 `broadcast` \xB7 `presence_full`|`presence_join`|`presence_leave` \xB7 `conversation_start`|`conversation_end` (replayed frames flagged `conversation: true`) \xB7 `pong` \xB7 `ack` \xB7 `error`. An `s.realtime.publish` frame also carries `_meta`: `{ injected: true }` (asserted marker for a server-authored event vs a relayed peer), plus `as: { dbo_id, row_id }` from `authTable`/`authId`.",
|
|
1836
|
+
" - `broadcast` is a RECEIPT to the sender, not a delivery confirmation: `payload.delivered_local` counts recipients on the ANSWERING NODE ONLY, not the channel. It also carries `id` on at_least_once and `dropped: true` when the handler returned null.",
|
|
1837
|
+
" - `error` carries `payload.message`, plus `code`/`limit`/`retry_after` when rate limited. `rate_limited` is the only code \u2014 do not switch on `code`.",
|
|
1722
1838
|
" - An `error` is a per-frame refusal, NOT a disconnect \u2014 EXCEPT a failed handshake and a REFUSED `connect` trigger, which each send one and then CLOSE with code 4401.",
|
|
1723
|
-
" - **Tenant instances (isolated DB):** a tenant's realtime objects live in the TENANT's database, so
|
|
1724
|
-
" - Socket: `server.getUrl(base, { tenant })` \u2192 `/ws/<tenant>:<canonical
|
|
1725
|
-
" -
|
|
1726
|
-
" -
|
|
1727
|
-
" - \u26A0 `getUrl`/`socketUrl` are NOT idempotent \u2014 a `baseUrl` that already carries a `/ws/<\u2026>` path THROWS. Resolve ONCE from the http(s) base; never feed a result back in.",
|
|
1839
|
+
" - **Tenant instances (isolated DB):** a tenant's realtime objects live in the TENANT's database, so both the socket and the HTTP half of a client must name the tenant. No request header is required for either.",
|
|
1840
|
+
" - Socket: `server.getUrl(base, { tenant })` \u2192 `/ws/<tenant>:<canonical>` \u2014 the colon form is socket-only; HTTP gives the tenant its own segment (`https://<host>/tenant/<tenant>/api:<canonical>/\u2026`). \u26A0 A bare canonical on a tenant host resolves against the INSTANCE workspace instead.",
|
|
1841
|
+
" - `getUrl` TRANSLATES a tenant base URL: pass the `https://<host>/tenant/<name>` that `npx @xano/sdk status` prints (and deploy injects as `window.XANO_HOST`) and the tenant is LIFTED into the socket form, so `getUrl(window.XANO_HOST)` needs no `{ tenant }`; a conflicting `{ tenant }` alongside it throws.",
|
|
1842
|
+
" - `getUrl`/`socketUrl` are NOT idempotent \u2014 a `baseUrl` that already carries a `/ws/<\u2026>` path THROWS. Resolve ONCE from the http(s) base; never feed a result back in.",
|
|
1728
1843
|
" - Still pass `{ tenant }` explicitly for a tenant on its OWN DOMAIN \u2014 the hostname carries it for HTTP, but there is nothing in the URL for the socket to lift.",
|
|
1729
|
-
" -
|
|
1844
|
+
" - Tokens are tenant-scoped (audience `<tenant>:<license>`, not the bare license), so one minted through the instance workspace is REJECTED by a tenant's realtime server \u2014 authenticate and dial through the same tenant.",
|
|
1730
1845
|
" - **Presence frames** (a `presence: true` channel only):",
|
|
1731
|
-
" - `presence_full` carries `payload.members`, an ARRAY:
|
|
1846
|
+
" - `presence_full` carries `payload.members`, an ARRAY: it INCLUDES the receiver, at join (first joiner: itself) and on a re-request. `presence_join`/`presence_leave` carry a single `payload.member`. `members` is in NO guaranteed order (not join order): sort it yourself if order matters.",
|
|
1732
1847
|
" - A member is `{ id, dbo_id, authenticated, extras, joined_at }`: `id` the auth row id as a string (`\"0\"` anonymous), `dbo_id` the auth table's id (`0` anonymous), `extras` the connection's extras (`[]` if none), `joined_at` epoch SECONDS.",
|
|
1733
1848
|
' - Render `presence_full`, then apply deltas. One member per authenticated identity (a second tab fires no `presence_join`); anonymous ones all have `id` `"0"`, never collapsed.',
|
|
1734
1849
|
" - Join order: `join` ack \u2192 `presence_full` \u2192 (others get `presence_join`) \u2192 conversation replay \u2192 `replay` frames.",
|
|
1735
1850
|
' - A joined client re-requests it with `{ action: "presence", channel }`, answered to the SENDER only; a socket that never joined is REFUSED.',
|
|
1736
|
-
" - **Conversation frames \u2014 the transcript hydrates the client
|
|
1851
|
+
" - **Conversation frames** \u2014 the transcript hydrates the client (no hydration endpoint); editable or moderated content needs one of the two shapes below.",
|
|
1737
1852
|
' - On a `conversation` channel the replay is PUSHED automatically at join, unasked: `conversation_start` (`payload.count`) \u2192 the last `limit` messages, each a normal `action: "message"` frame carrying its ORIGINAL `type` and `payload` plus `conversation: true` and the original `ts` \u2192 `conversation_end`.',
|
|
1738
|
-
" - Render `message` frames identically either way: no fetch or table read is needed to paint the initial view.",
|
|
1739
|
-
" - \u26A0 `{ enabled: true }` alone is a no-op: `limit` defaults to 0 and 0 means RETAIN NONE (see `conversation` above) \u2014 always pass `limit`.",
|
|
1740
1853
|
" - The POST-HANDLER broadcast payload IS the stored transcript row \u2014 a handler must broadcast everything the UI needs to render a past message (author name, id, `created_at`). Nothing else is replayed.",
|
|
1741
1854
|
" - The transcript is a capped ring (`limit`, `ttl`), not storage: persist to a table only for durability, search, or reads beyond it.",
|
|
1855
|
+
' - \u26A0 APPEND-ONLY: the transcript records EVERY fanned-out frame \u2014 `s.realtime.publish` frames included, not only `"channel"`/`"others"` handler returns \u2014 and no entry can be edited or removed. A message deleted or EDITED in the DB is still replayed to every later joiner: both its original and any edited broadcast stay in the ring until `limit`/`ttl` evicts them, including across a `--keep-data` redeploy \u2014 so for editable/moderated content the transcript LEAKS retracted bodies. An ephemeral `deliverTo: "others"` frame (a typing indicator) also takes a ring slot, so a busy signal evicts real messages.',
|
|
1856
|
+
" - Two safe shapes for editable/moderated chat: (a) turn `conversation` OFF, hydrate the initial view from a table endpoint, and keep the socket for live frames only; or (b) keep bodies OUT of the frames \u2014 publish ids only and read current bodies from a table \u2014 and put ephemeral signals (typing) on a SEPARATE channel with no `conversation`.",
|
|
1742
1857
|
' - **`delivery.guarantee: "at_least_once"` is a CLIENT CONTRACT, not just a channel setting.**',
|
|
1743
1858
|
' - The client must ACK what it receives \u2014 `{ action: "ack", channel, id }`, confirmed by `{ action: "ack", channel, payload: { cursor } }`.',
|
|
1744
1859
|
" - \u26A0 An ANONYMOUS client must ALSO send a durable `options.client_id` in its JOIN frame (once; later acks need not repeat it). WITHOUT one it has no cursor, its acks are SILENTLY IGNORED, and it degrades to at_most_once. An AUTHENTICATED client is keyed by identity and needs no `client_id`.",
|
|
1745
|
-
' - The missed gap arrives after join as `replay` frames, oldest-first, each with an `id` to ack.
|
|
1860
|
+
' - The missed gap arrives after join as `replay` frames, oldest-first, each with an `id` to ack. A first join gets `cursor: "0"`: the WHOLE retained stream replays, repeating a `conversation` transcript.',
|
|
1746
1861
|
' - DISTINCT from the conversation transcript: `conversation_*` is the SHARED "what was said before I arrived", `replay` is the PER-CLIENT "what I missed while disconnected". Both may be on.',
|
|
1747
1862
|
" - How far back `replay` reaches is sized by `conversation.ttl` (here a REAL per-message age cut, and it BEATS `limit`), else `conversation.limit`, else 1000 \u2014 even on a channel with no transcript enabled.",
|
|
1748
|
-
" - **What a message handler RETURNS decides delivery
|
|
1863
|
+
" - **What a message handler RETURNS decides delivery:**",
|
|
1749
1864
|
" - A returned value fans out per `deliverTo` and becomes the transcript row.",
|
|
1750
1865
|
" - Returning NULL delivers NOTHING \u2014 the supported way to veto a message (the sender is told `dropped: true`).",
|
|
1751
1866
|
" - A payload REJECTED by the declared `input` also delivers nothing; the detail goes ONLY to the sender.",
|
|
1752
|
-
" - \u26A0
|
|
1867
|
+
" - \u26A0 A handler that CRASHES FAILS OPEN \u2014 a failed `s.precondition`/`guard.*` (even in an `s.function.run` target), a throwing middleware, a runtime error: the sender's ORIGINAL, UNVALIDATED payload is broadcast unchanged (`s.throw` DROPS it). To veto, set the response var to `c.null()`.",
|
|
1753
1868
|
""
|
|
1754
1869
|
];
|
|
1755
1870
|
const triggers = [
|
|
1756
1871
|
"### Triggers",
|
|
1757
1872
|
"",
|
|
1758
|
-
"
|
|
1759
|
-
"
|
|
1760
|
-
"
|
|
1761
|
-
"
|
|
1762
|
-
"not editable) and arrive through the typed **stack handle** `t` \u2014 you can't",
|
|
1763
|
-
"reference them without it. (`response` too \u2014 a callback, or a plain value that",
|
|
1764
|
-
"reads none.) `t` exposes exactly that trigger type's inputs; a wrong",
|
|
1765
|
-
"name is a compile error, not a runtime surprise. The seven trigger types are",
|
|
1873
|
+
"A trigger has no user-declared `input`: its inputs are **implied by type** and arrive through the typed",
|
|
1874
|
+
"**stack handle** `t`, so `stack` is a callback \u2014 `stack: (t) => [...]` (a plain list works when it",
|
|
1875
|
+
"reads none; `response` likewise). `t` exposes exactly that trigger type's inputs; a wrong name is a",
|
|
1876
|
+
"compile error. The seven trigger types are",
|
|
1766
1877
|
"distinct root factories (not a namespace): `{tableTrigger, realtimeServerTrigger,",
|
|
1767
1878
|
"realtimeChannelTrigger, mcpServerTrigger, agentTrigger, workspaceTrigger,",
|
|
1768
1879
|
"errorTrigger}({ name, guid?, description?, active?, tags?, history?, ... })`.",
|
|
1769
1880
|
"`history` is per trigger (omit to inherit the workspace's `history.trigger`, default",
|
|
1770
1881
|
"off); a trigger's own failure reaches the error log only while it is on.",
|
|
1771
1882
|
"",
|
|
1772
|
-
'- `tableTrigger({ name, table?, datasources?, actions?: {insert?,update?,delete?,truncate?}, stack })` \u2014 database/table trigger. `t.new` / `t.old` are the row **after** / **before** the change; `t.action` (`insert|update|delete|truncate`), `t.datasource`. Bind `table` to a `table()` handle and `t.new("col")` / `t.old("col")` are typed to that row (misspelled column = compile error). \u26A0 Insert\'s `old` and delete\'s `new` are `{}`, not null \u2014 branch on `t.action
|
|
1883
|
+
'- `tableTrigger({ name, table?, datasources?, actions?: {insert?,update?,delete?,truncate?}, stack })` \u2014 database/table trigger. `t.new` / `t.old` are the row **after** / **before** the change; `t.action` (`insert|update|delete|truncate`), `t.datasource`. Bind `table` to a `table()` handle and `t.new("col")` / `t.old("col")` are typed to that row (misspelled column = compile error). \u26A0 Insert\'s `old` and delete\'s `new` are `{}`, not null, and drilling one (`t.old("col")`) RAISES and aborts the run \u2014 branch on `t.action` with an `s.conditional`. Config-only (no response). \u26A0 A table trigger runs AFTER the write COMMITS, from an event queue, so it is NOT the usual in-transaction trigger: it CANNOT veto the write (a top-level `s.precondition`/`s.throw` fails only inside the trigger \u2014 visible via an `errorTrigger` when history is on, never to the writing request, which already answered 200 with the row stored) and its own edits do NOT reach that request\'s response (a `slug` it computes lands on the row a moment later, not in the POST body). Validate in the WRITING stack or a shared `defineFunction`; use the trigger only for after-the-fact side effects. \u26A0 Writes made WHILE a trigger runs fire NO table triggers (the runner disables them for the whole stack), on the SAME or any OTHER table \u2014 so a trigger may safely edit its own table (no loop), but triggers do NOT chain: a trigger on `orders` that writes `stock` fires no `stock` trigger. Chain by calling the follow-up logic as a `defineFunction`.',
|
|
1773
1884
|
"- `realtimeServerTrigger({ name, realtimeServer, actions?: {connect?,disconnect?}, stack?, response?, responseShape? })` \u2014 realtime SERVER lifecycle (a client connecting to / disconnecting from the server, not a message). Inputs: `t.action` (`connect|disconnect`), `t.realtime_server`, `t.client`. Bind `realtimeServer` to a `realtimeServer()` handle (or its name).",
|
|
1774
|
-
" - `connect` GATES the connection \u2014 a denial sends an `error` and CLOSES the socket with code 4401 before it is ever ready
|
|
1775
|
-
" - A CRASH DENIES too
|
|
1885
|
+
" - `connect` GATES the connection \u2014 a denial sends an `error` and CLOSES the socket with code 4401 before it is ever ready. Same return shape as a channel `join` below (EMPTY/FALSY DENIES \u2014 including a gating trigger with NO `response`, which refuses every client).",
|
|
1886
|
+
" - A CRASH DENIES too. Failure is a LOCKOUT, not a breach (an unguarded drill into a null `db.get` raises \u2192 everyone refused).",
|
|
1776
1887
|
" - Gating is OPT-IN: a server with no `connect` trigger accepts every connection.",
|
|
1777
|
-
" - `disconnect` is OBSERVATIONAL (return ignored, throws swallowed
|
|
1888
|
+
" - `disconnect` is OBSERVATIONAL (return ignored, throws swallowed).",
|
|
1778
1889
|
" - Both are SERVER-scoped, so `s.realtime.get_session` works but carries no channel path and no bound params.",
|
|
1779
|
-
"- `realtimeChannelTrigger({ name, channel, actions?: {join?,leave?,deliver?}, stack?, response?, responseShape? })` \u2014 realtime CHANNEL lifecycle. Inputs: `t.action` (`join|leave|deliver`), `t.channel`, `t.payload`, `t.client`. Bind `channel` to a `realtimeChannel()` handle \u2014 a bare path is NOT accepted (it is unique only within its server).
|
|
1780
|
-
' - `join` GATES the join (it runs before membership) \u2014 return `{ allowed: c.bool(true) }` (optional `reason` reaches the client) or any truthy value to admit, and an EMPTY OR FALSY RETURN DENIES, so a stack that just falls through \u2014 or a gating trigger with NO `response` \u2014 refuses everyone, and a CRASH DENIES too. ONCE the object carries an `allowed` key admission needs STRICTLY `true` \u2014 `1`/`"yes"` there DENIES. Compute it as `c.expression("\u2026")` or a `ref()` to a `set_var` boolean (`expr()` is not a `response` value).
|
|
1781
|
-
' - A lifecycle trigger\'s inputs are PINNED to those four, so a channel PATH PARAM is NOT among them \u2014 `inp("room_id")` RAISES, which crashes the gate and so REFUSES every client; take the param from `s.realtime.get_session` (`ref("session.params.room_id")`).',
|
|
1890
|
+
"- `realtimeChannelTrigger({ name, channel, actions?: {join?,leave?,deliver?}, stack?, response?, responseShape? })` \u2014 realtime CHANNEL lifecycle. Inputs: `t.action` (`join|leave|deliver`), `t.channel`, `t.payload`, `t.client`. Bind `channel` to a `realtimeChannel()` handle \u2014 a bare path is NOT accepted (it is unique only within its server). Each action has its own return posture:",
|
|
1891
|
+
' - `join` GATES the join (it runs before membership) \u2014 return `{ allowed: c.bool(true) }` (optional `reason` reaches the client) or any truthy value to admit, and an EMPTY OR FALSY RETURN DENIES, so a stack that just falls through \u2014 or a gating trigger with NO `response` \u2014 refuses everyone, and a CRASH DENIES too. ONCE the object carries an `allowed` key admission needs STRICTLY `true` \u2014 `1`/`"yes"` there DENIES. Compute it as `c.expression("\u2026")` or a `ref()` to a `set_var` boolean (`expr()` is not a `response` value). This is the inverse of a crashing message, which still delivers, and of `deliver`. \u26A0 It runs ONCE: revoking access later (a deleted membership row) does NOT unsubscribe the open socket. Evict it from the endpoint that revokes the membership with `s.realtime.kick` (`llms/kinds-realtime.md`).',
|
|
1892
|
+
' - A lifecycle trigger\'s inputs are PINNED to those four, so a channel PATH PARAM is NOT among them \u2014 `inp("room_id")` RAISES, which crashes the gate and so REFUSES every client; take the param from `s.realtime.get_session` (`ref("session.params.room_id")`). \u26A0 It is RAW TEXT \u2014 path params are not validated or coerced at join (`rooms/abc` joins an `input.int()` channel; `session.params.room_id` is `"42"`, a string), so a numeric gate must CAST it (`fl.to_int()`) and refuse a non-numeric value itself. The declared type is enforced only when a MESSAGE reads `inp(...)`, per frame, after the join.',
|
|
1782
1893
|
' - A gate establishes NO auth: `auth("id")` reads 0 when authenticated, `ref("auth.id")` raises \u2014 identity is `t.client("permissions.row_id")` or the session. A SERVER connect/disconnect has no channel, so no params at all.',
|
|
1783
1894
|
" - `leave` is OBSERVATIONAL (return ignored, throws swallowed).",
|
|
1784
|
-
" - `deliver` GATES delivery PER RECIPIENT \u2014 the per-viewer redaction tool
|
|
1785
|
-
" -
|
|
1895
|
+
" - `deliver` GATES delivery PER RECIPIENT \u2014 the per-viewer redaction tool, a stack per recipient per message. \u26A0 It runs only when the channel sets `delivery.perRecipient` (`llms/kinds-realtime.md`); without it every subscriber receives the UNREDACTED payload, with no error.",
|
|
1896
|
+
" - \u26A0 `deliver`'s return values do not read like a filter: ONLY an explicit NULL drops the message for that recipient; an OBJECT replaces that recipient's payload; anything else \u2014 including `false`, `0`, `\"\"` \u2014 delivers it unchanged, as does a crash. Return null, not `false`, to suppress.",
|
|
1786
1897
|
' - The delivered payload arrives NESTED, so read `t.payload("<field>")`, and `t.client` is the SENDER while `s.realtime.get_session` describes the RECIPIENT this run is for.',
|
|
1787
|
-
'- `mcpServerTrigger({ name, mcpServer, stack?, response?, responseShape? })` / `agentTrigger({ name, agent, stack?, response?, responseShape? })` \u2014 toolset connection. Bind with the `mcpServer()`/`agent()` def handle (or its name) \u2014 it resolves to the toolset guid at export. Raw numeric `objId` is
|
|
1898
|
+
'- `mcpServerTrigger({ name, mcpServer, stack?, response?, responseShape? })` / `agentTrigger({ name, agent, stack?, response?, responseShape? })` \u2014 toolset connection. Bind with the `mcpServer()`/`agent()` def handle (or its name) \u2014 it resolves to the toolset guid at export. Raw numeric `objId` is a rarely-right escape hatch; binding nothing deploys a trigger that never fires. Inputs: `t.toolset` (`t.toolset("name")`), `t.tools`; an MCP server\'s also `t.prompts`/`t.resources`: return one filtered to narrow what the connection lists, omit it to list all \u2014 but \u26A0 a keyed response MUST keep `toolset` and `tools` (omitting either breaks the server for every client) \u2014 and `t.auth`, the signed-in user `{dbo, id, extras}` when the server has `oauth` (null otherwise). Response-bearing; the default returns every list input.',
|
|
1788
1899
|
"- `workspaceTrigger({ name, actions?: {branch_live?,branch_merge?,branch_new?}, stack? })` \u2014 branch lifecycle. Inputs: `t.to_branch`, `t.from_branch`, `t.action`. Config-only.",
|
|
1789
1900
|
'- `errorTrigger({ name, stack? })` \u2014 error-signature trigger. Inputs: `t.event` (`new|regression|fixed`), `t.id`, `t.signature`, `t.error` (`t.error("code")`/`t.error("message")`), `t.caller`, `t.statement`, `t.actor`, `t.count`, `t.first_seen`, `t.last_seen`, `t.fixed_at`. Config-only.',
|
|
1790
1901
|
""
|
|
@@ -1804,19 +1915,22 @@ function renderSections(m) {
|
|
|
1804
1915
|
"for columns, `input.<type>(opts?)` for inputs. Common opts: `required`, `nullable`,",
|
|
1805
1916
|
'`default`, `description`, `access` (a read omits `"internal"` columns, returns `"private"` ones; `InferRow`',
|
|
1806
1917
|
'is the full row, both kept), `sensitive` (masks the input\'s value in request logs; a read still RETURNS a sensitive column \u2014 `access: "internal"` keeps it out).',
|
|
1807
|
-
"
|
|
1808
|
-
|
|
1809
|
-
"`
|
|
1810
|
-
"
|
|
1811
|
-
"
|
|
1812
|
-
"
|
|
1918
|
+
'\u26A0 On a column, `required` is not a write-time constraint: `db.add`/`edit` store a null, `""`, or (after a `trim` method) whitespace-only value at HTTP 200 \u2014 it only shapes the seed write-shape, the typed row, and the editor. Enforce presence on the input (`input.*({ required: true })` plus a non-empty check \u2014 a `min: 1` method or an `s.precondition`).',
|
|
1919
|
+
'\u26A0 An `f.date` COLUMN does not validate the written value: an invalid calendar date ROLLS OVER into a different valid one (`"2020-13-45"` stores `"2021-02-14"`) instead of failing, so a value arriving through `input.text`/`input.json` or a computed var is silently corrupted. Validate at the boundary with `input.date` (it rejects the same string with a 400).',
|
|
1920
|
+
"**`nullable` defaults per type**: `true` for `f.vector`, `f.uuid`, every `f.geo.*` and every",
|
|
1921
|
+
"file type (`f.image`/`f.video`/`f.audio`/`f.attachment`); `false` for the rest. Inputs add",
|
|
1922
|
+
"date, timestamp and file, so an omitted one binds `null`",
|
|
1923
|
+
"(a `required` one still accepts an explicit `null`). Pass `nullable` to override.",
|
|
1924
|
+
'\u26A0 Except `input.geo.*`: an omitted optional geo input is not bound at all, so `inp("p")` 500s `Unable to locate input: p`. Mark it `required: true`, or read it only inside an `s.conditional` that a sibling flag gates.',
|
|
1925
|
+
"An empty default becomes NULL only when",
|
|
1813
1926
|
"nullable, so a non-null `f.vector(8)` column fails to create (`''` is not a vector).",
|
|
1814
1927
|
"**`f.geo.*` values are `{ type, data }`, not GeoJSON.** The same shape goes in and comes",
|
|
1815
1928
|
'back. `type` per column: `point` \u2192 `"point"`, `data` `{ lng, lat }`; `multipoint` \u2192 `"points"`,',
|
|
1816
1929
|
'`linestring` \u2192 `"path"`, `polygon` \u2192 `"poly"` (ring closed for you), `data` `[{ lng, lat }, \u2026]`;',
|
|
1817
1930
|
'`multilinestring` \u2192 `"paths"`, `multipolygon` \u2192 `"polys"`, `data` `[[{ lng, lat }, \u2026], \u2026]`.',
|
|
1818
1931
|
'Any other spelling (`"multipoint"`, `"linestring"`, `"Point"`) 400s `Only strings are supported for:`.',
|
|
1819
|
-
'Raw WKT text (`c.text("POINT(1 2)")`) is accepted on write too, but a read never returns one.',
|
|
1932
|
+
'Raw WKT text (`c.text("POINT(1 2)")`) is accepted on write too, but a COLUMN read never returns one.',
|
|
1933
|
+
'\u26A0 An `input.geo.*` is the exception: `inp("p")` inside the stack reads back as WKT TEXT (`"POINT(10 20)"`), NOT the `{ type, data }` you POSTed \u2014 it becomes `{ type, data }` only once WRITTEN to a geo column and read back. So `InferResponse` of a bare `inp()` of a geo input is wrong (it types `{ type, data }`); treat a bound geo input as a `string`.',
|
|
1820
1934
|
'`methods` (validators/transforms, names per type below): `"trim"`, `"min:8"`',
|
|
1821
1935
|
'(a text arg keeps its `:`: `"startsWith:https://"`), or `{ name, arg }` \u2014 for unlisted names and `pattern`\'s error text.',
|
|
1822
1936
|
"`f.json({children})` declares the nested shape stored INSIDE a json column \u2014 an ARRAY of",
|
|
@@ -1824,10 +1938,11 @@ function renderSections(m) {
|
|
|
1824
1938
|
"`f.object` takes positionally. Omit it for an unstructured json column.",
|
|
1825
1939
|
"`f.enum(values)`/`f.vector(size)`/`f.object(children)`/`f.tableRef(table)` take a",
|
|
1826
1940
|
"positional payload before opts \u2014 and still accept the standard `FieldOptions` after it",
|
|
1827
|
-
"(`f.enum([])`/`input.enum([])` are accepted: a pulled enum with no options, not one to",
|
|
1828
|
-
"author \u2014 it brands the column `never`, which `InferRow` surfaces as `undefined`.)",
|
|
1829
1941
|
"(e.g. `f.tableRef(users, { required: true })` \u2014 only `min`/`max` are listed as tableRef",
|
|
1830
|
-
"methods below, but `required`/`nullable`/`description`/\u2026 apply like any field.
|
|
1942
|
+
"methods below, but `required`/`nullable`/`description`/\u2026 apply like any field).",
|
|
1943
|
+
"`f.enum([])`/`input.enum([])` (a pulled enum with no options) brands the column `never`; `InferRow` surfaces it as `undefined`.",
|
|
1944
|
+
'\u26A0 An `f.enum` column refuses a non-member (400) but STORES `""`, which an omitted optional',
|
|
1945
|
+
'`input.text`/`input.enum` binds, overriding the `default`; `InferRow` types it members `| ""`. Declare that input `nullable: true` (omitted \u2192 `null` \u2192 the default).',
|
|
1831
1946
|
"An **OPTIONAL foreign key wants a `0` sentinel, not `nullable: true`**. `f.tableRef` to an int-keyed table stores",
|
|
1832
1947
|
"an `int`, and a null in it is unqueryable: `null` is never a legal `fieldValue`/`id`, so",
|
|
1833
1948
|
"`s.db.get`/`edit`/`del` on that column answer HTTP 400 `Missing param: field_value` rather",
|
|
@@ -1838,10 +1953,11 @@ function renderSections(m) {
|
|
|
1838
1953
|
"An `f.vector(size)` column is SEARCHED through `s.db.query`'s `eval` pipeline, not through",
|
|
1839
1954
|
'any `SearchOp`: give the table `index: [{ type: "vector", fields: [{ name: "embedding", op:',
|
|
1840
1955
|
'"vector_cosine_ops" }] }]`, then rank with a distance filter + a sort on its alias (see',
|
|
1841
|
-
"`s.db.query` \u2192 `eval`).
|
|
1842
|
-
"queries it.",
|
|
1956
|
+
"`s.db.query` \u2192 `eval`).",
|
|
1843
1957
|
"`{ array: true }` makes any `f.*` scalar a **list column** \u2014 `f.text({ array: true })`",
|
|
1844
|
-
"surfaces as `string[]` in `InferRow<typeof table
|
|
1958
|
+
"surfaces as `string[]` in `InferRow<typeof table>`.",
|
|
1959
|
+
"Filter one to rows containing a value with `contains`/`overlaps` and a LIST operand (NOT a",
|
|
1960
|
+
"scalar \u2014 `llms/statements-data.md`).",
|
|
1845
1961
|
"**Seed a table's starting rows with `table({ seed })`.** `seed` takes rows",
|
|
1846
1962
|
"typed against the table's schema as a WRITE shape (a column without",
|
|
1847
1963
|
"`required: true`, and the system columns, may be omitted; `null` needs",
|
|
@@ -1866,7 +1982,7 @@ function renderSections(m) {
|
|
|
1866
1982
|
"a stable derived uuid (uuid PK); supplying `id` pins it (and",
|
|
1867
1983
|
"resets an int sequence past the max). All-or-nothing \u2014 mixing explicit and",
|
|
1868
1984
|
"omitted `id` throws. A `system:false` PK is the author's to supply. Pinning is",
|
|
1869
|
-
"`seed`-only \u2014 `s.db.bulk.add` DROPS `id` unless `allowIdField: true`.",
|
|
1985
|
+
"`seed`-only \u2014 `s.db.bulk.add` DROPS `id` unless `allowIdField: true`. \u26A0 After a deploy, the FIRST insert into an UNSEEDED int-keyed table gets `id: 2`, not 1 (a seeded table continues correctly from its max) \u2014 so a test or fixture must not assume the first inserted row is `id: 1`.",
|
|
1870
1986
|
"**`use_xdo` storage mode.** Workspace setting (`registerWorkspace({ use_xdo })`,",
|
|
1871
1987
|
"default `false`): `true` stores fields as JSON in the `xdo` column (+ `gin(xdo)` index),",
|
|
1872
1988
|
"`false` real columns.",
|
|
@@ -1875,10 +1991,10 @@ function renderSections(m) {
|
|
|
1875
1991
|
"e.g. an emoji) is rejected at export; put such a value on an `input.<type>({ default })`.",
|
|
1876
1992
|
"`input.*` mirrors `f.*` \u2014 every column type below is",
|
|
1877
1993
|
"a legal input (scalars, files `input.image/video/audio/attachment`, `input.geo.*`,",
|
|
1878
|
-
"`input.vector(size)`, `input.tableRef(table)`, `input.object(children)`)
|
|
1879
|
-
"`input.dbLink(table)`
|
|
1880
|
-
'
|
|
1881
|
-
'
|
|
1994
|
+
"`input.vector(size)`, `input.tableRef(table)`, `input.object(children)`).",
|
|
1995
|
+
"Input-only: `input.dbLink(table)` expands into one input per column of the linked table;",
|
|
1996
|
+
'read them by column name (`inp("email")`), not by the entry\'s own name.',
|
|
1997
|
+
'`hidden: ["created_at"]` drops columns from that expansion.',
|
|
1882
1998
|
"`input.list(element)` for arrays \u2014 wrap any element constructor, e.g.",
|
|
1883
1999
|
"`input.list(input.text())` or `input.list(input.object({ id: f.int() }))`.",
|
|
1884
2000
|
"**A file reaches a column in two steps.** `input.file` is the RAW upload (the request's",
|
|
@@ -1890,6 +2006,7 @@ function renderSections(m) {
|
|
|
1890
2006
|
'`"public"` (a guessable URL): pass `"private"` and hand out `s.storage.sign_private_url`',
|
|
1891
2007
|
"results for anything user-scoped. `create_video`/`create_audio`/`create_attachment` are",
|
|
1892
2008
|
"the same shape for the other file columns, each fed `input.file` (`input.image`/\u2026 400s an upload).",
|
|
2009
|
+
"\u26A0 A WRONG-KIND upload to `create_image`/`create_audio`/`create_video` (text sent as an image, or a `.txt` renamed `.png`) fails the request with HTTP 500 `ERROR_FATAL` (`Invalid file extension.` / `This resource is not a valid image.`), not a 4xx. Guard it: wrap the store in `s.try_catch`, or precondition the upload's extension/mime first.",
|
|
1893
2010
|
'**An empty file column is a stored null that `where` does not see as null.** `expr(col("file"), "!=", c.null())`',
|
|
1894
2011
|
"matches EVERY row, and `= c.null()` matches none. Compare a key inside the file instead:",
|
|
1895
2012
|
'`expr(col("file.path"), "!=", c.null())` keeps only the rows holding a file.',
|
|
@@ -1899,6 +2016,9 @@ function renderSections(m) {
|
|
|
1899
2016
|
"`regex_matches` needed; `input.int`/`input.decimal`/`input.uuid`/`input.enum([...])`/`input.date`",
|
|
1900
2017
|
"likewise reject or coerce bad input at the boundary. Drop to `input.text` + `s.precondition`",
|
|
1901
2018
|
"only for rules no type expresses.",
|
|
2019
|
+
"\u26A0 `input.int` COERCES by TRUNCATION, not refusal: a fractional number binds its integer part",
|
|
2020
|
+
'at HTTP 200 (`1.7` \u2192 `1`, `2.9` \u2192 `2`), where `"abc"` gets a 400. When a fraction must be',
|
|
2021
|
+
"refused rather than silently floored, take `input.decimal` and check it with `s.precondition`.",
|
|
1902
2022
|
"\u26A0 `input.url` is NOT one of them \u2014 there is no engine `url` type, so it stores as `text`",
|
|
1903
2023
|
"and validates NOTHING: a `javascript:`/`data:` URL type-checks, imports, and binds. When the value gets navigated",
|
|
1904
2024
|
"to, check the scheme in the stack. It is INPUT ONLY \u2014 there is no `f.url` column.",
|
|
@@ -1907,25 +2027,39 @@ function renderSections(m) {
|
|
|
1907
2027
|
'offset but DROPS fractional seconds (`"\u2026T19:30:00.123Z"` binds `\u2026:00.000`). Send epoch ms',
|
|
1908
2028
|
"(`Date.now()`, `getTime()`) whenever sub-second precision matters.",
|
|
1909
2029
|
'\u26A0 `input.list` does NOT reject a non-array: one value binds as a ONE-item list (`"a"` \u2192',
|
|
1910
|
-
'`["a"]`)
|
|
1911
|
-
'children\'s DEFAULTS
|
|
1912
|
-
'`[{ name: "", \u2026 }]` with a 200
|
|
1913
|
-
"
|
|
1914
|
-
"
|
|
1915
|
-
"
|
|
1916
|
-
'\u26A0 `s.precondition`\'s `error` must be a TAGGED value \u2014 `c.text("\u2026")`, not a bare string.',
|
|
1917
|
-
'
|
|
1918
|
-
"non-scalar message, and a bare string lands there, so the client never sees your text. The",
|
|
1919
|
-
"`error_type` \u2192 HTTP status mapping is correct either way; only the message is lost.",
|
|
2030
|
+
'`["a"]`); a non-JSON string given to an `input.object` binds an object of its',
|
|
2031
|
+
'children\'s DEFAULTS, so `input.list(input.object({...}))` given `"notalist"` binds',
|
|
2032
|
+
'`[{ name: "", \u2026 }]` with a 200 (a list `min` passes: one item). A string starting with `[`',
|
|
2033
|
+
"is parsed as JSON with NO element check. To enforce the shape, mark an object child",
|
|
2034
|
+
"`required: true` (the default-filled object then 400s with its param path); check the rest",
|
|
2035
|
+
"with `s.precondition`.",
|
|
2036
|
+
'\u26A0 `s.precondition`\'s `error` must be a TAGGED value \u2014 `c.text("\u2026")`, not a bare string (warns `stack.precondition-bare-error`).',
|
|
2037
|
+
'A bare string is replaced by the generic "Precondition failed."; the status from `error_type` still applies.',
|
|
1920
2038
|
`\`error_type\` is how a stack sets a FAILURE status: ${preconditionStatusLine()}.`,
|
|
2039
|
+
"A failed request answers a JSON envelope `{ code, message, payload }`: `code` is the",
|
|
2040
|
+
"`ERROR_CODE_*` string for the `error_type` (`badrequest` \u2192 `ERROR_CODE_BAD_REQUEST`,",
|
|
2041
|
+
"`accessdenied` \u2192 `ERROR_CODE_ACCESS_DENIED`, `notfound` \u2192 `ERROR_CODE_NOT_FOUND`, \u2026;",
|
|
2042
|
+
"`standard`/an uncaught engine error \u2192 `ERROR_FATAL`). `message` is the `error` text.",
|
|
2043
|
+
"`payload` is `s.precondition`'s optional structured detail (`obj({...})`), client-visible;",
|
|
2044
|
+
'it is `""` when a precondition sets none and the key is ABSENT entirely on engine errors.',
|
|
2045
|
+
'\u26A0 A `db.edit`/`db.del` NotFound carries an EMPTY `message` (just `{code:"ERROR_CODE_NOT_FOUND"}`),',
|
|
2046
|
+
'so a `catch` that re-raises `fl.concat(caught("message"))` yields only its prefix and an',
|
|
2047
|
+
"`expect.to_throw(c.text(...))` can never match it \u2014 re-raise with your own `error` text.",
|
|
2048
|
+
"\u26A0 An uncaught `s.throw` (including one inside a function run with `s.function.run`):",
|
|
2049
|
+
'- answers HTTP **200** with `{ payload, statement: "Throw Error" }`, so `res.ok` is true \u2014 UNLESS it',
|
|
2050
|
+
' sets `status`: `s.throw({ name: "NOT_ALLOWED", value: c.text("no access"), status: 403 })`',
|
|
2051
|
+
" answers 403 with that body (`status` is a whole number, 100\u2013599).",
|
|
2052
|
+
"- The status applies only when nothing catches the throw; a caught throw leaves the response status alone.",
|
|
2053
|
+
"- The body carries `value` as `payload` and never the `name`.",
|
|
2054
|
+
"- For the `{ code, message, payload }` envelope, fail with `s.precondition` or `guard.require` instead.",
|
|
2055
|
+
"",
|
|
1921
2056
|
"For any other status \u2014 and for a redirect \u2014 use `respond.*`, which is sugar over",
|
|
1922
2057
|
"`s.util.set_header` (that statement reaches the status line): `respond.status(201)`,",
|
|
1923
2058
|
"`respond.redirect(url, { status?: 301|302|303|307 })` (a TUPLE \u2014 spread it; a `Location`",
|
|
1924
2059
|
"alone does NOT redirect), and `respond.header(name, value)`. Position in the stack does not",
|
|
1925
2060
|
"matter, a later status wins, and a FAILING `precondition` still wins over anything set",
|
|
1926
2061
|
"before it. \u26A0 `204` answers with an empty body whatever `response` says. \u26A0 `respond.status`",
|
|
1927
|
-
"REFUSES `308`/`425`/`451`/`102`/`103
|
|
1928
|
-
"so the response is 200 with nothing reported \u2014 use 301, 429 and 403 instead.",
|
|
2062
|
+
"REFUSES `308`/`425`/`451`/`102`/`103` (they would answer 200, nothing reported); use 301, 429 and 403 instead.",
|
|
1929
2063
|
"Normalizing transforms run on bind too \u2014 put `trim`/`lower`/`upper` on the input's `methods`",
|
|
1930
2064
|
'so `inp("name")` reads already-normalized; don\'t reroll `var $x = inp("name")|trim` in the stack.',
|
|
1931
2065
|
"\u26A0 `f.decimal`'s size depends on the table's layout; it takes no precision or scale option.",
|
|
@@ -1959,38 +2093,45 @@ function renderSections(m) {
|
|
|
1959
2093
|
filters.push(
|
|
1960
2094
|
"Attach to a value with `withFilters(v, fl.name(...))` \u2014 the value `filters[]`",
|
|
1961
2095
|
"pipeline. Filters are passed spread (canonical); the array form",
|
|
1962
|
-
"`withFilters(v, [fl.a(), fl.b()])` is also accepted. Every filter is typed:",
|
|
1963
|
-
"
|
|
1964
|
-
"
|
|
1965
|
-
"
|
|
1966
|
-
"
|
|
1967
|
-
"
|
|
1968
|
-
|
|
1969
|
-
"
|
|
1970
|
-
"
|
|
1971
|
-
"
|
|
1972
|
-
"
|
|
1973
|
-
'`filter("name", \u2026)
|
|
1974
|
-
"
|
|
1975
|
-
"catalog never declared and so are not arity-checked at all.",
|
|
2096
|
+
"`withFilters(v, [fl.a(), fl.b()])` is also accepted. Every filter is typed. Arity:",
|
|
2097
|
+
"",
|
|
2098
|
+
"- A declared argument list (the catalog below) is an EXACT count, not a floor: passing more",
|
|
2099
|
+
" THROWS, in the type and at runtime.",
|
|
2100
|
+
"- Seven declared filters take more: `concat` (trailing separator), `index_by` (trailing list",
|
|
2101
|
+
" flag), `get` (trailing variable map), `array_merge`/`array_merge_recursive` (any number of",
|
|
2102
|
+
" arrays), `jwe_encode`, `jwe_decode`.",
|
|
2103
|
+
"- A filter with NO declared list is called `fl.<name>()`; passing an argument is a compile",
|
|
2104
|
+
" error. The variadic filters at the end of the catalog take undeclared arguments and are",
|
|
2105
|
+
" not arity-checked.",
|
|
2106
|
+
"- Past any of these \u2014 a filter the catalog under-declares, or more than a",
|
|
2107
|
+
' zero-argument filter\'s `()` accepts \u2014 use the untyped `filter("name", \u2026)`.',
|
|
2108
|
+
"",
|
|
1976
2109
|
"A typed filter also accepts one object of NAMED arguments (`fl.add({ value: 1 })`); a key",
|
|
1977
2110
|
"the filter does not declare throws rather than being dropped.",
|
|
1978
2111
|
"A bare JS **scalar** \u2014 string, number or boolean \u2014 is accepted in ANY `fl.*` argument and",
|
|
1979
|
-
'wrapped as
|
|
1980
|
-
|
|
1981
|
-
"
|
|
1982
|
-
"
|
|
1983
|
-
"
|
|
1984
|
-
"
|
|
1985
|
-
"`fl.add`/`fl.sub`/`fl.mul` keep an INT when both operands are ints (`2 \xD7 3` is `6`, not",
|
|
1986
|
-
"`6.0`) and give a decimal only when either operand is one \u2014 the `decimal` return type",
|
|
1987
|
-
"below covers both, so an int pipeline needs no `fl.to_int()`. `fl.div` is an int only",
|
|
2112
|
+
'wrapped as a constant (`fl.get("a.b", 0)` \u2261 `fl.get(c.text("a.b"), c.int(0))`). Build an',
|
|
2113
|
+
"object or array with `c.obj`/`c.array`. Any argument also takes a runtime value (`inp`, `ref`,",
|
|
2114
|
+
"a `withFilters` chain); inside `obj()`/`expr()` an argument cannot carry its own filter",
|
|
2115
|
+
"chain \u2014 compute it in a prior `set_var`. Arg types below are ENGINE types, not JS types.",
|
|
2116
|
+
"`fl.add`/`fl.sub`/`fl.mul` keep an INT when both operands are ints (`2 \xD7 3` is `6`) and give",
|
|
2117
|
+
"a decimal when either is one; an int pipeline needs no `fl.to_int()`. `fl.div` is an int only",
|
|
1988
2118
|
"when it divides exactly.",
|
|
1989
2119
|
"To add to a numeric column (counter, stock, balance), use `s.db.increment`",
|
|
1990
2120
|
"(`llms/statements-data.md`) \u2014 one atomic UPDATE. A pipeline read-modify-write is NOT",
|
|
1991
2121
|
'atomic (concurrent writers lose updates), and `col("clicks")` does NOT resolve to the',
|
|
1992
2122
|
"stored value inside a `db.edit` `row` (it is `null`; `null + 1` aborts): `db.get` the row",
|
|
1993
2123
|
'`as: "current"`, then `withFilters(ref("current.clicks"), fl.add(c.int(1)))`.',
|
|
2124
|
+
"\u26A0 NULL operands, by filter:",
|
|
2125
|
+
"- Text filters (`trim`/`upper`/`strlen`/`to_int`/\u2026) pass null through (`strlen(null)` is `null`;",
|
|
2126
|
+
" `strlen` of a non-string is `null` too, not a length).",
|
|
2127
|
+
"- Arithmetic treats null as `0` (`null|add:1` \u2192 `1`).",
|
|
2128
|
+
'- `fl.concat` on a null or list base returns `""` and SILENTLY DROPS its argument',
|
|
2129
|
+
' (`null|concat:"x"` \u2192 `""`). Default the base first:',
|
|
2130
|
+
' `withFilters(inp("middle"), fl.first_notnull(c.text("")), fl.concat("x"))`.',
|
|
2131
|
+
'- `fl.split` of null is `[""]`.',
|
|
2132
|
+
"",
|
|
2133
|
+
"\u26A0 `fl.trim`/`ltrim`/`rtrim` (and the `s.text.*` trims) take `mask` as a SET OF CHARACTERS, not a",
|
|
2134
|
+
'substring. It is a PHP MASK, so `"a..c"` means the RANGE a-c, not the three characters `a`, `.`, `c`.',
|
|
1994
2135
|
""
|
|
1995
2136
|
);
|
|
1996
2137
|
const argFilters = m.filters.filter((fl) => fl.args?.length);
|
|
@@ -2012,8 +2153,10 @@ function renderSections(m) {
|
|
|
2012
2153
|
const variadic = m.filters.filter((fl) => fl.variadic).map((fl) => fl.name);
|
|
2013
2154
|
filters.push(
|
|
2014
2155
|
"",
|
|
2015
|
-
`Zero-argument filters, by operand type
|
|
2156
|
+
`Zero-argument filters, by operand type: ${zeroArg.join("; ")}.`,
|
|
2016
2157
|
"`fl.reverse()` reverses a list only: on a text value it answers the text UNCHANGED, with no error.",
|
|
2158
|
+
"An unknown `timezone` (a typo, `+05:30`, `PDT`) silently means UTC. A literal warns at export; take a runtime zone as an `input.enum`.",
|
|
2159
|
+
'`fl.to_bool()` is NOT a truthiness cast: it accepts only the boolean vocabulary \u2014 `true`/`1`/`"1"`/`"true"`/`"on"`/`"yes"` and `false`/`0`/`"0"`/`"false"`/`"off"`/`""` \u2014 and ANY other value 400s `ERROR_CODE_INPUT_ERROR` "Invalid boolean input.". For a truthiness cast pipe `fl.ne(c.int(0))`.',
|
|
2017
2160
|
"",
|
|
2018
2161
|
`Variadic filters \u2014 they take arguments, but no declared list, so the count is not checked: ${variadic.join(", ")}.`,
|
|
2019
2162
|
""
|
|
@@ -2024,17 +2167,15 @@ function renderSections(m) {
|
|
|
2024
2167
|
"Reachable through the `s` namespace: `s.<path>({...})`. Declarative statements",
|
|
2025
2168
|
"take one typed args object (field names match the engine); every surface's field",
|
|
2026
2169
|
"signature is in `llms/statements-catalog.md`. Specials (`[special]`) are",
|
|
2027
|
-
"hand-authored: control flow is below,
|
|
2028
|
-
"topic files this doc's navigation names.",
|
|
2029
|
-
"Wrap an `input`-routed `value` field in `ignored(...)` to store it but SKIP it at",
|
|
2030
|
-
" runtime \u2014 the engine records `<name>:ignore` and the parameter falls back to its",
|
|
2031
|
-
" default. Not the same as an empty value, and not the same as omitting the field",
|
|
2032
|
-
" (which stores no entry at all). Mostly seen on a pulled workspace. A field written",
|
|
2033
|
-
" into `context` instead (the `s.math.*`/`s.text.append` mutation family) has no slot",
|
|
2034
|
-
" for the flag and THROWS rather than dropping it.",
|
|
2170
|
+
"hand-authored: control flow is below, the rest are in the `llms/statements-*` topic files.",
|
|
2035
2171
|
"Fields marked `value` take a `Value` (`c.*`/`ref`/`inp`); `comparison` takes an",
|
|
2036
2172
|
"`expr(...)`. A `\u2192 as: <type>` suffix names what the statement's `as:` output var",
|
|
2037
2173
|
"holds (curated, not exhaustive \u2014 absence means read the `[output]` flag and prose).",
|
|
2174
|
+
"`ignored(...)` around an `input`-routed `value` field stores it but SKIPS it at runtime: the",
|
|
2175
|
+
"engine records `<name>:ignore` and the parameter takes its default. Distinct from an empty",
|
|
2176
|
+
"value and from omitting the field (no entry stored). Mostly seen on a pulled workspace. On a",
|
|
2177
|
+
"`context`-routed field (the `s.math.*`/`s.text.append` mutation family) `ignored(...)` THROWS:",
|
|
2178
|
+
"there is no slot for the flag.",
|
|
2038
2179
|
""
|
|
2039
2180
|
);
|
|
2040
2181
|
lines.push(
|
|
@@ -2060,7 +2201,12 @@ function renderSections(m) {
|
|
|
2060
2201
|
"Array blocks (an `if`/`transform` is applied per item):",
|
|
2061
2202
|
"",
|
|
2062
2203
|
'- `s.array.map({ source, as?, transform? })` \u2014 `transform` is either a per-item `Value` expression (each item maps to that value) or a **record of values** (each item maps to an object with those keys), or a list of `{ key, value }` pairs, for a key computed per item or two rows sharing one. Use `ref("$this")` for the item and `ref("$index")` for its position. A `transform` value, filter arguments included, can read `ref("$this.<path>")` and any outer stack variable or input. These are THIS statement\'s own bindings, in a value expression \u2014 not the JavaScript lambda contract (see **Lambda bodies**), which binds a different set per surface and is written with `lam.fn`.',
|
|
2063
|
-
|
|
2204
|
+
'- `s.array.union({ source, with, as?, transform? })` \u2014 set-union two arrays. `with` is REQUIRED; omitted \u2192 `Unable to locate input: `. `transform` is a per-item DEDUPE KEY over `$this`, not a map: the result keeps the original items, first occurrence wins (`transform: ref("$this.id")` unions records by `id`).',
|
|
2205
|
+
'- **Array predicates** (`s.array.filter`/`filter_count`/`find`/`find_index`/`has`/`every`/`partition`) share one shape: `{ expr, if, as }`. The `if` comparison reads the current item as `ref("$this")` (or `ref("$this.<path>")`) and resolves any outer var/input; `$index` is bound ONLY inside `partition`, not the others. Results: `filter` \u2192 the matching list; `filter_count` \u2192 an int; `find` \u2192 the item or `null` on a miss; `find_index` \u2192 the index or `-1` on a miss (on an OBJECT source it returns the matching KEY, e.g. `"x"`); `has` \u2192 a bool; `every` \u2192 a bool, `true` on `[]`; `partition` \u2192 `{ "true": [...], "false": [...] }` (STRING keys). \u26A0 An OBJECT source iterates its VALUES (keys dropped from `filter`\'s result), and a null, omitted or scalar source behaves like `[]`. The predicate uses the engine\'s LOOSE comparison, so `"abc" > 3` and `"1" = 1` are both true.',
|
|
2206
|
+
'- **Set ops** `s.array.difference`/`intersection` take `{ expr, value, by?, as }` (`s.array.union`\'s shape is the bullet above). All three compare STRICTLY (`"3"` \u2260 `3`), unlike the predicates \u2014 and they DEDUPE the source: `[1,1,2,"3"]` \u2212 `[3]` \u2192 `[1,2,"3"]`, `[1,2,2,3]` \u222A `[3,4]` \u2192 `[1,2,3,4]`. Without `by`, records compare whole; `by` is a `$this` expression (`by: ref("$this.id")`), not a column name.',
|
|
2207
|
+
'- `s.array.group_by({ expr, by?, as })` binds an OBJECT keyed by each item\'s `by` value (a missing key read with `{ safe: true }` groups under `""`). \u26A0 WITHOUT `by` on a list of records it 500s (`Cannot access offset of type array on array`) \u2014 always pass `by` for records.',
|
|
2208
|
+
'- **In-place array mutators** `s.array.push`/`unshift`/`merge`/`pop`/`shift` take `{ name, value? }` and REWRITE the var named `name` (no `as`); `name` may be a dotted path (`"o.items"`). `pop`/`shift` on `[]` bind `null`. \u26A0 `push` of a LIST appends it as ONE element (`[\u2026, [9,9]]`) where `merge` SPREADS it in; `push` onto a scalar var throws, and onto an object var it adds numeric keys.',
|
|
2209
|
+
"- `s.object.keys`/`values`/`entries({ value, as })` on `{}`, null, an omitted var or a string all bind `[]`; on a LIST they treat the indexes as keys. `entries` yields `{ key, value }` OBJECTS (not `[key, value]` tuples), and an integer-like key comes back as a NUMBER (PHP coerces it), for all three.",
|
|
2064
2210
|
"",
|
|
2065
2211
|
"DB reads/writes (`table` is a def handle or name; `fieldName` defaults to the",
|
|
2066
2212
|
"primary key `id`):",
|
|
@@ -2070,65 +2216,72 @@ function renderSections(m) {
|
|
|
2070
2216
|
"- `s.db.del({ table, fieldName?, fieldValue, as? })` \u2014 delete by field match.",
|
|
2071
2217
|
"- `s.db.add({ table, row?, data?, output?, as? })` \u2014 insert; `row` is a partial keyed by column.",
|
|
2072
2218
|
' - A row CELL takes a tagged `Value`, a nested object of sub-keys, or a bare JS literal typed against that column: `row: { is_hidden: true, notes: "\u2026" }` encodes exactly as `{ is_hidden: c.bool(true), notes: c.text("\u2026") }`. The tag comes from the COLUMN, not the literal \u2014 `10` on an `f.decimal()` column is `const:decimal`, not `const:int` \u2014 so a literal contradicting its column is a compile error on a `f.*`-schema table (`{ is_hidden: "yes" }` on an `f.bool()` column) and throws at encode on a raw-`ColumnDef[]` one. An `f.enum()` column keeps its member union. A column with no literal form \u2014 obj/json/list/geo/vector/file \u2014 still needs `c.obj`/`c.array`.',
|
|
2073
|
-
" - `null` is accepted on EVERY column
|
|
2074
|
-
" - Omitting a key on `add` writes the column's type default \u2014 declared `default` if set, `[]` for a list, `{}` for obj/json, else `null
|
|
2219
|
+
" - `null` is accepted on EVERY column at encode and encodes `const:null`; a column's `nullable` is not consulted there. \u26A0 The engine does not refuse it either: on a NON-NULLABLE column an explicit `null` is the SAME as omitting the key \u2014 it stores the column's `default`, else the type's zero value (`\"\"`/`0`/`false`/\u2026). Only a `nullable: true` column STORES null.",
|
|
2220
|
+
" - Omitting a key on `add` writes the column's type default \u2014 declared `default` if set, `[]` for a list, `{}` for obj/json, else `null`, which is EMITTED, not what the row holds: a `nullable` column keeps `null`, a non-nullable one lands on its type's zero value (`\"\"`, `0`, `false`). \u26A0 Except `f.date`: it stores TODAY's date, absent from `add`'s `as` \u2014 make an optional date `nullable: true`. On `edit` an omitted key keeps its stored value.",
|
|
2075
2221
|
" - An `f.password()` cell takes the PLAINTEXT \u2014 the column hashes on write, so a pre-hashed value, or a hashing filter on the cell, stores a hash of a hash that `security.check_password` can never match.",
|
|
2076
|
-
" - A `table({ seed })` cell hashes the same way: the import writes the plaintext through the column's own rules, so a seeded credential matches under `security.check_password` exactly as an added one does.
|
|
2222
|
+
" - A `table({ seed })` cell hashes the same way: the import writes the plaintext through the column's own rules, so a seeded credential matches under `security.check_password` exactly as an added one does. Seeded credentials work as fixtures; their plaintext is committed to the repo.",
|
|
2077
2223
|
"- `s.db.edit({ table, fieldName?, fieldValue, row?, data?, output?, as? })` \u2014 update by field match.",
|
|
2078
|
-
|
|
2079
|
-
"
|
|
2224
|
+
'- `s.db.patch({ table, fieldName?, fieldValue, data, output?, as? })` \u2014 merge a partial. \u26A0 Unlike `db.edit`\'s `row`, `data` is a single object `Value` \u2014 write `obj({ unread: c.int(0) })`, not the column-keyed record `row` takes. \u26A0 A json/object column value is DEEP-merged key by key, not replaced: patching `{ meta: { k: 1 } }` onto `meta = { origin: "WA" }` stores `{ origin: "WA", k: 1 }`, so a patch can NEVER drop a key from a json column \u2014 use `db.edit` with `row: { meta: \u2026 }` to replace one wholesale.',
|
|
2225
|
+
"- `output` on `db.get`/`add`/`edit`/`patch` restricts the columns of the RETURNED row only \u2014 on a write it does not change",
|
|
2080
2226
|
" what is written. Not offered on `db.del`/`db.has` (their result is a scalar) or on",
|
|
2081
2227
|
" `db.add_or_edit` (no output envelope).",
|
|
2082
2228
|
"- `s.db.add_or_edit({ table, fieldName?, fieldValue, row?, data?, as? })` \u2014 upsert.",
|
|
2083
2229
|
"- `s.db.query({ table, where?, additionalWhere?, bind?, sort?, paging?, external?, returnType?, distinct?, eval?, output?, lock?, addon?, as? })` \u2014 search.",
|
|
2084
|
-
" - `where` / `additionalWhere` \u2014 `expr(...)
|
|
2085
|
-
|
|
2230
|
+
" - `where` / `additionalWhere` \u2014 `expr(...)` or an `expr[]` (ANDed); never a value. Rides `context.search`.",
|
|
2231
|
+
' - \u26A0 `ignoreEmpty` DROPS the predicate when the operand is empty (not zero rows). "Empty" is PHP `empty()` \u2014 `null`, `""`, `"0"`, `0`, `false`, `[]`:',
|
|
2232
|
+
" - `0`/`false` also drop it: an optional numeric/bool filter can't match zero or false (`max_price=0` returns the whole table), and an omitted `input.int()`/`input.bool()` binds `0`/`false`. Use `ignoreEmpty` only for an optional TEXT/LIST filter; for a number/bool use a `nullable: true` input + `s.conditional` on `!= null`.",
|
|
2233
|
+
" - On `in` an empty list returns the UNFILTERED set, so never scope to permitted ids with it (a `bulk.delete` only it scopes throws).",
|
|
2234
|
+
" - `not in` an empty list is the mirror trap, matching NO rows, so an exclusion filter returns nothing when nothing is excluded \u2014 guard both empty cases.",
|
|
2086
2235
|
" - For the full operator set use `cmp(left, op, right, { ignoreEmpty? })` \u2014 `op`: `in`/`not in`/`like`/`ilike`/`between`/`contains`/`includes`/`overlaps`/`@>`/`~`/`search`/\u2026 plus the `expr` comparisons. Database-only \u2014 a runtime condition takes the `expr` set only.",
|
|
2087
|
-
' - \u26A0 `like`/`ilike` take the operand as the PATTERN, verbatim: a bare term matches only an exact whole-string equal, and the endpoint answers HTTP 200 with zero rows
|
|
2236
|
+
' - \u26A0 `like`/`ilike` take the operand as the PATTERN, verbatim: a bare term matches only an exact whole-string equal, and the endpoint answers HTTP 200 with zero rows, no error. For substring matching use `includes`/`not includes`, which wrap the operand in `%\u2026%` themselves and match case-INSENSITIVELY. Prefer them over a hand-built `"%" + term + "%"`, which is non-empty even for an empty term and so defeats `ignoreEmpty`; `includes` composes with it. `contains`/`@>`/`overlaps` are JSON/array containment, not text \u2014 on a text column they 400 `ParseError: Invalid value for param`.',
|
|
2237
|
+
' - **Filter a LIST column** (`f.text({ array: true })`) to rows that hold a value \u2014 the "posts tagged X" query \u2014 with `contains`/`overlaps` and a LIST on the right. \u26A0 A SCALAR on the right 400s `Invalid value for param` every request, whether a literal (`c.text("x")`) or a scalar-typed `inp("tag")`/`ref()` (`export()` warns `db.filter-operand-invalid`) \u2014 wrap the single value in a list first. For an OPTIONAL value add `fl.filter_empty_text` so an omitted one matches nothing (not `[""]`, which `array_push` would leave): `s.set_var("tag_list", withFilters(c.array([]), fl.array_push(inp("tag")), fl.filter_empty_text()))` then `cmp(col("tags"), "contains", ref("tag_list"), { ignoreEmpty: true })`. (`in` cannot take the list column on the RIGHT \u2014 one side must be a scalar.)',
|
|
2088
2238
|
" - Compose nested boolean logic with `and(...)` / `or(...)` groups (also available on `addon()` `where`).",
|
|
2089
2239
|
" - An operand may be a bare value (`col`/`inp`/`ref`/`auth`/`c.*`) OR a **filtered** value (`withFilters(...)`) inline \u2014 the engine compiles the string and arithmetic filters (`trim`, `concat`, `upper`, `lower`, \u2026) into the SQL.",
|
|
2090
2240
|
' - \u26A0 The REQUEST-TIME timestamp filters have no SQL form and kill the request with a bare fatal naming nothing: `epochms_transform`, `epochms_add_ms`, `epochms_add_secs`, `epochms_date`, `epochms_from_format`. For a relative cutoff use the SQL-side family instead (`qf.epochms_add_day(7)`, `qf.epochms_sub_month(1)`, `qf.epochms_year("UTC")`, \u2026) \u2014 or compute it in an earlier `s.set_var` and `ref()` that. `export --strict` reports it; a bare `c.now()` operand is always fine.',
|
|
2091
2241
|
' - `bind: [{ table, as?, join?, where? }]` \u2014 joins (`context.bind[]`). `join` defaults to `"inner"`. `as` defaults to the table name; two joins to the same table need distinct aliases.',
|
|
2092
|
-
' - \u26A0 In `where`/`sort`/`eval` a JOINED column takes a dotted path (`col("team_row.id")`); THIS query\'s own columns stay **bare** (`col("team")`). Qualifying your own by table name needs `tableAlias` (same rule as `aggregate`)
|
|
2242
|
+
' - \u26A0 In `where`/`sort`/`eval` a JOINED column takes a dotted path (`col("team_row.id")`); THIS query\'s own columns stay **bare** (`col("team")`). Qualifying your own by table name needs `tableAlias` (same rule as `aggregate`); without it the engine 400s `ParseError: Invalid value for param` naming the OTHER operand, so export throws.',
|
|
2093
2243
|
' - `bind: [{ table: team, as: "team_row", join: "left", where: expr(col("team"), "=", col("team_row.id")) }]`',
|
|
2094
2244
|
' - `bind: [{ expand: "blog.categories", as: "cat" }]` joins one row per element of a LIST column already in the query; read it as `col("cat.<key>")`.',
|
|
2095
2245
|
' - \u26A0 A join does NOT put the joined table\'s columns on the returned row \u2014 with or without a `bind`, a row is the QUERIED table\'s columns, which is what `InferResponse` types. There is no `row.team_row`. To read a joined column, PROJECT it with an `eval` whose `name` is the dotted path: `eval: [{ name: "team_row.name", as: "team_name" }]` puts `team_name` on the row and on the inferred type. A bare `name` there is `Unsupported parameter reference` at runtime (it qualifies to the base table), and a dotted joined column in `output` is dropped with no error.',
|
|
2096
|
-
' - `returnType` \u2014 `"list"` (default) | `"single"` | `"count"` | `"exists"` | `"stream"` | `"aggregate"`. Drives `context.return.type` AND the `InferResponse` shape: `count`\u2192`number`, `exists`\u2192`boolean`, `single`\u2192`Row|null`, `stream`\u2192`
|
|
2097
|
-
' - `eval: [{ name, as, filters? }]` \u2014 computed columns (`context.eval[]`). Each `as` grafts onto the row as
|
|
2098
|
-
' - An `eval`/`sort`/`where` filter pipeline compiles to **SQL**: `trim`/`lower`/`concat` work there too, plus a DIFFERENT registry than `fl.*`: the vector family, geo `distance`/`within`/`covers`, `search_rank`, the timestamp family, the aggregators. Build these with **`qf.*`** \u2014 `filters: [qf.vector_cos_distance(inp("q"))]` \u2014 which emits the same `{ name, arg }` step with the name, the argument COUNT and any enumerated argument checked at the call site. `qf` carries what the engine registers
|
|
2099
|
-
' - **Vector similarity search** \u2014 the ONLY way to query an `f.vector` column (no `SearchOp` does distance). `eval: [{ name: "embedding", as: "distance", filters: [
|
|
2100
|
-
'
|
|
2101
|
-
'
|
|
2102
|
-
|
|
2246
|
+
' - `returnType` \u2014 `"list"` (default) | `"single"` | `"count"` | `"exists"` | `"stream"` | `"aggregate"`. Drives `context.return.type` AND the `InferResponse` shape: `count`\u2192`number`, `exists`\u2192`boolean`, `single`\u2192`Row|null`, `stream`\u2192 a cursor only `s.foreach` reads (returned, it serves `"@stream"`; warns `db.stream-returned`), `list`\u2192`Row[]`/envelope, `aggregate`\u2192rows keyed by the `aggregate.group`/`eval` aliases. \u26A0 A bare `count` of ZERO has no reliable shape: it answers `0` or an EMPTY body (a client JSON parse error). Wrap it: `response: { count: ref("n") }`.',
|
|
2247
|
+
' - `eval: [{ name, as, filters? }]` \u2014 computed columns (`context.eval[]`). Each `as` grafts onto the row in `InferResponse` as `unknown`, or as the joined column for an unfiltered `<bind as>.<col>` (`| null` under `left`); shadowing a real column throws. \u26A0 `output` is applied to the eval columns too: with a non-empty `output`, LIST the alias there (`output: ["id", "<alias>"]`) or the engine drops it from the result (`export()` warns `db.eval-unselected`; an ADDON alias survives an omitting `output`, an eval alias does not). Write `name` **bare** (`"embedding"`) \u2014 it is alias-qualified on emit exactly like `aggregate` (a bare eval name is `Unsupported param format` at runtime), and the statement declares the alias it used. An `as` alias is `sort`able in the SAME query. \u26A0 An eval over a LIST column (`f.text({ array: true })`) is PER-ELEMENT (the engine unnests the column), so its `filters` must START with an AGGREGATE (`qf.count()` for the element count, `qf.to_list()`, \u2026): a non-aggregate first filter like `qf.array_length()` 500s `Aggregate filter must be processed first` at request time, with no export warning.',
|
|
2248
|
+
' - An `eval`/`sort`/`where` filter pipeline compiles to **SQL**: `trim`/`lower`/`concat` work there too, plus a DIFFERENT registry than `fl.*`: the vector family, geo `distance`/`within`/`covers`, `search_rank`, the timestamp family, the aggregators. Build these with **`qf.*`** \u2014 `filters: [qf.vector_cos_distance(inp("q"))]` \u2014 which emits the same `{ name, arg }` step with the name, the argument COUNT and any enumerated argument checked at the call site. `qf` carries what the engine registers: the per-part extractors take a timezone (`qf.epochms_month("UTC")`), `qf.round`\'s precision is required, `qf.time`\'s part is an enum. `QUERY_FILTER_NAMES`/`QUERY_AGGREGATE_NAMES` list the set; the raw `{ name, arg }` form still works for anything `qf` does not carry (`vector_distance`, which has no registered engine class).',
|
|
2249
|
+
' - **Vector similarity search** \u2014 the ONLY way to query an `f.vector` column (no `SearchOp` does distance). `eval: [{ name: "embedding", as: "distance", filters: [qf.vector_cos_distance(inp("q"))] }]` + `sort: [{ sortBy: "distance", dir: "asc" }]` ranks in the DATABASE over the column\'s index. Match the filter to the index `op` (`vector_cos_distance`\u2194`vector_cosine_ops`, `vector_l2_distance`\u2194`vector_l2_ops`, `vector_l1_distance`\u2194`vector_l1_ops`, `vector_inner_product`\u2194`vector_ip_ops`); `vector_cos_similarity` is the inverse, so sort it `desc`. The same filter on a `where` operand cuts off BY distance instead of by row count.',
|
|
2250
|
+
' - **Full-text search** \u2014 query a `type: "search"` index by the `name` you gave it, spelled as a column `"$<name>"`: `where: cmp(col("$ft"), "search", inp("q"))`, rank with `eval: [{ name: "$ft", as: "rank", filters: [qf.search_rank(inp("q"))] }]` + `sort: [{ sortBy: "rank", dir: "desc" }]` (the field `priority` weights the rank). \u26A0 A `"search"` cmp on a PLAIN column (`col("title")`, no `$`) 500s, and an UNNAMED search index can\'t be referenced at all (warns `table.search-index-unnamed`).',
|
|
2251
|
+
' - `aggregate: { group?, eval?, sort?, paging? }` (with `returnType:"aggregate"`) builds `context.return.aggregate`. `group`/`eval` are `{ name, as, filters? }`, an aggregator like `sum`/`count` riding `filters`. Some aggregators resolve ONLY here, not in a runtime value pipeline: `count_distinct`, `median`, `to_list`/`to_distinct_list` (each with `_asc`/`_desc`), and `vector_distance`. \u26A0 `avg` over a group whose values are ALL null returns `0`, not `null` (an unrated item reads as rated zero); a group with SOME nulls correctly averages only the non-nulls.',
|
|
2252
|
+
' - \u26A0 Write each `name` as a **bare** column (`"status"`). It is alias-qualified to `"<alias>.status"` on emit \u2014 the engine rejects an unqualified column in an aggregate with `Unsupported param format`. \u26A0 A JOINED column cannot be named here (refused at build): project it with a query `eval` (`{ name: "pr.name", as: "pname" }`) and name that alias BARE (`group: [{ name: "pname", as: "pname" }]`).',
|
|
2253
|
+
" - It qualifies with `tableAlias`, else the table's name, and the statement declares that alias (`context.dbo.as`) itself.",
|
|
2103
2254
|
' - `sort: [{ sortBy: <col>, dir?: "asc"|"desc"|"rand" }]` and `paging: { page?, per_page?, offset?, totals?, metadata?, search?, sort? }` ride `context.return.list`.',
|
|
2104
2255
|
" - \u26A0 `paging` with a page/per_page/offset field and `metadata` on (the DEFAULT) wraps the result in an envelope `{ items: Row[], curPage, nextPage, prevPage, offset, perPage, itemsReceived }` \u2014 plus `itemsTotal`/`pageTotal` when `totals: true` \u2014 instead of a bare `Row[]`. `InferResponse` reflects it. `paging: { metadata: false }` keeps the bare array.",
|
|
2105
2256
|
' - \u26A0 Under the ENVELOPE, `output` selects from the envelope, not the row: write `output: ["itemsReceived", "curPage", "items.id", "items.title"]`. A bare column list matches no envelope key, so every key is dropped and the response is `[]` at HTTP 200 with no error (and `ref("<var>.items")` then fails on a var that is gone). With `metadata: false` the statement binds the rows, so bare columns are the right form there. `export()` warns on a row-rooted selection under an envelope; `--strict` fails it.',
|
|
2106
2257
|
" - Read `nextPage` (`number|null`) as the typed has-next signal.",
|
|
2107
2258
|
' - **Input-bound paging:** `page`/`per_page`/`offset` also accept a `Value` (`inp("page")`), riding `context.simpleExternal` while the static block stays the engine gate (`enabled:true`). `paging.search`/`sort` are `Value` dynamic overrides.',
|
|
2108
2259
|
" - A `search`/`sort`-only `paging` (no numeric field) does NOT paginate.",
|
|
2109
|
-
" - `external: { value, permissions? }` \u2014 the
|
|
2260
|
+
" - `external: { value, permissions? }` \u2014 the whole paging config as one value (forces the gate on). It falls back to input-bound `paging` when it resolves empty, so supplying both is valid.",
|
|
2110
2261
|
' - `distinct` \u2014 `"auto"` (default) | `"yes"` | `"no"`, riding `context.return.<list|stream>.distinct`.',
|
|
2111
2262
|
"- `s.db.truncate({ table, reset?, as? })` \xB7 `s.db.schema({ table, path, as? })`.",
|
|
2112
2263
|
'- `s.db.direct_query({ sql, responseType?, args?, parser?, as? })` \u2014 `sql` is a **raw string** (not a `Value`); binds go in `args: Value[]`. `parser: "template_engine"` renders the body as a template first \u2014 how a query interpolates a column or table name a bound arg cannot carry; omit it for the default.',
|
|
2113
2264
|
" - Template placeholders are Twig over the request scope: `{{ $input.name }}` for an input, `{{ $var.name }}` for a stack variable. \u26A0 A BARE `{{ name }}` renders as the empty string \u2014 HTTP 200, no error, a query that silently ran with a blank where the value belonged. A bound `?` arg carries a VALUE without the template at all.",
|
|
2114
|
-
" - \u26A0 A table's PHYSICAL name is **not stable across deploys**. A deploy is a full replace
|
|
2115
|
-
"- `s.db.external.<engine>.direct_query({ sql, connectionString, responseType?, args?, parser?, as? })` \u2014 same shape against an EXTERNAL database; `<engine>` is `postgres`/`mysql`/`mssql`/`oracle`/`snowflake`. `connectionString` is a `Value` \u2014 reach for `env(...)`, not a literal \u2014 stored as `context.connection_string_flex`. A bare string stores
|
|
2116
|
-
|
|
2265
|
+
" - \u26A0 A table's PHYSICAL name is **not stable across deploys**. A deploy is a full replace that recreates every table, so the id in its name changes on every deploy. Never store, cache, hardcode or fixture one: resolve it from `information_schema` inside the same request that uses it.",
|
|
2266
|
+
"- `s.db.external.<engine>.direct_query({ sql, connectionString, responseType?, args?, parser?, as? })` \u2014 same shape against an EXTERNAL database; `<engine>` is `postgres`/`mysql`/`mssql`/`oracle`/`snowflake`. `connectionString` is a `Value` \u2014 reach for `env(...)`, not a literal \u2014 stored as `context.connection_string_flex`. A bare string stores `context.connection_string` instead (an env-var name unless it looks like a URL); each form round-trips as itself.",
|
|
2267
|
+
'- `s.db.transaction({ body })` \u2014 run a `Statement[]` atomically. It returns nothing, so it takes no `as`: read what the body binds. An `s.return` in the body ends the WHOLE stack with that value, and the writes before it commit. \u26A0 Atomic, not exclusive: a check-then-insert DOUBLE-BOOKS under concurrency (`lock: true` on the check locks only rows it returns). First lock a shared PARENT row: `s.db.get({ table: rooms, fieldValue: inp("room_id"), lock: true, as: "room" })`.',
|
|
2117
2268
|
' - The body shares the enclosing stack: a variable it binds (`as: "order"` on an `s.db.add`) is still bound AFTER the transaction.',
|
|
2118
2269
|
"- `s.db.bulk.add({ table, items, allowIdField?, as? })` / `s.db.bulk.update` / `s.db.bulk.patch` \u2014 `items` is an array `Value`.",
|
|
2119
|
-
|
|
2120
|
-
' - \u26A0 **`bulk.update` is a whole-row REPLACE: every column an item OMITS is zeroed** (`""`/`0`/`null`), HTTP 200, no error \u2014 `{ id: 7, status: "done" }` blanks the rest of row 7. **Use `s.db.bulk.patch`** for the partial write "update these rows" means. `export()` warns on a STATIC `items` missing columns (`--strict` fails); a `ref`/`inp` `items` is uninspectable.',
|
|
2121
|
-
"- `s.db.bulk.delete({ table, where?, allRows?, as? })` \u2014 deletes rows by a `context.search` filter. `where` is the same surface as `s.db.query` (`expr(...)`/`cmp(...)`, `and(...)`/`or(...)` groups, an array of those ANDed
|
|
2122
|
-
'- `s.db.increment({ table, where, fieldName, value, returnType?, output?, addon?, as? })` \u2014 adds `value` (a number or `Value`; negative decrements) to one `int`/`decimal` column on every row `where` matches, in ONE atomic locked UPDATE. **Use it for counters, stock, balances and tallies**: `db.get` \u2192 math \u2192 `db.edit` loses updates under concurrency, and so do `db.bulk.patch`/`update`. A guard in `where` (`expr(col("stock"), ">=", c.int(1))`) is re-checked under the row lock. `returnType: "count"` binds the changed-row count instead of the rows, and then takes no `output`/`addon`.',
|
|
2270
|
+
' - \u26A0 `bulk.add` **drops `id` on every row unless `allowIdField: true`** (silently, next sequence value instead) \u2014 the opposite of `seed`, where `id` pins. Rows referenced by a foreign key need `allowIdField: true`; literal `items` carrying `id` without it throw. `bulk.update`/`patch` keep `id` (their match key). A unique violation rolls back the WHOLE batch: 500 "SQL Error: 23505, UNIQUE VIOLATION".',
|
|
2271
|
+
' - \u26A0 **`bulk.update` is a whole-row REPLACE: every column an item OMITS is zeroed** (`""`/`0`/`null`), HTTP 200, no error \u2014 `{ id: 7, status: "done" }` blanks the rest of row 7. It also resets `created_at`. **Use `s.db.bulk.patch`** for the partial write "update these rows" means. `export()` warns on a STATIC `items` missing columns (`--strict` fails); a `ref`/`inp` `items` is uninspectable.',
|
|
2272
|
+
"- `s.db.bulk.delete({ table, where?, allRows?, as? })` \u2014 deletes rows by a `context.search` filter. `where` is the same surface as `s.db.query` (`expr(...)`/`cmp(...)`, `and(...)`/`or(...)` groups, an array of those ANDed) and encodes through the identical `{expression:[\u2026]}` search shape. \u26A0 A filter that constrains nothing (missing, empty, or `x OR and()`) deletes **every** row, so it **throws**: pass the filter, or `allRows: true` for a deliberate wipe (both together also throw). `allRows` emits the empty search the engine requires and returns the deleted count; reach for `s.db.truncate({ table, reset: true })` when the id sequence should restart too.",
|
|
2273
|
+
'- `s.db.increment({ table, where, fieldName, value, returnType?, output?, addon?, as? })` \u2014 adds `value` (a number or `Value`; negative decrements) to one `int`/`decimal` column on every row `where` matches, in ONE atomic locked UPDATE. **Use it for counters, stock, balances and tallies**: `db.get` \u2192 math \u2192 `db.edit` loses updates under concurrency, and so do `db.bulk.patch`/`update`. A guard in `where` (`expr(col("stock"), ">=", c.int(1))`) is re-checked under the row lock. To guard one column against ANOTHER of the same row (`used < max_uses`), set `tableAlias` on the statement and qualify the RIGHT operand with it (`expr(col("used"), "<", col("cpn.max_uses"))` with `tableAlias: "cpn"`) (a bare right-hand column throws at export). `returnType: "count"` binds the changed-row count instead of the rows, and then takes no `output`/`addon`.',
|
|
2123
2274
|
" - \u26A0 A `where` that constrains nothing (missing, empty, or `x OR and()`) changes NO rows and **throws**. A null stored value counts as 0. A fractional `value` on an `int` column, a non-numeric or list column, the `id` key, and a result that overflows the column are rejected with no rows changed.",
|
|
2124
2275
|
""
|
|
2125
2276
|
];
|
|
2126
2277
|
const stmtRuntime = [
|
|
2127
2278
|
"Runtime behavior (what the `as:` output holds, and misses):",
|
|
2128
2279
|
"",
|
|
2129
|
-
"- `db.get` binds **`null`** when no row matches (it does NOT throw)
|
|
2130
|
-
"- `db.edit` binds the **full, post-mutation row**. `db.add` binds the **full inserted row**, including the auto-assigned `id` and `created_at`.
|
|
2131
|
-
'- Unlike `db.get`, `db.edit` and `db.del` **throw** `NotFound` (HTTP 404) when no row matches the field. `db.add` throws on a unique-constraint violation: HTTP 500 `ERROR_FATAL` "Duplicate record detected\u2026", earlier writes kept. No error type is 409.
|
|
2280
|
+
"- `db.get` binds **`null`** when no row matches (it does NOT throw); null-check it. On a hit it binds the **full row**. (`db.has` is the boolean existence test.)",
|
|
2281
|
+
"- `db.edit` binds the **full, post-mutation row**. `db.add` binds the **full inserted row**, including the auto-assigned `id` and `created_at`. `db.del` **binds `null`**, not the deleted row.",
|
|
2282
|
+
'- Unlike `db.get`, `db.edit` and `db.del` **throw** `NotFound` (HTTP 404) when no row matches the field. `db.add` throws on a unique-constraint violation: HTTP 500 `ERROR_FATAL` "Duplicate record detected\u2026", earlier writes kept. No error type is 409.',
|
|
2283
|
+
'- `s.try_catch` catches it \u2014 and `s.precondition`/`guard.*` failures, answering 200 (`caught("code")`: `ERROR_CODE_NOT_FOUND`, \u2026) \u2014 so re-raise with an `s.precondition` in `catch` to keep a status.',
|
|
2284
|
+
'- No partial unique index: NULLs never collide, so null the key (or delete the row) to free it. \u26A0 A unique-index column that may be ABSENT must be `nullable: true` \u2014 a NON-nullable column stores an omitted/null cell as its zero value (`""`/`0`), which is NOT null and DOES collide, so only ONE row can omit it (the second 500s `Duplicate record detected`). An "optional composite key" needs the columns `nullable: true`.',
|
|
2132
2285
|
"- **`InferResponse<typeof query>`** derives an endpoint's response type. It resolves object-literal responses to those keys; a `response: ref(\"x\")` returning a variable bound by a TOP-LEVEL db op on a `table()` resolves to that op's result:",
|
|
2133
2286
|
" | statement | resolves to | on a miss |",
|
|
2134
2287
|
" |---|---|---|",
|
|
@@ -2138,42 +2291,50 @@ function renderSections(m) {
|
|
|
2138
2291
|
" | `db.has` | `boolean` | \u2014 |",
|
|
2139
2292
|
" | `db.bulk.delete` | `number` (count) | \u2014 |",
|
|
2140
2293
|
' | `db.increment` | `Row[]` (updated rows), or `number` with `returnType: "count"` | `[]` / `0` |',
|
|
2141
|
-
" | `db.del`, `db.bulk.add`/`bulk.update`, raw `direct_query` | `unknown` (the
|
|
2142
|
-
' - A `get`/`query` `output: [...]` selection narrows to a `Pick` (still `| null` for `get`). A dotted `ref("row.col")` into a `db.get` row
|
|
2294
|
+
" | `db.del`, `db.bulk.add`/`bulk.update`, raw `direct_query` | `unknown` (untyped; `bulk.add` binds the new ids, `bulk.update` the rows) | \u2014 |",
|
|
2295
|
+
' - A `get`/`query` `output: [...]` selection narrows to a `Pick` (still `| null` for `get`). A dotted `ref("row.col")` into a `db.get` row types `Col` (a miss 500s); `ref(path, { safe: true })` types `Col | null`.',
|
|
2143
2296
|
" - A value reshaped by a lambda, or a variable built by control flow, also resolves to `unknown`.",
|
|
2144
2297
|
' - A CALL binds the TARGET\'s response type: `s.function.call`/`s.function.run`/`s.api.call`/`s.tool.call` given a def HANDLE brand their `as` with `InferResponse` of the target, so `ref("out.field")` types to that field. What the target resolves to is what propagates \u2014 declare `responseShape` on the TARGET to fix every caller at once. A target named by STRING has no def to read and stays `unknown`; an async `s.function.run` binds its job id (`string`), not the result.',
|
|
2145
2298
|
" - In an object-literal response the KEYS are always known; a `c.*` constant VALUE types like an `s.set_var` of it (`{ success: c.bool(true) }` \u2192 `{ success: boolean }`).",
|
|
2146
|
-
' - A NESTED member resolves to any depth
|
|
2299
|
+
' - A NESTED member resolves to any depth, in either spelling \u2014 `{ user: obj({ id: ref("row.id") }) }` and the raw literal `{ user: { id: ref("row.id") } }` both derive `{ user: { id: Col } }`. A raw scalar NESTED member types itself (`{ stats: { count: 3 } }` \u2192 `{ stats: { count: number } }`), but a TOP-LEVEL member must be a `Value` \u2014 a bare scalar there (`{ count: 3 }`) is a type error and `query()` throws at load, so write `{ count: c.int(3) }`.',
|
|
2147
2300
|
" - Runs on every response-bearing kind \u2014 `query`, `defineFunction`, `realtimeMessage`, `tool`, `middleware`, and the response-bearing triggers \u2014 each of which also accepts `responseShape`. A trigger builds its stack and response through CALLBACKS (`stack: (t) => [...]`), and the trace follows through them.",
|
|
2148
|
-
" -
|
|
2149
|
-
" - The shapes that never derive, and the one line that closes each: rows built in `s.lambda` (JS is opaque to the walk) \u2192 `responseShape: [] as Row[]`; a var bound ONLY inside branches \u2192 `responseShape` (a branch/case/loop/`try`/`catch` re-binding unions in; one in EVERY branch replaces); a call whose target is named by STRING \u2192 give the TARGET a `responseShape` (a handle then carries it) or declare it here. Use `responseShape` as the FIRST move here.",
|
|
2301
|
+
" - The FIRST move for any `unknown`: declare `responseShape` on the def (`responseShape: null as InferRow<typeof t> | null`) \u2014 available on EVERY kind listed above, `query` included; the declaration ALWAYS overrides derivation. The shapes that never derive, and the one line that closes each: rows built in `s.lambda` (JS is opaque to the walk) \u2192 `responseShape: [] as Row[]`; a var bound ONLY inside branches \u2192 `responseShape` (a branch/case/loop/`try`/`catch` re-binding unions in; one in EVERY branch replaces); a call whose target is named by STRING \u2192 give the TARGET a `responseShape` (a handle then carries it) or declare it here.",
|
|
2150
2302
|
' - An `s.set_var` holding a `c.*` CONSTANT brands its binding with that constant\'s JS type, so `ref("n")` after `s.set_var("n", c.int(1))` resolves to `number` (widened: `c.bool(false)` \u2192 `boolean`; `s.update_var` re-binds). A filter chain \u2014 the value\'s own or `asFilters` \u2014 then retypes it (`[fl.to_int()]` \u2192 `number`). A bare `ref`/`inp` stays `unknown`.',
|
|
2151
|
-
' - \u26A0 A
|
|
2303
|
+
' - \u26A0 A var bound ONLY inside a branch body \u2014 an `s.conditional` `then`/`else`/`elif`, an `s.switch` case, a loop body (`s.for`/`s.foreach`) that ran zero times, or an `s.try_catch` `try` \u2014 does NOT exist when that path is skipped, so a later `ref` to it 500s `Missing var entry: <name>` (NOT null). `{ safe: true }` does NOT suppress it (it has no effect on a bare, dot-free name), and export warns `stack.var-conditionally-bound`. Declare the var on the ENCLOSING path first: `s.set_var("x", c.null())` before the block.',
|
|
2304
|
+
' - \u26A0 A hand-written `s.precondition` does not narrow the STATIC type. One (or a conditional) proving a `db.get` row non-null leaves `InferResponse` at `Row | null`. `guard.found("row")` DOES narrow: it emits the same non-null check (404) and drops `| null` from `row` \u2014 whole, dotted, and addon grafts alike \u2014 after it. `guard.owner` narrows the same way. Reach for `responseShape` only when neither fits.',
|
|
2305
|
+
" - \u26A0 `InferResponse` reads the `response` field ALONE \u2014 an `s.return(value)` ANYWHERE in the stack (an early cache hit, an idempotent replay, a `respond.status(409)` + `s.return` fast path) is INVISIBLE to it, including ones nested in `s.conditional`/`switch`/`foreach`/`try`. So the type covers only the fall-through `response`, and a typed client misses every early body. Declare `responseShape` as the UNION of every body the endpoint can serve: `responseShape: null as { value: number } | { cached: boolean }` (without one, export warns `response.return-outside-type`).",
|
|
2152
2306
|
' - \u26A0 A `resultStrategy: "replace"` middleware attached `post` reshapes the endpoint\'s output at runtime, which the static walk cannot see. Declare `responseShape` when a post middleware rewrites the response. A `merge` one makes a LIST response an index-keyed object; its keys are not inferred.',
|
|
2153
|
-
" - \u26A0 **Spreading a `Statement[]` helper into a stack kills the whole walk.**
|
|
2307
|
+
" - \u26A0 **Spreading a `Statement[]` helper into a stack kills the whole walk.** `...myHelper()` where the helper returns `Statement[]` widens the stack's TUPLE type, and EVERY `as` in that stack \u2014 including ones declared after the spread \u2014 stops resolving. The response then types as `StackTupleWidened`. Fix: return `statements(s.a(...), s.b(...))` from the helper (preserves the tuple). A helper that builds its array in a LOOP cannot be a tuple; declare `responseShape` there.",
|
|
2154
2308
|
"- **Addons** enrich returned rows. `db.query`/`get`/`add`/`edit`/`patch` accept `addon: [{ addon, as, input?, output?, children? }]`; `db.add_or_edit`/`del`/`has`/`truncate` take no `addon`.",
|
|
2155
2309
|
' - `addon` is the target (name or def handle). `as` is the destination on the row \u2014 a bare alias (`"_user"`) or a dotted `offset.alias`, authored relative to a row. Under a metadata paging envelope the `items[]` offset is prefixed automatically; writing it yourself is tolerated and not double-prefixed.',
|
|
2156
2310
|
" - `envelope: true` grafts once onto a paged query's envelope instead of each row.",
|
|
2157
|
-
" - `input` maps addon inputs \u2014 bind a parent-row column with `out(col)`. `output` restricts addon columns. `children` nests addons.",
|
|
2311
|
+
" - `input` maps addon inputs \u2014 bind a parent-row column with `out(col)`. `output` restricts addon columns. `children` nests addons onto each graft element (typed).",
|
|
2158
2312
|
" - The DEFINITION side \u2014 the `addon({...})` factory and `registerAddons` \u2014 is a def shape in `llms/kinds-core.md`.",
|
|
2159
|
-
" - Attaching a typed `addon({ table, output })` handle merges its alias (the last `as` segment) onto the row in `InferResponse`: `{cols}
|
|
2313
|
+
" - Attaching a typed `addon({ table, output })` handle merges its alias (the last `as` segment) onto the row in `InferResponse`: an OPTIONAL `{cols}` for `single` (absent, not null, on no match), `{cols}[]` for `list`, `number` for `count`, `boolean` for `exists`, and for `aggregate` an array keyed by the `group`/`eval` aliases \u2014 ONE optional object when `eval` has no `group` (`unknown` values; `unknown` when neither is declared).",
|
|
2160
2314
|
" - An attachment-level `output` narrows an object/array graft further. A bare-NAME reference grafts `unknown` \u2014 narrow it at the call site.",
|
|
2161
2315
|
" - \u26A0 An alias that shadows an existing column on the queried table throws at build time; rename with a `_` prefix.",
|
|
2162
2316
|
"- **Middleware attachment** runs a reusable `middleware({...})` before/after a host's own stack. Distinct from `s.middleware.call` (inline invoke).",
|
|
2163
2317
|
" - Attach with the host's `middleware: { pre, post }` field on `query`/`function`/`task`/`tool`/`apiGroup` (NOT triggers): each phase is an ordered list of middleware refs (def handle or name), or `{ middleware, active: false }` to keep an entry disabled.",
|
|
2164
2318
|
" - Providing a phase **overrides** it (sets the stored `pre_customize`/`post_customize` flag); omitting a phase **inherits** the parent tier's chain \u2014 the engine resolves Query \u2192 API Group \u2192 Workspace at request time (override, not merge; the API-Group tier applies to queries \u2014 functions/tasks/tools have no API-group binding and inherit straight from the workspace).",
|
|
2165
2319
|
" - Prefer a def handle over a bare name when the middleware pins an explicit `guid`.",
|
|
2320
|
+
' - `exceptionPolicy` governs what a **throw** in the middleware stack does to the request. `"rethrow"` is the **default** \u2014 the throw aborts the request and surfaces the authored `error`/status (a tripped `s.redis.ratelimit` \u2192 HTTP 429); the `post` chain still runs. `"silent"` swallows the throw, so a guard set to it is **not enforced** \u2014 advisory middleware only. `"critical"` is `"rethrow"` plus skipping the `post` chain.',
|
|
2166
2321
|
" - `pre: middleware.clear()` (an empty list) overrides with nothing \u2014 stop inheriting.",
|
|
2167
2322
|
" - Workspace-level defaults are the terminal tier: `workspaceConfig({ middleware: { query: { pre }, function, task, tool } })` emits the flat `{host}_{phase}` map (no `_customize` flags) \u2014 setting it replaces the whole workspace map, so unlisted hosts are cleared; omit the field to leave existing workspace middleware untouched.",
|
|
2168
2323
|
"- **Middleware request context.** A `pre` middleware runs **after** auth resolution, so `auth()` is available inside the middleware when the host is authenticated (its `auth` names an auth table); on a public host there is no caller identity for it to resolve.",
|
|
2169
|
-
' -
|
|
2170
|
-
" -
|
|
2324
|
+
' - A rate limit keyed by `auth("id")` is per-user on an authenticated endpoint; on a public endpoint `auth()` cannot resolve, so the request FAILS with a 403 on the first call, under `max`, with the host never running.',
|
|
2325
|
+
" - `export()` **warns** (never blocks) when a middleware whose stack references `auth()` reaches a host where `auth()` may be null \u2014 a `query` with no auth table, a `task` (scheduled, never authenticated), or a `function`/`tool` (whose auth is caller-dependent). An authenticated query (its own `auth` table set) is skipped.",
|
|
2171
2326
|
" - Inherited attachment (API group, workspace tier) warns too.",
|
|
2172
2327
|
'- **Rate-limit recipe (the canonical middleware).** Author it with `s.redis.ratelimit` and a **composite key** built via the filter chain \u2014 `"prefix" + auth("id")` does not exist, you build the key: `middleware({ name: "write_rl", exceptionPolicy: "rethrow", stack: [ s.redis.ratelimit({ key: withFilters(c.text("rl:write:"), fl.concat(auth("id"))), max: c.int(10), ttl: c.int(30), error: c.text("Too fast.") }) ] })`.',
|
|
2173
|
-
' - `exceptionPolicy
|
|
2328
|
+
' - The default `exceptionPolicy: "rethrow"` aborts a tripped limit with HTTP 429; `"silent"` lets the over-limit request through. Without `error` it never aborts \u2014 the request always runs on (`export()` warns) \u2014 but the bound value is NOT constant `false`: it binds `true` while the caller is under `max` and `false` once over (branch on it with that polarity).',
|
|
2174
2329
|
" - Attach it with `middleware: { pre: [writeRl] }` on an **authenticated** host; on a public host key off `sys.remoteIp()`.",
|
|
2175
2330
|
" - **Shared-bucket rule:** co-attaching one middleware object to N hosts means all N share the *same* key \u21D2 *one* counter \u2014 `max: 10` is a global per-user budget across them, not 10-per-host. Vary the key (fold in the host/action name) for an independent limit per host.",
|
|
2176
|
-
'- **
|
|
2331
|
+
'- **Redis (`s.redis.*`) semantics.** \u26A0 `set` REFUSES a null or `""` `data` with HTTP 400 `Missing param: data`, so you cannot negative-cache an empty/absent result \u2014 store a sentinel (`c.text("__none__")`) instead. A stored `false` reads back from `get` as `false`, INDISTINGUISHABLE from a miss \u2014 use `has` to tell them apart. `ttl: 0` means FOREVER (no expiry); a NEGATIVE `ttl` is a 500 `Unable to store data in cache`. `incr`/`decr` on a missing key start at 0 and bind the new value (a negative `by` works). List ops: `push`/`unshift` bind the new LENGTH; `pop`/`shift` bind one element, or a list with `count` (last-first, `pop count 2` \u2192 `[5,4]`); on an empty or missing key they bind `false` (not null); `count` on a missing key is `0`, `range` is `[]` (and `range` with no start/stop is the whole list); `remove` with no `count` drops EVERY occurrence, with `count` it binds the number removed. `keys({ search })` is a GLOB binding the full key names. Objects and lists round-trip through `set`/`get` and the list ops.',
|
|
2332
|
+
"- **File resources** \u2014 the value the `s.storage.*` and `s.zip.*` statements pass BETWEEN each other. A file resource is a short-lived (~24 h) TOKEN, not storage. PRODUCED by `inp(\"file\")` (an `input.file`), `s.storage.create_file_resource`, `s.zip.create_archive`, and an extract entry's `.resource`. CONSUMED by `s.storage.read_file_resource`, the `s.storage.create_*` statements, and `s.zip.add_to_archive`/`view_contents`/`extract`. \u26A0 A STORED file is NOT one: a `f.attachment()` cell / a `create_attachment` result / a cell's `url` passed to `read_file_resource` or `s.zip.*` 500s `Invalid file resource` \u2014 a stored file's bytes are not readable back through these. \u26A0 `s.zip.extract` binds `[{ name, size, last_modified, resource }]`; pass the entry's `.resource` (`ref(\"extracted.0.resource\")`) to `read_file_resource`, NOT the entry itself (500). \u26A0 In a RESPONSE a file resource serializes as an opaque token STRING, not an object, and it EXPIRES \u2014 persisting one in a table/redis looks fine and breaks later. `read_file_resource` binds `{ name, size, mime, data }` where `data` is RAW bytes \u2014 `fl.base64_encode()` it in the stack before a JSON response (which mangles raw binary). `create_file_resource` refuses a `/` in `filename` (400 `Invalid characters detected.`), though a `zip.add_to_archive` ENTRY name accepts `dir/b.txt`.",
|
|
2333
|
+
'- **Zip archives (`s.zip.*`)** \u2014 build then PERSIST. `s.zip.create_archive({ filename, password?, password_encryption?, as: "zip" })` binds an archive handle; `s.zip.add_to_archive`/`delete_from_archive` bind NOTHING and MUTATE the var passed as `zip` IN PLACE (loop over files, `create_file_resource` each, then `add_to_archive({ file: ref("res"), filename, zip: ref("zip") })`). \u26A0 `view_contents`/`extract` on an archive with NO entries 500s (`Invalid or uninitialized Zip object` / `Fatal Error`) \u2014 guard a possibly-empty export with a count check. `view_contents` binds `[{ name, size, last_modified }]`, `extract` `[{ name, size, last_modified, resource }]` (the `.resource` is a file resource; see **File resources**). PERSIST the archive with `s.storage.create_attachment({ value: ref("zip") })` (a bare file resource in a response expires). `password` with no `password_encryption` writes standard ZipCrypto; `AES-256` writes method 99, which macOS `unzip` cannot read; the password is per-entry and checked on extract. `delete_from_archive` of a name not in the archive is a silent no-op. \u26A0 `create_archive` needs a PAID (non-free) instance. (Uploaded archives must arrive as Content-Type `application/zip` \u2014 see `llms/errors.md`.)',
|
|
2334
|
+
'- **`s.math.*` MUTATES a variable in place** \u2014 `s.math.add`/`sub`/`mul`/`div`/`mod`/`bitwise.*` take `{ name, value }` and REWRITE the existing var `name` (declare it with `s.set_var` first; an undeclared `name` 500s `Missing var entry`). There is NO `as` \u2014 the catalog\'s `[output]` on `add`/`bitwise.*` is an engine artifact, the result is the mutated var. Numeric TEXT coerces (`"5" + 3` \u2192 `8`) and a null var acts as `0`; a non-numeric operand (`true`, `"abc"`, a list) 500s `Numbers are required for mathematical operations`. `div` of int/int yields a DECIMAL unless it divides exactly (`7/2` \u2192 `3.5`, `6/3` \u2192 `2`); `div`/`mod` by `0` is a catchable `ERROR_FATAL` (`Division by zero`/`Modulo by zero`). Integer overflow past signed-64-bit SILENTLY becomes a float (`9223372036854775807 + 1` \u2192 `9.22e18`), losing exactness; `bitwise.*` truncate a decimal operand and use two\'s complement on negatives. Same rules on the `fl.*` equivalents.',
|
|
2335
|
+
'- **`s.math.mod` / `fl.mod` is INTEGER modulo** \u2014 unlike its siblings `add`/`sub`/`mul`/`div`, which handle decimals exactly, `mod` TRUNCATES both operands toward zero before the remainder, so a decimal modulo returns WRONG data at HTTP 200: `c.decimal(5.5) mod c.decimal(2.5)` \u2192 `1` (the true remainder is `0.5`), and the sign follows the dividend (`-7 mod 3 = -1`). A divisor with `|x| < 1` truncates to 0 and 500s `Modulo by zero`. `c.expression("5.5 % 2.5")` and `withFilters(\u2026, fl.mod(2.5))` do the same (engine-wide PHP `%`). For a REAL decimal remainder compute `a - b*floor(a/b)` with the decimal `div`/`mul`/`sub`, or a lambda.',
|
|
2336
|
+
"- **Math failure modes** (`fl.*` aggregates and arithmetic, same engine as `s.math.*`). \u26A0 On an EMPTY list the aggregates DISAGREE: `fl.sum` \u2192 `0`, `fl.product` \u2192 `1`, `fl.min`/`fl.max` \u2192 `null`, but `fl.avg` 500s `Infinite value` (an `avg` over a filtered list that comes back empty fails the whole request) \u2014 guard it with `fl.count()` or a conditional. `fl.ln(0)` raises a catchable `ERROR_FATAL` `Infinite value`. \u26A0 A NaN or \xB1INF result does NOT raise: `fl.sqrt`/`fl.ln`/`fl.log`/`fl.log10` of a NEGATIVE, `fl.pow` of a negative base to a fractional power or past the float range, `fl.acos`/`fl.asin` outside [-1, 1], `fl.acosh` below 1, `fl.atanh` at or beyond \xB11. A response carrying one serializes to nothing and answers HTTP 200 with an EMPTY body (a JSON client throws on parse, far from the cause), so guard the operand's domain with an `s.conditional` BEFORE the filter. `fl.number_format` on a text value 500s.",
|
|
2337
|
+
'- **Date filter failure modes** \u2014 the request-time date filters fail QUIETLY on null/empty/unparseable input. A NULL or omitted timestamp reads as epoch 0, so `fl.epochms_date` formats it as `1970-01-01 \u2026` and `fl.epochms_transform` shifts from 1970 \u2014 GUARD a nullable timestamp (`s.conditional` on `= null`) before formatting. `fl.epochms_from_format` returns `""` on a parse MISS (treat `""` as failure) and a numeric STRING (not an int) on a hit. `fl.to_epochms` binds `0` for `""` but 400s `Invalid timestamp format.` on non-empty garbage (the one that fails the request, not silently). `fl.epochms_transform` quirks: `llms/filters.md`.',
|
|
2177
2338
|
"",
|
|
2178
2339
|
'- **Request history** controls per-object execution capture (the request/task/trigger debugger). Authored as a single scalar `history` field on any primitive: `false` off, `true` on at the default capture depth, a number = capture depth (how many statement executions are recorded per history record \u2014 NOT record retention), `"all"` unlimited.',
|
|
2179
2340
|
" - **Omit `history` to inherit** \u2014 the engine resolves object \u2192 container \u2192 workspace at request time (a query inherits from its API group, a tool from its toolset envelope, everything else straight from the workspace). Any authored value stops inheriting for that object.",
|
|
@@ -2184,11 +2345,11 @@ function renderSections(m) {
|
|
|
2184
2345
|
'- **Workspace environment variables** set a tenant\'s env vars through the workspace object: `workspaceConfig({ env: { STRIPE_KEY: "", APP_BASE_URL: "" } })`, passed to `registerWorkspace()` \u2014 unattached, it declares nothing. Author them as a name\u2192value MAP, declaring each NAME with an EMPTY value. Read a var back with `env("NAME")` (\u2192 `$env.NAME`), which compiles to tag "setting" with the plain name.',
|
|
2185
2346
|
" - Values are SECRETS and do NOT belong here: they live in `xano/.env`, which is gitignored and survives a `npx @xano/sdk pull`, and every command that compiles a bundle reads it with no flag. Fill it by hand from `xano/.env.example`, or run `npx @xano/sdk env pull`. CI passes `--backend-env-file <path>` or `--env-var KEY=VALUE` instead. A compiled bundle carries the values in cleartext \u2014 don't commit one.",
|
|
2186
2347
|
" - What a deploy sends is the RESOLVED map (the declared names, then ONE file \u2014 `xano/.env`, or `--backend-env-file <path>` which REPLACES it, never both \u2014 then `--env-var`), not the literal object written here. `deploy` REPLACES the tenant's env with it, so a declared name with no value anywhere REFUSES the deploy rather than clearing the live value \u2014 fill the name in rather than putting the value back in source, and reach for `--allow-empty-env=NAME` only when clearing is what you mean.",
|
|
2348
|
+
" - A merge (`deploy --to`) is ADD-ONLY for env, matched BY NAME \u2014 it creates names the target lacks but does NOT update or remove ones it has, so the target's value wins. A release carries no env values, so a NEW name reads null after `promote`/`tenant deploy` until `env set` (both name it first). A `--replace` deploy DROPS every env var the target holds that the config does not declare (named, and confirmed, before it runs). Omit `env` entirely to leave existing env untouched. The separate `settings` field is a plain object.",
|
|
2187
2349
|
"",
|
|
2188
2350
|
"- **Workspace documentation** gates the workspace's hosted docs: `workspaceConfig({ documentation: { require_token: true } })`. `require_token: true` IS the declaration that a token exists; the value lives in `xano/.secrets.json`, keyed by the object it gates rather than by a name, and a literal `token` FAILS the export. It is NOT a backend env var \u2014 `env()` cannot read it. Other members are carried verbatim.",
|
|
2189
|
-
" - \u26A0 OMIT the block and NO `documentation` key is emitted, leaving the target's live block as it is; the
|
|
2351
|
+
" - \u26A0 OMIT the block and NO `documentation` key is emitted, leaving the target's live block as it is; the `realtime` block follows the same rule. An `apiGroup`'s `documentation` follows the OPPOSITE rule \u2014 see its def shape.",
|
|
2190
2352
|
" - A declared gate with no token emits no block at all and REFUSES a `deploy`; `--allow-empty-doc-token=<scope>` clears that gate deliberately (scope = `workspace`, or an API group's NAME). `npx @xano/sdk pull` writes `xano/.secrets.json`, and `--no-secrets` writes none.",
|
|
2191
|
-
" - A merge (`deploy --to`) is ADD-ONLY, matched BY NAME \u2014 it creates names the target lacks but does NOT update or remove ones it has, so the target's value wins. Two gaps: a release carries no env values, so a NEW name reads null after `promote`/`tenant deploy` until `env set` (both name it first) \u2014 and a `--replace` deploy rebuilds it so every env var the target holds that the config does not declare is DROPPED (named, and confirmed, before it runs). Omit `env` entirely to leave existing env untouched. The separate `settings` field is a plain object.",
|
|
2192
2353
|
""
|
|
2193
2354
|
];
|
|
2194
2355
|
const lock = [
|
|
@@ -2198,7 +2359,7 @@ function renderSections(m) {
|
|
|
2198
2359
|
"stay renames (guids otherwise derive from `(type, name)`; a query's from `(api group,",
|
|
2199
2360
|
"verb, name)`). Committed. A composed entry is keyed by that identity \u2014",
|
|
2200
2361
|
"`query:<group>|<verb>|<name>`, `channel:<server>|<path>`, `message:<server>|<path>|<name>`",
|
|
2201
|
-
"\u2014 its guid's seed; a
|
|
2362
|
+
"\u2014 its guid's seed; a bare `query:<name>` key is rewritten to the composed form by the next locked export.",
|
|
2202
2363
|
"",
|
|
2203
2364
|
"- `npx @xano/sdk lock rename <kind> <old> <new>` \u2014 `kind` is the SDK kind (`table`, `apiGroup`) or stored key (`dbo`).",
|
|
2204
2365
|
" Run it when `export` names it after a rename in code (it prints the command); the next export emits the original guid under the new name.",
|
|
@@ -2214,83 +2375,108 @@ function renderSections(m) {
|
|
|
2214
2375
|
"- Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing any def",
|
|
2215
2376
|
" module \u2014 references bake guids at import time; `writeBundle` refuses an unseeded lock.",
|
|
2216
2377
|
"",
|
|
2217
|
-
"
|
|
2218
|
-
"
|
|
2219
|
-
"
|
|
2220
|
-
"
|
|
2221
|
-
"
|
|
2222
|
-
"
|
|
2223
|
-
"
|
|
2224
|
-
"
|
|
2225
|
-
"
|
|
2226
|
-
"
|
|
2227
|
-
"
|
|
2228
|
-
"
|
|
2229
|
-
"
|
|
2230
|
-
"
|
|
2231
|
-
"
|
|
2232
|
-
"
|
|
2378
|
+
"### Writers and readers",
|
|
2379
|
+
"",
|
|
2380
|
+
"- `export`/`deploy`/`release`/`preflight` of an ENTRY FILE update the lock; `compile`/`routes` only READ.",
|
|
2381
|
+
"- `--no-lock` builds without one (names derive guids, the instance invents public URLs, no `--prune`);",
|
|
2382
|
+
" REFUSED over a parseable lock.",
|
|
2383
|
+
"- A DEPLOY or a RELEASE writes back only `landed`: what this project LANDED on each destination",
|
|
2384
|
+
" (ephemerals: `.xano/ephemeral.json`). `--prune` deletes only that, never a merely exported name;",
|
|
2385
|
+
" no record there, no prune until one landing. Commit the lock.",
|
|
2386
|
+
"- A `deploy` (`--replace` too) PRESERVES the archive's guids, so the lock still describes the rebuilt workspace.",
|
|
2387
|
+
"",
|
|
2388
|
+
"### CI",
|
|
2389
|
+
"",
|
|
2390
|
+
"- `--frozen-lock` fails (`SDK_DRIFT`) instead of changing the lock, and fails while the lock carries",
|
|
2391
|
+
" an entry no exported object matches. A plain `export` only warns and writes that entry down, after",
|
|
2392
|
+
" which a rename and a deletion look the same. Resolve it with `lock rename` or `lock prune`, or",
|
|
2393
|
+
" accept them with `--allow-lock-orphans` when they are the not-yet-ported half of an adopted workspace.",
|
|
2394
|
+
"- `export --check` implies `--frozen-lock` and writes nothing \u2014 no bundle, no lock \u2014 so it",
|
|
2395
|
+
" reads no `xano/.env` or `.secrets.json` and refuses the flags that supply them. `npm run xano:check` runs it,",
|
|
2396
|
+
" so CI needs no secrets.",
|
|
2397
|
+
"- With no lock at all, either flag fails only when the source has identities to record (an empty workspace passes).",
|
|
2233
2398
|
""
|
|
2234
2399
|
];
|
|
2235
2400
|
const stmtCalls = [
|
|
2236
2401
|
"Auth & calls:",
|
|
2237
2402
|
"",
|
|
2238
|
-
|
|
2403
|
+
'- `s.security.create_auth_token({ table, id, extras?, expiration?, as? })` \u2014 `extras` defaults to `{}`, `expiration` (seconds, a `Value`: `c.int(3600)`) to 86400 (`c.int(0)` = never). \u26A0 Feeding `expiration` from an OPTIONAL int input mints a NEVER-expiring token when the client omits it: an omitted optional int binds `0`, and `0` means never \u2014 so `expiration: inp("ttl")` with an optional `ttl` silently issues permanent credentials. Declare `input.int({ default: 86400 })`, or leave `expiration` out in an `s.conditional` else branch when the input is null.',
|
|
2239
2404
|
'- **Marketplace first:** `@xano-sdk/auth` registers a complete auth surface \u2014 signup/login/me endpoints plus their `user`/`account`/`event_log` tables \u2014 via `registerAuth(ws, { canonical: "authn" })`. Authentication only, not authorization. Inspect with `npx @xano/sdk marketplace details @xano-sdk/auth --prompt`.',
|
|
2240
2405
|
"- **The auth loop end to end** \u2014 what that module implements; author it directly for a custom flow. An auth TABLE (`table({ auth: true })`) backs identity; a PUBLIC login query verifies and mints a token; every protected query names that table as `auth:` and reads the caller with `auth(...)`.",
|
|
2241
|
-
' - Signup: `s.db.add({ table: users, row: { email: inp("email"), password: inp("password") } })` \u2014 the `f.password()` column hashes on write; take the submission as `input.text()` on signup AND login (
|
|
2242
|
-
' - Login: `s.db.get({ table: users, fieldName: "email", fieldValue: inp("email"), output: ["id", "password"], as: "u" })` \u2014 the `output` naming `password` is REQUIRED (the column is `access: "internal"` and absent from the row otherwise) \u2192 `s.precondition({ expr: expr(ref("u", { safe: true }), "!=", c.null()), error: c.text("
|
|
2243
|
-
' - Client: send it as an `Authorization: Bearer <token>` header. A `query({ auth: users })` refuses a request without a valid one before its stack runs; inside the stack `auth("id")` is the caller\'s row id (`response: { id: auth("id") }` is the whole `me` endpoint).',
|
|
2244
|
-
'-
|
|
2406
|
+
' - Signup: `s.db.add({ table: users, row: { email: inp("email"), password: inp("password") } })` \u2014 the `f.password()` column hashes on write; take the submission as `input.text()` on signup AND login (a password input double-hashes; `llms.txt` Gotchas).',
|
|
2407
|
+
' - Login: `s.db.get({ table: users, fieldName: "email", fieldValue: inp("email"), output: ["id", "password"], as: "u" })` \u2014 the `output` naming `password` is REQUIRED (the column is `access: "internal"` and absent from the row otherwise) \u2192 `s.precondition({ expr: expr(ref("u", { safe: true }), "!=", c.null()), error: c.text("Invalid email or password."), error_type: "unauthorized" })` \u2192 `s.security.check_password({ text_password: inp("password"), hash_password: ref("u.password"), as: "ok" })` \u2192 precondition on `ok`, same error \u2192 `s.security.create_auth_token({ table: users, id: ref("u.id"), as: "token" })` \u2192 `response: { token: ref("token") }`. \u26A0 One error for both: a 404/401 split enumerates accounts.',
|
|
2408
|
+
' - Client: send it as an `Authorization: Bearer <token>` header. A `query({ auth: users })` refuses a request without a valid one before its stack runs; inside the stack `auth("id")` is the caller\'s row id (`response: { id: auth("id") }` is the whole `me` endpoint). \u26A0 The gate is STATELESS: it checks only the token\'s SIGNATURE and EXPIRY, never that the row still exists. A DELETED or disabled user\'s token keeps passing every `auth:` query until it expires (24 h by default), and `create_auth_token` mints for ANY id, so `auth("id")` can name a row that is gone \u2014 reads and ownership writes then serve or create rows for a ghost user. There is NO revocation; a short `expiration` is the only lever. Where it matters, verify the row exists: `s.db.get({ table: users, fieldValue: auth("id"), as: "__actor" })` \u2192 `guard.found("__actor", { errorType: "unauthorized" })` (`guard.role` already does this, answering 401 `Not signed in.`).',
|
|
2409
|
+
' - Claims: a token minted with `extras` is read back as `auth("extras.<key>")` (`auth("extras")` is the whole map). \u26A0 A key ABSENT from the token (an older token, or one minted without it) is a 500 `Unable to locate auth: extras.<key>`, not null \u2014 mint the same keys every time. And claims are a SNAPSHOT frozen at mint: a role change does not reach existing tokens, so authorize off the row (`guard.role`) when the value can change, not off a claim.',
|
|
2410
|
+
'- **Authorization, on top of that.** `guard.role(users, "admin")` and `guard.owner("note", "user_id")` each return a fixed-arity TUPLE of statements \u2014 spread them (`stack: [...guard.role(users, "admin"), \u2026]`).',
|
|
2245
2411
|
' - `guard.role(table, role | roles[], { field?, as?, errorType?, message?, missingErrorType?, missingMessage? })` \u2014 fetches the caller\'s own row by `auth("id")` into `__actor`, asserts it EXISTS (401), then asserts its `role` is in the set (403). Roles type from the enum column; an unknown role or `field` throws. The existence step matters: a role check on a null actor row is not reliably false.',
|
|
2246
|
-
' - `guard.owner(rowVar, ownerField = "user_id", { \u2026 })` \u2014 asserts the row bound to `rowVar` is non-null (404), THEN compares its owner column to `auth("id")` (also 404). Drilling before the existence check is a 500, not a denial: `db.get` binds `null` on a miss and `ref("note.user_id")` against it raises `Unable to locate var`. Takes the var NAME and the column separately
|
|
2412
|
+
' - `guard.owner(rowVar, ownerField = "user_id", { \u2026 })` \u2014 asserts the row bound to `rowVar` is non-null (404), THEN compares its owner column to `auth("id")` (also 404). Drilling before the existence check is a 500, not a denial: `db.get` binds `null` on a miss and `ref("note.user_id")` against it raises `Unable to locate var`. Takes the var NAME and the column separately; a dotted path is refused.',
|
|
2247
2413
|
' - `guard.found(rowVar, { errorType?, message? })` \u2014 ONE statement: asserts the row bound to `rowVar` is non-null (404, `"Not found."`), and NARROWS it \u2014 after it, `InferResponse` drops the `| null` from `rowVar`. `guard.owner`\'s existence step is this statement.',
|
|
2248
2414
|
" - `guard.require(condition, { errorType?, message? })` for anything else \u2014 same shape, and it defaults to 403 where a bare `s.precondition` defaults to `standard`, i.e. **500**.",
|
|
2249
2415
|
"- `s.security.create_uuid({ as? })` \u2014 bind a fresh UUID (v4). Takes nothing else. There is NO `create_guid` (internal, unpushable).",
|
|
2250
2416
|
'- **Receiving a webhook** \u2014 no `auth`, no declared `input` (the signature covers the raw bytes): `s.util.get_raw_input({ encoding: "none", as: "raw" })` \u2192 `s.set_var("mac", withFilters(ref("raw"), fl.hmac_sha256(env("WH_SECRET"))))` \u2192 `s.set_var("sig", withFilters(sys.httpHeaders(), fl.get("X-Signature")))` (Title-Cased) \u2192 an `s.precondition` (`error_type: "unauthorized"`) comparing the two TIMING-SAFELY by HMACing both again \u2014 `expr(withFilters(ref("sig"), fl.hmac_sha256(env("WH_SECRET"))), "=", withFilters(ref("mac"), fl.hmac_sha256(env("WH_SECRET"))))` \u2014 BEFORE `fl.json_decode()` reads `raw`. Claim the event id with `s.redis.set({ \u2026, create_only: c.bool(true) })` and answer 200 to a replay.',
|
|
2251
|
-
|
|
2252
|
-
'
|
|
2417
|
+
'- **Verifying a token (JWS/JWE)** \u2014 \u26A0 `s.security.jws_decode`/`jwe_decode`/`decrypt`/`check_password` THROW a 500 `ERROR_FATAL` on EVERY failure (a tampered/garbage/empty/wrong-key token, a wrong `signature_algorithm`, an expired token `The token expired.`, a failed `check_claims` `Invalid value for claim: <k>`, a bad `decrypt` key/iv, a non-hash to `check_password`), NOT a falsy result \u2014 so a bare decode answers 500 for every bad token where 401 is wanted. Wrap it: `s.try_catch({ try: [s.security.jws_decode({ token: inp("token"), key: env("JWT_SECRET"), signature_algorithm: "HS256", check_claims: obj({ role: c.text("admin") }), as: "claims" })], catch: [s.precondition({ expr: expr(c.bool(true), "=", c.bool(false)), error_type: "unauthorized", error: c.text("Invalid token.") })] })` \u2014 a good token binds `claims` and runs on; any failure lands in `catch`, which raises a clean 401. `check_claims` is an object of EXACT-match claims; `exp`/`nbf` are checked automatically.',
|
|
2418
|
+
'- **`s.security.*` defaults are WEAK \u2014 pass them explicitly** (the catalog prints none; these are the engine\'s). `encrypt`/`decrypt` default `algorithm` to `aes-128-cbc`, so a 32-byte key is CUT to 16 (AES-128, not -256) \u2014 pass `algorithm: "aes-256-cbc"`. AES keys are NOT length-checked (a short key is zero-padded and still encrypts at 200), and a non-string `data` 500s \u2014 `fl.json_encode` an object first. `jws_encode`/`jwe_encode` default `ttl: 0`, which mints a token with NO `exp` claim (it NEVER expires) \u2014 set a `ttl` in seconds. `create_rsa_key` defaults `bits: 1024`, below the 2048 minimum \u2014 pass `bits: 2048`+. `random_bytes` defaults `length: 1`; `random_number` bounds are INCLUSIVE and `min > max` 500s; `create_password` with a `character_count` below the required classes 500s.',
|
|
2419
|
+
"- `s.function.run({ fn, input?, as?, runtime? })` / `s.function.call({ fn, input?, as? })` \u2014 run another function.",
|
|
2420
|
+
" - **Inputs:** `input` is keyed by the target's input names (an undeclared one is a type and export error, a mistyped `c.*` constant a type error; generic over `fn`, pass `Record<string, Value>`; `2` binds an int \u2014 `c.decimal(2)` for a decimal).",
|
|
2421
|
+
' - \u26A0 **The two DIFFER ON FAILURE.** `s.function.run` RAISES \u2014 a `precondition`/500 in the target propagates, so the caller fails with that status, and an uncaught `s.throw` in it answers with its `status` (200 without one). `s.function.call` does NOT raise OUTSIDE a workflow test: it BINDS the error envelope `{ code, message, payload }` to `as` (still typed as the SUCCESS shape, so the mismatch is silent) and the stack answers 200 carrying it. Use `s.function.run` whenever a failing target must stop the caller; reach for `s.function.call` only to INSPECT a possible failure (branch on `ref("r.code")` before trusting the result). INSIDE a workflow test `s.function.call` DOES raise, like `s.api.call`/`s.task.call`.',
|
|
2422
|
+
" - \u26A0 **Omitted inputs:** `s.function.run` binds an input it OMITS from the CALLING def's same-named declared input \u2014 an endpoint declaring `discount` hands `?discount=100` through, or `0` when the client sends none. An endpoint/tool/prompt declaring NO inputs binds it from the raw request. `ignored()` always takes the target's default. Pass inputs explicitly (`statement.omitted-input` warns).",
|
|
2423
|
+
" - \u26A0 Forwarding a caller's OPTIONAL input (`input: { b: inp(\"b\") }`) passes its EMPTY value (`0`/`\"\"`) when the client omits it, NOT 'absent', so the TARGET's `default` never applies and you get wrong data at 200; declare the caller's input `nullable: true` (an omitted one then binds `null`, which DOES take the target's default) or repeat the default on the caller.",
|
|
2424
|
+
" - \u26A0 **Depth:** calls nest at most ~25 deep per request (the engine's variable-stack limit); deeper, including legitimate bounded recursion (a tree walk, factorial, self-paginating call), fails with HTTP 500 `Infinite recursion detected` \u2014 recurse iteratively (`s.while` over an explicit list) or batch.",
|
|
2425
|
+
' - `runtime?` runs it in the BACKGROUND: `{ mode: "async-shared" }` or `{ mode: "async-dedicated", cpu?, memory?, timeout?, maxRetry? }` (resources read at dedicated only). Omit `runtime` for a normal call; same on `s.ai.agent.run`.',
|
|
2426
|
+
" - An async run keeps its caller: `auth()` inside it is the dispatching request's, and from a public endpoint it has none.",
|
|
2427
|
+
' - An async call DOES NOT return the result \u2014 it dispatches and continues, and `as` binds the job id (a UUID `string`). Collect with `s.await({ ids, timeout, as })`, binding `{ "<jobId>": result }` (read each with `fl.get(ref("<idVar>"))`); a too-short `timeout` or unknown id is a 500 `Async timeout`, no partial result.',
|
|
2428
|
+
' - \u26A0 `s.await` NEVER RAISES for a FAILED job (only the timeout/unknown-id case 500s) \u2014 a crashed job\'s slot holds the error envelope in place of the result, served at HTTP 200, and `try_catch` cannot see it. Read each slot (`fl.get(ref("<idVar>"))`) and treat a present `code`/`statement`/`state` as a failure before trusting the result:',
|
|
2429
|
+
" - `{ code, message, payload }` for a precondition/engine error",
|
|
2430
|
+
" - `{ payload, statement }` for `s.throw` (no `code`)",
|
|
2431
|
+
' - `{ state: "terminated" }` for one stopped by `terminate`',
|
|
2432
|
+
' - \u26A0 `ids` is a single `Value`, so a bare `[ref("j1"), ref("j2")]` fails `tsc` \u2014 pass one id as `ref("j1")`, or a list by building it first: `s.set_var("ids", obj({ list: [ref("j1"), ref("j2")] }))` then `s.await({ ids: ref("ids.list"), timeout: c.int(10), as })`.',
|
|
2433
|
+
' - Defaults: `ids` omitted \u2192 `{}` at once, `timeout` 10s; awaiting the same id twice returns the same result. `terminate: c.true()` asks every still-outstanding job to STOP at its next statement boundary when the await times out (its slot then reads `{ state: "terminated" }`); the await still throws `Async timeout`.',
|
|
2253
2434
|
"- `s.api.call({ api, input?, headers?, auth?, as? })` \u2014 invoke an endpoint. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`).",
|
|
2254
|
-
" - `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) \u2014 a bare name is refused
|
|
2435
|
+
" - `api` takes the `query()` def HANDLE (or a `{ name, guid }` pair) \u2014 a bare name is refused (identity = api group + verb + name).",
|
|
2255
2436
|
" - `headers` REPLACES the request headers the callee sees and takes the same shapes as `s.api.request`'s, or one `Value`.",
|
|
2256
|
-
" - `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING \u2014 a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value
|
|
2257
|
-
" - Neither slot authenticates the call
|
|
2437
|
+
" - `auth` is `{ token, ignoreExpiration? }`: `token` must be a BARE STRING \u2014 a tagged `Value` deploys clean and then fails the run with `Param: token - Text filter requires an integer, float, string or boolean value`.",
|
|
2438
|
+
" - Neither slot authenticates the call; see `llms/tests.md` for what a workflow-test run actually sees.",
|
|
2258
2439
|
"- `s.api.request({ url, method?, params?, headers?, timeout?, follow_location?, verify_host?, verify_peer?, ca_certificate?, certificate?, certificate_pass?, private_key?, private_key_pass?, description?, output?, as? })` \u2014 external HTTP request (`mvp:api_request`). Ergonomic types, each also accepting a dynamic `Value`:",
|
|
2259
|
-
" - `method` suggests the
|
|
2440
|
+
" - `method` suggests the 8 verbs (GET/POST/PUT/DELETE/HEAD/OPTIONS/PATCH/QUERY). QUERY (RFC 10008) is the safe method that sends `params` as its body.",
|
|
2260
2441
|
' - `params` a plain JSON object **or** a FLAT record whose values are tagged `Value`s (`{ count: ref("count") }`, each lifted via a `set` filter \u2014 the same record-of-values shape `response: { key: value }` takes); a tagged value NESTED inside an object or array THROWS at encode, so wrap a structured body in `obj({...})`, which encodes any depth as one `const:expr2` (\u2192 query string for GET/HEAD/OPTIONS, body otherwise).',
|
|
2261
2442
|
' - `headers` a `{ "Name": value }` record whose values may be tagged (`{ "x-api-key": env("KEY") }`, each pair joined to a `"Name: value"` line) **or** a `string[]` of full header lines \u2014 prefer a header over a `?key=` query param for a credential \u2014 a URL reaches access logs and proxies.',
|
|
2262
2443
|
" - \u26A0 Neither spelling is envelope-safe: the `as` envelope's `request` half mirrors `url`, `params` AND `headers`, so never return it raw from a credentialed request \u2014 read `response.result`.",
|
|
2263
2444
|
" - A NAME outside the header-token charset is refused, and a LITERAL value (string or `c.text`) carrying CR/LF/NUL is refused; a value may hold `:` and spaces (`Bearer a: b` is a valid value). A TAGGED value cannot be checked at build time, so strip CRLF from caller-controlled input before this slot. Literal pairs are emitted before computed ones, whatever the key order.",
|
|
2264
2445
|
' - No `User-Agent` is sent unless `headers` carries one. An API requiring one answers **403** as ordinary `response.result` (no throw; every mapped field reads `null`). Send one (`headers: { "User-Agent": c.text("my-app") }`) and gate on `ref("<var>.response.status")` = 200 with `s.precondition`.',
|
|
2265
|
-
" - A transport failure (timeout, DNS) does not throw \u2014 `s.try_catch` never catches it: `response.status` is `0`, with `response.error` set. Retry on `status == 0 || status >= 500`; `status < 500`
|
|
2446
|
+
" - A transport failure (timeout, DNS) does not throw \u2014 `s.try_catch` never catches it: `response.status` is `0`, with `response.error` set. Retry on `status == 0 || status >= 500`; a bare `status < 500` check treats a transport failure (status 0) as success.",
|
|
2266
2447
|
" - `timeout` a `number` in seconds (1\u201386400), and `follow_location`/`verify_host`/`verify_peer` booleans.",
|
|
2267
2448
|
" - `description` and `output` filters ride the envelope. Cert pairings (certificate\u2194private_key, ca_certificate\u2192verify_peer) are checked at build time when provable.",
|
|
2268
2449
|
" - The `as` result is typed as the `{request, response}` envelope (`response.status: number`, `response.result: unknown`), so `InferResponse` resolves a `ref` to it. Same typed result on `webflow.request` and `microservice.request`.",
|
|
2269
2450
|
"- `s.stream.from_request({ url, method?, \u2026tls, as? })` \u2014 streaming external HTTP request (`mvp:streaming_api_request`); same typed field surface as `s.api.request` (no description/output envelope). `url` is REQUIRED.",
|
|
2270
|
-
'- `s.util.send_email({ to
|
|
2451
|
+
'- `s.util.send_email({ to?, subject, message, from?, cc?, bcc?, reply_to?, service_provider?, api_key?, scheduled_at?, as? })` \u2014 send email from the stack. `subject` and `message` are required at runtime, and so are `to` and `from` with `"resend"`. Use it over a hand-rolled `s.api.request` to a mail provider.',
|
|
2452
|
+
' - `service_provider: "xano"` \u2014 the built-in mailer: needs NO `api_key` and no configuration, and does not require a verified sender. \u26A0 It delivers ONLY to the workspace owner: `to`/`cc`/`bcc`/`reply_to`/`scheduled_at` are ignored and `from` is fixed \u2014 alerts to yourself, never mail to a user.',
|
|
2453
|
+
' - `service_provider: "resend"` \u2014 mail to any recipient; pass the key as `api_key: env("RESEND_API_KEY")`.',
|
|
2454
|
+
' - \u26A0 A failed send does NOT raise: `as` binds `{ status: "error", error }` (success binds `status: "success"`). Branch on `ref("<as>.status")`.',
|
|
2271
2455
|
"- `s.webflow.request({ path, method?, \u2026tls, as? })` \u2014 Webflow API request (`mvp:connect_webflow_api_request`); like `s.api.request` but addressed by `path` (host is engine-supplied), and `path` is REQUIRED \u2014 the engine rejects an empty one. No `headers`: the engine builds its own from the workspace's Webflow connection and ignores an authored value.",
|
|
2272
|
-
"- `s.task.call`
|
|
2273
|
-
"- `s.
|
|
2456
|
+
"- `s.task.call({ task, as? })` \u2014 runs the task's stack once, now; takes NO `input` (a task declares none). `as` binds the task's `s.return` value (null without one), which is how a `workflowTest` asserts a task has a result. WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`).",
|
|
2457
|
+
"- `s.tool.call` / `s.trigger.call` / `s.middleware.call` / `s.addon.call` \u2014 same `{ <target>, input?, as? }` shape against the named kind. `s.trigger.call` is WORKFLOW-TEST ONLY (see Gotchas in `llms.txt`); the other three run from any stack, but `s.tool.call` passes NO caller: `auth()` in the tool fails ACCESS_DENIED. \u26A0 Like `s.function.call`, a FAILING tool never raises: its error envelope binds to `as` at 200; `s.function.run` a shared function to stop the caller.",
|
|
2458
|
+
' - `s.trigger.call`\'s `input` is UNTYPED and must carry the inputs the target trigger reads, which the `t` accessor names: a `tableTrigger` needs `action` (`"insert"`/`"edit"`/`"delete"`), `datasource` (REQUIRED \u2014 without it the run fails `Missing param: datasource`), and `new`/`old` row objects; a misspelled key type-checks and is just ignored.',
|
|
2459
|
+
"- `s.action.call({ actionId, input?, registry?, as? })` / `s.action.package.call({ traceId, versionId, slug, input?, registry?, as? })` \u2014 invoke an installed action. Ids are SUPPLIED, never derived from a name: an action is installed onto the instance, so its identity is assigned at install and differs per instance \u2014 read them off a call in a pulled workspace. The package form needs all three parts: pass them together; any subset addresses nothing. `registry` is the action's own settings, `input` the per-call arguments.",
|
|
2274
2460
|
"- `s.cloud.job({ image, command, args?, secret?, template?, await?, as? })` \u2014 launch a containerized job. `image`/`command` are REQUIRED; omitted \u2192 `Missing param`. \u26A0 `await` is SECONDS (default 60), not a boolean.",
|
|
2275
2461
|
"- `s.cloud.job.status({ id, as? })` \xB7 `s.cloud.job.await({ ids, timeout, as? })` \u2014 poll one job, or block on several (`ids` a list `Value`, `timeout` in seconds; both required).",
|
|
2276
2462
|
"",
|
|
2277
2463
|
"Microservices (the `microservice()` def and the statement that calls it):",
|
|
2278
2464
|
"",
|
|
2279
2465
|
"- `microservice({ name, kind, \u2026 })` \u2014 two mutually exclusive shapes via `kind`: `builtin` declares containers (image/ports/resources/env/command/args) plus optional `ingresses`, and `helm` points at a chart and its `values` \u2014 passing both throws.",
|
|
2280
|
-
" -
|
|
2466
|
+
" - Unstable API \u2014 every export of a workspace declaring one prints a notice saying so.",
|
|
2281
2467
|
" - `configs`/`volumes` are typed and `@deprecated` but NOT deployable: the engine rejects an import carrying either, so `export()` fails the build rather than letting the deploy fatal.",
|
|
2282
2468
|
" - Put a value the workload reads in a container's `env`, and storage in a container's own `volumes` (`emptyDir`/`persistent`/`config`).",
|
|
2283
2469
|
" - Container names are free-form \u2014 they need not match the microservice name, which is what a stack addresses.",
|
|
2284
|
-
"-
|
|
2470
|
+
"- \u26A0 Secrets are copied verbatim: `chart.values` and `registryAuth.dockerconfigjson` are carried into the bundle, and into a pulled tree. `process.env.X` in the def is NOT a way out: it resolves at EXPORT and writes the literal in.",
|
|
2285
2471
|
' - Reference a `workspaceConfig({ env })` var instead and only the NAME travels \u2014 the engine substitutes at DEPLOY. Two spellings: `env: [{ name: "API_KEY", fromEnv: "STRIPE_SECRET" }]` on a builtin container (`value`/`fromEnv` exclusive; both \u2192 build error), or `${env.NAME}` inside a helm `chart.values` (a VALUE at any depth, never a key). A name the workspace does not define FAILS the deploy rather than resolving blank.',
|
|
2286
|
-
" - `registryAuth.dockerconfigjson` has NO such form: either leave it unset and pull a public image, or treat the bundle and any tree pulled from it as secret material \u2014 out of git, or rotate after. Export prints a notice per microservice carrying a literal; `--strict` does not
|
|
2472
|
+
" - `registryAuth.dockerconfigjson` has NO such form: either leave it unset and pull a public image, or treat the bundle and any tree pulled from it as secret material \u2014 out of git, or rotate after. Export prints a notice per microservice carrying a literal; `--strict` does not fail on it.",
|
|
2287
2473
|
"- `s.microservice.request({ host, path, port?, method?, params?, headers?, timeout?, follow_location?, as? })` \u2014 in-cluster microservice call (`mvp:microservice_request`); no TLS fields.",
|
|
2288
2474
|
" - ONLY `host`+`path` required; the rest default to the engine's values (`GET`/`{}`/`[]`/`10`/`true`), always emitted.",
|
|
2289
2475
|
" - Pass the `microservice()` DEF as `host` \u2014 it binds by NAME (how the engine resolves it), so a rename fixes every call site and the port is checked before deploy.",
|
|
2290
2476
|
' - `port?` folds into `host` as `"name:port"`: a def exposing ONE `servicePort` resolves automatically, SEVERAL requires it.',
|
|
2291
2477
|
' - A raw `"name:port"` string works, unvalidated, and is the only way to reach an instance-level microservice.',
|
|
2292
2478
|
' - `tenantDeploy: "manual"` on the def imports the row without starting the workload.',
|
|
2293
|
-
"- `s.workflow_test.call({ workflowTest, datasource?, as? })` \u2014 run another workflow test from inside one, which is the only place it runs (see Gotchas in `llms.txt`).
|
|
2479
|
+
"- `s.workflow_test.call({ workflowTest, datasource?, as? })` \u2014 run another workflow test from inside one, which is the only place it runs (see Gotchas in `llms.txt`). NO `input`; `datasource?` has the kind's clone caveat.",
|
|
2294
2480
|
""
|
|
2295
2481
|
];
|
|
2296
2482
|
const groups = /* @__PURE__ */ new Map();
|
|
@@ -2299,7 +2485,10 @@ function renderSections(m) {
|
|
|
2299
2485
|
const ns = s.sPath.includes(".") ? s.sPath.slice(0, s.sPath.indexOf(".")) : "(top-level)";
|
|
2300
2486
|
(groups.get(ns) ?? groups.set(ns, []).get(ns)).push(s);
|
|
2301
2487
|
}
|
|
2302
|
-
const stmtCatalog = [
|
|
2488
|
+
const stmtCatalog = [
|
|
2489
|
+
"`[special]`: hand-written signature (`llms.txt` Specials, `llms/statements-*`). `[output]`: the engine's output flag; in-place mutators carrying it (`s.math.add`, `bitwise.*`) still take no `as`.",
|
|
2490
|
+
""
|
|
2491
|
+
];
|
|
2303
2492
|
for (const ns of [...groups.keys()].sort()) {
|
|
2304
2493
|
stmtCatalog.push(`### ${ns}`, "");
|
|
2305
2494
|
const note = NAMESPACE_NOTES[ns];
|
|
@@ -2328,13 +2517,12 @@ function renderSections(m) {
|
|
|
2328
2517
|
// block reads as a section wherever it is rendered from.
|
|
2329
2518
|
"## Legacy",
|
|
2330
2519
|
"",
|
|
2331
|
-
"
|
|
2332
|
-
"
|
|
2520
|
+
"Shapes codegen emits when it decodes an existing workspace, all supported.",
|
|
2521
|
+
"**Do not author these.** They are listed by name only so you recognize them",
|
|
2333
2522
|
'in pulled code rather than "fixing" them; each line names what to use instead.',
|
|
2334
2523
|
"",
|
|
2335
|
-
"
|
|
2336
|
-
|
|
2337
|
-
"two things are the same object; check which list it came from.",
|
|
2524
|
+
'"realtime" and "channel" name objects in both lists: a matching name does NOT mean',
|
|
2525
|
+
"the same object; check which list it came from.",
|
|
2338
2526
|
""
|
|
2339
2527
|
);
|
|
2340
2528
|
for (const v of legacyValues) legacy.push(`- \`${v.name}\` \u2014 ${v.description}`);
|
|
@@ -2612,6 +2800,7 @@ export {
|
|
|
2612
2800
|
buildWorkspaceHistory,
|
|
2613
2801
|
bundleCapabilities,
|
|
2614
2802
|
calcSignatureJson,
|
|
2803
|
+
capabilityReport,
|
|
2615
2804
|
channelPathParams,
|
|
2616
2805
|
createLockContext,
|
|
2617
2806
|
declaredServicePorts,
|