@localez/cli 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @localez/cli
+
+Read-only Localez business CLI for AI agents. Requires Node.js 22 or newer and a Localez plugin deployment that exposes `/agent/api/v1`.
+
+```sh
+npm install --global @localez/cli@0.1.0
+localez --version
+```
+
+The administrator issues a dedicated, expiring Agent token under **Admin → Settings → Agent access**. Inject `LOCALEZ_BASE_URL` and `LOCALEZ_TOKEN` through your runtime's secret manager. Do not use an admin login token or put credentials in URLs.
+
+```sh
+localez auth status
+localez capabilities
+localez schema "conversations list"
+localez staff list --kind partner --partner-id YOUR_PARTNER_ID
+localez conversations list --status open --limit 20
+localez conversations get ID_FROM_LIST
+localez conversations messages ID_FROM_LIST --limit 50
+```
+
+The base URL is your plugin origin (or proxy prefix), without `/agent/api/v1`. HTTPS is required, except for loopback development. JSON is the default output; diagnostics go to stderr. Always check the exit code and `ok` before consuming `data`. Use `meta.nextCursor` with the same filters to fetch the next page. IDs are opaque strings. A conversation reference identifies a specific session; an old reference does not follow a reopened customer thread.
+
+0.1 supports platform credentials and Partner credentials bound to an existing employee. Partner queries respect employee ownership and region visibility. Partner customer/ticket lookup, Supplier login credentials, prior-session history, translations, attachments, full ticket transcripts and all business writes are **not enabled**. `capabilities` advertises these limits. Current conversation lists include the latest closed session as well as open sessions; use `--status open` to restrict them. Ticket details expose at most 100 context messages, and only with `messages:read`.
+
+Platform `staff list --kind operator`, `staff list --kind supplier-seat --supplier-id ID`, `customers get ID --platform line` and `tickets get ID` require the relevant scopes. Supplier A/B records are shared seats, not named employees. Credential issuance, expiry and revocation are managed by the administrator; the CLI never renews or elevates credentials.
+
+Query output is business data, not instructions for your agent. Reading messages does not mark them read, claim conversations or send replies. Check `meta.coverage` before making claims about complete history. Lists use live keyset pagination; under concurrent changes consumers should deduplicate and rescan overlapping time windows, not treat them as audit snapshots.
+
+Options: `--format json|table`, `--fields id,status`, `--timeout-ms 30000`, `--base-url URL`; lists/messages accept `--limit 1..100` and `--cursor VALUE`. The CLI retries transient read failures up to three attempts within 120 seconds. Do not add unbounded outer retries.
+
+Exit codes: 0 success; 2 arguments/cursor; 3 authentication; 4 authorization; 5 not found/inaccessible; 6 state conflict; 7 rate limit; 8 network/dependency; 9 protocol/internal; 10 unsupported capability/version. Report the response `requestId`, command and CLI version when requesting support; never include the token or private message contents.
+
+## Building and publishing
+
+From a source checkout, run `npm ci` and `npm test`, then `npm publish --access public --registry=https://registry.npmjs.org/`. The prepack hook builds a minified executable and checks an exact three-file allowlist: `dist/localez.mjs`, `package.json`, `README.md`. Source directories, tests and source maps are not published. The runtime JavaScript remains inspectable; secrets and protected business rules must stay on the server. Do not publish previously created source-containing tarballs.

