@xano/sdk 1.0.13 → 1.0.14
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 +15 -0
- package/README.md +28 -28
- package/dist/.build-fingerprint +1 -1
- package/dist/{agent-file-refresh-DAFGNMQX.js → agent-file-refresh-3J6YRVFL.js} +12 -11
- package/dist/{agent-skill-command-6M46ZGOL.js → agent-skill-command-VWDMQWCT.js} +51 -50
- package/dist/{answer-shape-CBUQRSXI.js → answer-shape-AVZSKBR6.js} +4 -4
- package/dist/{backend-dir-J2J7JNS6.js → backend-dir-ISP7RVF2.js} +11 -10
- package/dist/{backend-slot-X5AUX2TT.js → backend-slot-DZAUHLTS.js} +3 -3
- package/dist/bin.js +47 -46
- package/dist/{branch-YS2K3VOB.js → branch-IJTBZZFO.js} +8 -8
- package/dist/{branch-commands-BUKVE637.js → branch-commands-75IYFTBS.js} +26 -25
- package/dist/{chunk-UECNKDDA.js → chunk-2FDHIBEU.js} +8 -8
- package/dist/{chunk-P6HXDOFG.js → chunk-2KOB4QPW.js} +13 -13
- package/dist/{chunk-PCHIHVX6.js → chunk-2LF734YB.js} +4 -4
- package/dist/{chunk-R7XZW4SB.js → chunk-3H7R4ISR.js} +2 -2
- package/dist/{chunk-NMHTB346.js → chunk-3SZ7QRYA.js} +36 -10
- package/dist/{chunk-DB7P2SSK.js → chunk-45K2QZBR.js} +3 -3
- package/dist/{chunk-C2SAVXAB.js → chunk-4MX5LMPQ.js} +2 -2
- package/dist/{chunk-IZI3SYXH.js → chunk-5FJ4M4HB.js} +38 -38
- package/dist/{chunk-ZSMHS7BU.js → chunk-5TWLVFYB.js} +4 -4
- package/dist/{chunk-JKGRQW6D.js → chunk-5W7S2SCA.js} +4 -4
- package/dist/{chunk-F2NFNYCB.js → chunk-6ILHYSLR.js} +3 -3
- package/dist/{chunk-IFXPHVPY.js → chunk-6LJS4M6P.js} +3 -3
- package/dist/{chunk-CTUIMNEM.js → chunk-6X73VFCX.js} +2 -2
- package/dist/{chunk-DZUNF7IH.js → chunk-75QC66XI.js} +2 -2
- package/dist/{chunk-FBWMKHLO.js → chunk-7F3V6CFP.js} +3 -3
- package/dist/{chunk-5ONWBQ2C.js → chunk-B7CPSWQX.js} +7 -7
- package/dist/{chunk-4CS4DKQC.js → chunk-BEKEOXNG.js} +2 -2
- package/dist/{chunk-U4BGBU3R.js → chunk-BSGU4HS6.js} +44 -44
- package/dist/{chunk-ZGNWMGN3.js → chunk-CB67GIR3.js} +26 -8
- package/dist/{chunk-M7DIIJPW.js → chunk-DBDTQR23.js} +4 -4
- package/dist/{chunk-ENBGJJJH.js → chunk-DERQSEB5.js} +9 -9
- package/dist/{chunk-RZABQ4YH.js → chunk-DGYXCIBV.js} +4 -4
- package/dist/{chunk-BXVNRUDB.js → chunk-DLDYQNGP.js} +3 -3
- package/dist/{chunk-I2AVVARA.js → chunk-ECQXASG3.js} +2 -2
- package/dist/{chunk-2BHYGUTI.js → chunk-EQXHUWUO.js} +2 -2
- package/dist/{chunk-ONNSFD73.js → chunk-EYVIUX2T.js} +9 -9
- package/dist/{chunk-JFPLHK6Y.js → chunk-FBSGFPZ4.js} +2 -2
- package/dist/{chunk-EGEANMMK.js → chunk-FIERONKM.js} +2 -2
- package/dist/{chunk-K6BQPFRS.js → chunk-GBSHHNSD.js} +3 -3
- package/dist/{chunk-N3XSXGAL.js → chunk-GCINMMFL.js} +2 -2
- package/dist/{chunk-POZ6V4MU.js → chunk-GKQTXUOW.js} +2 -2
- package/dist/{chunk-SBS2IYTN.js → chunk-GOKRKTCX.js} +3 -3
- package/dist/{chunk-D4VKPOD4.js → chunk-GRXX2TOJ.js} +13 -112
- package/dist/{chunk-YJK4NPXC.js → chunk-GVHWIDEJ.js} +3 -3
- package/dist/{chunk-NZ7ML6LG.js → chunk-HINRE3UM.js} +5 -5
- package/dist/{chunk-H6VVSGKN.js → chunk-HK554MDD.js} +7 -7
- package/dist/{chunk-6HTXQAMG.js → chunk-HKI5Y5KW.js} +14 -14
- package/dist/{chunk-MLKJUEG3.js → chunk-HMYJOQXT.js} +23 -23
- package/dist/{chunk-DILYWJVP.js → chunk-HXFLHA5K.js} +2 -2
- package/dist/{chunk-A2AOUBJS.js → chunk-IHL2O7VY.js} +2 -2
- package/dist/{chunk-FLDFKG24.js → chunk-IKXXTRMN.js} +4 -4
- package/dist/{chunk-5XDKKE5Y.js → chunk-IWJ6GFST.js} +4 -4
- package/dist/{chunk-TANWE2ZY.js → chunk-J3XLCYTQ.js} +80 -80
- package/dist/{chunk-ENAUSLMP.js → chunk-J62TYONQ.js} +3 -3
- package/dist/{chunk-GRWYO2MS.js → chunk-KDEU5FUJ.js} +3 -3
- package/dist/{chunk-VA4JK4TW.js → chunk-KMKUH2IO.js} +3 -3
- package/dist/{chunk-VTMTIBKP.js → chunk-L34DM6QB.js} +2 -2
- package/dist/{chunk-6OOZJQJK.js → chunk-L4WG4BKJ.js} +68 -68
- package/dist/{chunk-QWWQM4XZ.js → chunk-LB76VK6D.js} +7 -7
- package/dist/{chunk-E763QI3G.js → chunk-LJZIBT75.js} +2 -2
- package/dist/{chunk-5SMUND4J.js → chunk-LPQZICYN.js} +6 -6
- package/dist/{chunk-UFFIU57H.js → chunk-LSJ3SQEU.js} +4 -4
- package/dist/{chunk-O6PWEJUV.js → chunk-LW7TOIS7.js} +8 -8
- package/dist/{chunk-XL7EA62X.js → chunk-MAXDJZQR.js} +5 -5
- package/dist/{chunk-7NNLRNXE.js → chunk-MIS6F4HM.js} +4 -4
- package/dist/{chunk-WZXEQUIM.js → chunk-MTBKTGZT.js} +2 -2
- package/dist/{chunk-WQZCFVAD.js → chunk-MYIIBV6A.js} +5 -5
- package/dist/{chunk-3RZ4UJWV.js → chunk-N6LGLNAC.js} +4 -4
- package/dist/{chunk-H7GMGZHI.js → chunk-NDV6CBR7.js} +2 -2
- package/dist/{chunk-HEMWBHQS.js → chunk-NOW522B4.js} +13 -13
- package/dist/{chunk-DFCYAEBE.js → chunk-NUZXSIEA.js} +3 -3
- package/dist/{chunk-DYGRTWAI.js → chunk-O44MJTLR.js} +3 -3
- package/dist/{chunk-EKS7SAZS.js → chunk-OLQN4Z5R.js} +53 -61
- package/dist/{chunk-CGZSF756.js → chunk-P4OWRYE7.js} +28 -28
- package/dist/{chunk-373AVIL2.js → chunk-QAEBBTYR.js} +7 -7
- package/dist/{chunk-UKC65HBQ.js → chunk-QJ25N4W6.js} +4 -4
- package/dist/{chunk-RAGFXELQ.js → chunk-QKHNJ7LE.js} +5 -5
- package/dist/{chunk-3ZVSOZZC.js → chunk-QRMKQYCB.js} +2 -2
- package/dist/{chunk-RQHXYL77.js → chunk-QX5XQEYB.js} +5 -7
- package/dist/{chunk-UDCKYLBW.js → chunk-RDZBXTZ3.js} +4 -4
- package/dist/{chunk-U4DSFCH5.js → chunk-RPBB7P4Q.js} +2 -2
- package/dist/{chunk-W5MKVFBQ.js → chunk-RV2BDU7V.js} +5 -5
- package/dist/{chunk-XFQAA2SU.js → chunk-RVAEPPRH.js} +2 -2
- package/dist/{chunk-6QJORUHC.js → chunk-RYWNNJK5.js} +2 -2
- package/dist/{chunk-VFRL4G72.js → chunk-SAEIVQLP.js} +3 -3
- package/dist/{chunk-H5FAYLCR.js → chunk-SPLRKCFV.js} +2 -2
- package/dist/{chunk-ZISPEBNM.js → chunk-SUKO4SZG.js} +60 -55
- package/dist/{chunk-B5N6EWOM.js → chunk-UQ2OD7D4.js} +3 -3
- package/dist/{chunk-DPSR5GRE.js → chunk-VBSCWV5H.js} +49 -49
- package/dist/chunk-VYJYDMY6.js +9 -0
- package/dist/{chunk-C4TZP5PQ.js → chunk-WS2X5BB2.js} +5 -5
- package/dist/{chunk-P5JF3U65.js → chunk-WS4BA75E.js} +37 -4
- package/dist/{chunk-XYVPF63S.js → chunk-XCFQLP6G.js} +8 -8
- package/dist/{chunk-OCNTMJSY.js → chunk-XPSDDTUZ.js} +3 -3
- package/dist/{chunk-OBRMA2VK.js → chunk-XY4OBD26.js} +3 -3
- package/dist/{chunk-XVOODRNK.js → chunk-Y5XAPLZS.js} +4 -4
- package/dist/{chunk-ZACMAKZE.js → chunk-YFQCDLCQ.js} +14 -14
- package/dist/{chunk-HDANNK4A.js → chunk-YL3WVBR5.js} +9 -9
- package/dist/{chunk-XM56DAM7.js → chunk-YR3MNGWZ.js} +8 -8
- package/dist/{chunk-HUEFVPYW.js → chunk-YTQYP7UJ.js} +3 -3
- package/dist/{chunk-KICERNAP.js → chunk-Z3DQ7ULY.js} +4 -4
- package/dist/{chunk-JHQAVWHW.js → chunk-Z4BQPABS.js} +2 -2
- package/dist/{chunk-6LECAG3Y.js → chunk-ZMJRAMLA.js} +4 -4
- package/dist/{chunk-AUYXBKGR.js → chunk-ZOHEHIFS.js} +2 -2
- package/dist/{chunk-A3CT26GX.js → chunk-ZRXDPCMN.js} +2 -2
- package/dist/cli.js +45 -44
- package/dist/{codegen-command-BAFON45M.js → codegen-command-JWOW6HE5.js} +63 -62
- package/dist/codegen.js +2 -2
- package/dist/{commands-IFRAGWGK.js → commands-5ILSWDSV.js} +2 -2
- package/dist/{completion-RTXCODHS.js → completion-UNKBVVDT.js} +2 -2
- package/dist/{config-EHFXNFSP.js → config-NTOASFCA.js} +3 -3
- package/dist/{deploy-command-JW7R3BPW.js → deploy-command-WESYWFJN.js} +52 -51
- package/dist/{deploy-source-ZUPLAL7L.js → deploy-source-ZQQNMDFX.js} +27 -26
- package/dist/{dev-env-sync-W7OTV7OD.js → dev-env-sync-4XJT7WOT.js} +46 -45
- package/dist/{display-name-hint-BKPMISQU.js → display-name-hint-MYXCCAOP.js} +10 -10
- package/dist/{env-example-refresh-TS7WBVZQ.js → env-example-refresh-4V2OCDJE.js} +64 -63
- package/dist/{env-pull-command-5IYXQ2WK.js → env-pull-command-SK5FS477.js} +42 -41
- package/dist/{env-target-TQBPLU2S.js → env-target-TEFSYACA.js} +9 -9
- package/dist/{env-var-command-AKCWYZPB.js → env-var-command-IJHKA2WJ.js} +37 -36
- package/dist/{ephemeral-CART6DIR.js → ephemeral-VLPRDNEJ.js} +8 -8
- package/dist/{ephemeral-command-SJYH6XRS.js → ephemeral-command-WCO5J4SN.js} +43 -42
- package/dist/{ephemeral-state-HPKSKC4Y.js → ephemeral-state-RUOU2GFS.js} +7 -7
- package/dist/{generate-command-FSCFZPOJ.js → generate-command-3WCOUOEQ.js} +68 -67
- package/dist/{gitignore-6IJ66XME.js → gitignore-WYS3GMOX.js} +15 -14
- package/dist/{guards-RU4C7TFG.js → guards-PPIBIMFZ.js} +6 -6
- package/dist/{impersonate-command-IH4HMSS3.js → impersonate-command-UMYVQTCG.js} +33 -32
- package/dist/{import-RUBCGLCA.js → import-T4ZTOTBT.js} +4 -4
- package/dist/index.js +11 -11
- package/dist/{init-command-STB4YSAK.js → init-command-UR5MSXIH.js} +50 -51
- package/dist/{init-modules-YIZYPCMM.js → init-modules-7KALFI5C.js} +7 -7
- package/dist/{init-web-OGKACAOC.js → init-web-DYE2FEXL.js} +2 -2
- package/dist/internal.js +68 -62
- package/dist/{keep-data-merge-VRKS64JK.js → keep-data-merge-OVHCIEBG.js} +24 -24
- package/dist/{lambda-config-reconcile-FXPDH2U5.js → lambda-config-reconcile-VOBVZPWS.js} +3 -3
- package/dist/{landing-record-5EFK7RI6.js → landing-record-AIHNW4AZ.js} +17 -16
- package/dist/{live-diff-HARRGFV4.js → live-diff-UMSOGPX3.js} +6 -6
- package/dist/{local-engine-choice-TRTEJVMV.js → local-engine-choice-XDGTATKJ.js} +30 -29
- package/dist/{local-engine-command-2FK2PE2P.js → local-engine-command-VQWNQ7UK.js} +35 -34
- package/dist/{local-engine-deploy-ZZVHBI2X.js → local-engine-deploy-4N4NFZ4T.js} +11 -11
- package/dist/{local-engine-lookup-QFRKO35F.js → local-engine-lookup-AQTUGSBT.js} +2 -2
- package/dist/{local-engine-mcp-bridge-T2EFRRAF.js → local-engine-mcp-bridge-AMYRH4SY.js} +9 -9
- package/dist/{local-engine-mcp-command-FB7EOGG6.js → local-engine-mcp-command-AIMNMXQG.js} +41 -48
- package/dist/{local-engine-process-XH35DURU.js → local-engine-process-OD5OSWDG.js} +6 -6
- package/dist/{local-engine-update-check-HAXE7BVG.js → local-engine-update-check-G3YCBXRE.js} +4 -4
- package/dist/{lock-commands-7PBZIRWR.js → lock-commands-H3YV2D6M.js} +50 -49
- package/dist/{login-command-2O6GRMTH.js → login-command-NMM3JNDZ.js} +23 -22
- package/dist/{logout-command-RZXGW3O2.js → logout-command-7DYC6G32.js} +13 -12
- package/dist/{loop-QHZD37KX.js → loop-DJNIHC7O.js} +6 -6
- package/dist/{marketplace-command-NCMLGIMS.js → marketplace-command-UCSHDZGO.js} +33 -33
- package/dist/{marketplace-resolve-HPCRNV5O.js → marketplace-resolve-JR4BBJ6K.js} +5 -5
- package/dist/{meta-client-DYYM5F5G.js → meta-client-CD3TXQP6.js} +10 -10
- package/dist/{module-manifest-EFE6JBZW.js → module-manifest-63I5GRK4.js} +3 -3
- package/dist/node.js +50 -49
- package/dist/{operation-outcome-SHNROAFA.js → operation-outcome-2ONIIDRU.js} +19 -19
- package/dist/{output-target-PSSR3E4N.js → output-target-67LHZKCO.js} +16 -15
- package/dist/{plan-disclosure-WEMB5ZJ2.js → plan-disclosure-T7DF4SRJ.js} +16 -16
- package/dist/{plugin-contributions-U5PAZKBE.js → plugin-contributions-YYEP7IWH.js} +4 -4
- package/dist/{plugin-prompt-O5PAMV5B.js → plugin-prompt-GKCQKNYI.js} +4 -4
- package/dist/{plugin-questions-ZVYNKDRB.js → plugin-questions-P7MA3TYI.js} +3 -3
- package/dist/{preflight-command-6F7JF3YQ.js → preflight-command-TJ7FURXB.js} +56 -55
- package/dist/{profile-command-5AOGD6GV.js → profile-command-LDPLTJEJ.js} +24 -23
- package/dist/{profile-pointer-VTOZDBHM.js → profile-pointer-JJ7K5O2R.js} +3 -3
- package/dist/{project-dependency-EZNTHMWI.js → project-dependency-X3KCWBK5.js} +6 -6
- package/dist/{project-sdk-ZGJM4WYQ.js → project-sdk-YHJZRCNB.js} +3 -3
- package/dist/promote-command-RURHOLNR.js +148 -0
- package/dist/{prompt-F7UVH4GP.js → prompt-QNMJIWNI.js} +3 -3
- package/dist/{publish-command-6VVSJPLI.js → publish-command-IIRN6NWN.js} +55 -54
- package/dist/{pull-command-GE2WUEUF.js → pull-command-ITO76ENU.js} +66 -65
- package/dist/{pull-superseded-77UZ7CHH.js → pull-superseded-6HADGGC5.js} +3 -3
- package/dist/{release-command-55RTR674.js → release-command-CVGIUD4M.js} +60 -59
- package/dist/{release-ns-command-5XPZ2B6N.js → release-ns-command-YLCQPVH3.js} +78 -77
- package/dist/{retry-command-S5QALD5Z.js → retry-command-LFZYEVRU.js} +7 -7
- package/dist/{routes-manifest-ET2TTSCL.js → routes-manifest-R3TQRB24.js} +6 -6
- package/dist/{routes-manifest-file-42FTJHRY.js → routes-manifest-file-GYNYFKAH.js} +9 -9
- package/dist/scaffold.d.ts +0 -5
- package/dist/scaffold.js +2 -2
- package/dist/{secrets-file-N5IF265R.js → secrets-file-PCNAFXNV.js} +15 -14
- package/dist/{secrets-fill-command-35WKBURT.js → secrets-fill-command-G7NQMRXU.js} +49 -48
- package/dist/{seed-5YLQRT2D.js → seed-4CD55LB4.js} +6 -6
- package/dist/{source-resolve-JXGOVJD3.js → source-resolve-U4SJR7ZA.js} +17 -17
- package/dist/{static-host-TQP3FXPI.js → static-host-MO4VDHL7.js} +4 -4
- package/dist/{status-command-G3DFRMU7.js → status-command-CD72PXIT.js} +60 -34
- package/dist/{store-ZE5BXCOW.js → store-AJX4MC7Y.js} +5 -5
- package/dist/{sync-baseline-JGAAOS25.js → sync-baseline-BJDKG4F2.js} +7 -7
- package/dist/{sync-contributions-7T4CSPVQ.js → sync-contributions-XK6LHISZ.js} +8 -8
- package/dist/{sync-record-ILWS44DG.js → sync-record-NE62ERA3.js} +9 -9
- package/dist/{table-V3LTQUY6.js → table-WPRAM4VW.js} +8 -8
- package/dist/{tables-command-7NUOZBHX.js → tables-command-NMTKR52H.js} +35 -34
- package/dist/{tenant-7WUS7Q6V.js → tenant-IIYECNWO.js} +9 -9
- package/dist/{tenant-command-JGEHRKN7.js → tenant-command-XQAWT46C.js} +83 -82
- package/dist/{test-command-2LNEA6GK.js → test-command-W4AD4KT4.js} +32 -31
- package/dist/{tests-ENFUACKD.js → tests-JWQRHFCT.js} +5 -5
- package/dist/{token-DWNH44NW.js → token-P3VQ6ITJ.js} +9 -8
- package/dist/{toolchain-hooks-QIFGPGH2.js → toolchain-hooks-UAJBPSTC.js} +8 -8
- package/dist/{toolchain-modules-F4DUMWTO.js → toolchain-modules-S3MPHCUI.js} +4 -4
- package/dist/{toolchain-peers-K44IINPG.js → toolchain-peers-FQJBTKEB.js} +7 -7
- package/dist/{tracked-backend-ZFXVLBBJ.js → tracked-backend-WWEPNUD5.js} +30 -29
- package/dist/{update-check-KBHT63GJ.js → update-check-O7QC5TBB.js} +48 -47
- package/dist/{upgrade-command-CI543AZP.js → upgrade-command-J6LRNHYF.js} +51 -50
- package/dist/{whoami-command-77DXENWD.js → whoami-command-KWRP2CII.js} +12 -11
- package/dist/{workspace-RI5C77BZ.js → workspace-3YNK4XO4.js} +4 -4
- package/dist/{workspace-binding-PR57NBGH.js → workspace-binding-TTDNXHO5.js} +11 -10
- package/dist/{workspace-command-6HHVFQKW.js → workspace-command-W4ANGLCZ.js} +79 -78
- package/dist/{workspace-env-2APJEASO.js → workspace-env-6LJGCTZA.js} +12 -11
- package/dist/{workspace-export-GHMUSX2P.js → workspace-export-PUEXKZNS.js} +4 -4
- package/dist/{writable-Y6CE2CGK.js → writable-LMMG4AFZ.js} +3 -3
- package/dist/{xano-2A2GT7EH.js → xano-Z3SRHYOR.js} +7 -7
- package/dist/{xanosdk-import-HBQH3ZBS.js → xanosdk-import-PNNMZ4SF.js} +5 -5
- package/dist/{xanosdk-project-W45IR3Q7.js → xanosdk-project-YW3BQY2E.js} +13 -12
- package/guides/README.md +3 -3
- package/guides/authoring.md +11 -11
- package/guides/bundle.md +2 -2
- package/guides/cli.md +179 -176
- package/guides/codegen.md +17 -17
- package/guides/codes.md +3 -3
- package/guides/coverage.md +2 -2
- package/guides/deploying.md +123 -123
- package/guides/environment.md +30 -30
- package/guides/marketplace.md +24 -24
- package/guides/module-contract.md +9 -9
- package/guides/object-kinds.md +4 -4
- package/guides/project-structure.md +4 -4
- package/guides/scaffold.md +22 -22
- package/guides/typed-frontend.md +3 -3
- package/llms/client.md +4 -4
- package/llms/errors.md +2 -2
- package/llms/fields.md +1 -1
- package/llms/kinds-agent-mcp.md +1 -1
- package/llms/kinds-realtime.md +2 -2
- package/llms/lock.md +3 -3
- package/llms/statements-calls.md +1 -1
- package/llms/statements-runtime.md +2 -2
- package/llms/tests.md +3 -3
- package/llms/toolchain.md +2 -2
- package/llms-full.txt +56 -53
- package/llms.txt +35 -32
- package/manifest.json +1 -1
- package/package.json +1 -1
- package/skills/xano-backend/SKILL.md +7 -7
- package/dist/promote-command-O2NRRFLK.js +0 -147
package/llms-full.txt
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# xanosdk v1.0.
|
|
1
|
+
# xanosdk v1.0.14
|
|
2
2
|
|
|
3
3
|
> TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
|
|
4
4
|
|
|
@@ -6,8 +6,8 @@ Xano is one platform to build, run and govern AI-built software: one WORKSPACE
|
|
|
6
6
|
serves a managed PostgreSQL database, HTTP APIs, background tasks, realtime
|
|
7
7
|
websocket channels, AI agents, MCP servers, file storage and redis. This SDK
|
|
8
8
|
authors it in TypeScript — typed def objects registered on a
|
|
9
|
-
`workspace(name)` — compiled to one importable bundle by `
|
|
10
|
-
./xano/index.ts`, shipped live by `
|
|
9
|
+
`workspace(name)` — compiled to one importable bundle by `npx @xano/sdk export
|
|
10
|
+
./xano/index.ts`, shipped live by `deploy`.
|
|
11
11
|
|
|
12
12
|
Def modules execute at BUILD time only: `s.*` factories return data, and the engine
|
|
13
13
|
runs the compiled stack per request — statements in order, a statement's `as:`
|
|
@@ -41,7 +41,7 @@ plain file read resolves them at the version you have.
|
|
|
41
41
|
- [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
|
|
42
42
|
- [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, tool, or addon — and for the `response` and `expr` shapes every one of them uses.
|
|
43
43
|
- [Consuming defs from a client](llms/client.md): Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
|
|
44
|
-
- [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `
|
|
44
|
+
- [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `npx @xano/sdk marketplace`.
|
|
45
45
|
- [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
|
|
46
46
|
- [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
|
|
47
47
|
- [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when building an MCP server (tools, prompts, resources) or an `agent()`.
|
|
@@ -112,7 +112,7 @@ export default workspace("my-blog")
|
|
|
112
112
|
.registerQueries([createPost, listPosts]);
|
|
113
113
|
```
|
|
114
114
|
|
|
115
|
-
Compile: `
|
|
115
|
+
Compile: `npx @xano/sdk export ./index.ts --out bundle.json` (or `writeBundle(app, path)`
|
|
116
116
|
from `@xano/sdk/node` in code). The default export must be the `Xano` registry. The entry must be an
|
|
117
117
|
ES module (Xano SDK defs are ESM-only): set `"type": "module"` in the nearest
|
|
118
118
|
package.json or name the entry `.mts`. `npm init -y` writes `"type": "commonjs"`,
|
|
@@ -120,7 +120,7 @@ which fails with a "must be ES modules" error until you switch it to module.
|
|
|
120
120
|
|
|
121
121
|
Set `canonical` on every `apiGroup`. The engine mints the URL token server-side, so
|
|
122
122
|
without one a group's client paths are unresolvable until a lock exists: the bundle
|
|
123
|
-
exports fine and `
|
|
123
|
+
exports fine and `npx @xano/sdk routes` / `getPath()` then fail on the very queries it just
|
|
124
124
|
built. An explicit `canonical` resolves them from the source alone.
|
|
125
125
|
⚠ A canonical is unique across the whole INSTANCE, not per workspace — two
|
|
126
126
|
workspaces cannot serve the same one, and no flag shares it. One set in code is a PIN:
|
|
@@ -134,8 +134,8 @@ operand, a `ref()` nothing binds). Each has a legitimate use, so each only warns
|
|
|
134
134
|
but nothing fails on a message no one reads, so in CI and in unattended agent builds
|
|
135
135
|
pass `--strict` (`emitBundle(app, { strict: true })` / `app.export({ strict: true })`):
|
|
136
136
|
every warning becomes a hard failure. Same bundle bytes either way.
|
|
137
|
-
Before calling the work done: `npm run typecheck`, `
|
|
138
|
-
`
|
|
137
|
+
Before calling the work done: `npm run typecheck`, `npx @xano/sdk export <entry> --strict`,
|
|
138
|
+
`deploy <entry>`, then `test run-all` against what deployed.
|
|
139
139
|
|
|
140
140
|
Identity: object guids derive from `(type, name)` — a query's from `(api group,
|
|
141
141
|
verb, name)` — so renames change identity.
|
|
@@ -144,15 +144,15 @@ BESIDE THE ENTRY FILE — `xano/xano.lock` for the standard scaffold,
|
|
|
144
144
|
NOT the project root — which you COMMIT (`--no-lock` opts out; CI guard
|
|
145
145
|
`--frozen-lock` fails instead of changing it).
|
|
146
146
|
To rename an object: rename in code, export (stderr prints the exact fix-up), run
|
|
147
|
-
`
|
|
147
|
+
`npx @xano/sdk lock rename <kind> <old> <new>`, export again — the original guid is emitted
|
|
148
148
|
under the new name, so the engine renames in place instead of delete+create. Taking
|
|
149
|
-
over an existing workspace: `
|
|
149
|
+
over an existing workspace: `npx @xano/sdk lock import <live-bundle.json>` first, then
|
|
150
150
|
export. Pruning, programmatic seeding, and which commands write the lock:
|
|
151
151
|
`llms/lock.md`.
|
|
152
152
|
|
|
153
153
|
## Deploy
|
|
154
154
|
|
|
155
|
-
`
|
|
155
|
+
Commands here run as `npx @xano/sdk <cmd>`: `init` → `deploy` → URL. A deploy runs the same compile pipeline as
|
|
156
156
|
`export` (honoring `xano.lock`), imports the result, and prints the URL.
|
|
157
157
|
⚠ Every deploy is a FULL REPLACE of its destination — objects AND records.
|
|
158
158
|
|
|
@@ -168,7 +168,7 @@ and a `tenant:` only if throwaway (`standard`/`run` refused).
|
|
|
168
168
|
|
|
169
169
|
**Destinations** — the Xano Engine by default, real only when you say so:
|
|
170
170
|
|
|
171
|
-
- `
|
|
171
|
+
- `deploy [source]` → the Xano Engine on this machine (no account). `--ephemeral` → a NAMED, auto-expiring ephemeral (~1h; `--expires-hours`
|
|
172
172
|
1–24), tracked in `./.xano/ephemeral.json`, so deploying again REFRESHES it at the same
|
|
173
173
|
URL; if it expired or was swept, a fresh one is created and the new URL called out.
|
|
174
174
|
⚠ Only the BACKEND URL survives a refresh — the replace clears static hosting, so
|
|
@@ -176,17 +176,17 @@ and a `tenant:` only if throwaway (`standard`/`run` refused).
|
|
|
176
176
|
(not under `--keep-data`, which MERGES an env a deploy filled: rows kept, no re-seed,
|
|
177
177
|
removed objects deleted; ⚠ a rename loses values, a RETYPE reads unfit ones as null, env
|
|
178
178
|
VALUES are not applied, a table trigger refuses it — `--reset` replaces and re-seeds).
|
|
179
|
-
- `
|
|
179
|
+
- `release create <name>` cuts from a running source and LANDS in your workspace
|
|
180
180
|
— the record that it came up, and the only thing `promote`/`tenant deploy` take. A
|
|
181
181
|
taken name is refused, and so is one that addresses a LOCATION instead of naming: `/`,
|
|
182
182
|
`\`, `:`, or a leading `.`. Every export derives its FILENAME from the name it is given,
|
|
183
183
|
so `release|ephemeral|workspace export` refuse those same shapes unless `--path` names
|
|
184
184
|
the file. Carries EVERY table's SCHEMA either way; `--seed[=<guids>]` adds
|
|
185
|
-
ROWS — guids from `
|
|
186
|
-
- `
|
|
185
|
+
ROWS — guids from `tables <backend>`; a redeploy KEEPS them.
|
|
186
|
+
- `release transfer <name> --to-profile <profile>` copies a release to another
|
|
187
187
|
workspace/instance by CONTENT (tar sha256): identical → reused; same name, other
|
|
188
188
|
bytes → exit 2.
|
|
189
|
-
- `
|
|
189
|
+
- `promote <release>` / `tenant deploy <tenant> <release>` land it.
|
|
190
190
|
`promote` adds a branch; ⚠ its TABLE edits hit live
|
|
191
191
|
(`--allow-shared-schema-changes`). `tenant deploy` REPLACES: DROPS tables it lacks,
|
|
192
192
|
CONVERTS retypes (`--seed`: rows).
|
|
@@ -204,24 +204,24 @@ and a `tenant:` only if throwaway (`standard`/`run` refused).
|
|
|
204
204
|
- Backend SECRETS stay out of the repo: declare the NAME, value empty, in `workspaceConfig({ env })`
|
|
205
205
|
passed to `registerWorkspace()`; the VALUE lives in `xano/.env` — gitignored, kept across a
|
|
206
206
|
pull, read by every build. `--backend-env-file <path>` replaces that default (CI has
|
|
207
|
-
no `xano/.env`), `--env-var KEY=VALUE` beats both, and `
|
|
207
|
+
no `xano/.env`), `--env-var KEY=VALUE` beats both, and `env pull` fills the file from
|
|
208
208
|
a running backend — the only command that writes `xano/.env`.
|
|
209
209
|
⚠ A deploy REPLACES the env set: a declared name with NO value refuses the deploy rather
|
|
210
210
|
than clearing the live one — `--allow-empty-env=NAME` clears it on purpose.
|
|
211
|
-
ONE live value, no deploy: `
|
|
211
|
+
ONE live value, no deploy: `env set NAME` (value on stdin) / `env unset NAME`.
|
|
212
212
|
(`--static-env` is the other one — PUBLIC frontend config.)
|
|
213
213
|
- A DOCUMENTATION token is a secret too, in a SECOND ignored file: source declares only the
|
|
214
214
|
gate — `documentation: { require_token: true }` on `workspaceConfig` or an `apiGroup` — and
|
|
215
215
|
the value lives in `xano/.secrets.json`, keyed by the object it gates. A literal `token`
|
|
216
|
-
FAILS the export. `
|
|
217
|
-
`
|
|
216
|
+
FAILS the export. `pull` writes that file and every build reads it back;
|
|
217
|
+
`secrets fill` MINTS one per gate that has none — a gate you AUTHORED has no value
|
|
218
218
|
to pull. CI, which does not have the file, passes `--secrets-file <path>` or
|
|
219
219
|
`--doc-token "<scope>=<value>"`
|
|
220
220
|
(scope = `workspace`, or the group's NAME).
|
|
221
221
|
⚠ OMISSION IS OPPOSITE PER SCOPE: off `workspaceConfig` the target's gate is left alone;
|
|
222
222
|
off an `apiGroup` it is CLEARED (an absent key there is written as the engine default). An
|
|
223
223
|
unsupplied gate refuses a `deploy` and fails the export for a publishing group.
|
|
224
|
-
- `
|
|
224
|
+
- `deploy --to workspace|tenant:<name>` skips the release flow to merge a LOCAL
|
|
225
225
|
build in, keeping the checks that need one (`--dry-run`, `--prune`, loss warnings) and
|
|
226
226
|
leaving nothing to roll back to. Prefer the release path.
|
|
227
227
|
⚠ Branches scope LOGIC: tables and microservices are shared by EVERY branch, so a
|
|
@@ -230,28 +230,28 @@ and a `tenant:` only if throwaway (`standard`/`run` refused).
|
|
|
230
230
|
⚠ `--replace` CLEARS BY WORKSPACE, NOT BY BRANCH: every non-live branch goes, with the
|
|
231
231
|
saved versions that would restore one — unrecoverable. Refused without
|
|
232
232
|
`--allow-branch-deletion`; `--yes` does not imply it. The default merge leaves them alone.
|
|
233
|
-
- `
|
|
233
|
+
- `workspace reset-tables <entry> --table <guid>` puts NAMED tables back to their
|
|
234
234
|
compiled `table({ seed })` rows, touching no other table. Dry run unless `--write`.
|
|
235
235
|
⚠ ROWS BEFORE LOGIC: rows are workspace-shared like schema, so they reach production when
|
|
236
236
|
applied even while the logic reading them is staged — no ordering makes a half-data change
|
|
237
237
|
atomic. Reset rows FIRST, then `promote`: new rows under old logic break only a feature
|
|
238
238
|
being removed; new logic over old rows breaks the one you are shipping.
|
|
239
|
-
- `
|
|
239
|
+
- `pull` refreshes THIS project from a backend: rewrites decoded files,
|
|
240
240
|
keeps yours, lists and confirms (`--yes`).
|
|
241
|
-
- `
|
|
242
|
-
- `
|
|
241
|
+
- `generate <source>`: the decoded tree ONLY, no project.
|
|
242
|
+
- `status` names the env this project last deployed to, its URL and its expiry.
|
|
243
243
|
|
|
244
|
-
**Frontend wiring.** `--static <dir>` (or `
|
|
244
|
+
**Frontend wiring.** `--static <dir>` (or `publish <dir>`) injects the env's backend URL as
|
|
245
245
|
`window.XANO_HOST` into EVERY html document in the build, before the app bundle runs,
|
|
246
246
|
so the frontend needs no rebuild to target an env. How to read it, local dev, verifying
|
|
247
247
|
the inject, and displaying a stored file: `llms/client.md`.
|
|
248
248
|
⚠ A static host serves its files verbatim, so everything injected is PUBLIC — base
|
|
249
249
|
URLs and publishable keys only, never secrets. Secrets go in backend env, read
|
|
250
250
|
server-side via `env(name)`.
|
|
251
|
-
⚠ `
|
|
251
|
+
⚠ `preflight` uses the deploy credential unless `XANO_VALIDATE_INSTANCE` /
|
|
252
252
|
`XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) are set.
|
|
253
253
|
|
|
254
|
-
**Full CLI surface:** `
|
|
254
|
+
**Full CLI surface:** `npx @xano/sdk <command> --help` — every command, flag, default and accepted
|
|
255
255
|
backend; `manifest.json` carries the same in its `cli` array.
|
|
256
256
|
**Style:** reach statements through the `s` namespace (`s.db.add`, `s.math.add`, …).
|
|
257
257
|
The flat aliases (`dbAdd`, `setVar`, …) are identical in output; prefer `s.*`.
|
|
@@ -430,11 +430,11 @@ Non-obvious authoring rules:
|
|
|
430
430
|
refuses the pair (`export()` warns even unlocked); it is for pinning identity
|
|
431
431
|
across a rename, not for sharing a name.
|
|
432
432
|
- **`export()` vs `emitBundle()` vs `writeBundle()`:** `export()` returns the object,
|
|
433
|
-
`emitBundle()` the JSON, `writeBundle(app, path)` writes `
|
|
433
|
+
`emitBundle()` the JSON, `writeBundle(app, path)` writes `export`'s file. All
|
|
434
434
|
three run the SAME build-time checks, INCLUDING seed validation of a literal `seed: [...]`
|
|
435
435
|
array (row shape, unknown column, coercion, enum membership, the all-or-nothing `id`
|
|
436
436
|
rule). A DEFERRED seed — a thunk (`() => import("./seed.json")`) or `seedFile()` — is
|
|
437
|
-
checked only by the `
|
|
437
|
+
checked only by the `export`/`deploy` CLI path. Only `deploy` ships seed rows.
|
|
438
438
|
- Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O
|
|
439
439
|
import from `@xano/sdk/node`, NOT the browser-safe `@xano/sdk` entry (a frontend
|
|
440
440
|
imports from it; request types come from `routes.gen.ts`). `@xano/sdk/internal` is the
|
|
@@ -442,15 +442,18 @@ Non-obvious authoring rules:
|
|
|
442
442
|
— a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.
|
|
443
443
|
- **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not
|
|
444
444
|
extensionless — the defs compile under `moduleResolution: bundler`. Add the `.js`.
|
|
445
|
-
- **Agents authenticate with env vars — never `
|
|
445
|
+
- **Agents authenticate with env vars — never `npx @xano/sdk login`.** `login` blocks on a
|
|
446
446
|
browser consent no agent can complete. Set all three of `$XANO_INSTANCE_URL`,
|
|
447
447
|
`$XANO_WORKSPACE_ID`, `$XANO_META_TOKEN` and run `deploy`/`promote` directly: no disk, no
|
|
448
448
|
rotation, so it survives repeated runs.
|
|
449
|
+
- Not signed in: ask the human whether they have a Xano account; never guess. No: sign
|
|
450
|
+
them up via https://app.dev.xano.com/.well-known/auth.md; it returns this triple once they confirm by email. Yes: the
|
|
451
|
+
human runs `login`.
|
|
449
452
|
- The triple outranks every other credential (`--config`, `$XANO_PROFILE` and
|
|
450
453
|
`$XANO_REFRESH_TOKEN` included, each named on stderr when displaced). Setting SOME of the
|
|
451
454
|
three is a hard error, so a misspelled secret cannot fall through to whatever credential
|
|
452
455
|
the runner has. An explicit `--profile` against it is a hard error too, not a displacement.
|
|
453
|
-
- On disk: `
|
|
456
|
+
- On disk: `npx @xano/sdk profile add <name> --instance … --workspace-id <n>` reads the token
|
|
454
457
|
from piped stdin, else PROMPTS (a flag would reach the process list); the instance must accept it.
|
|
455
458
|
`auth.json` holds a map of named profiles, selected by `--profile <name>`. The older
|
|
456
459
|
`$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works but ROTATES: single-use.
|
|
@@ -656,7 +659,7 @@ Importing a def into a browser bundle or a Node script — for `getPath()`, `get
|
|
|
656
659
|
⚠ A FLOOR — **~267 kB minified (~65 kB gzipped)** for the FIRST def; splitting modules
|
|
657
660
|
never removes it. The floor is the RUNTIME, not the def: a second or much richer def
|
|
658
661
|
adds ~2 kB, so trimming a def does not shrink it.
|
|
659
|
-
Fix: `
|
|
662
|
+
Fix: `npx @xano/sdk routes <entry> --emit xano/routes.gen.ts` (`paths` is an accepted alias) — verbs, paths, and sockets as
|
|
660
663
|
plain data importing NOTHING, still compile-checked: `routePath("GET blog/{slug}", { slug })`
|
|
661
664
|
`channelPath("rooms/{room_id}", { room_id })`, `socketUrl("chat", baseUrl)` (tenant base
|
|
662
665
|
URLs lifted to `wss://h/ws/<tenant>:<canonical>`), `mcpUrl("notes_mcp", baseUrl)` (an MCP
|
|
@@ -668,7 +671,7 @@ Importing a def into a browser bundle or a Node script — for `getPath()`, `get
|
|
|
668
671
|
keep `InferInput` in code that already imports defs. They match `InferInput`, except a
|
|
669
672
|
`dbLink` input appears as the linked table's columns (what the server accepts). Responses
|
|
670
673
|
are not in the file: `InferResponse` on an `import type` of the def.
|
|
671
|
-
Runtime validation: `
|
|
674
|
+
Runtime validation: `npx @xano/sdk marketplace install zod` adds `@xano-sdk/zod`, which writes
|
|
672
675
|
`ROUTE_SCHEMAS`/`CHANNEL_SCHEMAS`/`MESSAGE_SCHEMAS` into the file under the same keys, each
|
|
673
676
|
checked against its type at typecheck; the file then imports `zod`, never `@xano/sdk`.
|
|
674
677
|
- **Verifying a def outside a bundler.** Inside a bundler (Vite/webpack) importing a
|
|
@@ -679,7 +682,7 @@ Importing a def into a browser bundle or a Node script — for `getPath()`, `get
|
|
|
679
682
|
xanosdk CLI's own loader resolves). Running from outside the project root also breaks
|
|
680
683
|
the `@xano/sdk` specifier resolution.
|
|
681
684
|
|
|
682
|
-
**Reading the injected backend URL.** `
|
|
685
|
+
**Reading the injected backend URL.** `npx @xano/sdk deploy <entry> --static <dir>` writes the deployed env's URL
|
|
683
686
|
into every html document: a prerendered build serves a different one per
|
|
684
687
|
route, and a route without the global renders fine while every call goes to the wrong
|
|
685
688
|
origin. Read it at runtime with a build-time fallback:
|
|
@@ -694,7 +697,7 @@ host falls back to '', and every call 404s off the dev server.
|
|
|
694
697
|
⚠ It is INJECTED in bracket form — `window["XANO_HOST"]="…"` — so verifying a deploy
|
|
695
698
|
by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Grep the
|
|
696
699
|
bare `XANO_HOST` token.
|
|
697
|
-
**Frontend without the backend.** `
|
|
700
|
+
**Frontend without the backend.** `npx @xano/sdk publish <dir> [--to <backend>]` uploads an
|
|
698
701
|
already-built directory and nothing else — no compile, no import (scaffold script
|
|
699
702
|
`npm run xano:deploy:frontend`). A Xano Engine (`--to local`, or bare after a local
|
|
700
703
|
deploy) serves it, server half included, at `http://<prefix>.localhost:<port>`.
|
|
@@ -719,7 +722,7 @@ an absent file and is correct on an ephemeral and an instance workspace alike.
|
|
|
719
722
|
|
|
720
723
|
# Toolchain modules
|
|
721
724
|
|
|
722
|
-
> Read when `package.json` has a `"xanosdk"` block or you run `
|
|
725
|
+
> Read when `package.json` has a `"xanosdk"` block or you run `npx @xano/sdk marketplace`.
|
|
723
726
|
|
|
724
727
|
**Toolchain modules** extend the CLI, not the workspace — nothing to register in
|
|
725
728
|
`xano/index.ts`. An installed one runs on `export` and `deploy` (after the compile,
|
|
@@ -744,7 +747,7 @@ the request inputs under the manifest's keys and its config, it returns `{ impor
|
|
|
744
747
|
imports as bare package names (`@xano/sdk*`, relative and `node:` are refused). A module that
|
|
745
748
|
fails to load or throws leaves its previous block as it was, with a warning naming it, and the
|
|
746
749
|
core sections still refresh; under `routes --emit --strict` it is fatal. `@xano-sdk/zod`
|
|
747
|
-
(`
|
|
750
|
+
(`npx @xano/sdk marketplace install zod`) is one: it adds `ROUTE_SCHEMAS` and its siblings.
|
|
748
751
|
|
|
749
752
|
# Error index
|
|
750
753
|
|
|
@@ -785,7 +788,7 @@ core sections still refresh; under `routes --emit --strict` it is fatal. `@xano-
|
|
|
785
788
|
- `ERR_PACKAGE_PATH_NOT_EXPORTED` — `tsx -e "import …"`, or running from outside the project root; run a real file with `tsx <file.ts>` from the root. `llms/client.md`.
|
|
786
789
|
- `Missing statement: mvp:placeholder` on import — an unconfigured slot in a pulled tree; replace it with the statement it stands in for. `llms/legacy.md`.
|
|
787
790
|
- 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[]` → `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`.
|
|
788
|
-
- A CLI command reports `could not reach <url>: fetch failed (<code>)` — blocked egress, not a bad credential; fix it before `
|
|
791
|
+
- A CLI command reports `could not reach <url>: fetch failed (<code>)` — blocked egress, not a bad credential; fix it before `npx @xano/sdk login`, which rotates a single-use refresh token.
|
|
789
792
|
|
|
790
793
|
### CLI exit codes
|
|
791
794
|
|
|
@@ -800,7 +803,7 @@ A failure document's `exitCode` matches.
|
|
|
800
803
|
| 4 | `deploy --require-microservices`: a microservice was not ready in time. The backend landed. | Check the microservice. |
|
|
801
804
|
| 5 | `test` / `deploy --test`: the suite ran and a test failed. A deploy is not retracted. | Fix the test or the code. |
|
|
802
805
|
| 6 | `test`, `deploy --test`: the suite could not be reached. | Check the backend; rerun. |
|
|
803
|
-
| 7 | `upgrade --check`: an upgrade is available. | `
|
|
806
|
+
| 7 | `upgrade --check`: an upgrade is available. | `npx @xano/sdk upgrade`. |
|
|
804
807
|
| 8 | A named backend could not be addressed (or a named release, profile, branch, test, module, lock entry, `--seed` guid or Xano Engine version is missing): gone, expired, unreachable, a stopped Xano Engine, or a busy import. | Retry, or redeploy. |
|
|
805
808
|
| 9 | A write whose outcome is unknown, Ctrl-C during a write included. | Read the target's state before retrying. |
|
|
806
809
|
| 130 | Ctrl-C outside a write or install. | — |
|
|
@@ -856,14 +859,14 @@ The run is isolated in ways that make a correct test fail for reasons the failur
|
|
|
856
859
|
|
|
857
860
|
### Running them
|
|
858
861
|
|
|
859
|
-
`
|
|
862
|
+
`npx @xano/sdk test run-all` runs the unit tests AND the `workflowTest()` objects an environment carries. It takes no entry file and compiles nothing: it runs what is DEPLOYED, so deploy before testing.
|
|
860
863
|
|
|
861
864
|
- `--on <backend>` picks the backend — `--on ephemeral:<name>`, `--on local`, `--on tenant:<name>`, `--on workspace`; omitted, the one this project last deployed to (grammar: **Backends** in `llms.txt`). ⚠ `workspace` runs against the REAL database: safe only while every test keeps `datasource: ""`, since a stored non-empty datasource is CLONED before the run.
|
|
862
|
-
- `
|
|
865
|
+
- `npx @xano/sdk test list` shows what is there without running it; `test run "<name>"` runs one; an ambiguous name prints qualified forms (`function:math/happy path`, `workflow:<name>`) `run` accepts.
|
|
863
866
|
- `--kind unit|workflow` narrows to one family. `--concurrency <n>` defaults to 1: tests share the environment database.
|
|
864
867
|
- A failing suite exits 5; exit 6 when the suite could not be reached — retry it; a backend that can't be looked up exits 8 (see errors). Having no tests is success.
|
|
865
868
|
- For CI: the exit code says THAT something failed, the JSON says WHICH. Progress goes to stderr; stdout carries one JSON document when not a terminal, or with `--json`. `run-all` and `run`: `{ kind, env, name, display, total, passed, failed, tests: [{ kind, name, qualified, object?, status: "pass"|"fail", message?, expectations?: [{ index, status, message? }], timing? }] }` (`message`: the first failure; `expectations`: a unit test's every expectation in order, `index` from 0; `env`: an ephemeral's or tenant's name; `name`: the backend's own, a Xano Engine's too; null if none), same keys on an empty suite. `list` is `{ kind, env, name, display, total, tests }`; `deploy --test` nests the run under `testRun`.
|
|
866
|
-
- `
|
|
869
|
+
- `npx @xano/sdk deploy ./index.ts --test` deploys and then runs the suite against what it just shipped. A failure exits 5 WITHOUT retracting the deploy — the environment is live either way.
|
|
867
870
|
|
|
868
871
|
# Agent and MCP def shapes
|
|
869
872
|
|
|
@@ -896,7 +899,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
|
|
|
896
899
|
- `tools?`: same `ToolsetToolEntry[]` as `mcpServer` — bare `tool()` handles, or a `{ tool, enabled?, auth? }` wrapper when one needs `enabled`/`auth`. A tool reading `auth()` MUST use the wrapper naming the auth table — a bare handle runs it with no caller (see `mcpServer`'s `tools?`).
|
|
897
900
|
- `output?`: `{ schema: Record<string, input.*>, enabled? }` — structured-output schema. `schema` is a named-field record authored with the `input.*` catalog, exactly like a `defineFunction`/`query` `input:` map (the stored `structuredOutputsSchema` is the same wire shape as function inputs). 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 straight from this schema — no `resultShape` witness needed (the shape is declared once). `resultShape` remains only to override that, or to type an agent referenced by bare name.
|
|
898
901
|
- **Run + read recipe (`s.ai.agent.run`):** bind the run to a var (`s.ai.agent.run({ agent, args, allowToolExecution: c.bool(true), as: "run" })`) — 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`); persist it in a later step the same way (`s.set_var("summary", ref("run.result.summary"))`). `args` is a plain object of run inputs (`{ topic: inp("topic") }` — 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"`. ⚠ An agent with tools needs `allowToolExecution: c.bool(true)` on the run: unset, its tools are OFF and it answers without them (warns `stack.agent-tools-off`).
|
|
899
|
-
- **Marketplace:** for chat history, use `@xano-sdk/chatbot`; for vector RAG, use `@xano-sdk/vector` (`tools: [vector.searchTool]`). Find add-ons with `
|
|
902
|
+
- **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>`.
|
|
900
903
|
- Both kinds persist under the `toolset` payload key, so a same-name `agent` + `mcpServer` pair derives ONE guid and `export()` throws — give them distinct names.
|
|
901
904
|
|
|
902
905
|
# Knowledge def shape
|
|
@@ -957,7 +960,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
|
|
|
957
960
|
- ⚠ FAIL-SOFT — a missing/disabled server or dead bus is swallowed engine-side, so a mis-targeted publish is SILENT with no result to check.
|
|
958
961
|
- `authTable`/`authId` are ASSERTED attribution on the frame — not a credential, nothing validates them.
|
|
959
962
|
- **Client recipe (derive, never hardcode):**
|
|
960
|
-
- `server.getUrl(baseUrl)` → `wss://<host>/ws/<canonical>` — accepts the `https://…` instance base URL and normalizes the scheme. `channel.getChannel({ room_id: 42 })` → `"rooms/42"`, the path that goes in a frame's `channel` field. Both throw rather than guess. A canonical is minted by `
|
|
963
|
+
- `server.getUrl(baseUrl)` → `wss://<host>/ws/<canonical>` — accepts the `https://…` instance base URL and normalizes the scheme. `channel.getChannel({ room_id: 42 })` → `"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`.
|
|
961
964
|
- Auth is a bearer token passed as the websocket SUBPROTOCOL: `new WebSocket(url, token)`. No token = an anonymous client, admitted only where `anonymousClients: true`.
|
|
962
965
|
- 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` — an immediate first frame is refused.
|
|
963
966
|
- `options` is `{ to?, client_id?, channel? }` — `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`.
|
|
@@ -969,7 +972,7 @@ The run is isolated in ways that make a correct test fail for reasons the failur
|
|
|
969
972
|
- **Tenant instances (isolated DB):** a tenant's realtime objects live in the TENANT's database, so BOTH halves of a client must name the tenant.
|
|
970
973
|
- Socket: `server.getUrl(base, { tenant })` → `/ws/<tenant>:<canonical>`. ⚠ A bare canonical on a tenant host resolves against the INSTANCE workspace instead.
|
|
971
974
|
- That colon form is PECULIAR TO THE SOCKET. Every other tenant URL gives the tenant its OWN segment — the HTTP half of the same client is `https://<host>/tenant/<tenant>/api:<canonical>/…`. NO request header is required for either.
|
|
972
|
-
- Because the shapes differ, `getUrl` TRANSLATES a tenant base URL instead of concatenating: pass the `https://<host>/tenant/<name>` that `
|
|
975
|
+
- Because the shapes differ, `getUrl` TRANSLATES a tenant base URL instead of concatenating: pass the `https://<host>/tenant/<name>` that `npx @xano/sdk status` prints (and that deploy injects as `window.XANO_HOST`) and the tenant is LIFTED into the socket form. So `getUrl(window.XANO_HOST)` needs no `{ tenant }`, and a CONFLICTING `{ tenant }` alongside it throws.
|
|
973
976
|
- ⚠ `getUrl`/`socketUrl` are NOT idempotent — a `baseUrl` that already carries a `/ws/<…>` path THROWS. Resolve ONCE from the http(s) base; never feed a result back in.
|
|
974
977
|
- Still pass `{ tenant }` explicitly for a tenant on its OWN DOMAIN — the hostname carries it for HTTP, but there is nothing in the URL for the socket to lift.
|
|
975
978
|
- ⚠ 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 — authenticate and dial through the same tenant.
|
|
@@ -1165,12 +1168,12 @@ Runtime behavior (what the `as:` output holds, and misses):
|
|
|
1165
1168
|
- Workspace-level defaults are the terminal tier: `workspaceConfig({ history: { query, function, task, tool, trigger, middleware } })` emits the flat `{objType}_enabled`/`{objType}_limit` map (no inherit flag) — setting it is wholesale (unlisted types fall back to their engine default), so declare every default you want to keep; omit the field to leave existing workspace history untouched.
|
|
1166
1169
|
|
|
1167
1170
|
- **Workspace environment variables** set a tenant's env vars through the workspace object: `workspaceConfig({ env: { STRIPE_KEY: "", APP_BASE_URL: "" } })`, passed to `registerWorkspace()` — unattached, it declares nothing. Author them as a name→value MAP, declaring each NAME with an EMPTY value. Read a var back with `env("NAME")` (→ `$env.NAME`), which compiles to tag "setting" with the plain name.
|
|
1168
|
-
- Values are SECRETS and do NOT belong here: they live in `xano/.env`, which is gitignored and survives a `
|
|
1171
|
+
- 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 — don't commit one.
|
|
1169
1172
|
- What a deploy sends is the RESOLVED map (the declared names, then ONE file — `xano/.env`, or `--backend-env-file <path>` which REPLACES it, never both — 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 — 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.
|
|
1170
1173
|
|
|
1171
1174
|
- **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 — `env()` cannot read it. Other members are carried verbatim.
|
|
1172
1175
|
- ⚠ OMIT the block and NO `documentation` key is emitted, leaving the target's live block as it is; the legacy `realtime` block follows the same rule. An `apiGroup`'s `documentation` follows the OPPOSITE rule — see its def shape.
|
|
1173
|
-
- 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). `
|
|
1176
|
+
- 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.
|
|
1174
1177
|
- A merge (`deploy --to`) is ADD-ONLY, matched BY NAME — 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) — 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.
|
|
1175
1178
|
|
|
1176
1179
|
# Auth, cross-object calls, and microservices
|
|
@@ -1180,7 +1183,7 @@ Runtime behavior (what the `as:` output holds, and misses):
|
|
|
1180
1183
|
Auth & calls:
|
|
1181
1184
|
|
|
1182
1185
|
- `s.security.create_auth_token({ table, id, extras?, expiration?, as? })` — `extras` defaults to `{}`, `expiration` (seconds, a `Value`: `c.int(3600)`) to 86400 (`c.int(0)` = never).
|
|
1183
|
-
- **Marketplace first:** `@xano-sdk/auth` registers a complete auth surface — signup/login/me endpoints plus their `user`/`account`/`event_log` tables — via `registerAuth(ws, { canonical: "authn" })`. Authentication only, not authorization. Inspect with `
|
|
1186
|
+
- **Marketplace first:** `@xano-sdk/auth` registers a complete auth surface — signup/login/me endpoints plus their `user`/`account`/`event_log` tables — via `registerAuth(ws, { canonical: "authn" })`. Authentication only, not authorization. Inspect with `npx @xano/sdk marketplace details @xano-sdk/auth --prompt`.
|
|
1184
1187
|
- **The auth loop end to end** — 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(...)`.
|
|
1185
1188
|
- Signup: `s.db.add({ table: users, row: { email: inp("email"), password: inp("password") } })` — the `f.password()` column hashes on write; take the submission as `input.text()` on signup AND login (see Gotchas on double-hashing).
|
|
1186
1189
|
- Login: `s.db.get({ table: users, fieldName: "email", fieldValue: inp("email"), output: ["id", "password"], as: "u" })` — the `output` naming `password` is REQUIRED (the column is `access: "internal"` and absent from the row otherwise) → `s.precondition({ expr: expr(ref("u", { safe: true }), "!=", c.null()), error: c.text("No such user."), error_type: "notfound" })` → `s.security.check_password({ text_password: inp("password"), hash_password: ref("u.password"), as: "ok" })` → precondition on `ok` → `s.security.create_auth_token({ table: users, id: ref("u.id"), as: "token" })` → `response: { token: ref("token") }`.
|
|
@@ -1319,7 +1322,7 @@ typed against the table's schema as a WRITE shape (a column without
|
|
|
1319
1322
|
(`seed: seedFile("./seed.json", import.meta.url)`; path resolves against the DECLARING
|
|
1320
1323
|
file), or a thunk (`seed: () => import("./seed.json")`, async ok, `.default` unwrapped).
|
|
1321
1324
|
Inline rows are TYPED against the schema at compile time; a `seedFile`/thunk seed is
|
|
1322
|
-
not — `
|
|
1325
|
+
not — `npx @xano/sdk export`/`deploy` validates it, naming the row index and column.
|
|
1323
1326
|
Timestamp seeds: epoch ms, `Date`, ISO 8601 date, or date-time with `Z`/offset; else THROWS.
|
|
1324
1327
|
Int seeds: whole, in int64 (past 2^53: a string).
|
|
1325
1328
|
⚠ Prefer `seedFile` for a file: a thunk's `import()` sits in
|
|
@@ -1738,13 +1741,13 @@ verb, name)`). Committed. A composed entry is keyed by that identity —
|
|
|
1738
1741
|
`query:<group>|<verb>|<name>`, `channel:<server>|<path>`, `message:<server>|<path>|<name>`
|
|
1739
1742
|
— its guid's seed; a legacy `query:<name>` is migrated by the next locked export.
|
|
1740
1743
|
|
|
1741
|
-
- `
|
|
1744
|
+
- `npx @xano/sdk lock rename <kind> <old> <new>` — `kind` is the SDK kind (`table`, `apiGroup`) or stored key (`dbo`).
|
|
1742
1745
|
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.
|
|
1743
1746
|
Reads the `index.ts` beside the lock (or `--entry`); refused while `<old>` is still exported. Composed names go in full; renaming a parent moves them.
|
|
1744
|
-
- `
|
|
1747
|
+
- `npx @xano/sdk lock prune <entry-file> [keys…] --yes` — drops orphaned entries. Finding orphans
|
|
1745
1748
|
RUNS the entry's module scope (env assertions included); `--identity-only --yes <key>…`
|
|
1746
1749
|
prunes named keys (`table:users`) with no evaluation and no orphan check.
|
|
1747
|
-
- `
|
|
1750
|
+
- `npx @xano/sdk lock import <live-bundle.json> [--yes]` — seed the lock from a `workspace export`
|
|
1748
1751
|
to take over an existing workspace (a compiled bundle is refused).
|
|
1749
1752
|
- Every lock subcommand accepts `--lock=<path>`; from outside the lock's directory pass it.
|
|
1750
1753
|
- Merge conflict: keep both sides; two keys on one guid → `lock rename` onto the kept
|
package/llms.txt
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# xanosdk v1.0.
|
|
1
|
+
# xanosdk v1.0.14
|
|
2
2
|
|
|
3
3
|
> TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
|
|
4
4
|
|
|
@@ -6,8 +6,8 @@ Xano is one platform to build, run and govern AI-built software: one WORKSPACE
|
|
|
6
6
|
serves a managed PostgreSQL database, HTTP APIs, background tasks, realtime
|
|
7
7
|
websocket channels, AI agents, MCP servers, file storage and redis. This SDK
|
|
8
8
|
authors it in TypeScript — typed def objects registered on a
|
|
9
|
-
`workspace(name)` — compiled to one importable bundle by `
|
|
10
|
-
./xano/index.ts`, shipped live by `
|
|
9
|
+
`workspace(name)` — compiled to one importable bundle by `npx @xano/sdk export
|
|
10
|
+
./xano/index.ts`, shipped live by `deploy`.
|
|
11
11
|
|
|
12
12
|
Def modules execute at BUILD time only: `s.*` factories return data, and the engine
|
|
13
13
|
runs the compiled stack per request — statements in order, a statement's `as:`
|
|
@@ -41,7 +41,7 @@ plain file read resolves them at the version you have.
|
|
|
41
41
|
- [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
|
|
42
42
|
- [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, tool, or addon — and for the `response` and `expr` shapes every one of them uses.
|
|
43
43
|
- [Consuming defs from a client](llms/client.md): Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
|
|
44
|
-
- [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `
|
|
44
|
+
- [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `npx @xano/sdk marketplace`.
|
|
45
45
|
- [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
|
|
46
46
|
- [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
|
|
47
47
|
- [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when building an MCP server (tools, prompts, resources) or an `agent()`.
|
|
@@ -112,7 +112,7 @@ export default workspace("my-blog")
|
|
|
112
112
|
.registerQueries([createPost, listPosts]);
|
|
113
113
|
```
|
|
114
114
|
|
|
115
|
-
Compile: `
|
|
115
|
+
Compile: `npx @xano/sdk export ./index.ts --out bundle.json` (or `writeBundle(app, path)`
|
|
116
116
|
from `@xano/sdk/node` in code). The default export must be the `Xano` registry. The entry must be an
|
|
117
117
|
ES module (Xano SDK defs are ESM-only): set `"type": "module"` in the nearest
|
|
118
118
|
package.json or name the entry `.mts`. `npm init -y` writes `"type": "commonjs"`,
|
|
@@ -120,7 +120,7 @@ which fails with a "must be ES modules" error until you switch it to module.
|
|
|
120
120
|
|
|
121
121
|
Set `canonical` on every `apiGroup`. The engine mints the URL token server-side, so
|
|
122
122
|
without one a group's client paths are unresolvable until a lock exists: the bundle
|
|
123
|
-
exports fine and `
|
|
123
|
+
exports fine and `npx @xano/sdk routes` / `getPath()` then fail on the very queries it just
|
|
124
124
|
built. An explicit `canonical` resolves them from the source alone.
|
|
125
125
|
⚠ A canonical is unique across the whole INSTANCE, not per workspace — two
|
|
126
126
|
workspaces cannot serve the same one, and no flag shares it. One set in code is a PIN:
|
|
@@ -134,8 +134,8 @@ operand, a `ref()` nothing binds). Each has a legitimate use, so each only warns
|
|
|
134
134
|
but nothing fails on a message no one reads, so in CI and in unattended agent builds
|
|
135
135
|
pass `--strict` (`emitBundle(app, { strict: true })` / `app.export({ strict: true })`):
|
|
136
136
|
every warning becomes a hard failure. Same bundle bytes either way.
|
|
137
|
-
Before calling the work done: `npm run typecheck`, `
|
|
138
|
-
`
|
|
137
|
+
Before calling the work done: `npm run typecheck`, `npx @xano/sdk export <entry> --strict`,
|
|
138
|
+
`deploy <entry>`, then `test run-all` against what deployed.
|
|
139
139
|
|
|
140
140
|
Identity: object guids derive from `(type, name)` — a query's from `(api group,
|
|
141
141
|
verb, name)` — so renames change identity.
|
|
@@ -144,15 +144,15 @@ BESIDE THE ENTRY FILE — `xano/xano.lock` for the standard scaffold,
|
|
|
144
144
|
NOT the project root — which you COMMIT (`--no-lock` opts out; CI guard
|
|
145
145
|
`--frozen-lock` fails instead of changing it).
|
|
146
146
|
To rename an object: rename in code, export (stderr prints the exact fix-up), run
|
|
147
|
-
`
|
|
147
|
+
`npx @xano/sdk lock rename <kind> <old> <new>`, export again — the original guid is emitted
|
|
148
148
|
under the new name, so the engine renames in place instead of delete+create. Taking
|
|
149
|
-
over an existing workspace: `
|
|
149
|
+
over an existing workspace: `npx @xano/sdk lock import <live-bundle.json>` first, then
|
|
150
150
|
export. Pruning, programmatic seeding, and which commands write the lock:
|
|
151
151
|
`llms/lock.md`.
|
|
152
152
|
|
|
153
153
|
## Deploy
|
|
154
154
|
|
|
155
|
-
`
|
|
155
|
+
Commands here run as `npx @xano/sdk <cmd>`: `init` → `deploy` → URL. A deploy runs the same compile pipeline as
|
|
156
156
|
`export` (honoring `xano.lock`), imports the result, and prints the URL.
|
|
157
157
|
⚠ Every deploy is a FULL REPLACE of its destination — objects AND records.
|
|
158
158
|
|
|
@@ -168,7 +168,7 @@ and a `tenant:` only if throwaway (`standard`/`run` refused).
|
|
|
168
168
|
|
|
169
169
|
**Destinations** — the Xano Engine by default, real only when you say so:
|
|
170
170
|
|
|
171
|
-
- `
|
|
171
|
+
- `deploy [source]` → the Xano Engine on this machine (no account). `--ephemeral` → a NAMED, auto-expiring ephemeral (~1h; `--expires-hours`
|
|
172
172
|
1–24), tracked in `./.xano/ephemeral.json`, so deploying again REFRESHES it at the same
|
|
173
173
|
URL; if it expired or was swept, a fresh one is created and the new URL called out.
|
|
174
174
|
⚠ Only the BACKEND URL survives a refresh — the replace clears static hosting, so
|
|
@@ -176,17 +176,17 @@ and a `tenant:` only if throwaway (`standard`/`run` refused).
|
|
|
176
176
|
(not under `--keep-data`, which MERGES an env a deploy filled: rows kept, no re-seed,
|
|
177
177
|
removed objects deleted; ⚠ a rename loses values, a RETYPE reads unfit ones as null, env
|
|
178
178
|
VALUES are not applied, a table trigger refuses it — `--reset` replaces and re-seeds).
|
|
179
|
-
- `
|
|
179
|
+
- `release create <name>` cuts from a running source and LANDS in your workspace
|
|
180
180
|
— the record that it came up, and the only thing `promote`/`tenant deploy` take. A
|
|
181
181
|
taken name is refused, and so is one that addresses a LOCATION instead of naming: `/`,
|
|
182
182
|
`\`, `:`, or a leading `.`. Every export derives its FILENAME from the name it is given,
|
|
183
183
|
so `release|ephemeral|workspace export` refuse those same shapes unless `--path` names
|
|
184
184
|
the file. Carries EVERY table's SCHEMA either way; `--seed[=<guids>]` adds
|
|
185
|
-
ROWS — guids from `
|
|
186
|
-
- `
|
|
185
|
+
ROWS — guids from `tables <backend>`; a redeploy KEEPS them.
|
|
186
|
+
- `release transfer <name> --to-profile <profile>` copies a release to another
|
|
187
187
|
workspace/instance by CONTENT (tar sha256): identical → reused; same name, other
|
|
188
188
|
bytes → exit 2.
|
|
189
|
-
- `
|
|
189
|
+
- `promote <release>` / `tenant deploy <tenant> <release>` land it.
|
|
190
190
|
`promote` adds a branch; ⚠ its TABLE edits hit live
|
|
191
191
|
(`--allow-shared-schema-changes`). `tenant deploy` REPLACES: DROPS tables it lacks,
|
|
192
192
|
CONVERTS retypes (`--seed`: rows).
|
|
@@ -204,24 +204,24 @@ and a `tenant:` only if throwaway (`standard`/`run` refused).
|
|
|
204
204
|
- Backend SECRETS stay out of the repo: declare the NAME, value empty, in `workspaceConfig({ env })`
|
|
205
205
|
passed to `registerWorkspace()`; the VALUE lives in `xano/.env` — gitignored, kept across a
|
|
206
206
|
pull, read by every build. `--backend-env-file <path>` replaces that default (CI has
|
|
207
|
-
no `xano/.env`), `--env-var KEY=VALUE` beats both, and `
|
|
207
|
+
no `xano/.env`), `--env-var KEY=VALUE` beats both, and `env pull` fills the file from
|
|
208
208
|
a running backend — the only command that writes `xano/.env`.
|
|
209
209
|
⚠ A deploy REPLACES the env set: a declared name with NO value refuses the deploy rather
|
|
210
210
|
than clearing the live one — `--allow-empty-env=NAME` clears it on purpose.
|
|
211
|
-
ONE live value, no deploy: `
|
|
211
|
+
ONE live value, no deploy: `env set NAME` (value on stdin) / `env unset NAME`.
|
|
212
212
|
(`--static-env` is the other one — PUBLIC frontend config.)
|
|
213
213
|
- A DOCUMENTATION token is a secret too, in a SECOND ignored file: source declares only the
|
|
214
214
|
gate — `documentation: { require_token: true }` on `workspaceConfig` or an `apiGroup` — and
|
|
215
215
|
the value lives in `xano/.secrets.json`, keyed by the object it gates. A literal `token`
|
|
216
|
-
FAILS the export. `
|
|
217
|
-
`
|
|
216
|
+
FAILS the export. `pull` writes that file and every build reads it back;
|
|
217
|
+
`secrets fill` MINTS one per gate that has none — a gate you AUTHORED has no value
|
|
218
218
|
to pull. CI, which does not have the file, passes `--secrets-file <path>` or
|
|
219
219
|
`--doc-token "<scope>=<value>"`
|
|
220
220
|
(scope = `workspace`, or the group's NAME).
|
|
221
221
|
⚠ OMISSION IS OPPOSITE PER SCOPE: off `workspaceConfig` the target's gate is left alone;
|
|
222
222
|
off an `apiGroup` it is CLEARED (an absent key there is written as the engine default). An
|
|
223
223
|
unsupplied gate refuses a `deploy` and fails the export for a publishing group.
|
|
224
|
-
- `
|
|
224
|
+
- `deploy --to workspace|tenant:<name>` skips the release flow to merge a LOCAL
|
|
225
225
|
build in, keeping the checks that need one (`--dry-run`, `--prune`, loss warnings) and
|
|
226
226
|
leaving nothing to roll back to. Prefer the release path.
|
|
227
227
|
⚠ Branches scope LOGIC: tables and microservices are shared by EVERY branch, so a
|
|
@@ -230,28 +230,28 @@ and a `tenant:` only if throwaway (`standard`/`run` refused).
|
|
|
230
230
|
⚠ `--replace` CLEARS BY WORKSPACE, NOT BY BRANCH: every non-live branch goes, with the
|
|
231
231
|
saved versions that would restore one — unrecoverable. Refused without
|
|
232
232
|
`--allow-branch-deletion`; `--yes` does not imply it. The default merge leaves them alone.
|
|
233
|
-
- `
|
|
233
|
+
- `workspace reset-tables <entry> --table <guid>` puts NAMED tables back to their
|
|
234
234
|
compiled `table({ seed })` rows, touching no other table. Dry run unless `--write`.
|
|
235
235
|
⚠ ROWS BEFORE LOGIC: rows are workspace-shared like schema, so they reach production when
|
|
236
236
|
applied even while the logic reading them is staged — no ordering makes a half-data change
|
|
237
237
|
atomic. Reset rows FIRST, then `promote`: new rows under old logic break only a feature
|
|
238
238
|
being removed; new logic over old rows breaks the one you are shipping.
|
|
239
|
-
- `
|
|
239
|
+
- `pull` refreshes THIS project from a backend: rewrites decoded files,
|
|
240
240
|
keeps yours, lists and confirms (`--yes`).
|
|
241
|
-
- `
|
|
242
|
-
- `
|
|
241
|
+
- `generate <source>`: the decoded tree ONLY, no project.
|
|
242
|
+
- `status` names the env this project last deployed to, its URL and its expiry.
|
|
243
243
|
|
|
244
|
-
**Frontend wiring.** `--static <dir>` (or `
|
|
244
|
+
**Frontend wiring.** `--static <dir>` (or `publish <dir>`) injects the env's backend URL as
|
|
245
245
|
`window.XANO_HOST` into EVERY html document in the build, before the app bundle runs,
|
|
246
246
|
so the frontend needs no rebuild to target an env. How to read it, local dev, verifying
|
|
247
247
|
the inject, and displaying a stored file: `llms/client.md`.
|
|
248
248
|
⚠ A static host serves its files verbatim, so everything injected is PUBLIC — base
|
|
249
249
|
URLs and publishable keys only, never secrets. Secrets go in backend env, read
|
|
250
250
|
server-side via `env(name)`.
|
|
251
|
-
⚠ `
|
|
251
|
+
⚠ `preflight` uses the deploy credential unless `XANO_VALIDATE_INSTANCE` /
|
|
252
252
|
`XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) are set.
|
|
253
253
|
|
|
254
|
-
**Full CLI surface:** `
|
|
254
|
+
**Full CLI surface:** `npx @xano/sdk <command> --help` — every command, flag, default and accepted
|
|
255
255
|
backend; `manifest.json` carries the same in its `cli` array.
|
|
256
256
|
**Style:** reach statements through the `s` namespace (`s.db.add`, `s.math.add`, …).
|
|
257
257
|
The flat aliases (`dbAdd`, `setVar`, …) are identical in output; prefer `s.*`.
|
|
@@ -430,11 +430,11 @@ Non-obvious authoring rules:
|
|
|
430
430
|
refuses the pair (`export()` warns even unlocked); it is for pinning identity
|
|
431
431
|
across a rename, not for sharing a name.
|
|
432
432
|
- **`export()` vs `emitBundle()` vs `writeBundle()`:** `export()` returns the object,
|
|
433
|
-
`emitBundle()` the JSON, `writeBundle(app, path)` writes `
|
|
433
|
+
`emitBundle()` the JSON, `writeBundle(app, path)` writes `export`'s file. All
|
|
434
434
|
three run the SAME build-time checks, INCLUDING seed validation of a literal `seed: [...]`
|
|
435
435
|
array (row shape, unknown column, coercion, enum membership, the all-or-nothing `id`
|
|
436
436
|
rule). A DEFERRED seed — a thunk (`() => import("./seed.json")`) or `seedFile()` — is
|
|
437
|
-
checked only by the `
|
|
437
|
+
checked only by the `export`/`deploy` CLI path. Only `deploy` ships seed rows.
|
|
438
438
|
- Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O
|
|
439
439
|
import from `@xano/sdk/node`, NOT the browser-safe `@xano/sdk` entry (a frontend
|
|
440
440
|
imports from it; request types come from `routes.gen.ts`). `@xano/sdk/internal` is the
|
|
@@ -442,15 +442,18 @@ Non-obvious authoring rules:
|
|
|
442
442
|
— a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.
|
|
443
443
|
- **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not
|
|
444
444
|
extensionless — the defs compile under `moduleResolution: bundler`. Add the `.js`.
|
|
445
|
-
- **Agents authenticate with env vars — never `
|
|
445
|
+
- **Agents authenticate with env vars — never `npx @xano/sdk login`.** `login` blocks on a
|
|
446
446
|
browser consent no agent can complete. Set all three of `$XANO_INSTANCE_URL`,
|
|
447
447
|
`$XANO_WORKSPACE_ID`, `$XANO_META_TOKEN` and run `deploy`/`promote` directly: no disk, no
|
|
448
448
|
rotation, so it survives repeated runs.
|
|
449
|
+
- Not signed in: ask the human whether they have a Xano account; never guess. No: sign
|
|
450
|
+
them up via https://app.dev.xano.com/.well-known/auth.md; it returns this triple once they confirm by email. Yes: the
|
|
451
|
+
human runs `login`.
|
|
449
452
|
- The triple outranks every other credential (`--config`, `$XANO_PROFILE` and
|
|
450
453
|
`$XANO_REFRESH_TOKEN` included, each named on stderr when displaced). Setting SOME of the
|
|
451
454
|
three is a hard error, so a misspelled secret cannot fall through to whatever credential
|
|
452
455
|
the runner has. An explicit `--profile` against it is a hard error too, not a displacement.
|
|
453
|
-
- On disk: `
|
|
456
|
+
- On disk: `npx @xano/sdk profile add <name> --instance … --workspace-id <n>` reads the token
|
|
454
457
|
from piped stdin, else PROMPTS (a flag would reach the process list); the instance must accept it.
|
|
455
458
|
`auth.json` holds a map of named profiles, selected by `--profile <name>`. The older
|
|
456
459
|
`$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` pair still works but ROTATES: single-use.
|
package/manifest.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xano/sdk",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.14",
|
|
4
4
|
"description": "The official TypeScript SDK for Xano, one platform to build, run and govern AI-built software. Your coding agent writes the backend in TypeScript, you run it on the Xano Engine on your machine, then deploy it to Xano.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"xanosdk",
|