@postman-cse/onboarding-repo-sync 2.1.17 → 2.1.19

package/README.md

@@ -113,6 +113,8 @@ with:
   monitor-id: 1e2f3a4b-monitor-id
 ```
 
+Repo-sync supports public mocks for anonymous validation. An explicit `mock-url` must match one mock in the resolved workspace and reference the expected baseline collection and environment. Discovered and newly created mocks pass the same live visibility check. Private mocks, responses without a recognized visibility field, stale URLs, and identity mismatches fail before `mock-url` is emitted; repo-sync never places a Postman API key in a collection or environment to make a private mock callable.
+
 ### mTLS certificates for Postman CLI runs
 
 The generated CI workflow can run [Postman CLI collection runs](https://learning.postman.com/docs/postman-cli/postman-cli-collections/) with client certificates. Pass the cert material as inputs; when a GitHub token and repository context are available, the action persists them as repository secrets (`POSTMAN_SSL_CLIENT_CERT_B64`, `POSTMAN_SSL_CLIENT_KEY_B64`, `POSTMAN_SSL_CLIENT_PASSPHRASE`, `POSTMAN_SSL_EXTRA_CA_CERTS_B64`) for the generated workflow:
@@ -283,7 +285,7 @@ For `commit-and-push`, the push target is resolved from `current-ref`, then `GIT
 
 Mocks and monitors: when `baseline-collection-id`, `workspace-id`, and at least one environment are available, the action creates or reuses a mock server. When `smoke-collection-id` is also available, it creates or reuses a cloud smoke monitor unless `monitor-type: cli` is set. With an empty `monitor-cron`, a new cloud monitor is created disabled and triggered once per workflow invocation.
 
-Asset reuse priority is explicit inputs (`environment-uids-json`, `mock-url`, `monitor-id`), then live discovery by exact workspace-scoped name, collection UID, and environment UID, then create. Creates submit once and reconcile on ambiguous gateway errors; overlapping compatible creates inside one process share a single in-flight promise. Adopted environments are updated to the requested values. Mock environment assignment has no verified patch route, so a mock is reused only when its live environment already matches; mismatches are never claimed as converged. Concurrent jobs against the same workspace can still race because Postman does not expose create idempotency keys—serialize those workflows with GitHub Actions `concurrency` (or an equivalent CI lock) when duplicate mocks/monitors/environments would be harmful.
+Asset reuse priority is explicit inputs (`environment-uids-json`, `mock-url`, `monitor-id`), then live discovery by exact workspace-scoped name, collection UID, and environment UID, then create. Mock reuse is public-only: the gateway's live `published` field must confirm public visibility, and explicit URLs must match the expected workspace, collection, and environment. Private or unknown visibility fails closed without injecting credentials. Creates submit once and reconcile on ambiguous gateway errors; overlapping compatible creates inside one process share a single in-flight promise. Adopted environments are updated to the requested values. Mock environment assignment has no verified patch route, so a mock is reused only when its live environment already matches; mismatches are never claimed as converged. Concurrent jobs against the same workspace can still race because Postman does not expose create idempotency keys—serialize those workflows with GitHub Actions `concurrency` (or an equivalent CI lock) when duplicate mocks/monitors/environments would be harmful.
 
 Deeper reference:
 

package/dist/action.cjs

@@ -136941,6 +136941,25 @@ var PostmanAssetsClient = class {
 };
 
 // src/lib/postman/postman-gateway-assets-client.ts
