@postman-cse/onboarding-bootstrap 2.9.7 → 2.9.9

package/dist/action.cjs

@@ -258195,6 +258195,7 @@ var POSTMAN_ENDPOINT_PROFILES = {
   prod: {
     apiBaseUrl: "https://api.getpostman.com",
     bifrostBaseUrl: "https://bifrost-premium-https-v4.gw.postman.com",
+    fallbackBaseUrl: "https://go.postman.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn.io/install/unix.sh",
     gatewayBaseUrl: "https://gateway.postman.com",
     iapubBaseUrl: "https://iapub.postman.co"
@@ -258202,6 +258203,7 @@ var POSTMAN_ENDPOINT_PROFILES = {
   beta: {
     apiBaseUrl: "https://api.getpostman-beta.com",
     bifrostBaseUrl: "https://bifrost-https-v4.gw.postman-beta.com",
+    fallbackBaseUrl: "https://go.postman-beta.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn-beta.io/install/unix.sh",
     gatewayBaseUrl: "https://gateway.postman-beta.com",
     iapubBaseUrl: "https://iapub.postman.co"
@@ -261015,6 +261017,13 @@ function normalizeResponseKey(status) {
   const raw = String(status);
   return /^[1-5]xx$/i.test(raw) ? raw.toUpperCase() : raw;
 }
+function responseBodyExpectation(method, status, content) {
+  const normalizedStatus = normalizeResponseKey(status);
+  if (method === "head" || normalizedStatus === "1XX" || /^1[0-9][0-9]$/.test(normalizedStatus) || normalizedStatus === "204" || normalizedStatus === "205" || normalizedStatus === "304") {
+    return "forbidden";
+  }
+  return Object.keys(content).length > 0 ? "declared" : "unknown";
+}
 function collectSecurityApiKeys(root, operation) {
   const securitySchemes = asRecord5(asRecord5(root.components)?.securitySchemes);
   const requirements = operation.security === void 0 ? asArray2(root.security) : asArray2(operation.security);
@@ -261445,6 +261454,13 @@ function collectRequestBody(root, operation, version, operationId, warnings) {
   const body2 = resolveInternalRef(root, operation.requestBody);
   if (!body2) return void 0;
   const content = asRecord5(body2.content);
+  for (const [contentType2, mediaObject] of Object.entries(content ?? {})) {
+    if (asRecord5(mediaObject)?.schema === void 0) {
+      warnings.push(
+        `CONTRACT_REQUEST_SCHEMA_UNDOCUMENTED: request body ${contentType2} on ${operationId} declares no schema; generated request payload shape is not validated`
+      );
+    }
+  }
   const fieldRules = content ? requestBodyFieldRules(root, content, version, operationId, warnings) : void 0;
   if (fieldRules) {
     for (const [base, rule] of Object.entries(fieldRules)) {
@@ -262291,9 +262307,22 @@ function buildContractIndex(root) {
           const linkExpressions = collectLinkExpressions(root, response, `${lowerMethod.toUpperCase()} ${path10}`, responseWarnings, version, linkTargetSchemas);
           const responseContext = `${lowerMethod.toUpperCase()} ${path10} status ${status}`;
           const content = responseContent(root, version, response, responseContext, responseWarnings);
-          if ((status === "204" || status === "205" || status === "304") && Object.keys(content).length > 0) {
+          const bodyExpectation = responseBodyExpectation(lowerMethod, status, content);
+          if (bodyExpectation === "forbidden" && Object.keys(content).length > 0) {
             responseWarnings.add(`CONTRACT_BODYLESS_STATUS_WITH_CONTENT: ${lowerMethod.toUpperCase()} ${path10} declares content for status ${status}, which RFC 9110 forbids on the wire`);
           }
+          if (bodyExpectation === "unknown") {
+            responseWarnings.add(
+              `CONTRACT_RESPONSE_BODY_UNDOCUMENTED: ${responseContext} declares no response content; body presence, media type, and shape are not validated`
+            );
+          }
+          for (const [contentType2, mediaObject] of Object.entries(asRecord5(response.content) ?? {})) {
+            if (asRecord5(mediaObject)?.schema === void 0) {
+              responseWarnings.add(
+                `CONTRACT_RESPONSE_SCHEMA_UNDOCUMENTED: response ${contentType2} on ${responseContext} declares no schema; body shape is not validated`
+              );
+            }
+          }
           for (const [contentType2, media] of Object.entries(content)) {
             const base = contentType2.toLowerCase().split(";")[0]?.trim() ?? "";
             const schemaType = asRecord5(media.schema)?.type;
@@ -262305,7 +262334,7 @@ function buildContractIndex(root) {
           const writeOnlyProperties = collectResponseWriteOnlyNames(root, response);
           contractResponses[normalizeResponseKey(status)] = {
             content,
-            hasBody: Object.keys(content).length > 0,
+            bodyExpectation,
             headers,
             ...linkExpressions.length > 0 ? { links: linkExpressions } : {},
             ...writeOnlyProperties.length > 0 ? { writeOnlyProperties } : {}
@@ -262581,7 +262610,12 @@ function createContractScript(operation, warnings = []) {
     "  return null;",
     "}",
     'function responseText() { return pm.response.text() || ""; }',
-    'function isBodyless() { return pm.response.code === 204 || pm.response.code === 205 || pm.response.code === 304 || contract.method === "HEAD"; }',
+    'function isBodyless() { return pm.response.code < 200 || pm.response.code === 204 || pm.response.code === 205 || pm.response.code === 304 || contract.method === "HEAD"; }',
+    "function selectedBodyExpectation() {",
+    '  if (isBodyless()) return "forbidden";',
+    '  if (!selected) return "unknown";',
+    '  return selected.value.bodyExpectation || "unknown";',
+    "}",
     'function mediaBase(value) { return String(value || "").toLowerCase().split(";")[0].trim(); }',
     'function mediaParts(value) { var base = mediaBase(value); var parts = base.split("/"); return { raw: base, type: parts[0] || "", subtype: parts[1] || "" }; }',
     'function isJsonSubtype(subtype) { return subtype === "json" || /\\+json$/.test(subtype); }',
@@ -262621,6 +262655,7 @@ function createContractScript(operation, warnings = []) {
     "  return matches[0];",
     "}",
     "var selected = selectedResponseContract();",
+    "var bodyExpectation = selectedBodyExpectation();",
     ...skipped.length > 0 ? [
       // A schema schemasafe could not compile is NOT silently ignored: it is
       // surfaced here (and as a CONTRACT_SCHEMA_NOT_COMPILED warning at generation
@@ -262652,10 +262687,8 @@ function createContractScript(operation, warnings = []) {
     "});",
     "pm.test('Response body matches OpenAPI body contract', function () {",
     "  if (!selected) return;",
-    "  if (isBodyless()) { pm.expect(responseText().trim().length).to.equal(0); return; }",
-    "  var content = selected.value.content || {};",
-    '  if (Object.keys(content).length === 0) { pm.expect(responseText().trim().length, "OpenAPI response defines no body but response body was not empty").to.equal(0); }',
-    '  else { pm.expect(responseText().trim().length, "OpenAPI response defines a body but response body was empty").to.be.above(0); }',
+    '  if (bodyExpectation === "forbidden") { pm.expect(responseText().length, "HTTP semantics forbid a response body for " + contract.method + " " + contract.path + " status " + pm.response.code).to.equal(0); return; }',
+    '  if (bodyExpectation === "declared") { pm.expect(responseText().length, "OpenAPI response declares content but response body was empty").to.be.above(0); }',
     "});",
     "pm.test('Content-Type matches OpenAPI response content', function () {",
     "  if (!selected || isBodyless()) return;",
@@ -263698,8 +263731,7 @@ function createContractScript(operation, warnings = []) {
     '  if (contract.method === "HEAD" || pm.response.code === 304) return;',
     "  var actualBytes = unescape(encodeURIComponent(responseText())).length;",
     '  if (Number(String(raw).trim()) !== actualBytes) pm.expect.fail("Content-Length must equal the response body byte length when Content-Encoding and Transfer-Encoding are absent (RFC 9110 8.6): " + raw + " !== " + actualBytes);',
-    "  var mustBeEmpty = isBodyless() || (selected && Object.keys(selected.value.content || {}).length === 0);",
-    '  if (mustBeEmpty && Number(String(raw).trim()) !== 0) pm.expect.fail("OpenAPI defines no response body for " + contract.method + " " + contract.path + " status " + pm.response.code + " but Content-Length was " + raw);',
+    '  if (bodyExpectation === "forbidden" && Number(String(raw).trim()) !== 0) pm.expect.fail("HTTP semantics forbid a carried response body for " + contract.method + " " + contract.path + " status " + pm.response.code + " but Content-Length was " + raw);',
     "});",
     "pm.test('RFC SHOULD-level advisories are documented', function () {",
     '  pm.expect(rfcAdvisories, "SHOULD-level findings (advisory, non-failing): " + rfcAdvisories.join("; ")).to.be.an("array");',
@@ -265363,6 +265395,11 @@ ${error2.responseBody ?? ""}`
             method: "post",
             path: `/v3/collections/${cid}/items/`,
             retry: "none",
+            // The transport's cold /_api fallback only fires after the primary
+            // budget is exhausted; by then this loop has reconciled the item as
+            // absent (match == null), so a fallback resend cannot duplicate a
+            // committed create.
+            fallback: "auto",
             headers: { "X-Entity-Type": kind },
             body: this.buildItemCreateBody(item, parentId)
           });
@@ -265740,6 +265777,7 @@ var AccessTokenGatewayClient = class {
   orgMode;
   fetchImpl;
   secretMasker;
+  fallbackBaseUrl;
   maxRetries;
   retryBaseDelayMs;
   retryMaxDelayMs;
@@ -265755,6 +265793,8 @@ var AccessTokenGatewayClient = class {
     this.orgMode = options.orgMode ?? false;
     this.fetchImpl = options.fetchImpl ?? fetch;
     this.secretMasker = options.secretMasker ?? createSecretMasker([this.tokenProvider.current()]);
+    const fallbackEnv = typeof process !== "undefined" ? process.env?.POSTMAN_ITEM_CREATE_FALLBACK : void 0;
+    this.fallbackBaseUrl = fallbackEnv === "off" ? void 0 : options.fallbackBaseUrl?.replace(/\/+$/, "");
     this.maxRetries = options.maxRetries ?? 3;
     this.retryBaseDelayMs = options.retryBaseDelayMs ?? 400;
     this.retryMaxDelayMs = options.retryMaxDelayMs ?? 5e3;
@@ -265777,8 +265817,8 @@ var AccessTokenGatewayClient = class {
     }
     return headers;
   }
-  async send(request) {
-    const url = `${this.bifrostBaseUrl}/ws/proxy`;
+  async send(request, baseUrl) {
+    const url = `${baseUrl ?? this.bifrostBaseUrl}/ws/proxy`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
     try {
@@ -265808,6 +265848,50 @@ var AccessTokenGatewayClient = class {
    * 200 envelope carrying an inner collection-service error is treated as that
    * inner status. The auth-refresh-once path is independent of the retry budget.
    */
+  /**
+   * One cold, serial attempt against the fallback base URL after the primary
+   * budget is exhausted on a transient failure. Never hedged in parallel with
+   * the primary; only fires when the request would otherwise throw. Callers
+   * with `retry: 'none'` still reconcile first — the fallback attempt here is
+   * the resend, so it is only used for requests whose mutation is known
+   * idempotent or already reconciled by the caller's adopt-on-ambiguous loop.
+   */
+  async tryFallback(request) {
+    if (!this.fallbackBaseUrl) return null;
+    try {
+      return await this.send(request, this.fallbackBaseUrl);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Run the fallback attempt and classify its response the same way the
+   * primary path would. Returns the rebuilt success response, or null when the
+   * fallback also failed transiently (caller then throws the original error).
+   * Non-transient fallback failures (4xx, inner errors) surface as their own
+   * HttpError since they are the freshest authoritative answer.
+   */
+  fallbackEligible(request) {
+    if (!this.fallbackBaseUrl) return false;
+    const retryMode = request.retry ?? (request.method === "get" ? "safe" : "none");
+    return retryMode === "safe" || request.fallback === "auto";
+  }
+  async attemptFallback(request) {
+    if (!this.fallbackEligible(request)) return null;
+    const response = await this.tryFallback(request);
+    if (!response) return null;
+    const body2 = await response.text().catch(() => "");
+    if (response.ok) {
+      const innerStatus = detectInnerError(body2);
+      if (innerStatus !== null) {
+        if (isTransientGatewayError(innerStatus, body2)) return null;
+        throw this.toInnerHttpError(request, innerStatus, body2);
+      }
+      return this.rebuildResponse(response, body2);
+    }
+    if (isTransientGatewayError(response.status, body2)) return null;
+    throw this.toHttpError(request, response, body2);
+  }
   async request(request) {
     if (!this.tokenProvider.current() && this.tokenProvider.canRefresh()) {
       await this.tokenProvider.refresh();
@@ -265825,6 +265909,8 @@ var AccessTokenGatewayClient = class {
           await this.sleepImpl(delay);
           continue;
         }
+        const fallbackResponse2 = await this.attemptFallback(request);
+        if (fallbackResponse2) return fallbackResponse2;
         throw error2;
       }
       if (response.ok) {
@@ -265837,6 +265923,8 @@ var AccessTokenGatewayClient = class {
             await this.sleepImpl(delay);
             continue;
           }
+          const fallbackResponse2 = await this.attemptFallback(request);
+          if (fallbackResponse2) return fallbackResponse2;
           throw this.toInnerHttpError(request, innerStatus, okBody);
         }
         return this.rebuildResponse(response, okBody);
@@ -265865,6 +265953,8 @@ var AccessTokenGatewayClient = class {
         await this.sleepImpl(delay);
         continue;
       }
+      const fallbackResponse = await this.attemptFallback(request);
+      if (fallbackResponse) return fallbackResponse;
       throw this.toHttpError(request, response, body2);
     }
   }
@@ -311990,6 +312080,7 @@ function resolveInputs(env = process.env) {
     postmanStack,
     postmanApiBase: endpointProfile.apiBaseUrl,
     postmanBifrostBase: endpointProfile.bifrostBaseUrl,
+    postmanFallbackBase: endpointProfile.fallbackBaseUrl,
     postmanGatewayBase: endpointProfile.gatewayBaseUrl,
     postmanCliInstallUrl: endpointProfile.cliInstallUrl,
     postmanIapubBase: endpointProfile.iapubBaseUrl,
@@ -313744,6 +313835,7 @@ async function runAction(actionCore = core_exports, actionExec = exec_exports, a
         gateway: new AccessTokenGatewayClient({
           tokenProvider: probeProvider,
           bifrostBaseUrl: inputs.postmanBifrostBase,
+          fallbackBaseUrl: inputs.postmanFallbackBase,
           teamId: inputs.teamId || "",
           orgMode: false,
           secretMasker: createSecretMasker([inputs.postmanApiKey, inputs.postmanAccessToken])
@@ -313866,6 +313958,7 @@ function createBootstrapDependencies(inputs, factories, orgMode = false) {
   const gatewayClient = inputs.postmanAccessToken || inputs.postmanApiKey ? new AccessTokenGatewayClient({
     tokenProvider,
     bifrostBaseUrl: inputs.postmanBifrostBase,
+    fallbackBaseUrl: inputs.postmanFallbackBase,
     teamId: inputs.teamId || "",
     orgMode,
     secretMasker

package/dist/cli.cjs

@@ -256513,6 +256513,7 @@ var POSTMAN_ENDPOINT_PROFILES = {
   prod: {
     apiBaseUrl: "https://api.getpostman.com",
     bifrostBaseUrl: "https://bifrost-premium-https-v4.gw.postman.com",
+    fallbackBaseUrl: "https://go.postman.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn.io/install/unix.sh",
     gatewayBaseUrl: "https://gateway.postman.com",
     iapubBaseUrl: "https://iapub.postman.co"
@@ -256520,6 +256521,7 @@ var POSTMAN_ENDPOINT_PROFILES = {
   beta: {
     apiBaseUrl: "https://api.getpostman-beta.com",
     bifrostBaseUrl: "https://bifrost-https-v4.gw.postman-beta.com",
+    fallbackBaseUrl: "https://go.postman-beta.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn-beta.io/install/unix.sh",
     gatewayBaseUrl: "https://gateway.postman-beta.com",
     iapubBaseUrl: "https://iapub.postman.co"
@@ -259333,6 +259335,13 @@ function normalizeResponseKey(status) {
   const raw = String(status);
   return /^[1-5]xx$/i.test(raw) ? raw.toUpperCase() : raw;
 }
+function responseBodyExpectation(method, status, content) {
+  const normalizedStatus = normalizeResponseKey(status);
+  if (method === "head" || normalizedStatus === "1XX" || /^1[0-9][0-9]$/.test(normalizedStatus) || normalizedStatus === "204" || normalizedStatus === "205" || normalizedStatus === "304") {
+    return "forbidden";
+  }
+  return Object.keys(content).length > 0 ? "declared" : "unknown";
+}
 function collectSecurityApiKeys(root, operation) {
   const securitySchemes = asRecord5(asRecord5(root.components)?.securitySchemes);
   const requirements = operation.security === void 0 ? asArray2(root.security) : asArray2(operation.security);
@@ -259763,6 +259772,13 @@ function collectRequestBody(root, operation, version, operationId, warnings) {
   const body2 = resolveInternalRef(root, operation.requestBody);
   if (!body2) return void 0;
   const content = asRecord5(body2.content);
+  for (const [contentType2, mediaObject] of Object.entries(content ?? {})) {
+    if (asRecord5(mediaObject)?.schema === void 0) {
+      warnings.push(
+        `CONTRACT_REQUEST_SCHEMA_UNDOCUMENTED: request body ${contentType2} on ${operationId} declares no schema; generated request payload shape is not validated`
+      );
+    }
+  }
   const fieldRules = content ? requestBodyFieldRules(root, content, version, operationId, warnings) : void 0;
   if (fieldRules) {
     for (const [base, rule] of Object.entries(fieldRules)) {
@@ -260609,9 +260625,22 @@ function buildContractIndex(root) {
           const linkExpressions = collectLinkExpressions(root, response, `${lowerMethod.toUpperCase()} ${path8}`, responseWarnings, version, linkTargetSchemas);
           const responseContext = `${lowerMethod.toUpperCase()} ${path8} status ${status}`;
           const content = responseContent(root, version, response, responseContext, responseWarnings);
-          if ((status === "204" || status === "205" || status === "304") && Object.keys(content).length > 0) {
+          const bodyExpectation = responseBodyExpectation(lowerMethod, status, content);
+          if (bodyExpectation === "forbidden" && Object.keys(content).length > 0) {
             responseWarnings.add(`CONTRACT_BODYLESS_STATUS_WITH_CONTENT: ${lowerMethod.toUpperCase()} ${path8} declares content for status ${status}, which RFC 9110 forbids on the wire`);
           }
+          if (bodyExpectation === "unknown") {
+            responseWarnings.add(
+              `CONTRACT_RESPONSE_BODY_UNDOCUMENTED: ${responseContext} declares no response content; body presence, media type, and shape are not validated`
+            );
+          }
+          for (const [contentType2, mediaObject] of Object.entries(asRecord5(response.content) ?? {})) {
+            if (asRecord5(mediaObject)?.schema === void 0) {
+              responseWarnings.add(
+                `CONTRACT_RESPONSE_SCHEMA_UNDOCUMENTED: response ${contentType2} on ${responseContext} declares no schema; body shape is not validated`
+              );
+            }
+          }
           for (const [contentType2, media] of Object.entries(content)) {
             const base = contentType2.toLowerCase().split(";")[0]?.trim() ?? "";
             const schemaType = asRecord5(media.schema)?.type;
@@ -260623,7 +260652,7 @@ function buildContractIndex(root) {
           const writeOnlyProperties = collectResponseWriteOnlyNames(root, response);
           contractResponses[normalizeResponseKey(status)] = {
             content,
-            hasBody: Object.keys(content).length > 0,
+            bodyExpectation,
             headers,
             ...linkExpressions.length > 0 ? { links: linkExpressions } : {},
             ...writeOnlyProperties.length > 0 ? { writeOnlyProperties } : {}
@@ -260899,7 +260928,12 @@ function createContractScript(operation, warnings = []) {
     "  return null;",
     "}",
     'function responseText() { return pm.response.text() || ""; }',
-    'function isBodyless() { return pm.response.code === 204 || pm.response.code === 205 || pm.response.code === 304 || contract.method === "HEAD"; }',
+    'function isBodyless() { return pm.response.code < 200 || pm.response.code === 204 || pm.response.code === 205 || pm.response.code === 304 || contract.method === "HEAD"; }',
+    "function selectedBodyExpectation() {",
+    '  if (isBodyless()) return "forbidden";',
+    '  if (!selected) return "unknown";',
+    '  return selected.value.bodyExpectation || "unknown";',
+    "}",
     'function mediaBase(value) { return String(value || "").toLowerCase().split(";")[0].trim(); }',
     'function mediaParts(value) { var base = mediaBase(value); var parts = base.split("/"); return { raw: base, type: parts[0] || "", subtype: parts[1] || "" }; }',
     'function isJsonSubtype(subtype) { return subtype === "json" || /\\+json$/.test(subtype); }',
@@ -260939,6 +260973,7 @@ function createContractScript(operation, warnings = []) {
     "  return matches[0];",
     "}",
     "var selected = selectedResponseContract();",
+    "var bodyExpectation = selectedBodyExpectation();",
     ...skipped.length > 0 ? [
       // A schema schemasafe could not compile is NOT silently ignored: it is
       // surfaced here (and as a CONTRACT_SCHEMA_NOT_COMPILED warning at generation
@@ -260970,10 +261005,8 @@ function createContractScript(operation, warnings = []) {
     "});",
     "pm.test('Response body matches OpenAPI body contract', function () {",
     "  if (!selected) return;",
-    "  if (isBodyless()) { pm.expect(responseText().trim().length).to.equal(0); return; }",
-    "  var content = selected.value.content || {};",
-    '  if (Object.keys(content).length === 0) { pm.expect(responseText().trim().length, "OpenAPI response defines no body but response body was not empty").to.equal(0); }',
-    '  else { pm.expect(responseText().trim().length, "OpenAPI response defines a body but response body was empty").to.be.above(0); }',
+    '  if (bodyExpectation === "forbidden") { pm.expect(responseText().length, "HTTP semantics forbid a response body for " + contract.method + " " + contract.path + " status " + pm.response.code).to.equal(0); return; }',
+    '  if (bodyExpectation === "declared") { pm.expect(responseText().length, "OpenAPI response declares content but response body was empty").to.be.above(0); }',
     "});",
     "pm.test('Content-Type matches OpenAPI response content', function () {",
     "  if (!selected || isBodyless()) return;",
@@ -262016,8 +262049,7 @@ function createContractScript(operation, warnings = []) {
     '  if (contract.method === "HEAD" || pm.response.code === 304) return;',
     "  var actualBytes = unescape(encodeURIComponent(responseText())).length;",
     '  if (Number(String(raw).trim()) !== actualBytes) pm.expect.fail("Content-Length must equal the response body byte length when Content-Encoding and Transfer-Encoding are absent (RFC 9110 8.6): " + raw + " !== " + actualBytes);',
-    "  var mustBeEmpty = isBodyless() || (selected && Object.keys(selected.value.content || {}).length === 0);",
-    '  if (mustBeEmpty && Number(String(raw).trim()) !== 0) pm.expect.fail("OpenAPI defines no response body for " + contract.method + " " + contract.path + " status " + pm.response.code + " but Content-Length was " + raw);',
+    '  if (bodyExpectation === "forbidden" && Number(String(raw).trim()) !== 0) pm.expect.fail("HTTP semantics forbid a carried response body for " + contract.method + " " + contract.path + " status " + pm.response.code + " but Content-Length was " + raw);',
     "});",
     "pm.test('RFC SHOULD-level advisories are documented', function () {",
     '  pm.expect(rfcAdvisories, "SHOULD-level findings (advisory, non-failing): " + rfcAdvisories.join("; ")).to.be.an("array");',
@@ -263681,6 +263713,11 @@ ${error.responseBody ?? ""}`
             method: "post",
             path: `/v3/collections/${cid}/items/`,
             retry: "none",
+            // The transport's cold /_api fallback only fires after the primary
+            // budget is exhausted; by then this loop has reconciled the item as
+            // absent (match == null), so a fallback resend cannot duplicate a
+            // committed create.
+            fallback: "auto",
             headers: { "X-Entity-Type": kind },
             body: this.buildItemCreateBody(item, parentId)
           });
@@ -264058,6 +264095,7 @@ var AccessTokenGatewayClient = class {
   orgMode;
   fetchImpl;
   secretMasker;
+  fallbackBaseUrl;
   maxRetries;
   retryBaseDelayMs;
   retryMaxDelayMs;
@@ -264073,6 +264111,8 @@ var AccessTokenGatewayClient = class {
     this.orgMode = options.orgMode ?? false;
     this.fetchImpl = options.fetchImpl ?? fetch;
     this.secretMasker = options.secretMasker ?? createSecretMasker([this.tokenProvider.current()]);
+    const fallbackEnv = typeof process !== "undefined" ? process.env?.POSTMAN_ITEM_CREATE_FALLBACK : void 0;
+    this.fallbackBaseUrl = fallbackEnv === "off" ? void 0 : options.fallbackBaseUrl?.replace(/\/+$/, "");
     this.maxRetries = options.maxRetries ?? 3;
     this.retryBaseDelayMs = options.retryBaseDelayMs ?? 400;
     this.retryMaxDelayMs = options.retryMaxDelayMs ?? 5e3;
@@ -264095,8 +264135,8 @@ var AccessTokenGatewayClient = class {
     }
     return headers;
   }
-  async send(request) {
-    const url = `${this.bifrostBaseUrl}/ws/proxy`;
+  async send(request, baseUrl) {
+    const url = `${baseUrl ?? this.bifrostBaseUrl}/ws/proxy`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
     try {
@@ -264126,6 +264166,50 @@ var AccessTokenGatewayClient = class {
    * 200 envelope carrying an inner collection-service error is treated as that
    * inner status. The auth-refresh-once path is independent of the retry budget.
    */
+  /**
+   * One cold, serial attempt against the fallback base URL after the primary
+   * budget is exhausted on a transient failure. Never hedged in parallel with
+   * the primary; only fires when the request would otherwise throw. Callers
+   * with `retry: 'none'` still reconcile first — the fallback attempt here is
+   * the resend, so it is only used for requests whose mutation is known
+   * idempotent or already reconciled by the caller's adopt-on-ambiguous loop.
+   */
+  async tryFallback(request) {
+    if (!this.fallbackBaseUrl) return null;
+    try {
+      return await this.send(request, this.fallbackBaseUrl);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Run the fallback attempt and classify its response the same way the
+   * primary path would. Returns the rebuilt success response, or null when the
+   * fallback also failed transiently (caller then throws the original error).
+   * Non-transient fallback failures (4xx, inner errors) surface as their own
+   * HttpError since they are the freshest authoritative answer.
+   */
+  fallbackEligible(request) {
+    if (!this.fallbackBaseUrl) return false;
+    const retryMode = request.retry ?? (request.method === "get" ? "safe" : "none");
+    return retryMode === "safe" || request.fallback === "auto";
+  }
+  async attemptFallback(request) {
+    if (!this.fallbackEligible(request)) return null;
+    const response = await this.tryFallback(request);
+    if (!response) return null;
+    const body2 = await response.text().catch(() => "");
+    if (response.ok) {
+      const innerStatus = detectInnerError(body2);
+      if (innerStatus !== null) {
+        if (isTransientGatewayError(innerStatus, body2)) return null;
+        throw this.toInnerHttpError(request, innerStatus, body2);
+      }
+      return this.rebuildResponse(response, body2);
+    }
+    if (isTransientGatewayError(response.status, body2)) return null;
+    throw this.toHttpError(request, response, body2);
+  }
   async request(request) {
     if (!this.tokenProvider.current() && this.tokenProvider.canRefresh()) {
       await this.tokenProvider.refresh();
@@ -264143,6 +264227,8 @@ var AccessTokenGatewayClient = class {
           await this.sleepImpl(delay);
           continue;
         }
+        const fallbackResponse2 = await this.attemptFallback(request);
+        if (fallbackResponse2) return fallbackResponse2;
         throw error;
       }
       if (response.ok) {
@@ -264155,6 +264241,8 @@ var AccessTokenGatewayClient = class {
             await this.sleepImpl(delay);
             continue;
           }
+          const fallbackResponse2 = await this.attemptFallback(request);
+          if (fallbackResponse2) return fallbackResponse2;
           throw this.toInnerHttpError(request, innerStatus, okBody);
         }
         return this.rebuildResponse(response, okBody);
@@ -264183,6 +264271,8 @@ var AccessTokenGatewayClient = class {
         await this.sleepImpl(delay);
         continue;
       }
+      const fallbackResponse = await this.attemptFallback(request);
+      if (fallbackResponse) return fallbackResponse;
       throw this.toHttpError(request, response, body2);
     }
   }
@@ -310302,6 +310392,7 @@ function resolveInputs(env = process.env) {
     postmanStack,
     postmanApiBase: endpointProfile.apiBaseUrl,
     postmanBifrostBase: endpointProfile.bifrostBaseUrl,
+    postmanFallbackBase: endpointProfile.fallbackBaseUrl,
     postmanGatewayBase: endpointProfile.gatewayBaseUrl,
     postmanCliInstallUrl: endpointProfile.cliInstallUrl,
     postmanIapubBase: endpointProfile.iapubBaseUrl,
@@ -312020,6 +312111,7 @@ function createBootstrapDependencies(inputs, factories, orgMode = false) {
   const gatewayClient = inputs.postmanAccessToken || inputs.postmanApiKey ? new AccessTokenGatewayClient({
     tokenProvider,
     bifrostBaseUrl: inputs.postmanBifrostBase,
+    fallbackBaseUrl: inputs.postmanFallbackBase,
     teamId: inputs.teamId || "",
     orgMode,
     secretMasker

package/dist/index.cjs

@@ -258220,6 +258220,7 @@ var POSTMAN_ENDPOINT_PROFILES = {
   prod: {
     apiBaseUrl: "https://api.getpostman.com",
     bifrostBaseUrl: "https://bifrost-premium-https-v4.gw.postman.com",
+    fallbackBaseUrl: "https://go.postman.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn.io/install/unix.sh",
     gatewayBaseUrl: "https://gateway.postman.com",
     iapubBaseUrl: "https://iapub.postman.co"
@@ -258227,6 +258228,7 @@ var POSTMAN_ENDPOINT_PROFILES = {
   beta: {
     apiBaseUrl: "https://api.getpostman-beta.com",
     bifrostBaseUrl: "https://bifrost-https-v4.gw.postman-beta.com",
+    fallbackBaseUrl: "https://go.postman-beta.co/_api",
     cliInstallUrl: "https://dl-cli.pstmn-beta.io/install/unix.sh",
     gatewayBaseUrl: "https://gateway.postman-beta.com",
     iapubBaseUrl: "https://iapub.postman.co"
@@ -261040,6 +261042,13 @@ function normalizeResponseKey(status) {
   const raw = String(status);
   return /^[1-5]xx$/i.test(raw) ? raw.toUpperCase() : raw;
 }
+function responseBodyExpectation(method, status, content) {
+  const normalizedStatus = normalizeResponseKey(status);
+  if (method === "head" || normalizedStatus === "1XX" || /^1[0-9][0-9]$/.test(normalizedStatus) || normalizedStatus === "204" || normalizedStatus === "205" || normalizedStatus === "304") {
+    return "forbidden";
+  }
+  return Object.keys(content).length > 0 ? "declared" : "unknown";
+}
 function collectSecurityApiKeys(root, operation) {
   const securitySchemes = asRecord5(asRecord5(root.components)?.securitySchemes);
   const requirements = operation.security === void 0 ? asArray2(root.security) : asArray2(operation.security);
@@ -261470,6 +261479,13 @@ function collectRequestBody(root, operation, version, operationId, warnings) {
   const body2 = resolveInternalRef(root, operation.requestBody);
   if (!body2) return void 0;
   const content = asRecord5(body2.content);
+  for (const [contentType2, mediaObject] of Object.entries(content ?? {})) {
+    if (asRecord5(mediaObject)?.schema === void 0) {
+      warnings.push(
+        `CONTRACT_REQUEST_SCHEMA_UNDOCUMENTED: request body ${contentType2} on ${operationId} declares no schema; generated request payload shape is not validated`
+      );
+    }
+  }
   const fieldRules = content ? requestBodyFieldRules(root, content, version, operationId, warnings) : void 0;
   if (fieldRules) {
     for (const [base, rule] of Object.entries(fieldRules)) {
@@ -262316,9 +262332,22 @@ function buildContractIndex(root) {
           const linkExpressions = collectLinkExpressions(root, response, `${lowerMethod.toUpperCase()} ${path10}`, responseWarnings, version, linkTargetSchemas);
           const responseContext = `${lowerMethod.toUpperCase()} ${path10} status ${status}`;
           const content = responseContent(root, version, response, responseContext, responseWarnings);
-          if ((status === "204" || status === "205" || status === "304") && Object.keys(content).length > 0) {
+          const bodyExpectation = responseBodyExpectation(lowerMethod, status, content);
+          if (bodyExpectation === "forbidden" && Object.keys(content).length > 0) {
             responseWarnings.add(`CONTRACT_BODYLESS_STATUS_WITH_CONTENT: ${lowerMethod.toUpperCase()} ${path10} declares content for status ${status}, which RFC 9110 forbids on the wire`);
           }
+          if (bodyExpectation === "unknown") {
+            responseWarnings.add(
+              `CONTRACT_RESPONSE_BODY_UNDOCUMENTED: ${responseContext} declares no response content; body presence, media type, and shape are not validated`
+            );
+          }
+          for (const [contentType2, mediaObject] of Object.entries(asRecord5(response.content) ?? {})) {
+            if (asRecord5(mediaObject)?.schema === void 0) {
+              responseWarnings.add(
+                `CONTRACT_RESPONSE_SCHEMA_UNDOCUMENTED: response ${contentType2} on ${responseContext} declares no schema; body shape is not validated`
+              );
+            }
+          }
           for (const [contentType2, media] of Object.entries(content)) {
             const base = contentType2.toLowerCase().split(";")[0]?.trim() ?? "";
             const schemaType = asRecord5(media.schema)?.type;
@@ -262330,7 +262359,7 @@ function buildContractIndex(root) {
           const writeOnlyProperties = collectResponseWriteOnlyNames(root, response);
           contractResponses[normalizeResponseKey(status)] = {
             content,
-            hasBody: Object.keys(content).length > 0,
+            bodyExpectation,
             headers,
             ...linkExpressions.length > 0 ? { links: linkExpressions } : {},
             ...writeOnlyProperties.length > 0 ? { writeOnlyProperties } : {}
@@ -262606,7 +262635,12 @@ function createContractScript(operation, warnings = []) {
     "  return null;",
     "}",
     'function responseText() { return pm.response.text() || ""; }',
-    'function isBodyless() { return pm.response.code === 204 || pm.response.code === 205 || pm.response.code === 304 || contract.method === "HEAD"; }',
+    'function isBodyless() { return pm.response.code < 200 || pm.response.code === 204 || pm.response.code === 205 || pm.response.code === 304 || contract.method === "HEAD"; }',
+    "function selectedBodyExpectation() {",
+    '  if (isBodyless()) return "forbidden";',
+    '  if (!selected) return "unknown";',
+    '  return selected.value.bodyExpectation || "unknown";',
+    "}",
     'function mediaBase(value) { return String(value || "").toLowerCase().split(";")[0].trim(); }',
     'function mediaParts(value) { var base = mediaBase(value); var parts = base.split("/"); return { raw: base, type: parts[0] || "", subtype: parts[1] || "" }; }',
     'function isJsonSubtype(subtype) { return subtype === "json" || /\\+json$/.test(subtype); }',
@@ -262646,6 +262680,7 @@ function createContractScript(operation, warnings = []) {
     "  return matches[0];",
     "}",
     "var selected = selectedResponseContract();",
+    "var bodyExpectation = selectedBodyExpectation();",
     ...skipped.length > 0 ? [
       // A schema schemasafe could not compile is NOT silently ignored: it is
       // surfaced here (and as a CONTRACT_SCHEMA_NOT_COMPILED warning at generation
@@ -262677,10 +262712,8 @@ function createContractScript(operation, warnings = []) {
     "});",
     "pm.test('Response body matches OpenAPI body contract', function () {",
     "  if (!selected) return;",
-    "  if (isBodyless()) { pm.expect(responseText().trim().length).to.equal(0); return; }",
-    "  var content = selected.value.content || {};",
-    '  if (Object.keys(content).length === 0) { pm.expect(responseText().trim().length, "OpenAPI response defines no body but response body was not empty").to.equal(0); }',
-    '  else { pm.expect(responseText().trim().length, "OpenAPI response defines a body but response body was empty").to.be.above(0); }',
+    '  if (bodyExpectation === "forbidden") { pm.expect(responseText().length, "HTTP semantics forbid a response body for " + contract.method + " " + contract.path + " status " + pm.response.code).to.equal(0); return; }',
+    '  if (bodyExpectation === "declared") { pm.expect(responseText().length, "OpenAPI response declares content but response body was empty").to.be.above(0); }',
     "});",
     "pm.test('Content-Type matches OpenAPI response content', function () {",
     "  if (!selected || isBodyless()) return;",
@@ -263723,8 +263756,7 @@ function createContractScript(operation, warnings = []) {
     '  if (contract.method === "HEAD" || pm.response.code === 304) return;',
     "  var actualBytes = unescape(encodeURIComponent(responseText())).length;",
     '  if (Number(String(raw).trim()) !== actualBytes) pm.expect.fail("Content-Length must equal the response body byte length when Content-Encoding and Transfer-Encoding are absent (RFC 9110 8.6): " + raw + " !== " + actualBytes);',
-    "  var mustBeEmpty = isBodyless() || (selected && Object.keys(selected.value.content || {}).length === 0);",
-    '  if (mustBeEmpty && Number(String(raw).trim()) !== 0) pm.expect.fail("OpenAPI defines no response body for " + contract.method + " " + contract.path + " status " + pm.response.code + " but Content-Length was " + raw);',
+    '  if (bodyExpectation === "forbidden" && Number(String(raw).trim()) !== 0) pm.expect.fail("HTTP semantics forbid a carried response body for " + contract.method + " " + contract.path + " status " + pm.response.code + " but Content-Length was " + raw);',
     "});",
     "pm.test('RFC SHOULD-level advisories are documented', function () {",
     '  pm.expect(rfcAdvisories, "SHOULD-level findings (advisory, non-failing): " + rfcAdvisories.join("; ")).to.be.an("array");',
@@ -265388,6 +265420,11 @@ ${error2.responseBody ?? ""}`
             method: "post",
             path: `/v3/collections/${cid}/items/`,
             retry: "none",
+            // The transport's cold /_api fallback only fires after the primary
+            // budget is exhausted; by then this loop has reconciled the item as
+            // absent (match == null), so a fallback resend cannot duplicate a
+            // committed create.
+            fallback: "auto",
             headers: { "X-Entity-Type": kind },
             body: this.buildItemCreateBody(item, parentId)
           });
@@ -265765,6 +265802,7 @@ var AccessTokenGatewayClient = class {
   orgMode;
   fetchImpl;
   secretMasker;
+  fallbackBaseUrl;
   maxRetries;
   retryBaseDelayMs;
   retryMaxDelayMs;
@@ -265780,6 +265818,8 @@ var AccessTokenGatewayClient = class {
     this.orgMode = options.orgMode ?? false;
     this.fetchImpl = options.fetchImpl ?? fetch;
     this.secretMasker = options.secretMasker ?? createSecretMasker([this.tokenProvider.current()]);
+    const fallbackEnv = typeof process !== "undefined" ? process.env?.POSTMAN_ITEM_CREATE_FALLBACK : void 0;
+    this.fallbackBaseUrl = fallbackEnv === "off" ? void 0 : options.fallbackBaseUrl?.replace(/\/+$/, "");
     this.maxRetries = options.maxRetries ?? 3;
     this.retryBaseDelayMs = options.retryBaseDelayMs ?? 400;
     this.retryMaxDelayMs = options.retryMaxDelayMs ?? 5e3;
@@ -265802,8 +265842,8 @@ var AccessTokenGatewayClient = class {
     }
     return headers;
   }
-  async send(request) {
-    const url = `${this.bifrostBaseUrl}/ws/proxy`;
+  async send(request, baseUrl) {
+    const url = `${baseUrl ?? this.bifrostBaseUrl}/ws/proxy`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
     try {
@@ -265833,6 +265873,50 @@ var AccessTokenGatewayClient = class {
    * 200 envelope carrying an inner collection-service error is treated as that
    * inner status. The auth-refresh-once path is independent of the retry budget.
    */
+  /**
+   * One cold, serial attempt against the fallback base URL after the primary
+   * budget is exhausted on a transient failure. Never hedged in parallel with
+   * the primary; only fires when the request would otherwise throw. Callers
+   * with `retry: 'none'` still reconcile first — the fallback attempt here is
+   * the resend, so it is only used for requests whose mutation is known
+   * idempotent or already reconciled by the caller's adopt-on-ambiguous loop.
+   */
+  async tryFallback(request) {
+    if (!this.fallbackBaseUrl) return null;
+    try {
+      return await this.send(request, this.fallbackBaseUrl);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Run the fallback attempt and classify its response the same way the
+   * primary path would. Returns the rebuilt success response, or null when the
+   * fallback also failed transiently (caller then throws the original error).
+   * Non-transient fallback failures (4xx, inner errors) surface as their own
+   * HttpError since they are the freshest authoritative answer.
+   */
+  fallbackEligible(request) {
+    if (!this.fallbackBaseUrl) return false;
+    const retryMode = request.retry ?? (request.method === "get" ? "safe" : "none");
+    return retryMode === "safe" || request.fallback === "auto";
+  }
+  async attemptFallback(request) {
+    if (!this.fallbackEligible(request)) return null;
+    const response = await this.tryFallback(request);
+    if (!response) return null;
+    const body2 = await response.text().catch(() => "");
+    if (response.ok) {
+      const innerStatus = detectInnerError(body2);
+      if (innerStatus !== null) {
+        if (isTransientGatewayError(innerStatus, body2)) return null;
+        throw this.toInnerHttpError(request, innerStatus, body2);
+      }
+      return this.rebuildResponse(response, body2);
+    }
+    if (isTransientGatewayError(response.status, body2)) return null;
+    throw this.toHttpError(request, response, body2);
+  }
   async request(request) {
     if (!this.tokenProvider.current() && this.tokenProvider.canRefresh()) {
       await this.tokenProvider.refresh();
@@ -265850,6 +265934,8 @@ var AccessTokenGatewayClient = class {
           await this.sleepImpl(delay);
           continue;
         }
+        const fallbackResponse2 = await this.attemptFallback(request);
+        if (fallbackResponse2) return fallbackResponse2;
         throw error2;
       }
       if (response.ok) {
@@ -265862,6 +265948,8 @@ var AccessTokenGatewayClient = class {
             await this.sleepImpl(delay);
             continue;
           }
+          const fallbackResponse2 = await this.attemptFallback(request);
+          if (fallbackResponse2) return fallbackResponse2;
           throw this.toInnerHttpError(request, innerStatus, okBody);
         }
         return this.rebuildResponse(response, okBody);
@@ -265890,6 +265978,8 @@ var AccessTokenGatewayClient = class {
         await this.sleepImpl(delay);
         continue;
       }
+      const fallbackResponse = await this.attemptFallback(request);
+      if (fallbackResponse) return fallbackResponse;
       throw this.toHttpError(request, response, body2);
     }
   }
@@ -312015,6 +312105,7 @@ function resolveInputs(env = process.env) {
     postmanStack,
     postmanApiBase: endpointProfile.apiBaseUrl,
     postmanBifrostBase: endpointProfile.bifrostBaseUrl,
+    postmanFallbackBase: endpointProfile.fallbackBaseUrl,
     postmanGatewayBase: endpointProfile.gatewayBaseUrl,
     postmanCliInstallUrl: endpointProfile.cliInstallUrl,
     postmanIapubBase: endpointProfile.iapubBaseUrl,
@@ -313772,6 +313863,7 @@ async function runAction(actionCore = core_exports, actionExec = exec_exports, a
         gateway: new AccessTokenGatewayClient({
           tokenProvider: probeProvider,
           bifrostBaseUrl: inputs.postmanBifrostBase,
+          fallbackBaseUrl: inputs.postmanFallbackBase,
           teamId: inputs.teamId || "",
           orgMode: false,
           secretMasker: createSecretMasker([inputs.postmanApiKey, inputs.postmanAccessToken])
@@ -313894,6 +313986,7 @@ function createBootstrapDependencies(inputs, factories, orgMode = false) {
   const gatewayClient = inputs.postmanAccessToken || inputs.postmanApiKey ? new AccessTokenGatewayClient({
     tokenProvider,
     bifrostBaseUrl: inputs.postmanBifrostBase,
+    fallbackBaseUrl: inputs.postmanFallbackBase,
     teamId: inputs.teamId || "",
     orgMode,
     secretMasker

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman-cse/onboarding-bootstrap",
-  "version": "2.9.7",
+  "version": "2.9.9",
   "description": "Bootstrap Postman workspaces, specs, and collections from OpenAPI.",
   "type": "module",
   "main": "dist/index.cjs",