feat(import): add stable per-resource source keys to the importer contract (#614)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

plugins/importer-postman/src/index.ts

@@ -49,6 +49,12 @@ export function convertPostman(contents: string): ImportPluginResponse | undefin
 
   const globalAuth = importAuth(root.auth);
 
+  const sourceKeys: Record<string, string> = {};
+  const trackSourceKey = (modelId: string, v: Record<string, unknown>, prefix: string) => {
+    const id = v.id ?? v._postman_id;
+    if (typeof id === "string" && id !== "") sourceKeys[modelId] = `${prefix}:${id}`;
+  };
+
   const exportResources: ExportResources = {
     workspaces: [],
     environments: [],
@@ -63,6 +69,7 @@ export function convertPostman(contents: string): ImportPluginResponse | undefin
     description: importDescription(info.description),
     ...globalAuth,
   };
+  trackSourceKey(workspace.id, info, "collection");
   exportResources.workspaces.push(workspace);
 
   // Create the base environment
@@ -92,6 +99,7 @@ export function convertPostman(contents: string): ImportPluginResponse | undefin
         name: v.name,
         folderId,
       };
+      trackSourceKey(folder.id, v, "item");
       exportResources.folders.push(folder);
       for (const child of v.item) {
         importItem(child, folder.id);
@@ -142,6 +150,7 @@ export function convertPostman(contents: string): ImportPluginResponse | undefin
         headers,
         ...requestAuth,
       };
+      trackSourceKey(request.id, v, "item");
       exportResources.httpRequests.push(request);
     } else {
       console.log("Unknown item", v, folderId);
@@ -156,7 +165,7 @@ export function convertPostman(contents: string): ImportPluginResponse | undefin
     convertTemplateSyntax(exportResources),
   ) as PartialImportResources;
 
-  return { resources };
+  return { resources, sourceKeys };
 }
 
 function convertUrl(rawUrl: unknown): Pick<HttpRequest, "url" | "urlParameters"> {

plugins/importer-postman/tests/fixtures/auth.output.json

@@ -300,5 +300,8 @@
       }
     ],
     "folders": []
+  },
+  "sourceKeys": {
+    "GENERATE_ID::WORKSPACE_0": "collection:9e6dfada-256c-49ea-a38f-7d1b05b7ca2d"
   }
 }

plugins/importer-postman/tests/fixtures/nested.output.json

@@ -88,5 +88,8 @@
         "folderId": "GENERATE_ID::FOLDER_0"
       }
     ]
+  },
+  "sourceKeys": {
+    "GENERATE_ID::WORKSPACE_1": "collection:9e6dfada-256c-49ea-a38f-7d1b05b7ca2d"
   }
 }

plugins/importer-postman/tests/fixtures/params.output.json

@@ -100,5 +100,8 @@
       }
     ],
     "folders": []
+  },
+  "sourceKeys": {
+    "GENERATE_ID::WORKSPACE_2": "collection:9e6dfada-256c-49ea-a38f-7d1b05b7ca2d"
   }
 }

plugins/importer-postman/tests/index.test.ts

@@ -87,4 +87,55 @@ describe("importer-postman", () => {
       }),
     ]);
   });
+
+  test("Keys items by their Postman ID, unchanged by a rename", () => {
+    const collection = (requestName: string) =>
+      JSON.stringify({
+        info: {
+          _postman_id: "collection-id",
+          name: "Keys",
+          schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+        },
+        item: [
+          {
+            id: "folder-id",
+            name: "Folder",
+            item: [
+              {
+                id: "request-id",
+                name: requestName,
+                request: { method: "GET", url: "https://yaak.app" },
+              },
+            ],
+          },
+        ],
+      });
+
+    const before = convertPostman(collection("Original"));
+    const after = convertPostman(collection("Renamed"));
+
+    const keyOf = (result: ReturnType<typeof convertPostman>, id: string | undefined) =>
+      id == null ? undefined : result?.sourceKeys?.[id];
+
+    expect(keyOf(before, before?.resources.httpRequests[0]?.id)).toBe("item:request-id");
+    expect(keyOf(after, after?.resources.httpRequests[0]?.id)).toBe("item:request-id");
+    expect(keyOf(before, before?.resources.folders[0]?.id)).toBe("item:folder-id");
+    expect(keyOf(before, before?.resources.workspaces[0]?.id)).toBe("collection:collection-id");
+  });
+
+  test("Omits keys for items the collection never identified", () => {
+    const result = convertPostman(
+      JSON.stringify({
+        info: {
+          name: "No IDs",
+          schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+        },
+        item: [{ name: "Request", request: { method: "GET", url: "https://yaak.app" } }],
+      }),
+    );
+
+    const requestId = result?.resources.httpRequests[0]?.id;
+    expect(requestId).toBeDefined();
+    expect(result?.sourceKeys).not.toHaveProperty(requestId as string);
+  });
 });