+var MockContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MockContractError";
+  }
+};
+function requirePublicMock(mock) {
+  if (mock.visibility === "private") {
+    throw new MockContractError(
+      `MOCK_NOT_PUBLIC: Mock ${mock.uid} is private. Make it public in Postman or remove/rename it so repo-sync can create the canonical public mock.`
+    );
+  }
+  if (mock.visibility !== "public") {
+    throw new MockContractError(
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+    );
+  }
+  return mock;
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -137122,6 +137141,41 @@ var PostmanGatewayAssetsClient = class {
     const id = record.uid ?? record.id;
     return typeof id === "string" ? id.trim() : String(id ?? "").trim();
   }
+  decodeMockRecord(value, operation) {
+    const record = this.asRecord(value);
+    if (!record) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a non-object mock record`
+      );
+    }
+    const uid = this.idOf(record);
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    const collection = typeof record.collection === "string" ? record.collection.trim() : "";
+    const mockUrl = typeof (record.url ?? record.mockUrl) === "string" ? String(record.url ?? record.mockUrl).trim() : "";
+    const environment = typeof record.environment === "string" ? record.environment.trim() : "";
+    if (!uid) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a mock without a UID`
+      );
+    }
+    if (!name) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a name`
+      );
+    }
+    if (!collection) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a collection UID`
+      );
+    }
+    if (!mockUrl) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a URL`
+      );
+    }
+    const visibility = typeof record.published === "boolean" ? record.published ? "public" : "private" : "unknown";
+    return { uid, name, collection, mockUrl, environment, visibility };
+  }
   /**
    * Reduce a Postman public uid (`<owner>-<uuid>`, 6 hyphen groups) to the bare
    * model id (`<uuid>`, 5 groups), mirroring `decomposeUID`. Used ONLY for the
@@ -137422,7 +137476,8 @@ var PostmanGatewayAssetsClient = class {
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        return { uid: existing.uid, url: existing.mockUrl };
+        const reusable = requirePublicMock(existing);
+        return { uid: reusable.uid, url: reusable.mockUrl };
       }
       const body = {
         name: mockName,
@@ -137445,13 +137500,12 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const uid = this.idOf(record);
-        if (!uid) {
-          throw new Error("Mock create did not return a UID");
-        }
+        const created = requirePublicMock(
+          this.decodeMockRecord(record, "Mock create")
+        );
         return {
-          uid,
-          url: String(record?.url ?? record?.mockUrl ?? "").trim()
+          uid: created.uid,
+          url: created.mockUrl
         };
       };
       try {
@@ -137462,7 +137516,8 @@ var PostmanGatewayAssetsClient = class {
           error2
         );
         if (adopted) {
-          return { uid: adopted.uid, url: adopted.mockUrl };
+          const reusable = requirePublicMock(adopted);
+          return { uid: reusable.uid, url: reusable.mockUrl };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -137478,14 +137533,14 @@ var PostmanGatewayAssetsClient = class {
       method: "get",
       path: `/mocks?workspace=${this.workspaceId}`
     });
-    const items = Array.isArray(response) ? response : Array.isArray(this.asRecord(response)?.data) ? this.asRecord(response).data : [];
-    return items.map((raw) => this.asRecord(raw)).filter((m) => m !== null).map((m) => ({
-      uid: this.idOf(m),
-      name: String(m.name ?? ""),
-      collection: String(m.collection ?? ""),
-      mockUrl: String(m.url ?? m.mockUrl ?? ""),
-      environment: String(m.environment ?? "")
-    }));
+    const envelope = this.asRecord(response);
+    const items = Array.isArray(response) ? response : Array.isArray(envelope?.data) ? envelope.data : null;
+    if (!items) {
+      throw new MockContractError(
+        "CONTRACT_MOCK_RESPONSE_INVALID: Mock list envelope must be an array or contain a data array"
+      );
+    }
+    return items.map((raw) => this.decodeMockRecord(raw, "Mock list"));
   }
   /**
    * Delete an environment through the sync service (GC path). The path id is
@@ -137539,7 +137594,7 @@ var PostmanGatewayAssetsClient = class {
       `workspace ${this.workspaceId}, name "${mockName}", collection ${want}, and environment ${environment || "(none)"}`,
       matches
     );
-    return match ? { uid: match.uid, mockUrl: match.mockUrl } : null;
+    return match;
   }
   // --- monitors (service: monitors; collection-based = jobTemplates) ---
   /** Map raw jobTemplate records to the facade shape; `collection` is a flat public uid. */
@@ -138469,6 +138524,61 @@ function resolveRepoSyncMasker(dependencies) {
 function causeText(cause) {
   return cause instanceof Error ? cause.message : String(cause);
 }
+function normalizeMockUrl(value, source) {
+  let url;
+  try {
+    url = new URL(String(value || "").trim());
+  } catch {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} is not a valid absolute URL`
+    );
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} must be an HTTPS URL without credentials, query parameters, or a fragment`
+    );
+  }
+  url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
+  return url.toString();
+}
+function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+  const normalized = normalizeMockUrl(explicitUrl, "mock-url");
+  const matches = mocks.filter(
+    (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
+  );
+  if (matches.length === 0) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_NOT_FOUND: mock-url was not found in the resolved workspace mock inventory`
+    );
+  }
+  if (matches.length > 1) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_AMBIGUOUS: mock-url matched multiple workspace mocks (${matches.map((mock) => mock.uid).join(", ")})`
+    );
+  }
+  const match = matches[0];
+  if (match.collection !== collectionUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references collection ${match.collection || "(none)"}, expected ${collectionUid}`
+    );
+  }
+  if (match.environment !== environmentUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
+    );
+  }
+  return requirePublicMock(match);
+}
+function shouldRetryMockCreate(error2) {
+  if (error2 instanceof MockContractError) return false;
+  if (error2 instanceof HttpError) {
+    return error2.status === 408 || error2.status === 429 || error2.status >= 500;
+  }
+  if (error2 instanceof Error && error2.message.startsWith("Multiple mocks match ")) {
+    return false;
+  }
+  return true;
+}
 function toOneLineDisplay(value) {
   return String(value ?? "").replace(/[\r\n\u0085\u2028\u2029\v\f]+/g, " ").replace(/[ \t]{2,}/g, " ").trim();
 }
