@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/message-cleanup.d.ts

@@ -0,0 +1,227 @@
+import type { OperationOptions } from "./client.js";
+import type { MessageOperationError } from "./message-errors.js";
+import { type ApiErrorDetail } from "./api-errors.js";
+import { FluxerlyError } from "./errors.js";
+import { type InputValidationDetail } from "./input-validation.js";
+import type { Message, MessageCore, MessageOperationOptions } from "./messages.js";
+/** Choose messages for previewCleanup without deleting them.
+ * Set explicit scan and selection limits, and supply authorId, filter, or both.
+ * With both supplied, a message must match the author before the filter runs.
+ * Messages are inspected newest first, using this client's messageFields selection.
+ * The SDK keeps the preview and deletion plan only in memory, not on disk
+ *
+ * @category Messages
+ */
+export interface MessageCleanupSelection<M extends MessageCore = Message> {
+    /** Select only messages authored by this account ID, as a decimal string */
+    readonly authorId?: string;
+    /** Return true to select a message, false to skip it. Runs synchronously, so do not block or return a Promise.
+     * A throw or non-boolean return fails preview with reason filter, before any deletion.
+     * Cancellation and timeouts cannot preempt blocking JavaScript. Mistaken asynchronous work is not awaited or cancelled
+     */
+    readonly filter?: (message: M) => boolean;
+    /** Maximum history messages to fetch and inspect, a required integer from 1 through 10,000 */
+    readonly maxScanned: number;
+    /** Maximum selected snapshots to keep in the plan, a required integer from 1 through 10,000 */
+    readonly maxSelected: number;
+}
+/** Why preview stopped: An empty history page, the scan cap, or the selected-message cap.
+ * The scanLimit and selectionLimit reasons do not mean that the channel's history was exhausted
+ *
+ * @category Messages
+ */
+export type MessageCleanupStopReason = "historyExhausted" | "scanLimit" | "selectionLimit";
+/** Frozen preview of the exact messages to inspect before requesting deletion.
+ * Pass the original object to cleanup on the client that produced it. Reconstructed JSON and plans from another client are rejected.
+ * Cleanup marks a valid plan as used before it sends any deletion request, even if it then fails before sending one.
+ * A consumed plan cannot be retried. Use a fresh preview or explicit deleteMany requests after application-owned reconciliation.
+ * The plan does not store a reference to its client or save requests to disk. The SDK cannot recover it after a crash
+ *
+ * @category Messages
+ */
+export interface MessageCleanupPlan<M extends MessageCore = Message> {
+    /** Channel inspected by preview and the only channel this plan can delete from */
+    readonly channelId: string;
+    /** Exact selected message snapshots, newest first. Changes after preview do not update this selection */
+    readonly selectedMessages: readonly M[];
+    /** Number of messages inspected, including messages rejected by the selection */
+    readonly scannedCount: number;
+    /** Condition that ended preview. Even historyExhausted describes an observed empty page, not a stable remote snapshot */
+    readonly stopReason: MessageCleanupStopReason;
+}
+/** Exact IDs in one cleanup bulk-delete request, containing at most 100 IDs.
+ * Batches run sequentially. A successful HTTP response means Fluxer accepted the request. It does not prove that every ID existed or was deleted
+ *
+ * @category Messages
+ */
+export interface MessageCleanupBatch {
+    /** Submission position, with 0 identifying the first batch */
+    readonly batchIndex: number;
+    /** Selected IDs assigned to this request, in preview order. Cleanup does not rescan history */
+    readonly messageIds: readonly string[];
+}
+/** Report returned after cleanup received successful responses for its selected batches.
+ * This reports submissions, not a verified number of deleted messages.
+ * Deletion is not atomic and the SDK does not roll back earlier batches.
+ * An empty selection produces a successful report without a delete request
+ *
+ * @category Messages
+ */
+export interface MessageCleanupReport {
+    /** Channel targeted by the preview plan */
+    readonly channelId: string;
+    /** Exact IDs copied from the plan, newest first */
+    readonly selectedMessageIds: readonly string[];
+    /** Number of history messages inspected during the earlier preview, not during deletion */
+    readonly scannedCount: number;
+    /** Batch requests that received successful HTTP responses, in submission order */
+    readonly submittedBatches: readonly MessageCleanupBatch[];
+}
+/** Progress notification for a cleanup batch, not durable evidence of individual deletions.
+ * The onProgress callback runs synchronously and cleanup continues after it fails.
+ * A throw, a rejected asynchronous return or a returned or resolved Err result reaches the client-level onError as a
+ * progress FailureReport, or is logged at Error. A returned Effect is not run and is reported the same way as misuse.
+ * An application that needs the notification for reconciliation should persist it synchronously.
+ * Cancellation or interruption can leave a submitting batch uncertain without a terminal failed notification
+ *
+ * @category Messages
+ */
+export type MessageCleanupProgress = {
+    /** The batch is about to be attempted, not proof that it was dispatched */
+    readonly state: "submitting";
+    /** Exact planned batch */
+    readonly batch: MessageCleanupBatch;
+} | {
+    /** Fluxer returned a successful HTTP response for this batch, without per-message deletion proof */
+    readonly state: "submitted";
+    /** Batch whose request succeeded */
+    readonly batch: MessageCleanupBatch;
+} | {
+    /** A batch request failed with one of the documented errors, rather than being interrupted */
+    readonly state: "failed";
+    /** Failed or uncertain batch */
+    readonly batch: MessageCleanupBatch;
+    /** Safe failure classification without message bodies or application callback errors */
+    readonly failure: MessageCleanupFailureMetadata;
+};
+/** Expected batch failure details included in a failed progress notification.
+ * Contains SDK-owned classifications, not message bodies, filter details or raw provider response text
+ *
+ * @category Errors
+ */
+export interface MessageCleanupFailureMetadata {
+    /** Classified cause of the failure, such as invalid input, closure, rejection or deadline expiry */
+    readonly reason: MessageCleanupErrorReason;
+    /** What is known about dispatch: Not sent, definitively rejected, or uncertain */
+    readonly outcome: MessageCleanupOutcome;
+    /** Known HTTP status, or null when none is available */
+    readonly status: number | null;
+    /** Retry delay reported by Fluxer in milliseconds, or null. This does not establish that retrying is safe */
+    readonly retryAfterMs: number | null;
+    /** Safe Fluxer rejection classification, or null, excluding raw response text and provider field paths */
+    readonly apiError: ApiErrorDetail | null;
+}
+/** Settings for cleanup's batch submissions.
+ * One timeoutMs deadline covers the entire cleanup execution, including rate-limit waits between batches.
+ * Preview has its own separate per-call deadline and does not accept onProgress
+ *
+ * @category Messages
+ */
+export interface MessageCleanupOptions extends MessageOperationOptions {
+    /** Observe submitting, submitted and failed batches synchronously.
+     * Return values are not awaited, and the callback does not schedule retries or recovery.
+     * A throw, a rejected asynchronous return or a returned or resolved Err result goes to the client-level onError as a
+     * progress FailureReport with the thrown, rejected or Err error, or is logged at Error, and cleanup continues.
+     * The callback runs synchronously in both entry points, so a returned Effect is not run. It is reported as a progress
+     * FailureReport with a TypeError instead of being ignored
+     */
+    readonly onProgress?: (progress: MessageCleanupProgress) => unknown;
+}
+/** Cleanup settings for the Promise and Result API, with AbortSignal cancellation.
+ * Cancellation returns CancelledError rather than a partial report. Earlier requests may already have been submitted.
+ * Use progress observations for application-owned reconciliation. The Effect entry point retains interruption in Cause
+ *
+ * @category Messages
+ */
+export interface DefaultMessageCleanupOptions extends MessageCleanupOptions, OperationOptions {
+}
+/** Expected preview or cleanup failure classification.
+ * The reason filter denotes a bad selection callback, closed denotes client closure, and input denotes invalid settings or plan ownership.
+ * Other values preserve the underlying message operation's failure reason
+ *
+ * @category Errors
+ */
+export type MessageCleanupErrorReason = "filter" | "closed" | "input" | MessageOperationError["reason"];
+/** What is known about the failed stage's request.
+ * The outcome notDispatched means no request was sent, rejected means confirmed rejection, and unknown means Fluxer may have acted.
+ * An unknown outcome does not mean it is safe to repeat the request
+ *
+ * @category Messages
+ */
+export type MessageCleanupOutcome = "notDispatched" | "rejected" | "unknown";
+/** A cleanup preview or deletion failed, with selected IDs and batch progress where available.
+ * Preview never deletes. Cleanup can fail after earlier batches received successful responses.
+ * The submittedBatches field describes only those earlier responses. The terminalBatchIds field identifies the failed or uncertain request when reached.
+ * Its message and details contain no message bodies or criteria, and it proves neither individual deletion nor safe replay.
+ * A filter that threw keeps its thrown value as cause, and a failed history read or batch request keeps its operation error as cause.
+ * Cancellation in the default API is returned separately as CancelledError. Native interruption and unexpected defects remain outside this error
+ *
+ * @category Errors
+ */
+export declare class MessageCleanupError extends FluxerlyError {
+    /** Literal error tag for identifying MessageCleanupError */
+    readonly _tag = "MessageCleanupError";
+    /** Which stage failed. The preview phase never deletes, while cleanup can fail after earlier batch submissions */
+    readonly phase: "preview" | "cleanup";
+    /** Expected failure classification. The failed message operation or thrown filter value is available through cause */
+    readonly reason: MessageCleanupErrorReason;
+    /** What is known about dispatch at the failed stage, not about the earlier successful batches */
+    readonly outcome: MessageCleanupOutcome;
+    /** HTTP status at the failed stage, or null when unavailable */
+    readonly status: number | null;
+    /** Fluxer's retry delay in milliseconds, or null. This delay does not establish that a repeat request is safe */
+    readonly retryAfterMs: number | null;
+    /** Messages inspected before preview failed, or the completed preview's scan count when cleanup failed */
+    readonly scannedCount: number;
+    /** Selected message IDs known at failure time, without message bodies or filter details */
+    readonly selectedMessageIds: readonly string[];
+    /** Earlier batch requests with successful HTTP responses, not confirmed individual deletions */
+    readonly submittedBatches: readonly MessageCleanupBatch[];
+    /** Failed or uncertain batch's IDs when a batch request was reached, otherwise null */
+    readonly terminalBatchIds: readonly string[] | null;
+    /** Safe local validation detail, copied and frozen, or null for other failures */
+    readonly inputValidation: InputValidationDetail | null;
+    /** Safe Fluxer rejection detail for the failed stage, or null when unavailable */
+    readonly apiError: ApiErrorDetail | null;
+    /** Record an expected preview or cleanup failure and the submission knowledge available at that point.
+     * Optional validation and Fluxer details default to null. Construction performs no requests, deletion or recovery
+     */
+    constructor(options: {
+        readonly phase: "preview" | "cleanup";
+        readonly reason: MessageCleanupErrorReason;
+        readonly outcome: MessageCleanupOutcome;
+        readonly status: number | null;
+        readonly retryAfterMs: number | null;
+        readonly scannedCount: number;
+        readonly selectedMessageIds: readonly string[];
+        readonly submittedBatches: readonly MessageCleanupBatch[];
+        readonly terminalBatchIds: readonly string[] | null;
+        readonly inputValidation?: InputValidationDetail | null | undefined;
+        readonly apiError?: ApiErrorDetail | null | undefined;
+        /**
+         * Fluxer error code that this SDK version does not recognize, recorded as details.providerCode and named in the
+         * message. Ignored when apiError is present or the code does not have the shape of a Fluxer code
+         */
+        readonly providerCode?: string | null | undefined;
+        /** Response field path or named check that failed, recorded as details.responseField for reason response */
+        readonly responseField?: string | null | undefined;
+        readonly cause?: unknown;
+    });
+}
+/** Expected preview and cleanup errors shared by both entry points.
+ * CancelledError in the default API and interruption in Effect are separate from this type
+ *
+ * @category Errors
+ */
+export type MessageCleanupFailure = MessageCleanupError;
+//# sourceMappingURL=message-cleanup.d.ts.map

