slackmark 0.5.0 → 0.6.1

package/dist/slack.js

@@ -1,255 +1,778 @@
-// src/slack/slack-upload-error.ts
-var SlackUploadStage = {
-  GetUploadUrl: "get-upload-url",
-  UploadBytes: "upload-bytes",
-  CompleteUpload: "complete-upload",
-  FileInfo: "file-info",
-  ProcessingTimeout: "processing-timeout"
+//#region src/errors.ts
+/**
+* Registry-keyed markers, not module-local symbols.
+*
+* Each published entry (`slackmark`, `slackmark/renderers`, `slackmark/slack`) is bundled
+* without code splitting, so every entry carries its own copy of these classes and
+* `instanceof` is false for an error that crosses an entry boundary. `Symbol.for` keys are
+* shared by every copy, which is what makes the exported guards below reliable. Prefer
+* those guards to `instanceof` for any error that can cross an entry.
+*/
+const RECEIPT_SNAPSHOT_LOCK = Symbol.for("slackmark.receiptSnapshotLock");
+const CONFIGURATION_ERROR_BRAND = Symbol.for("slackmark.error.configuration");
+const OPERATION_ERROR_BRAND = Symbol.for("slackmark.error.operation");
+/**
+* Marks a class prototype so instances from any bundled copy answer to one identity.
+* Subclasses inherit the brand, and instances carry no extra own property.
+*/
+function brandErrorPrototype(prototype, brand) {
+	Object.defineProperty(prototype, brand, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false
+	});
+}
+/**
+* Reads a brand without trusting the value: a hostile getter must not escape a guard.
+*/
+function hasErrorBrand(value, brand) {
+	if (typeof value !== "object" || value === null) return false;
+	try {
+		return Reflect.get(value, brand) === true;
+	} catch {
+		return false;
+	}
+}
+var ConfigurationError = class extends Error {
+	static {
+		brandErrorPrototype(this.prototype, CONFIGURATION_ERROR_BRAND);
+	}
+	name;
+	code;
+	stage;
+	retryable;
+	receipts;
+	settledReceipts;
+	constructor(message, options = {}) {
+		super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "ConfigurationError";
+		this.code = options.code ?? "invalid_configuration";
+		this.stage = options.stage;
+		this.retryable = false;
+		this.receipts = freezeReceipts(options.receipts ?? []);
+		this.settledReceipts = options.settledReceipts ?? Promise.resolve(this.receipts);
+	}
+};
+const OperationErrorCode = {
+	Aborted: "operation_aborted",
+	DeadlineExceeded: "operation_deadline_exceeded",
+	Shutdown: "operation_shutdown"
+};
+/**
+* Operational control-flow error. These failures are never degradations.
+*/
+var OperationError = class extends Error {
+	static {
+		brandErrorPrototype(this.prototype, OPERATION_ERROR_BRAND);
+	}
+	name;
+	code;
+	stage;
+	retryable;
+	receipts;
+	settledReceipts;
+	constructor(message, code, stage, retryable, options = {}) {
+		super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "OperationError";
+		this.code = code;
+		this.stage = stage;
+		this.retryable = retryable;
+		this.receipts = freezeReceipts(options.receipts ?? []);
+		this.settledReceipts = options.settledReceipts ?? Promise.resolve(this.receipts);
+	}
+};
+var OperationAbortedError = class extends OperationError {
+	name;
+	constructor(stage, options = {}) {
+		super("Operation aborted by caller", OperationErrorCode.Aborted, stage, false, options);
+		this.name = "OperationAbortedError";
+	}
+};
+var OperationDeadlineExceededError = class extends OperationError {
+	name;
+	constructor(stage, options = {}) {
+		super("Operation deadline exceeded", OperationErrorCode.DeadlineExceeded, stage, true, options);
+		this.name = "OperationDeadlineExceededError";
+	}
+};
+/**
+* Identifies a {@link ConfigurationError} from any entry of this package.
+*
+* Use this instead of `instanceof` when the error may have been thrown by a different
+* entry — for example a `ConfigurationError` from `slackmark/renderers` caught by code
+* that imported the class from `slackmark`.
+*/
+function isConfigurationError(value) {
+	return hasErrorBrand(value, CONFIGURATION_ERROR_BRAND);
+}
+/**
+* Identifies an {@link OperationError} — abort, deadline, or shutdown — from any entry of
+* this package, including its subclasses.
+*
+* Use this instead of `instanceof` when the error may have been thrown by a different
+* entry — for example an abort raised inside `FetchSlackUploader` from `slackmark/slack`
+* caught by code that imported the class from `slackmark`. Narrow further with `code`
+* against {@link OperationErrorCode} rather than testing a subclass with `instanceof`.
+*/
+function isOperationError(value) {
+	return hasErrorBrand(value, OPERATION_ERROR_BRAND);
+}
+function attachReceipts(error, receipts, settledReceipts) {
+	if (!(error instanceof Error)) return error;
+	try {
+		if (Reflect.get(error, RECEIPT_SNAPSHOT_LOCK) === true) return error;
+	} catch {
+		return error;
+	}
+	let existing = [];
+	try {
+		const candidate = Reflect.get(error, "receipts");
+		if (Array.isArray(candidate)) existing = candidate.filter(isUploadReceipt);
+	} catch {
+		existing = [];
+	}
+	Reflect.defineProperty(error, "receipts", {
+		configurable: true,
+		enumerable: true,
+		value: freezeReceipts(mergeReceipts(existing, receipts)),
+		writable: false
+	});
+	if (settledReceipts !== void 0) {
+		const finalReceipts = freezeSettledReceipts(settledReceipts, receipts);
+		Reflect.defineProperty(error, "settledReceipts", {
+			configurable: true,
+			enumerable: true,
+			value: finalReceipts,
+			writable: false
+		});
+	}
+	return error;
+}
+async function freezeSettledReceipts(settledReceipts, fallback) {
+	try {
+		return freezeReceipts(await settledReceipts);
+	} catch {
+		return freezeReceipts(fallback);
+	}
+}
+function mergeReceipts(existing, incoming) {
+	const existingGroups = groupReceipts(existing);
+	const incomingGroups = groupReceipts(incoming);
+	const merged = [...incoming];
+	for (const [key, values] of existingGroups) {
+		const overlap = incomingGroups.get(key)?.length ?? 0;
+		if (values.length > overlap) merged.push(...values.slice(overlap));
+	}
+	return merged;
+}
+function groupReceipts(receipts) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const receipt of receipts) {
+		const key = receiptKey(receipt);
+		const values = grouped.get(key);
+		if (values === void 0) grouped.set(key, [receipt]);
+		else values.push(receipt);
+	}
+	return grouped;
+}
+function receiptKey(receipt) {
+	return [
+		receipt.provider,
+		receipt.phase,
+		receipt.fileId ?? "",
+		String(receipt.shared),
+		receipt.processing,
+		String(receipt.status ?? ""),
+		String(receipt.retryAfterMs ?? ""),
+		receipt.providerCode ?? "",
+		receipt.retrySafety
+	].join("\0");
+}
+function freezeReceipts(receipts) {
+	return Object.freeze(receipts.map((receipt) => Object.freeze({ ...receipt })));
+}
+function isUploadReceipt(value) {
+	return typeof value === "object" && value !== null && Reflect.get(value, "kind") === "upload";
+}
+//#endregion
+//#region src/receipts.ts
+const UploadPhase = {
+	Requested: "requested",
+	Allocated: "allocated",
+	Uploaded: "uploaded",
+	Completed: "completed",
+	Shared: "shared",
+	Unknown: "unknown"
+};
+const UploadProcessing = {
+	NotRequested: "not-requested",
+	Pending: "pending",
+	Verified: "verified",
+	Unverified: "unverified"
+};
+const RetrySafety = {
+	Never: "never",
+	Safe: "safe",
+	MayDuplicate: "may-duplicate"
 };