@@ -140095,20 +140205,37 @@ async function runRepoSyncInner(inputs, dependencies) {
       let resolvedMockUrl = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
-        resolvedMockUrl = inputs.mockUrl;
+        let mocks;
+        try {
+          mocks = await dependencies.postman.listMocks();
+        } catch (error2) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Explicit mock-url lookup",
+              entity: `mock-url ${inputs.mockUrl} workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`,
+              cause: error2,
+              remediation: "verify the URL and mock access then rerun",
+              mask
+            }),
+            { cause: error2 }
+          );
+        }
+        resolvedMockUrl = resolveExplicitPublicMock(
+          mocks,
+          inputs.mockUrl,
+          inputs.baselineCollectionId,
+          mockEnvUid
+        ).mockUrl;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
+        let discovered;
         try {
-          const discovered = await dependencies.postman.findMockByCollection(
+          discovered = await dependencies.postman.findMockByCollection(
             inputs.baselineCollectionId,
             mockEnvUid,
             mockName
           );
-          if (discovered) {
-            resolvedMockUrl = discovered.mockUrl;
-            dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
-          }
         } catch (error2) {
           throw new Error(
             formatOrchestrationIssue({
@@ -140121,6 +140248,10 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error2 }
           );
         }
+        if (discovered) {
+          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
+        }
       }
       if (!resolvedMockUrl) {
         const mockEntity = `mock "${mockName}" workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`;
@@ -140137,6 +140268,7 @@ async function runRepoSyncInner(inputs, dependencies) {
               maxAttempts: 3,
               delayMs: 2e3,
               backoffMultiplier: 2,
+              shouldRetry: (error2) => shouldRetryMockCreate(error2),
               onRetry: ({ attempt, maxAttempts, error: error2 }) => {
                 dependencies.core.warning(
                   formatOrchestrationIssue({

package/dist/cli.cjs

@@ -135046,6 +135046,25 @@ var PostmanAssetsClient = class {
 };
 
 // src/lib/postman/postman-gateway-assets-client.ts
+var MockContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MockContractError";
+  }
+};
+function requirePublicMock(mock) {
+  if (mock.visibility === "private") {
+    throw new MockContractError(
+      `MOCK_NOT_PUBLIC: Mock ${mock.uid} is private. Make it public in Postman or remove/rename it so repo-sync can create the canonical public mock.`
+    );
+  }
+  if (mock.visibility !== "public") {
+    throw new MockContractError(
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+    );
+  }
+  return mock;
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -135227,6 +135246,41 @@ var PostmanGatewayAssetsClient = class {
     const id = record.uid ?? record.id;
     return typeof id === "string" ? id.trim() : String(id ?? "").trim();
   }
+  decodeMockRecord(value, operation) {
+    const record = this.asRecord(value);
+    if (!record) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a non-object mock record`
+      );
+    }
+    const uid = this.idOf(record);
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    const collection = typeof record.collection === "string" ? record.collection.trim() : "";
+    const mockUrl = typeof (record.url ?? record.mockUrl) === "string" ? String(record.url ?? record.mockUrl).trim() : "";
+    const environment = typeof record.environment === "string" ? record.environment.trim() : "";
+    if (!uid) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a mock without a UID`
+      );
+    }
+    if (!name) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a name`
+      );
+    }
+    if (!collection) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a collection UID`
+      );
+    }
+    if (!mockUrl) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a URL`
+      );
+    }
+    const visibility = typeof record.published === "boolean" ? record.published ? "public" : "private" : "unknown";
+    return { uid, name, collection, mockUrl, environment, visibility };
+  }
   /**
    * Reduce a Postman public uid (`<owner>-<uuid>`, 6 hyphen groups) to the bare
    * model id (`<uuid>`, 5 groups), mirroring `decomposeUID`. Used ONLY for the
@@ -135527,7 +135581,8 @@ var PostmanGatewayAssetsClient = class {
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        return { uid: existing.uid, url: existing.mockUrl };
+        const reusable = requirePublicMock(existing);
+        return { uid: reusable.uid, url: reusable.mockUrl };
       }
       const body = {
         name: mockName,
@@ -135550,13 +135605,12 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const uid = this.idOf(record);
-        if (!uid) {
-          throw new Error("Mock create did not return a UID");
-        }
+        const created = requirePublicMock(
+          this.decodeMockRecord(record, "Mock create")
+        );
         return {
-          uid,
-          url: String(record?.url ?? record?.mockUrl ?? "").trim()
+          uid: created.uid,
+          url: created.mockUrl
         };
       };
       try {
@@ -135567,7 +135621,8 @@ var PostmanGatewayAssetsClient = class {
           error
         );
         if (adopted) {
-          return { uid: adopted.uid, url: adopted.mockUrl };
+          const reusable = requirePublicMock(adopted);
+          return { uid: reusable.uid, url: reusable.mockUrl };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -135583,14 +135638,14 @@ var PostmanGatewayAssetsClient = class {
       method: "get",
       path: `/mocks?workspace=${this.workspaceId}`
     });
-    const items = Array.isArray(response) ? response : Array.isArray(this.asRecord(response)?.data) ? this.asRecord(response).data : [];
-    return items.map((raw) => this.asRecord(raw)).filter((m) => m !== null).map((m) => ({
-      uid: this.idOf(m),
-      name: String(m.name ?? ""),
-      collection: String(m.collection ?? ""),
-      mockUrl: String(m.url ?? m.mockUrl ?? ""),
-      environment: String(m.environment ?? "")
-    }));
+    const envelope = this.asRecord(response);
+    const items = Array.isArray(response) ? response : Array.isArray(envelope?.data) ? envelope.data : null;
+    if (!items) {
+      throw new MockContractError(
+        "CONTRACT_MOCK_RESPONSE_INVALID: Mock list envelope must be an array or contain a data array"
+      );
+    }
+    return items.map((raw) => this.decodeMockRecord(raw, "Mock list"));
   }
   /**
    * Delete an environment through the sync service (GC path). The path id is
@@ -135644,7 +135699,7 @@ var PostmanGatewayAssetsClient = class {
       `workspace ${this.workspaceId}, name "${mockName}", collection ${want}, and environment ${environment || "(none)"}`,
       matches
     );
-    return match ? { uid: match.uid, mockUrl: match.mockUrl } : null;
+    return match;
   }
   // --- monitors (service: monitors; collection-based = jobTemplates) ---
   /** Map raw jobTemplate records to the facade shape; `collection` is a flat public uid. */
@@ -136522,6 +136577,61 @@ function resolveRepoSyncMasker(dependencies) {
 function causeText(cause) {
   return cause instanceof Error ? cause.message : String(cause);
 }
+function normalizeMockUrl(value, source) {
+  let url;
+  try {
+    url = new URL(String(value || "").trim());
+  } catch {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} is not a valid absolute URL`
+    );
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} must be an HTTPS URL without credentials, query parameters, or a fragment`
+    );
+  }
+  url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
+  return url.toString();
+}
+function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+  const normalized = normalizeMockUrl(explicitUrl, "mock-url");
+  const matches = mocks.filter(
+    (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
+  );
+  if (matches.length === 0) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_NOT_FOUND: mock-url was not found in the resolved workspace mock inventory`
+    );
+  }
+  if (matches.length > 1) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_AMBIGUOUS: mock-url matched multiple workspace mocks (${matches.map((mock) => mock.uid).join(", ")})`
+    );
+  }
+  const match = matches[0];
+  if (match.collection !== collectionUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references collection ${match.collection || "(none)"}, expected ${collectionUid}`
+    );
+  }
+  if (match.environment !== environmentUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
+    );
+  }
+  return requirePublicMock(match);
+}
+function shouldRetryMockCreate(error) {
+  if (error instanceof MockContractError) return false;
+  if (error instanceof HttpError) {
+    return error.status === 408 || error.status === 429 || error.status >= 500;
+  }
+  if (error instanceof Error && error.message.startsWith("Multiple mocks match ")) {
+    return false;
+  }
+  return true;
+}
 function toOneLineDisplay(value) {
   return String(value ?? "").replace(/[\r\n\u0085\u2028\u2029\v\f]+/g, " ").replace(/[ \t]{2,}/g, " ").trim();
 }
