@ax-hub/sdk 2.0.0 → 2.1.1

package/README.md

@@ -18,6 +18,48 @@ agent-first Node.js SDK for AX Hub. Designed for Claude, Codex, and other coding
 | use admin/governance APIs | [`@ax-hub/admin-sdk`](../admin-sdk/README.md) |
 | upgrade from 0.x | [Migration & Upgrade](#migration--upgrade) |
 
+## Agent field guide from live QA (2026-06-08)
+
+Use this section when an autonomous agent only has the README and must ship against AX Hub safely.
+
+### 1. Runtime inputs
+
+```bash
+export AX_HUB_PAT="<short-lived PAT>"
+export AX_HUB_TENANT_ID="cc1e58f1-8e46-4ac7-96c1-190c4cdd5b70"   # test tenant
+export AX_HUB_TENANT_SLUG="test"
+```
+
+- PAT auth is `tokenType: 'pat'` and is sent as `X-Api-Key`.
+- JWT auth is `tokenType: 'jwt'` and is sent as `Authorization: Bearer`.
+- Never log the token. Redact env dumps before saving QA artifacts.
+
+### 2. Fastest safe live loop
+
+1. Create a timestamp-suffixed private app in tenant `test`.
+2. Set an env var, list env vars, then delete it and assert it is absent.
+3. Create a table with `owner_id`, `title`, `status`, and optional metadata columns.
+4. Add a column, inspect the table, then delete the column and inspect again.
+5. Add a table grant, list grants, revoke the grant, then assert the same grant id has `revokedAt`.
+6. Insert a row, get it by id, patch it, list it with a filter, count it, browse admin rows, then delete it.
+7. Assert row get after delete returns `404` or `410`.
+8. Delete the table and assert inspect after delete returns `404` or `410`.
+9. Soft-delete the app, then permanent-delete the app.
+
+### 3. Deletion semantics that prevent false positives
+
+- Row delete: prove it by a follow-up `get` returning `404` or `410`.
+- Table delete: prove it by a follow-up `inspect` returning `404` or `410`.
+- Table grant delete: AX Hub currently soft-revokes. `listGrants` can still return the grant, but `revokedAt` must be set. Do not assert hard disappearance.
+- Deploy without git/bootstrap source can return a precondition-style 4xx. That proves error handling, not a deployment failure.
+
+### 4. Production evidence already collected
+
+- Node production mutation suite exercised app/env/comments/likes/table/columns/grants/data/OAuth/publication/deploy/git preconditions with exit `0`.
+- A real app bootstrap/deploy wait succeeded in production: app `d31958ad-4a9b-4dcc-8951-64a1f3060c3d`, deployment `d3a48ce3-0f9c-4bab-aa07-863c31c44460`, final status `succeeded`, followed by app permanent delete.
+- Go, Java, Kotlin, Python, and Ruby each hit 189 generated backend operation facades against the same production `test` tenant with SDK exceptions `0` and backend 5xx `0`.
+- Go, Java, Kotlin, Python, and Ruby each passed the strict destructive DB loop above: 22 live steps, 17 assertions, 7 cleanup calls.
+
 ## Magic Moment
 
 ```ts

package/dist/cli/doctor.cjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-'use strict';var fs=require('fs'),path=require('path');var _documentCurrentScript=typeof document!=='undefined'?document.currentScript:null;function t(e=process.cwd()){let r=[{name:"package.json",ok:fs.existsSync(path.resolve(e,"package.json"))},{name:"codegen/swagger.json",ok:fs.existsSync(path.resolve(e,"codegen/swagger.json"))},{name:"packages/sdk/src/index.ts",ok:fs.existsSync(path.resolve(e,"packages/sdk/src/index.ts"))}];return {ok:r.every(n=>n.ok),checks:r}}if((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('doctor.cjs', document.baseURI).href))===`file://${process.argv[1]}`){let e=t();process.stdout.write(`${JSON.stringify(e,null,2)}
-`),process.exit(e.ok?0:1);}exports.runDoctor=t;
+'use strict';var fs=require('fs'),path=require('path');var _documentCurrentScript=typeof document!=='undefined'?document.currentScript:null;var c=Object.defineProperty;var n=(e,o)=>c(e,"name",{value:o,configurable:true});function a(e=process.cwd()){let o=[{name:"package.json",ok:fs.existsSync(path.resolve(e,"package.json"))},{name:"codegen/swagger.json",ok:fs.existsSync(path.resolve(e,"codegen/swagger.json"))},{name:"packages/sdk/src/index.ts",ok:fs.existsSync(path.resolve(e,"packages/sdk/src/index.ts"))}];return {ok:o.every(t=>t.ok),checks:o}}n(a,"runDoctor");if((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('doctor.cjs', document.baseURI).href))===`file://${process.argv[1]}`){let e=a();process.stdout.write(`${JSON.stringify(e,null,2)}
+`),process.exit(e.ok?0:1);}exports.runDoctor=a;

package/dist/cli/doctor.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import {existsSync}from'fs';import {resolve}from'path';function t(e=process.cwd()){let r=[{name:"package.json",ok:existsSync(resolve(e,"package.json"))},{name:"codegen/swagger.json",ok:existsSync(resolve(e,"codegen/swagger.json"))},{name:"packages/sdk/src/index.ts",ok:existsSync(resolve(e,"packages/sdk/src/index.ts"))}];return {ok:r.every(n=>n.ok),checks:r}}if(import.meta.url===`file://${process.argv[1]}`){let e=t();process.stdout.write(`${JSON.stringify(e,null,2)}
-`),process.exit(e.ok?0:1);}export{t as runDoctor};
+import {existsSync}from'fs';import {resolve}from'path';var c=Object.defineProperty;var n=(e,o)=>c(e,"name",{value:o,configurable:true});function a(e=process.cwd()){let o=[{name:"package.json",ok:existsSync(resolve(e,"package.json"))},{name:"codegen/swagger.json",ok:existsSync(resolve(e,"codegen/swagger.json"))},{name:"packages/sdk/src/index.ts",ok:existsSync(resolve(e,"packages/sdk/src/index.ts"))}];return {ok:o.every(t=>t.ok),checks:o}}n(a,"runDoctor");if(import.meta.url===`file://${process.argv[1]}`){let e=a();process.stdout.write(`${JSON.stringify(e,null,2)}
+`),process.exit(e.ok?0:1);}export{a as runDoctor};