@postman-cse/onboarding-bootstrap 2.9.7 → 2.9.8

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"
@@ -265363,6 +265365,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 +265747,7 @@ var AccessTokenGatewayClient = class {
   orgMode;
   fetchImpl;
   secretMasker;
+  fallbackBaseUrl;
   maxRetries;
   retryBaseDelayMs;
   retryMaxDelayMs;
@@ -265755,6 +265763,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 +265787,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 +265818,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 +265879,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 +265893,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 +265923,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 +312050,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 +313805,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 +313928,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"
@@ -263681,6 +263683,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 +264065,7 @@ var AccessTokenGatewayClient = class {
   orgMode;
   fetchImpl;
   secretMasker;
+  fallbackBaseUrl;
   maxRetries;
   retryBaseDelayMs;
   retryMaxDelayMs;
@@ -264073,6 +264081,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 +264105,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 +264136,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 +264197,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 +264211,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 +264241,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 +310362,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 +312081,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"
@@ -265388,6 +265390,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 +265772,7 @@ var AccessTokenGatewayClient = class {
   orgMode;
   fetchImpl;
   secretMasker;
+  fallbackBaseUrl;
   maxRetries;
   retryBaseDelayMs;
   retryMaxDelayMs;
@@ -265780,6 +265788,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 +265812,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 +265843,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 +265904,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 +265918,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 +265948,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 +312075,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 +313833,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 +313956,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.8",
   "description": "Bootstrap Postman workspaces, specs, and collections from OpenAPI.",
   "type": "module",
   "main": "dist/index.cjs",