@powerhousedao/reactor-attachments 6.2.2-dev.4 → 6.2.2-dev.41

package/dist/client.d.ts

@@ -1,6 +1,37 @@
-import { A as ReserveAttachmentOptions, B as SizeMismatch, C as AttachmentMetadata, D as AttachmentUploadResult, E as AttachmentTransportConfig, F as AttachmentNotFound, I as AttachmentPending, L as HashMismatch, M as TransportResponse, N as UploadFirstReserveAttachmentOptions, O as HashFirstReserveAttachmentOptions, P as AttachmentAlreadyExists, R as InvalidAttachmentRef, S as AttachmentHeader, T as AttachmentStatus, V as UploadTooLarge, _ as IAttachmentTransport, a as RemoteAttachmentUpload, b as IAttachmentUploadFactory, c as SwitchboardAttachmentTransport, d as createRef, f as parseRef, g as IAttachmentStore, h as IAttachmentService, i as RemoteAttachmentUploadFactory, j as TransportFetchResult, k as Reservation, l as SwitchboardTransportConfig, m as IAttachmentReader, n as createRemoteAttachmentService, o as RemoteReservationStore, p as AttachmentService, r as RemoteAttachmentStore, s as SwitchboardClientConfig, t as NullAttachmentTransport, u as ParsedRef, v as IAttachmentTransportFactory, w as AttachmentResponse, x as IReservationStore, y as IAttachmentUpload, z as ReservationNotFound } from "./null-attachment-transport-BBhQIk5A.js";
+import { $ as UploadTooLarge, A as AttachmentHeader, B as ReserveAttachmentOptions, C as IAttachmentUploadFactory, D as AttachmentDownloadOptions, F as AttachmentTransportConfig, G as AttachmentNotFound, H as TransportResponse, I as AttachmentUploadResult, J as AttachmentTransferStage, K as AttachmentPending, L as AttachmentUploadTarget, M as AttachmentResponse, N as AttachmentStatus, O as AttachmentDownloadTarget, P as AttachmentTargetHeaders, Q as SizeMismatch, R as HashFirstReserveAttachmentOptions, S as IAttachmentUpload, U as UploadFirstReserveAttachmentOptions, V as TransportFetchResult, W as AttachmentAlreadyExists, X as InvalidAttachmentRef, Y as HashMismatch, Z as ReservationNotFound, _ as IAttachmentReader, a as RemoteAttachmentUpload, b as IAttachmentTransport, c as SwitchboardAttachmentTransport, d as createRef, f as parseRef, h as parseAttachmentUploadTarget, i as RemoteAttachmentUploadFactory, j as AttachmentMetadata, k as AttachmentDownloadTargetOptions, l as SwitchboardTransportConfig, m as parseAttachmentDownloadTarget, n as createRemoteAttachmentService, o as RemoteReservationStore, p as AttachmentService, q as AttachmentTransferError, r as RemoteAttachmentStore, s as SwitchboardClientConfig, t as NullAttachmentTransport, u as ParsedRef, v as IAttachmentService, w as IReservationStore, x as IAttachmentTransportFactory, y as IAttachmentStore, z as Reservation } from "./null-attachment-transport-D1Bj3hLU.js";
 import { AttachmentHash, AttachmentRef } from "@powerhousedao/reactor";
 