+//#endregion
+//#region src/slack/slack-upload-error.ts
+/** See the brand rationale in `errors.ts`: this class is bundled into more than one entry. */
+const SLACK_UPLOAD_ERROR_BRAND = Symbol.for("slackmark.error.slackUpload");
+const SlackUploadStage = {
+	Admission: "admission",
+	GetUploadUrl: "get-upload-url",
+	UploadBytes: "upload-bytes",
+	CompleteUpload: "complete-upload",
+	FileInfo: "file-info",
+	ProcessingTimeout: "processing-timeout"
+};
+/**
+* Integration error from one explicit stage of Slack's external-upload flow.
+*/
 var SlackUploadError = class extends Error {
-  name;
-  stage;
-  status;
-  code;
-  constructor(message, details) {
-    super(message, details.cause !== void 0 ? { cause: details.cause } : void 0);
-    this.name = "SlackUploadError";
-    this.stage = details.stage;
-    this.status = details.status;
-    this.code = details.code;
-  }
+	static {
+		brandErrorPrototype(this.prototype, SLACK_UPLOAD_ERROR_BRAND);
+	}
+	name;
+	stage;
+	status;
+	code;
+	retryable;
+	retryAfterMs;
+	receipt;
+	receipts;
+	settledReceipts;
+	constructor(message, details) {
+		super(message, details.cause !== void 0 ? { cause: details.cause } : void 0);
+		this.name = "SlackUploadError";
+		this.stage = details.stage;
+		this.status = details.status;
+		this.code = details.code;
+		this.retryable = details.retryable ?? isRetryable(details.status, details.code);
+		this.retryAfterMs = details.retryAfterMs;
+		this.receipt = Object.freeze(details.receipt ?? {
+			kind: "upload",
+			provider: "slack",
+			phase: UploadPhase.Requested,
+			fileId: void 0,
+			shared: false,
+			processing: UploadProcessing.NotRequested,
+			status: details.status,
+			retryAfterMs: details.retryAfterMs,
+			providerCode: details.code,
+			retrySafety: RetrySafety.Safe
+		});
+		this.receipts = Object.freeze([this.receipt]);
+		this.settledReceipts = Promise.resolve(this.receipts);
+	}
 };