@@ -138005,20 +138115,37 @@ async function runRepoSyncInner(inputs, dependencies) {
       let resolvedMockUrl = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
-        resolvedMockUrl = inputs.mockUrl;
+        let mocks;
+        try {
+          mocks = await dependencies.postman.listMocks();
+        } catch (error) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Explicit mock-url lookup",
+              entity: `mock-url ${inputs.mockUrl} workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`,
+              cause: error,
+              remediation: "verify the URL and mock access then rerun",
+              mask
+            }),
+            { cause: error }
+          );
+        }
+        resolvedMockUrl = resolveExplicitPublicMock(
+          mocks,
+          inputs.mockUrl,
+          inputs.baselineCollectionId,
+          mockEnvUid
+        ).mockUrl;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
+        let discovered;
         try {
-          const discovered = await dependencies.postman.findMockByCollection(
+          discovered = await dependencies.postman.findMockByCollection(
             inputs.baselineCollectionId,
             mockEnvUid,
             mockName
           );
-          if (discovered) {
-            resolvedMockUrl = discovered.mockUrl;
-            dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
-          }
         } catch (error) {
           throw new Error(
             formatOrchestrationIssue({
@@ -138031,6 +138158,10 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error }
           );
         }
+        if (discovered) {
+          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
+        }
       }
       if (!resolvedMockUrl) {
         const mockEntity = `mock "${mockName}" workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`;
@@ -138047,6 +138178,7 @@ async function runRepoSyncInner(inputs, dependencies) {
               maxAttempts: 3,
               delayMs: 2e3,
               backoffMultiplier: 2,
+              shouldRetry: (error) => shouldRetryMockCreate(error),
               onRetry: ({ attempt, maxAttempts, error }) => {
                 dependencies.core.warning(
                   formatOrchestrationIssue({

package/dist/index.cjs

@@ -136963,6 +136963,25 @@ var PostmanAssetsClient = class {
 };
 
 // src/lib/postman/postman-gateway-assets-client.ts
+var MockContractError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MockContractError";
+  }
+};
+function requirePublicMock(mock) {
+  if (mock.visibility === "private") {
+    throw new MockContractError(
+      `MOCK_NOT_PUBLIC: Mock ${mock.uid} is private. Make it public in Postman or remove/rename it so repo-sync can create the canonical public mock.`
+    );
+  }
+  if (mock.visibility !== "public") {
+    throw new MockContractError(
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+    );
+  }
+  return mock;
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -137144,6 +137163,41 @@ var PostmanGatewayAssetsClient = class {
     const id = record.uid ?? record.id;
     return typeof id === "string" ? id.trim() : String(id ?? "").trim();
   }
+  decodeMockRecord(value, operation) {
+    const record = this.asRecord(value);
+    if (!record) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a non-object mock record`
+      );
+    }
+    const uid = this.idOf(record);
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    const collection = typeof record.collection === "string" ? record.collection.trim() : "";
+    const mockUrl = typeof (record.url ?? record.mockUrl) === "string" ? String(record.url ?? record.mockUrl).trim() : "";
+    const environment = typeof record.environment === "string" ? record.environment.trim() : "";
+    if (!uid) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned a mock without a UID`
+      );
+    }
+    if (!name) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a name`
+      );
+    }
+    if (!collection) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a collection UID`
+      );
+    }
+    if (!mockUrl) {
+      throw new MockContractError(
+        `CONTRACT_MOCK_RESPONSE_INVALID: ${operation} returned mock ${uid} without a URL`
+      );
+    }
+    const visibility = typeof record.published === "boolean" ? record.published ? "public" : "private" : "unknown";
+    return { uid, name, collection, mockUrl, environment, visibility };
+  }
   /**
    * Reduce a Postman public uid (`<owner>-<uuid>`, 6 hyphen groups) to the bare
    * model id (`<uuid>`, 5 groups), mirroring `decomposeUID`. Used ONLY for the
@@ -137444,7 +137498,8 @@ var PostmanGatewayAssetsClient = class {
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        return { uid: existing.uid, url: existing.mockUrl };
+        const reusable = requirePublicMock(existing);
+        return { uid: reusable.uid, url: reusable.mockUrl };
       }
       const body = {
         name: mockName,
@@ -137467,13 +137522,12 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const uid = this.idOf(record);
-        if (!uid) {
-          throw new Error("Mock create did not return a UID");
-        }
+        const created = requirePublicMock(
+          this.decodeMockRecord(record, "Mock create")
+        );
         return {
-          uid,
-          url: String(record?.url ?? record?.mockUrl ?? "").trim()
+          uid: created.uid,
+          url: created.mockUrl
         };
       };
       try {
@@ -137484,7 +137538,8 @@ var PostmanGatewayAssetsClient = class {
           error2
         );
         if (adopted) {
-          return { uid: adopted.uid, url: adopted.mockUrl };
+          const reusable = requirePublicMock(adopted);
+          return { uid: reusable.uid, url: reusable.mockUrl };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -137500,14 +137555,14 @@ var PostmanGatewayAssetsClient = class {
       method: "get",
       path: `/mocks?workspace=${this.workspaceId}`
     });
-    const items = Array.isArray(response) ? response : Array.isArray(this.asRecord(response)?.data) ? this.asRecord(response).data : [];
-    return items.map((raw) => this.asRecord(raw)).filter((m) => m !== null).map((m) => ({
-      uid: this.idOf(m),
-      name: String(m.name ?? ""),
-      collection: String(m.collection ?? ""),
-      mockUrl: String(m.url ?? m.mockUrl ?? ""),
-      environment: String(m.environment ?? "")
-    }));
+    const envelope = this.asRecord(response);
+    const items = Array.isArray(response) ? response : Array.isArray(envelope?.data) ? envelope.data : null;
+    if (!items) {
+      throw new MockContractError(
+        "CONTRACT_MOCK_RESPONSE_INVALID: Mock list envelope must be an array or contain a data array"
+      );
+    }
+    return items.map((raw) => this.decodeMockRecord(raw, "Mock list"));
   }
   /**
    * Delete an environment through the sync service (GC path). The path id is
@@ -137561,7 +137616,7 @@ var PostmanGatewayAssetsClient = class {
       `workspace ${this.workspaceId}, name "${mockName}", collection ${want}, and environment ${environment || "(none)"}`,
       matches
     );
-    return match ? { uid: match.uid, mockUrl: match.mockUrl } : null;
+    return match;
   }
   // --- monitors (service: monitors; collection-based = jobTemplates) ---
   /** Map raw jobTemplate records to the facade shape; `collection` is a flat public uid. */
@@ -138491,6 +138546,61 @@ function resolveRepoSyncMasker(dependencies) {
 function causeText(cause) {
   return cause instanceof Error ? cause.message : String(cause);
 }
+function normalizeMockUrl(value, source) {
+  let url;
+  try {
+    url = new URL(String(value || "").trim());
+  } catch {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} is not a valid absolute URL`
+    );
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_INVALID: ${source} must be an HTTPS URL without credentials, query parameters, or a fragment`
+    );
+  }
+  url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
+  return url.toString();
+}
+function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+  const normalized = normalizeMockUrl(explicitUrl, "mock-url");
+  const matches = mocks.filter(
+    (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
+  );
+  if (matches.length === 0) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_NOT_FOUND: mock-url was not found in the resolved workspace mock inventory`
+    );
+  }
+  if (matches.length > 1) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_URL_AMBIGUOUS: mock-url matched multiple workspace mocks (${matches.map((mock) => mock.uid).join(", ")})`
+    );
+  }
+  const match = matches[0];
+  if (match.collection !== collectionUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references collection ${match.collection || "(none)"}, expected ${collectionUid}`
+    );
+  }
+  if (match.environment !== environmentUid) {
+    throw new MockContractError(
+      `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
+    );
+  }
+  return requirePublicMock(match);
+}
+function shouldRetryMockCreate(error2) {
+  if (error2 instanceof MockContractError) return false;
+  if (error2 instanceof HttpError) {
+    return error2.status === 408 || error2.status === 429 || error2.status >= 500;
+  }
+  if (error2 instanceof Error && error2.message.startsWith("Multiple mocks match ")) {
+    return false;
+  }
+  return true;
+}
 function toOneLineDisplay(value) {
   return String(value ?? "").replace(/[\r\n\u0085\u2028\u2029\v\f]+/g, " ").replace(/[ \t]{2,}/g, " ").trim();
 }