package/dist/message-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-cleanup.d.ts","sourceRoot":"","sources":["../src/message-cleanup.ts"],"names":[],"mappings":"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"}

package/dist/message-cleanup.js

@@ -0,0 +1,101 @@
+import { operationErrorMessage, operationFailureHint, safeProviderCode, safeResponseField, } from "./api-errors.js";
+import { FluxerlyError, operationDetails } from "./errors.js";
+import { freezeInputValidationDetail } from "./input-validation.js";
+/** A cleanup preview or deletion failed, with selected IDs and batch progress where available.
+ * Preview never deletes. Cleanup can fail after earlier batches received successful responses.
+ * The submittedBatches field describes only those earlier responses. The terminalBatchIds field identifies the failed or uncertain request when reached.
+ * Its message and details contain no message bodies or criteria, and it proves neither individual deletion nor safe replay.
+ * A filter that threw keeps its thrown value as cause, and a failed history read or batch request keeps its operation error as cause.
+ * Cancellation in the default API is returned separately as CancelledError. Native interruption and unexpected defects remain outside this error
+ *
+ * @category Errors
+ */
+export class MessageCleanupError extends FluxerlyError {
+    /** Literal error tag for identifying MessageCleanupError */
+    _tag = "MessageCleanupError";
+    /** Which stage failed. The preview phase never deletes, while cleanup can fail after earlier batch submissions */
+    phase;
+    /** Expected failure classification. The failed message operation or thrown filter value is available through cause */
+    reason;
+    /** What is known about dispatch at the failed stage, not about the earlier successful batches */
+    outcome;
+    /** HTTP status at the failed stage, or null when unavailable */
+    status;
+    /** Fluxer's retry delay in milliseconds, or null. This delay does not establish that a repeat request is safe */
+    retryAfterMs;
+    /** Messages inspected before preview failed, or the completed preview's scan count when cleanup failed */
+    scannedCount;
+    /** Selected message IDs known at failure time, without message bodies or filter details */
+    selectedMessageIds;
+    /** Earlier batch requests with successful HTTP responses, not confirmed individual deletions */
+    submittedBatches;
+    /** Failed or uncertain batch's IDs when a batch request was reached, otherwise null */
+    terminalBatchIds;
+    /** Safe local validation detail, copied and frozen, or null for other failures */
+    inputValidation;
+    /** Safe Fluxer rejection detail for the failed stage, or null when unavailable */
+    apiError;
+    /** Record an expected preview or cleanup failure and the submission knowledge available at that point.
+     * Optional validation and Fluxer details default to null. Construction performs no requests, deletion or recovery
+     */
+    constructor(options) {
+        const phase = options.phase;
+        const reason = options.reason;
+        const outcome = options.outcome;
+        const status = options.status;
+        const retryAfterMs = options.retryAfterMs;
+        const scannedCount = options.scannedCount;
+        const selectedMessageIds = options.selectedMessageIds;
+        const submittedBatches = options.submittedBatches;
+        const terminalBatchIds = options.terminalBatchIds;
+        const inputValidation = options.inputValidation ?? null;
+        const apiError = options.apiError ?? null;
+        const providerCode = safeProviderCode(apiError, options.providerCode ?? null);
+        const responseField = safeResponseField(options.responseField ?? null);
+        super(operationErrorMessage({
+            subject: "Message cleanup",
+            operation: phase,
+            reason,
+            outcome,
+            status,
+            apiError,
+            inputExplanation: inputValidation?.explanation ?? null,
+            retryAfterMs,
+            facts: { providerCode, responseField },
+        }), {
+            code: `cleanup.${reason}`,
+            hint: operationFailureHint({
+                reason,
+                outcome,
+                status,
+                retryAfterMs,
+                apiError,
+                inputPath: inputValidation?.path ?? null,
+            }),
+            cause: options.cause,
+            details: operationDetails({
+                phase,
+                reason,
+                outcome,
+                status,
+                retryAfterMs,
+                scannedCount,
+                providerCode,
+                responseField,
+            }),
+        });
+        this.phase = phase;
+        this.reason = reason;
+        this.outcome = outcome;
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+        this.scannedCount = scannedCount;
+        this.selectedMessageIds = selectedMessageIds;
+        this.submittedBatches = submittedBatches;
+        this.terminalBatchIds = terminalBatchIds;
+        this.apiError = apiError;
+        this.name = this._tag;
+        this.inputValidation = freezeInputValidationDetail(inputValidation);
+    }
+}
+//# sourceMappingURL=message-cleanup.js.map