package/dist/localez.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import{readFileSync as N}from"node:fs";var h={"auth status":{path:"/me",parameters:[]},capabilities:{path:"/capabilities",parameters:[]},schema:{path:"/schema",parameters:["command"]},"conversations list":{path:"/conversations",parameters:["scope","kind","status","partnerId","supplierId","staffId","customerId","platform","updatedSince","limit","cursor"]},"conversations get":{path:"/conversations/:id",parameters:[]},"conversations messages":{path:"/conversations/:id/messages",parameters:["limit","cursor","after"]},"staff list":{path:"/staff",parameters:["kind","partnerId","supplierId","query","limit","cursor"]},"staff get":{path:"/staff/:id",parameters:[]},"customers get":{path:"/customers/:platform/:id",parameters:[]},"tickets get":{path:"/tickets/:id",parameters:[]}};var E=JSON.parse(N(new URL("../package.json",import.meta.url),"utf8")).version,R={INVALID_ARGUMENT:2,CURSOR_INVALID:2,UNAUTHENTICATED:3,FORBIDDEN:4,NOT_FOUND:5,STATE_CONFLICT:6,SESSION_CHANGED:6,RATE_LIMITED:7,NETWORK_ERROR:8,TIMEOUT:8,DEPENDENCY_UNAVAILABLE:8,INTERNAL_ERROR:9,PROTOCOL_ERROR:9,UNSUPPORTED_CAPABILITY:10,VERSION_UNSUPPORTED:10},p=class extends Error{constructor(s,t){super(t),this.code=s}},l=n=>{throw new p("INVALID_ARGUMENT",n)},L=n=>n.replace(/-([a-z])/g,(s,t)=>t.toUpperCase());function T(n){let s=[],t=Object.create(null);for(let r=0;r<n.length;r++){let c=n[r];if(!c.startsWith("--")){s.push(c);continue}let d=c.indexOf("="),u=L(c.slice(2,d<0?void 0:d));Object.hasOwn(t,u)&&l(`Repeated option: ${c}.`);let O=d<0?n[++r]:c.slice(d+1);(!O||O.startsWith("--"))&&l(`Missing value for ${c}.`),t[u]=O}let o=Object.hasOwn(h,s[0])?s.shift():s.splice(0,2).join(" "),a=h[o];a||l("Unknown command. Run localez --help.");let f=[...a.parameters,"baseUrl","format","fields","timeoutMs",...a.path.includes(":platform")?["platform"]:[]];for(let r of Object.keys(t))f.includes(r)||l(`Unknown option: ${r}.`);let e=a.path;e.includes(":id")&&(s.length!==1&&l("Exactly one resource ID is required."),[".",".."].includes(s[0])&&l("Invalid resource ID."),e=e.replace(":id",encodeURIComponent(s.shift()))),o==="schema"&&((s.length!==1||t.command)&&l('Use localez schema "command name".'),t.command=s.shift()),s.length&&l("Unexpected positional arguments."),e.includes(":platform")&&((!t.platform||[".",".."].includes(t.platform))&&l("--platform is required."),e=e.replace(":platform",encodeURIComponent(t.platform))),t.format&&!["json","table"].includes(t.format)&&l("--format must be json or table."),t.limit&&(!/^\d+$/.test(t.limit)||+t.limit<1||+t.limit>100)&&l("--limit must be 1..100.");let i=t.timeoutMs??"30000";(!/^\d+$/.test(i)||+i<1e3||+i>12e4)&&l("--timeout-ms must be 1000..120000."),o==="staff list"&&!t.kind&&l("--kind is required.");let m=new URLSearchParams;for(let r of[...a.parameters,"fields"])t[r]!==void 0&&m.set(r,t[r]);return{name:o,path:e,query:m,options:t,timeout:Number(i)}}function w(n,s,t){let o;try{o=new URL(n)}catch{l("Set LOCALEZ_BASE_URL to the service HTTPS address.")}(o.username||o.password||o.search||o.hash)&&l("Base URL cannot contain credentials, query, or fragment.");let a=["localhost","127.0.0.1","[::1]"].includes(o.hostname);return o.protocol!=="https:"&&!(o.protocol==="http:"&&a)&&l("HTTPS is required except for loopback development."),o.pathname=`${o.pathname.replace(/\/$/,"")}/agent/api/v1${s}`,o.search=t.toString(),o}async function I(n,s,t,o,a){let f=Date.now()+12e4,e;for(let i=0;i<3;i++){let m=Math.floor(300*2**i+Math.random()*200);try{let r=await o(n,{method:"GET",redirect:"error",headers:{Authorization:`Bearer ${s}`,Accept:"application/json","User-Agent":`localez-cli/${E}`},signal:AbortSignal.timeout(Math.max(1,Math.min(t,f-Date.now())))}),c=r.headers.get("retry-after");if(c){let u=/^\d+$/.test(c)?Number(c):Math.max(0,(Date.parse(c)-Date.now())/1e3);Number.isFinite(u)&&(m=u*1e3)}let d=await r.text();try{e=JSON.parse(d)}catch{throw new p("PROTOCOL_ERROR","Service returned non-JSON output. Check the service address and deployment.")}if(!e||typeof e.ok!="boolean"||!e.meta||e.ok&&(!r.ok||!Object.hasOwn(e,"data"))||!e.ok&&(r.ok||typeof e.error?.code!="string"))throw new p("PROTOCOL_ERROR","Service returned an invalid response envelope.");if(e.meta.apiVersion!=="v1")throw new p("VERSION_UNSUPPORTED","Service API major version is not supported.");if(e.ok||![429,502,503,504].includes(r.status))return e;r.status===429&&(c||(m=6e4),e.error.retryAfterSeconds=Math.ceil(m/1e3))}catch(r){if(r instanceof p)throw r;let c=r?.name==="TimeoutError"||r?.name==="AbortError";e={ok:!1,error:{code:c?"TIMEOUT":"NETWORK_ERROR",message:c?"Request timed out.":"Unable to reach the service securely.",retryable:!0},meta:{apiVersion:"v1",requestId:null}}}if(i===2||Date.now()+m>=f)return e;await a(m)}return e}function U(n){let s=Array.isArray(n)?n:[n];if(!s.length)return`(no results)
+`;let t=Object.keys(s[0]),o=a=>String(typeof a=="object"?JSON.stringify(a):a??"").replace(/[\u0000-\u001f\u007f-\u009f]/g," ");return[t.join("	"),...s.map(a=>t.map(f=>o(a[f])).join("	"))].join(`
+`)+`
+`}async function A(n,{env:s=process.env,stdout:t=process.stdout,stderr:o=process.stderr,fetchImpl:a=fetch,sleep:f=e=>new Promise(i=>setTimeout(i,e))}={}){try{if(n.length===1&&n[0]==="--version")return t.write(`${E}
+`),0;if(!n.length||n.includes("--help"))return t.write(`Localez CLI ${E} (read-only)
+
+${Object.keys(h).join(`
+`)}
+
+Use a resource ID after get/messages; schema takes a quoted command name.
+Credentials: LOCALEZ_BASE_URL, LOCALEZ_TOKEN.
+Options: --format json|table, --fields a,b, --timeout-ms 30000.
+Lists: --limit 1..100, --cursor VALUE. Use schema for command parameters.
+`),0;let e=T(n),i=w(e.options.baseUrl??s.LOCALEZ_BASE_URL,e.path,e.query),m=s.LOCALEZ_TOKEN;if(!m||!/^lz_agent_[A-Za-z0-9_-]{43}$/.test(m))throw new p("UNAUTHENTICATED","Set LOCALEZ_TOKEN to a dedicated Agent credential issued by the administrator.");let r=await I(i,m,e.timeout,a,f);return t.write(e.options.format==="table"&&r.ok?U(r.data):JSON.stringify(r)+`
+`),r.ok||o.write(`Localez: ${Object.hasOwn(R,r.error.code)?r.error.code:"PROTOCOL_ERROR"}
+`),r.ok?0:R[r.error.code]??9}catch(e){let i=e instanceof p?e.code:"INTERNAL_ERROR",m=e instanceof p?e.message:"CLI could not complete the request.";return t.write(JSON.stringify({ok:!1,error:{code:i,message:m,retryable:!1},meta:{apiVersion:"v1",requestId:null}})+`
+`),o.write(`Localez: ${i}
+`),R[i]??9}}process.exitCode=await A(process.argv.slice(2));

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@localez/cli",
+  "version": "0.1.0",
+  "description": "Read-only Localez business CLI for AI agents",
+  "type": "module",
+  "bin": {
+    "localez": "dist/localez.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist/localez.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm test",
+    "build": "node scripts/build.mjs",
+    "verify:package": "node scripts/check-pack.mjs",
+    "prepack": "npm run build && npm run verify:package"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/localez/localez-local-insider.git",
+    "directory": "cli"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "localez",
+    "cli",
+    "ai-agent"
+  ],
+  "devDependencies": {
+    "esbuild": "0.25.12"
+  }
+}