callman-core 1.34.0 → 1.36.0

package/dist/script/pm-api-metadata.js

@@ -1,46 +1,100 @@
 // Canonical, machine-readable description of the `pm.*` scripting surface.
 // Same philosophy as templating/generator-metadata.ts: ONE runtime data
 // structure, colocated with the implementation, consumed by every surface
-// that needs to know "what exists" — today the AI knowledge-pack generator
-// (scripts/generate-ai-packs.mjs), tomorrow the desktop autocomplete.
+// that needs to know "what exists" — the AI knowledge-pack generator
+// (scripts/generate-ai-packs.mjs), the backend AI script prompt, the MCP docs
+// and the desktop `/help` catalog.
 //
-// When a feature module gains/loses a method, update THIS file in the same
-// commit. The CI drift check regenerates ai-packs/ and fails on a diff, so
-// the metadata cannot silently fall behind the docs the AI sees.
+// The TypeScript declarations editors use live in pm-api-declarations.ts; this
+// file is the DOCUMENTATION half (descriptions, examples, stage notes).
+// scripts/check-pm-api-drift.mjs fails CI when a documented `pm.x.y` is not a
+// member of the declared (and therefore real) API, and `npm run ai:packs:check`
+// fails when the generated packs fall behind this file.
+//
+// When a feature module gains/loses a method, update THIS file and
+// pm-api-declarations.ts in the same commit.
+const RESPONSE_STAGES = ["post-response", "tests"];
+const REQUEST_STAGES = ["pre-request", "post-response", "tests"];
 export const PM_API_METADATA = [
+    {
+        name: "pm",
+        description: "The script API. `cm` and `callman` are the SAME object as `pm` — a script can use `cm.` exactly like `pm.` (cm === pm), so Postman scripts run unchanged and Callman-branded scripts behave identically.",
+        members: [
+            {
+                signature: "cm.environment.set(key, value)",
+                description: "`cm.x` and `callman.x` are aliases of `pm.x` for every member below.",
+                example: 'cm.test("ok", () => cm.expect(1).to.equal(1))',
+            },
+        ],
+    },
     {
         name: "pm.test",
-        description: "Register a named test. The callback's assertion failures mark the test failed without aborting the script.",
+        description: "Register a named test. The callback runs synchronously; a failing assertion (or a throw) marks the test failed without aborting the script. Works in pre-request, post-response and tests scripts.",
         members: [
             {
                 signature: "pm.test(name, fn)",
-                description: "Runs fn (sync or async); pass/fail lands in the run's test results.",
+                description: "Runs fn immediately; pass/fail lands in the run's test results. An async fn / returned Promise is awaited before the script is reported.",
+                example: 'pm.test("sum is 4", () => pm.expect(2 + 2).to.equal(4))',
+            },
+            {
+                signature: "pm.test(name, done => { done(); })",
+                description: "Callback-style async test: the test completes when done() is called (done(error) fails it).",
+                example: 'pm.test("later", done => { setTimeout(done, 10); })',
+            },
+            {
+                signature: "pm.test.skip(name)",
+                description: "Record a skipped test (shown as SKIP); the callback, if any, is never run.",
+                example: 'pm.test.skip("not ready yet")',
+            },
+            {
+                signature: "pm.test.index()",
+                description: "Number of tests recorded so far in this script.",
+                example: "pm.test.index()",
             },
         ],
     },
     {
         name: "pm.expect",
-        description: "Chai-style assertions plus Jest-style matchers.",
+        description: "pm.expect is chai 4.4.1 with the full BDD API (expect-style), the chai-postman helpers and a few jest-style aliases. Chain words (to, be, been, is, that, which, and, has, have, with, at, of, same, but, does, still, also) read like English; flags (not, deep, nested, own, ordered, any, all, itself) change the assertion that follows. Equality is strict: .equal / .eq use ===, so NaN does not equal NaN and 1 does not equal \"1\"; use .eql / .deep.equal for structural comparison. Failure messages are chai's own.",
         members: [
             {
-                signature: "pm.expect(value)",
-                description: "Assertion chain. Equality: .to.equal(x) (identity), .to.eql(x) / .to.deep.equal(x) / .toEqual(x) (deep). Existence: .to.exist, .toBeDefined(), .toBeNull(). Strings/arrays: .to.include(x) / .toContain(x), .oneOf([..]). Numbers: .toBeGreaterThan / .toBeLessThan / .to.be.above(n) / .to.be.below(n). Types: .to.be.a('string'|'number'|...). Negation: .to.not.<...> / .not.<matcher>. Properties: .to.have.property('name', value?).",
+                signature: "pm.expect(value, message?)",
+                description: "Start an assertion. Equality: .to.equal(x) (===), .to.eql(x) / .to.deep.equal(x) (deep), .toBe(x) / .toEqual(x) (jest-style). Existence/type: .to.exist, .to.be.null, .to.be.undefined, .to.be.true, .to.be.a('string'|'number'|'array'|'object'|...). Strings/arrays: .to.include(x) / .to.contain(x) / .toContain(x), .to.have.lengthOf(n), .to.be.empty, .to.match(/re/), .to.have.members([...]), .to.be.oneOf([...]). Numbers: .to.be.above(n) / .below(n) / .within(a, b) / .closeTo(n, delta) / .toBeGreaterThan(n) / .toBeLessThan(n). Objects: .to.have.property('a.b', value?) (dot paths work by default), .to.have.all.keys('a', 'b'), .to.have.jsonSchema(schema). Negation: .to.not.<assertion>.",
+                example: 'pm.expect(user.id).to.be.a("number")',
+            },
+            {
+                signature: "pm.expect.fail(message?)",
+                description: "Throws an AssertionError (fails the surrounding test) immediately.",
+                example: 'pm.expect.fail("unexpected branch")',
+            },
+            {
+                signature: "pm.expect(value).to.have.jsonSchema(schema, ajvOptions?)",
+                description: "Validate any value against a JSON Schema (ajv). Also available on the response as pm.response.to.have.jsonSchema(schema) in post-response scripts.",
+                example: 'pm.expect(user).to.have.jsonSchema({ type: "object", required: ["id"] })',
             },
-            { signature: "pm.expect.fail(message?)", description: "Fails the surrounding test immediately." },
         ],
     },
     {
         name: "pm.environment",
-        description: "Active environment variables (alias: pm.env). Writes are scoped to the run and surface as variable mutations.",
+        description: "Active environment variables (alias: pm.env). get() returns the value as it was set within the run (numbers and objects stay native); stored values are strings, objects/arrays are saved as JSON. Writes surface as variable mutations.",
         members: [
-            { signature: "pm.environment.get(key)", description: "Read a variable (string or undefined)." },
-            { signature: "pm.environment.set(key, value)", description: "Write a variable for subsequent steps." },
+            { signature: "pm.environment.get(key)", description: "Read a variable (undefined when missing).", example: 'pm.environment.get("baseUrl")' },
+            {
+                signature: "pm.environment.set(key, value, type?)",
+                description: "Write a variable for subsequent steps. type is one of string, number, boolean, json, any.",
+                example: 'pm.environment.set("token", token)',
+            },
             { signature: "pm.environment.unset(key)", description: "Remove a variable." },
             { signature: "pm.environment.has(key)", description: "true when the key exists." },
             { signature: "pm.environment.clear()", description: "Remove every variable in the scope." },
             { signature: "pm.environment.toObject()", description: "Plain { key: value } snapshot." },
-            { signature: "pm.environment.replaceIn(template)", description: "Resolve {{tokens}} inside a string." },
+            {
+                signature: "pm.environment.replaceIn(template)",
+                description: "Resolve {{tokens}} against THIS scope only. Unresolved {{x}} stay as written (literal); objects and arrays are walked.",
+                example: 'pm.environment.replaceIn("{{baseUrl}}/users")',
+            },
             { signature: "pm.environment.name", description: "Active environment's name." },
+            { signature: "pm.environment.values", description: "The raw string values record (read-only view)." },
         ],
     },
     {
@@ -48,189 +102,328 @@ export const PM_API_METADATA = [
         description: "Workspace-level global variables. Same surface as pm.environment.",
         members: [
             { signature: "pm.globals.get(key)", description: "Read a global." },
-            { signature: "pm.globals.set(key, value)", description: "Write a global for the run." },
+            { signature: "pm.globals.set(key, value, type?)", description: "Write a global for the run." },
             { signature: "pm.globals.unset(key)", description: "Remove a global." },
             { signature: "pm.globals.has(key)", description: "true when the key exists." },
             { signature: "pm.globals.clear()", description: "Remove every global in the scope." },
             { signature: "pm.globals.toObject()", description: "Plain snapshot." },
-            { signature: "pm.globals.replaceIn(template)", description: "Resolve {{tokens}} inside a string." },
+            { signature: "pm.globals.replaceIn(template)", description: "Resolve {{tokens}} against the globals; unresolved tokens stay literal." },
+            { signature: "pm.globals.name", description: "Scope name." },
+            { signature: "pm.globals.values", description: "The raw string values record (read-only view)." },
         ],
     },
     {
         name: "pm.collectionVariables",
-        description: "Collection-scoped variables that survive across requests within one collection run iteration.",
+        description: "Collection-scoped variables that survive across requests within one collection run. `{{name}}` resolves them after the environment and before globals.",
         members: [
             { signature: "pm.collectionVariables.get(key)", description: "Read a collection variable." },
-            { signature: "pm.collectionVariables.set(key, value)", description: "Write; persists across the iteration." },
+            { signature: "pm.collectionVariables.set(key, value, type?)", description: "Write; persists across the iteration." },
             { signature: "pm.collectionVariables.unset(key)", description: "Remove a collection variable." },
             { signature: "pm.collectionVariables.has(key)", description: "true when the key exists." },
             { signature: "pm.collectionVariables.clear()", description: "Remove all collection variables." },
             { signature: "pm.collectionVariables.toObject()", description: "Plain snapshot." },
-            { signature: "pm.collectionVariables.replaceIn(template)", description: "Resolve {{tokens}}." },
+            { signature: "pm.collectionVariables.replaceIn(template)", description: "Resolve {{tokens}}; unresolved tokens stay literal." },
+            { signature: "pm.collectionVariables.name", description: "Scope name." },
+            { signature: "pm.collectionVariables.values", description: "The raw string values record (read-only view)." },
         ],
     },
     {
         name: "pm.variables",
-        description: "Layered read across all scopes (per-iteration > environment > globals) plus template resolution.",
+        description: "Layered read across all scopes — local > iteration data > environment > collection > globals. `set` writes the local scope, shared by every script of the same request (collection → folder → request) and gone afterwards.",
         members: [
-            { signature: "pm.variables.get(key)", description: "Read through the precedence chain." },
-            { signature: "pm.variables.set(key, value)", description: "Write to the run-local layer." },
+            { signature: "pm.variables.get(key)", description: "Read through the precedence chain.", example: 'pm.variables.get("userId")' },
+            { signature: "pm.variables.set(key, value, type?)", description: "Write to the run-local layer." },
             { signature: "pm.variables.unset(key)", description: "Remove from the run-local layer." },
             { signature: "pm.variables.has(key)", description: "true when any layer has the key." },
+            { signature: "pm.variables.clear()", description: "Clear the run-local layer." },
             { signature: "pm.variables.toObject()", description: "Merged snapshot." },
-            { signature: "pm.variables.replaceIn(template)", description: "Resolve {{tokens}} in a string." },
+            {
+                signature: "pm.variables.replaceIn(template)",
+                description: "Postman semantics: resolve {{tokens}} (and dynamic variables like {{$guid}}); an unresolved {{x}} stays as written; objects and arrays are walked.",
+                example: 'pm.variables.replaceIn("{{baseUrl}}/users/{{userId}}")',
+            },
             {
                 signature: "pm.variables.resolve(template)",
-                description: "Like replaceIn, but also resolves scenario node-output references.",
+                description: "Callman's older resolver: like replaceIn on a string, but an unresolved {{x}} becomes an empty string. Does NOT read scenario node outputs — use pm.node(label) for those.",
+                example: 'pm.variables.resolve("{{missing}}")',
             },
         ],
     },
+    {
+        name: "pm.iterationData",
+        description: "The data-file / dataset row of the current iteration of a data-driven run (empty outside one). Also a layer of pm.variables.",
+        members: [
+            { signature: "pm.iterationData.get(key)", description: "Read a column of the current row.", example: 'pm.iterationData.get("email")' },
+            { signature: "pm.iterationData.has(key)", description: "true when the row has the column." },
+            { signature: "pm.iterationData.toObject()", description: "The whole row as a plain object." },
+            { signature: "pm.iterationData.toJSON()", description: "Same as toObject(); used by JSON.stringify." },
+            { signature: "pm.iterationData.set(key, value)", description: "Change this run's copy of the row (not written back to the data file)." },
+            { signature: "pm.iterationData.unset(key)", description: "Remove a column from this run's copy of the row." },
+            { signature: "pm.iterationData.clear()", description: "Remove every column from this run's copy of the row." },
+            { signature: "pm.iterationData.replaceIn(template)", description: "Resolve {{tokens}} against the row only." },
+        ],
+    },
     {
         name: "pm.request",
-        description: "The outgoing request. Mutations only have effect in pre-request scripts (the call has not fired yet).",
+        description: "The request. Its url is a postman-collection Url object that ALSO behaves like a string (url.includes('/v1'), url + '?x=1'); headers is a HeaderList (case-insensitive get/has/add/upsert/remove, bracket access headers['X-Id']). Mutations only have effect in pre-request scripts (the call has not fired yet).",
         members: [
-            { signature: "pm.request.url", description: "Resolved URL string." },
-            { signature: "pm.request.method", description: "HTTP method." },
-            { signature: "pm.request.body", description: "Body snapshot (mode + content)." },
-            { signature: "pm.request.headers", description: "HeaderList: .all() .get(name) .has(name) .add({key,value}) .upsert({key,value}) .remove(name) .idx(i)." },
-            { signature: "pm.request.query", description: "Query params as a HeaderList." },
-            { signature: "pm.request.getHeader(name)", description: "Read one header value." },
-            { signature: "pm.request.setHeader(name, value)", description: "Set/replace a header.", stages: ["pre-request", "scenario-script"] },
-            { signature: "pm.request.unsetHeader(name)", description: "Remove a header.", stages: ["pre-request", "scenario-script"] },
+            { signature: "pm.request.url", description: "Url object: .getHost() .getPath() .getPathWithQuery() .getQueryString() .getRaw() .protocol .host[] .port .path[] .hash .query (list of params) .variables .addQueryParams() .removeQueryParams() .update(); also usable as a string. Assign a string to replace it." },
+            { signature: "pm.request.url.query.get(key)", description: "Value of a query param.", example: 'pm.request.url.query.get("page")' },
+            { signature: "pm.request.url.query.add(param)", description: "Add a query param ({ key, value }).", stages: ["pre-request"], example: 'pm.request.url.query.add({ key: "debug", value: "1" })' },
+            { signature: "pm.request.method", description: "HTTP method string; assignable in pre-request." },
+            {
+                signature: "pm.request.body",
+                description: "RequestBody: .mode ('raw'|'urlencoded'|'formdata'|'file'|'graphql') .raw .urlencoded .formdata .graphql .isEmpty() .toString() .update({ mode, raw }).",
+                example: 'pm.request.body.update({ mode: "raw", raw: JSON.stringify({ a: 1 }) })',
+            },
+            {
+                signature: "pm.request.headers",
+                description: "HeaderList: .get(name) .has(name) .add({key,value}) .upsert({key,value}) .remove(name) .each(fn) .map(fn) .filter(fn) .find(fn) .count() .toObject(); bracket access reads/writes by name.",
+                example: 'pm.request.headers.upsert({ key: "X-Trace", value: pm.variables.replaceIn("{{$guid}}") })',
+            },
+            { signature: "pm.request.query", description: "Callman alias of pm.request.url.query (the query params list)." },
+            { signature: "pm.request.getHeader(name)", description: "Read one header value (case-insensitive)." },
+            { signature: "pm.request.setHeader(name, value)", description: "Set/replace a header.", stages: ["pre-request"] },
+            { signature: "pm.request.unsetHeader(name)", description: "Remove a header.", stages: ["pre-request"] },
             { signature: "pm.request.getQueryParam(name)", description: "Read one query param." },
-            { signature: "pm.request.setQueryParam(name, value)", description: "Set/replace a query param.", stages: ["pre-request", "scenario-script"] },
-            { signature: "pm.request.unsetQueryParam(name)", description: "Remove a query param.", stages: ["pre-request", "scenario-script"] },
-            { signature: "pm.request.setUrl(url)", description: "Replace the URL.", stages: ["pre-request", "scenario-script"] },
-            { signature: "pm.request.setMethod(method)", description: "Replace the method.", stages: ["pre-request", "scenario-script"] },
-            { signature: "pm.request.setRawBody(value)", description: "Replace the raw body (string or object → JSON).", stages: ["pre-request", "scenario-script"] },
+            { signature: "pm.request.setQueryParam(name, value)", description: "Set/replace a query param.", stages: ["pre-request"] },
+            { signature: "pm.request.unsetQueryParam(name)", description: "Remove a query param.", stages: ["pre-request"] },
+            { signature: "pm.request.setUrl(url)", description: "Replace the URL.", stages: ["pre-request"] },
+            { signature: "pm.request.setMethod(method)", description: "Replace the method.", stages: ["pre-request"] },
+            { signature: "pm.request.setRawBody(value)", description: "Replace the body with raw text (objects are NOT auto-stringified; pass JSON.stringify(obj)).", stages: ["pre-request"] },
+            { signature: "pm.request.to.have.header(name)", description: "chai-postman assertions work on the request too (pm.request.to.have.header, .to.have.body, ...)." },
         ],
     },
     {
         name: "pm.response",
-        description: "The received response. Not available in pre-request scripts.",
+        description: "The received response — a postman-collection Response. Not available in pre-request scripts. pm.response.code is the NUMBER (200); pm.response.status is the reason PHRASE ('OK', 'Not Found') exactly like Postman, so `pm.response.status === 200` is false.",
         members: [
-            { signature: "pm.response.code", description: "Status code (number).", stages: ["post-response", "tests", "scenario-script"] },
-            { signature: "pm.response.status", description: "Status code (number, alias).", stages: ["post-response", "tests", "scenario-script"] },
-            { signature: "pm.response.statusText", description: "Status text.", stages: ["post-response", "tests", "scenario-script"] },
-            { signature: "pm.response.json()", description: "Parsed JSON body — call once into a const (`const body = pm.response.json()`); throws on non-JSON, so guard with try/catch or pm.response.to.be.json when the content type is uncertain.", stages: ["post-response", "tests", "scenario-script"] },
-            { signature: "pm.response.text()", description: "Raw body as string.", stages: ["post-response", "tests", "scenario-script"] },
-            { signature: "pm.response.rawBody", description: "Raw body string.", stages: ["post-response", "tests", "scenario-script"] },
-            { signature: "pm.response.headers", description: "Response HeaderList.", stages: ["post-response", "tests", "scenario-script"] },
-            { signature: "pm.response.responseTime", description: "Duration in ms.", stages: ["post-response", "tests", "scenario-script"] },
-            { signature: "pm.response.responseSize", description: "Body size in bytes.", stages: ["post-response", "tests", "scenario-script"] },
+            { signature: "pm.response.code", description: "Status code (number).", stages: RESPONSE_STAGES, example: "pm.expect(pm.response.code).to.equal(200)" },
+            { signature: "pm.response.status", description: "Status reason phrase (string), e.g. \"OK\". Use pm.response.code for the number.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.reason()", description: "Reason phrase (method form of status).", stages: RESPONSE_STAGES },
+            { signature: "pm.response.statusText", description: "Callman alias of pm.response.reason().", stages: RESPONSE_STAGES },
+            {
+                signature: "pm.response.json()",
+                description: "Parse the body as JSON — call it once into a const. THROWS when the body is empty or not valid JSON (guard with try/catch, or assert pm.response.to.be.json first). Optional reviver as in JSON.parse.",
+                stages: RESPONSE_STAGES,
+                example: "const body = pm.response.json()",
+            },
+            { signature: "pm.response.text()", description: "Raw body as a string.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.jsonp(callbackName?)", description: "Parse a JSONP body; throws when it is not valid.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.rawBody", description: "Raw body string (Callman alias of text()).", stages: RESPONSE_STAGES },
+            { signature: "pm.response.body", description: "Callman: the parsed body (JSON value, or the text). Prefer json() / text().", stages: RESPONSE_STAGES },
+            { signature: "pm.response.headers", description: "Response HeaderList (read-only): .get(name) .has(name) .each(fn) .toObject(); bracket access headers['content-type'].", stages: RESPONSE_STAGES, example: 'pm.response.headers.get("Content-Type")' },
+            { signature: "pm.response.cookies", description: "CookieList of the response's Set-Cookie headers: .get(name) .has(name) .toObject() .each(fn).", stages: RESPONSE_STAGES },
+            { signature: "pm.response.responseTime", description: "Duration in ms.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.responseSize", description: "Body size in bytes.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.size()", description: "{ body, header, total } sizes in bytes.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.dataURI()", description: "The body as a data: URI.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.details()", description: "{ code, name, detail } of the status code.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.contentInfo()", description: "{ mimeType, mimeFormat, charset, fileExtension, contentType } of the body.", stages: RESPONSE_STAGES },
+            { signature: "pm.response.stream", description: "Body bytes as a Buffer.", stages: RESPONSE_STAGES },
             {
-                signature: "pm.response.to.have.status(code)",
-                description: "Assertion shortcuts; also .to.have.header/.jsonBody/.body and .to.be.ok/.json/.success/.clientError/... plus .to.not.<predicate>.",
-                stages: ["post-response", "tests", "scenario-script"],
+                signature: "pm.response.to.have.status(codeOrReason)",
+                description: "chai-postman assertions on the response: .to.have.status(200 | \"OK\"), .to.have.header(name, value?), .to.have.body(text?), .to.have.jsonBody(path?, value?), .to.have.jsonSchema(schema), .to.have.responseTime.below(ms), .to.be.ok / .success / .info / .redirection / .clientError / .serverError / .error / .json / .html / .xml / .withBody / .accepted / .badRequest / .unauthorized / .forbidden / .notFound / .rateLimited, plus .to.not.<predicate>.",
+                stages: RESPONSE_STAGES,
+                example: 'pm.response.to.have.status(200)',
             },
         ],
     },
     {
         name: "pm.sendRequest",
-        description: "Fire an ad-hoc HTTP request from inside a script.",
+        description: "Fire an ad-hoc HTTP request from inside a script. It returns a Promise that resolves to a Response with the same API as pm.response (code, status, json(), text(), headers, cookies, responseTime, ...). The callback form (err, res) also works; hosts that keep a cookie jar send and store cookies.",
         members: [
             {
-                signature: "pm.sendRequest(urlOrOptions, callback?)",
-                description: "Options: { url, method, header: {name: value}, body }. Body accepts a plain object (auto-JSON) OR Postman style { mode: 'raw', raw: JSON.stringify({...}) } / { mode: 'urlencoded', urlencoded: [{key, value}] }. Prefer `const res = await pm.sendRequest({...})`; callback form gets (err, res). The response object is { code, status, statusText, headers, body, responseTime, json(), text() } — note it is NOT pm.response.",
+                signature: "pm.sendRequest(url)",
+                description: "GET a URL string. Prefer `const res = await pm.sendRequest(...)`.",
+                example: 'const res = await pm.sendRequest("https://api.example.com/health")',
+            },
+            {
+                signature: "pm.sendRequest({ url, method, header, body })",
+                description: "Request options. header: object, array of { key, value } or a header string. body: a string, or { mode: 'raw', raw }, { mode: 'urlencoded', urlencoded: [{key,value}] }, { mode: 'formdata', formdata: [{key,value}] } (text parts only), { mode: 'graphql', graphql: { query, variables } }. {{variables}} in all fields are resolved.",
+                example: 'await pm.sendRequest({ url: "https://x.test/login", method: "POST", header: { "Content-Type": "application/json" }, body: { mode: "raw", raw: JSON.stringify({ user: "a" }) } })',
+            },
+            {
+                signature: "pm.sendRequest(request, (err, res, history) => {})",
+                description: "Callback form; request may also be a postman-collection Request (new (require('postman-collection').Request)({...})).",
+                example: 'pm.sendRequest("https://x.test", (err, res) => { pm.environment.set("code", res.code) })',
             },
         ],
     },
+    {
+        name: "pm.cookies",
+        description: "Cookies of the current request's domain (a CookieList: .get(name) .has(name) .toObject() .each(fn)), plus the cookie jar of ANY domain via pm.cookies.jar().",
+        members: [
+            { signature: "pm.cookies.get(name)", description: "Value of a cookie of the request's domain.", example: 'pm.cookies.get("session")' },
+            { signature: "pm.cookies.has(name)", description: "true when the cookie exists." },
+            { signature: "pm.cookies.toObject()", description: "{ name: value } of the request's domain." },
+            { signature: "pm.cookies.jar()", description: "The cookie jar. Every jar method takes a callback (error, result) OR returns a Promise.", example: 'const jar = pm.cookies.jar()' },
+            { signature: "pm.cookies.jar().set(url, name, value)", description: "Set a cookie (or pass a { name, value, domain, path, expires, httpOnly, secure } object instead of name, value).", example: 'await pm.cookies.jar().set("https://x.test", "theme", "dark")' },
+            { signature: "pm.cookies.jar().get(url, name)", description: "Value of one cookie, or null.", example: 'await pm.cookies.jar().get("https://x.test", "theme")' },
+            { signature: "pm.cookies.jar().getAll(url)", description: "All cookies matching the url (Cookie objects).", example: 'await pm.cookies.jar().getAll("https://x.test")' },
+            { signature: "pm.cookies.jar().unset(url, name)", description: "Delete one cookie." },
+            { signature: "pm.cookies.jar().clear(url)", description: "Delete every cookie of the url's domain." },
+        ],
+    },
+    {
+        name: "pm.visualizer",
+        description: "Render a custom view of the response: pass a Handlebars HTML template and its data; the host shows it in the Visualize tab (the last call wins). Data must be JSON-serializable.",
+        members: [
+            {
+                signature: "pm.visualizer.set(template, data, options?)",
+                description: "template: Handlebars HTML string; data: object available as {{...}} in the template; options: Handlebars compile options.",
+                stages: RESPONSE_STAGES,
+                example: 'pm.visualizer.set("<ul>{{#each items}}<li>{{name}}</li>{{/each}}</ul>", { items: pm.response.json() })',
+            },
+            { signature: "pm.visualizer.clear()", description: "Remove the visualization set earlier in the run.", stages: RESPONSE_STAGES },
+            {
+                signature: "pm.getData(callback)",
+                description: "Inside a visualizer template script: receive the data passed to pm.visualizer.set as callback(error, data).",
+                stages: RESPONSE_STAGES,
+                example: "pm.getData((error, data) => { console.log(data) })",
+            },
+        ],
+    },
+    {
+        name: "require",
+        description: "require(name) and pm.require(name) load one of the built-in libraries (Postman's list). There is no filesystem or package access: `npm:`, `jsr:` and `@team/` specifiers and any other name throw \"Cannot find module\". The `node:` prefix is accepted.",
+        members: [
+            { signature: "require(name)", description: "Built-in modules: lodash, moment, chai, ajv (v6), cheerio (0.22), xml2js, uuid, csv-parse/lib/sync, postman-collection, crypto-js, tv4, atob, btoa, path, assert, buffer, util, url, querystring, string_decoder, stream, events, punycode, timers.", example: 'const moment = require("moment")' },
+            { signature: "pm.require(name)", description: "Same as require(name).", example: 'const _lodash = pm.require("lodash")' },
+            { signature: "require('uuid').v4()", description: "Random UUID v4 string.", example: 'const id = require("uuid").v4()' },
+            { signature: "require('csv-parse/lib/sync')(input, options?)", description: "Parse CSV text into an array of rows.", example: 'require("csv-parse/lib/sync")(csv, { columns: true })' },
+            { signature: "require('xml2js').parseString(xml, callback)", description: "Parse XML into a JS object (also parseStringPromise).", example: 'require("xml2js").parseString(xmlText, (err, result) => {})' },
+            { signature: "require('cheerio').load(html)", description: "Parse HTML and query it with jQuery-style selectors (cheerio 0.22).", example: 'const $ = require("cheerio").load(htmlText)' },
+        ],
+    },
+    {
+        name: "console",
+        description: "The full console API. Output appears in the run's Console and is streamed while the script runs (kept even when the script times out). Format strings %s %d %i %f %j %o %O %c are supported; objects, Errors, Maps and Sets print readably.",
+        members: [
+            { signature: "console.log(...args)", description: "Print to the console (also console.info / warn / error / debug, which set the level).", example: 'console.log("token:", pm.environment.get("token"))' },
+            { signature: "console.info(...args)", description: "Info level." },
+            { signature: "console.warn(...args)", description: "Warning level." },
+            { signature: "console.error(...args)", description: "Error level." },
+            { signature: "console.debug(...args)", description: "Debug level." },
+            { signature: "console.trace(...args)", description: "Log with a stack trace." },
+            { signature: "console.assert(condition, ...args)", description: "Log an error when the condition is falsy (never throws)." },
+            { signature: "console.count(label?)", description: "Count calls per label.", example: 'console.count("retry")' },
+            { signature: "console.countReset(label?)", description: "Reset a counter." },
+            { signature: "console.time(label?)", description: "Start a timer." },
+            { signature: "console.timeLog(label?, ...args)", description: "Log the elapsed time without stopping the timer." },
+            { signature: "console.timeEnd(label?)", description: "Log the elapsed time and stop the timer." },
+            { signature: "console.group(...label)", description: "Indent following output until console.groupEnd() (console.groupCollapsed is the same)." },
+            { signature: "console.groupCollapsed(...label)", description: "Like console.group()." },
+            { signature: "console.groupEnd()", description: "End the current group." },
+            { signature: "console.table(data, columns?)", description: "Print an array of objects/arrays as a table.", example: "console.table(rows)" },
+            { signature: "console.dir(value, options?)", description: "Print an object with Node's inspect (depth/colors options)." },
+            { signature: "console.dirxml(...args)", description: "Same as console.log()." },
+            { signature: "console.clear()", description: "Clear the console buffer of the host." },
+        ],
+    },
     {
         name: "pm.db",
         description: "Database access (Oracle / MongoDB / PostgreSQL / MySQL). Disabled by feature policy in some contexts — tests then report SKIP.",
         members: [
             {
                 signature: "pm.db.query({ connectionId, query })",
-                description: "Run an ad-hoc query — ALWAYS await it. SQL connections (Oracle/Postgres/MySQL): `query` is the SQL text. MongoDB: `query` is a JSON STRING of a command object, e.g. `JSON.stringify({ collection: 'users', operation: 'findOne', filter: { email } })` — operation is find|findOne|aggregate|countDocuments|insertOne|updateOne|deleteOne|…, the match key is `filter` (NOT a `db.coll.find(...)` shell string and NOT `query`), and aggregate uses `pipeline`. Resolves to { success, error, rowCount, rows, firstRow(), connectionId, connectionName, connectionType, durationMs, executedAt }. firstRow is a FUNCTION: res.firstRow()?.STATUS (Oracle columns are UPPERCASE); for a Mongo existence check assert rowCount > 0.",
+                description: "Run an ad-hoc query — ALWAYS await it. Rejects when the query fails. SQL connections (Oracle/Postgres/MySQL): `query` is the SQL text. MongoDB: `query` is a JSON STRING of a command object, e.g. `JSON.stringify({ collection: 'users', operation: 'findOne', filter: { email } })` — operation is find|findOne|aggregate|countDocuments|insertOne|updateOne|deleteOne|…, the match key is `filter` (NOT a `db.coll.find(...)` shell string and NOT `query`), and aggregate uses `pipeline`. Resolves to { success, error, rowCount, rows, firstRow(), connectionId, connectionName, connectionType, durationMs, executedAt }. firstRow is a FUNCTION: res.firstRow()?.STATUS (Oracle columns are UPPERCASE); for a Mongo existence check assert rowCount > 0.",
                 requires: "database",
+                example: 'const res = await pm.db.query({ connectionId: "orders-db", query: "select status from orders where id = 1" })',
             },
             {
                 signature: "pm.db.pre",
                 description: "Result object of the declared pre-request DB query: { success, error, rowCount, rows, firstRow() }. Not a promise — read directly.",
                 requires: "database",
+                stages: REQUEST_STAGES,
             },
             {
                 signature: "pm.db.post",
-                description: "Result object of the declared post-response DB query (same shape as pm.db.pre).",
+                description: "Result object of the declared post-response DB query (same shape as pm.db.pre). Populated ONLY in the `tests` script; in a post-response script it is an empty result.",
                 requires: "database",
-                stages: ["post-response", "tests"],
+                stages: ["tests"],
             },
         ],
     },
-    {
-        name: "pm.kafka",
-        description: "Captured Kafka events from the request's Kafka tab listener.",
-        members: [
-            { signature: "pm.kafka.event()", description: "The matched event's parsed payload (or null).", requires: "kafka", stages: ["post-response", "tests"] },
-            { signature: "pm.kafka.messages()", description: "Every captured message in the listen window.", requires: "kafka", stages: ["post-response", "tests"] },
-        ],
-    },
     {
         name: "pm.redis",
         description: "Run ad-hoc Redis commands and read results of declared pre/post commands.",
         members: [
             {
                 signature: "pm.redis.command({ connectionId, command })",
-                description: "Run an ad-hoc Redis command (GET/SET/DEL/EXISTS/TTL) — ALWAYS await it. Resolves to { success, error, result, resultText, commandName, key, connectionId, connectionName, command, resolvedCommand, durationMs, executedAt }. Omit connectionId to use the request's configured Redis connection.",
+                description: "Run an ad-hoc Redis command (strings, hashes, lists, sets, sorted sets, counters, key expiry, SCAN) — ALWAYS await it. Resolves to { success, error, result, resultText, commandName, key, connectionId, connectionName, command, resolvedCommand, durationMs, executedAt }. Omit connectionId to use the request's configured Redis connection.",
                 requires: "redis",
+                example: 'const res = await pm.redis.command({ command: "GET session:1" })',
             },
             { signature: "pm.redis.get(key)", description: "Read a value already captured by a declared GET.", requires: "redis" },
             { signature: "pm.redis.results.pre", description: "Array of pre-stage command results (by line index).", requires: "redis" },
-            { signature: "pm.redis.results.post", description: "Array of post-stage command results.", requires: "redis", stages: ["post-response", "tests"] },
+            { signature: "pm.redis.results.post", description: "Array of post-stage command results.", requires: "redis", stages: RESPONSE_STAGES },
         ],
     },
     {
         name: "pm.random",
-        description: "Deterministic-format random data generators.",
+        description: "Random data generators. EVERY generator returns a string (pm.random.int() returns \"42\", pm.random.boolean() returns \"true\"/\"false\") — wrap with Number() when you need a number.",
         members: [
-            { signature: "pm.random.uuid()", description: "UUID v4." },
-            { signature: "pm.random.email()", description: "Random email address." },
-            { signature: "pm.random.string(length?)", description: "Alphanumeric string." },
-            { signature: "pm.random.int(min, max)", description: "Integer in range." },
-            { signature: "pm.random.bigdecimal(min, max, scale)", description: "Decimal with given scale." },
-            { signature: "pm.random.boolean()", description: "true/false." },
+            { signature: "pm.random.uuid()", description: "UUID v4 string.", example: "pm.random.uuid()" },
+            { signature: "pm.random.email()", description: "Random email address string." },
+            { signature: "pm.random.string(length?)", description: "Alphanumeric string (default 12, max 128)." },
+            { signature: "pm.random.int(min?, max?)", description: "Integer in range, as a STRING (default 0..999999).", example: "Number(pm.random.int(1, 100))" },
+            { signature: "pm.random.bigdecimal(min?, max?, scale?)", description: "Decimal string with `scale` fraction digits (default 6)." },
+            { signature: "pm.random.boolean()", description: "The string \"true\" or \"false\"." },
             { signature: "pm.random.phone()", description: "Phone number string." },
-            { signature: "pm.random.name()", description: "Person name." },
-            { signature: "pm.random.date(format?)", description: "Date string." },
+            { signature: "pm.random.name()", description: "Person name string." },
+            { signature: "pm.random.date(format?)", description: "Date string within ±1 year (default format YYYY-MM-DD; tokens YYYY MM DD HH mm ss SSS Z)." },
         ],
     },
     {
         name: "pm.counter",
-        description: "Monotonic counter scoped to the run.",
+        description: "Counter that survives across the requests of a run.",
         members: [
-            { signature: "pm.counter.next()", description: "Next value (starts at 1)." },
-            { signature: "pm.counter.start(startAt?)", description: "Counter starting at a custom value." },
+            { signature: "pm.counter.next()", description: "Next value (number, starts at 1)." },
+            { signature: "pm.counter.start(startAt?)", description: "Counter starting at a custom value (number, default 1); each call increments." },
         ],
     },
     {
         name: "pm.info",
-        description: "Execution metadata snapshot.",
+        description: "Execution metadata snapshot (read-only).",
         members: [
-            { signature: "pm.info.eventName", description: "\"prerequest\" | \"test\"." },
-            { signature: "pm.info.iteration", description: "Zero-based data-driven iteration index." },
-            {
-                signature: "pm.info.iterationCount",
-                description: "Total iterations — only meaningful in collection/data-driven runs. Never use it to gate token/cache logic in single sends.",
-            },
+            { signature: "pm.info.eventName", description: "\"prerequest\" in pre-request scripts, \"test\" in post-response / tests scripts, \"scenario-script\" in scenario script nodes." },
+            { signature: "pm.info.iteration", description: "0-BASED index of the current iteration of a data-driven run (0 outside one, like Postman)." },
+            { signature: "pm.info.iterationCount", description: "Total iterations of the run (1 outside a data-driven run). Never use it to gate token/cache logic in single sends." },
             { signature: "pm.info.requestName", description: "Current request's name." },
             { signature: "pm.info.requestId", description: "Current request's id." },
         ],
     },
     {
         name: "pm.execution",
-        description: "Collection-run flow control.",
+        description: "Collection-run flow control (Postman's pm.execution). Honoured by the collection runner; a single Send ignores it.",
         members: [
-            { signature: "pm.execution.setNextRequest(name)", description: "Jump to a named request next (collection runs)." },
-            { signature: "pm.execution.skipRequest()", description: "Skip the current request.", stages: ["pre-request"] },
-            { signature: "pm.execution.location", description: "Folder path of the current request." },
+            {
+                signature: "pm.execution.setNextRequest(nameOrId)",
+                description: "Run the request with this name or id next; pass null to stop the run after the current request. Postman's postman.setNextRequest is the same.",
+                example: 'pm.execution.setNextRequest("Get order")',
+            },
+            {
+                signature: "pm.execution.skipRequest()",
+                description: "Skip the current request: it is not sent and its post-response/tests scripts do not run (counted as skipped).",
+                stages: ["pre-request"],
+            },
+            { signature: "pm.execution.location", description: "Folder path of the current request as an array of names; pm.execution.location.current is the request's own name.", example: "pm.execution.location.current" },
+            { signature: "pm.execution.runRequest(requestIdOrName)", description: "Not supported in Callman yet — always throws a clear error." },
         ],
     },
     {
         name: "pm.node",
-        description: "Scenario workflow context (only meaningful inside scenario script nodes).",
+        description: "Scenario workflow context (scenario script and request nodes only). pm.node is a FUNCTION — pm.node(label) — not an object. The same data is also available as a global named after the node label when the label is a valid identifier (Login.token).",
         members: [
-            { signature: "pm.node.nodeLabel", description: "Current node's label.", stages: ["scenario-script"] },
-            { signature: "pm.node.setNextRequest(name)", description: "Route the workflow to a named node.", stages: ["scenario-script"] },
+            {
+                signature: "pm.node(label)",
+                description: "Output of a previous node by label (null when it has not run). The value carries __meta { status, success, failed, skipped, attempts, startedAt, endedAt, durationMs, error }.",
+                stages: ["scenario-script"],
+                example: 'const token = pm.node("Login").token',
+            },
+            { signature: "workflow.__meta", description: "Run-level metadata: status, totalNodes, successfulNodes, failedNodes, skippedNodes, totalRetries, durationMs, currentNode, lastNode, failedNode.", stages: ["scenario-script"] },
+            { signature: "env.NAME", description: "The active environment's variables as a plain object (also available in request scripts).", example: "env.BASE_URL" },
         ],
     },
     {
@@ -240,30 +433,67 @@ export const PM_API_METADATA = [
     },
     {
         name: "CryptoJS",
-        description: "crypto-js global (NOT under pm.*).",
+        description: "crypto-js global (NOT under pm.*; also require('crypto-js')). Results are WordArrays: call .toString() for hex or .toString(CryptoJS.enc.Base64).",
         members: [
-            { signature: "CryptoJS.SHA256(msg) / SHA1 / SHA512 / MD5", description: "Hashes; .toString() or .toString(CryptoJS.enc.Hex)." },
-            { signature: "CryptoJS.HmacSHA256(msg, key)", description: "HMAC family (SHA1/224/384/512, MD5 variants)." },
-            { signature: "CryptoJS.AES.encrypt(msg, key) / .decrypt(cipher, key)", description: "AES; decrypt result needs .toString(CryptoJS.enc.Utf8)." },
-            { signature: "CryptoJS.PBKDF2(password, salt, options)", description: "Key derivation." },
-            { signature: "CryptoJS.enc.Utf8 / Base64 / Hex / Latin1", description: "Encoders for .toString(...)." },
-            { signature: "CryptoJS.lib.WordArray.create / random(n)", description: "Raw word arrays (e.g. random IVs)." },
+            { signature: "CryptoJS.SHA256(message)", description: "Hash (also SHA1, SHA224, SHA384, SHA512, SHA3, MD5, RIPEMD160); .toString() is hex.", example: "CryptoJS.SHA256(body).toString()" },
+            { signature: "CryptoJS.HmacSHA256(message, key)", description: "HMAC (also HmacSHA1/224/384/512, HmacMD5).", example: "CryptoJS.HmacSHA256(msg, secret).toString(CryptoJS.enc.Hex)" },
+            { signature: "CryptoJS.AES.encrypt(message, key)", description: "AES encryption; CryptoJS.AES.decrypt(cipher, key) returns a WordArray — call .toString(CryptoJS.enc.Utf8).", example: "CryptoJS.AES.encrypt(text, key).toString()" },
+            { signature: "CryptoJS.PBKDF2(password, salt, options)", description: "Key derivation ({ keySize, iterations })." },
+            { signature: "CryptoJS.enc.Base64", description: "Encoders for .toString(...) / .parse(...): Utf8, Base64, Base64url, Hex, Latin1, Utf16.", example: "CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(text))" },
+            { signature: "CryptoJS.lib.WordArray.random(nBytes)", description: "Raw random word array (e.g. IVs); WordArray.create(words, sigBytes) builds one." },
         ],
     },
     {
         name: "_",
-        description: "lodash global (NOT under pm.*).",
+        description: "lodash global (NOT under pm.*; also require('lodash')).",
         members: [
-            { signature: "_.get(obj, path, default?) / _.pick / _.groupBy / _.sortBy / _.uniq / ...", description: "Full lodash surface for data wrangling." },
+            { signature: "_.get(object, path, defaultValue?)", description: "Safe nested read; the full lodash surface (pick, omit, groupBy, sortBy, uniq, merge, cloneDeep, isEqual, chunk, ...) is available.", example: '_.get(payload, "data.items[0].id")' },
+            { signature: "_.groupBy(collection, iteratee)", description: "Group items by a key or function.", example: '_.groupBy(items, "status")' },
         ],
     },
     {
         name: "timers",
-        description: "Safe per-execution timer wrappers (callbacks never outlive the run).",
+        description: "Safe per-run timer wrappers (callbacks never outlive the run; delays are capped at 60 s). They return numeric ids.",
         members: [
-            { signature: "setTimeout(fn, ms) / clearTimeout(id)", description: "Use with await new Promise(r => setTimeout(r, ms)) for polling loops." },
-            { signature: "setInterval(fn, ms) / clearInterval(id)", description: "Interval variant." },
+            { signature: "setTimeout(handler, delayMs)", description: "Run later; use with await new Promise(r => setTimeout(r, ms)) for polling loops. clearTimeout(id) cancels.", example: "await new Promise(r => setTimeout(r, 500))" },
+            { signature: "clearTimeout(id)", description: "Cancel a setTimeout." },
+            { signature: "setInterval(handler, delayMs)", description: "Repeat; clearInterval(id) cancels." },
+            { signature: "clearInterval(id)", description: "Cancel a setInterval." },
+            { signature: "setImmediate(handler)", description: "Run on the next turn (clearImmediate(id) cancels)." },
         ],
     },
+    {
+        name: "globals",
+        description: "Other globals available in every script (no import): Buffer, Intl, Reflect, Proxy, WeakRef, URL, URLSearchParams, TextEncoder/TextDecoder, atob/btoa, structuredClone, queueMicrotask, AbortController, Blob, crypto (Web Crypto), encodeURI/decodeURI, escape/unescape and the usual JSON/Math/Date/Promise/Map/Set/typed arrays. fetch, XMLHttpRequest, WebSocket, process, window, eval and Function are blocked — use pm.sendRequest for HTTP.",
+        members: [
+            { signature: "Buffer.from(data, encoding?)", description: "Node Buffer (utf8, hex, base64, base64url, latin1, ...).", example: 'Buffer.from("hello").toString("base64")' },
+            { signature: "crypto.randomUUID()", description: "Web Crypto: also crypto.getRandomValues(typedArray) and crypto.subtle.digest/sign/verify/encrypt/decrypt.", example: "crypto.randomUUID()" },
+            { signature: "structuredClone(value)", description: "Deep clone (Date, Map, Set, RegExp, ...)." },
+            { signature: "atob(base64)", description: "Decode base64 to a binary string (btoa(text) encodes)." },
+        ],
+    },
+    {
+        name: "postman",
+        description: "Postman's LEGACY scripting API, kept so old exported collections run unchanged. Enabled in request scripts unless the script starts with \"use sandbox2\"; prefer pm.* in new scripts.",
+        members: [
+            { signature: "postman.setEnvironmentVariable(key, value)", description: "Same as pm.environment.set (also getEnvironmentVariable, clearEnvironmentVariable, clearEnvironmentVariables).", example: 'postman.setEnvironmentVariable("token", "abc")' },
+            { signature: "postman.setGlobalVariable(key, value)", description: "Same as pm.globals.set (also getGlobalVariable, clearGlobalVariable, clearGlobalVariables)." },
+            { signature: "postman.setNextRequest(name)", description: "Same as pm.execution.setNextRequest." },
+            { signature: "postman.getResponseHeader(name)", description: "Header value of the response.", stages: RESPONSE_STAGES },
+            { signature: "postman.getResponseCookie(name)", description: "Cookie of the response.", stages: RESPONSE_STAGES },
+            { signature: "tests['name'] = boolean", description: "Legacy test: records a test named `name` that passes when the value is truthy.", example: 'tests["status is 200"] = responseCode.code === 200' },
+            { signature: "responseBody", description: "Legacy: raw response body text.", stages: RESPONSE_STAGES },
+            { signature: "responseCode.code", description: "Legacy: { code, name, detail } of the status.", stages: RESPONSE_STAGES },
+            { signature: "responseTime", description: "Legacy: response time in ms.", stages: RESPONSE_STAGES },
+            { signature: "responseHeaders", description: "Legacy: response headers as a plain object.", stages: RESPONSE_STAGES },
+            { signature: "responseCookies", description: "Legacy: response cookies as { name: value }.", stages: RESPONSE_STAGES },
+            { signature: "environment['name']", description: "Legacy: `environment` and `globals` also read variables by bracket (environment['token']); environment.get('token') keeps working. `data` is the iteration row, `iteration` the 0-based index; tv4, cheerio and xml2Json(xml) are globals." },
+        ],
+    },
+    {
+        name: "unsupported",
+        description: "Postman APIs Callman does not implement. Accessing them throws a clear \"is not supported in Callman yet\" error (never `undefined`), so a copied script fails loudly instead of misbehaving: pm.vault, pm.datasets, pm.mock, pm.state, pm.message, pm.execution.runRequest, and pm.require('npm:...' / 'jsr:...' / '@team/...') package specifiers. Postman Flows, Postbot, gRPC/WebSocket/MQTT hooks are out of scope.",
+        members: [],
+    },
 ];
 //# sourceMappingURL=pm-api-metadata.js.map