-
-// src/slack/fetch-slack-uploader.ts
-var SLACK_API_BASE_URL = "https://slack.com/api";
-var DEFAULT_POLL_INTERVAL_MS = 250;
-var DEFAULT_POLL_MAX_ATTEMPTS = 20;
-var DEFAULT_POLL_TIMEOUT_MS = 3e4;
+/**
+* Identifies a {@link SlackUploadError} from any entry of this package. `slackmark` and
+* `slackmark/slack` each bundle their own copy, so `instanceof` is unreliable when the
+* error crosses between them.
+*/
+function isSlackUploadError(value) {
+	return hasErrorBrand(value, SLACK_UPLOAD_ERROR_BRAND);
+}
+function isRetryable(status, code) {
+	return status === 429 || status !== void 0 && status >= 500 || code === "fetch_failed" || code === "request_timeout" || code === "processing_timeout";
+}
+//#endregion
+//#region src/slack/fetch-slack-uploader.ts
+const SLACK_API_BASE_URL = "https://slack.com/api";
+const DEFAULT_POLL_INTERVAL_MS = 250;
+const DEFAULT_POLL_MAX_ATTEMPTS = 20;
+const DEFAULT_POLL_TIMEOUT_MS = 3e4;
+const DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+/**
+* Web-standard implementation of Slack's external file-upload flow.
+*
+* @see https://docs.slack.dev/messaging/working-with-files
+*/
 var FetchSlackUploader = class {
-  token;
-  fetcher;
-  channelId;
-  pollIntervalMs;
-  pollMaxAttempts;
-  pollTimeoutMs;
-  sleep;
-  clock;
-  constructor(options) {
-    this.token = options.token;
-    this.fetcher = options.fetch ?? defaultFetch;
-    this.channelId = options.channelId;
-    this.pollIntervalMs = options.poll?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-    this.pollMaxAttempts = options.poll?.maxAttempts ?? DEFAULT_POLL_MAX_ATTEMPTS;
-    this.pollTimeoutMs = options.poll?.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
-    this.sleep = options.poll?.sleep ?? defaultSleep;
-    this.clock = options.poll?.clock ?? defaultClock;
-    validateOptions({
-      token: this.token,
-      pollIntervalMs: this.pollIntervalMs,
-      pollMaxAttempts: this.pollMaxAttempts,
-      pollTimeoutMs: this.pollTimeoutMs
-    });
-  }
-  async upload(img) {
-    const target = await this.getUploadTarget(img);
-    await this.uploadBytes(target, img);
-    await this.completeUpload(target.fileId, img.filename);
-    await this.waitUntilProcessed(target.fileId);
-    return { fileId: target.fileId };
-  }
-  async getUploadTarget(img) {
-    const payload = await this.callSlackApi(
-      "files.getUploadURLExternal",
-      encodeForm([
-        ["filename", img.filename],
-        ["length", String(img.data.byteLength)]
-      ]),
-      SlackUploadStage.GetUploadUrl
-    );
-    const uploadUrl = payload["upload_url"];
-    const fileId = payload["file_id"];
-    if (!isNonEmptyString(uploadUrl) || !isNonEmptyString(fileId)) {
-      throw new SlackUploadError("files.getUploadURLExternal returned no upload_url or file_id", {
-        stage: SlackUploadStage.GetUploadUrl,
-        code: "invalid_response"
-      });
-    }
-    return { uploadUrl, fileId };
-  }
-  async uploadBytes(target, img) {
-    let response;
-    try {
-      response = await this.fetcher(target.uploadUrl, {
-        method: "POST",
-        headers: { "content-type": img.mimeType },
-        body: img.data
-      });
-    } catch (cause) {
-      throw new SlackUploadError("Uploading bytes to Slack failed", {
-        stage: SlackUploadStage.UploadBytes,
-        code: "fetch_failed",
-        cause
-      });
-    }
-    if (!response.ok) {
-      throw new SlackUploadError(`Slack upload URL returned HTTP ${String(response.status)}`, {
-        stage: SlackUploadStage.UploadBytes,
-        status: response.status,
-        code: `http_${String(response.status)}`
-      });
-    }
-  }
-  async completeUpload(fileId, filename) {
-    const fields = [
-      [
-        "files",
-        JSON.stringify([
-          {
-            id: fileId,
-            title: filename
-          }
-        ])
-      ]
-    ];
-    if (this.channelId !== void 0) {
-      fields.push(["channel_id", this.channelId]);
-    }
-    await this.callSlackApi(
-      "files.completeUploadExternal",
-      encodeForm(fields),
-      SlackUploadStage.CompleteUpload
-    );
-  }
-  async waitUntilProcessed(fileId) {
-    const startedAt = this.clock();
-    for (let attempt = 1; attempt <= this.pollMaxAttempts; attempt += 1) {
-      const payload = await this.callSlackApi(
-        "files.info",
-        encodeForm([["file", fileId]]),
-        SlackUploadStage.FileInfo
-      );
-      if (isProcessedImageFile(payload["file"])) {
-        return;
-      }
-      if (attempt === this.pollMaxAttempts || this.clock() - startedAt >= this.pollTimeoutMs) {
-        throw processingTimeout(fileId, attempt);
-      }
-      try {
-        await this.sleep(this.pollIntervalMs);
-      } catch (cause) {
-        throw new SlackUploadError("Slack file-processing poll sleep failed", {
-          stage: SlackUploadStage.ProcessingTimeout,
-          code: "sleep_failed",
-          cause
-        });
-      }
-      if (this.clock() - startedAt >= this.pollTimeoutMs) {
-        throw processingTimeout(fileId, attempt);
-      }
-    }
-  }
-  async callSlackApi(method, body, stage) {
-    let response;
-    try {
-      response = await this.fetcher(`${SLACK_API_BASE_URL}/${method}`, {
-        method: "POST",
-        headers: {
-          authorization: `Bearer ${this.token}`,
-          "content-type": "application/x-www-form-urlencoded;charset=UTF-8"
-        },
-        body
-      });
-    } catch (cause) {
-      throw new SlackUploadError(`${method} request failed`, {
-        stage,
-        code: "fetch_failed",
-        cause
-      });
-    }
-    let payload;
-    try {
-      payload = await response.json();
-    } catch (cause) {
-      throw new SlackUploadError(`${method} returned invalid JSON`, {
-        stage,
-        status: response.status,
-        code: "invalid_json",
-        cause
-      });
-    }
-    const slackCode = getSlackErrorCode(payload);
-    if (!response.ok || !isRecord(payload) || payload["ok"] !== true) {
-      throw new SlackUploadError(`${method} was rejected by Slack`, {
-        stage,
-        status: response.status,
-        code: slackCode ?? (response.ok ? "invalid_response" : `http_${String(response.status)}`)
-      });
-    }
-    return payload;
-  }
+	token;
+	fetcher;
+	channelId;
+	requestTimeoutMs;
+	waitForProcessing;
+	pollIntervalMs;
+	pollMaxAttempts;
+	pollTimeoutMs;
+	sleep;
+	clock;
+	constructor(options) {
+		const resolved = resolveUploaderOptions(options);
+		this.token = resolved.token;
+		this.fetcher = resolved.fetcher;
+		this.channelId = resolved.channelId;
+		this.requestTimeoutMs = resolved.requestTimeoutMs;
+		this.waitForProcessing = resolved.waitForProcessing;
+		this.pollIntervalMs = resolved.pollIntervalMs;
+		this.pollMaxAttempts = resolved.pollMaxAttempts;
+		this.pollTimeoutMs = resolved.pollTimeoutMs;
+		this.sleep = resolved.sleep;
+		this.clock = resolved.clock;
+	}
+	async upload(img, context) {
+		let receipt = slackReceipt({
+			phase: UploadPhase.Requested,
+			processing: UploadProcessing.NotRequested,
+			retrySafety: RetrySafety.Safe
+		});
+		try {
+			const target = await this.getUploadTarget(img, context);
+			receipt = slackReceipt({
+				phase: UploadPhase.Allocated,
+				fileId: target.fileId,
+				processing: UploadProcessing.NotRequested,
+				retrySafety: RetrySafety.MayDuplicate
+			});
+			await this.uploadBytes(target, img, context);
+			receipt = slackReceipt({
+				phase: UploadPhase.Uploaded,
+				fileId: target.fileId,
+				processing: UploadProcessing.NotRequested,
+				retrySafety: RetrySafety.MayDuplicate
+			});
+			await this.completeUpload(target.fileId, img.filename, context);
+			receipt = slackReceipt({
+				phase: this.channelId === void 0 ? UploadPhase.Completed : UploadPhase.Shared,
+				fileId: target.fileId,
+				shared: this.channelId !== void 0,
+				processing: this.waitForProcessing ? UploadProcessing.Pending : UploadProcessing.NotRequested,
+				retrySafety: RetrySafety.Never
+			});
+			if (this.waitForProcessing) try {
+				await this.waitUntilProcessed(target.fileId, receipt, context);
+				receipt = slackReceipt({
+					...receipt,
+					processing: UploadProcessing.Verified
+				});
+			} catch (error) {
+				if (isOperationError(error)) throw attachReceipts(error, [receipt]);
+				if (isSlackUploadError(error)) receipt = slackReceipt({
+					...receipt,
+					processing: UploadProcessing.Unverified,
+					status: error.status,
+					retryAfterMs: error.retryAfterMs,
+					providerCode: error.code
+				});
+				else receipt = slackReceipt({
+					...receipt,
+					processing: UploadProcessing.Unverified,
+					providerCode: "processing_failed"
+				});
+			}
+			return {
+				fileId: target.fileId,
+				receipt
+			};
+		} catch (error) {
+			if (isSlackUploadError(error)) throw withReceipt(error, receipt);
+			if (isOperationError(error)) throw attachReceipts(error, [receipt]);
+			throw error;
+		}
+	}
+	async getUploadTarget(img, control) {
+		const payload = await this.callSlackApi("files.getUploadURLExternal", encodeForm([["filename", img.filename], ["length", String(img.data.byteLength)]]), SlackUploadStage.GetUploadUrl, control);
+		const uploadUrl = payload["upload_url"];
+		const fileId = payload["file_id"];
+		if (!isNonEmptyString(uploadUrl) || !isNonEmptyString(fileId)) throw new SlackUploadError("files.getUploadURLExternal returned no upload_url or file_id", {
+			stage: SlackUploadStage.GetUploadUrl,
+			code: "invalid_response"
+		});
+		return {
+			uploadUrl,
+			fileId
+		};
+	}
+	async uploadBytes(target, img, control) {
+		const stageSignal = createStageSignal(control, this.requestTimeoutMs, this.clock);
+		let response;
+		try {
+			response = await this.fetcher(target.uploadUrl, {
+				method: "POST",
+				headers: { "content-type": img.mimeType },
+				body: img.data,
+				signal: stageSignal.signal
+			});
+		} catch (cause) {
+			const operationError = stageSignal.operationError(SlackUploadStage.UploadBytes, cause);
+			if (operationError !== void 0) throw operationError;
+			throw new SlackUploadError("Slack byte upload failed", {
+				stage: SlackUploadStage.UploadBytes,
+				code: stageSignal.code(),
+				cause
+			});
+		} finally {
+			stageSignal.cleanup();
+		}
+		if (!response.ok) throw new SlackUploadError("Slack byte upload was rejected", {
+			stage: SlackUploadStage.UploadBytes,
+			status: response.status,
+			code: `http_${String(response.status)}`,
+			retryAfterMs: retryAfterMs(response)
+		});
+	}
+	async completeUpload(fileId, filename, control) {
+		const fields = [["files", JSON.stringify([{
+			id: fileId,
+			title: filename
+		}])]];
+		if (this.channelId !== void 0) fields.push(["channel_id", this.channelId]);
+		await this.callSlackApi("files.completeUploadExternal", encodeForm(fields), SlackUploadStage.CompleteUpload, control);
+	}
+	async waitUntilProcessed(fileId, receipt, control) {
+		const startedAt = this.clock();
+		const pollDeadlineMs = startedAt + this.pollTimeoutMs;
+		const pollOwnsDeadline = control.deadlineMs === void 0 || pollDeadlineMs < control.deadlineMs;
+		const pollContext = {
+			signal: control.signal,
+			deadlineMs: Math.min(control.deadlineMs ?? Number.POSITIVE_INFINITY, pollDeadlineMs)
+		};
+		for (let attempt = 1; attempt <= this.pollMaxAttempts; attempt += 1) {
+			if (this.clock() >= pollDeadlineMs) throw processingTimeout(receipt, attempt - 1);
+			let payload;
+			try {
+				payload = await this.callSlackApi("files.info", encodeForm([["file", fileId]]), SlackUploadStage.FileInfo, pollContext);
+			} catch (error) {
+				if (pollOwnsDeadline && isOperationDeadline(error)) throw processingTimeout(receipt, attempt);
+				throw error;
+			}
+			if (isProcessedImageFile(payload["file"])) return;
+			if (attempt === this.pollMaxAttempts || this.clock() - startedAt >= this.pollTimeoutMs) throw processingTimeout(receipt, attempt);
+			try {
+				await controlledSleep(this.sleep, Math.min(this.pollIntervalMs, Math.max(0, pollDeadlineMs - this.clock())), pollContext, this.clock);
+			} catch (error) {
+				if (pollOwnsDeadline && isOperationDeadline(error)) throw processingTimeout(receipt, attempt);
+				throw error;
+			}
+			if (this.clock() - startedAt >= this.pollTimeoutMs) throw processingTimeout(receipt, attempt);
+		}
+	}
+	async callSlackApi(method, body, stage, control) {
+		const stageSignal = createStageSignal(control, this.requestTimeoutMs, this.clock);
+		let response;
+		try {
+			response = await this.fetcher(`${SLACK_API_BASE_URL}/${method}`, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${this.token}`,
+					"content-type": "application/x-www-form-urlencoded;charset=UTF-8"
+				},
+				body,
+				signal: stageSignal.signal
+			});
+		} catch (cause) {
+			const operationError = stageSignal.operationError(stage, cause);
+			stageSignal.cleanup();
+			if (operationError !== void 0) throw operationError;
+			throw new SlackUploadError("Slack API request failed", {
+				stage,
+				code: stageSignal.code(),
+				cause
+			});
+		}
+		let payload;
+		try {
+			payload = await raceWithSignal(response.json(), stageSignal.signal);
+		} catch (cause) {
+			const operationError = stageSignal.operationError(stage, cause);
+			const signalCode = stageSignal.code();
+			if (operationError !== void 0) throw operationError;
+			throw new SlackUploadError("Slack API returned invalid JSON", {
+				stage,
+				status: response.status,
+				code: signalCode === "fetch_failed" ? "invalid_json" : signalCode,
+				cause
+			});
+		} finally {
+			stageSignal.cleanup();
+		}
+		const slackCode = getSlackErrorCode(payload);
+		if (!response.ok || !isRecord(payload) || payload["ok"] !== true) throw new SlackUploadError("Slack API rejected the request", {
+			stage,
+			status: response.status,
+			code: slackCode ?? (response.ok ? "invalid_response" : `http_${String(response.status)}`),
+			retryAfterMs: retryAfterMs(response)
+		});
+		return payload;
+	}
 };
-function validateOptions(uploader) {
-  if (uploader.token.length === 0) {
-    throw new TypeError("token must not be empty");
-  }
-  if (!Number.isInteger(uploader.pollIntervalMs) || uploader.pollIntervalMs < 0) {
-    throw new RangeError("poll.intervalMs must be a non-negative integer");
-  }
-  if (!Number.isInteger(uploader.pollMaxAttempts) || uploader.pollMaxAttempts <= 0) {
-    throw new RangeError("poll.maxAttempts must be a positive integer");
-  }
-  if (!Number.isFinite(uploader.pollTimeoutMs) || uploader.pollTimeoutMs <= 0) {
-    throw new RangeError("poll.timeoutMs must be positive");
-  }
+function resolveUploaderOptions(options) {
+	assertKnownPlainObject(options, [
+		"token",
+		"fetch",
+		"channelId",
+		"requestTimeoutMs",
+		"waitForProcessing",
+		"poll"
+	], "FetchSlackUploader options");
+	let token;
+	let fetcher;
+	let channelId;
+	let requestTimeoutMs;
+	let waitForProcessing;
+	let poll;
+	try {
+		token = Reflect.get(options, "token");
+		fetcher = Reflect.get(options, "fetch");
+		channelId = Reflect.get(options, "channelId");
+		requestTimeoutMs = Reflect.get(options, "requestTimeoutMs");
+		waitForProcessing = Reflect.get(options, "waitForProcessing");
+		poll = Reflect.get(options, "poll");
+	} catch (cause) {
+		throw invalidUploaderOptions("Uploader options could not be read", cause);
+	}
+	if (typeof token !== "string" || token.length === 0 || token !== token.trim()) throw invalidUploaderOptions("token must be a nonempty trimmed string");
+	if (channelId !== void 0 && (typeof channelId !== "string" || channelId.length === 0 || channelId !== channelId.trim())) throw invalidUploaderOptions("channelId must be a nonempty trimmed string");
+	if (fetcher !== void 0 && typeof fetcher !== "function") throw invalidUploaderOptions("fetch must be a function");
+	if (requestTimeoutMs !== void 0 && (typeof requestTimeoutMs !== "number" || !Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0)) throw invalidUploaderOptions("requestTimeoutMs must be positive");
+	if (waitForProcessing !== void 0 && typeof waitForProcessing !== "boolean") throw invalidUploaderOptions("waitForProcessing must be boolean");
+	const resolvedPoll = resolvePollOptions(poll);
+	return {
+		token,
+		fetcher: fetcher ?? defaultFetch,
+		channelId,
+		requestTimeoutMs: requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+		waitForProcessing: waitForProcessing ?? false,
+		pollIntervalMs: resolvedPoll.intervalMs,
+		pollMaxAttempts: resolvedPoll.maxAttempts,
+		pollTimeoutMs: resolvedPoll.timeoutMs,
+		sleep: resolvedPoll.sleep,
+		clock: resolvedPoll.clock
+	};
+}
+function resolvePollOptions(poll) {
+	if (poll === void 0) return {
+		intervalMs: DEFAULT_POLL_INTERVAL_MS,
+		maxAttempts: DEFAULT_POLL_MAX_ATTEMPTS,
+		timeoutMs: DEFAULT_POLL_TIMEOUT_MS,
+		sleep: defaultSleep,
+		clock: defaultClock
+	};
+	assertKnownPlainObject(poll, [
+		"intervalMs",
+		"maxAttempts",
+		"timeoutMs",
+		"sleep",
+		"clock"
+	], "poll options");
+	let intervalMs;
+	let maxAttempts;
+	let timeoutMs;
+	let sleep;
+	let clock;
+	try {
+		intervalMs = Reflect.get(poll, "intervalMs");
+		maxAttempts = Reflect.get(poll, "maxAttempts");
+		timeoutMs = Reflect.get(poll, "timeoutMs");
+		sleep = Reflect.get(poll, "sleep");
+		clock = Reflect.get(poll, "clock");
+	} catch (cause) {
+		throw invalidUploaderOptions("poll options could not be read", cause);
+	}
+	const resolvedInterval = intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const resolvedAttempts = maxAttempts ?? DEFAULT_POLL_MAX_ATTEMPTS;
+	const resolvedTimeout = timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+	if (!Number.isInteger(resolvedInterval) || resolvedInterval < 0) throw invalidUploaderOptions("poll.intervalMs must be a non-negative integer");
+	if (!Number.isInteger(resolvedAttempts) || resolvedAttempts <= 0) throw invalidUploaderOptions("poll.maxAttempts must be a positive integer");
+	if (!Number.isFinite(resolvedTimeout) || resolvedTimeout <= 0) throw invalidUploaderOptions("poll.timeoutMs must be positive");
+	if (sleep !== void 0 && typeof sleep !== "function") throw invalidUploaderOptions("poll.sleep must be a function");
+	if (clock !== void 0 && typeof clock !== "function") throw invalidUploaderOptions("poll.clock must be a function");
+	return {
+		intervalMs: resolvedInterval,
+		maxAttempts: resolvedAttempts,
+		timeoutMs: resolvedTimeout,
+		sleep: sleep ?? defaultSleep,
+		clock: clock ?? defaultClock
+	};
+}
+function assertKnownPlainObject(value, allowed, label) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalidUploaderOptions(`${label} must be a plain object`);
+	let prototype;
+	let keys;
+	try {
+		prototype = Object.getPrototypeOf(value);
+		keys = Object.keys(value);
+	} catch (cause) {
+		throw invalidUploaderOptions(`${label} could not be inspected`, cause);
+	}
+	if (prototype !== Object.prototype && prototype !== null) throw invalidUploaderOptions(`${label} must be a plain object`);
+	const allowedKeys = new Set(allowed);
+	for (const key of keys) if (!allowedKeys.has(key)) throw invalidUploaderOptions(`Unknown ${label} key: ${key}`);
+}
+function invalidUploaderOptions(message, cause) {
+	return new ConfigurationError(message, {
+		code: "invalid_slack_uploader_options",
+		stage: "configuration",
+		cause
+	});
 }
 function encodeForm(fields) {
-  return fields.map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`).join("&");
+	return fields.map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`).join("&");
 }
 function isRecord(value) {
-  return typeof value === "object" && value !== null;
+	return typeof value === "object" && value !== null;
 }
 function isNonEmptyString(value) {
-  return typeof value === "string" && value.length > 0;
+	return typeof value === "string" && value.length > 0;
 }
 function isPositiveNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) && value > 0;
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
 }
 function isProcessedImageFile(value) {
-  if (!isRecord(value)) {
-    return false;
-  }
-  return isNonEmptyString(value["mimetype"]) && isNonEmptyString(value["filetype"]) && isPositiveNumber(value["original_w"]) && isPositiveNumber(value["original_h"]);
+	if (!isRecord(value)) return false;
+	return isNonEmptyString(value["mimetype"]) && isNonEmptyString(value["filetype"]) && isPositiveNumber(value["original_w"]) && isPositiveNumber(value["original_h"]);
 }
 function getSlackErrorCode(payload) {
-  if (!isRecord(payload)) {
-    return void 0;
-  }
-  const error = payload["error"];
-  return typeof error === "string" ? error : void 0;
-}
-function processingTimeout(fileId, attempts) {
-  return new SlackUploadError(
-    `Slack file ${fileId} was not processed after ${String(attempts)} polls`,
-    {
-      stage: SlackUploadStage.ProcessingTimeout,
-      code: "processing_timeout"
-    }
-  );
+	if (!isRecord(payload)) return;
+	const error = payload["error"];
+	return typeof error === "string" ? error : void 0;
+}
+function processingTimeout(receipt, attempts) {
+	return new SlackUploadError(`Slack file processing did not complete after ${String(attempts)} polls`, {
+		stage: SlackUploadStage.ProcessingTimeout,
+		code: "processing_timeout",
+		receipt: slackReceipt({
+			...receipt,
+			processing: UploadProcessing.Unverified,
+			providerCode: "processing_timeout"
+		})
+	});
+}
+/**
+* Subclass identity is as bundle-sensitive as the base class, so discriminate on `code`.
+*/
+function isOperationDeadline(error) {
+	return isOperationError(error) && error.code === OperationErrorCode.DeadlineExceeded;
+}
+function createStageSignal(control, requestTimeoutMs, clock) {
+	const controller = new AbortController();
+	let timeoutKind;
+	const abortFromCaller = () => {
+		controller.abort(control.signal?.reason);
+	};
+	if (control.signal?.aborted === true) abortFromCaller();
+	else control.signal?.addEventListener("abort", abortFromCaller, { once: true });
+	const requestDeadlineMs = clock() + requestTimeoutMs;
+	const operationDeadlineMs = control.deadlineMs ?? Number.POSITIVE_INFINITY;
+	const remaining = Math.max(0, Math.min(requestDeadlineMs, operationDeadlineMs) - clock());
+	const timeout = setTimeout(() => {
+		timeoutKind = operationDeadlineMs <= requestDeadlineMs ? "operation" : "request";
+		controller.abort(/* @__PURE__ */ new Error("Slack request deadline exceeded"));
+	}, remaining);
+	return {
+		signal: controller.signal,
+		cleanup: () => {
+			clearTimeout(timeout);
+			control.signal?.removeEventListener("abort", abortFromCaller);
+		},
+		code: () => {
+			if (timeoutKind !== void 0) return "request_timeout";
+			return control.signal?.aborted === true ? "aborted" : "fetch_failed";
+		},
+		operationError: (stage, cause) => {
+			if (control.signal?.aborted === true) return new OperationAbortedError(stage, { cause });
+			if (timeoutKind === "operation") return new OperationDeadlineExceededError(stage, { cause });
+		}
+	};
+}
+function controlledSleep(sleep, milliseconds, control, clock) {
+	if (control.signal?.aborted === true) return Promise.reject(new OperationAbortedError(SlackUploadStage.ProcessingTimeout, { cause: control.signal.reason }));
+	if (control.deadlineMs !== void 0 && clock() >= control.deadlineMs) return Promise.reject(new OperationDeadlineExceededError(SlackUploadStage.ProcessingTimeout));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			cleanup();
+			reject(new OperationAbortedError(SlackUploadStage.ProcessingTimeout, { cause: control.signal?.reason }));
+		};
+		const onDeadline = () => {
+			cleanup();
+			reject(new OperationDeadlineExceededError(SlackUploadStage.ProcessingTimeout));
+		};
+		const deadlineTimer = control.deadlineMs === void 0 ? void 0 : setTimeout(onDeadline, Math.max(0, control.deadlineMs - clock()));
+		const cleanup = () => {
+			if (deadlineTimer !== void 0) clearTimeout(deadlineTimer);
+			control.signal?.removeEventListener("abort", onAbort);
+		};
+		control.signal?.addEventListener("abort", onAbort, { once: true });
+		sleep(milliseconds).then(() => {
+			cleanup();
+			resolve();
+		}, (error) => {
+			cleanup();
+			reject(error);
+		});
+	});
+}
+function raceWithSignal(promise, signal) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			signal.removeEventListener("abort", onAbort);
+			reject(signal.reason);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+function slackReceipt(options) {
+	return Object.freeze({
+		kind: "upload",
+		provider: "slack",
+		phase: options.phase,
+		fileId: options.fileId,
+		shared: options.shared ?? false,
+		processing: options.processing,
+		status: options.status,
+		retryAfterMs: options.retryAfterMs,
+		providerCode: options.providerCode,
+		retrySafety: options.retrySafety ?? RetrySafety.Never
+	});
+}
+function withReceipt(error, receipt) {
+	return new SlackUploadError(error.message, {
+		stage: error.stage,
+		status: error.status,
+		code: error.code,
+		retryable: error.retryable,
+		retryAfterMs: error.retryAfterMs,
+		receipt: slackReceipt({
+			...receipt,
+			status: error.status,
+			retryAfterMs: error.retryAfterMs,
+			providerCode: error.code,
+			retrySafety: receipt.phase === UploadPhase.Requested ? RetrySafety.Safe : receipt.phase === UploadPhase.Completed || receipt.phase === UploadPhase.Shared ? RetrySafety.Never : RetrySafety.MayDuplicate
+		}),
+		cause: error.cause
+	});
+}
+function retryAfterMs(response) {
+	const raw = response.headers?.get("retry-after");
+	if (raw === void 0 || raw === null) return;
+	const seconds = Number(raw);
+	return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1e3 : void 0;
 }
 function defaultFetch(input, init) {
-  return globalThis.fetch(input, init);
+	return globalThis.fetch(input, init);
 }
 function defaultSleep(milliseconds) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, milliseconds);
-  });
+	return new Promise((resolve) => {
+		setTimeout(resolve, milliseconds);
+	});
 }
 function defaultClock() {
-  return Date.now();
+	return Date.now();
 }
-export {
-  FetchSlackUploader,
-  SlackUploadError,
-  SlackUploadStage
-};
+//#endregion
+export { FetchSlackUploader, SlackUploadError, SlackUploadStage, isConfigurationError, isOperationError, isSlackUploadError };
+
 //# sourceMappingURL=slack.js.map