@@ -140117,20 +140227,37 @@ async function runRepoSyncInner(inputs, dependencies) {
       let resolvedMockUrl = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
-        resolvedMockUrl = inputs.mockUrl;
+        let mocks;
+        try {
+          mocks = await dependencies.postman.listMocks();
+        } catch (error2) {
+          throw new Error(
+            formatOrchestrationIssue({
+              operation: "Explicit mock-url lookup",
+              entity: `mock-url ${inputs.mockUrl} workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`,
+              cause: error2,
+              remediation: "verify the URL and mock access then rerun",
+              mask
+            }),
+            { cause: error2 }
+          );
+        }
+        resolvedMockUrl = resolveExplicitPublicMock(
+          mocks,
+          inputs.mockUrl,
+          inputs.baselineCollectionId,
+          mockEnvUid
+        ).mockUrl;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
+        let discovered;
         try {
-          const discovered = await dependencies.postman.findMockByCollection(
+          discovered = await dependencies.postman.findMockByCollection(
             inputs.baselineCollectionId,
             mockEnvUid,
             mockName
           );
-          if (discovered) {
-            resolvedMockUrl = discovered.mockUrl;
-            dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
-          }
         } catch (error2) {
           throw new Error(
             formatOrchestrationIssue({
@@ -140143,6 +140270,10 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error2 }
           );
         }
+        if (discovered) {
+          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
+        }
       }
       if (!resolvedMockUrl) {
         const mockEntity = `mock "${mockName}" workspace ${inputs.workspaceId} collection ${inputs.baselineCollectionId} environment ${mockEnvUid}`;
@@ -140159,6 +140290,7 @@ async function runRepoSyncInner(inputs, dependencies) {
               maxAttempts: 3,
               delayMs: 2e3,
               backoffMultiplier: 2,
+              shouldRetry: (error2) => shouldRetryMockCreate(error2),
               onRetry: ({ attempt, maxAttempts, error: error2 }) => {
                 dependencies.core.warning(
                   formatOrchestrationIssue({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman-cse/onboarding-repo-sync",
-  "version": "2.1.17",
+  "version": "2.1.19",
   "description": "Postman repo sync GitHub Action.",
   "type": "module",
   "main": "dist/index.cjs",