fix(common): resolve api-extractor report and doc warnings

Tag LocatedAttachmentRecord as @Alpha, use a qualified @link to
AttachmentQueue.saveFile, and update etc/common.api.md for the new
attachment transport API.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: khawarizmus

packages/common/etc/common.api.md

@@ -105,6 +105,14 @@ export class AttachmentQueue {
         id?: string;
         updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
     }): Promise<AttachmentRecord>;
+    saveFileFromUri(input: {
+        localUri: string;
+        fileExtension: string;
+        mediaType?: string;
+        metaData?: string;
+        id?: string;
+        updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
+    }): Promise<AttachmentRecord>;
     startSync(): Promise<void>;
     stopSync(): Promise<void>;
     readonly syncIntervalMs: number;
@@ -127,6 +135,7 @@ export interface AttachmentQueueOptions {
     syncIntervalMs?: number;
     syncThrottleDuration?: number;
     tableName?: string;
+    transportAdapter?: AttachmentTransportAdapter;
     watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise<void>, signal: AbortSignal) => void;
 }
 
@@ -178,6 +187,12 @@ export interface AttachmentTableOptions extends Omit<TableOptions, 'name' | 'col
 // @alpha
 export type AttachmentTableRecord = RowType<AttachmentTable>;
 
+// @alpha
+export interface AttachmentTransportAdapter {
+    download(attachment: LocatedAttachmentRecord): Promise<void>;
+    upload(attachment: LocatedAttachmentRecord): Promise<void>;
+}
+
 // @public (undocumented)
 export type BaseColumnType<T extends number | string | null> = {
     type: ColumnType;
@@ -242,6 +257,15 @@ export interface BatchedUpdateNotification {
     tables: string[];
 }
 
+// @alpha
+export class BufferedAttachmentTransport implements AttachmentTransportAdapter {
+    constructor(localStorage: LocalStorageAdapter, remoteStorage: RemoteStorageAdapter);
+    // (undocumented)
+    download(attachment: LocatedAttachmentRecord): Promise<void>;
+    // (undocumented)
+    upload(attachment: LocatedAttachmentRecord): Promise<void>;
+}
+
 // @public (undocumented)
 export class Column {
     constructor(options: ColumnOptions);
@@ -651,11 +675,17 @@ export interface LocalStorageAdapter {
     getLocalUri(filename: string): string;
     initialize(): Promise<void>;
     makeDir(path: string): Promise<void>;
+    moveFile?(sourceUri: string, targetUri: string): Promise<number>;
     readFile(filePath: string): Promise<ArrayBuffer>;
     rmDir(path: string): Promise<void>;
     saveFile(filePath: string, data: AttachmentData): Promise<number>;
 }
 
+// @alpha
+export type LocatedAttachmentRecord = AttachmentRecord & {
+    localUri: string;
+};
+
 // @public (undocumented)
 export abstract class LockContext implements SqlExecutor, DBGetUtils {
     // (undocumented)

packages/common/src/attachments/AttachmentQueue.ts

@@ -489,9 +489,9 @@ export class AttachmentQueue {
    * Registers a file that already exists on disk and queues it for upload, moving it
    * into managed storage without loading it into memory.
    *
-   * Prefer this over {@link saveFile} for large, app-originated files (recordings,
-   * videos): it avoids reading the file into an `ArrayBuffer` just to write it back to
-   * disk. Requires the local storage adapter to implement `moveFile`.
+   * Prefer this over {@link AttachmentQueue.saveFile} for large, app-originated files
+   * (recordings, videos): it avoids reading the file into an `ArrayBuffer` just to write
+   * it back to disk. Requires the local storage adapter to implement `moveFile`.
    *
    * @param options - File registration options
    * @returns Promise resolving to the created attachment record

packages/common/src/attachments/AttachmentTransportAdapter.ts

@@ -5,6 +5,8 @@ import { AttachmentRecord } from './Schema.js';
  *
  * The syncing service assigns `localUri` before invoking a transport download,
  * so implementations always receive both the metadata and the destination path.
+ *
+ * @alpha
  */
 export type LocatedAttachmentRecord = AttachmentRecord & { localUri: string };