api-ref: keep plugin ownership metadata internal

Hide plugin ownership metadata from the public ApiRef type while preserving internal ownership resolution for the builder-based API ref flow.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor

packages/frontend-plugin-api/report.api.md

@@ -194,7 +194,6 @@ export type ApiHolder = {
 export type ApiRef<T, TId extends string = string> = {
   readonly $$type?: '@backstage/ApiRef';
   readonly id: TId;
-  readonly pluginId?: string;
   readonly T: T;
 };
 

packages/frontend-plugin-api/src/apis/system/ApiRef.test.ts

@@ -27,6 +27,8 @@ describe('ApiRef', () => {
   });
 
   it('should not accept pluginId with deprecated config form', () => {
+    expect(createApiRef<string>({ id: 'abc' }).id).toBe('abc');
+
     // @ts-expect-error pluginId is only supported through .with(...)
     createApiRef<string>({ id: 'abc', pluginId: 'test' });
   });
@@ -45,9 +47,12 @@ describe('ApiRef', () => {
     const ref = createApiRef<string>().with({ id: 'abc', pluginId: 'test' });
     expect(ref.$$type).toBe('@backstage/ApiRef');
     expect(ref.id).toBe('abc');
-    expect(ref.pluginId).toBe('test');
     expect(String(ref)).toBe('apiRef{abc}');
     expect(ref.T).toBeNull();
+    expect((ref as { pluginId?: string }).pluginId).toBe('test');
+
+    // @ts-expect-error pluginId is internal runtime metadata
+    expect(ref.pluginId).toBe('test');
   });
 
   it('should infer literal ids with builder pattern', () => {

packages/frontend-plugin-api/src/apis/system/types.ts

@@ -22,7 +22,6 @@
 export type ApiRef<T, TId extends string = string> = {
   readonly $$type?: '@backstage/ApiRef';
   readonly id: TId;
-  readonly pluginId?: string;
   readonly T: T;
 };