package/dist/message-cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-cleanup.js","sourceRoot":"","sources":["../src/message-cleanup.ts"],"names":[],"mappings":"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"}

package/dist/message-errors.d.ts

@@ -0,0 +1,172 @@
+import type { ClientClosedError, ConfigurationError } from "./errors.js";
+import { type ApiErrorDetail } from "./api-errors.js";
+import { FluxerlyError, type OperationErrorOptions, type OperationOutcome, type OperationReason } from "./errors.js";
+import { type InputValidationDetail } from "./input-validation.js";
+/** An event subscription stopped because unread events exceeded its count or byte limit.
+ * The subscription does not restart or replay missed events
+ *
+ * @category Errors
+ */
+export declare class EventOverflowError extends FluxerlyError {
+    /** Budget exceeded by the incoming event */
+    readonly limit: "messages" | "bytes";
+    /** Configured event-payload count when limit is messages, or source-JSON bytes when limit is bytes.
+     * A bulk deletion or reaction batch counts as one payload
+     */
+    readonly capacity: number;
+    /** Discriminator for identifying queue overflow in an expected failure result */
+    readonly _tag = "EventOverflowError";
+    constructor(
+    /** Budget exceeded by the incoming event */
+    limit: "messages" | "bytes", 
+    /** Configured event-payload count when limit is messages, or source-JSON bytes when limit is bytes.
+     * A bulk deletion or reaction batch counts as one payload
+     */
+    capacity: number);
+}
+/** A second next call tried to read while the same default API pull subscription already had a pending read.
+ * Await that read before requesting another event
+ *
+ * @category Errors
+ */
+export declare class EventReadBusyError extends FluxerlyError {
+    /** Discriminator for identifying an overlapping pending read */
+    readonly _tag = "EventReadBusyError";
+    constructor();
+}
+/** A filtered event wait ended without a match or could not use its synchronous filter.
+ * A filter throw keeps the thrown value as cause. A non-boolean return is not retained
+ *
+ * @category Errors
+ */
+export declare class EventWaitError extends FluxerlyError {
+    /** The reason timeout means no matching event was observed before the local deadline.
+     * The reason filter means the callback threw or failed to return a boolean synchronously, and a thrown value is the error's cause
+     */
+    readonly reason: "timeout" | "filter";
+    /** Stable discriminator for a local timeout or synchronous filter failure */
+    readonly _tag = "EventWaitError";
+    constructor(
+    /** The reason timeout means no matching event was observed before the local deadline.
+     * The reason filter means the callback threw or failed to return a boolean synchronously, and a thrown value is the error's cause
+     */
+    reason: "timeout" | "filter", 
+    /** Optional underlying failure, such as the value thrown by the filter */
+    options?: {
+        readonly cause?: unknown;
+    });
+}
+/** A send, reply or forward ended without confirming that Fluxer created the message.
+ * Inspect outcome before retrying, since unknown means message creation may already have occurred.
+ * Even notDispatched or rejected can follow preparatory file uploads and does not prove rollback.
+ * Metadata contains no Fluxer response body or message content.
+ * A missing-permission rejection lists the permissions that sending needs in details.requiredPermissions, as
+ * ApiErrorDetail describes
+ *
+ * @category Errors
+ */
+export declare class MessageError extends FluxerlyError {
+    /** Discriminator for identifying expected message-creation failures */
+    readonly _tag = "MessageError";
+    /** Failure category, described by {@link OperationReason}.
+     * Busy also covers full local upload capacity, and a send never reports notFound
+     */
+    readonly reason: Exclude<OperationReason, "notFound">;
+    /** Whether the message may have been created, using the same vocabulary as other operation errors.
+     * The outcome notDispatched means no message creation request was sent, and rejected means Fluxer answered with a
+     * rejection. Neither is proof of rollback, and preparatory file uploads may already have occurred.
+     * The outcome unknown means the message may already have been created, so another send can duplicate it
+     */
+    readonly outcome: OperationOutcome;
+    /** HTTP status when received, or null for local failures and missing responses */
+    readonly status: number | null;
+    /** Server-required wait in milliseconds when usable, otherwise null */
+    readonly retryAfterMs: number | null;
+    /** Reviewed Fluxer rejection detail, or null when no safe classification is available */
+    readonly apiError: ApiErrorDetail | null;
+    /** Safe local validation facts when the SDK can identify a failed input rule, otherwise null */
+    readonly inputValidation: InputValidationDetail | null;
+    /** Create a send failure from its reason and outcome, with optional status, retry wait, API detail, input detail and cause */
+    constructor(options: {
+        readonly reason: Exclude<OperationReason, "notFound">;
+        readonly outcome: OperationOutcome;
+        readonly status?: number | null | undefined;
+        readonly retryAfterMs?: number | null | undefined;
+        readonly apiError?: ApiErrorDetail | null | undefined;
+        readonly inputValidation?: InputValidationDetail | null | undefined;
+        /** Unrecognized Fluxer error code, as in OperationErrorOptions */
+        readonly providerCode?: string | null | undefined;
+        /** Failed response field or check, as in OperationErrorOptions */
+        readonly responseField?: string | null | undefined;
+        readonly cause?: unknown;
+    });
+}
+/**
+ * A message lookup, read or change failed.
+ * Read operation to identify the call and reason to distinguish invalid input, full local capacity and Fluxer failures.
+ * A local get cache miss is successful undefined, not this error.
+ * Reads do not change messages, but a mutation with outcome unknown may already have taken effect.
+ * Error details contain no response body, credential or message content.
+ * A missing-permission rejection lists the permissions that the operation needs in details.requiredPermissions when
+ * the SDK knows them, as ApiErrorDetail describes.
+ * Cancellation in the default API and client closure have separate error tags and can also occur after mutation dispatch
+ *
+ * @category Errors
+ */
+export declare class MessageOperationError extends FluxerlyError {
+    /** Stable discriminator for expected message-management failures */
+    readonly _tag = "MessageOperationError";
+    /** The requested operation, independent of the gateway connection state */
+    readonly operation: "messages.get" | "typing" | "fetch" | "publish" | "fetchCrosspostSource" | "fetchHistory" | "search" | "fetchReactionUsers" | "pin" | "unpin" | "fetchPins" | "edit" | "delete" | "deleteAttachment" | "deleteMany" | "deleteOwnMessages" | "addReaction" | "removeReaction" | "removeUserReaction" | "clearReaction" | "clearReactions";
+    /** Failure category, described by {@link OperationReason}.
+     * Busy also covers full local upload capacity, and notFound applies to the target or its containing resource
+     */
+    readonly reason: OperationReason;
+    /** Whether the request may have reached Fluxer, described by {@link OperationOutcome}.
+     * Preparatory file uploads may already have occurred even when no message or reaction request was dispatched.
+     * An unknown outcome includes server errors and missing or invalid success responses.
+     * Read calls do not mutate messages even when their request outcome is unknown
+     */
+    readonly outcome: OperationOutcome;
+    /** HTTP status when available to this failure, otherwise null */
+    readonly status: number | null;
+    /** Server-required wait in milliseconds when usable, otherwise null */
+    readonly retryAfterMs: number | null;
+    /** Reviewed Fluxer rejection detail, or null when no safe classification is available */
+    readonly apiError: ApiErrorDetail | null;
+    /** Safe explanation of the locally invalid property, or null when no input problem could be identified */
+    readonly inputValidation: InputValidationDetail | null;
+    /** Create the failure from its operation, reason and outcome, with optional status, retry wait, API detail, input detail and cause */
+    constructor(options: OperationErrorOptions<MessageOperationError["operation"]>);
+}
+/**
+ * Expected subscription-registration failures from invalid options or permanent client closure
+ *
+ * @category Errors
+ */
+export type RegistrationError = ConfigurationError | ClientClosedError;
+/** Expected subscription-read failures from queue overflow or a competing pending read.
+ * Default API calls add CancelledError, while native interruption remains in the Effect cause
+ *
+ * @category Errors
+ */
+export type EventReadError = EventOverflowError | EventReadBusyError;
+/** Expected filtered event-wait failures, including invalid options, client closure, queue overflow, deadline expiry or a failed filter.
+ * Default API calls add CancelledError, while native interruption remains in the Effect cause
+ *
+ * @category Errors
+ */
+export type EventWaitFailure = ConfigurationError | ClientClosedError | EventOverflowError | EventWaitError;
+/** Expected message-creation failures shared by both entry points, including permanent client closure.
+ * Default API calls add CancelledError, while native interruption remains in the Effect cause
+ *
+ * @category Errors
+ */
+export type SendError = MessageError | ClientClosedError;
+/**
+ * Message lookup, management and reaction failures shared by both entry points. Native interruption remains outside this union
+ *
+ * @category Errors
+ */
+export type MessageOperationFailure = MessageOperationError | ClientClosedError;
+//# sourceMappingURL=message-errors.d.ts.map

package/dist/message-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-errors.d.ts","sourceRoot":"","sources":["../src/message-errors.ts"],"names":[],"mappings":"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"}