+//#region src/concurrency.d.ts
+/**
+ * Ordered result of one batch item. `index` always mirrors the input
+ * position, so callers can correlate results with inputs regardless of
+ * completion order, and successes are retained when siblings fail.
+ */
+type BatchItemResult<R> = {
+  index: number;
+  status: "fulfilled";
+  value: R;
+} | {
+  index: number;
+  status: "rejected";
+  error: unknown;
+};
+type RunWithConcurrencyOptions = {
+  /** Maximum simultaneously running workers. Must be a positive integer. */concurrency: number;
+  /**
+   * Whole-batch cancellation: unstarted items are rejected with the signal's
+   * reason without ever starting, while already-started items keep running —
+   * per-item signals are the mechanism for interrupting active work.
+   */
+  signal?: AbortSignal;
+};
+/**
+ * Runs `worker` over `items` with a hard upper bound on simultaneous
+ * executions. Bounding starts (not just transfers) is what keeps memory flat:
+ * an item's preprocessing (hashing/buffering) only begins when a slot frees.
+ */
+declare function runWithConcurrency<T, R>(items: readonly T[], worker: (item: T, index: number) => Promise<R>, options: RunWithConcurrencyOptions): Promise<BatchItemResult<R>[]>;
+//#endregion
 //#region src/client.d.ts
 type PreprocessResult = {
   ref: AttachmentRef;
@@ -10,14 +41,106 @@ type PreprocessResult = {
   data: ReadableStream<Uint8Array>;
   stream: () => ReadableStream<Uint8Array>;
 };
+type AttachmentStage = "hashing" | "reserving" | "uploading" | "requesting-download-target" | "downloading" | "done" | "error";
+type AttachmentStageListener = (stage: AttachmentStage) => void;
+type AttachmentUploadInput = {
+  file: Blob;
+  fileName?: string;
+  mimeType?: string; /** Per-item cancellation, checked between stages. */
+  signal?: AbortSignal;
+};
+/**
+ * Every remote download names the document that authorizes its ref; batches
+ * may freely mix documents because the anchor travels with each item.
+ */
+type AttachmentDownloadInput = {
+  documentId: string;
+  ref: AttachmentRef;
+  signal?: AbortSignal;
+};
+/**
+ * The document keeps its own name and type for an attachment (the same
+ * bytes may appear under different names in different documents), so the
+ * blob-producing conveniences let callers override what the server header
+ * reports from upload time.
+ */
+type AttachmentBlobOptions = {
+  mimeType?: string;
+};
+type AttachmentSaveOptions = {
+  fileName?: string;
+  mimeType?: string;
+};
+type AttachmentBlobResult = {
+  blob: Blob;
+  header: AttachmentHeader;
+};
+type AttachmentObjectUrl = {
+  /** Ready for img/iframe/video src. Pins memory until revoke() is called. */url: string;
+  header: AttachmentHeader;
+  revoke: () => void;
+};
+type AttachmentShareLinkInput = {
+  documentId: string;
+  ref: AttachmentRef; /** Requested link lifetime in seconds; the server clamps to its maximum. */
+  expiresIn?: number;
+  signal?: AbortSignal;
+};
+/**
+ * A self-contained public URL: anyone holding it can fetch the bytes until
+ * expiresAtUtc, with no login and no document access. Minting one requires
+ * document read access; once minted it cannot be revoked before expiry.
+ */
+type AttachmentShareLink = {
+  url: string;
+  expiresAtUtc: string;
+};
+type AttachmentBatchOptions = {
+  /** Bounds preprocessing and transfer together. Defaults to 4. */concurrency?: number; /** Whole-batch cancellation: stops unstarted items. */
+  signal?: AbortSignal;
+  onStage?: (index: number, stage: AttachmentStage) => void;
+};
+declare const DEFAULT_ATTACHMENT_BATCH_CONCURRENCY = 4;
 interface IAttachmentClient {
   preprocess(file: Blob, opts?: {
     fileName?: string;
     mimeType?: string;
   }): Promise<PreprocessResult>;
   reserve(options: HashFirstReserveAttachmentOptions, send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>): Promise<AttachmentUploadResult>;
+  /** Hash, reserve, and transfer one file; confirmed dedup skips the transfer. */
+  upload(input: AttachmentUploadInput, onStage?: AttachmentStageListener): Promise<AttachmentUploadResult>;
+  /** Document-authorized download of one ref. */
+  download(input: AttachmentDownloadInput, onStage?: AttachmentStageListener): Promise<AttachmentResponse>;
+  /**
+   * Document-authorized download materialized as a typed Blob. The Blob's
+   * type comes from the server header unless overridden — that's what makes
+   * browsers render PDFs inline and images correctly.
+   */
+  downloadBlob(input: AttachmentDownloadInput, options?: AttachmentBlobOptions, onStage?: AttachmentStageListener): Promise<AttachmentBlobResult>;
+  /**
+   * Download and hand the bytes to the browser's save-file flow. Browser
+   * only. fileName defaults to the server header's; pass the document's own
+   * name for per-document naming.
+   */
+  saveAttachment(input: AttachmentDownloadInput, options?: AttachmentSaveOptions, onStage?: AttachmentStageListener): Promise<void>;
+  /**
+   * Download and expose the bytes as an object URL for inline rendering
+   * (img/iframe/video src). Callers MUST call revoke() when done — the URL
+   * pins the blob in memory until then.
+   */
+  downloadObjectUrl(input: AttachmentDownloadInput, options?: AttachmentBlobOptions, onStage?: AttachmentStageListener): Promise<AttachmentObjectUrl>;
+  /**
+   * Mint a public share link: a presigned URL anyone can fetch until it
+   * expires, with no login. Authorized exactly like a download (document
+   * read access + the reference index). Requires a presigned-capable
+   * storage backend (S3); rejects when the server answers with an
+   * authenticated switchboard target, which would not be public.
+   */
+  getShareLink(input: AttachmentShareLinkInput): Promise<AttachmentShareLink>;
+  uploadMany(inputs: readonly AttachmentUploadInput[], options?: AttachmentBatchOptions): Promise<BatchItemResult<AttachmentUploadResult>[]>;
+  downloadMany(inputs: readonly AttachmentDownloadInput[], options?: AttachmentBatchOptions): Promise<BatchItemResult<AttachmentResponse>[]>;
 }
 declare function createAttachmentClient(service: IAttachmentService): IAttachmentClient;
 //#endregion
-export { AttachmentAlreadyExists, type AttachmentHeader, type AttachmentMetadata, AttachmentNotFound, AttachmentPending, type AttachmentResponse, AttachmentService, type AttachmentStatus, type AttachmentTransportConfig, type AttachmentUploadResult, type HashFirstReserveAttachmentOptions, HashMismatch, IAttachmentClient, type IAttachmentReader, type IAttachmentService, type IAttachmentStore, type IAttachmentTransport, type IAttachmentTransportFactory, type IAttachmentUpload, type IAttachmentUploadFactory, type IReservationStore, InvalidAttachmentRef, NullAttachmentTransport, type ParsedRef, PreprocessResult, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, type Reservation, ReservationNotFound, type ReserveAttachmentOptions, SizeMismatch, SwitchboardAttachmentTransport, type SwitchboardClientConfig, type SwitchboardTransportConfig, type TransportFetchResult, type TransportResponse, type UploadFirstReserveAttachmentOptions, UploadTooLarge, createAttachmentClient, createRef, createRemoteAttachmentService, parseRef };
+export { AttachmentAlreadyExists, AttachmentBatchOptions, AttachmentBlobOptions, AttachmentBlobResult, AttachmentDownloadInput, type AttachmentDownloadOptions, type AttachmentDownloadTarget, type AttachmentDownloadTargetOptions, type AttachmentHeader, type AttachmentMetadata, AttachmentNotFound, AttachmentObjectUrl, AttachmentPending, type AttachmentResponse, AttachmentSaveOptions, AttachmentService, AttachmentShareLink, AttachmentShareLinkInput, AttachmentStage, AttachmentStageListener, type AttachmentStatus, type AttachmentTargetHeaders, AttachmentTransferError, type AttachmentTransferStage, type AttachmentTransportConfig, AttachmentUploadInput, type AttachmentUploadResult, type AttachmentUploadTarget, type BatchItemResult, DEFAULT_ATTACHMENT_BATCH_CONCURRENCY, type HashFirstReserveAttachmentOptions, HashMismatch, IAttachmentClient, type IAttachmentReader, type IAttachmentService, type IAttachmentStore, type IAttachmentTransport, type IAttachmentTransportFactory, type IAttachmentUpload, type IAttachmentUploadFactory, type IReservationStore, InvalidAttachmentRef, NullAttachmentTransport, type ParsedRef, PreprocessResult, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, type Reservation, ReservationNotFound, type ReserveAttachmentOptions, type RunWithConcurrencyOptions, SizeMismatch, SwitchboardAttachmentTransport, type SwitchboardClientConfig, type SwitchboardTransportConfig, type TransportFetchResult, type TransportResponse, type UploadFirstReserveAttachmentOptions, UploadTooLarge, createAttachmentClient, createRef, createRemoteAttachmentService, parseAttachmentDownloadTarget, parseAttachmentUploadTarget, parseRef, runWithConcurrency };
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;;;KA0DY,gBAAA;EACV,GAAA,EAAK,aAAA;EACL,IAAA,EAAM,cAAA;EACN,SAAA;EACA,OAAA,EAAS,iCAAA;EACT,IAAA,EAAM,cAAA,CAAe,UAAA;EACrB,MAAA,QAAc,cAAA,CAAe,UAAA;AAAA;AAAA,UAGd,iBAAA;EACf,UAAA,CACE,IAAA,EAAM,IAAA,EACN,IAAA;IAAS,QAAA;IAAmB,QAAA;EAAA,IAC3B,OAAA,CAAQ,gBAAA;EACX,OAAA,CACE,OAAA,EAAS,iCAAA,EACT,IAAA,GAAO,MAAA,EAAQ,iBAAA,KAAsB,OAAA,CAAQ,sBAAA,IAC5C,OAAA,CAAQ,sBAAA;AAAA;AAAA,iBA2DG,sBAAA,CACd,OAAA,EAAS,kBAAA,GACR,iBAAA"}
+{"version":3,"file":"client.d.ts","names":[],"sources":["../src/concurrency.ts","../src/client.ts"],"mappings":"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"}

package/dist/client.js

@@ -1,5 +1,62 @@
-import { _ as SizeMismatch, a as RemoteAttachmentUpload, c as AttachmentService, d as AttachmentAlreadyExists, f as AttachmentNotFound, g as ReservationNotFound, h as InvalidAttachmentRef, i as RemoteAttachmentUploadFactory, l as createRef, m as HashMismatch, n as createRemoteAttachmentService, o as RemoteReservationStore, p as AttachmentPending, r as RemoteAttachmentStore, s as SwitchboardAttachmentTransport, t as NullAttachmentTransport, u as parseRef, v as UploadTooLarge } from "./null-attachment-transport-Drx03s02.js";
+import { _ as HashMismatch, a as RemoteAttachmentUpload, b as SizeMismatch, c as AttachmentService, d as parseAttachmentDownloadTarget, f as parseAttachmentUploadTarget, g as AttachmentTransferError, h as AttachmentPending, i as RemoteAttachmentUploadFactory, l as createRef, m as AttachmentNotFound, n as createRemoteAttachmentService, o as RemoteReservationStore, p as AttachmentAlreadyExists, r as RemoteAttachmentStore, s as SwitchboardAttachmentTransport, t as NullAttachmentTransport, u as parseRef, v as InvalidAttachmentRef, x as UploadTooLarge, y as ReservationNotFound } from "./null-attachment-transport-CTBrRCDe.js";
+//#region src/concurrency.ts
+/**
+* Runs `worker` over `items` with a hard upper bound on simultaneous
+* executions. Bounding starts (not just transfers) is what keeps memory flat:
+* an item's preprocessing (hashing/buffering) only begins when a slot frees.
+*/
+async function runWithConcurrency(items, worker, options) {
+	const { concurrency, signal } = options;
+	if (!Number.isInteger(concurrency) || concurrency < 1) throw new Error(`concurrency must be a positive integer, got: ${concurrency}`);
+	const results = new Array(items.length);
+	let nextIndex = 0;
+	async function runLane() {
+		for (;;) {
+			const index = nextIndex++;
+			if (index >= items.length) return;
+			if (signal?.aborted) {
+				results[index] = {
+					index,
+					status: "rejected",
+					error: signalReason(signal)
+				};
+				continue;
+			}
+			try {
+				results[index] = {
+					index,
+					status: "fulfilled",
+					value: await worker(items[index], index)
+				};
+			} catch (error) {
+				results[index] = {
+					index,
+					status: "rejected",
+					error
+				};
+			}
+		}
+	}
+	const lanes = Array.from({ length: Math.min(concurrency, items.length) }, () => runLane());
+	await Promise.all(lanes);
+	return results;
+}
+function signalReason(signal) {
+	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+//#endregion
 //#region src/client.ts
+const DEFAULT_ATTACHMENT_BATCH_CONCURRENCY = 4;
+/**
+* Duck-typed dedup detection: bundlers (notably Vite dev pre-bundling) can
+* load two copies of this package's error classes, one for the service and
+* one for the client wrapper, making a plain instanceof check miss the
+* cross-copy throw. Name plus payload shape identifies the error reliably.
+*/
+function isAttachmentAlreadyExists(err) {
+	if (err instanceof AttachmentAlreadyExists) return true;
+	return err instanceof Error && err.name === "AttachmentAlreadyExists" && typeof err.hash === "string" && typeof err.ref === "string";
+}
 function streamFromBuffer(buf) {
 	return new ReadableStream({ start(controller) {
 		controller.enqueue(buf);
@@ -39,7 +96,7 @@ var AttachmentClientImpl = class {
 		try {
 			handle = await this.service.reserve(options);
 		} catch (err) {
-			if (err instanceof AttachmentAlreadyExists) {
+			if (isAttachmentAlreadyExists(err)) {
 				const header = await this.service.stat(err.ref);
 				return {
 					hash: err.hash,
@@ -51,11 +108,128 @@ var AttachmentClientImpl = class {
 		}
 		return send(handle);
 	}
+	async upload(input, onStage) {
+		try {
+			input.signal?.throwIfAborted();
+			onStage?.("hashing");
+			const preprocessed = await this.preprocess(input.file, {
+				...input.fileName !== void 0 ? { fileName: input.fileName } : {},
+				...input.mimeType !== void 0 ? { mimeType: input.mimeType } : {}
+			});
+			input.signal?.throwIfAborted();
+			onStage?.("reserving");
+			const result = await this.reserve(preprocessed.options, (handle) => {
+				input.signal?.throwIfAborted();
+				onStage?.("uploading");
+				return handle.send(preprocessed.stream());
+			});
+			onStage?.("done");
+			return result;
+		} catch (err) {
+			onStage?.("error");
+			throw err;
+		}
+	}
+	async download(input, onStage) {
+		try {
+			input.signal?.throwIfAborted();
+			onStage?.("requesting-download-target");
+			const response = await this.service.get(input.ref, {
+				documentId: input.documentId,
+				signal: input.signal
+			});
+			onStage?.("downloading");
+			onStage?.("done");
+			return response;
+		} catch (err) {
+			onStage?.("error");
+			throw err;
+		}
+	}
+	async downloadBlob(input, options, onStage) {
+		try {
+			input.signal?.throwIfAborted();
+			onStage?.("requesting-download-target");
+			const { header, body } = await this.service.get(input.ref, {
+				documentId: input.documentId,
+				signal: input.signal
+			});
+			onStage?.("downloading");
+			const reader = body.getReader();
+			const chunks = [];
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				chunks.push(value);
+			}
+			const blob = new Blob(chunks, { type: options?.mimeType ?? header.mimeType });
+			onStage?.("done");
+			return {
+				blob,
+				header
+			};
+		} catch (err) {
+			onStage?.("error");
+			throw err;
+		}
+	}
+	async saveAttachment(input, options, onStage) {
+		if (typeof document === "undefined") throw new Error("saveAttachment requires a browser environment; use downloadBlob elsewhere");
+		const { blob, header } = await this.downloadBlob(input, { mimeType: options?.mimeType }, onStage);
+		const url = URL.createObjectURL(blob);
+		try {
+			const anchor = document.createElement("a");
+			anchor.href = url;
+			anchor.download = options?.fileName ?? header.fileName;
+			anchor.click();
+		} finally {
+			URL.revokeObjectURL(url);
+		}
+	}
+	async downloadObjectUrl(input, options, onStage) {
+		const { blob, header } = await this.downloadBlob(input, options, onStage);
+		const url = URL.createObjectURL(blob);
+		let revoked = false;
+		return {
+			url,
+			header,
+			revoke: () => {
+				if (revoked) return;
+				revoked = true;
+				URL.revokeObjectURL(url);
+			}
+		};
+	}
+	async getShareLink(input) {
+		input.signal?.throwIfAborted();
+		const target = await this.service.getDownloadTarget(input.ref, {
+			documentId: input.documentId,
+			...input.expiresIn !== void 0 ? { expiresIn: input.expiresIn } : {},
+			...input.signal !== void 0 ? { signal: input.signal } : {}
+		});
+		if (target.kind !== "presigned-get") throw new Error("Public share links require a presigned-capable storage backend (S3); this server answered with an authenticated target");
+		return {
+			url: target.url,
+			expiresAtUtc: target.expiresAtUtc
+		};
+	}
+	uploadMany(inputs, options) {
+		return runWithConcurrency(inputs, (input, index) => this.upload(input, (stage) => options?.onStage?.(index, stage)), {
+			concurrency: options?.concurrency ?? 4,
+			signal: options?.signal
+		});
+	}
+	downloadMany(inputs, options) {
+		return runWithConcurrency(inputs, (input, index) => this.download(input, (stage) => options?.onStage?.(index, stage)), {
+			concurrency: options?.concurrency ?? 4,
+			signal: options?.signal
+		});
+	}
 };
 function createAttachmentClient(service) {
 	return new AttachmentClientImpl(service);
 }
 //#endregion
-export { AttachmentAlreadyExists, AttachmentNotFound, AttachmentPending, AttachmentService, HashMismatch, InvalidAttachmentRef, NullAttachmentTransport, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, ReservationNotFound, SizeMismatch, SwitchboardAttachmentTransport, UploadTooLarge, createAttachmentClient, createRef, createRemoteAttachmentService, parseRef };
+export { AttachmentAlreadyExists, AttachmentNotFound, AttachmentPending, AttachmentService, AttachmentTransferError, DEFAULT_ATTACHMENT_BATCH_CONCURRENCY, HashMismatch, InvalidAttachmentRef, NullAttachmentTransport, RemoteAttachmentStore, RemoteAttachmentUpload, RemoteAttachmentUploadFactory, RemoteReservationStore, ReservationNotFound, SizeMismatch, SwitchboardAttachmentTransport, UploadTooLarge, createAttachmentClient, createRef, createRemoteAttachmentService, parseAttachmentDownloadTarget, parseAttachmentUploadTarget, parseRef, runWithConcurrency };
 
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["import type { AttachmentHash, AttachmentRef } from \"@powerhousedao/reactor\";\nimport { AttachmentAlreadyExists } from \"./errors.js\";\nimport type { IAttachmentService, IAttachmentUpload } from \"./interfaces.js\";\nimport { createRef } from \"./ref.js\";\nimport type {\n  AttachmentUploadResult,\n  HashFirstReserveAttachmentOptions,\n} from \"./types.js\";\n\nexport { AttachmentService } from \"./attachment-service.js\";\nexport {\n  AttachmentAlreadyExists,\n  AttachmentNotFound,\n  AttachmentPending,\n  HashMismatch,\n  InvalidAttachmentRef,\n  ReservationNotFound,\n  SizeMismatch,\n  UploadTooLarge,\n} from \"./errors.js\";\nexport type {\n  IAttachmentReader,\n  IAttachmentService,\n  IAttachmentStore,\n  IAttachmentTransport,\n  IAttachmentTransportFactory,\n  IAttachmentUpload,\n  IAttachmentUploadFactory,\n  IReservationStore,\n} from \"./interfaces.js\";\nexport { parseRef, createRef } from \"./ref.js\";\nexport type { ParsedRef } from \"./ref.js\";\nexport type {\n  AttachmentHeader,\n  AttachmentMetadata,\n  AttachmentResponse,\n  AttachmentStatus,\n  AttachmentTransportConfig,\n  AttachmentUploadResult,\n  HashFirstReserveAttachmentOptions,\n  UploadFirstReserveAttachmentOptions,\n  Reservation,\n  ReserveAttachmentOptions,\n  TransportFetchResult,\n  TransportResponse,\n} from \"./types.js\";\nexport {\n  SwitchboardAttachmentTransport,\n  type SwitchboardTransportConfig,\n  RemoteReservationStore,\n  type SwitchboardClientConfig,\n  RemoteAttachmentUpload,\n  RemoteAttachmentUploadFactory,\n  RemoteAttachmentStore,\n  createRemoteAttachmentService,\n} from \"./switchboard/index.js\";\nexport { NullAttachmentTransport } from \"./null-attachment-transport.js\";\n\nexport type PreprocessResult = {\n  ref: AttachmentRef;\n  hash: AttachmentHash;\n  sizeBytes: number;\n  options: HashFirstReserveAttachmentOptions;\n  data: ReadableStream<Uint8Array>;\n  stream: () => ReadableStream<Uint8Array>;\n};\n\nexport interface IAttachmentClient {\n  preprocess(\n    file: Blob,\n    opts?: { fileName?: string; mimeType?: string },\n  ): Promise<PreprocessResult>;\n  reserve(\n    options: HashFirstReserveAttachmentOptions,\n    send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>,\n  ): Promise<AttachmentUploadResult>;\n}\n\nfunction streamFromBuffer(buf: Uint8Array): ReadableStream<Uint8Array> {\n  return new ReadableStream({\n    start(controller) {\n      controller.enqueue(buf);\n      controller.close();\n    },\n  });\n}\n\nclass AttachmentClientImpl implements IAttachmentClient {\n  constructor(private readonly service: IAttachmentService) {}\n\n  async preprocess(\n    file: Blob,\n    opts?: { fileName?: string; mimeType?: string },\n  ): Promise<PreprocessResult> {\n    const buf = await file.arrayBuffer();\n    const bytes = new Uint8Array(buf);\n    const digest = await globalThis.crypto.subtle.digest(\"SHA-256\", bytes);\n    const hash = Array.from(new Uint8Array(digest))\n      .map((b) => b.toString(16).padStart(2, \"0\"))\n      .join(\"\") as AttachmentHash;\n    const ref = createRef(hash);\n    const sizeBytes = file.size;\n    const mimeType = opts?.mimeType ?? file.type;\n    const fileName =\n      opts?.fileName ?? (file instanceof File ? file.name : \"attachment\");\n    const options: HashFirstReserveAttachmentOptions = {\n      mimeType,\n      fileName,\n      clientHash: hash,\n      sizeBytes,\n    };\n    const data = streamFromBuffer(bytes);\n    const stream = (): ReadableStream<Uint8Array> => streamFromBuffer(bytes);\n    return { ref, hash, sizeBytes, options, data, stream };\n  }\n\n  async reserve(\n    options: HashFirstReserveAttachmentOptions,\n    send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>,\n  ): Promise<AttachmentUploadResult> {\n    let handle: IAttachmentUpload;\n    try {\n      handle = await this.service.reserve(options);\n    } catch (err) {\n      if (err instanceof AttachmentAlreadyExists) {\n        const header = await this.service.stat(err.ref);\n        return { hash: err.hash, ref: err.ref, header };\n      }\n      throw err;\n    }\n    return send(handle);\n  }\n}\n\nexport function createAttachmentClient(\n  service: IAttachmentService,\n): IAttachmentClient {\n  return new AttachmentClientImpl(service);\n}\n"],"mappings":";;AA8EA,SAAS,iBAAiB,KAA6C;AACrE,QAAO,IAAI,eAAe,EACxB,MAAM,YAAY;AAChB,aAAW,QAAQ,IAAI;AACvB,aAAW,OAAO;IAErB,CAAC;;AAGJ,IAAM,uBAAN,MAAwD;CACtD,YAAY,SAA8C;AAA7B,OAAA,UAAA;;CAE7B,MAAM,WACJ,MACA,MAC2B;EAC3B,MAAM,MAAM,MAAM,KAAK,aAAa;EACpC,MAAM,QAAQ,IAAI,WAAW,IAAI;EACjC,MAAM,SAAS,MAAM,WAAW,OAAO,OAAO,OAAO,WAAW,MAAM;EACtE,MAAM,OAAO,MAAM,KAAK,IAAI,WAAW,OAAO,CAAC,CAC5C,KAAK,MAAM,EAAE,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAC3C,KAAK,GAAG;EACX,MAAM,MAAM,UAAU,KAAK;EAC3B,MAAM,YAAY,KAAK;EAIvB,MAAM,UAA6C;GACjD,UAJe,MAAM,YAAY,KAAK;GAKtC,UAHA,MAAM,aAAa,gBAAgB,OAAO,KAAK,OAAO;GAItD,YAAY;GACZ;GACD;EACD,MAAM,OAAO,iBAAiB,MAAM;EACpC,MAAM,eAA2C,iBAAiB,MAAM;AACxE,SAAO;GAAE;GAAK;GAAM;GAAW;GAAS;GAAM;GAAQ;;CAGxD,MAAM,QACJ,SACA,MACiC;EACjC,IAAI;AACJ,MAAI;AACF,YAAS,MAAM,KAAK,QAAQ,QAAQ,QAAQ;WACrC,KAAK;AACZ,OAAI,eAAe,yBAAyB;IAC1C,MAAM,SAAS,MAAM,KAAK,QAAQ,KAAK,IAAI,IAAI;AAC/C,WAAO;KAAE,MAAM,IAAI;KAAM,KAAK,IAAI;KAAK;KAAQ;;AAEjD,SAAM;;AAER,SAAO,KAAK,OAAO;;;AAIvB,SAAgB,uBACd,SACmB;AACnB,QAAO,IAAI,qBAAqB,QAAQ"}
+{"version":3,"file":"client.js","names":[],"sources":["../src/concurrency.ts","../src/client.ts"],"sourcesContent":["/**\n * Ordered result of one batch item. `index` always mirrors the input\n * position, so callers can correlate results with inputs regardless of\n * completion order, and successes are retained when siblings fail.\n */\nexport type BatchItemResult<R> =\n  | { index: number; status: \"fulfilled\"; value: R }\n  | { index: number; status: \"rejected\"; error: unknown };\n\nexport type RunWithConcurrencyOptions = {\n  /** Maximum simultaneously running workers. Must be a positive integer. */\n  concurrency: number;\n  /**\n   * Whole-batch cancellation: unstarted items are rejected with the signal's\n   * reason without ever starting, while already-started items keep running —\n   * per-item signals are the mechanism for interrupting active work.\n   */\n  signal?: AbortSignal;\n};\n\n/**\n * Runs `worker` over `items` with a hard upper bound on simultaneous\n * executions. Bounding starts (not just transfers) is what keeps memory flat:\n * an item's preprocessing (hashing/buffering) only begins when a slot frees.\n */\nexport async function runWithConcurrency<T, R>(\n  items: readonly T[],\n  worker: (item: T, index: number) => Promise<R>,\n  options: RunWithConcurrencyOptions,\n): Promise<BatchItemResult<R>[]> {\n  const { concurrency, signal } = options;\n  if (!Number.isInteger(concurrency) || concurrency < 1) {\n    throw new Error(\n      `concurrency must be a positive integer, got: ${concurrency}`,\n    );\n  }\n\n  const results: BatchItemResult<R>[] = new Array<BatchItemResult<R>>(\n    items.length,\n  );\n  let nextIndex = 0;\n\n  async function runLane(): Promise<void> {\n    for (;;) {\n      const index = nextIndex++;\n      if (index >= items.length) return;\n      if (signal?.aborted) {\n        results[index] = {\n          index,\n          status: \"rejected\",\n          error: signalReason(signal),\n        };\n        continue;\n      }\n      try {\n        const value = await worker(items[index], index);\n        results[index] = { index, status: \"fulfilled\", value };\n      } catch (error) {\n        results[index] = { index, status: \"rejected\", error };\n      }\n    }\n  }\n\n  const lanes = Array.from(\n    { length: Math.min(concurrency, items.length) },\n    () => runLane(),\n  );\n  await Promise.all(lanes);\n  return results;\n}\n\nfunction signalReason(signal: AbortSignal): unknown {\n  return (\n    (signal as { reason?: unknown }).reason ??\n    new DOMException(\"The operation was aborted\", \"AbortError\")\n  );\n}\n","import type { AttachmentHash, AttachmentRef } from \"@powerhousedao/reactor\";\nimport { runWithConcurrency, type BatchItemResult } from \"./concurrency.js\";\nimport { AttachmentAlreadyExists } from \"./errors.js\";\nexport type { AttachmentTransferStage } from \"./errors.js\";\nexport {\n  runWithConcurrency,\n  type BatchItemResult,\n  type RunWithConcurrencyOptions,\n} from \"./concurrency.js\";\nimport type { IAttachmentService, IAttachmentUpload } from \"./interfaces.js\";\nimport { createRef } from \"./ref.js\";\nimport type {\n  AttachmentHeader,\n  AttachmentResponse,\n  AttachmentUploadResult,\n  HashFirstReserveAttachmentOptions,\n} from \"./types.js\";\n\nexport { AttachmentService } from \"./attachment-service.js\";\nexport {\n  AttachmentAlreadyExists,\n  AttachmentNotFound,\n  AttachmentPending,\n  AttachmentTransferError,\n  HashMismatch,\n  InvalidAttachmentRef,\n  ReservationNotFound,\n  SizeMismatch,\n  UploadTooLarge,\n} from \"./errors.js\";\nexport type {\n  IAttachmentReader,\n  IAttachmentService,\n  IAttachmentStore,\n  IAttachmentTransport,\n  IAttachmentTransportFactory,\n  IAttachmentUpload,\n  IAttachmentUploadFactory,\n  IReservationStore,\n} from \"./interfaces.js\";\nexport { parseRef, createRef } from \"./ref.js\";\nexport type { ParsedRef } from \"./ref.js\";\nexport type {\n  AttachmentDownloadOptions,\n  AttachmentDownloadTarget,\n  AttachmentDownloadTargetOptions,\n  AttachmentHeader,\n  AttachmentMetadata,\n  AttachmentResponse,\n  AttachmentStatus,\n  AttachmentTransportConfig,\n  AttachmentUploadResult,\n  AttachmentTargetHeaders,\n  AttachmentUploadTarget,\n  HashFirstReserveAttachmentOptions,\n  UploadFirstReserveAttachmentOptions,\n  Reservation,\n  ReserveAttachmentOptions,\n  TransportFetchResult,\n  TransportResponse,\n} from \"./types.js\";\nexport {\n  parseAttachmentDownloadTarget,\n  parseAttachmentUploadTarget,\n} from \"./targets.js\";\nexport {\n  SwitchboardAttachmentTransport,\n  type SwitchboardTransportConfig,\n  RemoteReservationStore,\n  type SwitchboardClientConfig,\n  RemoteAttachmentUpload,\n  RemoteAttachmentUploadFactory,\n  RemoteAttachmentStore,\n  createRemoteAttachmentService,\n} from \"./switchboard/index.js\";\nexport { NullAttachmentTransport } from \"./null-attachment-transport.js\";\n\nexport type PreprocessResult = {\n  ref: AttachmentRef;\n  hash: AttachmentHash;\n  sizeBytes: number;\n  options: HashFirstReserveAttachmentOptions;\n  data: ReadableStream<Uint8Array>;\n  stream: () => ReadableStream<Uint8Array>;\n};\n\nexport type AttachmentStage =\n  | \"hashing\"\n  | \"reserving\"\n  | \"uploading\"\n  | \"requesting-download-target\"\n  | \"downloading\"\n  | \"done\"\n  | \"error\";\n\nexport type AttachmentStageListener = (stage: AttachmentStage) => void;\n\nexport type AttachmentUploadInput = {\n  file: Blob;\n  fileName?: string;\n  mimeType?: string;\n  /** Per-item cancellation, checked between stages. */\n  signal?: AbortSignal;\n};\n\n/**\n * Every remote download names the document that authorizes its ref; batches\n * may freely mix documents because the anchor travels with each item.\n */\nexport type AttachmentDownloadInput = {\n  documentId: string;\n  ref: AttachmentRef;\n  signal?: AbortSignal;\n};\n\n/**\n * The document keeps its own name and type for an attachment (the same\n * bytes may appear under different names in different documents), so the\n * blob-producing conveniences let callers override what the server header\n * reports from upload time.\n */\nexport type AttachmentBlobOptions = {\n  mimeType?: string;\n};\n\nexport type AttachmentSaveOptions = {\n  fileName?: string;\n  mimeType?: string;\n};\n\nexport type AttachmentBlobResult = {\n  blob: Blob;\n  header: AttachmentHeader;\n};\n\nexport type AttachmentObjectUrl = {\n  /** Ready for img/iframe/video src. Pins memory until revoke() is called. */\n  url: string;\n  header: AttachmentHeader;\n  revoke: () => void;\n};\n\nexport type AttachmentShareLinkInput = {\n  documentId: string;\n  ref: AttachmentRef;\n  /** Requested link lifetime in seconds; the server clamps to its maximum. */\n  expiresIn?: number;\n  signal?: AbortSignal;\n};\n\n/**\n * A self-contained public URL: anyone holding it can fetch the bytes until\n * expiresAtUtc, with no login and no document access. Minting one requires\n * document read access; once minted it cannot be revoked before expiry.\n */\nexport type AttachmentShareLink = {\n  url: string;\n  expiresAtUtc: string;\n};\n\nexport type AttachmentBatchOptions = {\n  /** Bounds preprocessing and transfer together. Defaults to 4. */\n  concurrency?: number;\n  /** Whole-batch cancellation: stops unstarted items. */\n  signal?: AbortSignal;\n  onStage?: (index: number, stage: AttachmentStage) => void;\n};\n\nexport const DEFAULT_ATTACHMENT_BATCH_CONCURRENCY = 4;\n\nexport interface IAttachmentClient {\n  preprocess(\n    file: Blob,\n    opts?: { fileName?: string; mimeType?: string },\n  ): Promise<PreprocessResult>;\n  reserve(\n    options: HashFirstReserveAttachmentOptions,\n    send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>,\n  ): Promise<AttachmentUploadResult>;\n  /** Hash, reserve, and transfer one file; confirmed dedup skips the transfer. */\n  upload(\n    input: AttachmentUploadInput,\n    onStage?: AttachmentStageListener,\n  ): Promise<AttachmentUploadResult>;\n  /** Document-authorized download of one ref. */\n  download(\n    input: AttachmentDownloadInput,\n    onStage?: AttachmentStageListener,\n  ): Promise<AttachmentResponse>;\n  /**\n   * Document-authorized download materialized as a typed Blob. The Blob's\n   * type comes from the server header unless overridden — that's what makes\n   * browsers render PDFs inline and images correctly.\n   */\n  downloadBlob(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions,\n    onStage?: AttachmentStageListener,\n  ): Promise<AttachmentBlobResult>;\n  /**\n   * Download and hand the bytes to the browser's save-file flow. Browser\n   * only. fileName defaults to the server header's; pass the document's own\n   * name for per-document naming.\n   */\n  saveAttachment(\n    input: AttachmentDownloadInput,\n    options?: AttachmentSaveOptions,\n    onStage?: AttachmentStageListener,\n  ): Promise<void>;\n  /**\n   * Download and expose the bytes as an object URL for inline rendering\n   * (img/iframe/video src). Callers MUST call revoke() when done — the URL\n   * pins the blob in memory until then.\n   */\n  downloadObjectUrl(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions,\n    onStage?: AttachmentStageListener,\n  ): Promise<AttachmentObjectUrl>;\n  /**\n   * Mint a public share link: a presigned URL anyone can fetch until it\n   * expires, with no login. Authorized exactly like a download (document\n   * read access + the reference index). Requires a presigned-capable\n   * storage backend (S3); rejects when the server answers with an\n   * authenticated switchboard target, which would not be public.\n   */\n  getShareLink(input: AttachmentShareLinkInput): Promise<AttachmentShareLink>;\n  uploadMany(\n    inputs: readonly AttachmentUploadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentUploadResult>[]>;\n  downloadMany(\n    inputs: readonly AttachmentDownloadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentResponse>[]>;\n}\n\n/**\n * Duck-typed dedup detection: bundlers (notably Vite dev pre-bundling) can\n * load two copies of this package's error classes, one for the service and\n * one for the client wrapper, making a plain instanceof check miss the\n * cross-copy throw. Name plus payload shape identifies the error reliably.\n */\nfunction isAttachmentAlreadyExists(\n  err: unknown,\n): err is AttachmentAlreadyExists {\n  if (err instanceof AttachmentAlreadyExists) return true;\n  return (\n    err instanceof Error &&\n    err.name === \"AttachmentAlreadyExists\" &&\n    typeof (err as { hash?: unknown }).hash === \"string\" &&\n    typeof (err as { ref?: unknown }).ref === \"string\"\n  );\n}\n\nfunction streamFromBuffer(buf: Uint8Array): ReadableStream<Uint8Array> {\n  return new ReadableStream({\n    start(controller) {\n      controller.enqueue(buf);\n      controller.close();\n    },\n  });\n}\n\nclass AttachmentClientImpl implements IAttachmentClient {\n  constructor(private readonly service: IAttachmentService) {}\n\n  async preprocess(\n    file: Blob,\n    opts?: { fileName?: string; mimeType?: string },\n  ): Promise<PreprocessResult> {\n    const buf = await file.arrayBuffer();\n    const bytes = new Uint8Array(buf);\n    const digest = await globalThis.crypto.subtle.digest(\"SHA-256\", bytes);\n    const hash = Array.from(new Uint8Array(digest))\n      .map((b) => b.toString(16).padStart(2, \"0\"))\n      .join(\"\") as AttachmentHash;\n    const ref = createRef(hash);\n    const sizeBytes = file.size;\n    const mimeType = opts?.mimeType ?? file.type;\n    const fileName =\n      opts?.fileName ?? (file instanceof File ? file.name : \"attachment\");\n    const options: HashFirstReserveAttachmentOptions = {\n      mimeType,\n      fileName,\n      clientHash: hash,\n      sizeBytes,\n    };\n    const data = streamFromBuffer(bytes);\n    const stream = (): ReadableStream<Uint8Array> => streamFromBuffer(bytes);\n    return { ref, hash, sizeBytes, options, data, stream };\n  }\n\n  async reserve(\n    options: HashFirstReserveAttachmentOptions,\n    send: (handle: IAttachmentUpload) => Promise<AttachmentUploadResult>,\n  ): Promise<AttachmentUploadResult> {\n    let handle: IAttachmentUpload;\n    try {\n      handle = await this.service.reserve(options);\n    } catch (err) {\n      if (isAttachmentAlreadyExists(err)) {\n        const header = await this.service.stat(err.ref);\n        return { hash: err.hash, ref: err.ref, header };\n      }\n      throw err;\n    }\n    return send(handle);\n  }\n\n  async upload(\n    input: AttachmentUploadInput,\n    onStage?: AttachmentStageListener,\n  ): Promise<AttachmentUploadResult> {\n    try {\n      input.signal?.throwIfAborted();\n      onStage?.(\"hashing\");\n      const preprocessed = await this.preprocess(input.file, {\n        ...(input.fileName !== undefined ? { fileName: input.fileName } : {}),\n        ...(input.mimeType !== undefined ? { mimeType: input.mimeType } : {}),\n      });\n\n      input.signal?.throwIfAborted();\n      onStage?.(\"reserving\");\n      const result = await this.reserve(preprocessed.options, (handle) => {\n        input.signal?.throwIfAborted();\n        onStage?.(\"uploading\");\n        return handle.send(preprocessed.stream());\n      });\n      onStage?.(\"done\");\n      return result;\n    } catch (err) {\n      onStage?.(\"error\");\n      throw err;\n    }\n  }\n\n  async download(\n    input: AttachmentDownloadInput,\n    onStage?: AttachmentStageListener,\n  ): Promise<AttachmentResponse> {\n    try {\n      input.signal?.throwIfAborted();\n      onStage?.(\"requesting-download-target\");\n      const response = await this.service.get(input.ref, {\n        documentId: input.documentId,\n        signal: input.signal,\n      });\n      onStage?.(\"downloading\");\n      onStage?.(\"done\");\n      return response;\n    } catch (err) {\n      onStage?.(\"error\");\n      throw err;\n    }\n  }\n\n  async downloadBlob(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions,\n    onStage?: AttachmentStageListener,\n  ): Promise<AttachmentBlobResult> {\n    try {\n      input.signal?.throwIfAborted();\n      onStage?.(\"requesting-download-target\");\n      const { header, body } = await this.service.get(input.ref, {\n        documentId: input.documentId,\n        signal: input.signal,\n      });\n      onStage?.(\"downloading\");\n      const reader = body.getReader();\n      const chunks: BlobPart[] = [];\n      for (;;) {\n        const { done, value } = await reader.read();\n        if (done) break;\n        chunks.push(value as BlobPart);\n      }\n      const blob = new Blob(chunks, {\n        type: options?.mimeType ?? header.mimeType,\n      });\n      onStage?.(\"done\");\n      return { blob, header };\n    } catch (err) {\n      onStage?.(\"error\");\n      throw err;\n    }\n  }\n\n  async saveAttachment(\n    input: AttachmentDownloadInput,\n    options?: AttachmentSaveOptions,\n    onStage?: AttachmentStageListener,\n  ): Promise<void> {\n    if (typeof document === \"undefined\") {\n      throw new Error(\n        \"saveAttachment requires a browser environment; use downloadBlob elsewhere\",\n      );\n    }\n    const { blob, header } = await this.downloadBlob(\n      input,\n      { mimeType: options?.mimeType },\n      onStage,\n    );\n    const url = URL.createObjectURL(blob);\n    try {\n      const anchor = document.createElement(\"a\");\n      anchor.href = url;\n      anchor.download = options?.fileName ?? header.fileName;\n      anchor.click();\n    } finally {\n      URL.revokeObjectURL(url);\n    }\n  }\n\n  async downloadObjectUrl(\n    input: AttachmentDownloadInput,\n    options?: AttachmentBlobOptions,\n    onStage?: AttachmentStageListener,\n  ): Promise<AttachmentObjectUrl> {\n    const { blob, header } = await this.downloadBlob(input, options, onStage);\n    const url = URL.createObjectURL(blob);\n    let revoked = false;\n    return {\n      url,\n      header,\n      revoke: () => {\n        if (revoked) return;\n        revoked = true;\n        URL.revokeObjectURL(url);\n      },\n    };\n  }\n\n  async getShareLink(\n    input: AttachmentShareLinkInput,\n  ): Promise<AttachmentShareLink> {\n    input.signal?.throwIfAborted();\n    const target = await this.service.getDownloadTarget(input.ref, {\n      documentId: input.documentId,\n      ...(input.expiresIn !== undefined ? { expiresIn: input.expiresIn } : {}),\n      ...(input.signal !== undefined ? { signal: input.signal } : {}),\n    });\n    if (target.kind !== \"presigned-get\") {\n      throw new Error(\n        \"Public share links require a presigned-capable storage backend (S3); this server answered with an authenticated target\",\n      );\n    }\n    return { url: target.url, expiresAtUtc: target.expiresAtUtc };\n  }\n\n  uploadMany(\n    inputs: readonly AttachmentUploadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentUploadResult>[]> {\n    return runWithConcurrency(\n      inputs,\n      (input, index) =>\n        this.upload(input, (stage) => options?.onStage?.(index, stage)),\n      {\n        concurrency:\n          options?.concurrency ?? DEFAULT_ATTACHMENT_BATCH_CONCURRENCY,\n        signal: options?.signal,\n      },\n    );\n  }\n\n  downloadMany(\n    inputs: readonly AttachmentDownloadInput[],\n    options?: AttachmentBatchOptions,\n  ): Promise<BatchItemResult<AttachmentResponse>[]> {\n    return runWithConcurrency(\n      inputs,\n      (input, index) =>\n        this.download(input, (stage) => options?.onStage?.(index, stage)),\n      {\n        concurrency:\n          options?.concurrency ?? DEFAULT_ATTACHMENT_BATCH_CONCURRENCY,\n        signal: options?.signal,\n      },\n    );\n  }\n}\n\nexport function createAttachmentClient(\n  service: IAttachmentService,\n): IAttachmentClient {\n  return new AttachmentClientImpl(service);\n}\n"],"mappings":"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"}